@jarenjs/contract 0.49.2 → 0.66.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/contract",
   "private": false,
-  "version": "0.49.2",
+  "version": "0.66.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -102,9 +102,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.49.2",
-    "@jarenjs/json": "^0.49.2",
-    "@jarenjs/validate": "^0.49.2",
-    "@jarenjs/emit": "^0.49.2"
+    "@jarenjs/core": "^0.66.1",
+    "@jarenjs/json": "^0.66.1",
+    "@jarenjs/validate": "^0.66.1",
+    "@jarenjs/emit": "^0.66.1"
   }
 }

package/src/adapters/fetch.js

@@ -6,22 +6,64 @@
  * Dependency-free and structurally typed: it needs only the platform's
  * `Request`, `Response` and `Headers`.
  *
- * The adapter reads the body only when the matched operation can carry
- * one (`text()` for a JSON operation, `arrayBuffer()` for an opaque one),
- * refuses a declared `content-length` above the operation's limit
- * BEFORE reading (the dispatcher answers the 413 from the header), never
- * reads an unmatched request's body, and hands everything else to
- * `dispatch`. `Headers` combines repeated field lines with `, `, so a
- * repeated scalar header member is invisible here (the node adapter sees
- * distinct lines); `text()` decodes with replacement, so invalid UTF-8
- * reaches the JSON parser as U+FFFD (the node adapter hands bytes over
- * and the dispatcher's strict decode answers `JC2005`).
+ * The adapter hands the request's body stream to the dispatcher as a
+ * pull source only when the matched operation can carry one — a JSON
+ * operation drains it under its limit there (the strict UTF-8 decode
+ * decides `JC2005`, as through the node adapter), an opaque handler
+ * pulls it chunk by chunk — refuses a declared `content-length` above
+ * the operation's limit BEFORE reading (the dispatcher answers the 413
+ * from the header), never reads an unmatched request's body, and hands
+ * everything else to `dispatch`. A streamed response body becomes a
+ * `ReadableStream` that pulls one chunk per demand. `Headers` combines
+ * repeated field lines with `, `, so a repeated scalar header member is
+ * invisible here (the node adapter sees distinct lines).
  */
 
 /**
  * @typedef {import('../http/serve.js').HttpDispatcher} HttpDispatcher
  */
 
