@nats-kit/rpc 0.3.0

package/src/events.ts

@@ -0,0 +1,139 @@
+import { nuid } from "@nats-io/nuid";
+import {
+  headers as buildMsgHdrs,
+  type MsgHdrs,
+  type NatsConnectionLike,
+  type NatsConnectionRunner,
+  type PubAck,
+} from "@nats-kit/core";
+import { z } from "zod";
+
+/** A CloudEvents-shaped event definition (§2.5, §4.8). */
+export interface EventContract<T extends z.ZodType> {
+  /** `<app>.<entity>.<event>` — also the CloudEvents `type` and the subject. */
+  type: string;
+  /** CloudEvents `source`, e.g. "urn:anki:sandbox". */
+  source: string;
+  data: T;
+}
+
+export function defineEvent<T extends z.ZodType>(def: EventContract<T>): EventContract<T> {
+  return def;
+}
+
+/**
+ * `publishEvent` needs a JetStream client to get a `PubAck` (design §2.5);
+ * `NatsConnectionLike` alone is Core-NATS-only, so we widen it with just the
+ * one extra accessor both `NatsConnectionRunner` and the NestJS `NatsService`
+ * (which delegates to it) already expose.
+ */
+export interface PublishEventOptions {
+  nats: NatsConnectionLike & Pick<NatsConnectionRunner, "getJetStream">;
+  /** CloudEvents `id` and `Nats-Msg-Id`. Defaults to a nuid. */
+  id?: string;
+  /** RFC3339. Defaults to `new Date().toISOString()`. */
+  time?: string;
+  /** CloudEvents optional `subject` attribute (a resource id, NOT the NATS subject). */
+  subject?: string;
+  traceparent?: string;
+  /** Override the publish subject. Defaults to `event.type`. */
+  natsSubject?: string;
+}
+
+interface CloudEventEnvelope<T> {
+  specversion: "1.0";
+  id: string;
+  source: string;
+  type: string;
+  time: string;
+  subject?: string;
+  datacontenttype: "application/json";
+  data: T;
+}
+
+export type CloudEvent<T> = CloudEventEnvelope<T>;
+
+/** Validates the envelope shape (§4.8) around an arbitrary `data` payload. */
+const CloudEventEnvelopeSchema = z.object({
+  specversion: z.literal("1.0"),
+  id: z.string().min(1),
+  source: z.string().min(1),
+  type: z.string().min(1),
+  time: z.string().min(1),
+  subject: z.string().optional(),
+  datacontenttype: z.literal("application/json"),
+  data: z.unknown(),
+});
+
+/**
+ * JSON has no representation for `NaN`/`Infinity` — `JSON.stringify` silently
+ * turns them into `null`, which would silently corrupt an event's data on
+ * the wire. Walk the value and reject before that can happen.
+ */
+function assertJsonSafe(value: unknown, path = "$"): void {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        `publishEvent: non-finite number (${String(value)}) at ${path} is not valid JSON`,
+      );
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => assertJsonSafe(v, `${path}[${i}]`));
+    return;
+  }
+  if (value !== null && typeof value === "object") {
+    for (const [k, v] of Object.entries(value)) {
+      assertJsonSafe(v, `${path}.${k}`);
+    }
+  }
+}
+
+/**
+ * Publish a CloudEvents 1.0 structured-mode envelope (§4.8) via JetStream,
+ * with `Nats-Msg-Id` set to the CloudEvents `id` for stream-level dedup.
+ */
+export async function publishEvent<T extends z.ZodType>(
+  event: EventContract<T>,
+  data: z.input<T>,
+  options: PublishEventOptions,
+): Promise<PubAck> {
+  const parsed = event.data.parse(data);
+  assertJsonSafe(parsed);
+  const id = options.id ?? nuid.next();
+  const envelope: CloudEventEnvelope<unknown> = {
+    specversion: "1.0",
+    id,
+    source: event.source,
+    type: event.type,
+    time: options.time ?? new Date().toISOString(),
+    subject: options.subject,
+    datacontenttype: "application/json",
+    data: parsed,
+  };
+
+  const h: MsgHdrs = buildMsgHdrs();
+  if (options.traceparent !== undefined) {
+    h.set("traceparent", options.traceparent);
+  }
+
+  const body = new TextEncoder().encode(JSON.stringify(envelope));
+  await options.nats.waitForReady();
+  const js = options.nats.getJetStream();
+  return js.publish(options.natsSubject ?? event.type, body, { msgID: id, headers: h });
+}
+
+/**
+ * Parse a received JetStream/Core message as a CloudEvents envelope,
+ * validating the full envelope (not just `data`) per §4.8.
+ */
+export function parseEvent<T extends z.ZodType>(
+  event: EventContract<T>,
+  msg: { data: Uint8Array; headers?: MsgHdrs },
+): CloudEvent<z.output<T>> {
+  const raw: unknown = JSON.parse(new TextDecoder().decode(msg.data));
+  const envelope = CloudEventEnvelopeSchema.parse(raw);
+  const data = event.data.parse(envelope.data);
+  return { ...envelope, data };
+}

