@jarenjs/contract 0.49.2 → 0.66.1

package/src/project/typescript.jtlt.json

@@ -29,25 +29,57 @@
         "  url<K extends keyof UrlOperations>(op: K, input: UrlOperations[K]): string;\n",
         "  close(): void;\n",
         "}\n\n",
+        "/** Every opaque public operation by id, with its input type, for `HttpClient.bytes`. */\n",
+        "export interface ByteOperations {\n",
+        [{ "$apply": ["$.operations[?@.opaque == true]", "url"] }],
+        "}\n\n",
+        "/** Per-call options of bytes: the members of InvokeContext that apply to an opaque call, plus the request body to send — text, bytes, a Web stream, an async iterable of chunks, or none. */\n",
+        "export interface ByteContext { signal?: AbortSignal; attempt?: unknown; headers?: Record<string, string>; ifNoneMatch?: string; ifMatch?: string; body?: string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | null }\n\n",
+        "/** The success value of bytes: the status, the response headers (lowercase names), the response media (null when none) and the live response body — a stream the caller reads; null when the response carries none. */\n",
+        "export type ByteResponse = { status: number; headers: Record<string, string>; media: string | null; body: ReadableStream<Uint8Array> | null };\n\n",
+        "/** The HTTP client: the binding-neutral Client plus bytes over the opaque operations, whose success owns a live stream rather than a JSON value. */\n",
+        "export interface HttpClient extends Client {\n",
+        "  bytes<K extends keyof ByteOperations>(op: K, input: ByteOperations[K], ctx?: ByteContext): Promise<Outcome<ByteResponse>>;\n",
+        "}\n\n",
         "/** A declared failure a handler returns (ctx.fail): the declared code, the catalog parameters, the wire details and whether the caller may retry (null defers to the operation's retry policy). */\n",
         "export type Failure = { code: string; params: Readonly<Record<string, unknown>>; details: unknown; retryable: boolean | null };\n\n",
-        "/** The per-request context a server binding hands a handler. */\n",
-        "export interface HandlerContext {\n",
+        "/** The binding a handler context comes from. */\n",
+        "export type CarrierName = 'http' | 'port' | 'local';\n\n",
+        "/** The members every carrier's context shares; `host` is the host lifecycle's acquired value (null by default). */\n",
+        "export interface HandlerContextBase<Host = null> {\n",
         "  op: unknown;\n",
         "  trace: string;\n",
+        "  host: Host;\n",
+        "  headers: Readonly<Record<string, string>>;\n",
+        "  signal: AbortSignal | null;\n",
+        "  fail(code: string, params?: Record<string, unknown>, details?: unknown, options?: { retryable?: boolean }): Failure;\n",
+        "}\n\n",
+        "/** The HTTP binding's context: the request line, the raw body of an opaque operation, the idempotency key, and the entity-tag and status arms. */\n",
+        "export interface HttpHandlerContext<Host = null> extends HandlerContextBase<Host> {\n",
+        "  carrier: 'http';\n",
         "  method: string;\n",
         "  path: string;\n",
         "  params: Readonly<Record<string, string>>;\n",
-        "  headers: Readonly<Record<string, string>>;\n",
-        "  body: string | Uint8Array | null;\n",
-        "  signal: AbortSignal | null;\n",
+        "  body: string | Uint8Array | AsyncIterable<Uint8Array> | null;\n",
         "  idempotency: Readonly<{ key: string; scope: string }> | null;\n",
-        "  fail(code: string, params?: Record<string, unknown>, details?: unknown, options?: { retryable?: boolean }): Failure;\n",
         "  etag(tag: string, options?: { strong?: boolean }): void;\n",
         "  status(status: number): void;\n",
         "}\n\n",
+        "/** The port and local bindings' context: no request line, no body, no key, and no callable etag or status — spelled null, never omitted. */\n",
+        "export interface ChannelHandlerContext<Host = null, Carrier extends 'port' | 'local' = 'port' | 'local'> extends HandlerContextBase<Host> {\n",
+        "  carrier: Carrier;\n",
+        "  method: null;\n",
+        "  path: null;\n",
+        "  params: null;\n",
+        "  body: null;\n",
+        "  idempotency: null;\n",
+        "  etag: null;\n",
+        "  status: null;\n",
+        "}\n\n",
+        "/** The per-request context a server binding hands a handler, selected by carrier: the HTTP context by default; a carrier union is a discriminated union to narrow on `carrier`. */\n",
+        "export type HandlerContext<Host = null, Carrier extends CarrierName = 'http'> = Extract<HttpHandlerContext<Host> | ChannelHandlerContext<Host, 'port'> | ChannelHandlerContext<Host, 'local'>, { carrier: Carrier }>;\n\n",
         "/** The typed handler table of a server binding: one handler per invokable operation, answering the output, a declared failure, or a promise of either. */\n",
