@avatarsd-llc/libtracer-client
v0.22.0
Published
EXPERIMENTAL libtracer client SDK (#56, ADR-0034/0035) — a path-addressed client over the cross-validated codec (@avatarsd-llc/libtracer) and an injected transport seam (e.g. @avatarsd-llc/libtracer-ws). Speaks the RFC-0004 remote operations over FWD: rea
Maintainers
Readme
@avatarsd-llc/libtracer-client (EXPERIMENTAL)
The libtracer client SDK that the web-UI of the originating production
firmware (an ESP32-C6 smart-agriculture node) builds against
(#56,
ADR-0034 /
ADR-0035).
It composes the cross-validated wire codec (@avatarsd-llc/libtracer) over an
injected transport seam (@avatarsd-llc/libtracer-ws's TransportWs satisfies
it structurally), so it runs in the browser or Node and is testable against an
in-memory fake with no socket.
Experimental —
0.1.0, pre-1.0. The client speaks the RFC-0004 remote-operation envelope (FWD/FIELD) the v1 spec §3 fast-tracks: a path-addressedread/write/await/readField/subscribe, each aFWDframe whose source-routedFWD{REPLY}is decoded back. Error-reply codes are provisional until the ERROR registry (#8) pins them.
What it does
import { LibtracerClient, encodeValue } from '@avatarsd-llc/libtracer-client';
import { TransportWs } from '@avatarsd-llc/libtracer-ws';
const transport = new TransportWs('ws://robot.local:9000');
await transport.connect();
const client = new LibtracerClient(transport);
// Path-addressed remote operations over RFC-0004 FWD — each resolves its FWD{REPLY}:
const temp = await client.read('/sensor/temp'); // -> VALUE TLV
await client.write('/sensor/temp', encodeValue(new Uint8Array([0x01])));
const next = await client.await_('/sensor/temp', 1_000_000_000n); // block for the next write (1 s)
const subs = await client.readField('/sensor/temp', ':subscribers[]'); // -> POINT of SUBSCRIBER slots
// subscribe = a field-write of a SUBSCRIBER into :subscribers[]; deliveries fire the handler.
const unsubscribe = await client.subscribe('/sensor/temp', (value) => render(value));
unsubscribe(); // local detach
// A kind=ERROR reply rejects with a typed FwdError (.code / .codeName, e.g. "NOT_FOUND").
client.onError((err) => console.error('inbound decode error', err));await_ deadlines are the client's own. A responder is not required to answer
TIMEOUT (RFC-0004 Amendment 3): it answers on the next write, and otherwise stays silent.
await_ therefore always ends locally, at the shorter of requestTimeoutMs (10 s by
default, and still 10 s for await_ when that option disables other deadlines) and its
timeoutNs, rejecting with a FwdError whose codeName is "TIMEOUT".
Do not pipeline a read behind an await_ on the same vertex. Replies name no request
op, so with both outstanding to one vertex over one connection the two RESULTs cannot be told
apart, and the read's answer can be handed to the await_. Await and read different
vertices, or let one settle before sending the other.
The pure builders (the exact bytes, transport-free) are also exported — the FWD / FIELD envelope builders and the payload builders, each pinned to a conformance vector:
import { encodeFwd, encodeField, FWD_OP, encodeSubscriber } from '@avatarsd-llc/libtracer-client';
encodeSubscriber(['sensor', 'temp']); // === subscriber-path vector
encodeFwd({ op: FWD_OP.READ, dst: ['sensor', 'temp'], src: ['client'] }); // === fwd-read vector
encodeField(':subscribers[]'); // === field-append vectorSurfaces
| Surface | Status | Pinned by |
| --- | --- | --- |
| read / write / await_ / readField / subscribe over FWD | implemented (RFC-0004) | fwd-read, fwd-write-value, fwd-await-timeout, fwd-write-subscriber-field |
| encodeFwd / encodeField builders + decodeFwd | implemented | fwd-*, field-*, fwd-reply-* |
| encodeValue / encodeSubscriber / encodePath payload builders | implemented | value-bool-true, value-ll-u32, value-ts-abs, subscriber-path, path-sensor-temp |
| inbound VALUE delivery (FWD{WRITE} / bare / ROUTER-shed) | implemented | router-wrapped + all vectors |
| typed FwdError on kind=ERROR reply | implemented (codes provisional) | fwd-reply-error; ERROR registry (#8) pins the code set. The ERROR is the first ERROR child of the STATUS at whatever position — fwd-reply-error-after-description pins that rule here and in the Rust binding |
Dependencies
@avatarsd-llc/libtracer is a required peerDependency (the cross-validated
codec — ADR-0033).
@avatarsd-llc/libtracer-ws is an optional peer (the seam is structural; the
client never imports it — inject any { send, onFrame }). ESM-only, node >= 18.
Tests
npm run build && npm test # from bindings/typescript/test/vectors.test.mjs— every outbound builder (encodeValue/encodeSubscriber/encodePath/encodeFwd/encodeField) matches its conformance vector byte-for-byte;decodeFwdparses thefwd-reply-*vectors.test/roundtrip.test.mjs— mock-transport round-trip: the exactFWDbytes each op emits, REPLY-resolves-the-op / ERROR-rejects, injected deliveries, and a realTransportWsecho.test/interop.test.mjs— end-to-end against a live C++fwd_node_serverover a real socket (all five ops, incl. a live subscribe delivery). Guarded onLIBTRACER_FWD_NODE_SERVER; the CIfwd-interopjob builds the binary and runs it.