package/src/headers.ts

@@ -0,0 +1,147 @@
+import { headers as buildMsgHdrs, type MsgHdrs } from "@nats-kit/core";
+import { Match } from "@nats-io/nats-core";
+
+import { type RpcCaller } from "./types.js";
+
+/** Header names (D5, §4.2). Never mint a bare `Nats-*` header — that prefix is server/ADR-32 territory. */
+export const HEADER_REQUEST_ID = "Nk-Request-Id";
+export const HEADER_CALLER_KIND = "Nk-Caller-Kind";
+export const HEADER_CALLER_ID = "Nk-Caller-Id";
+export const HEADER_CALLER_ROLE = "Nk-Caller-Role";
+export const HEADER_DEADLINE = "Nk-Deadline";
+export const HEADER_CONTENT_TYPE = "Content-Type";
+export const HEADER_TRACEPARENT = "traceparent";
+export const HEADER_TRACESTATE = "tracestate";
+
+export const CONTENT_TYPE_JSON = "application/json";
+
+const ROLE_RE = /^[A-Za-z0-9_:-]{1,64}$/;
+const REQUEST_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+export interface BuildRequestHeadersInit {
+  requestId: string;
+  caller: RpcCaller;
+  deadlineMs?: number;
+  traceparent?: string;
+  tracestate?: string;
+  /** Extra `Nk-*` headers. `Nats-*` and reserved names are rejected by the caller (client.ts). */
+  extra?: Record<string, string>;
+}
+
+/** Build the request `MsgHdrs` per §4.2. */
+export function buildRequestHeaders(init: BuildRequestHeadersInit): MsgHdrs {
+  const h = buildMsgHdrs();
+  h.set(HEADER_CONTENT_TYPE, CONTENT_TYPE_JSON);
+  h.set(HEADER_REQUEST_ID, init.requestId);
+  h.set(HEADER_CALLER_KIND, init.caller.kind);
+  if (init.caller.id !== undefined) {
+    h.set(HEADER_CALLER_ID, init.caller.id);
+  }
+  if (init.caller.roles && init.caller.roles.length > 0) {
+    h.set(HEADER_CALLER_ROLE, init.caller.roles.join(","));
+  }
+  if (init.deadlineMs !== undefined) {
+    h.set(HEADER_DEADLINE, String(Math.trunc(init.deadlineMs)));
+  }
+  if (init.traceparent !== undefined) {
+    h.set(HEADER_TRACEPARENT, init.traceparent);
+  }
+  if (init.tracestate !== undefined) {
+    h.set(HEADER_TRACESTATE, init.tracestate);
+  }
+  if (init.extra) {
+    for (const [k, v] of Object.entries(init.extra)) {
+      h.set(k, v);
+    }
+  }
+  return h;
+}
+
+/**
+ * Parse `Nk-Caller-Role` per §4.2: comma-separated, no spaces, absent/empty
+ * means an empty set. Guards the classic `"".split(",")` trap, which yields
+ * `[""]` rather than `[]`.
+ */
+export function parseRoles(headerValue: string | undefined | null): readonly string[] {
+  if (!headerValue) return [];
+  return headerValue.split(",").filter((r) => r.length > 0);
+}
+
+export function isValidRole(role: string): boolean {
+  return ROLE_RE.test(role);
+}
+
+export function isValidRequestId(id: string): boolean {
+  return REQUEST_ID_RE.test(id);
+}
+
+export interface ParsedRequestHeaders {
+  requestId: string;
+  callerKind: "user" | "service";
+  callerId?: string;
+  roles: readonly string[];
+  deadlineMs?: number;
+  traceparent?: string;
+}
+
+export type ParseHeadersResult =
+  | { ok: true; value: ParsedRequestHeaders }
+  | { ok: false; message: string };
+
+/**
+ * Parse and validate the required/conditional request headers per §4.2.
+ * Used by `createRpcServer` as dispatch step 1 (missing/malformed -> 400;
+ * `user` with no `Nk-Caller-Id` -> handled by the caller as 401).
+ */
+export function parseRequestHeaders(h: MsgHdrs | undefined): ParseHeadersResult {
+  if (!h) {
+    return { ok: false, message: "missing required headers" };
+  }
+
+  const contentType = h.get(HEADER_CONTENT_TYPE, Match.IgnoreCase);
+  if (contentType && contentType !== CONTENT_TYPE_JSON) {
+    return { ok: false, message: `unsupported ${HEADER_CONTENT_TYPE}: "${contentType}"` };
+  }
+
+  const requestId = h.get(HEADER_REQUEST_ID, Match.IgnoreCase);
+  if (!requestId || !isValidRequestId(requestId)) {
+    return { ok: false, message: `missing or malformed ${HEADER_REQUEST_ID}` };
+  }
+
+  const callerKind = h.get(HEADER_CALLER_KIND, Match.IgnoreCase);
+  if (callerKind !== "user" && callerKind !== "service") {
+    return { ok: false, message: `missing or invalid ${HEADER_CALLER_KIND}` };
+  }
+
+  const rawCallerId = h.get(HEADER_CALLER_ID, Match.IgnoreCase) || undefined;
+  if (rawCallerId !== undefined && (rawCallerId.length < 1 || rawCallerId.length > 256)) {
+    return { ok: false, message: `${HEADER_CALLER_ID} must be 1-256 chars` };
+  }
+  const callerId = rawCallerId;
+
+  const rawRoles = h.get(HEADER_CALLER_ROLE, Match.IgnoreCase);
+  const roles = parseRoles(rawRoles);
+  if (rawRoles) {
+    for (const role of roles) {
+      if (!isValidRole(role)) {
+        return { ok: false, message: `malformed role in ${HEADER_CALLER_ROLE}: "${role}"` };
+      }
+    }
+  }
+
+  const rawDeadline = h.get(HEADER_DEADLINE, Match.IgnoreCase);
+  let deadlineMs: number | undefined;
+  if (rawDeadline) {
+    if (!/^\d+$/.test(rawDeadline)) {
+      return { ok: false, message: `malformed ${HEADER_DEADLINE}` };
+    }
+    deadlineMs = Number(rawDeadline);
+  }
+
+  const traceparent = h.get(HEADER_TRACEPARENT, Match.IgnoreCase) || undefined;
+
+  return {
+    ok: true,
+    value: { requestId, callerKind, callerId, roles, deadlineMs, traceparent },
+  };
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+// Public surface of @nats-kit/rpc — typed request/reply RPC over NATS,
+// built on @nats-io/services (ADR-32) with a reconnect supervisor.
+//
+// See docs/spec/nats-kit-wire-spec.md for the language-neutral wire spec this
+// package implements (mirrors design doc §4).
+
+// Contract
+export {
+  defineService,
+  method,
+  methodSubject,
+  serviceName,
+  groupSubject,
+  SUBJECT_SEGMENT_RE,
+} from "./contract.js";
+export type { RpcMethodDef, ServiceContract } from "./contract.js";
+
+// Client
+export { createRpcClient } from "./client.js";
+export type {
+  RpcCaller,
+  RpcCallOptions,
+  RpcClient,
+  RpcClientOptions,
+} from "./types.js";
+
+// Server
+export { createRpcServer, ok, fail, newRequestId } from "./server.js";
+export type {
+  RpcContext,
+  RpcResult,
+  RpcHandlers,
+  RpcAuthorize,
+  RpcServerOptions,
+  RpcServerHandle,
+} from "./types.js";
+
+// Errors
+export {
+  RpcError,
+  isRpcError,
+  isDomainError,
+  isTransportError,
+  TRANSPORT_ERROR_CODES,
+  SERVICE_ERROR_CODES,
+} from "./errors.js";
+export type { RpcErrorKind, RpcErrorInit } from "./errors.js";
+
+// Headers (exposed for consumers building their own low-level tooling, e.g.
+// the interop test harness or a Go-side test client written in TS).
+export {
+  HEADER_REQUEST_ID,
+  HEADER_CALLER_KIND,
+  HEADER_CALLER_ID,
+  HEADER_CALLER_ROLE,
+  HEADER_DEADLINE,
+  HEADER_CONTENT_TYPE,
+  HEADER_TRACEPARENT,
+  HEADER_TRACESTATE,
+  CONTENT_TYPE_JSON,
+  parseRoles,
+  parseRequestHeaders,
+} from "./headers.js";
+
+// Events
+export { defineEvent, publishEvent, parseEvent } from "./events.js";
+export type { EventContract, PublishEventOptions, CloudEvent } from "./events.js";
+
+// KV
+export { defineKvValue } from "./kv.js";
+export type { KvValueContract } from "./kv.js";
+
+// Re-export the ADR-32 error class from `@nats-io/services` so consumers can
+// `instanceof`-check it without a direct dependency (mirrors the core
+// barrel's `@nats-io/*` re-export rule).
+export { ServiceError } from "@nats-io/services";

package/src/kv.ts

@@ -0,0 +1,33 @@
+import { type z } from "zod";
+
+const KV_KEY_PART_RE = /^[a-zA-Z0-9_-]+$/;
+
+/** 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 function defineKvValue<T extends z.ZodType>(def: {
+  bucket: string;
+  value: T;
+}): KvValueContract<T> {
+  return {
+    bucket: def.bucket,
+    value: def.value,
+    key(...parts: string[]): string {
+      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;
+    },
+  };
+}