Skip to content

feat: add Rust native streaming client and shared conformance - #21

Draft
igorls wants to merge 9 commits into
masterfrom
feat/rust-native-stream-v1
Draft

igorls wants to merge 9 commits into
masterfrom
feat/rust-native-stream-v1

Conversation

@igorls

@igorls igorls commented Oct 23, 2026 •

Copy link
Copy Markdown
Member

Adds an experimental Rust client for Hyperion's additive native WebSocket + JSON protocol. A standalone core has no third-party dependencies; the separate adapter supplies Tokio, tokio-tungstenite, Serde/JSON and Rustls with certificate and hostname verification.

The client supports typed action/delta requests, scoped subscription identities, bounded stream/connection credit, history/live ordering, cancellation, finite deadlines, irreversible delivery and inclusive replay. Reconnect preserves the earliest recovery block and verified LIB identity while invalidating old reversible buffers. Application acceptance ACKs remain distinct from durable processing.

The versioned contract and SHA256-pinned shared corpus cover 37 valid/invalid wire vectors, 24 state scenarios and two action/delta network sessions. Both Rust and native Node WebSocket peers run the network fixtures. Regression work fixed stale reconnect clocks, lost terminal errors, finality identity loss, repeated reuse of disconnect reserves, simultaneous-error loss, below-anchor/pre-acceptance data, and malformed known receipt metadata. A pre-existing legacy LIB fixture now waits for the replacement UUID; delayed ACKs reproduce its former race without changing legacy production code.

Validation:

  • 24 Rust tests plus the compiled API example; shared vectors/scenarios run within these tests.
  • Real WebSocket fault, cancellation, recovery, idle/subprotocol/message-limit and authentication cases.
  • TLS success, unknown CA and wrong-hostname rejection without disabling verification.
  • Rust 1.88/stable format, strict Clippy, dependency isolation, docs and core package verification.
  • Legacy 60-test ESM and 60-test CommonJS suites and external package consumers.
  • CI covers Windows/Linux, Rust 1.88/stable and Node 24/26.

Refs #20 and the investigation in #19. Server integration is coordinated in eosrio/hyperion-history-api#294: shared history delivery landed in #295, and native JSON/credit foundations are in #296. This PR remains a draft while the actual native endpoint, real routing/history cleanup and source/proxy/fanout/recovery acceptance are integrated. The Node peer is a conformance peer; production JavaScript recovery parity and Python are separate work. No crate/npm publication or production endpoint activation is included.

@igorls

igorls commented Oct 23, 2026

Copy link
Copy Markdown
Member Author

Exact client head: 346c473f55979ff2dd841aa2bbba4bcfebc49ef7.

Standards

No outstanding actionable findings. The core/adapter dependency boundary is preserved. Queue usage counters balance through delivery, failure, cancellation, fork and disconnect. Reconnect retains terminal outcomes; subscription admission and the disconnect reserve remain bounded, including repeated failed recovery and simultaneous terminal errors. Incremental receipt validation matches the server helper while leaving arbitrary contract data opaque.

Spec

No outstanding actionable findings. Independent review verified the corrected reconnect clock, retained replay-required errors, persistent LIB consistency and bounded outcomes. Shared literal scenarios exercise the public core and codec. Receipt shape changes and the delayed-ACK legacy fixture regression passed independent Rust/Node and ESM/CJS checks.

Total outstanding findings: Standards 0; Spec 0.

Validation on this head:

  • All four Rust acceptance jobs passed: Windows/Linux, Rust 1.88/stable, native Node 22/24 peers, 24 Rust tests, compiled API example, strict Clippy/format/docs, core dependency isolation and package verification.
  • All four legacy client acceptance jobs passed: Node 22/24 on Windows/Linux, ESM/CommonJS/type/package consumers, Chromium and production dependency audit.
  • Shared corpus revision 2: 37 wire vectors, 24 public-state scenarios and two action/delta network sessions; all four manifest resources are SHA256-pinned.
  • The architecture owner consumed the identical client pin in HAPI #296 and reported all 37 vectors plus 91 focused server checks passing on Node 22/24. The shared history seam #295 is merged. The actual native endpoint/session, real routing/history cleanup and source/proxy/fanout/recovery acceptance remain open under HAPI #294/#231, so this PR stays a draft.

No crate/npm publication or production endpoint activation was performed.

@igorls

igorls commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

Node baseline reconciliation is complete at c6c3733719fec6a11dcf07a31c66e523f06dba9a (tree fac88addef7e0c402b0da1f67339cd7197ac46f0). The feature branch inherits merged baseline #23 (7fe4e21) and retains its native client implementation.

  • Node minimum is 24; JavaScript CI covers 24/26 on Linux and Windows.
  • Native Rust peers use Node 24 with Rust 1.88.0 and Node 26 with stable Rust, on both platforms. Every existing format, Clippy, conformance, documentation and package check is retained.
  • Superseded PR runs cancel; push/manual events have run-specific groups and do not cancel one another.
  • The approved Bun pin is corrected to 1.4.4, agreeing with current documentation.
  • Rust source/toolchains, Cargo lockfile, npm dependency pins, protocol/source pins, all four shared-corpus hashes and historical measurements are unchanged.

Standards

Independent fixed-head review: 0 violations, 0 smell findings. Both workflows preserve pinned actions, permissions, timeouts and acceptance commands. Current engine metadata and documentation agree.

Spec

Independent fixed-head review: 0 findings. The changes match the approved Node 24 minimum / Node 24+26 transition and Bun correction. PR #21 remains draft and issue #22 remains open.

All eight exact-head jobs passed: JavaScript acceptance and Rust native acceptance. Native action/delta interoperability and the 37 wire vectors also passed locally with Node 24.19.0 and checksum-verified Node 26.12.1; Bun 1.4.4 typechecking passed.

The 7,086-byte handoff patch from the original 346c473 base was verified in a temporary Git index to reproduce the exact new tree. SHA256: bd83b68d474f0f2f55509d77b3c5758c79a295f65d09447ba57effbbba772ed6. It is submitted through coordination task task_node26_client_rust_draft_20261024.

Refs #22. This runtime-baseline reconciliation does not establish native server endpoint/source/proxy/fanout acceptance and does not merge, publish or activate the native client.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant