Skip to content

Feat/retire aimdb ws protocol - #201

Open
lxsaah wants to merge 53 commits into
mainfrom
feat/retire-aimdb-ws-protocol
Open

Feat/retire aimdb ws protocol#201
lxsaah wants to merge 53 commits into
mainfrom
feat/retire-aimdb-ws-protocol

Conversation

@lxsaah

@lxsaah lxsaah commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

Retire aimdb-ws-protocol — every transport speaks AimX

Deletes the WebSocket-only wire protocol and converges the entire workspace on
the AimX-v3 envelope (aimdb-core::session::aimx). One codec, one error
mapping, one client demux — the WebSocket stack and the browser bridge now ride
the same session engine as UDS/serial/TCP and aimdb-client.

Implements design 047 (docs/design/047-retire-ws-protocol-converge-on-aimx.md).

Why

The workspace shipped two wire protocols for one feature. Every capability —
snapshots, acks, writes, queries, subscribe — existed twice, with two codecs and
two error vocabularies, plus a hand-rolled ~835-line browser demux duplicating
run_client. Both protocols already rode the same session engine, so the fork
was pure duplication.

Convergence removes a 353-line protocol crate, a 507-line codec, two error
mappings, and the browser demux, against a small additive AimX extension
(wildcard subscribe + two result-shape changes) that every transport now
inherits (CLI watch 'temp.#', MCP wildcard reads, future serial/TCP browsers).

What changed

Core (additive AimX extension)

  • Wildcard / multi-record live subscribe. A pattern containing #/*
    matches the (builder-frozen) record set once at subscribe time, merges the
    matched records' update streams under one subscription id, and emits one
    snapshot per matched record on open.
  • topic_match module — MQTT-style matching over dot-separated keys, shared
    by the core wildcard path and the WS fan-out bus.
  • SubUpdate item type — subscription streams now carry
    { topic: Option<Arc<str>>, data, skipped } so each event names the concrete
    record that fired and threads buffer-lag counts through for drop detection.
  • Wire additions: optional topic on event, sub on snap, an explicit
    subscribed ack frame (WS only; UDS/serial/TCP stay ack-implicit).
  • Query/list result shapes: record.query{ records: [{topic, payload, ts}], total } (canonical QueryRecord row); RecordMetadata gains
    schema_type and entity.
  • Version-gated hello — protocol bumped 2.0 → 3.0; an incompatible or
    version-less peer is refused at the handshake (RpcError::VersionMismatch).
  • Loss accounting — buffer lag folds into skipped; the server pump does
    seq += skipped + 1; the client demux recovers loss as a seq shortfall.

WebSocket connector

  • Speaks AimX on the transport (one codec blob per WS text frame — no extra
    framing). Dispatch converged on record.query / record.list.
  • The fan-out bus carries (topic, payload) as Arc-shared updates; the
    per-connection codec envelopes each event (O(1) fan-out preserved).
  • record.query falls back to the persistence-registered QueryHandlerFn when
    no custom handler is plugged in; record.list rows are stamped with schema
    names from the connector's StreamableRegistry.
  • Removed: WsCodec + id↔topic maps, split_multi_topic, the pre-serialized
    Data-frame broadcast, with_raw_payload, ClientConfig::topic_routed_subs.

Browser bridge (aimdb-wasm-adapter::ws_bridge)

  • Rewritten on run_client + ClientHandle over a web_sys::WebSocket-backed
    Connection/Dialer (single-threaded wasm Send/Sync wrappers). Reply and
    subscription correlation now exists exactly once, in core.
  • JS API preserved: write, query, listTopics, onStatusChange, offline
    queue, and reconnect are all delegated to the engine.

Deletions

  • aimdb-ws-protocol crate, WsCodec, protocol.rs shims, dead aimdb-client
    re-exports.

Breaking changes

  • Wire protocol 2.0 → 3.0 — pre-3.x clients are refused at hello. Browser
    clients on the old ws-protocol wire must ship the rebuilt bridge; they fail
    closed against a 3.0 server.
  • Removed builder knobs: with_raw_payload, ClientConfig::topic_routed_subs.
  • record.query result shape changed from {values:[{record,value,stored_at}], count} to {records:[{topic,payload,ts}],total}.

Lands as one branch in a release already flagged protocol-breaking, one commit
per work item (no stacked PRs).

