@jarenjs/contract 0.43.1

package/src/public.js

@@ -0,0 +1,206 @@
+//@ts-check
+/**
+ * @file `publicProjection`: the browser-safe subset of a compiled contract
+ * as a JSON document that is ITSELF a valid `$contract` 0.1 — what a
+ * client needs and no more, what the revision hashes, and what every other
+ * projection (OpenAPI, TypeScript, Markdown, tools) is built on.
+ *
+ * Retained: the operations whose `policy.audience` is not `server` (and,
+ * when the caller narrows with `ops`, only those), each with its resolved
+ * binding and policy minus the server-side knobs (`limits`,
+ * `errors.details`), plus the `$defs` the retained schemas reach. Member
+ * order is FIXED (docs/CONTRACT-FORMAT.md §12.1 — normative, because the
+ * revision is the SHA-256 of the canonical bytes of this document): root
+ * `$contract, id, version, compat, $defs, operations`; operation `kind,
+ * input, output, errors, policy, http, doc`; policy `task, idempotency,
+ * revision, cache, retry, stream, audience`; http `method, path, in, body, status,
+ * media`; error `status, schema`; operations in document order; `$defs` in
+ * first-reference order. Defaults are materialized (the projection says
+ * what the binding DOES, not what the author typed), so two documents
+ * that behave alike project alike, and the projection of a projection is
+ * the projection.
+ */
+
+import { isJsonObject, setObjectMember } from '@jarenjs/core/object';
+
+import { ContractHostError } from './errors.js';
+import { reachableDefs } from './bundle.js';
+
+/**
+ * @typedef {import('./compile.js').Contract} Contract
+ * @typedef {import('./compile.js').CompiledOperation} CompiledOperation
+ */
+
+/**
+ * @typedef {Object} PublicProjectionOptions
+ * @property {readonly string[]} [ops] - the operations to keep, a subset
+ *   of the contract's ids (default: all); `server` operations are never
+ *   kept, listed or not
+ */
+
+/**
+ * Whether `value` is a compiled contract — reads the members every
+ * projection needs.
+ * @param {unknown} value
+ * @returns {value is Contract}
+ */
+export function isCompiledContract(value) {
+  if (value === null || typeof value !== 'object') return false;
+  const c = /** @type {any} */ (value);
+  return isJsonObject(c.doc) && Array.isArray(c.ids) && c.operations !== null && typeof c.operations === 'object'
+    && typeof c.match === 'function';
+}
+
+/**
+ * The operations a projection retains, in document order: the public
+ * ones, narrowed by `ops` when given. Throws `JC1008` for a malformed
+ * `contract` or an `ops` entry that names no operation.
+ * @param {Contract} contract
+ * @param {readonly string[] | undefined} ops
+ * @param {string} who - the projection's name, for the message
+ * @returns {CompiledOperation[]}
+ */
+export function retainedOperations(contract, ops, who) {
+  if (!isCompiledContract(contract)) {
+    throw new ContractHostError('JC1008', `${who}: contract must be a compiled contract (compileContract(doc))`);
+  }
+  let wanted = null;
+  if (ops !== undefined) {
+    if (!Array.isArray(ops)) throw new ContractHostError('JC1008', `${who}: ops must be an array of operation ids`);
+    wanted = new Set();
+    for (let i = 0; i < ops.length; i++) {
+      const id = ops[i];
+      if (typeof id !== 'string' || !Object.hasOwn(contract.operations, id)) {
+        throw new ContractHostError('JC1008', `${who}: ops[${i}] names no operation of the contract (${typeof id === 'string' ? id : typeof id})`);
+      }
+      wanted.add(id);
+    }
+  }
+  const out = [];
+  for (let i = 0; i < contract.ids.length; i++) {
+    const op = contract.operations[contract.ids[i]];
+    if (op.policy.audience === 'server') continue;
+    if (wanted !== null && !wanted.has(op.id)) continue;
+    out.push(op);
+  }
+  return out;
+}
+
+/**
+ * The public policy of an operation: the client-facing members in the
+ * fixed order, defaults materialized, the server-side knobs (`limits`,
+ * `errors.details`) left out.
+ * @param {CompiledOperation} op
+ * @returns {Record<string, unknown>}
+ */
+function publicPolicy(op) {
+  const p = op.policy;
+  /** @type {Record<string, unknown>} */
+  const policy = { task: p.task, idempotency: p.idempotency };
+  if (p.revision !== null) policy.revision = p.revision;
+  policy.cache = p.cache;
+  if (p.retry !== null) policy.retry = { max: p.retry.max, on: p.retry.on.slice() };
+  if (p.stream !== null) {
+    policy.stream = p.stream.maxPatchBytes === null
+      ? { resume: p.stream.resume, heartbeatMs: p.stream.heartbeatMs }
+      : { resume: p.stream.resume, heartbeatMs: p.stream.heartbeatMs, maxPatchBytes: p.stream.maxPatchBytes };
+  }
+  policy.audience = p.audience;
+  return policy;
+}
+
+/**
+ * The public binding of an operation: method, canonical path, every
+ * member's location, the whole-body member when declared, status, media.
+ * @param {CompiledOperation} op
+ * @returns {Record<string, unknown>}
+ */
+function publicHttp(op) {
+  const h = op.http;
+  /** @type {Record<string, unknown>} */
+  const http = { method: h.method, path: h.path };
+  /** @type {Record<string, string>} */
+  const locations = {};
+  const members = Object.keys(h.in);
+  for (let i = 0; i < members.length; i++) setObjectMember(locations, members[i], h.in[members[i]]);
+  http.in = locations;
+  if (h.body !== null) http.body = h.body;
+  http.status = h.status;
+  http.media = h.media;
+  return http;
+}
+
+/**
+ * Project one operation.
+ * @param {CompiledOperation} op
+ * @returns {Record<string, unknown>}
+ */
+function publicOperation(op) {
+  /** @type {Record<string, unknown>} */
+  const out = { kind: op.kind };
+  if (op.input !== null) out.input = op.input.schema;
+  out.output = op.output.schema;
+  const codes = Object.keys(op.errors);
+  if (codes.length > 0) {
+    /** @type {Record<string, unknown>} */
+    const errors = {};
+    for (let i = 0; i < codes.length; i++) {
+      const decl = op.errors[codes[i]];
+      /** @type {Record<string, unknown>} */
+      const e = { status: decl.status };
+      if (decl.schema !== null) e.schema = decl.schema;
+      setObjectMember(errors, codes[i], e);
+    }
+    out.errors = errors;
+  }
+  out.policy = publicPolicy(op);
+  out.http = publicHttp(op);
+  if (op.doc !== null) out.doc = op.doc;
+  return out;
+}
+
+/**
+ * The public projection of a compiled contract: a `$contract` 0.1
+ * document (it compiles) holding the public operations with their
+ * resolved bindings and policies and the `$defs` they reach, in the fixed
+ * member order the revision hashes. Schema subtrees are the contract's own
+ * (frozen); the composition is fresh.
+ * @param {Contract} contract
+ * @param {PublicProjectionOptions} [options]
+ * @returns {Record<string, unknown>}
+ * @throws {ContractHostError} `JC1008` — not a compiled contract, or `ops` names no operation
+ * @example
+ * const pub = publicProjection(contract);
+ * compileContract(pub).ids; // the public operations, in document order
+ */
+export function publicProjection(contract, options = {}) {
+  const ops = retainedOperations(contract, options.ops, 'publicProjection');
+  /** @type {Record<string, unknown>} */
+  const out = { $contract: '0.1' };
+  if (contract.id !== null) out.id = contract.id;
+  if (contract.version !== null) out.version = contract.version;
+  if (contract.compat.length > 0) out.compat = contract.compat.slice();
+  /** @type {unknown[]} */
+  const roots = [];
+  for (let i = 0; i < ops.length; i++) {
+    const op = ops[i];
+    if (op.input !== null) roots.push(op.input.schema);
+    roots.push(op.output.schema);
+    const codes = Object.keys(op.errors);
+    for (let j = 0; j < codes.length; j++) {
+      if (op.errors[codes[j]].schema !== null) roots.push(op.errors[codes[j]].schema);
+    }
+  }
+  const names = reachableDefs(roots, contract.doc);
+  if (names.length > 0) {
+    /** @type {Record<string, unknown>} */
+    const defs = {};
+    for (let i = 0; i < names.length; i++) setObjectMember(defs, names[i], contract.doc.$defs[names[i]]);
+    out.$defs = defs;
+  }
+  /** @type {Record<string, unknown>} */
+  const operations = {};
+  for (let i = 0; i < ops.length; i++) setObjectMember(operations, ops[i].id, publicOperation(ops[i]));
+  out.operations = operations;
+  return out;
+}

