@nats-kit/rpc 0.3.0

package/dist/commonjs/kv.d.ts

@@ -0,0 +1,13 @@
+import { type z } from "zod";
+/** A typed KV value contract (§2.5, §4.9). No envelope; a breaking shape change means a new bucket. */
+export interface KvValueContract<T extends z.ZodType> {
+    bucket: string;
+    value: T;
+    /** Builds a validated, dot-joined key from parts; each part must be `[a-zA-Z0-9_-]+`. */
+    key(...parts: string[]): string;
+}
+export declare function defineKvValue<T extends z.ZodType>(def: {
+    bucket: string;
+    value: T;
+}): KvValueContract<T>;
+//# sourceMappingURL=kv.d.ts.map

package/dist/commonjs/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../src/kv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,uGAAuG;AACvG,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,CAAC,CAAC;IACT,yFAAyF;IACzF,GAAG,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;CACjC;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,CAAC,CAAC;CACV,GAAG,eAAe,CAAC,CAAC,CAAC,CAiBrB"}

package/dist/commonjs/kv.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineKvValue = defineKvValue;
+const KV_KEY_PART_RE = /^[a-zA-Z0-9_-]+$/;
+function defineKvValue(def) {
+    return {
+        bucket: def.bucket,
+        value: def.value,
+        key(...parts) {
+            for (const part of parts) {
+                if (!KV_KEY_PART_RE.test(part)) {
+                    throw new Error(`defineKvValue(${def.bucket}): invalid key part "${part}"`);
+                }
+            }
+            const key = parts.join(".");
+            if (key.length === 0 || key.length > 255) {
+                throw new Error(`defineKvValue(${def.bucket}): key length out of bounds`);
+            }
+            return key;
+        },
+    };
+}
+//# sourceMappingURL=kv.js.map

package/dist/commonjs/kv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.js","sourceRoot":"","sources":["../../src/kv.ts"],"names":[],"mappings":";;AAYA,sCAoBC;AA9BD,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAU1C,SAAgB,aAAa,CAAsB,GAGlD;IACC,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,GAAG,CAAC,GAAG,KAAe;YACpB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC/B,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,MAAM,wBAAwB,IAAI,GAAG,CAAC,CAAC;gBAC9E,CAAC;YACH,CAAC;YACD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;gBACzC,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,MAAM,6BAA6B,CAAC,CAAC;YAC5E,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/commonjs/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "commonjs",
+  "sideEffects": false
+}

package/dist/commonjs/server.d.ts

@@ -0,0 +1,45 @@
+import { type ServiceHandler } from "@nats-io/services";
+import { type ServiceContract } from "./contract.js";
+import { type RpcAuthorize, type RpcContext, type RpcHandlers, type RpcResult, type RpcServerHandle, type RpcServerOptions } from "./types.js";
+/** Build a successful `RpcResult`. */
+export declare function ok<T>(result: T): {
+    ok: true;
+    result: T;
+};
+/** Build a domain-error `RpcResult`. */
+export declare function fail<E extends string>(code: E, message: string, details?: unknown): {
+    ok: false;
+    error: {
+        code: E;
+        message: string;
+        details?: unknown;
+    };
+};
+/**
+ * Build the `ServiceHandler` for one contract method — dispatch order fixed
+ * by design §2.4 / wire spec §4.5.
+ *
+ * The library's own synchronous try/catch around `handler(err, msg)` (see
+ * `ServiceImpl.setupHandler`) cannot observe an `async` handler's rejection,
+ * so it never counts our service errors toward `num_errors` — we build every
+ * response (success, domain error, service error) explicitly instead of
+ * throwing, which is what lets a 400/403 carry a JSON `details` body. This is
+ * a documented deviation from `nats micro stats` incrementing on our service
+ * errors; see the package README.
+ *
+ * Exported for unit tests (mock `ServiceMsg` + assert the dispatch order) and
+ * for advanced embedding over a transport other than `@nats-io/services`'
+ * `ServiceHandler`. Not part of the documented public API surface.
+ */
+export declare function buildEndpointHandler<C extends ServiceContract>(contract: C, methodName: string, options: RpcServerOptions<C>, drainSignal: AbortSignal): ServiceHandler;
+/**
+ * Start the reconnect supervisor loop for one contract (design §3).
+ *
+ * `Svcm`-backed `Service` instances permanently stop on connection loss with
+ * no restart path, so this loop rebuilds the service every time it stops
+ * (healthy stop or connection loss) until `signal` aborts.
+ */
+export declare function createRpcServer<C extends ServiceContract>(contract: C, options: RpcServerOptions<C>): RpcServerHandle;
+export declare function newRequestId(): string;
+export type { RpcHandlers, RpcAuthorize, RpcContext, RpcResult, RpcServerHandle, RpcServerOptions };
+//# sourceMappingURL=server.d.ts.map

