feat(ui): operator event feed — bounded node ring + /api/v1/events + live panel

[arkadianet]

What

Phase 2B — the last Phase 2 item of the first-class UI effort: the node narrates its own lifecycle through a live Events panel.

Node side (zero new locks)

• event_feed.rs — bounded EventFeedRing (512, monotonic seq, FIFO eviction) plus a tick-diff deriver. Events are derived, not instrumented: one call site in snapshot_emit diffs successive per-tick observations already collected on the hot path — no subsystem grows an event hook.
• v1 kinds: blockApplied (newest-4/tick from the committed tail, so initial sync can't flood), reorg (committed-tail comparison — including reorg-with-advance, detected when the tail shows a different id at the previous tip height), peerConnected/peerDisconnected (sorted, deterministic 16/tick cap), indexerStatus transitions. The first tick primes the differ silently.
• Consistency contract: the differ's tip is derived from the committed recent tail itself — the same source as its block list — so the async-persist window (in-memory tip ahead of committed) defers events by a tick instead of losing them.
• Ring tail projects into the lock-free snapshot as Arc<ApiNodeEvents>, seq-key-cached so a quiet tick re-publishes the same allocation.

API

• GET /api/v1/events?since=<seq> — flat camelCase events with optional per-kind fields; latestSeq for cursor polling; gaps = ring eviction; the reorg approximation is documented at the API level. Defaulted NodeReadState::events() keeps the many test fixtures untouched. utoipa-documented, native openapi snapshot regenerated.

UI

• Overview gains a full-width Events panel: kind-colored pills, block heights deep-linking into the explorer, relative timestamps, newest first — hidden gracefully on nodes without the endpoint.

Review & testing

• codex adversarial pass found 1 High + 2 Medium + 1 Low + 1 Nit — all fixed in this commit: the High (committed-vs-in-memory tip desync permanently losing block events) is closed by the same-source contract above and pinned by a dedicated test; reorg-with-advance detection added; the differ gained 8 unit tests (priming, idempotent ticks, caps, both reorg shapes, deferred-not-lost lag, peer determinism, indexer transitions); peer caps made deterministic; projection Arc cached by seq.
• 4-case endpoint test (full tail / strict since / beyond-latest / defaulted-empty); openapi snapshot + runtime-mount + ring tests green.
• Full workspace gate green (fmt / clippy -D warnings / cargo test --all).
• Panel verified via the dev proxy with a mocked feed (9063 runs v0.5.0 without the endpoint — which also exercised the hidden-when-absent path).

Closes out Phase 2. Phase 3 (mining panel, light theme completion, responsive/a11y) is next.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added GET /api/v1/events to the operator API, including sequence-based polling via since.
  • Added a live “Events” panel to the dashboard showing the latest events (with links where applicable).
  • Introduced structured event payloads with typed fields and latestSeq.
• Bug Fixes
  • Ensures consistent event ordering and correct filtering when using since (including empty/zero states).
• Documentation
  • Updated OpenAPI spec with the new endpoint and response schemas for event feeds.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6f6e4c88-83c9-4fcb-bfa4-9a44a9bcbb6f

📥 Commits

Reviewing files that changed from the base of the PR and between 7a168a3 and 8355131.

📒 Files selected for processing (3)

• ergo-api/src/server.rs
• ergo-api/tests/fixtures/openapi_native.yaml
• ergo-node/src/node/snapshot_emit.rs

🚧 Files skipped from review as they are similar to previous changes (3)

• ergo-api/tests/fixtures/openapi_native.yaml
• ergo-node/src/node/snapshot_emit.rs
• ergo-api/src/server.rs

---

📝 Walkthrough

Walkthrough

Adds an operator event feed from node snapshot state to a new GET /api/v1/events API, with OpenAPI updates, endpoint tests, and dashboard rendering for recent events.

Changes

Operator event feed feature

Layer / File(s)	Summary
Event feed ring buffer and event derivation ergo-node/src/node/event_feed.rs, ergo-node/src/node/mod.rs	Defines the event feed data model, differencing logic, bounded ring storage, module wiring, and unit tests.
NodeState wiring for event feed ergo-node/src/node/state.rs, ergo-node/src/node/boot.rs, ergo-node/src/node/tests.rs	Adds event-feed fields to NodeState and initializes them at boot and in test fixtures.
Snapshot projection and publishing ergo-node/src/snapshot.rs, ergo-node/src/node/snapshot_emit.rs, ergo-node/src/api_bridge.rs	Adds the events snapshot field, builds and caches the API projection during snapshot publication, and clones it through the snapshot bridge.
API endpoint, DTOs, and tests ergo-api/src/types.rs, ergo-api/src/traits.rs, ergo-api/src/server.rs, ergo-api/tests/events_endpoint.rs, ergo-api/tests/fixtures/openapi_native.yaml	Adds the event DTOs, trait method, handler, router mount, OpenAPI entries, and endpoint tests for /api/v1/events.
Dashboard client and Events panel ergo-api/web/js/api-client.js, ergo-api/web/js/overview.js, ergo-api/web/dashboard.css	Adds the client fetch, slow-state wiring, dashboard rendering, and CSS for the events panel.

Estimated code review effort: 3 (Moderate) | ~35 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change set: an operator event feed with the node ring, API endpoint, and live UI panel.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ 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 feat/ui-events-feed

---

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: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

ergo-node/src/node/snapshot_emit.rs (1)

139-155: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Handle committed_tip() errors without advancing the event-feed cursor.
Err(e) currently becomes an empty tail, so derive_events sees tip_height = 0 / tip_id = "" and resets FeedPrev; when the read succeeds again, the feed can replay already-emitted blockApplied events. Keep Ok(None) as the genuine no-chain case, but skip derive_events or reuse the last projection on the error path.

🤖 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-node/src/node/snapshot_emit.rs` around lines 139 - 155, The error path
in snapshot emission is being treated like a real empty chain, which advances
the event-feed cursor incorrectly. In `snapshot_emit.rs`, keep `Ok(None)` as the
only case that yields an empty tail, but change the `Err(e)` branch from
`ChainStoreReader::committed_tip()` so it does not feed `derive_events` with a
fake zero tip; instead, skip updating the projection or reuse the previously
computed tail state from `recent_blocks_for_tip`/`FeedPrev` handling. Make the
fix around the `recent_blocks_committed` computation so transient read faults
preserve the last emitted cursor and avoid replaying `blockApplied` events.

🧹 Nitpick comments (2)

ergo-api/tests/events_endpoint.rs (2)

39-141: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reduce duplicated boilerplate between FeedStub and DefaultStub.

The two stubs repeat identical info/status/tip/sync/peers/mempool_summary/mempool_transactions/mempool_transaction/health bodies. Since DefaultStub must keep NOT overriding events() to actually exercise the trait default, full merging into one struct isn't possible, but the shared bodies can be factored into free functions both impls delegate to.

♻️ Suggested refactor (illustrative)

+mod stub_defaults {
+    use super::*;
+    pub fn info() -> ApiInfo { ApiInfo { agent_name: "ergo-rust".into(), node_name: "stub".into(), network: "mainnet".into(), version: "0.1.0".into(), started_at_unix_ms: 0, uptime_seconds: 0, target_block_interval_ms: 120_000 } }
+    pub fn status() -> ApiStatus { ApiStatus { sync_state: SyncStateLabel::AtTip, peer_count: 0, best_header_height: 900_000, best_full_block_height: 900_000, headers_ahead_of_full_blocks: 0, mempool_size: 0, snapshot_age_ms: 0, bootstrap: None, last_block_apply_error: None, block_apply_errors_total: 0, mempool_tx_requested_total: 0, mempool_peer_tx_admitted_total: 0, mempool_peer_tx_rejected_total: 0 } }
+    // ...tip/sync/mempool_summary/mempool_transactions/health likewise...
+}
+
 impl NodeReadState for FeedStub {
     fn events(&self) -> ApiNodeEvents { /* ... */ }
-    fn info(&self) -> ApiInfo { ApiInfo { /* full literal */ } }
+    fn info(&self) -> ApiInfo { stub_defaults::info() }
     // ...same delegation pattern for the rest...
 }
 
 impl NodeReadState for DefaultStub {
-    fn info(&self) -> ApiInfo { ApiInfo { /* full literal, duplicated */ } }
+    fn info(&self) -> ApiInfo { stub_defaults::info() }
     // events() intentionally absent — exercises the trait default.
 }

Also applies to: 205-299

🤖 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/tests/events_endpoint.rs` around lines 39 - 141, The `FeedStub` impl
duplicates the same `info`, `status`, `tip`, `sync`, `peers`, `mempool_summary`,
`mempool_transactions`, `mempool_transaction`, and `health` bodies already
present in `DefaultStub`; factor these shared return values into helper/free
functions and have both impls delegate to them. Keep `DefaultStub`’s `events()`
unimplemented so it continues to exercise the trait default, and only extract
the repeated non-events methods from the `NodeReadState` impls.

---

178-195: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a test for a non-numeric since value.

The endpoint's documented contract ("Omitted or non-numeric = the full retained tail") isn't exercised by any test — only the omitted, valid, and beyond-latest cases are covered.

#[tokio::test]
async fn events_since_non_numeric_returns_full_tail() {
    let body = get_json(app(Arc::new(FeedStub)), "/api/v1/events?since=abc").await;
    assert_eq!(body["events"].as_array().unwrap().len(), 3);
}

🤖 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/tests/events_endpoint.rs` around lines 178 - 195, Add a test in
events_endpoint.rs to cover the non-numeric since query behavior that is part of
the endpoint contract. Extend the events_since_* test coverage by adding a new
tokio::test alongside events_since_filters_strictly_greater and
events_since_beyond_latest_returns_empty_list, using
get_json(app(Arc::new(FeedStub)), "/api/v1/events?since=abc") and asserting the
response returns the full retained tail (all events) rather than filtering or
erroring.

🤖 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/server.rs`:
- Around line 1661-1697: The `/api/v1/events` handler documentation currently
describes the retained event tail as if it were the full 512-event ring, but
`build_events_projection()` only exposes `ring.latest(100)`, so the stated
retention is misleading. Update the `events_handler`/`ApiNodeEvents` description
to match the actual 100-event snapshot window, or change
`build_events_projection()` to publish the full 512 if that is the intended
behavior.

In `@ergo-node/src/node/snapshot_emit.rs`:
- Around line 916-979: `build_events_projection` is truncating the event feed to
`ring.latest(100)`, which breaks the intended resume semantics because clients
can miss still-retained events before ring eviction. Update this projection to
expose the full available ring window (or otherwise align the documented
catch-up guarantee with the actual cap) so `events_handler` in the API sees all
events still present in `EventFeedRing`, and keep the seq-keyed cache behavior
unchanged.

---

Outside diff comments:
In `@ergo-node/src/node/snapshot_emit.rs`:
- Around line 139-155: The error path in snapshot emission is being treated like
a real empty chain, which advances the event-feed cursor incorrectly. In
`snapshot_emit.rs`, keep `Ok(None)` as the only case that yields an empty tail,
but change the `Err(e)` branch from `ChainStoreReader::committed_tip()` so it
does not feed `derive_events` with a fake zero tip; instead, skip updating the
projection or reuse the previously computed tail state from
`recent_blocks_for_tip`/`FeedPrev` handling. Make the fix around the
`recent_blocks_committed` computation so transient read faults preserve the last
emitted cursor and avoid replaying `blockApplied` events.

---

Nitpick comments:
In `@ergo-api/tests/events_endpoint.rs`:
- Around line 39-141: The `FeedStub` impl duplicates the same `info`, `status`,
`tip`, `sync`, `peers`, `mempool_summary`, `mempool_transactions`,
`mempool_transaction`, and `health` bodies already present in `DefaultStub`;
factor these shared return values into helper/free functions and have both impls
delegate to them. Keep `DefaultStub`’s `events()` unimplemented so it continues
to exercise the trait default, and only extract the repeated non-events methods
from the `NodeReadState` impls.
- Around line 178-195: Add a test in events_endpoint.rs to cover the non-numeric
since query behavior that is part of the endpoint contract. Extend the
events_since_* test coverage by adding a new tokio::test alongside
events_since_filters_strictly_greater and
events_since_beyond_latest_returns_empty_list, using
get_json(app(Arc::new(FeedStub)), "/api/v1/events?since=abc") and asserting the
response returns the full retained tail (all events) rather than filtering or
erroring.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 771c1c16-8f8e-456e-844a-a3f650ed0457

📥 Commits

Reviewing files that changed from the base of the PR and between 72e3b52 and 7a168a3.

📒 Files selected for processing (16)

• ergo-api/src/server.rs
• ergo-api/src/traits.rs
• ergo-api/src/types.rs
• ergo-api/tests/events_endpoint.rs
• ergo-api/tests/fixtures/openapi_native.yaml
• ergo-api/web/dashboard.css
• ergo-api/web/js/api-client.js
• ergo-api/web/js/overview.js
• ergo-node/src/api_bridge.rs
• ergo-node/src/node/boot.rs
• ergo-node/src/node/event_feed.rs
• ergo-node/src/node/mod.rs
• ergo-node/src/node/snapshot_emit.rs
• ergo-node/src/node/state.rs
• ergo-node/src/node/tests.rs
• ergo-node/src/snapshot.rs