refactor(ergo-api): split server.rs, types.rs, batch.rs (1/2)

[arkadianet]

Mechanical, behavior-preserving file-split refactor of the three largest ergo-api root/route files. First of a 2-PR stack (part 2: refactor/ergo-api-split, splitting wallet/native/dto.rs, v1/routes/dto.rs, v1/routes/tx_intel.rs). One commit per split file; every function body moved verbatim (only import headers, new-file module docs, and the minimum visibility promotions listed below).

Split map

src/server.rs (2,524 lines) → src/server/

• mod.rs — ServerCtx, bind/serve wrappers (bind, serve_on*, serve, realtime_handle), the utxo_reads_supported-gated subtree (scala_utxo_subtree + 503 handler + snapshots-info handler), all router builders incl. the ~920-line router_with_mempool_and_wallet_and_security, wallet-ui redirects, SPA security headers
• handlers.rs — the 18 native operator handlers (info/identity/host/status/votes/set_votes/tip/sync/peers/recent_blocks/events/difficulty_history/miner_stats/votes_history/metrics/shutdown/peers_connect/health)
• shared.rs — submit_via_node + map_submit_error (already pub(crate); re-exported at crate::server::* so compat::{blocks,transactions} call sites are untouched)
• openapi.rs — NativeOpenApi derive + SecurityAddon + native_openapi_yaml + the cfg(test) emission test
• assets.rs — static-asset handlers (index, swagger pages, spec emitters, fonts, css, js helper)

src/types.rs (1,876 lines) → src/types/

• mod.rs (mod decls + glob re-exports + shared hex32), identity.rs, status.rs, voting.rs, chain_refs.rs, peers.rs, mempool.rs, events.rs, indexer.rs — flat DTO list partitioned by domain; the ~700-line wire-shape/round-trip pinning-test tail was split alongside each owning domain file (no monolithic test file left behind). ApiWeightFunction's real TryFrom<&str> + error type and ApiNativeSubmitError's From<ApiSubmitError> moved verbatim.

src/v1/routes/batch.rs (1,125 lines) → src/v1/routes/batch/

• mod.rs — module doc, public policy caps (MAX_BATCH_ITEMS, MAX_BATCH_WEIGHT), wire types (BatchRequest/BatchItemRequest/BatchItemResult/BatchResponse)
• allowlist.rs — the route! macro and the ~500-line allowed_routes() manifest kept together as one self-contained unit, so the macro's dispatch-router/classification-table anti-drift invariant is preserved structurally (dispatch.rs consumes only the resulting data, never the macro); the existing table-invariant test (allowed_routes_table_excludes_mutating_submit_domain) lives here and passes
• dispatch.rs — AllowedRoute, template_matches/specificity/classify, BatchState, parse_method, dispatch_one, batch_handler, batch_router

Honored "do NOT split" call-outs

