@nats-kit/rpc 0.3.0

package/src/client.ts

@@ -0,0 +1,377 @@
+import { nuid } from "@nats-io/nuid";
+import { Match } from "@nats-io/nats-core";
+import {
+  ClosedConnectionError,
+  ConnectionError,
+  NoRespondersError,
+  RequestError,
+  TimeoutError,
+  noopTelemetry,
+  type MsgHdrs,
+} from "@nats-kit/core";
+
+import { type ServiceContract, methodSubject } from "./contract.js";
+import {
+  RpcError,
+  SERVICE_CODE_BY_STATUS,
+  SERVICE_ERROR_CODES,
+  TRANSPORT_ERROR_CODES,
+  isRpcError,
+} from "./errors.js";
+import {
+  HEADER_CALLER_ID,
+  HEADER_CALLER_KIND,
+  HEADER_CALLER_ROLE,
+  HEADER_CONTENT_TYPE,
+  HEADER_DEADLINE,
+  HEADER_REQUEST_ID,
+  HEADER_TRACEPARENT,
+  HEADER_TRACESTATE,
+  buildRequestHeaders,
+} from "./headers.js";
+import {
+  type RpcCallOptions,
+  type RpcCaller,
+  type RpcClient,
+  type RpcClientOptions,
+} from "./types.js";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const RESERVED_HEADER_NAMES = new Set(
+  [
+    HEADER_REQUEST_ID,
+    HEADER_CALLER_KIND,
+    HEADER_CALLER_ID,
+    HEADER_CALLER_ROLE,
+    HEADER_DEADLINE,
+    HEADER_CONTENT_TYPE,
+    HEADER_TRACEPARENT,
+    HEADER_TRACESTATE,
+  ].map((name) => name.toLowerCase()),
+);
+
+function assertAllowedExtraHeaders(extra: Record<string, string> | undefined): void {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (name.toLowerCase().startsWith("nats-")) {
+      throw new Error(`createRpcClient: cannot set a "Nats-*" header ("${name}")`);
+    }
+    if (RESERVED_HEADER_NAMES.has(name.toLowerCase())) {
+      throw new Error(`createRpcClient: "${name}" is set by the client, not overridable`);
+    }
+  }
+}
+
+/**
+ * Parse a JSON response body, tolerating an empty buffer (§4.5: service
+ * errors MAY have no body at all — uncaught handler throws emit one).
+ */
+function tryParseJson(data: Uint8Array): { ok: true; value: unknown } | { ok: false } {
+  if (data.length === 0) return { ok: false };
+  try {
+    return { ok: true, value: JSON.parse(new TextDecoder().decode(data)) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/** Build the `createRpcClient` implementation for a single contract method. */
+function buildMethodCaller<C extends ServiceContract>(
+  contract: C,
+  methodName: string,
+  options: RpcClientOptions,
+): (input: unknown, opts?: RpcCallOptions) => Promise<unknown> {
+  const methodDef = contract.methods[methodName];
+  if (!methodDef) {
+    throw new Error(`createRpcClient: unknown method "${methodName}"`);
+  }
+  const subject = methodSubject(contract, methodName);
+  const validateResponses = options.validateResponses ?? true;
+  const logger = options.logger;
+  const telemetry = options.telemetry ?? noopTelemetry;
+
+  return async (input: unknown, callOpts: RpcCallOptions = {}): Promise<unknown> => {
+    assertAllowedExtraHeaders(callOpts.headers);
+
+    const requestId = callOpts.requestId ?? nuid.next();
+    const start = Date.now();
+    let outcome:
+      | "ok"
+      | "domain-error"
+      | "service-error"
+      | "timeout"
+      | "no-responders"
+      | "aborted"
+      | "connection-lost" = "ok";
+
+    try {
+      telemetry.onRpcRequest?.(subject, requestId);
+
+      const parsedInputResult = methodDef.input.safeParse(input);
+      if (!parsedInputResult.success) {
+        outcome = "service-error";
+        throw new RpcError({
+          kind: "service",
+          code: SERVICE_ERROR_CODES.BAD_REQUEST,
+          message: "input failed local schema validation",
+          details: parsedInputResult.error.issues,
+          subject,
+          requestId,
+        });
+      }
+      const parsedInput = parsedInputResult.data;
+      const caller: RpcCaller = callOpts.caller ?? options.caller ?? { kind: "service" };
+      const timeoutMs =
+        callOpts.timeoutMs ?? methodDef.timeoutMs ?? options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const deadlineMs = callOpts.deadlineMs ?? Date.now() + timeoutMs;
+
+      const reqHeaders: MsgHdrs = buildRequestHeaders({
+        requestId,
+        caller,
+        deadlineMs,
+        traceparent: callOpts.traceparent,
+        extra: callOpts.headers,
+      });
+
+      const body = new TextEncoder().encode(JSON.stringify(parsedInput));
+
+      await options.nats.waitForReady();
+      const nc = options.nats.getConnection();
+
+      let reply: { data: Uint8Array; headers?: MsgHdrs };
+      try {
+        const requestPromise = nc.request(subject, body, {
+          timeout: timeoutMs,
+          headers: reqHeaders,
+        });
+        reply = callOpts.signal
+          ? await raceWithSignal(requestPromise, callOpts.signal)
+          : await requestPromise;
+      } catch (error) {
+        throw toTransportError(error, subject, requestId);
+      }
+
+      const svcErrorCode = reply.headers?.get("Nats-Service-Error-Code", Match.IgnoreCase);
+      if (svcErrorCode) {
+        outcome = "service-error";
+        const status = Number(svcErrorCode);
+        const description =
+          reply.headers?.get("Nats-Service-Error", Match.IgnoreCase) || "service error";
+        const parsedBody = tryParseJson(reply.data);
+        const details =
+          parsedBody.ok && typeof parsedBody.value === "object" && parsedBody.value !== null
+            ? (parsedBody.value as { details?: unknown }).details
+            : undefined;
+        throw new RpcError({
+          kind: "service",
+          code: SERVICE_CODE_BY_STATUS[status] ?? SERVICE_ERROR_CODES.SERVICE_ERROR,
+          message: description,
+          serviceCode: status,
+          details,
+          subject,
+          requestId,
+        });
+      }
+
+      const parsedBody = tryParseJson(reply.data);
+      if (!parsedBody.ok || typeof parsedBody.value !== "object" || parsedBody.value === null) {
+        outcome = "service-error";
+        throw new RpcError({
+          kind: "service",
+          code: SERVICE_ERROR_CODES.MALFORMED_REPLY,
+          message: "reply body was not valid JSON",
+          subject,
+          requestId,
+        });
+      }
+
+      const envelope = parsedBody.value as {
+        ok?: boolean;
+        result?: unknown;
+        error?: { code?: string; message?: string; details?: unknown };
+      };
+
+      if (envelope.ok === false) {
+        outcome = "domain-error";
+        throw new RpcError({
+          kind: "domain",
+          code: envelope.error?.code ?? "UNKNOWN",
+          message: envelope.error?.message ?? "domain error",
+          details: envelope.error?.details,
+          subject,
+          requestId,
+        });
+      }
+
+      if (envelope.ok !== true) {
+        outcome = "service-error";
+        throw new RpcError({
+          kind: "service",
+          code: SERVICE_ERROR_CODES.MALFORMED_REPLY,
+          message: 'reply body missing "ok"',
+          subject,
+          requestId,
+        });
+      }
+
+      if (!validateResponses) {
+        return envelope.result;
+      }
+
+      // Wire spec §4.3: a method with no output sends `"result": null` on
+      // the wire, but `z.void()`/`z.undefined()` only accept `undefined` —
+      // retry with `undefined` before treating a `null` result as malformed.
+      let parsedOutput = methodDef.output.safeParse(envelope.result);
+      if (!parsedOutput.success && envelope.result === null) {
+        parsedOutput = methodDef.output.safeParse(undefined);
+      }
+      if (!parsedOutput.success) {
+        outcome = "service-error";
+        throw new RpcError({
+          kind: "service",
+          code: SERVICE_ERROR_CODES.MALFORMED_REPLY,
+          message: "reply result failed output schema validation",
+          details: parsedOutput.error.issues,
+          subject,
+          requestId,
+        });
+      }
+
+      return parsedOutput.data;
+    } catch (error) {
+      // Transport errors (timeout, no-responders, connection-lost, aborted)
+      // never flow through the `outcome = "..."` assignments above — derive
+      // it here from the normalised `RpcError` before it's telemetered.
+      if (outcome === "ok" && isRpcError(error)) {
+        if (error.kind === "transport") {
+          outcome =
+            error.code === TRANSPORT_ERROR_CODES.TIMEOUT
+              ? "timeout"
+              : error.code === TRANSPORT_ERROR_CODES.NO_RESPONDERS
+                ? "no-responders"
+                : error.code === TRANSPORT_ERROR_CODES.ABORTED
+                  ? "aborted"
+                  : error.code === TRANSPORT_ERROR_CODES.CONNECTION_LOST
+                    ? "connection-lost"
+                    : "service-error";
+        } else if (error.kind === "domain") {
+          outcome = "domain-error";
+        } else {
+          outcome = "service-error";
+        }
+      }
+      throw error;
+    } finally {
+      logger?.debug?.(
+        { subject, requestId, outcome, durationMs: Date.now() - start },
+        "RPC call completed",
+      );
+      telemetry.onRpcResponse?.(subject, outcome, Date.now() - start);
+    }
+  };
+}
+
+function toTransportError(error: unknown, subject: string, requestId: string): RpcError {
+  // `raceWithSignal` already builds a fully-formed `RpcError` (kind:
+  // "transport", code: ABORTED) when the caller's signal fires — pass it
+  // through unchanged instead of reclassifying it as CONNECTION_LOST.
+  if (isRpcError(error)) return error;
+  if (error instanceof RequestError) {
+    if (error.isNoResponders() || error.cause instanceof NoRespondersError) {
+      return new RpcError({
+        kind: "transport",
+        code: TRANSPORT_ERROR_CODES.NO_RESPONDERS,
+        message: "no responders for subject",
+        subject,
+        requestId,
+        cause: error,
+      });
+    }
+    if (error.cause instanceof TimeoutError) {
+      return new RpcError({
+        kind: "transport",
+        code: TRANSPORT_ERROR_CODES.TIMEOUT,
+        message: "request timed out",
+        subject,
+        requestId,
+        cause: error,
+      });
+    }
+  }
+  if (error instanceof TimeoutError) {
+    return new RpcError({
+      kind: "transport",
+      code: TRANSPORT_ERROR_CODES.TIMEOUT,
+      message: "request timed out",
+      subject,
+      requestId,
+      cause: error,
+    });
+  }
+  if (error instanceof NoRespondersError) {
+    return new RpcError({
+      kind: "transport",
+      code: TRANSPORT_ERROR_CODES.NO_RESPONDERS,
+      message: "no responders for subject",
+      subject,
+      requestId,
+      cause: error,
+    });
+  }
+  if (error instanceof ClosedConnectionError || error instanceof ConnectionError) {
+    return new RpcError({
+      kind: "transport",
+      code: TRANSPORT_ERROR_CODES.CONNECTION_LOST,
+      message: "connection closed or lost",
+      subject,
+      requestId,
+      cause: error,
+    });
+  }
+  return new RpcError({
+    kind: "transport",
+    code: TRANSPORT_ERROR_CODES.CONNECTION_LOST,
+    message: error instanceof Error ? error.message : "request failed",
+    subject,
+    requestId,
+    cause: error,
+  });
+}
+
+function raceWithSignal<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) {
+    return Promise.reject(new RpcError({ kind: "transport", code: TRANSPORT_ERROR_CODES.ABORTED, message: "aborted" }));
+  }
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      reject(new RpcError({ kind: "transport", code: TRANSPORT_ERROR_CODES.ABORTED, message: "aborted" }));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Build a typed `RpcClient<C>` — one method per contract entry, request
+ * headers per §4.2, and error normalisation per §4.6. Rejects with
+ * {@link RpcError} in every non-success case; never leaks `{ok:false}`.
+ */
+export function createRpcClient<C extends ServiceContract>(
+  contract: C,
+  options: RpcClientOptions,
+): RpcClient<C> {
+  const client: Record<string, (input: unknown, opts?: RpcCallOptions) => Promise<unknown>> = {};
+  for (const methodName of Object.keys(contract.methods)) {
+    client[methodName] = buildMethodCaller(contract, methodName, options);
+  }
+  return client as RpcClient<C>;
+}

package/src/contract.ts

@@ -0,0 +1,105 @@
+import { type z } from "zod";
+
+/** Segment grammar shared by `app`, `service` and every method name (§4.1). */
+export const SUBJECT_SEGMENT_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+/**
+ * Definition of a single RPC method within a {@link ServiceContract}.
+ *
+ * See design §2.1. `errors` is a closed set of domain error codes the method
+ * may return via `fail()` — kept as a literal tuple by {@link method} so
+ * `RpcHandlers<C>` and `isDomainError` can narrow against it.
+ */
+export interface RpcMethodDef<
+  I extends z.ZodType = z.ZodType,
+  O extends z.ZodType = z.ZodType,
+  E extends readonly string[] = readonly string[],
+> {
+  input: I;
+  output: O;
+  /** Closed set of domain error codes this method may return. */
+  errors?: E;
+  /**
+   * Roles the caller must hold. Empty/absent means no role requirement.
+   * Enforced by the library BEFORE dispatch: a caller missing any of these
+   * gets a 403 service error and the handler is never invoked.
+   */
+  requiredRoles?: readonly string[];
+  /** Default client timeout for this method. Falls back to 10_000. */
+  timeoutMs?: number;
+  /** Free-form endpoint metadata; surfaces in `nats micro info`. */
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Identity helper that preserves the literal tuple type of `errors` — a bare
+ * object literal would widen `errors: ["NOT_FOUND"]` to `string[]`, which
+ * would flatten every domain error union to `string` throughout the contract.
+ */
+export function method<
+  I extends z.ZodType,
+  O extends z.ZodType,
+  const E extends readonly string[] = readonly [],
+>(def: RpcMethodDef<I, O, E>): RpcMethodDef<I, O, E> {
+  return def;
+}
+
+/** A named collection of RPC methods, addressed at `<app>.<service>.<method>` (§2.1, §4.1). */
+export interface ServiceContract<
+  M extends Record<string, RpcMethodDef> = Record<string, RpcMethodDef>,
+> {
+  /** Subject segment 1. `[a-z0-9-]+`. */
+  app: string;
+  /** Subject segment 2. `[a-z0-9-]+`. */
+  service: string;
+  /** SemVer — `@nats-io/services` rejects anything else (`parseSemVer`). */
+  version: string;
+  description?: string;
+  metadata?: Record<string, string>;
+  /** Keys are method names; each must be `[a-z0-9-]+`. */
+  methods: M;
+}
+
+/** SemVer as required by `@nats-io/services`' `ServiceConfig.version` (`parseSemVer`). */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+
+/**
+ * Validate and return a {@link ServiceContract}. Throws synchronously on a
+ * malformed `app`/`service`/`version`/method name — a contract is authored
+ * once and imported everywhere, so failing fast at module-load time is
+ * preferable to a runtime surprise deep inside `createRpcServer`.
+ */
+export function defineService<const M extends Record<string, RpcMethodDef>>(
+  def: ServiceContract<M>,
+): ServiceContract<M> {
+  if (!SUBJECT_SEGMENT_RE.test(def.app)) {
+    throw new Error(`defineService: invalid app segment "${def.app}"`);
+  }
+  if (!SUBJECT_SEGMENT_RE.test(def.service)) {
+    throw new Error(`defineService: invalid service segment "${def.service}"`);
+  }
+  if (!SEMVER_RE.test(def.version)) {
+    throw new Error(`defineService: invalid semver version "${def.version}"`);
+  }
+  for (const name of Object.keys(def.methods)) {
+    if (!SUBJECT_SEGMENT_RE.test(name)) {
+      throw new Error(`defineService: invalid method name "${name}"`);
+    }
+  }
+  return def;
+}
+
+/** The subject a method is served/called on: `<app>.<service>.<method>` (§4.1). */
+export function methodSubject(contract: ServiceContract, methodName: string): string {
+  return `${contract.app}.${contract.service}.${methodName}`;
+}
+
+/** The micro service `name` (dots are rejected by `Svcm.add`, so `-` joins app/service). */
+export function serviceName(contract: ServiceContract): string {
+  return `${contract.app}-${contract.service}`;
+}
+
+/** The group subject prefix every endpoint is registered under. */
+export function groupSubject(contract: ServiceContract): string {
+  return `${contract.app}.${contract.service}`;
+}

package/src/errors.ts

@@ -0,0 +1,100 @@
+/**
+ * RPC error taxonomy (design §2.3, wire spec §4.5–§4.6).
+ *
+ * - `transport`: never touched the network (no-responders, timeout,
+ *   connection lost, local abort), synthesised entirely by the client.
+ * - `service`: an ADR-32 header error (`Nats-Service-Error-Code`) — bad
+ *   envelope, auth, or a server-side crash. Counted in micro's `num_errors`.
+ * - `domain`: an application outcome carried in the response BODY
+ *   (`{ok:false,error:{code,...}}`). Never touches micro's error counter.
+ */
+export type RpcErrorKind = "transport" | "service" | "domain";
+
+export interface RpcErrorInit {
+  code: string;
+  message: string;
+  kind: RpcErrorKind;
+  details?: unknown;
+  /** ADR-32 numeric code, present only when `kind === "service"`. */
+  serviceCode?: number;
+  subject?: string;
+  requestId?: string;
+  cause?: unknown;
+}
+
+/** The single error type every `RpcClient` method call rejects with. */
+export class RpcError extends Error {
+  readonly code: string;
+  readonly kind: RpcErrorKind;
+  readonly details?: unknown;
+  readonly serviceCode?: number;
+  readonly subject?: string;
+  readonly requestId?: string;
+
+  constructor(init: RpcErrorInit) {
+    super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+    this.name = "RpcError";
+    this.code = init.code;
+    this.kind = init.kind;
+    this.details = init.details;
+    this.serviceCode = init.serviceCode;
+    this.subject = init.subject;
+    this.requestId = init.requestId;
+  }
+}
+
+export function isRpcError(e: unknown): e is RpcError {
+  return e instanceof RpcError;
+}
+
+export function isTransportError(e: unknown): e is RpcError {
+  return isRpcError(e) && e.kind === "transport";
+}
+
+export function isDomainError<C extends string>(
+  e: unknown,
+  code?: C,
+): e is RpcError {
+  if (!isRpcError(e) || e.kind !== "domain") return false;
+  return code === undefined || e.code === code;
+}
+
+/** Reserved transport codes (§4.6) — never appear on the wire. */
+export const TRANSPORT_ERROR_CODES = {
+  NO_RESPONDERS: "NO_RESPONDERS",
+  TIMEOUT: "TIMEOUT",
+  CONNECTION_LOST: "CONNECTION_LOST",
+  ABORTED: "ABORTED",
+} as const;
+
+/** Reserved service codes (§2.3) — the numeric-to-string mapping from §4.6. */
+export const SERVICE_ERROR_CODES = {
+  BAD_REQUEST: "BAD_REQUEST",
+  UNAUTHENTICATED: "UNAUTHENTICATED",
+  FORBIDDEN: "FORBIDDEN",
+  NOT_IMPLEMENTED: "NOT_IMPLEMENTED",
+  INTERNAL: "INTERNAL",
+  UNAVAILABLE: "UNAVAILABLE",
+  MALFORMED_REPLY: "MALFORMED_REPLY",
+  SERVICE_ERROR: "SERVICE_ERROR",
+} as const;
+
+/** §4.6 client normalisation step (2): ADR-32 numeric code -> reserved string code. */
+export const SERVICE_CODE_BY_STATUS: Record<number, string> = {
+  400: SERVICE_ERROR_CODES.BAD_REQUEST,
+  401: SERVICE_ERROR_CODES.UNAUTHENTICATED,
+  403: SERVICE_ERROR_CODES.FORBIDDEN,
+  404: SERVICE_ERROR_CODES.NOT_IMPLEMENTED,
+  500: SERVICE_ERROR_CODES.INTERNAL,
+  503: SERVICE_ERROR_CODES.UNAVAILABLE,
+};
+
+/** Server-side reverse mapping: a domain/service code back to its wire status (§2.4). */
+export const STATUS_BY_SERVICE_CODE: Partial<Record<string, number>> = {
+  [SERVICE_ERROR_CODES.BAD_REQUEST]: 400,
+  [SERVICE_ERROR_CODES.UNAUTHENTICATED]: 401,
+  [SERVICE_ERROR_CODES.FORBIDDEN]: 403,
+  [SERVICE_ERROR_CODES.NOT_IMPLEMENTED]: 404,
+  [SERVICE_ERROR_CODES.INTERNAL]: 500,
+  [SERVICE_ERROR_CODES.UNAVAILABLE]: 503,
+};

package/src/eslint/index.ts

@@ -0,0 +1,30 @@
+/**
+ * ESLint flat-config snippet (design §2.8): a lint-level nudge, not a
+ * guarantee — `no-restricted-properties` is purely syntactic. Spread into a
+ * consumer's flat config:
+ *
+ * ```js
+ * import { rpcBoundaryRules } from "@nats-kit/rpc/eslint";
+ * export default [{ files: ["src/**\/*.ts"], rules: { ...rpcBoundaryRules } }];
+ * ```
+ */
+export const rpcBoundaryRules = {
+  "no-restricted-properties": [
+    "error",
+    {
+      property: "respondError",
+      message:
+        "Return fail(...) or throw RpcError from an RPC handler; the rpc layer owns ADR-32 error headers.",
+    },
+    {
+      object: "nc",
+      property: "request",
+      message: "Use a typed createRpcClient() method instead of raw nc.request().",
+    },
+    {
+      object: "msg",
+      property: "respond",
+      message: "Raw msg.respond() bypasses the RPC envelope. Use an RPC handler.",
+    },
+  ],
+};