Testing

make check and make all green. New/updated coverage: AimX codec roundtrip
suite (frames + splice byte-for-byte), topic_match tests, topic_leaf
dual-separator, version-compatibility matrix, query_handler_shape,
UDS handshake_version, rewritten WebSocket e2e.rs (subscribe ack, wildcard
fan-out, late-join), and fan-out encode benchmarks.

Known limitations (accepted)

  • Auto-subscribe under engine demux — server-seeded subscriptions carry
    server-chosen sub ids (counted down from u64::MAX); a run_client-based
    consumer drops events for ids it never issued, so engine clients (including the
    new bridge) subscribe explicitly. No user-visible change (the pro hub already
    subscribes by exact name).
  • Dynamic record membership — wildcard matches are resolved once at subscribe
    time against the builder-frozen record set; MQTT-style late registration is
    deferred until core grows runtime registration.

test and others added 25 commits July 17, 2026 14:04
…sport on AimX

The mapping-table design doc 036 A2 gated the protocol unification on
(038 §3.9, 034 §3.10 rc10): AimX ↔ ws-protocol frame mapping, the gap
decisions (wildcard subscribe via optional Event.topic, Snapshot routing
via a new sub field, the explicit subscribed ack, the 6→3 error-code
collapse, shared record.query/record.list result shapes), two scope
corrections verified against the code (the aimdb-client demux fold was
already done in PR #124; query passthrough already existed — only the
result shape was missing), and the go/no-go.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…r AimX (design 045)

The two features that justified the ws-protocol fork, added to AimX so
every transport inherits them:

- session::topic_match — the MQTT-style matcher moved in from
  aimdb-ws-protocol (same semantics, same tests) plus is_wildcard.
- Subscription streams yield SubUpdate {topic: Option<Arc<str>>, data}
  on both engines; Outbound::Event gains an optional topic and
  Outbound::Snapshot the routing sub, so a wildcard subscription's
  events and late-join snapshots name the record that fired.
  Session::snapshot becomes snapshots() — one per covered record.
- AimxDispatch matches wildcard patterns against the registry once at
  subscribe time (builder-frozen record set), merges matched streams
  under one subscription id, and snapshots each match on open.
- AimxCodec learns the {"t":"subscribed"} ack (servers running
  acks_subscribe:true — the WS connector) and gets a dedicated
  roundtrip test suite; exact-topic frames are unchanged on the wire.
- ClientConfig::topic_routed_subs removed — it existed solely for the
  retired ws wire; all subscriptions are id-routed.
- Shared result vocabulary: remote::QueryRecord {topic, payload, ts},
  with_persistence's QueryHandlerFn returning {records, total} (sorted
  by ts), and RecordMetadata gaining optional schema_type/entity.
- aimdb-client: AimxConnection::subscribe_with_topics yields
  (Option<String>, Value) pairs; wildcard e2e test over the production
  UDS server; query-shape test against the persistence registration.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ign 045)

The wire is now AimX — one tagged frame per WS text message, the same
envelope as UDS/serial/TCP; the delta really was just the envelope
(everything below the codec already rode the shared session engine).

- run_session drives the shared AimxCodec; the 507-line per-connection
  WsCodec and its id↔topic maps are deleted, as are the multi-topic
  Subscribe split and the protocol re-export shim.
- ClientManager delivers topic-tagged SubUpdates; the per-frame envelope
  is applied by each connection's codec (payload bytes stay Arc-shared).
  The pre-serialized Data frame, its server-side ts, and with_raw_payload
  are gone.
- WsDispatch converges on the AimX vocabulary: record.query via a
  plugged-in QueryHandler (now returning core QueryRecord rows) or the
  Extensions QueryHandlerFn from with_persistence; record.list answers
  {name, schema_type, entity} rows (TopicInfo now lives here).
  Errors collapse to the 3-code set; auth stays at the HTTP 401.
- SnapshotProvider::snapshots(pattern) returns every cached value under
  the pattern, so wildcard subscriptions late-join each covered record.
- Auto-subscribe seeds AimX sub frames with ids counting down from
  u64::MAX (cannot collide with client-chosen ids; design 045 §3.6).
- ws-client builder rides AimxCodec (topic_routed_subs gone); e2e tests
  rewritten to drive raw AimX frames, including golden wire frames and
  ws↔AimX parity for ack/wildcard/snapshot/query/list.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…c (design 045)