package/src/revision.js

@@ -0,0 +1,90 @@
+//@ts-check
+/**
+ * @file The contract revision: the lowercase hex SHA-256 over the RFC
+ * 8785 canonical bytes of the public projection (docs/CONTRACT-FORMAT.md
+ * §14) — the compatibility identity two independent processes agree on.
+ * It hashes the PUBLIC projection, never the source document, so a
+ * server-audience operation, a `policy.limits` value or an error-detail
+ * level can change without moving the revision, while any member a
+ * client can observe moves it. Memoized per compiled contract in a
+ * private `WeakMap`, so `compileContract` stays synchronous and the
+ * digest is computed at most once per process; `peekRevision` is the
+ * synchronous read `describe()` uses (`null` until the promise settled).
+ */
+
+import { canonicalSha256 } from '@jarenjs/json/canonical';
+
+import { ContractCompileError } from './errors.js';
+import { publicProjection } from './public.js';
+
+/**
+ * @typedef {import('./compile.js').Contract} Contract
+ */
+
+/**
+ * The memo: contract → `{ promise, value }`. `value` stays `null` until
+ * the digest resolved; a rejected computation is NOT memoized, so a
+ * transient host failure (`crypto.subtle` unavailable) can be retried,
+ * while the deterministic refusal (`JC0061`) simply recurs.
+ * @type {WeakMap<object, { promise: Promise<string>, value: string | null }>}
+ */
+const revisions = new WeakMap();
+
+/**
+ * Compute (once) the revision of a compiled contract: SHA-256 over the
+ * canonical bytes of `publicProjection(contract)`, as 64 lowercase hex
+ * characters. A projection that is not canonicalizable — a string member
+ * carrying an unpaired surrogate, say — rejects with `JC0061`
+ * (`ContractCompileError`, its `docPath` the offending value's pointer
+ * INTO THE PROJECTION).
+ * @param {Contract} contract
+ * @returns {Promise<string>}
+ * @example
+ * const contract = compileContract(doc);
+ * await contract.revision(); // 'e3b0c442…' — stable across compiles of equal documents
+ */
+export function contractRevision(contract) {
+  const memo = revisions.get(contract);
+  if (memo !== undefined) return memo.promise;
+  /** @type {{ promise: Promise<string>, value: string | null }} */
+  const record = { promise: /** @type {any} */ (null), value: null };
+  record.promise = digest(contract, record);
+  revisions.set(contract, record);
+  return record.promise;
+}
+
+/**
+ * @param {Contract} contract
+ * @param {{ promise: Promise<string>, value: string | null }} record
+ * @returns {Promise<string>}
+ */
+async function digest(contract, record) {
+  let hex;
+  try {
+    hex = await canonicalSha256(publicProjection(contract));
+  }
+  catch (err) {
+    revisions.delete(contract);
+    if (err !== null && typeof err === 'object' && /** @type {any} */ (err).name === 'JsonCanonicalizeError') {
+      throw new ContractCompileError('JC0061',
+        `the public projection is not canonicalizable: ${/** @type {Error} */ (err).message}`,
+        /** @type {any} */ (err).dataPath, /** @type {Error} */ (err));
+    }
+    throw err;
+  }
+  record.value = hex;
+  return hex;
+}
+
+/**
+ * The revision of a compiled contract if it has been computed, else
+ * `null` — the synchronous read `describe()` renders, so a description
+ * taken before anyone awaited `revision()` honestly says "not computed"
+ * rather than blocking.
+ * @param {Contract} contract
+ * @returns {string | null}
+ */
+export function peekRevision(contract) {
+  const memo = revisions.get(contract);
+  return memo === undefined ? null : memo.value;
+}

