@net-mesh/core 0.21.0 → 0.23.0

package/mesh_rpc.js

@@ -21,10 +21,28 @@
 //   const policy = new RetryPolicy({ maxAttempts: 3 })
 //   const reply = await rpc.callWithRetry(targetId, 'echo', req, undefined, policy)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NRPC_TYPED_HANDLER_ERROR = exports.NRPC_TYPED_BAD_REQUEST = exports.CircuitBreaker = exports.BreakerOpenError = exports.HedgePolicy = exports.RetryPolicy = exports.TypedRpcStream = exports.TypedMeshRpc = void 0;
+exports.NRPC_TYPED_HANDLER_ERROR = exports.NRPC_TYPED_BAD_REQUEST = exports.CircuitBreaker = exports.BreakerOpenError = exports.HedgePolicy = exports.RetryPolicy = exports.TypedResponseSink = exports.TypedDuplexStream = exports.TypedDuplexSink = exports.TypedDuplexCall = exports.TypedRequestStream = exports.TypedClientStreamCall = exports.TypedRpcStream = exports.TypedMeshRpc = exports.DIRECTION_INBOUND = exports.DIRECTION_OUTBOUND = exports.STATUS_KIND_CANCELED = exports.STATUS_KIND_TIMEOUT = exports.STATUS_KIND_ERROR = exports.STATUS_KIND_OK = void 0;
 exports.defaultRetryable = defaultRetryable;
 exports.defaultBreakerFailure = defaultBreakerFailure;
 exports.appError = appError;
+exports.rawEventToTyped = rawEventToTyped;
+/**
+ * Status-kind discriminants emitted on `RawRpcCallEvent.statusKind`
+ * and consumed when normalizing into the tagged-union
+ * {@link RpcCallStatus}. Prefer these constants over hard-coding
+ * the string literal in `if (evt.statusKind === '...')` checks —
+ * a typo on the literal silently never fires.
+ *
+ * Named `STATUS_KIND_*` to disambiguate from the wire-level
+ * `STATUS_*` u16 status codes used by `RpcServerError`.
+ */
+exports.STATUS_KIND_OK = 'ok';
+exports.STATUS_KIND_ERROR = 'error';
+exports.STATUS_KIND_TIMEOUT = 'timeout';
+exports.STATUS_KIND_CANCELED = 'canceled';
+/** Direction-kind discriminants on `RawRpcCallEvent.direction`. */
+exports.DIRECTION_OUTBOUND = 'outbound';
+exports.DIRECTION_INBOUND = 'inbound';
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const native = require('./index');
 // Duck-typed message extractor — keeps the "any rejected value
