@jarenjs/contract 0.43.3 → 0.46.5

package/dist/types/adapters/node.d.ts

@@ -8,8 +8,10 @@
  *
  * 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 the request is destroyed once
- * the response has flushed. A declared `content-length` above the limit
+ * 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
  * dispatcher answers 404/405 without it and the platform discards the
  * rest). Bytes are handed to the dispatcher as received — for a JSON
@@ -26,7 +28,10 @@ export type NodeRequestLike = {
     headers: Record<string, string | string[] | undefined>;
     on: (event: string, listener: (...args: any[]) => void) => unknown;
     pause?: () => unknown;
+    resume?: () => unknown;
     destroy?: (error?: Error) => unknown;
+    readableEnded?: boolean;
+    destroyed?: boolean;
 };
 export type NodeResponseLike = {
     writeHead: (status: number, headers?: Record<string, string>) => unknown;
@@ -40,8 +45,14 @@ export type NodeResponseLike = {
 /**
  * Put a dispatcher behind Node's `(req, res)` listener.
  * @param {HttpDispatcher} dispatcher
+ * @param {{ lingerMs?: number }} [options] - `lingerMs` bounds how long a
+ *   closing response waits, draining the peer's unfinished upload, before
+ *   the socket is destroyed (default 1000 ms; see the linger comment
+ *   below — it is what keeps an overflow 413 readable through the close).
  * @returns {(req: NodeRequestLike, res: NodeResponseLike) => void}
  * @example
  * http.createServer(toNodeHandler(serveHttp(contract, handlers))).listen(8080);
  */
-export declare function toNodeHandler(dispatcher: HttpDispatcher): (req: NodeRequestLike, res: NodeResponseLike) => void;
+export declare function toNodeHandler(dispatcher: HttpDispatcher, options?: {
+    lingerMs?: number;
+}): (req: NodeRequestLike, res: NodeResponseLike) => void;

package/docs/CONTRACT-FORMAT.md

@@ -962,8 +962,12 @@ the platform:
 - **`toNodeHandler(dispatcher)`** (`@jarenjs/contract/node`) → `(req,
   res)` — `http.createServer`'s listener and Express middleware. It
   collects the body chunk by chunk up to the operation's limit; on
-  overflow it stops reading, answers the 413 with `connection: close`
-  and destroys the request once the response has flushed; a declared
+  overflow it stops reading, answers the 413 with `connection: close`,
+  then lingers — draining and discarding the rest of the upload, bounded
+  by a grace timer (`toNodeHandler(dispatcher, { lingerMs })`, default
+  1000 ms) — before destroying the request, so the close is a FIN the
+  client can read the 413 through rather than an RST that discards it
+  (winsock drops buffered receive data on RST); a declared
   `content-length` above the limit is never read; an unmatched request's
   body is never read. Bytes reach the dispatcher as received (its strict
   UTF-8 decode decides `JC2005`); repeated header lines arrive as arrays

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/contract",
   "private": false,
-  "version": "0.43.3",
+  "version": "0.46.5",
   "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.43.3",
-    "@jarenjs/json": "^0.43.3",
-    "@jarenjs/validate": "^0.43.3",
-    "@jarenjs/emit": "^0.43.3"
+    "@jarenjs/core": "^0.46.5",
+    "@jarenjs/json": "^0.46.5",
+    "@jarenjs/validate": "^0.46.5",
+    "@jarenjs/emit": "^0.46.5"
   }
 }

package/src/adapters/node.js

@@ -9,8 +9,10 @@
  *
  * 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 the request is destroyed once
- * the response has flushed. A declared `content-length` above the limit
+ * 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
  * dispatcher answers 404/405 without it and the platform discards the
  * rest). Bytes are handed to the dispatcher as received — for a JSON
@@ -33,9 +35,18 @@
  * @property {Record<string, string | string[] | undefined>} headers
  * @property {(event: string, listener: (...args: any[]) => void) => unknown} on
  * @property {() => unknown} [pause]
+ * @property {() => unknown} [resume]
  * @property {(error?: Error) => unknown} [destroy]
+ * @property {boolean} [readableEnded]
+ * @property {boolean} [destroyed]
  */
 