+/**
+ * A Web `ReadableStream` over an async byte source: one `pull` awaits
+ * one `next()`, `cancel()` runs the source's `return()` once, and a
+ * source that throws errors the stream.
+ * @param {AsyncIterable<Uint8Array>} source
+ * @returns {ReadableStream<Uint8Array>}
+ */
+function bodyStream(source) {
+  const iterator = source[Symbol.asyncIterator]();
+  let cancelled = false;
+  return new ReadableStream({
+    async pull(controller) {
+      let r;
+      try {
+        r = await iterator.next();
+      }
+      catch (err) {
+        controller.error(err);
+        return;
+      }
+      if (r.done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(r.value);
+    },
+    async cancel() {
+      if (cancelled) return;
+      cancelled = true;
+      if (typeof iterator.return === 'function') {
+        try {
+          await iterator.return();
+        }
+        catch {
+          // the source refused its cancel; it is released either way
+        }
+      }
+    },
+  }, { highWaterMark: 0 });
+}
+
 /**
  * Whether the request could carry a body the operation reads.
  * @param {string} method
@@ -61,7 +103,10 @@ export function toFetchHandler(dispatcher) {
       if (hit !== null) {
         const declared = Number(headers['content-length']);
         if (!(Number.isFinite(declared) && declared > hit.op.policy.limits.maxBodyBytes)) {
-          body = hit.op.http.opaque ? new Uint8Array(await request.arrayBuffer()) : await request.text();
+          // the platform's stream reaches the dispatcher as a pull
+          // source: a JSON operation drains it under its limit there,
+          // an opaque handler pulls it chunk by chunk
+          body = request.body;
         }
       }
     }
@@ -70,40 +115,114 @@ export function toFetchHandler(dispatcher) {
       method, url: url.pathname + url.search, headers, body, signal: request.signal,
     });
     if (typeof response.stream === 'function') {
-      // an SSE response: the pump writes into a ReadableStream; a
-      // consumer cancel stops the subscription (the request signal
+      // an SSE response: the pump writes into a ReadableStream that
+      // produces on DEMAND — a write settles only when the consumer's
+      // pull takes the chunk, so the pump never runs ahead of the
+      // reader; a consumer cancel rejects the write waiting for demand
+      // and stops the subscription exactly once (the request signal
       // covers the disconnect path too)
       const pump = response.stream;
       const encoder = new TextEncoder();
+      /** @type {ReturnType<typeof pump> | null} */
+      let runner = null;
+      let stopped = false;
+      const stopOnce = () => {
+        if (stopped) return;
+        stopped = true;
+        if (runner !== null) runner.stop();
+      };
+      /** @type {ReadableStreamDefaultController<Uint8Array> | null} */
+      let controllerRef = null;
+      /** the write waiting for the consumer's demand */
+      /** @type {{ chunk: string, resolve: () => void, reject: (reason: unknown) => void } | null} */
+      let waiting = null;
+      /** the pull no write has answered yet */
       /** @type {(() => void) | null} */
-      let stop = null;
+      let demand = null;
+      let cancelled = false;
+      /** @type {unknown} */
+      let cancelReason;
+      /** One chunk crosses when a write and a pull are both present. */
+      const serve = () => {
+        if (waiting === null || demand === null || controllerRef === null) return;
+        const w = waiting;
+        const d = demand;
+        waiting = null;
+        demand = null;
+        try {
+          controllerRef.enqueue(encoder.encode(w.chunk));
+        }
+        catch (err) {
+          w.reject(err);
+          d();
+          return;
+        }
+        w.resolve();
+        d();
+      };
       const streamBody = new ReadableStream({
         start(controller) {
-          stop = pump({
-            write: (chunk) => {
+          controllerRef = controller;
+          runner = pump({
+            write: (chunk) => new Promise((resolve, reject) => {
+              if (cancelled) {
+                reject(cancelReason);
+                return;
+              }
+              waiting = { chunk, resolve, reject };
+              serve();
+            }),
+            end: () => {
               try {
-                controller.enqueue(encoder.encode(chunk));
+                controller.close();
               }
               catch {
-                // a closed stream drops the write; the abort path stops the pump
+                // already closed or cancelled
               }
             },
-            end: () => {
+            abort: (reason) => {
+              // the carrier is torn down: the consumer's pending read
+              // rejects with the reason, and the subscription is
+              // released as a destroyed node socket releases it
               try {
-                controller.close();
+                controller.error(reason);
               }
               catch {
-                // already closed
+                // already closed or cancelled
               }
+              stopOnce();
             },
           });
         },
-        cancel() {
-          if (stop !== null) stop();
+        pull() {
+          return new Promise((resolve) => {
+            demand = () => resolve(undefined);
+            serve();
+          });
         },
-      });
+        cancel(reason) {
+          cancelled = true;
+          cancelReason = reason === undefined ? new Error('the stream was cancelled') : reason;
+          if (waiting !== null) {
+            const w = waiting;
+            waiting = null;
+            w.reject(cancelReason);
+          }
+          if (demand !== null) {
+            const d = demand;
+            demand = null;
+            d();
+          }
+          stopOnce();
+        },
+      }, { highWaterMark: 0 });
       return new Response(streamBody, { status: response.status, headers: response.headers });
     }
-    return new Response(/** @type {BodyInit | null} */ (response.body), { status: response.status, headers: response.headers });
+    const out = response.body;
+    if (out !== null && typeof out === 'object' && !(out instanceof Uint8Array)) {
+      // a streamed body: one pull per chunk, cancelled once by the consumer
+      return new Response(bodyStream(out), { status: response.status, headers: response.headers });
+    }
+    return new Response(/** @type {BodyInit | null} */ (out), { status: response.status, headers: response.headers });
   };
 }

package/src/adapters/node.js

@@ -7,21 +7,31 @@
  * `headersDistinct` (or `headers`) and a readable-stream event surface,
  * the response anything with `writeHead`/`end`.
  *
- * The body is collected chunk by chunk up to the matched operation's
- * `policy.limits.maxBodyBytes`; on overflow the read stops, the 413 is
- * answered with `connection: close`, and once the response has flushed
- * the socket lingers — draining and discarding the rest of the upload
- * (bounded by a grace timer) before it is destroyed, so the close is a
- * FIN the peer can read the 413 through, not an RST that discards it. A declared `content-length` above the limit
- * is never read at all; an unmatched request's body is never read (the
+ * The body reaches the dispatcher as a PULL SOURCE over the request's
+ * own chunks — nothing is collected here: a JSON operation drains it
+ * under `policy.limits.maxBodyBytes` in the dispatcher (its strict
+ * UTF-8 decode decides `JC2005`), an opaque handler pulls it one chunk
+ * at a time through a source that never yields past the limit. When an
+ * upload was pulled and left unread (a limit crossing, a response
+ * before EOF) the answer carries `connection: close`, and once it has
+ * flushed the socket lingers — draining and discarding the rest of the
+ * upload (bounded by a grace timer) before it is destroyed, so the
+ * close is a FIN the peer can read the 413 through, not an RST that
+ * discards it. A declared `content-length` above the limit is never
+ * read at all; an unmatched request's body is never read (the
  * dispatcher answers 404/405 without it and the platform discards the
- * rest). Bytes are handed to the dispatcher as received — for a JSON
- * operation too, so its strict UTF-8 decode decides `JC2005`. Repeated
+ * rest). A streamed response body is written chunk by chunk behind the
+ * socket's `drain`. Repeated
  * header lines reach the dispatcher as arrays (`headersDistinct`), which
  * is how a repeated scalar header member becomes `JC2015`. `ctx.signal`