@@ -172,6 +190,147 @@ class TypedMeshRpc {
     findServiceNodes(service) {
         return this._raw.findServiceNodes(service);
     }
+    // ---- client-streaming (S2-B1) -------------------------------------------
+    /**
+     * Open a typed client-streaming call. Returns a
+     * `TypedClientStreamCall<Req, Resp>` — push each request via
+     * `send(value)`, then `finish()` to drain the terminal
+     * response.
+     *
+     * Cancellation (v3 / C-A1): `opts.signal` is wired end-to-end
+     * via the same `wireAbortSignal` helper unary calls use.
+     * `signal.aborted` triggers the substrate's
+     * `MeshNode::cancel(token)`, which drops the pending
+     * client-stream entry — the next `send()` / `finish()` observes
+     * a stream-closed error within bounded time, and the call's
+     * Drop emits CANCEL on the wire. Invoking `typedCall.close()`
+     * explicitly is still supported as the imperative cancel
+     * surface.
+     */
+    async callClientStream(targetNodeId, service, opts) {
+        const { rawOpts, detach } = wireAbortSignal(this._raw, opts);
+        try {
+            const rawCall = await this._raw.callClientStream(targetNodeId, service, rawOpts);
+            return new TypedClientStreamCall(rawCall, detach);
+        }
+        catch (err) {
+            detach();
+            throw err;
+        }
+    }
+    /**
+     * Register a typed client-streaming handler. The handler
+     * receives a `TypedRequestStream<Req>` (auto-decodes each
+     * inbound chunk to `Req`) and returns the terminal response
+     * `Resp` (encoded back to JSON before reaching the caller).
+     *
+     * Decode failure on a chunk surfaces from `stream.next()` as
+     * `nrpc:codec_decode:` — the handler may catch it (e.g. skip
+     * the bad chunk) or let it propagate. Letting it propagate
+     * surfaces to the caller as `RpcServerError(Internal)`; the
+     * handler may instead wrap it with `appError(NRPC_TYPED_BAD_REQUEST,
+     * ...)` to signal a typed bad-request status code.
+     */
+    serveClientStream(service, handler) {
+        return this._raw.serveClientStream(service, async (rawStream) => {
+            const typedStream = new TypedRequestStream(rawStream);
+            const resp = await handler(typedStream);
+            return jsonEncode(resp);
+        });
+    }
+    // ---- duplex (S2-B2) ----------------------------------------------------
+    /**
+     * Open a typed duplex call. Returns a `TypedDuplexCall<Req,
+     * Resp>` — push typed requests via `send`, pull typed responses
+     * via `next` (or `for await`), or `intoSplit` to separate the
+     * halves for the encoder-task / decoder-task pattern.
+     *
+     * Cancellation (v3 / C-A1): `opts.signal` is wired through to
+     * the substrate's cancel-token primitive — same pattern as
+     * `callClientStream`. Aborting the signal drops both halves
+     * cleanly; the receive side observes EOF on its next pull and
+     * Drop emits CANCEL on the wire. `typedCall.close()` is still
+     * supported as the imperative cancel surface.
+     */
+    async callDuplex(targetNodeId, service, opts) {
+        const { rawOpts, detach } = wireAbortSignal(this._raw, opts);
+        try {
+            const rawCall = await this._raw.callDuplex(targetNodeId, service, rawOpts);
+            return new TypedDuplexCall(rawCall, detach);
+        }
+        catch (err) {
+            detach();
+            throw err;
+        }
+    }
+    /**
+     * Register a typed duplex handler. The user signature is
+     * `(stream: TypedRequestStream<Req>, sink: TypedResponseSink<Resp>) => Promise<void>`
+     * — the wrapper destructures the napi-side `[stream, sink]`
+     * tuple internally so the user handler never sees the array
+     * form. Handler return is `void`; the substrate emits the
+     * terminal frame automatically. To surface a typed Application
+     * status, throw `appError(code, body)` from the handler.
+     */
+    serveDuplex(service, handler) {
+        return this._raw.serveDuplex(service, async ([rawStream, rawSink]) => {
+            const typedStream = new TypedRequestStream(rawStream);
+            const typedSink = new TypedResponseSink(rawSink);
+            await handler(typedStream, typedSink);
+            // The napi side discards the terminal Buffer for duplex
+            // handlers (only the Ok/Err outcome matters — see
+            // NodeDuplexRpcHandler at bindings/node/src/mesh_rpc.rs).
+            // Return an empty Buffer so the JS signature is satisfied.
+            return DUPLEX_TERMINAL_SENTINEL;
+        });
+    }
+    // ---- observer + metrics (S2-B3) ----------------------------------------
+    /**
+     * Install (pass a handler) or clear (pass `null`) the caller-side
+     * nRPC observer. The handler fires once per completed outbound
+     * RPC with a decoded {@link RpcCallEvent} — the tagged
+     * `status` discriminator is reconstructed from the napi POD's
+     * flat `statusKind` / `statusMessage` fields.
+     *
+     * **Callback contract (locked decision #1).** The handler fires
+     * synchronously from the substrate's dispatch path via a TSFN in
+     * `NonBlocking` mode — if the Node event loop is wedged, events
+     * are **dropped**, not buffered. Callbacks must therefore be
+     * cheap: push into a queue or ring buffer for slow consumers;
+     * do not do work inline. A bounded-mpsc + drop-counter layer is
+     * a deliberate post-v1 follow-up.
+     *
+     * **Mid-call swap.** The substrate uses `ArcSwap` for the
+     * observer slot, so swaps are atomic — but a swap mid-call
+     * means some events fire against the old handler, some against
+     * the new. Set the observer once at startup for clean
+     * semantics.
+     *
+     * v1 only emits `direction === 'outbound'` events; the
+     * server-side `'inbound'` hook is a planned follow-up.
+     */
+    setObserver(handler) {
+        if (handler === null) {
+            this._raw.setObserver(null);
+            return;
+        }
+        // Normalize the napi POD's flat `statusKind` / `statusMessage`
+        // into the TS-idiomatic tagged `RpcCallStatus` discriminator
+        // before reaching user code.
+        this._raw.setObserver((raw) => {
+            handler(rawEventToTyped(raw));
+        });
+    }
+    /**
+     * Snapshot the per-service nRPC metrics registry. Cheap — one
+     * DashMap iteration on the substrate side. Safe to collect on
+     * every Prometheus scrape. The returned object is a plain POD
+     * (no class wrapping); read fields directly or feed into your
+     * own exporter.
+     */
+    metricsSnapshot() {
+        return this._raw.metricsSnapshot();
+    }
     // ---- resilience helpers --------------------------------------------------
     /**
      * Direct-addressed typed call with retry. See {@link RetryPolicy}.
@@ -277,6 +436,486 @@ class TypedRpcStream {
 }
 exports.TypedRpcStream = TypedRpcStream;
 // ============================================================================
+// TypedClientStreamCall + TypedRequestStream (S2-B1).
+//
+// Client-streaming: caller pushes typed Reqs via `send`, then
+// `finish` awaits a single terminal Resp.
+//
+// Server-side handler shape mirrors the unary `serve`'s decode
+// boundary — chunks decode lazily inside `TypedRequestStream.next`
+// so a single malformed chunk doesn't poison the entire stream
+// (the handler can catch and skip).
+//
+// Cancellation contract (locked decision #2): v1 supports
+// `close()`-only cancellation. AbortSignal / cancel-token wiring
+// across streaming shapes is a deliberate post-v1 follow-up.
+// ============================================================================
+/**
+ * Typed client-streaming call handle. Push typed requests via
+ * `send`, then await the terminal response with `finish`. Drop
+ * / `close` fires CANCEL via the underlying raw call's drop.
+ */
+class TypedClientStreamCall {
+    _raw;
+    _detachSignal;
+    /**
+     * `detachSignal` is the cleanup function returned by
+     * `wireAbortSignal`. Run on `close()` (or on call resolution
+     * via `finish()`) so the AbortSignal listener doesn't outlive
+     * the call.
+     */
+    constructor(rawCall, detachSignal = () => { }) {
+        this._raw = rawCall;
+        this._detachSignal = detachSignal;
+    }
+    /** Underlying raw call for users who want the Buffer-level surface. */
+    get raw() {
+        return this._raw;
+    }
+    /**
+     * Encode `value` as JSON and push it as one request chunk.
+     * Throws `nrpc:codec_encode:` if encoding fails (the chunk is
+     * NOT sent in that case).
+     */
+    async send(value) {
+        const buf = jsonEncode(value);
+        await this._raw.send(buf);
+    }
+    /**
+     * Close the upload direction and await the terminal response.
+     * Consumes the call — subsequent `send` / `finish` throw
+     * `stream_closed`. Decode failure on the terminal Buffer
+     * surfaces as `nrpc:codec_decode:`.
+     */
+    async finish() {
+        try {
+            const buf = await this._raw.finish();
+            return jsonDecode(buf);
+        }
+        finally {
+            this._detachSignal();
+        }
+    }
+    /** Server-assigned `call_id`. */
+    async callId() {
+        return await this._raw.callId();
+    }
+    /** `true` if the call was opened with `requestWindowInitial`. */
+    async flowControlled() {
+        return await this._raw.flowControlled();
+    }
+    /**
+     * Close without finishing. Fires CANCEL on the wire if the
+     * initial REQUEST has flown. Idempotent. A concurrent in-flight
+     * `send()` awaiting flow-control credit observes `stream_closed`.
+     *
+     * Detaches the `AbortSignal` listener (if one was wired by
+     * `TypedMeshRpc.callClientStream(opts.signal)`) so the
+     * signal can be reused for a subsequent call.
+     */
+    async close() {
+        this._detachSignal();
+        try {
+            await this._raw.close();
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    }
+}
+exports.TypedClientStreamCall = TypedClientStreamCall;
+/**
+ * Typed inbound request stream surfaced to client-streaming +
+ * duplex server handlers. Drain via `next()` until it returns
+ * `null` (clean EOF) or implements `AsyncIterable<Req>` for
+ * `for await (const req of stream)` style.
+ *
+ * Decode failure on a chunk surfaces as `nrpc:codec_decode:` —
+ * the handler may catch and skip, or let it propagate to abort
+ * the call. The underlying raw stream is closed on decode
+ * failure so subsequent `next()` returns `null`.
+ */
+class TypedRequestStream {
+    _raw;
+    _done;
+    constructor(rawStream) {
+        this._raw = rawStream;
+        this._done = false;
+    }
+    /** Underlying raw stream for users who need the Buffer-level surface. */
+    get raw() {
+        return this._raw;
+    }
+    /** Caller's peer origin hash (`0n` on the loopback fast path). */
+    get callerOrigin() {
+        return this._raw.callerOrigin;
+    }
+    /** Server-assigned `call_id`. */
+    get callId() {
+        return this._raw.callId;
+    }
+    /**
+     * Caller's declared deadline as a Unix-nanoseconds absolute
+     * timestamp. `0n` means no deadline was declared.
+     */
+    get deadlineNs() {
+        return this._raw.deadlineNs;
+    }
+    /**
+     * Initial-REQUEST headers carried by the caller. Each entry is
+     * `[name, value]` with `name` lowercase.
+     */
+    get headers() {
+        return this._raw.headers;
+    }
+    /**
+     * Pull the next decoded request. Returns `null` on clean EOF.
+     * Throws `nrpc:codec_decode:` on decode failure (the underlying
+     * raw stream is marked closed; subsequent `next()` returns
+     * `null`).
+     */
+    async next() {
+        if (this._done)
+            return null;
+        let buf;
+        try {
+            buf = await this._raw.next();
+        }
+        catch (e) {
+            this._done = true;
+            throw e;
+        }
+        if (buf === null || buf === undefined) {
+            this._done = true;
+            return null;
+        }
+        try {
+            return jsonDecode(buf);
+        }
+        catch (e) {
+            // Mark done so subsequent next() returns null — refuse to
+            // continue draining a stream whose framing is broken.
+            this._done = true;
+            throw e;
+        }
+    }
+    /** Async iterator support: `for await (const req of stream) { ... }`. */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const value = await this.next();
+            if (value === null)
+                return;
+            yield value;
+        }
+    }
+}
+exports.TypedRequestStream = TypedRequestStream;
+// ============================================================================
+// TypedDuplexCall + TypedDuplexSink + TypedDuplexStream +
+// TypedResponseSink (S2-B2).
+//
+// Duplex: caller pushes Reqs and pulls Resps concurrently on a
+// single call. `intoSplit` separates the halves for the encoder-
+// task / decoder-task pattern where each half lives in its own
+// async task.
+//
+// Cancellation contract (locked decision #2): v1 `.close()`-only,
+// same as client-streaming.
+// ============================================================================
+/**
+ * Constant sentinel returned by the duplex serve-handler shim.
+ * The napi `NodeDuplexRpcHandler` discards the terminal Buffer
+ * (only the Ok/Err outcome matters for duplex), so a stable
+ * empty Buffer is enough.
+ */
+const DUPLEX_TERMINAL_SENTINEL = Buffer.alloc(0);
+/**
+ * Typed duplex call handle. Push typed requests via `send`,
+ * pull typed responses via `next` or `for await`, or call
+ * `intoSplit` to peel off independent sink + stream halves.
+ *
+ * After `intoSplit` returns, this call is "consumed" — calling
+ * `send` / `finishSending` / `next` / `close` on it throws.
+ */
+class TypedDuplexCall {
+    _raw;
+    _done;
+    _detachSignal;
+    /**
+     * `detachSignal` is the cleanup function returned by
+     * `wireAbortSignal`. Run on `close()` (or transferred to one
+     * of the split halves on `intoSplit`) so the AbortSignal
+     * listener doesn't outlive the call.
+     */
+    constructor(rawCall, detachSignal = () => { }) {
+        this._raw = rawCall;
+        this._done = false;
+        this._detachSignal = detachSignal;
+    }
+    /** Underlying raw call for users who want the Buffer-level surface. */
+    get raw() {
+        return this._raw;
+    }
+    /** Encode + push one request chunk. */
+    async send(value) {
+        const buf = jsonEncode(value);
+        await this._raw.send(buf);
+    }
+    /** Close the upload direction (emit REQUEST_END). */
+    async finishSending() {
+        await this._raw.finishSending();
+    }
+    /**
+     * Pull the next decoded response. Returns `null` on clean EOF.
+     * Decode failure throws `nrpc:codec_decode:` and closes the
+     * underlying duplex call — subsequent `next()` returns `null`.
+     */
+    async next() {
+        if (this._done)
+            return null;
+        let buf;
+        try {
+            buf = await this._raw.next();
+        }
+        catch (e) {
+            this._done = true;
+            throw e;
+        }
+        if (buf === null || buf === undefined) {
+            this._done = true;
+            return null;
+        }
+        try {
+            return jsonDecode(buf);
+        }
+        catch (e) {
+            this._done = true;
+            try {
+                await this._raw.close();
+            }
+            catch {
+                /* swallow — best-effort */
+            }
+            throw e;
+        }
+    }
+    /** Async iterator support over the response stream. */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const value = await this.next();
+            if (value === null)
+                return;
+            yield value;
+        }
+    }
+    /**
+     * Split the duplex into independent typed sink + stream halves.
+     * After return, this `TypedDuplexCall` is consumed — subsequent
+     * `send` / `finishSending` / `next` throw `stream_closed`.
+     * CANCEL fires only when BOTH split halves drop without
+     * observing the response stream's terminal frame.
+     *
+     * The AbortSignal listener (if one was wired) transfers to the
+     * sink half — the sink is the half that issues the upload,
+     * which is typically dropped first. Wherever the listener
+     * ends up, it stays attached until that half's `close()` runs;
+     * the stream half can still observe cancel-mid-flight via the
+     * substrate's cancel-token primitive even if the sink half's
+     * listener has already detached.
+     */
+    async intoSplit() {
+        const [rawSink, rawStream] = await this._raw.intoSplit();
+        this._done = true;
+        return [
+            new TypedDuplexSink(rawSink, this._detachSignal),
+            new TypedDuplexStream(rawStream),
+        ];
+    }
+    /** Server-assigned `call_id`. */
+    async callId() {
+        return await this._raw.callId();
+    }
+    /**
+     * `true` if the call was opened with non-`None`
+     * `requestWindowInitial`. Reports the UPLOAD-direction
+     * flow-control state.
+     */
+    async flowControlled() {
+        return await this._raw.flowControlled();
+    }
+    /**
+     * Close without observing the response terminator. Fires
+     * CANCEL on the wire. Idempotent. Concurrent in-flight
+     * `send()` awaiting credit observes `stream_closed`.
+     *
+     * Detaches the `AbortSignal` listener (if one was wired by
+     * `TypedMeshRpc.callDuplex(opts.signal)`) so the signal can
+     * be reused for a subsequent call.
+     */
+    async close() {
+        this._done = true;
+        this._detachSignal();
+        try {
+            await this._raw.close();
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    }
+}
+exports.TypedDuplexCall = TypedDuplexCall;
+/** Send-half of a typed duplex call after `intoSplit`. */
+class TypedDuplexSink {
+    _raw;
+    _detachSignal;
+    constructor(rawSink, detachSignal = () => { }) {
+        this._raw = rawSink;
+        this._detachSignal = detachSignal;
+    }
+    /** Underlying raw sink for Buffer-level access. */
+    get raw() {
+        return this._raw;
+    }
+    /** Encode + push one request chunk. */
+    async send(value) {
+        const buf = jsonEncode(value);
+        await this._raw.send(buf);
+    }
+    /** Close the upload direction (emit REQUEST_END). */
+    async finish() {
+        await this._raw.finish();
+    }
+    /** Server-assigned `call_id`. */
+    async callId() {
+        return await this._raw.callId();
+    }
+    /** `true` if the call was opened with `requestWindowInitial`. */
+    async flowControlled() {
+        return await this._raw.flowControlled();
+    }
+    /**
+     * Close without emitting REQUEST_END. Idempotent. Concurrent
+     * in-flight `send()` awaiting credit observes `stream_closed`.
+     *
+     * Detaches the AbortSignal listener (if one was transferred from
+     * the parent `TypedDuplexCall` via `intoSplit`).
+     */
+    async close() {
+        this._detachSignal();
+        try {
+            await this._raw.close();
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    }
+}
+exports.TypedDuplexSink = TypedDuplexSink;
+/** Receive-half of a typed duplex call after `intoSplit`. */
+class TypedDuplexStream {
+    _raw;
+    _done;
+    constructor(rawStream) {
+        this._raw = rawStream;
+        this._done = false;
+    }
+    /** Underlying raw stream for Buffer-level access. */
+    get raw() {
+        return this._raw;
+    }
+    /**
+     * Pull the next decoded response. Returns `null` on clean EOF.
+     * Decode failure throws `nrpc:codec_decode:` and closes the
+     * underlying stream.
+     */
+    async next() {
+        if (this._done)
+            return null;
+        let buf;
+        try {
+            buf = await this._raw.next();
+        }
+        catch (e) {
+            this._done = true;
+            throw e;
+        }
+        if (buf === null || buf === undefined) {
+            this._done = true;
+            return null;
+        }
+        try {
+            return jsonDecode(buf);
+        }
+        catch (e) {
+            this._done = true;
+            try {
+                await this._raw.close();
+            }
+            catch {
+                /* swallow — best-effort */
+            }
+            throw e;
+        }
+    }
+    /** Async iterator support over the response stream. */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const value = await this.next();
+            if (value === null)
+                return;
+            yield value;
+        }
+    }
+    /** Server-assigned `call_id`. */
+    async callId() {
+        return await this._raw.callId();
+    }
+    /** Close the stream. Idempotent. */
+    async close() {
+        this._done = true;
+        try {
+            await this._raw.close();
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    }
+}
+exports.TypedDuplexStream = TypedDuplexStream;
+/**
+ * Typed outbound response sink for duplex server handlers.
+ * Non-async — mirrors `RawResponseSink.send`. Returns `true`
+ * when the chunk was enqueued; `false` if the underlying sink
+ * is closed. Encode failure throws `nrpc:codec_encode:` and the
+ * chunk is NOT sent.
+ *
+ * Flow control: the underlying sink `try_send`s into a bounded
+ * 1024-chunk mpsc; bursts past the credit window are dropped
+ * (counted by `streaming_chunks_dropped_total`). Pace your
+ * `send` calls via REQUEST_GRANT cadence for lossless flow
+ * control.
+ */
+class TypedResponseSink {
+    _raw;
+    constructor(rawSink) {
+        this._raw = rawSink;
+    }
+    /** Underlying raw sink for Buffer-level access. */
+    get raw() {
+        return this._raw;
+    }
+    /**
+     * Encode + emit one response chunk. Returns `true` on
+     * successful enqueue; `false` if the sink has been closed.
+     * Throws `nrpc:codec_encode:` on encoding failure.
+     */
+    send(value) {
+        const buf = jsonEncode(value);
+        return this._raw.send(buf);
+    }
+}
+exports.TypedResponseSink = TypedResponseSink;
+// ============================================================================
 // RetryPolicy — mirrors net_sdk::mesh_rpc_resilience::RetryPolicy.
 //
 // Defaults: 3 attempts, 50ms initial backoff, doubling per