+/** How long a closing response waits for the peer's upload to end before
+ * destroying the socket anyway. Long enough for a client that finishes
+ * writing once it sees the response; short enough that a peer that never
+ * stops cannot hold the socket. The timer is unref'd. */
+const LINGER_MS = 1000;
+
 /**
  * The response surface the adapter writes — `http.ServerResponse` fits.
  * `write` and `flushHeaders` are read only for a streaming (SSE)
@@ -149,14 +160,20 @@ function send(res, response, close, done) {
 /**
  * Put a dispatcher behind Node's `(req, res)` listener.
  * @param {HttpDispatcher} dispatcher
+ * @param {{ lingerMs?: number }} [options] - `lingerMs` bounds how long a
+ *   closing response waits, draining the peer's unfinished upload, before
+ *   the socket is destroyed (default 1000 ms; see the linger comment
+ *   below — it is what keeps an overflow 413 readable through the close).
  * @returns {(req: NodeRequestLike, res: NodeResponseLike) => void}
  * @example
  * http.createServer(toNodeHandler(serveHttp(contract, handlers))).listen(8080);
  */
-export function toNodeHandler(dispatcher) {
+export function toNodeHandler(dispatcher, options = {}) {
   if (dispatcher === null || typeof dispatcher !== 'object' || typeof dispatcher.dispatch !== 'function') {
     throw new TypeError('toNodeHandler: the argument must be a dispatcher from serveHttp');
   }
+  const lingerMs = typeof options.lingerMs === 'number' && options.lingerMs >= 0
+    ? options.lingerMs : LINGER_MS;
   const contract = dispatcher.contract;
   const head = dispatcher.capabilities.head;
 
@@ -172,9 +189,30 @@ export function toNodeHandler(dispatcher) {
       if (res.writableFinished !== true) controller.abort();
     });
 
+    // Closing a socket with unread data in its receive buffer sends RST,
+    // and winsock discards buffered receive data on RST — the flushed 413
+    // would never reach a Windows client. So the close lingers: resume the
+    // paused request so what is still arriving drains and discards (the
+    // settled guard below already ignores it), and destroy only after a
+    // grace window, which closes with FIN and leaves the response
+    // readable. No request event can drive this — once the response has
+    // finished, a paused, unconsumed request emits nothing further — so
+    // the window is a plain unref'd timer.
+    const lingerThenDestroy = () => {
+      if (typeof req.destroy !== 'function' || req.destroyed === true) return;
+      if (req.readableEnded === true) {
+        req.destroy();
+        return;
+      }
+      if (typeof req.resume === 'function') req.resume();
+      const timer = setTimeout(() => {
+        if (req.destroyed !== true) req.destroy();
+      }, lingerMs);
+      if (typeof timer.unref === 'function') timer.unref();
+    };
     /** @param {import('../http/wire.js').HttpResponse} response @param {boolean} close */
     const finish = (response, close) => {
-      send(res, response, close, close ? () => { if (typeof req.destroy === 'function') req.destroy(); } : undefined);
+      send(res, response, close, close ? lingerThenDestroy : undefined);
     };
     /** @param {string | Uint8Array | null} body @param {boolean} close */
     const answer = (body, close) => {

package/src/client/http.js

@@ -956,6 +956,17 @@ export function openHttpClient(contract, options = {}) {
       const body = /** @type {any} */ (response).body;
       if (typeof contentType !== 'string' || contentType.toLowerCase().indexOf(STREAM_MEDIA) === -1
         || body === null || body === undefined || typeof body.getReader !== 'function') {
+        // a refused stream still holds a live response body; release it,
+        // or the transport keeps the connection reserved for a read that
+        // will never come
+        try {
+          if (body !== null && body !== undefined && typeof body.cancel === 'function') {
+            Promise.resolve(body.cancel()).catch(() => {});
+          }
+        }
+        catch {
+          // cancellation is best-effort; the outcome below is the answer
+        }
         consumer.fail(failedOutcome('contract',
           outcomeError('JC2090', renderMessage(catalog, STREAM_ERRORS.JC2090.msgid, { op: route.id }), status, null, false), meta));
         return;