package/dist/commonjs/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AAQ7F,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAIpB,sCAAsC;AACtC,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAExD;AAED,wCAAwC;AACxC,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EACnC,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,OAAO,GAChB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAEvE;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,eAAe,EAC5D,QAAQ,EAAE,CAAC,EACX,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,WAAW,EAAE,WAAW,GACvB,cAAc,CA0NhB;AAyED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACvD,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC3B,eAAe,CAsHjB;AAID,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/commonjs/server.js

@@ -0,0 +1,433 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ok = ok;
+exports.fail = fail;
+exports.buildEndpointHandler = buildEndpointHandler;
+exports.createRpcServer = createRpcServer;
+exports.newRequestId = newRequestId;
+const services_1 = require("@nats-io/services");
+const nuid_1 = require("@nats-io/nuid");
+const core_1 = require("@nats-kit/core");
+const contract_js_1 = require("./contract.js");
+const errors_js_1 = require("./errors.js");
+const headers_js_1 = require("./headers.js");
+const DEFAULT_REBUILD_DELAY_MS = 1000;
+/** Build a successful `RpcResult`. */
+function ok(result) {
+    return { ok: true, result };
+}
+/** Build a domain-error `RpcResult`. */
+function fail(code, message, details) {
+    return { ok: false, error: { code, message, details } };
+}
+function encodeEnvelope(value) {
+    return new TextEncoder().encode(JSON.stringify(value));
+}
+function jsonResponseHeaders() {
+    const h = (0, core_1.headers)();
+    h.set(headers_js_1.HEADER_CONTENT_TYPE, headers_js_1.CONTENT_TYPE_JSON);
+    return h;
+}
+/**
+ * Build the `ServiceHandler` for one contract method — dispatch order fixed
+ * by design §2.4 / wire spec §4.5.
+ *
+ * The library's own synchronous try/catch around `handler(err, msg)` (see
+ * `ServiceImpl.setupHandler`) cannot observe an `async` handler's rejection,
+ * so it never counts our service errors toward `num_errors` — we build every
+ * response (success, domain error, service error) explicitly instead of
+ * throwing, which is what lets a 400/403 carry a JSON `details` body. This is
+ * a documented deviation from `nats micro stats` incrementing on our service
+ * errors; see the package README.
+ *
+ * Exported for unit tests (mock `ServiceMsg` + assert the dispatch order) and
+ * for advanced embedding over a transport other than `@nats-io/services`'
+ * `ServiceHandler`. Not part of the documented public API surface.
+ */
+function buildEndpointHandler(contract, methodName, options, drainSignal) {
+    const rawMethodDef = contract.methods[methodName];
+    if (!rawMethodDef) {
+        throw new Error(`createRpcServer: contract has no method "${methodName}"`);
+    }
+    const methodDef = rawMethodDef;
+    // The generic `RpcHandlers<C>` mapping is only meaningful at the contract
+    // author's call site; this dispatcher is generic over an arbitrary method
+    // name, so it deals in `unknown` and lets zod re-establish the real types.
+    const handler = options.handlers[methodName];
+    const authorize = options.authorize;
+    const logger = options.logger;
+    const telemetry = options.telemetry ?? core_1.noopTelemetry;
+    const subject = (0, contract_js_1.methodSubject)(contract, methodName);
+    return (err, msg) => {
+        if (err)
+            return; // subscription-level error: the library is already closing the service.
+        void dispatch(msg).catch((dispatchErr) => {
+            logger?.error({ err: dispatchErr, subject }, "RPC dispatch crashed unexpectedly");
+            try {
+                msg.respondError(500, "internal error");
+            }
+            catch {
+                // best-effort — the connection may already be gone.
+            }
+        });
+    };
+    async function dispatch(msg) {
+        const start = Date.now();
+        let outcome = "ok";
+        let requestId = "unknown";
+        let responded = false;
+        const respond = (data) => {
+            responded = true;
+            msg.respond(data, { headers: jsonResponseHeaders() });
+        };
+        const respondError = (code, description, data) => {
+            responded = true;
+            if (data) {
+                msg.respondError(code, description, data, { headers: jsonResponseHeaders() });
+            }
+            else {
+                msg.respondError(code, description);
+            }
+        };
+        let deadlineTimer;
+        try {
+            if (drainSignal.aborted) {
+                respondError(503, "shutting down");
+                outcome = "service-error";
+                return;
+            }
+            // 1. header parse.
+            const parsed = (0, headers_js_1.parseRequestHeaders)(msg.headers);
+            if (!parsed.ok) {
+                respondError(400, parsed.message);
+                outcome = "service-error";
+                return;
+            }
+            const { value: h } = parsed;
+            requestId = h.requestId;
+            if (h.callerKind === "user" && !h.callerId) {
+                respondError(401, "user caller requires Nk-Caller-Id");
+                outcome = "service-error";
+                return;
+            }
+            // 2. deadline check — already past ⇒ 503, handler never invoked.
+            if (h.deadlineMs !== undefined && h.deadlineMs <= Date.now()) {
+                respondError(503, "deadline already passed");
+                outcome = "service-error";
+                return;
+            }
+            // 3. requiredRoles.
+            const requiredRoles = methodDef.requiredRoles ?? [];
+            const missingRole = requiredRoles.find((role) => !h.roles.includes(role));
+            if (missingRole) {
+                respondError(403, `missing role: ${missingRole}`);
+                outcome = "service-error";
+                return;
+            }
+            // Contract/implementation skew: the endpoint exists (there's a
+            // subscription) but no handler is bound for it — wire spec §4.5's 404.
+            // A genuinely unknown method never reaches here at all: no endpoint
+            // means no subscription, so the caller sees no-responders instead.
+            if (typeof handler !== "function") {
+                respondError(404, "unknown method");
+                outcome = "service-error";
+                return;
+            }
+            // Build the deadline/drain-combined abort signal for the handler.
+            const signals = [drainSignal];
+            if (h.deadlineMs !== undefined) {
+                const deadlineController = new AbortController();
+                deadlineTimer = setTimeout(() => deadlineController.abort(), Math.max(0, h.deadlineMs - Date.now()));
+                signals.push(deadlineController.signal);
+            }
+            const handlerSignal = AbortSignal.any(signals);
+            const ctx = {
+                caller: { kind: h.callerKind, id: h.callerId, roles: h.roles },
+                requestId: h.requestId,
+                signal: handlerSignal,
+                headers: msg.headers,
+                subject: msg.subject,
+                method: methodName,
+                deadlineMs: h.deadlineMs,
+                traceparent: h.traceparent,
+            };
+            // Body parsing gets its own try: `msg.json()` throws on non-UTF-8/
+            // non-JSON bodies, and that failure must never be mistaken for a
+            // handler crash (500) — it's a client mistake (400).
+            let body;
+            try {
+                body = msg.json();
+            }
+            catch (bodyErr) {
+                respondError(400, "malformed request body", encodeEnvelope({
+                    details: { message: bodyErr instanceof Error ? bodyErr.message : String(bodyErr) },
+                }));
+                outcome = "service-error";
+                return;
+            }
+            // 4. input schema parse.
+            const parsedInput = methodDef.input.safeParse(body);
+            if (!parsedInput.success) {
+                respondError(400, "input validation failed", encodeEnvelope({ details: { issues: parsedInput.error.issues } }));
+                outcome = "service-error";
+                return;
+            }
+            // 5. authorize hook.
+            if (authorize) {
+                try {
+                    await authorize(ctx, methodName);
+                }
+                catch (authErr) {
+                    if ((0, errors_js_1.isRpcError)(authErr)) {
+                        const status = errors_js_1.STATUS_BY_SERVICE_CODE[authErr.code] ?? 500;
+                        respondError(status, authErr.message);
+                    }
+                    else {
+                        respondError(500, "authorization hook threw");
+                    }
+                    outcome = "service-error";
+                    return;
+                }
+            }
+            // 6. handler, 7. output schema parse — share a catch: any throw here
+            // (handler rejection, or an unexpected throw while validating output)
+            // is a server bug, never a client mistake, so it always maps to 500.
+            try {
+                const result = (await handler(parsedInput.data, ctx));
+                if (!result.ok) {
+                    outcome = "domain-error";
+                    respond(encodeEnvelope({ ok: false, error: result.error }));
+                    return;
+                }
+                const parsedOutput = methodDef.output.safeParse(result.result);
+                if (!parsedOutput.success) {
+                    respondError(500, "handler returned a value the output schema rejects");
+                    outcome = "service-error";
+                    return;
+                }
+                // Wire spec §4.3: a method with no output sends `"result": null`
+                // explicitly (never an omitted key) — `parsedOutput.data` is
+                // `undefined` for `z.void()`/`z.undefined()`, which `JSON.stringify`
+                // would otherwise drop from the object entirely.
+                respond(encodeEnvelope({ ok: true, result: parsedOutput.data ?? null }));
+            }
+            catch (handlerErr) {
+                outcome = "service-error";
+                // Never leak the real error message on the wire — it's server-internal
+                // detail, not something the caller should see or parse. Logged instead.
+                logger?.error({ err: handlerErr, requestId, subject }, "RPC handler threw");
+                // `responded` guards against a second response when the throw came
+                // from `respond()` itself (already sent) rather than the handler.
+                if (!responded)
+                    respondError(500, "internal error");
+            }
+        }
+        catch (unexpectedErr) {
+            // Defensive net: anything that slipped past the wrapped sections
+            // above. `responded` guards against answering the same request twice.
+            outcome = "service-error";
+            if (!responded) {
+                try {
+                    respondError(500, "internal error");
+                }
+                catch {
+                    logger?.error({ err: unexpectedErr, subject }, "failed to respond with error");
+                }
+            }
+        }
+        finally {
+            if (deadlineTimer)
+                clearTimeout(deadlineTimer);
+            const durationMs = Date.now() - start;
+            logger?.debug?.({ subject, requestId, outcome, durationMs }, "RPC request handled");
+            telemetry.onRpcHandled?.(subject, outcome, durationMs);
+        }
+    }
+}
+/** Resolve on the next `onReconnect()` emission, on abort, or on completion (mirrors core's internal helper). */
+function waitForReconnectOrAbort(nats, signal) {
+    if (signal.aborted)
+        return Promise.resolve("aborted");
+    return new Promise((resolve) => {
+        let settled = false;
+        // Holder object (not a reassigned `let`) so `settle` can unsubscribe even
+        // when the reconnect observable is a COMPLETED subject that signals
+        // synchronously during `.subscribe()` below — i.e. before the subscribe
+        // call itself has returned. Mirrors the core's internal helper.
+        const holder = {};
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            holder.sub?.unsubscribe();
+            resolve(outcome);
+        };
+        const onAbort = () => settle("aborted");
+        signal.addEventListener("abort", onAbort);
+        holder.sub = nats.onReconnect().subscribe({
+            next: () => settle("reconnect"),
+            complete: () => settle("completed"),
+            error: () => settle("completed"),
+        });
+    });
+}
+function abortableSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function abortPromise(signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        signal.addEventListener("abort", () => resolve(), { once: true });
+    });
+}
+/**
+ * True for the synchronous config errors `Svcm.add` throws (wrapped in a
+ * rejected promise) for an invalid `name`/`queue` or a non-SemVer `version`
+ * (design §3). These never become valid by retrying, so the supervisor must
+ * reject `handle.done` instead of looping — as opposed to a genuine
+ * connection error, which is retried after the next reconnect.
+ */
+function isTerminalConfigError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return (/ name required$/.test(err.message) ||
+        /^invalid .* name - /.test(err.message) ||
+        /is not a semver value$/.test(err.message));
+}
+/**
+ * Start the reconnect supervisor loop for one contract (design §3).
+ *
+ * `Svcm`-backed `Service` instances permanently stop on connection loss with
+ * no restart path, so this loop rebuilds the service every time it stops
+ * (healthy stop or connection loss) until `signal` aborts.
+ */
+function createRpcServer(contract, options) {
+    const { nats, signal, logger } = options;
+    const telemetry = options.telemetry ?? core_1.noopTelemetry;
+    const rebuildDelayMs = options.rebuildDelayMs ?? DEFAULT_REBUILD_DELAY_MS;
+    const queue = options.queue;
+    // Combined abort: external `signal` OR an internal stop() call. Draining
+    // starts the instant either fires, per design §3's shutdown notes.
+    const internalController = new AbortController();
+    const drainSignal = AbortSignal.any([signal, internalController.signal]);
+    let currentServiceId;
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((resolve, reject) => {
+        resolveDone = resolve;
+        rejectDone = reject;
+    });
+    // `rejectDone(fatal)` (below) can fire before any consumer has awaited or
+    // `.catch()`-ed `done` (e.g. a terminal config error surfacing on the very
+    // first tick) — without this, that's an unhandled rejection. This dummy
+    // handler keeps the rejection observed without swallowing it: `done`
+    // itself still rejects for every real consumer that awaits it.
+    void done.catch(() => undefined);
+    // Registered once — every iteration reuses the same settled/pending
+    // promise instead of adding a fresh `drainSignal` abort listener per
+    // rebuild.
+    const drainAborted = abortPromise(drainSignal).then(() => null);
+    void (async () => {
+        try {
+            while (!drainSignal.aborted) {
+                let svc;
+                try {
+                    // Racing against `drainAborted` (rather than a bare `await`) makes
+                    // shutdown responsive even while `waitForReady()` is still
+                    // pending — the eventual settlement is otherwise never observed,
+                    // so it's `.catch()`-ed to avoid an unhandled rejection.
+                    const readyPromise = nats.waitForReady();
+                    await Promise.race([readyPromise, drainAborted]);
+                    if (drainSignal.aborted) {
+                        void readyPromise.catch(() => undefined);
+                        break;
+                    }
+                    const nc = nats.getConnection();
+                    svc = await new services_1.Svcm(nc).add({
+                        name: (0, contract_js_1.serviceName)(contract),
+                        version: contract.version,
+                        description: contract.description,
+                        metadata: contract.metadata,
+                        queue,
+                    });
+                    currentServiceId = svc.info().id;
+                    try {
+                        const group = svc.addGroup((0, contract_js_1.groupSubject)(contract), queue);
+                        for (const methodName of Object.keys(contract.methods)) {
+                            group.addEndpoint(methodName, buildEndpointHandler(contract, methodName, options, drainSignal));
+                        }
+                    }
+                    catch (groupErr) {
+                        // The service was created but addGroup/addEndpoint failed
+                        // (e.g. a bad method name) — stop it before retrying so we
+                        // don't leak a half-wired service.
+                        await svc.stop().catch(() => undefined);
+                        throw groupErr;
+                    }
+                    if (drainSignal.aborted) {
+                        await svc.stop();
+                        break;
+                    }
+                    telemetry.onRpcServiceStarted?.(svc.info().name, svc.info().id);
+                    logger?.log({ name: svc.info().name, id: svc.info().id }, "RPC service started");
+                    const stopErr = await Promise.race([svc.stopped.then((e) => e), drainAborted]);
+                    await svc.stop();
+                    telemetry.onRpcServiceStopped?.(svc.info().name, svc.info().id, stopErr ?? undefined);
+                    logger?.log({ name: svc.info().name, id: svc.info().id }, "RPC service stopped — will rebuild");
+                }
+                catch (error) {
+                    if (drainSignal.aborted)
+                        break;
+                    // Config errors (bad name/queue, non-SemVer version) never become
+                    // valid by retrying while the connection is healthy — reject
+                    // `done` and stop the loop instead of waiting on a reconnect that
+                    // will never fix anything.
+                    if (isTerminalConfigError(error))
+                        throw error;
+                    logger?.error({ err: error }, "RPC service failed to start — will retry on reconnect");
+                    const waitOutcome = await waitForReconnectOrAbort(nats, drainSignal);
+                    if (waitOutcome === "completed")
+                        break;
+                    continue;
+                }
+                if (drainSignal.aborted)
+                    break;
+                await abortableSleep(rebuildDelayMs, drainSignal);
+            }
+            resolveDone();
+        }
+        catch (fatal) {
+            rejectDone(fatal);
+        }
+    })();
+    return {
+        done,
+        serviceId: () => currentServiceId,
+        stop: async () => {
+            internalController.abort();
+            await done;
+        },
+    };
+}
+// Re-export request id helper for consumers who want to mint one manually
+// (e.g. logging correlation before a call is made).
+function newRequestId() {
+    return nuid_1.nuid.next();
+}
+//# sourceMappingURL=server.js.map