• router_with_mempool_and_wallet_and_security kept whole in server/mod.rs
• batch dispatch/handler logic kept together as one unit in dispatch.rs
• route! macro + table kept together in allowlist.rs (spec's preferred option)

Visibility promotions (complete list, with reasons)

• server/handlers.rs: 18 handler fns private → pub(super) (used by mod.rs route registration and by the NativeOpenApi paths() derive)
• server/assets.rs: 15 asset fns private → pub(super) (used by mod.rs route registration)
• batch/dispatch.rs: AllowedRoute struct + its 3 fields private → pub(super) (constructed by allowlist.rs's route! table)
• batch/allowlist.rs: allowed_routes() private → pub(super) (called by batch_router)
• mod dispatch is pub(crate): v1/openapi.rs's paths() entry was re-pathed to batch::dispatch::batch_handler because utoipa resolves the hidden __path_* struct beside the fn definition, which a plain re-export does not carry
• Everything else keeps its original visibility (submit_via_node/map_submit_error stay pub(crate), all types DTOs were already pub)

Verification

• Baseline (origin/main 981c5a0): cargo test -p ergo-api = 1041 passed / 0 failed / 5 ignored (66 targets); clippy clean
• After every split and at this head: 1041 / 0 / 5 — identical
• OpenAPI golden fixtures (openapi_native_snapshot, openapi_v1_snapshot) pass unchanged — the generated specs are byte-identical
• cargo clippy -p ergo-api --all-targets --all-features -- -D warnings clean; cargo fmt --all --check clean; cargo check --workspace --all-targets clean

🤖 Generated with Claude Code

https://claude.ai/code/session_01Kw7uCwqmiGna8fpg6TvxGi

Summary by CodeRabbit

• New Features
  • Added operator dashboard APIs for node status, health, peers, events, voting, chain data, mempool activity, and metrics.
  • Added OpenAPI and Swagger documentation endpoints, including native and v1 specifications.
  • Added embedded dashboard assets, fonts, JavaScript, and styles.
  • Added a read-only batch API supporting up to 32 requests per call.
  • Added administrative actions for peer connections, voting updates, and node shutdown.
• Documentation
  • Expanded generated API documentation to include batch dispatch routes and authentication details.

[coderabbitai]

Warning

Review limit reached

@arkadianet, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 50 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 40ee042e-b111-4d72-b3d8-5bd59ca403eb

📥 Commits

Reviewing files that changed from the base of the PR and between b276c17 and 4f9ce63.

📒 Files selected for processing (2)

• ergo-api/src/types/voting.rs
• ergo-api/tests/fixtures/openapi_native.yaml

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/ergo-api-split-1

---

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.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

ergo-api/src/v1/routes/batch/dispatch.rs (1)

96-102: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Ignore query strings during route classification.

If a client includes a query string in the path field instead of using the query field, it currently results in an inconsistency. A path like /api/v1/boxes/abcd?limit=10 will successfully pass classification (as abcd?limit=10 satisfies the wildcard :box_id check) and route correctly. However, a path like /api/v1/boxes?limit=10 will fail classification because "boxes?limit=10" does not literally match "boxes", resulting in a ForbiddenTarget error.

Stripping the query string during classification resolves this inconsistency and safely allows Axum to parse and route the URI correctly in both scenarios.

♻️ Proposed refactor

 fn classify(table: &[AllowedRoute], method: &Method, path: &str) -> Option<RouteClass> {
+    let path_only = path.split_once('?').map_or(path, |(p, _)| p);
     table
         .iter()
-        .filter(|r| r.method == *method && template_matches(r.template, path))
+        .filter(|r| r.method == *method && template_matches(r.template, path_only))
         .max_by_key(|r| specificity(r.template))
         .map(|r| r.class)
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ergo-api/src/v1/routes/batch/dispatch.rs` around lines 96 - 102, Update
classify to remove the query-string suffix from path before calling
template_matches and specificity, while preserving the existing method filtering
and route-selection behavior. Use only the portion before the first '?' so paths
with query parameters classify consistently.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ergo-api/src/types/voting.rs`:
- Line 79: Update the voting cadence documentation near the “Desired value”
comment to state that the node votes one step per voting epoch, matching the
behavior described in the surrounding voting documentation. Do not describe the
cadence as occurring per block.

---

Nitpick comments:
In `@ergo-api/src/v1/routes/batch/dispatch.rs`:
- Around line 96-102: Update classify to remove the query-string suffix from
path before calling template_matches and specificity, while preserving the
existing method filtering and route-selection behavior. Use only the portion
before the first '?' so paths with query parameters classify consistently.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 79a26637-da06-4c1f-978b-6f9b68eab737

📥 Commits

Reviewing files that changed from the base of the PR and between 981c5a0 and b276c17.

📒 Files selected for processing (20)

• ergo-api/src/server/assets.rs
• ergo-api/src/server/handlers.rs
• ergo-api/src/server/mod.rs
• ergo-api/src/server/openapi.rs
• ergo-api/src/server/shared.rs
• ergo-api/src/types.rs
• ergo-api/src/types/chain_refs.rs
• ergo-api/src/types/events.rs
• ergo-api/src/types/identity.rs
• ergo-api/src/types/indexer.rs
• ergo-api/src/types/mempool.rs
• ergo-api/src/types/mod.rs
• ergo-api/src/types/peers.rs
• ergo-api/src/types/status.rs
• ergo-api/src/types/voting.rs
• ergo-api/src/v1/openapi.rs
• ergo-api/src/v1/routes/batch.rs
• ergo-api/src/v1/routes/batch/allowlist.rs
• ergo-api/src/v1/routes/batch/dispatch.rs
• ergo-api/src/v1/routes/batch/mod.rs

💤 Files with no reviewable changes (2)

• ergo-api/src/types.rs
• ergo-api/src/v1/routes/batch.rs