The browser is now a first-class engine client: a web_sys::WebSocket-
backed Connection/Dialer pair (JS events funneled into the engine's
async recv; single-threaded wasm Send shims, same pattern and compile
guard as SendFuture) drives run_client + AimxCodec, so reply and
subscription correlation, reconnect backoff, keepalive, and the offline
queue exist exactly once — in core. The hand-rolled 835-line demux is
gone.

The #[wasm_bindgen] surface is preserved (write, query, listTopics,
onStatusChange, status, disconnect, connectBridge options; lateJoin is
retained for option-shape compatibility — snapshots are server-driven
under AimX). Subscription pumps mirror topic-tagged updates into local
records and re-subscribe when a stream ends; the queued subscribe
replays after the engine redials. WasmDb.discover speaks a one-shot
record.list request and resolves {name, schema_type, entity} rows.

Depends on aimdb-core's connector-session + remote features (the
engines cross-compile to wasm32); the aimdb-ws-protocol dep is gone.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…idue (design 045)

With no consumers left, the fork is gone:

- aimdb-ws-protocol crate deleted (353 lines) and de-registered from the
  workspace members, Makefile build/test/clippy/doc targets, and the
  publish sequence (17 → 16 crates).
- aimdb-client: dead NDJSON helpers retired with the hand-rolled client
  in PR #124 are deleted (RequestExt/ResponseExt/serialize_message/
  parse_message/EventMessage/cli_hello — grep-confirmed zero consumers);
  the protocol re-export keeps RecordMetadata/WelcomeMessage/Request/
  Response/Event.
- design 038 §2.5/§3.9 annotated as resolved by 045; root and per-crate
  CHANGELOGs describe the breaking release.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ancelToken, CancelHandle, WasmWsConnection, WasmWsDialer and WsBridge
- Updated comments in `Cargo.toml` files to clarify transport features.
- Revised comments in `engine.rs`, `aimx_session.rs`, and various other files to remove design references and improve clarity.
- Removed outdated design references in `protocol.rs`, `query.rs`, and `codec.rs`.
- Enhanced clarity in `dispatch.rs`, `builder_ext.rs`, and `http.rs` by simplifying comments.
- Adjusted test descriptions in `query_handler_shape.rs` and `e2e.rs` for better understanding.
- Cleaned up `ws_bridge.rs`, `registry.rs`, and `session.rs` to focus on current functionality without legacy design notes.
- Updated `CHANGELOG.md` to reflect changes in `record.list` response structure and removed references to obsolete types.
- Improved overall consistency and readability of comments throughout the codebase.
Reconcile main's direct-JSON-byte remote path (#192/#203) with design-048's
SubUpdate.skipped loss-signal design:

- Subscribe path keeps design-048's SubUpdate/skipped contract (the merged
  Session::subscribe trait yields BoxStream<SubUpdate>); stream.rs stays on
  the (Value, u64) design.
- dispatch.rs combines both: SubUpdate subscribe + wildcard fan-in + WI1
  hello() version gate, plus main's DispatchReply / record.get fast path.
  Restored the futures_util::StreamExt import main had dropped.
- aimdb-bench/Cargo.toml unions both bench sets (fanout_encode + remote_json);
  remote_json.rs updated for Outbound::Event's new `topic` field.