package/dist/commonjs/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/types.d.ts

@@ -0,0 +1,100 @@
+import { type z } from "zod";
+import { type MsgHdrs, type NatsConnectionLike, type NatsLogger, type NatsTelemetry } from "@nats-kit/core";
+import { type ServiceContract } from "./contract.js";
+/** Caller identity stamped on a request (§2.2, §4.2). */
+export interface RpcCaller {
+    kind: "user" | "service";
+    /** Keycloak subject for `user`; service name for `service`. */
+    id?: string;
+    roles?: readonly string[];
+}
+export interface RpcCallOptions {
+    timeoutMs?: number;
+    /** Overrides the client-level caller for this call. */
+    caller?: RpcCaller;
+    /** Supply your own correlation id; otherwise a nuid is minted. */
+    requestId?: string;
+    /** Sets `Nk-Deadline`. Defaults to now + effective timeout. */
+    deadlineMs?: number;
+    /** Extra `Nk-*` headers. `Nats-*` and reserved names are rejected. */
+    headers?: Record<string, string>;
+    /** W3C traceparent to propagate. */
+    traceparent?: string;
+    /** Cancels the in-flight request locally. */
+    signal?: AbortSignal;
+}
+/** One typed method per contract method, resolving with `z.output` or rejecting with `RpcError`. */
+export type RpcClient<C extends ServiceContract> = {
+    [K in keyof C["methods"]]: (input: z.input<C["methods"][K]["input"]>, opts?: RpcCallOptions) => Promise<z.output<C["methods"][K]["output"]>>;
+};
+export interface RpcClientOptions {
+    nats: NatsConnectionLike;
+    /** Default caller identity stamped on every call. */
+    caller?: RpcCaller;
+    /** Fallback when a method declares no `timeoutMs`. Default 10_000. */
+    defaultTimeoutMs?: number;
+    /**
+     * Validate responses against `output` before resolving. Default TRUE.
+     * Per-client opt-out only (no per-call override).
+     */
+    validateResponses?: boolean;
+    logger?: NatsLogger;
+    telemetry?: NatsTelemetry;
+}
+/** Per-request context handed to a server handler (§2.4). */
+export interface RpcContext {
+    caller: Required<Pick<RpcCaller, "kind">> & RpcCaller & {
+        roles: readonly string[];
+    };
+    requestId: string;
+    /** Aborts at `Nk-Deadline`, or when the server drains. */
+    signal: AbortSignal;
+    headers: MsgHdrs;
+    subject: string;
+    method: string;
+    deadlineMs?: number;
+    traceparent?: string;
+}
+export type RpcResult<T, E extends string> = {
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    error: {
+        code: E;
+        message: string;
+        details?: unknown;
+    };
+};
+export type RpcHandlers<C extends ServiceContract> = {
+    [K in keyof C["methods"]]: (input: z.output<C["methods"][K]["input"]>, ctx: RpcContext) => Promise<RpcResult<z.input<C["methods"][K]["output"]>, C["methods"][K]["errors"] extends readonly (infer E extends string)[] ? E : never>>;
+};
+/**
+ * Optional escape hatch for policy the contract's `requiredRoles` cannot
+ * express. Runs AFTER the library's `requiredRoles` check and before
+ * dispatch. Return normally to allow; throw an `RpcError` to deny.
+ */
+export type RpcAuthorize<C extends ServiceContract> = (ctx: Omit<RpcContext, "signal">, method: keyof C["methods"] & string) => void | Promise<void>;
+export interface RpcServerOptions<C extends ServiceContract> {
+    nats: NatsConnectionLike;
+    handlers: RpcHandlers<C>;
+    /** Optional second gate, run only after `requiredRoles` passed. */
+    authorize?: RpcAuthorize<C>;
+    /** Queue group. Defaults to micro's `"q"`; `""` disables load balancing. */
+    queue?: string;
+    /** Stops the supervisor and drains. */
+    signal: AbortSignal;
+    /** Delay before rebuilding after the service stops. Default 1000. */
+    rebuildDelayMs?: number;
+    logger?: NatsLogger;
+    telemetry?: NatsTelemetry;
+}
+export interface RpcServerHandle {
+    /** Resolves when the supervisor loop has exited. */
+    readonly done: Promise<void>;
+    /** Current micro service id (nuid). Changes on every rebuild. */
+    serviceId(): string | undefined;
+    /** Aborts the server's signal (if it owns one) and awaits `done`. */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map