-        "export type Handlers = { [K in keyof Operations]: (input: Operations[K]['input'], ctx: HandlerContext) => Operations[K]['output'] | Failure | Promise<Operations[K]['output'] | Failure> };\n"
+        "export type Handlers<Host = null, Carrier extends CarrierName = 'http'> = { [K in keyof Operations]: (input: Operations[K]['input'], ctx: HandlerContext<Host, Carrier>) => Operations[K]['output'] | Failure | Promise<Operations[K]['output'] | Failure> };\n"
       ]
     },
     {

package/src/runtime.js

@@ -0,0 +1,36 @@
+//@ts-check
+/**
+ * @file The one place a contract binding reads its `runtime` option:
+ * the record is resolved through `@jarenjs/core/runtime` — nothing given
+ * is the platform's own clock, identifier and source — and a malformed
+ * record is refused as the binding's OWN host error (`JC1001` for a
+ * server, `JC1008` for a client), naming the option, so the refusal
+ * reads like every other option refusal of that constructor. Every
+ * binding then takes its host facts from the record only where its
+ * explicit option (`trace`, `keys`, `now`) is absent: the record
+ * injects, it never replaces a published option.
+ */
+
+import { resolveRuntime } from '@jarenjs/core/runtime';
+
+/**
+ * @typedef {import('@jarenjs/core/runtime').Runtime} Runtime
+ */
+
+/**
+ * Resolve a binding's `options.runtime`, or refuse it as that binding's
+ * host error under the code it refuses every malformed option with.
+ * @param {Partial<Runtime> | undefined | null} candidate - `options.runtime`
+ * @param {(code: any, reason: string) => Error} host - the binding's host
+ *   error constructor
+ * @param {'JC1001' | 'JC1008'} code - the binding's malformed-option code
+ * @returns {Readonly<Runtime>}
+ */
+export function resolveHostRuntime(candidate, host, code) {
+  try {
+    return resolveRuntime(candidate);
+  }
+  catch (error) {
+    throw host(code, `options.runtime: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/src/stream/client.js

@@ -27,8 +27,12 @@ import { STREAM_ERRORS } from './sse.js';
 
 /**
  * The callbacks of one `client.subscribe` call; every one optional.
+ * `onSnapshot`'s `info` is stable in shape: `reset` says the snapshot
+ * re-seeds a consumer whose cursor fell behind the server's retention
+ * (its `seq` is then the cursor to resume from), and the two watermarks
+ * are the server log's when it reported them (`null` on a fresh stream).
  * @typedef {Object} StreamCallbacks
- * @property {(value: unknown, info: { seq: number, resumed: boolean }) => void} [onSnapshot]
+ * @property {(value: unknown, info: { seq: number, resumed: boolean, reset: boolean, earliestAvailable: number | null, highWatermark: number | null }) => void} [onSnapshot]
  * @property {(emission: { patch: unknown[], seq: number }) => void} [onPatch]
  * @property {(outcome: Outcome) => void} [onError]
  * @property {(info: { reason: string }) => void} [onEnd]
@@ -51,7 +55,9 @@ import { STREAM_ERRORS } from './sse.js';
  * 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.
+ * no-ops once finished. `lastSeq` reads the cursor: the resume seq the
+ * caller passed until a snapshot or patch moves it — what a further
+ * attempt resumes from.
  * @param {StreamConsumerOptions} options
  * @returns {{ snapshot: (seq: number | null, data: unknown) => void,
  *   patch: (seq: number | null, data: unknown) => void,
@@ -59,11 +65,13 @@ import { STREAM_ERRORS } from './sse.js';
  *   end: (data: unknown) => void,
  *   fail: (outcome: Outcome) => void,
  *   cancel: () => void,
- *   finished: () => boolean }}
+ *   finished: () => boolean,
+ *   lastSeq: () => number | null }}
  */
 export function createStreamConsumer(options) {
   const { route, catalog, meta, callbacks, finish } = options;
   let lastSeq = options.lastSeq;
+  let delivered = false;
   let done = false;
 
   /**
@@ -135,13 +143,27 @@ export function createStreamConsumer(options) {
           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) {
+      const reset = envelope.reset === true;
+      // a mid-stream snapshot (a maxPatchBytes replacement) must still
+      // advance; a reset snapshot may land AT the resume cursor — the
+      // server's watermark had not moved past what the consumer held.
+      // A zero seed may replace the resume cursor only before this
+      // attempt delivers anything, when replay falls back to a fresh source.
+      const initialSeed = !delivered && at === 0;
+      if (at !== null && lastSeq !== null && !initialSeed && (reset ? at < lastSeq : 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 });
+      delivered = true;
+      const watermark = (/** @type {unknown} */ v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+      call(callbacks.onSnapshot, envelope.value, {
+        seq: at === null ? 0 : at,
+        resumed: envelope.resumed === true,
+        reset,
+        earliestAvailable: watermark(envelope.earliestAvailable),
+        highWatermark: watermark(envelope.highWatermark),
+      });
     },
     patch(seq, data) {
       if (done) return;
@@ -158,6 +180,7 @@ export function createStreamConsumer(options) {
         return;
       }
       lastSeq = at;
+      delivered = true;
       call(callbacks.onPatch, { patch, seq: at });
     },
     error(data) {
@@ -175,6 +198,16 @@ export function createStreamConsumer(options) {
         call(callbacks.onError, failedOutcome('failure', outcomeError(code, message, null, record.details, retryable), meta));
         return;
       }
+      // a stream code the server ends with that is a NETWORK verdict (the
+      // consumer fell behind, JC2096) is a network outcome under its own
+      // code — retryable, and what a reconnect policy keys on
+      if (code !== null && Object.hasOwn(STREAM_ERRORS, code)
+        && STREAM_ERRORS[/** @type {keyof typeof STREAM_ERRORS} */ (code)].kind === 'network') {
+        const row = STREAM_ERRORS[/** @type {keyof typeof STREAM_ERRORS} */ (code)];
+        const message = typeof record.message === 'string' ? record.message : renderMessage(catalog, row.msgid, { op: route.id });
+        call(callbacks.onError, failedOutcome('network', outcomeError(code, message, null, record.details, row.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 : {
@@ -206,6 +239,7 @@ export function createStreamConsumer(options) {
       }
     },
     finished: () => done,
+    lastSeq: () => lastSeq,
   };
 }