- * aborts when the client goes away before the response finished.
+ * aborts when the client goes away before the response finished. A
+ * streaming (SSE) response writes each event only after the previous
+ * one drained: a `res.write()` that answers `false` parks the pump
+ * until `drain`, so a slow reader never grows the process's buffers.
  */
 
+import { createAwaitedSink } from '@jarenjs/core/async';
+
 /**
  * @typedef {import('../http/serve.js').HttpDispatcher} HttpDispatcher
  */
@@ -49,18 +59,212 @@ const LINGER_MS = 1000;
 
 /**
  * The response surface the adapter writes — `http.ServerResponse` fits.
- * `write` and `flushHeaders` are read only for a streaming (SSE)
- * response.
+ * `write`, `flushHeaders`, `once`/`removeListener` (or `off`),
+ * `destroy`, `destroyed` and `writableEnded` are read only for a
+ * streaming (SSE) response: `write`'s `false` is waited out on `drain`
+ * (settled on `close`/`error` too, with the listeners removed), and a
+ * response already ended or destroyed refuses the write instead of
+ * emitting `write after end`.
  * @typedef {Object} NodeResponseLike
  * @property {(status: number, headers?: Record<string, string>) => unknown} writeHead
  * @property {(body?: string | Uint8Array, callback?: () => void) => unknown} end
  * @property {(event: string, listener: (...args: any[]) => void) => unknown} on
+ * @property {(event: string, listener: (...args: any[]) => void) => unknown} [once]
+ * @property {(event: string, listener: (...args: any[]) => void) => unknown} [removeListener]
+ * @property {(event: string, listener: (...args: any[]) => void) => unknown} [off]
  * @property {(chunk: string | Uint8Array) => unknown} [write]
  * @property {() => unknown} [flushHeaders]
+ * @property {(error?: Error) => unknown} [destroy]
  * @property {boolean} [writableFinished]
+ * @property {boolean} [writableEnded]
+ * @property {boolean} [destroyed]
  * @property {boolean} [headersSent]
  */
 