package/src/stream/client.js

@@ -0,0 +1,212 @@
+//@ts-check
+/**
+ * @file The client half of the stream binding, carrier-neutral
+ * (docs/CONTRACT-FORMAT.md §19): one consumer state machine that both
+ * `client.subscribe` implementations feed — the HTTP client with
+ * decoded SSE events, the port client with push frames. It validates
+ * every snapshot against the operation's output schema, enforces the
+ * strictly-increasing seq (`JC2092`), classifies a server `error` event
+ * (a declared code is a `failure` outcome under its own code; anything
+ * else is `contract` `JC2093` with the server's record in `details`),
+ * and delivers each `on*` callback totally — a callback that throws
+ * never breaks the machine. After the first terminal event (`error`,
+ * `end`, a local failure) the machine is finished: the carrier's
+ * `finish` hook has run and every later event is dropped.
+ */
+
+import { renderMessage, verdict, projectValidationDetails } from '../http/wire.js';
+import { failedOutcome, outcomeError, clientError } from '../client/outcome.js';
+import { STREAM_ERRORS } from './sse.js';
+
+/**
+ * @typedef {import('../client/outcome.js').OutcomeRoute} OutcomeRoute
+ * @typedef {import('../client/outcome.js').OutcomeMeta} OutcomeMeta
+ * @typedef {import('../client/outcome.js').Outcome} Outcome
+ * @typedef {import('../http/wire.js').Catalog} Catalog
+ */
+
+/**
+ * The callbacks of one `client.subscribe` call; every one optional.
+ * @typedef {Object} StreamCallbacks
+ * @property {(value: unknown, info: { seq: number, resumed: boolean }) => void} [onSnapshot]
+ * @property {(emission: { patch: unknown[], seq: number }) => void} [onPatch]
+ * @property {(outcome: Outcome) => void} [onError]
+ * @property {(info: { reason: string }) => void} [onEnd]
+ */
+
+/**
+ * @typedef {Object} StreamConsumerOptions
+ * @property {OutcomeRoute & { details: 'none' | 'paths' | 'full' }} route
+ * @property {Catalog | null} catalog
+ * @property {OutcomeMeta} meta - mutated: `trace` is refreshed from error records
+ * @property {StreamCallbacks} callbacks
+ * @property {() => void} finish - the carrier's cleanup (remove the entry,
+ *   cancel readers and timers); called exactly once, before the terminal callback
+ * @property {number | null} lastSeq - the resume seq the caller passed (the
+ *   regression baseline until a snapshot or patch moves it)
+ */
+
+/**
+ * The consumer the carriers feed. `snapshot`/`patch` take the seq the
+ * wire carried (the SSE id, the frame's `seq`) — `null` falls back to
+ * the data's own `seq`; `error`/`end` take the event data; `fail` takes
+ * a ready outcome (a transport failure the carrier classified). All are
+ * no-ops once finished.
+ * @param {StreamConsumerOptions} options
+ * @returns {{ snapshot: (seq: number | null, data: unknown) => void,
+ *   patch: (seq: number | null, data: unknown) => void,
+ *   error: (data: unknown) => void,
+ *   end: (data: unknown) => void,
+ *   fail: (outcome: Outcome) => void,
+ *   cancel: () => void,
+ *   finished: () => boolean }}
+ */
+export function createStreamConsumer(options) {
+  const { route, catalog, meta, callbacks, finish } = options;
+  let lastSeq = options.lastSeq;
+  let done = false;
+
+  /**
+   * Run one callback totally.
+   * @param {((arg: any, extra?: any) => void) | undefined} cb
+   * @param {any} arg
+   * @param {any} [extra]
+   */
+  function call(cb, arg, extra) {
+    if (cb === undefined) return;
+    try {
+      cb(arg, extra);
+    }
+    catch {
+      // a consumer callback that throws never breaks the stream machine
+    }
+  }
+
+  /** Terminate: cleanup first, then the terminal callback. */
+  function terminate() {
+    if (done) return false;
+    done = true;
+    try {
+      finish();
+    }
+    catch {
+      // the carrier's cleanup must not eat the terminal callback
+    }
+    return true;
+  }
+
+  /**
+   * A stream-code outcome (`JC2090`/`JC2092`/`JC2094`), rendered here.
+   * @param {'JC2090' | 'JC2092' | 'JC2094'} code
+   * @param {Record<string, unknown>} params
+   * @returns {Outcome}
+   */
+  function streamOutcome(code, params) {
+    const row = STREAM_ERRORS[code];
+    return failedOutcome(row.kind === 'network' ? 'network' : 'contract',
+      outcomeError(code, renderMessage(catalog, row.msgid, { op: route.id, ...params }), null, null, row.retryable), meta);
+  }
+
+  /**
+   * The seq of one event: the wire's, or the data's own.
+   * @param {number | null} seq
+   * @param {any} data
+   * @returns {number | null}
+   */
+  function seqOf(seq, data) {
+    if (typeof seq === 'number' && Number.isFinite(seq)) return seq;
+    const own = data !== null && typeof data === 'object' ? data.seq : undefined;
+    return typeof own === 'number' && Number.isFinite(own) ? own : null;
+  }
+
+  return {
+    snapshot(seq, data) {
+      if (done) return;
+      const envelope = /** @type {any} */ (data);
+      if (envelope === null || typeof envelope !== 'object' || !Object.hasOwn(envelope, 'value')) {
+        if (terminate()) call(callbacks.onError, failedOutcome('contract',
+          clientError(catalog, 'JC2053', { op: route.id }, null, [{ path: '', keyword: 'snapshot' }]), meta));
+        return;
+      }
+      const at = seqOf(seq, envelope);
+      const v = verdict(route.validateOutput, envelope.value);
+      if (!v.valid) {
+        if (terminate()) call(callbacks.onError, failedOutcome('contract',
+          clientError(catalog, 'JC2053', { op: route.id }, null, projectValidationDetails(route.details, v.errors)), meta));
+        return;
+      }
+      // a mid-stream snapshot (a maxPatchBytes replacement) must still advance
+      if (at !== null && lastSeq !== null && at !== 0 && at <= lastSeq) {
+        if (terminate()) call(callbacks.onError, streamOutcome('JC2092', {}));
+        return;
+      }
+      if (at !== null) lastSeq = at;
+      call(callbacks.onSnapshot, envelope.value, { seq: at === null ? 0 : at, resumed: envelope.resumed === true });
+    },
+    patch(seq, data) {
+      if (done) return;
+      const emission = /** @type {any} */ (data);
+      const patch = emission !== null && typeof emission === 'object' ? emission.patch : undefined;
+      const at = seqOf(seq, emission);
+      if (!Array.isArray(patch) || at === null) {
+        if (terminate()) call(callbacks.onError, failedOutcome('contract',
+          clientError(catalog, 'JC2053', { op: route.id }, null, [{ path: '', keyword: 'patch' }]), meta));
+        return;
+      }
+      if (lastSeq !== null && at <= lastSeq) {
+        if (terminate()) call(callbacks.onError, streamOutcome('JC2092', {}));
+        return;
+      }
+      lastSeq = at;
+      call(callbacks.onPatch, { patch, seq: at });
+    },
+    error(data) {
+      if (!terminate()) return;
+      const record = /** @type {any} */ (data);
+      const code = record !== null && typeof record === 'object' && typeof record.code === 'string' ? record.code : null;
+      if (record !== null && typeof record === 'object' && typeof record.requestId === 'string' && record.requestId.length > 0) {
+        meta.trace = record.requestId;
+      }
+      if (code !== null && Object.hasOwn(route.errors, code)) {
+        const message = typeof record.message === 'string'
+          ? record.message
+          : renderMessage(catalog, 'contract/handler-error', { op: route.id, code });
+        const retryable = typeof record.retryable === 'boolean' ? record.retryable : route.retryOn.has(code);
+        call(callbacks.onError, failedOutcome('failure', outcomeError(code, message, null, record.details, retryable), meta));
+        return;
+      }
+      // an undeclared server error ends the stream as a contract violation;
+      // the server's record rides in details so a JC2091 stays visible
+      const details = code === null ? null : {
+        code,
+        message: record !== null && typeof record === 'object' && typeof record.message === 'string' ? record.message : null,
+      };
+      call(callbacks.onError, failedOutcome('contract',
+        outcomeError('JC2093', renderMessage(catalog, STREAM_ERRORS.JC2093.msgid, { op: route.id, code: code === null ? 'none' : code }),
+          null, details, false), meta));
+    },
+    end(data) {
+      if (!terminate()) return;
+      const record = /** @type {any} */ (data);
+      const reason = record !== null && typeof record === 'object' && typeof record.reason === 'string' ? record.reason : 'closed';
+      call(callbacks.onEnd, { reason });
+    },
+    fail(outcome) {
+      if (!terminate()) return;
+      call(callbacks.onError, outcome);
+    },
+    cancel() {
+      if (done) return;
+      done = true;
+      try {
+        finish();
+      }
+      catch {
+        // a cancel is silent either way
+      }
+    },
+    finished: () => done,
+  };
+}
+
+export { STREAM_ERRORS };