Feat/retire aimdb ws protocol - #201
Conversation
…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>
…nents and documentation
…ancelToken, CancelHandle, WasmWsConnection, WasmWsDialer and WsBridge
…ndshake and compatibility checks
…ns and related components
- 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>
… for data integrity
| ws.set_onerror(Some(on_error.as_ref().unchecked_ref())); | ||
| plain_callbacks.push(on_error); | ||
|
|
||
| if open_rx.await != Ok(true) { |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Fixed: accept_dial re-checks stopped after the handshake and abandons the socket; regression tests added in mod dial_tests.
There was a problem hiding this comment.
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?
…DB client and CLI
… for transform join
… the client engine
… final frame flag
…prevent pending entry accumulation
…ve connection stability
…-chromedriver version compatibility
thaodt
left a comment
There was a problem hiding this comment.
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.
| Some(RecordUpdate { | ||
| topic: u.topic.as_deref().map(String::from), | ||
| value, | ||
| skipped, |
There was a problem hiding this comment.
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?
| /// 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 | ||
| } |
There was a problem hiding this comment.
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); |
There was a problem hiding this comment.
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(); |
There was a problem hiding this comment.
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) { |
There was a problem hiding this comment.
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?
| // Terminal rejection: end the stream. | ||
| Err(_) => return futures::future::ready(None), |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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.
4ea7bfc to
36eb670
Compare
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>
36eb670 to
1d12efc
Compare
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>
Retire
aimdb-ws-protocol— every transport speaks AimXDeletes the WebSocket-only wire protocol and converges the entire workspace on
the AimX-v3 envelope (
aimdb-core::session::aimx). One codec, one errormapping, 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 forkwas 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)
#/*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_matchmodule — MQTT-style matching over dot-separated keys, sharedby the core wildcard path and the WS fan-out bus.
SubUpdateitem type — subscription streams now carry{ topic: Option<Arc<str>>, data, skipped }so each event names the concreterecord that fired and threads buffer-lag counts through for drop detection.
topiconevent,subonsnap, an explicitsubscribedack frame (WS only; UDS/serial/TCP stay ack-implicit).record.query→{ records: [{topic, payload, ts}], total }(canonicalQueryRecordrow);RecordMetadatagainsschema_typeandentity.hello— protocol bumped2.0 → 3.0; an incompatible orversion-less peer is refused at the handshake (
RpcError::VersionMismatch).skipped; the server pump doesseq += skipped + 1; the client demux recovers loss as aseqshortfall.WebSocket connector
framing). Dispatch converged on
record.query/record.list.(topic, payload)asArc-shared updates; theper-connection codec envelopes each event (O(1) fan-out preserved).
record.queryfalls back to the persistence-registeredQueryHandlerFnwhenno custom handler is plugged in;
record.listrows are stamped with schemanames from the connector's
StreamableRegistry.WsCodec+ id↔topic maps,split_multi_topic, the pre-serializedData-frame broadcast,with_raw_payload,ClientConfig::topic_routed_subs.Browser bridge (
aimdb-wasm-adapter::ws_bridge)run_client+ClientHandleover aweb_sys::WebSocket-backedConnection/Dialer(single-threaded wasmSend/Syncwrappers). Reply andsubscription correlation now exists exactly once, in core.
write,query,listTopics,onStatusChange, offlinequeue, and reconnect are all delegated to the engine.
Deletions
aimdb-ws-protocolcrate,WsCodec,protocol.rsshims, deadaimdb-clientre-exports.
Breaking changes
2.0 → 3.0— pre-3.x clients are refused athello. Browserclients on the old ws-protocol wire must ship the rebuilt bridge; they fail
closed against a 3.0 server.
with_raw_payload,ClientConfig::topic_routed_subs.record.queryresult 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 checkandmake allgreen. New/updated coverage: AimX codec roundtripsuite (frames + splice byte-for-byte),
topic_matchtests,topic_leafdual-separator, version-compatibility matrix,
query_handler_shape,UDS
handshake_version, rewritten WebSockete2e.rs(subscribe ack, wildcardfan-out, late-join), and fan-out encode benchmarks.
Known limitations (accepted)
server-chosen sub ids (counted down from
u64::MAX); arun_client-basedconsumer 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).
time against the builder-frozen record set; MQTT-style late registration is
deferred until core grows runtime registration.