+/**
+ * The streaming sink over a platform response: `write` hands the chunk
+ * to `res.write` and answers nothing when the platform took it (`true`),
+ * or a promise that resolves on the next `drain` when it answered
+ * `false` — so the pump behind it writes the next event only once the
+ * socket has room — and rejects when the response closes or errors
+ * first. Every listener the wait registered is removed at settlement.
+ * `end` ends the response; `abort` destroys it.
+ * @param {NodeResponseLike} res
+ * @returns {import('@jarenjs/core/async').SinkLike<string>}
+ */
+function responseSink(res) {
+  const listen = typeof res.once === 'function' ? res.once.bind(res) : res.on.bind(res);
+  const unlisten = typeof res.removeListener === 'function'
+    ? res.removeListener.bind(res)
+    : typeof res.off === 'function' ? res.off.bind(res) : null;
+  return {
+    write: (chunk) => {
+      if (typeof res.write !== 'function') return undefined;
+      if (res.writableEnded === true || res.destroyed === true) {
+        return Promise.reject(new Error('the response is closed'));
+      }
+      let taken;
+      try {
+        taken = res.write(chunk);
+      }
+      catch (err) {
+        return Promise.reject(err);
+      }
+      if (taken !== false) return undefined;
+      return new Promise((resolve, reject) => {
+        let settled = false;
+        /** @type {() => void} */
+        const off = () => {
+          settled = true;
+          if (unlisten === null) return;
+          unlisten('drain', onDrain);
+          unlisten('close', onClose);
+          unlisten('error', onError);
+        };
+        const onDrain = () => {
+          if (settled) return;
+          off();
+          resolve();
+        };
+        const onClose = () => {
+          if (settled) return;
+          off();
+          reject(new Error('the response closed before it drained'));
+        };
+        /** @param {unknown} err */
+        const onError = (err) => {
+          if (settled) return;
+          off();
+          reject(err);
+        };
+        listen('drain', onDrain);
+        listen('close', onClose);
+        listen('error', onError);
+      });
+    },
+    end: () => {
+      try {
+        res.end();
+      }
+      catch {
+        // the socket may already be gone
+      }
+    },
+    abort: () => {
+      if (typeof res.destroy === 'function' && res.destroyed !== true) res.destroy();
+    },
+  };
+}
+
+/**
+ * The request as a pull source of its body chunks — what a body-carrying
+ * matched request hands the dispatcher. Chunks come from the platform's
+ * own async iterator (paused between pulls, so an unpulled upload never
+ * fills memory); `return()` does NOT destroy the request — a mid-upload
+ * cancel (a limit crossing, a response before EOF) must answer through
+ * a readable close, so the source only records that it was cancelled
+ * and `send` lingers and destroys after the response flushed. `state`
+ * says whether the request was pulled at all and whether it reached
+ * EOF, which decides `connection: close`.
+ * @param {NodeRequestLike} req
+ * @returns {AsyncIterable<Uint8Array> & { state: { started: boolean, ended: boolean, cancelled: boolean } }}
+ */
+function requestSource(req) {
+  const state = { started: false, ended: false, cancelled: false };
+  /** @type {AsyncIterator<Uint8Array> | null} */
+  let inner = null;
+  return {
+    state,
+    [Symbol.asyncIterator]() {
+      return {
+        async next() {
+          if (state.ended || state.cancelled) return { done: true, value: undefined };
+          state.started = true;
+          if (inner === null) {
+            const iterable = /** @type {any} */ (req);
+            if (typeof iterable[Symbol.asyncIterator] !== 'function') {
+              state.ended = true;
+              return { done: true, value: undefined };
+            }
+            inner = iterable[Symbol.asyncIterator]();
+          }
+          let r;
+          try {
+            r = await inner.next();
+          }
+          catch (err) {
+            state.cancelled = true;
+            throw err;
+          }
+          if (r.done) {
+            state.ended = true;
+            return { done: true, value: undefined };
+          }
+          return { done: false, value: r.value };
+        },
+        async return(value) {
+          // no destroy here: the response decides how the socket closes
+          state.cancelled = true;
+          if (typeof req.pause === 'function') req.pause();
+          return { done: true, value };
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Write a streamed response body: chunk by chunk through the
+ * drain-aware sink, then end; the peer going away — or a sink failure —
+ * cancels the source exactly once, and a source that throws destroys
+ * the response (its status is already on the wire; the body is cut).
+ * @param {NodeResponseLike} res
+ * @param {AsyncIterable<Uint8Array>} body
+ * @param {(() => void) | undefined} done
+ */
+function pumpBody(res, body, done) {
+  const sink = createAwaitedSink(responseSink(res));
+  const iterator = body[Symbol.asyncIterator]();
+  let cancelled = false;
+  const cancel = async () => {
+    if (cancelled) return;
+    cancelled = true;
+    if (typeof iterator.return === 'function') {
+      try {
+        await iterator.return();
+      }
+      catch {
+        // the source refused its cancel; it is released either way
+      }
+    }
+  };
+  const onClose = () => {
+    if (res.writableFinished !== true) void cancel();
+  };
+  res.on('close', onClose);
+  (async () => {
+    try {
+      for (;;) {
+        const r = await iterator.next();
+        if (r.done) break;
+        if (cancelled) break;
+        await sink.write(r.value);
+      }
+      if (cancelled) {
+        await sink.abort(new Error('the response was cancelled'));
+        return;
+      }
+      await sink.end();
+      if (done !== undefined) done();
+    }
+    catch (err) {
+      // a source that threw, or a sink that failed: the body is cut
+      await cancel();
+      await sink.abort(err).catch(() => undefined);
+    }
+  })();
+}
+
 /**
  * Whether the request could carry a body the operation reads.
  * @param {string} method
@@ -99,23 +303,6 @@ function headersOf(req) {
   return out;
 }
 
-/**
- * Concatenate collected chunks into one Uint8Array.
- * @param {Uint8Array[]} chunks
- * @param {number} total
- * @returns {Uint8Array}
- */
-function concat(chunks, total) {
-  if (chunks.length === 1) return chunks[0];
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (let i = 0; i < chunks.length; i++) {
-    out.set(chunks[i], offset);
-    offset += chunks[i].byteLength;
-  }
-  return out;
-}
-
 /**
  * Write a dispatcher response to the platform response.
  * @param {NodeResponseLike} res
@@ -128,30 +315,26 @@ function send(res, response, close, done) {
   const headers = { ...response.headers };
   if (typeof response.stream === 'function') {
     // an SSE response: headers out immediately, then the pump writes
-    // events until the stream ends (the pump ends the response itself);
-    // the peer-gone path runs through the request's abort signal
+    // events until the stream ends (the pump ends the response itself),
+    // each event only once the previous one drained; the peer-gone path
+    // runs through the request's abort signal
     res.writeHead(response.status, headers);
     if (typeof res.flushHeaders === 'function') res.flushHeaders();
-    response.stream({
-      write: (chunk) => {
-        if (typeof res.write === 'function') res.write(chunk);
-      },
-      end: () => {
-        try {
-          res.end();
-        }
-        catch {
-          // the socket may already be gone
-        }
-      },
-    });
+    response.stream(responseSink(res));
     return;
   }
   const body = response.body;
+  if (close) headers.connection = 'close';
+  if (body !== null && typeof body === 'object' && !(body instanceof Uint8Array)) {
+    // a streamed body: chunked, each chunk behind the previous one's
+    // drain; the peer going away cancels the source once
+    res.writeHead(response.status, headers);
+    pumpBody(res, body, done);
+    return;
+  }
   if (body !== null && headers['content-length'] === undefined) {
     headers['content-length'] = String(typeof body === 'string' ? new TextEncoder().encode(body).byteLength : body.byteLength);
   }
-  if (close) headers.connection = 'close';
   res.writeHead(response.status, headers);
   if (body === null) res.end(undefined, done);
   else res.end(body, done);
@@ -214,10 +397,18 @@ export function toNodeHandler(dispatcher, options = {}) {
     const finish = (response, close) => {
       send(res, response, close, close ? lingerThenDestroy : undefined);
     };
-    /** @param {string | Uint8Array | null} body @param {boolean} close */
-    const answer = (body, close) => {
+    /**
+     * Dispatch and answer. A request whose upload was pulled and left
+     * unread (a limit crossing, a response before EOF) cannot keep its
+     * connection: the answer carries `connection: close` and the socket
+     * lingers, draining and discarding the rest, before it is destroyed
+     * — so the 413 is readable through a FIN, never lost to an RST. An
+     * upload that was never pulled is the platform's to discard.
+     * @param {(AsyncIterable<Uint8Array> & { state: { started: boolean, ended: boolean, cancelled: boolean } }) | null} body
+     */
+    const answer = (body) => {
       dispatcher.dispatch({ method, url, headers, body, signal: controller.signal })
-        .then((response) => finish(response, close), (err) => {
+        .then((response) => finish(response, body !== null && body.state.started && !body.state.ended), (err) => {
           // only JC1004 can arrive here, and this adapter builds a
           // well-formed request; still, a rejection must not hang the socket
           const message = err instanceof Error ? err.message : String(err);
@@ -231,46 +422,19 @@ export function toNodeHandler(dispatcher, options = {}) {
       if (hit === null && method === 'HEAD' && head) hit = contract.match('GET', path);
     }
     if (hit === null) {
-      answer(null, false);
+      answer(null);
       return;
     }
-    const op = hit.op;
-    const limit = op.policy.limits.maxBodyBytes;
+    const limit = hit.op.policy.limits.maxBodyBytes;
     const declared = Number(headers['content-length']);
     if (Number.isFinite(declared) && declared > limit) {
       // the dispatcher answers the 413 from the header; the body is never read
-      answer(null, false);
+      answer(null);
       return;
     }
-
-    /** @type {Uint8Array[]} */
-    const chunks = [];
-    let total = 0;
-    let settled = false;
-    req.on('data', (chunk) => {
-      if (settled) return;
-      const bytes = /** @type {Uint8Array} */ (chunk);
-      total += bytes.byteLength;
-      if (total > limit) {
-        settled = true;
-        if (typeof req.pause === 'function') req.pause();
-        // an oversize stream: the bytes read so far already exceed the
-        // limit, so the dispatcher answers the 413 from that length
-        // without a body; the request is destroyed after the response
-        // has flushed
-        headers['content-length'] = String(total);
-        answer(null, true);
-        return;
-      }
-      chunks.push(bytes);
-    });
-    req.on('end', () => {
-      if (settled) return;
-      settled = true;
-      answer(total === 0 ? null : concat(chunks, total), false);
-    });
-    req.on('error', () => {
-      settled = true;
-    });
+    // the body reaches the dispatcher as a pull source: a JSON operation
+    // drains it under its limit there, an opaque handler pulls it chunk
+    // by chunk, and nothing is collected here
+    answer(requestSource(req));
   };
 }