main's direct-JSON-bytes optimization in the live subscribe path is
superseded here and left as the documented follow-up (design 048, "removing
the intermediate serde_json::Value").

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The subscribe path never inspects a record update between reading it and
encoding it onto the wire, yet it parsed the buffer's JSON bytes into a
`serde_json::Value` (`recv_json`) only to re-serialize the tree back to bytes
(`to_payload`) at the dispatch boundary — a pure parse+re-serialize round-trip
per update. This is the direct-JSON-bytes follow-up design 048 flagged.

`stream_record_updates` now reads owned JSON bytes via `recv_json_bytes` and
yields `(Payload, u64)`; the two `stream.map` sites in the AimX dispatch build
`SubUpdate` directly from those bytes. The design-048 `skipped` loss signal is
untouched — it still rides each `SubUpdate`. No wire or public API change.

Verified with the `remote_json` subscription-event benchmark (Tree vs Direct):
the direct-bytes path sustains ~2× the throughput of the former tree path,
matching the 2.06–2.49× encode figure in design 048.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lxsaah
lxsaah requested a review from thaodt July 24, 2026 13:28
@lxsaah
lxsaah marked this pull request as ready for review July 24, 2026 13:28
Comment thread aimdb-core/src/session/topic_match.rs Outdated
Comment thread aimdb-core/src/session/client.rs Outdated
Comment thread aimdb-client/src/engine.rs Outdated
ws.set_onerror(Some(on_error.as_ref().unchecked_ref()));
plain_callbacks.push(on_error);

if open_rx.await != Ok(true) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we re-check shared.stopped immediately after this await?
If disconnect() runs while the handshake is pending, shared.ws is still None, so it cannot close this socket. A later onopen reaches the code below, installs the socket and changes the status back to Connected despite the completed disconnect request. Subscription pumps may also keep ClientHandle clones alive.
I suggest we should close/detach the in-flight socket when stopped and add a disconnect-during-connect regression.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed: accept_dial re-checks stopped after the handshake and abandons the socket; regression tests added in mod dial_tests.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The post-handshake stopped check fixes the late-adoption/status-resurrection part. I'm reopening this because disconnect() still cannot interrupt open_rx.await: while the handshake is pending, the socket is not reachable through shared.ws, so the dial future and its callbacks can remain alive until the browser eventually emits an open/close/error event.

The added regression proves that the socket is rejected after the handshake resolves, but it does not prove prompt cancellation while the handshake remains pending. Could we track and close the in-flight socket, and add a test that keeps open_rx pending and verifies that disconnect() settles the dial promptly?

Comment thread aimdb-wasm-adapter/src/ws_bridge.rs Outdated
Comment thread aimdb-websocket-connector/benches/fanout_socket.rs Outdated
Comment thread aimdb-wasm-adapter/src/ws_bridge.rs

@thaodt thaodt left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm requesting changes for the remaining correctness blockers described inline, primarily the lost snapshot_end marker at the public API boundary and request-ID wraparound.
Separately, I noticed the quiet ws subscription lazy-pruning issue also exists on main and is not a regression of this PR, so it should be tracked in a separate follow-up issue rather than block it.

Comment on lines +392 to +395
Some(RecordUpdate {
topic: u.topic.as_deref().map(String::from),
value,
skipped,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The core fix now makes the 300-record static burst auditable through ClientHandle: 255 ordinary snapshots plus one snapshot_end carrying skipped == 44. However, decode_updates does not copy u.snapshot_end and RecordUpdate has no equivalent field.

decode_updates copies only topic, value and skipped. Therefore, two SubUpdates that differ only in snapshot_end become indistinguishable after decoding, the completion marker is irretrievably lost at this API boundary.

Consequently, AimxConnection::subscribe_updates and the CLI cannot identify when the initial snapshot burst completed, so the snapshot-only guarantee currently holds only for low-level ClientHandle callers. Could we propagate snapshot_end or an explicit update phase/kind through RecordUpdate and add a regression at this API boundary?

Comment on lines +177 to +181
/// Allocate the next correlation id. Monotonic across reconnects, so an id
/// is never reused by a later connection.
fn next_id(&self) -> u64 {
self.next_id.fetch_add(1, Ordering::Relaxed) as u64
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AtomicUsize::fetch_add wraps modulo the target word size. On wasm32/thumbv7em, after the 2^32 ID space is exhausted this returns the reserved ID 0, then reuses 1, 2, etc... Calls and subscriptions share this wire ID space, so a long-lived client can collide with active subscriptions or pending calls and mis-route replies/events.

The explicit cancellation design itself looks correct. Could the allocator use a checked fetch_update and return an error on exhaustion instead of wrapping? Also you may want to add a boundary regression.

while let Some(update) = stream.next().await {
match update {
Ok(update) => {
let _ = router.route(id.as_ref(), &update.data, &ctx);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pump_client consumes only update.data and ignores update.skipped. After a remote buffer, fan-out funnel or client sink overrun, the mirror routes the next value as though delivery had been contiguous.

The CLI and WASM bridge now surface gaps, but the normal connector mirror path remains silently lossy. Could this path expose/report the gap or apply a documented fail/resync policy, with a regression? If mirrors are intentionally latest-state/best-effort, that contract should be explicit rather than silently dropping the metadata.

&"WsBridge: frame queue full — dropping the connection to resync"
.into(),
);
frame_tx.close_channel();

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

close_channel() closes only the receiver, the ws remains open until the queued frames drain and WasmWsConnection is dropped. Its Drop implementation detaches onclose before closing the socket and does not update shared.status.

In particular, with autoReconnect: false, the engine exits after the overflow and no later dial changes the status, so JS can continue observing "connected" after the connection has terminated. With reconnect enabled, the status also stays connected through the drain/backoff window.

Could overflow close the actual socket or otherwise set drop_status() deterministically? A browser regression covering both reconnect settings would pin this down.

ws.set_onerror(Some(on_error.as_ref().unchecked_ref()));
plain_callbacks.push(on_error);

if open_rx.await != Ok(true) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The post-handshake stopped check fixes the late-adoption/status-resurrection part. I'm reopening this because disconnect() still cannot interrupt open_rx.await: while the handshake is pending, the socket is not reachable through shared.ws, so the dial future and its callbacks can remain alive until the browser eventually emits an open/close/error event.

The added regression proves that the socket is rejected after the handshake resolves, but it does not prove prompt cancellation while the handshake remains pending. Could we track and close the in-flight socket, and add a test that keeps open_rx pending and verifies that disconnect() settles the dial promptly?

Comment on lines +403 to +404
// Terminal rejection: end the stream.
Err(_) => return futures::future::ready(None),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The raw ClientHandle stream intentionally carries Err(RpcError) so a caller can distinguish a denied/not-found subscription from a disconnect or normal end. decode_updates converts every terminal error into clean EOF instead.

As a result, aimdb watch treats a denied subscription as a normal stream stop, prints its closing summary and returns success. Could the loss-aware API surface terminal errors, for e.g., as Stream<Item = Result<RecordUpdate, ClientError>>, while retaining value-only compat helpers if needed?

pkg-config --version
"

- name: Test headless browser toolchain

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The browser regressions are still not executed by CI yet.

This step verifies Chrome/chromedriver versions and opens about:blank, but no workflow runs make wasm-test. make check depends on test-wasm, which is only a wasm32 cargo check, so the actual browser-only dial_testsremain unexecuted even though CI is green.

I guess we may add a CI step that runs make wasm-test and add the requested FRAME_QUEUE_CAP overflow regression? The new toolchain is present now, but it is not yet exercising the code it was added for.

@lxsaah
lxsaah force-pushed the feat/retire-aimdb-ws-protocol branch from 4ea7bfc to 36eb670 Compare July 30, 2026 21:22
The transform_join browser target hangs at "Loading scripts..." in the
wasm-browser-tests job while the lib target passes, and it loads fine
locally including pinned to one core. Ruled out by prior runs: Chrome
sandbox, harness timeout (it hung the full 120 s), module size (3 MB
stripped behaves like 23 MB unstripped), CPU, and session order — it
fails alone as the job's first browser session.

The page dies before the harness boots, so the harness's own console
divs stay empty and report nothing useful. Run the target under a
verbose chromedriver log, which carries Chrome's stderr, and print it.

Temporary diagnostic, continue-on-error so the suite still reports.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@lxsaah
lxsaah force-pushed the feat/retire-aimdb-ws-protocol branch from 36eb670 to 1d12efc Compare July 30, 2026 21:29
The transform_join browser target never loaded in CI: its generated JS
glue failed to parse with

  SyntaxError: Identifier
  'wasm_bindgen_..._convert__closures_____invoke______'
  has already been declared

Two closure-invoke shims mangle to one JS identifier, so the module is a
parse error and no test ever starts — which is why the page sat at
"Loading scripts..." with empty console divs and why raising the harness
timeout, shrinking the module and reordering sessions all changed
nothing.

It reproduces only in CI because mangling depends on the compiler: the
devcontainer is on rustc 1.91.1 while the workflow floats on @stable
(1.97.1). wasm-bindgen 0.2.105 was held at that version by
wasm-bindgen-test 0.3.55; moving the family together picks up the
upstream codegen fix.

wasm-bindgen 0.2.105 -> 0.2.126, wasm-bindgen-test 0.3.55 -> 0.3.76,
web-sys/js-sys 0.3.82 -> 0.3.103. Only aimdb-wasm-adapter depends on
them; clippy, test-wasm and the browser suite pass locally.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.

2 participants