fix: stabilize geyser plugin startup

[thlorenz]

Summary

Split the geyser plugin startup config into a validator-facing JSON wrapper and a plugin runtime TOML config so solana-test-validator can keep loading the plugin through its expected JSON entrypoint while the plugin itself uses TOML for runtime settings.

Also fixed the startup path around ksql restore and Agave version alignment by pinning the plugin to the validator's 4.0.0-beta.4 crates, correcting the generated shared-library path used by local launch targets, and handling ksql startup restore queries and HTTP errors more defensively.

Details

Config loading and launch flow

• added a JSON wrapper config that carries libpath plus the TOML runtime config path
• updated the plugin config loader to accept either the new wrapper or a direct TOML file for compatibility
• removed libpath from the TOML runtime config and updated local examples, docs, and Makefile targets to generate and use the two-file setup
• fixed the generated local plugin library path so launches resolve the workspace target/release artifact correctly

Validator and ksql startup fixes

• pinned the plugin's Agave/Solana dependencies to the same 4.0.0-beta.4 line as the installed validator to avoid runtime mismatch during plugin load
• corrected the startup restore ksql query shape to match the deployed table naming and surface HTTP failure bodies directly when startup restore fails
• kept the restore flow behavior the same after a successful query, including deduplication and backfill chunking

Noise reduction

• moved ignored account update byte logging down to trace level so normal runs are less noisy

Summary by CodeRabbit

• New Features

  • Plugin config now supports a JSON wrapper plus a TOML runtime file; validator JSON can point to the runtime TOML.

• Bug Fixes

  • Improved ksql query generation, stricter identifier validation, and clearer HTTP error reporting.
  • Reduced noisy fallback logging for account parsing.

• Documentation

  • README and examples updated to show the two-file setup and usage.

• Chores

  • Pinned several plugin dependency versions.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

Introduces a JSON “validator wrapper” config (libpath + config_file) and makes libpath optional in the TOML runtime config; updates config-loading to resolve and load the referenced TOML, adjusts Makefile to use the JSON wrapper, pins several Cargo deps, tweaks logging and ksql query/HTTP handling.

Changes

Cohort / File(s)	Summary
Config loading & runtime behavior geyser-plugin/src/config.rs	Make libpath: Option<String>; add read_to_string and resolve_runtime_config_path helpers; support validator JSON wrapper that points to a runtime TOML; add tests for wrapper and minimal TOML.
Build & invocation geyser-plugin/Makefile	Change PLUGIN_PATH to ../target/release/...; add VALIDATOR_CONFIG var; init-config generates both validator JSON and plugin TOML; launch uses --geyser-plugin-config with validator JSON and derives plugin TOML fallback from config_file.
Configuration examples geyser-plugin/configs/plugin-config.example.json, geyser-plugin/configs/plugin-config.example.toml, geyser-plugin/plugin-config.toml	Add JSON wrapper example (libpath + config_file); remove top-level libpath from TOML example and instance file.
Documentation geyser-plugin/README.md	Update docs and examples to document two-file setup: JSON wrapper passed to validator and TOML used for plugin runtime; clarify config_file path rules.
Dependency pinning geyser-plugin/Cargo.toml	Change several dependency constraints to exact/pinned versions (e.g., =4.0.0-beta.4).
Runtime behavior & tests geyser-plugin/src/account_update_publisher.rs, geyser-plugin/src/ksql.rs	Lower fallback log level from debug! to trace! for unparseable pubkey; ksql: validate identifiers (new validate_ksql_identifier), interpolate table unquoted, change HTTP handling to check status.is_success() and include response body on error; add ksql identifier tests.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• feat: unify grpc and plugin configs #1: Modifies geyser-plugin/src/config.rs related to configuration loading; closely related to the config-loading and Makefile changes in this PR.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 65.22% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: stabilize geyser plugin startup' clearly and concisely summarizes the main objective: stabilizing the plugin startup process through configuration restructuring and dependency pinning.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-config

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@geyser-plugin/Makefile`:
- Around line 21-25: The init-config perl replacements are turning an existing
"../target/release/..." path into "../../target/..." because the regex blindly
matches "target/release/..." even when already prefixed; update the two perl
substitution expressions so they only replace bare "target/release/..."
occurrences that are not already prefixed (e.g., use a negative lookbehind like
(?<!\.\./) or a start-of-string/quote-aware anchor) and apply the fix to both
commands that produce $(PLUGIN_CONFIG) and $(VALIDATOR_CONFIG), ensuring
PLUGIN_PATH is inserted only once.
- Around line 40-44: The preflight check currently fails if $(PLUGIN_CONFIG) is
missing; change it to allow valid JSON wrappers by also honoring the runtime
config path stored as config_file inside $(VALIDATOR_CONFIG): update the
Makefile check so it passes when either $(PLUGIN_CONFIG) exists OR
$(VALIDATOR_CONFIG) contains a non-empty config_file value (pointing to an
absolute or differently named TOML path); implement this by parsing
$(VALIDATOR_CONFIG) for the config_file key and using that path as an acceptable
plugin config source (while still erroring if neither condition is met).

In `@geyser-plugin/src/config.rs`:
- Around line 131-138: The code currently swallows serde_json::from_str errors
and falls back to TOML, hiding JSON wrapper parse issues; update the logic
around the serde_json::from_str::<ValidatorConfig>(&contents) call (and the
runtime_path determination using resolve_runtime_config_path and variable
runtime_path) so that if parsing fails and the source is a JSON file
(config_path extension == "json") or the contents look like JSON (trimmed
starts_with('{') or '['), you propagate/return the JSON parse error instead of
falling back to config_path.to_path_buf(); otherwise (non-JSON file/contents)
continue with the existing TOML fallback behavior. Ensure you use the original
serde_json error (not a generic Err(_)) so the caller sees the real parsing
failure.

In `@geyser-plugin/src/ksql.rs`:
- Line 35: The SQL string interpolation uses self.table unescaped (let sql =
format!("SELECT PUBKEY FROM {};", self.table)), so add validation or safe
quoting before formatting: implement a helper like
validate_ksql_identifier(identifier: &str) -> io::Result<&str> that ensures the
identifier starts with a letter or '_' and contains only ASCII alphanumeric or
'_' (or alternatively implement proper double-quoting with escaping), call that
helper on self.table in the function that builds sql (the place where sql is
defined) and return an Err if validation fails; then use the validated/quoted
value when constructing the SELECT statement to prevent injection/invalid
identifiers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: efd80f80-c78d-442c-8c8a-34ec6ea95088

📥 Commits

Reviewing files that changed from the base of the PR and between 5f2f01d and d40859c.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (9)

• geyser-plugin/Cargo.toml
• geyser-plugin/Makefile
• geyser-plugin/README.md
• geyser-plugin/configs/plugin-config.example.json
• geyser-plugin/configs/plugin-config.example.toml
• geyser-plugin/plugin-config.toml
• geyser-plugin/src/account_update_publisher.rs
• geyser-plugin/src/config.rs
• geyser-plugin/src/ksql.rs

💤 Files with no reviewable changes (2)

• geyser-plugin/plugin-config.toml
• geyser-plugin/configs/plugin-config.example.toml