@net-mesh/core 0.19.0

package/mesh_rpc.js

@@ -0,0 +1,780 @@
+"use strict";
+// Typed nRPC wrappers + retry / hedge / circuit-breaker helpers.
+//
+// Sits on top of the raw napi `MeshRpc` class (in index.js):
+// translates typed JS objects to/from JSON-encoded Buffers,
+// re-throws errors as typed `RpcError` subclasses, and provides
+// pure-JS implementations of the resilience policies that mirror
+// the Rust SDK's defaults.
+//
+// Usage:
+//   import { NetMesh } from '@net-mesh/core'
+//   import { TypedMeshRpc, RetryPolicy } from '@net-mesh/core/mesh_rpc'
+//
+//   const mesh = await NetMesh.create({ ... })
+//   const rpc = TypedMeshRpc.fromMesh(mesh)
+//
+//   const handle = rpc.serve('echo', async (req) => req)
+//   const reply = await rpc.call(targetId, 'echo', { hello: 'world' })
+//
+//   // With retry:
+//   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.defaultRetryable = defaultRetryable;
+exports.defaultBreakerFailure = defaultBreakerFailure;
+exports.appError = appError;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const native = require('./index');
+// Duck-typed message extractor — keeps the "any rejected value
+// with a string `message`" contract uniform across the two
+// modules. The TS source compiles this `import` to a `require`
+// of the sibling `./errors.js`, which `prepublishOnly` emits
+// alongside `mesh_rpc.js`.
+const errors_1 = require("./errors");
+// ============================================================================
+// JSON codec.
+//
+// Default codec for typed wrappers. Matches the Rust SDK's
+// Codec::Json. Encode failure (e.g. circular reference, BigInt
+// in unsupported position) → throw RpcCodecError(direction='encode')
+// BEFORE the call hits the wire. Decode failure on the reply
+// surfaces as RpcCodecError(direction='decode').
+// ============================================================================
+const utf8 = new TextEncoder();
+const utf8d = new TextDecoder('utf-8', { fatal: true });
+function jsonEncode(value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch (e) {
+        throw new Error(`nrpc:codec_encode: ${(0, errors_1.extractMessage)(e) || String(e)}`);
+    }
+    if (json === undefined) {
+        // JSON.stringify(undefined) === undefined. nRPC expects bytes.
+        throw new Error('nrpc:codec_encode: top-level undefined cannot be serialized');
+    }
+    return Buffer.from(utf8.encode(json));
+}
+function jsonDecode(buf) {
+    try {
+        return JSON.parse(utf8d.decode(buf));
+    }
+    catch (e) {
+        throw new Error(`nrpc:codec_decode: ${(0, errors_1.extractMessage)(e) || String(e)}`);
+    }
+}
+class TypedMeshRpc {
+    _raw;
+    /**
+     * Build a TypedMeshRpc against a NetMesh. Cheap; returns a
+     * new wrapper around an internal raw MeshRpc.
+     */
+    static fromMesh(mesh) {
+        return new TypedMeshRpc(native.MeshRpc.fromMesh(mesh));
+    }
+    /**
+     * Build a TypedMeshRpc from an already-constructed raw MeshRpc.
+     * Useful if you need the raw + typed surface side by side.
+     */
+    constructor(rawMeshRpc) {
+        this._raw = rawMeshRpc;
+    }
+    /** Underlying raw `MeshRpc` for users who want the Buffer-level surface. */
+    get raw() {
+        return this._raw;
+    }
+    /**
+     * Register a typed handler. The handler receives a decoded
+     * `Req` and returns a `Resp` (or a Promise of one). JSON
+     * encode/decode happens at the binding boundary; encode
+     * failure inside the handler surfaces to the caller as
+     * `RpcServerError(status=0x0006 Internal)`.
+     */
+    serve(service, handler) {
+        return this._raw.serve(service, async (reqBuf) => {
+            // Decode failures on the request surface to the caller as
+            // a canonical typed-bad-request: the Rust binding maps any
+            // promise rejection whose message starts with
+            // `nrpc:app_error:0x<code>:<body>` to
+            // RpcHandlerError::Application { code, message: body },
+            // which the fold emits as RpcStatus::Application(code).
+            // Status 0x8000 == NRPC_TYPED_BAD_REQUEST per the cross-
+            // binding contract pinned in
+            // `tests/cross_lang_nrpc/golden_vectors.json`.
+            let req;
+            try {
+                req = jsonDecode(reqBuf);
+            }
+            catch (e) {
+                const body = JSON.stringify({
+                    error: 'invalid_request',
+                    detail: (0, errors_1.extractMessage)(e) || String(e),
+                });
+                throw appError(0x8000, body);
+            }
+            const resp = await handler(req);
+            return jsonEncode(resp);
+        });
+    }
+    /**
+     * Direct-addressed typed call. Encodes `req` as JSON, calls,
+     * decodes the response. Throws an `RpcError` subclass on
+     * failure (matched by the napi prefix → JS class mapping in
+     * `errors.js`).
+     *
+     * Pass `opts.signal` (AbortSignal) for caller-driven
+     * cancellation. The wrapper mints a cancel token via the raw
+     * binding's `reserveCancelToken()`, attaches an abort listener,
+     * and lets the abort fire `cancelCall(token)` to drop the in-
+     * flight call (CANCEL fires on the wire, the call rejects with
+     * `nrpc:cancelled:`).
+     */
+    async call(targetNodeId, service, req, opts) {
+        const reqBuf = jsonEncode(req);
+        const { rawOpts, detach } = wireAbortSignal(this._raw, opts);
+        try {
+            const respBuf = await this._raw.call(targetNodeId, service, reqBuf, rawOpts);
+            return jsonDecode(respBuf);
+        }
+        finally {
+            detach();
+        }
+    }
+    /**
+     * Service-discovery typed call. Resolves `service` against the
+     * local capability index, picks a target per the routing
+     * policy, calls. Throws an `RpcError` subclass on failure.
+     */
+    async callService(service, req, opts) {
+        const reqBuf = jsonEncode(req);
+        const { rawOpts, detach } = wireAbortSignal(this._raw, opts);
+        try {
+            const respBuf = await this._raw.callService(service, reqBuf, rawOpts);
+            return jsonDecode(respBuf);
+        }
+        finally {
+            detach();
+        }
+    }
+    /**
+     * Open a typed streaming call. Returns a `TypedRpcStream` that
+     * yields decoded `Resp` values per `next()` until EOF.
+     */
+    async callStreaming(targetNodeId, service, req, opts) {
+        const reqBuf = jsonEncode(req);
+        const inner = await this._raw.callStreaming(targetNodeId, service, reqBuf, opts);
+        return new TypedRpcStream(inner);
+    }
+    /** Pass-through to `MeshRpc.findServiceNodes`. */
+    findServiceNodes(service) {
+        return this._raw.findServiceNodes(service);
+    }
+    // ---- resilience helpers --------------------------------------------------
+    /**
+     * Direct-addressed typed call with retry. See {@link RetryPolicy}.
+     */
+    async callWithRetry(targetNodeId, service, req, opts, policy) {
+        // Encode once and reuse across attempts (matches the Rust
+        // SDK's call_typed_with_retry contract).
+        const reqBuf = jsonEncode(req);
+        const respBuf = await runRetry(policy, async () => {
+            return await this._raw.call(targetNodeId, service, reqBuf, opts);
+        });
+        return jsonDecode(respBuf);
+    }
+    /**
+     * Hedge typed call across the listed targets. First reply
+     * (Ok or Err) wins; if every target fails, the surfaced error
+     * is the primary's (target index 0) for stable diagnostics.
+     */
+    async callWithHedgeTo(targets, service, req, opts, policy) {
+        const reqBuf = jsonEncode(req);
+        const respBuf = await runHedge(policy, targets, async (targetId) => {
+            return await this._raw.call(targetId, service, reqBuf, opts);
+        });
+        return jsonDecode(respBuf);
+    }
+}
+exports.TypedMeshRpc = TypedMeshRpc;
+// ============================================================================
+// TypedRpcStream — typed wrapper around the raw RpcStream.
+// ============================================================================
+class TypedRpcStream {
+    _raw;
+    _done;
+    constructor(rawRpcStream) {
+        this._raw = rawRpcStream;
+        this._done = false;
+    }
+    /**
+     * Pull the next decoded value. Returns `null` on clean EOF.
+     * Throws `RpcCodecError(direction='decode')` if a chunk fails
+     * to decode (terminates the stream — the underlying CANCEL is
+     * fired by the raw RpcStream's drop).
+     */
+    async next() {
+        if (this._done)
+            return null;
+        let buf;
+        try {
+            buf = await this._raw.next();
+        }
+        catch (e) {
+            this._done = true;
+            throw e; // user catch site classifies via classifyError
+        }
+        if (buf === null || buf === undefined) {
+            this._done = true;
+            return null;
+        }
+        try {
+            return jsonDecode(buf);
+        }
+        catch (e) {
+            this._done = true;
+            // Close the underlying stream so the server's handler
+            // observes CANCEL — no point keeping a stream open whose
+            // subsequent chunks we can't decode.
+            try {
+                await this._raw.close();
+            }
+            catch {
+                /* swallow — best-effort */
+            }
+            throw e;
+        }
+    }
+    /** Async iterator support: `for await (const chunk of stream) { ... }`. */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const value = await this.next();
+            if (value === null)
+                return;
+            yield value;
+        }
+    }
+    /** Grant `n` flow-control credits to the server pump. */
+    async grant(n) {
+        await this._raw.grant(n);
+    }
+    /** `true` if the call set `streamWindowInitial`. */
+    async flowControlled() {
+        return await this._raw.flowControlled();
+    }
+    /** Close the stream; emits CANCEL to the server. Idempotent. */
+    async close() {
+        this._done = true;
+        try {
+            await this._raw.close();
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    }
+}
+exports.TypedRpcStream = TypedRpcStream;
+// ============================================================================
+// RetryPolicy — mirrors net_sdk::mesh_rpc_resilience::RetryPolicy.
+//
+// Defaults: 3 attempts, 50ms initial backoff, doubling per
+// attempt, capped at 1s, full-half jitter on. The retryable
+// predicate skips RpcCodecError + RpcNoRouteError + non-transient
+// RpcServerError statuses (matches Rust's default_retryable).
+// ============================================================================
+const DEFAULT_RETRY = Object.freeze({
+    maxAttempts: 3,
+    initialBackoffMs: 50,
+    maxBackoffMs: 1000,
+    backoffMultiplier: 2.0,
+    jitter: true,
+});
+// Wire-level RpcStatus codes the default predicate considers
+// transient (server-observed). Matches the Rust SDK's default_retryable.
+const STATUS_INTERNAL = 0x0006;
+const STATUS_BACKPRESSURE = 0x0004;
+const STATUS_TIMEOUT = 0x0003;
+function defaultRetryable(err) {
+    // Per Rust SDK: NoRoute + Codec are caller-fixable / terminal
+    // and never retried. Timeout (caller-side) and Transport
+    // always retry. ServerError retries only for canonical
+    // transient statuses.
+    //
+    // Detection strategy: try `err.name` first (a runtime string,
+    // dual-module-safe), then fall back to message-prefix matching
+    // for raw napi errors that haven't been classified yet.
+    // String / null / undefined rejections short-circuit to "not
+    // retryable" — the predicate only fires for object-shaped errors.
+    if (err === null || err === undefined || typeof err !== 'object') {
+        return false;
+    }
+    const errAny = err;
+    const name = errAny.name ?? '';
+    switch (name) {
+        case 'RpcNoRouteError':
+        case 'RpcCodecError':
+        case 'RpcCancelledError':
+            // Cancellation is caller-driven — retrying defeats the
+            // point. Pinned by `RpcCancelledError`'s class docstring;
+            // pre-TS-migration the predicate fell through to the
+            // generic `nrpc:` "retry by default" branch and silently
+            // re-issued cancelled calls.
+            return false;
+        case 'RpcTimeoutError':
+        case 'RpcTransportError':
+            return true;
+        case 'RpcServerError': {
+            // Prefer err.status (set by RpcServerError constructor);
+            // fall back to parsing the message.
+            const status = typeof errAny.status === 'number'
+                ? errAny.status
+                : parseStatusFromMessage((0, errors_1.extractMessage)(err));
+            return (status === STATUS_INTERNAL ||
+                status === STATUS_BACKPRESSURE ||
+                status === STATUS_TIMEOUT);
+        }
+    }
+    // Fall back to message prefix. Use the same duck-typed
+    // extractor as classifyError so plain-object rejections with a
+    // `message` field classify the same way real Errors do.
+    const msg = (0, errors_1.extractMessage)(err);
+    if (!msg.startsWith('nrpc:'))
+        return false;
+    if (msg.startsWith('nrpc:no_route:'))
+        return false;
+    if (msg.startsWith('nrpc:codec_'))
+        return false;
+    if (msg.startsWith('nrpc:cancelled:'))
+        return false;
+    if (msg.startsWith('nrpc:server_error:')) {
+        const status = parseStatusFromMessage(msg);
+        return (status === STATUS_INTERNAL ||
+            status === STATUS_BACKPRESSURE ||
+            status === STATUS_TIMEOUT);
+    }
+    // nrpc:timeout, nrpc:transport, and any future variant → retry.
+    return true;
+}
+function parseStatusFromMessage(msg) {
+    if (!msg)
+        return undefined;
+    const m = /status=0x([0-9a-fA-F]+)/.exec(msg);
+    return m ? parseInt(m[1], 16) : undefined;
+}
+/**
+ * Retry policy. Defaults: 3 attempts, 50ms→1s exponential backoff,
+ * full-half jitter on, retryable predicate matches the Rust SDK's
+ * `default_retryable` (skips RpcCodecError, RpcNoRouteError, and
+ * non-transient ServerError statuses).
+ */
+class RetryPolicy {
+    maxAttempts;
+    initialBackoffMs;
+    maxBackoffMs;
+    backoffMultiplier;
+    jitter;
+    retryable;
+    constructor(opts) {
+        const merged = { ...DEFAULT_RETRY, ...(opts ?? {}) };
+        this.maxAttempts = Math.max(1, merged.maxAttempts | 0);
+        this.initialBackoffMs = Math.max(0, merged.initialBackoffMs);
+        this.maxBackoffMs = Math.max(this.initialBackoffMs, merged.maxBackoffMs);
+        this.backoffMultiplier = Math.max(1.0, merged.backoffMultiplier);
+        this.jitter = !!merged.jitter;
+        const retryable = (opts?.retryable ?? defaultRetryable);
+        if (typeof retryable !== 'function') {
+            throw new TypeError('RetryPolicy.retryable must be a function (received ' +
+                typeof retryable +
+                ')');
+        }
+        this.retryable = retryable;
+    }
+    /**
+     * Compute the backoff for `attempt` (1-indexed). Caps at
+     * `maxBackoffMs` AFTER jitter so the cap is a true ceiling.
+     */
+    computeBackoffMs(attempt) {
+        const exp = Math.max(0, attempt - 1);
+        const scaled = this.initialBackoffMs * Math.pow(this.backoffMultiplier, exp);
+        const preCap = Math.min(this.maxBackoffMs, scaled);
+        const jittered = this.jitter ? preCap * (0.5 + 0.5 * Math.random()) : preCap;
+        return Math.min(this.maxBackoffMs, jittered);
+    }
+}
+exports.RetryPolicy = RetryPolicy;
+async function runRetry(policy, op) {
+    let lastErr;
+    for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+        try {
+            return await op();
+        }
+        catch (e) {
+            lastErr = e;
+            if (attempt === policy.maxAttempts || !policy.retryable(e)) {
+                throw e;
+            }
+            const ms = policy.computeBackoffMs(attempt);
+            if (ms > 0)
+                await sleep(ms);
+        }
+    }
+    // Unreachable under normal control flow (the loop returns or
+    // throws), but TS's exhaustiveness requires an explicit throw.
+    throw lastErr;
+}
+// ============================================================================
+// HedgePolicy — mirrors net_sdk::mesh_rpc_resilience::HedgePolicy.
+//
+// Fire-then-race: primary at t=0, additional hedges at
+// t = delay * idx. First reply (Ok or Err) wins; if every hedge
+// fails, surfaces the PRIMARY's error deterministically (matches
+// the Rust SDK's M19 fix).
+// ============================================================================
+const DEFAULT_HEDGE = Object.freeze({
+    delayMs: 50,
+    hedges: 1,
+});
+/**
+ * Hedge policy. Fire-then-race: primary at t=0, hedges at
+ * t = delayMs * idx. First reply wins; if every hedge fails,
+ * the primary's error is surfaced deterministically.
+ */
+class HedgePolicy {
+    delayMs;
+    hedges;
+    constructor(opts) {
+        const merged = { ...DEFAULT_HEDGE, ...(opts ?? {}) };
+        this.delayMs = Math.max(0, merged.delayMs);
+        this.hedges = Math.max(0, merged.hedges | 0);
+    }
+}
+exports.HedgePolicy = HedgePolicy;
+async function runHedge(policy, targets, op) {
+    if (!Array.isArray(targets) || targets.length === 0) {
+        // Plain Error with the stable prefix; user's catch site
+        // calls classifyError() to get a typed RpcNoRouteError.
+        throw new Error('nrpc:no_route: hedge: empty targets list');
+    }
+    // Hedges = 0 → degrade to a straight call against targets[0].
+    if (policy.hedges === 0 || targets.length === 1) {
+        return await op(targets[0]);
+    }
+    // Cap hedges to the available targets (primary + N-1 hedges).
+    const fanout = Math.min(targets.length, 1 + policy.hedges);
+    const errors = new Array(fanout).fill(undefined);
+    let resolved = false;
+    let firstOk = null;
+    let okIndex = -1;
+    // Each launch is a Promise that either:
+    //  - resolves with { ok: true, value } if op succeeds AND we're first
+    //  - resolves with { idx, err } if op fails
+    //  - never resolves if a previous launch already won
+    const launches = [];
+    for (let i = 0; i < fanout; i++) {
+        const idx = i;
+        launches.push((async () => {
+            if (idx > 0)
+                await sleep(policy.delayMs * idx);
+            if (resolved)
+                return { idx, err: null, skipped: true };
+            try {
+                const value = await op(targets[idx]);
+                if (!resolved) {
+                    resolved = true;
+                    firstOk = value;
+                    okIndex = idx;
+                }
+                return { idx, err: null, value };
+            }
+            catch (e) {
+                errors[idx] = e;
+                return { idx, err: e };
+            }
+        })());
+    }
+    await Promise.all(launches);
+    if (okIndex >= 0)
+        return firstOk;
+    // All failed — surface the primary's error (or the lowest-
+    // indexed defined error). Deterministic across runs.
+    for (let i = 0; i < errors.length; i++) {
+        if (errors[i] !== undefined)
+            throw errors[i];
+    }
+    // Shouldn't reach here, but defend against a fanout = 0 edge
+    // case that slipped past the cap above.
+    throw new Error('nrpc:hedge: drained with no error captured (bug)');
+}
+const STATE_CLOSED = 'closed';
+const STATE_OPEN = 'open';
+const STATE_HALF_OPEN = 'half-open';
+const DEFAULT_BREAKER = Object.freeze({
+    failureThreshold: 5,
+    resetAfterMs: 30_000,
+    successThreshold: 1,
+});
+function defaultBreakerFailure(err) {
+    // Mirror default_retryable — same set of "transient infra
+    // failures" counts toward tripping; codec / no-route / app
+    // errors don't.
+    return defaultRetryable(err);
+}
+// BreakerOpenError extends `Error` (not RpcError) so its identity
+// is local to this module — the test imports BreakerOpenError
+// from this same file, so `instanceof` works. Users who catch
+// "any RPC failure" with `instanceof RpcError` should also catch
+// `instanceof BreakerOpenError` separately when using the
+// breaker. The `nrpc:breaker_open:` message prefix lets
+// `classifyError` route this through the generic `RpcError` base
+// for users who want a unified catch.
+class BreakerOpenError extends Error {
+    constructor() {
+        super('nrpc:breaker_open: circuit breaker is open');
+        this.name = 'BreakerOpenError';
+        Object.setPrototypeOf(this, BreakerOpenError.prototype);
+    }
+}
+exports.BreakerOpenError = BreakerOpenError;
+/**
+ * Three-state circuit breaker. Long-lived; instantiate once per
+ * logical downstream and share. `breaker.call(() => ...)`
+ * composes around any async op.
+ */
+class CircuitBreaker {
+    failureThreshold;
+    resetAfterMs;
+    successThreshold;
+    failurePredicate;
+    _state;
+    _consecutiveFailures;
+    _consecutiveSuccesses;
+    _openedAt;
+    _probeInFlight;
+    constructor(opts) {
+        const merged = { ...DEFAULT_BREAKER, ...(opts ?? {}) };
+        this.failureThreshold = Math.max(1, merged.failureThreshold | 0);
+        this.resetAfterMs = Math.max(0, merged.resetAfterMs);
+        this.successThreshold = Math.max(1, merged.successThreshold | 0);
+        const predicate = (opts?.failurePredicate ??
+            defaultBreakerFailure);
+        if (typeof predicate !== 'function') {
+            throw new TypeError('CircuitBreaker.failurePredicate must be a function (received ' +
+                typeof predicate +
+                ')');
+        }
+        this.failurePredicate = predicate;
+        this._state = STATE_CLOSED;
+        this._consecutiveFailures = 0;
+        this._consecutiveSuccesses = 0;
+        this._openedAt = 0;
+        this._probeInFlight = false;
+    }
+    state() {
+        // Lazy "Open → HalfOpen on cooldown elapsed" transition: we
+        // probe at admission time, not on a background timer.
+        return this._state;
+    }
+    consecutiveFailures() {
+        return this._consecutiveFailures;
+    }
+    reset() {
+        this._state = STATE_CLOSED;
+        this._consecutiveFailures = 0;
+        this._consecutiveSuccesses = 0;
+        this._openedAt = 0;
+        this._probeInFlight = false;
+    }
+    /**
+     * Wrap an async op. Returns its value on success, throws on
+     * failure (or on rejection). When the breaker is `Open` within
+     * its cooldown, throws `BreakerOpenError` without invoking
+     * `op`.
+     *
+     * Both success and failure paths record the outcome through
+     * `_recordOutcome`, which is responsible for clearing
+     * `_probeInFlight` on the half-open-probe admission. A
+     * synchronous throw inside `op` (rare — `await` is always at
+     * `op`'s call site) is still routed through the catch arm.
+     */
+    async call(op) {
+        const admission = this._tryAdmit();
+        if (admission === 'reject') {
+            throw new BreakerOpenError();
+        }
+        try {
+            const value = await op();
+            this._recordOutcome(admission, true, undefined);
+            return value;
+        }
+        catch (e) {
+            this._recordOutcome(admission, false, e);
+            throw e;
+        }
+    }
+    _tryAdmit() {
+        if (this._state === STATE_CLOSED)
+            return 'closed';
+        if (this._state === STATE_OPEN) {
+            const elapsed = Date.now() - this._openedAt;
+            if (elapsed >= this.resetAfterMs) {
+                this._state = STATE_HALF_OPEN;
+                this._consecutiveSuccesses = 0;
+                this._probeInFlight = true;
+                return 'half-open-probe';
+            }
+            return 'reject';
+        }
+        // HalfOpen — at most one probe at a time.
+        if (this._probeInFlight)
+            return 'reject';
+        this._probeInFlight = true;
+        return 'half-open-probe';
+    }
+    _recordOutcome(admission, ok, err) {
+        if (admission === 'closed') {
+            if (ok) {
+                this._consecutiveFailures = 0;
+            }
+            else if (this.failurePredicate(err)) {
+                this._consecutiveFailures += 1;
+                if (this._consecutiveFailures >= this.failureThreshold) {
+                    this._state = STATE_OPEN;
+                    this._openedAt = Date.now();
+                    this._consecutiveSuccesses = 0;
+                }
+            }
+            return;
+        }
+        // half-open-probe
+        this._probeInFlight = false;
+        if (ok) {
+            this._consecutiveSuccesses += 1;
+            if (this._consecutiveSuccesses >= this.successThreshold) {
+                this._state = STATE_CLOSED;
+                this._consecutiveFailures = 0;
+                this._consecutiveSuccesses = 0;
+                this._openedAt = 0;
+            }
+        }
+        else if (this.failurePredicate(err)) {
+            // Failed probe → re-open with fresh cooldown.
+            this._state = STATE_OPEN;
+            this._openedAt = Date.now();
+            this._consecutiveFailures = 0;
+            this._consecutiveSuccesses = 0;
+        }
+        // Predicate said "not a failure" (e.g. application error) →
+        // leave state HalfOpen for the next probe.
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+// ============================================================================
+// Helpers.
+// ============================================================================
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Wire an AbortSignal (`opts.signal`) into the raw napi cancel
+ * surface. Returns `{ rawOpts, detach }`:
+ *
+ *   - `rawOpts` is the option object to pass to the raw call,
+ *     with `cancelToken` populated when a signal was provided
+ *     (the raw napi side does not understand `signal`).
+ *   - `detach` MUST be called from a `finally` block on the call
+ *     site to remove the abort listener regardless of
+ *     success/failure path. Idempotent.
+ *
+ * If no signal is provided (or the signal is already aborted),
+ * the wrapper either short-circuits or returns the rawOpts
+ * unchanged so the non-cancellable fast path stays free of
+ * tokio-spawn / registry overhead.
+ */
+function wireAbortSignal(raw, opts) {
+    if (!opts || !opts.signal) {
+        return { rawOpts: opts, detach: () => { } };
+    }
+    const signal = opts.signal;
+    // If the signal is already aborted, fail fast — don't even
+    // start the call.
+    if (signal.aborted) {
+        throw new Error('nrpc:cancelled: AbortSignal already aborted');
+    }
+    // Mint a token, copy opts (drop `signal` since the napi side
+    // doesn't know it), attach a listener that calls cancelCall on
+    // abort. The listener removes itself on detach so the AbortSignal
+    // can be reused for a subsequent call without leaking handlers.
+    const token = raw.reserveCancelToken();
+    const rawOpts = { ...opts, cancelToken: token };
+    delete rawOpts.signal;
+    let detached = false;
+    const onAbort = () => {
+        if (detached)
+            return;
+        try {
+            raw.cancelCall(token);
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    return {
+        rawOpts,
+        detach: () => {
+            if (detached)
+                return;
+            detached = true;
+            signal.removeEventListener('abort', onAbort);
+        },
+    };
+}
+/**
+ * Build an Error a typed serve handler can throw to surface a
+ * specific application status code to the caller. The Rust
+ * binding parses messages of the form
+ * `nrpc:app_error:0x<code>:<body>` and maps them to
+ * `RpcStatus::Application(code)` — without this prefix the
+ * thrown error becomes a generic `RpcStatus::Internal`. Mirrors
+ * the Python binding's `RpcAppError(code, body)`.
+ *
+ * Use cases: typed handlers that want to return 4xx-style
+ * application errors (`NRPC_TYPED_BAD_REQUEST`,
+ * `NRPC_TYPED_HANDLER_ERROR`, custom app codes >= 0x8000).
+ *
+ * @example
+ *   rpc.serve('echo', (req) => {
+ *     if (typeof req.text !== 'string') {
+ *       throw appError(NRPC_TYPED_BAD_REQUEST,
+ *                      JSON.stringify({error: 'missing text'}))
+ *     }
+ *     return { echo: req.text }
+ *   })
+ */
+function appError(code, body) {
+    if (typeof code !== 'number' || code < 0 || code > 0xffff) {
+        throw new TypeError(`appError: code must be a 0..=0xFFFF integer (got ${code})`);
+    }
+    let bodyStr;
+    if (typeof body === 'string') {
+        bodyStr = body;
+    }
+    else if (Buffer.isBuffer(body)) {
+        bodyStr = body.toString('utf8');
+    }
+    else {
+        bodyStr = String(body ?? '');
+    }
+    // The Rust parser splits on the FIRST colon after `0x<hex>:`,
+    // so the body itself can contain colons safely.
+    const codeHex = code.toString(16).padStart(4, '0');
+    return new Error(`nrpc:app_error:0x${codeHex}:${bodyStr}`);
+}
+// Status code constants (parallel to NRPC_TYPED_BAD_REQUEST /
+// NRPC_TYPED_HANDLER_ERROR in the Rust SDK).
+/** RpcStatus::Application(0x8000): typed handler bad-request body. */
+exports.NRPC_TYPED_BAD_REQUEST = 0x8000;
+/** RpcStatus::Application(0x8001): typed handler returned `throw`. */
+exports.NRPC_TYPED_HANDLER_ERROR = 0x8001;