@@ -783,3 +1422,38 @@ function appError(code, body) {
 exports.NRPC_TYPED_BAD_REQUEST = 0x8000;
 /** RpcStatus::Application(0x8001): typed handler returned `throw`. */
 exports.NRPC_TYPED_HANDLER_ERROR = 0x8001;
+/**
+ * Convert the napi POD shape (`RawRpcCallEvent` with flat
+ * `statusKind` / `statusMessage` fields) into the TS-idiomatic
+ * tagged `RpcCallEvent`. Exported for tests that need to
+ * synthesize observer events; production code receives already-
+ * decoded events via `TypedMeshRpc.setObserver`.
+ */
+function rawEventToTyped(raw) {
+    let status;
+    switch (raw.statusKind) {
+        case exports.STATUS_KIND_OK:
+            status = { kind: 'ok' };
+            break;
+        case exports.STATUS_KIND_ERROR:
+            status = { kind: 'error', message: raw.statusMessage ?? '' };
+            break;
+        case exports.STATUS_KIND_TIMEOUT:
+            status = { kind: 'timeout' };
+            break;
+        case exports.STATUS_KIND_CANCELED:
+            status = { kind: 'canceled' };
+            break;
+    }
+    return {
+        caller: raw.caller,
+        callee: raw.callee,
+        method: raw.method,
+        latencyMs: raw.latencyMs,
+        status,
+        requestBytes: raw.requestBytes,
+        responseBytes: raw.responseBytes,
+        direction: raw.direction,
+        tsUnixMs: raw.tsUnixMs,
+    };
+}