@procedures/client 0.5.0 → 0.7.0

package/src/adapters/http/server/ndjson.ts

@@ -0,0 +1,259 @@
+/**
+ * The writer of an NDJSON stream response (wire protocol v1, `documentation/WIRE-PROTOCOL.md`).
+ *
+ * `HttpServerTransport` writes each NDJSON stream with `writeNdjsonStream`. A server without
+ * Express can use the function too: it takes a `ServerResponse` of `node:http`. This module
+ * imports only the types of `node:http`, so it loads no Node code at run time.
+ */
+
+import type { ServerResponse } from "node:http";
+import { realClock, type Cancel, type Clock } from "../../../clock.js";
+import { toMs, type Duration } from "../../../duration.js";
+import { PROTOCOL_HEADER, PROTOCOL_VERSION, errorCodeOf } from "../../../protocol.js";
+import { TIMER_DEFAULTS } from "../../../timers.js";
+
+/** The media type of a stream response: one JSON value on each line. */
+export const NDJSON_MEDIA_TYPE = "application/x-ndjson";
+
+/** The keep-alive line of an NDJSON stream: a blank line. A reader skips it. It has no `seq`. */
+export const KEEP_ALIVE_LINE = "\n";
+
+/** The longest delay of a Node timer. A longer delay starts the timer at once. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/** The error of an `error` line: its code, its message and its retryable flag. */
+export interface NdjsonError {
+  code: string;
+  message: string;
+  retryable: boolean;
+}
+
+/** The options of `writeNdjsonStream`. */
+export interface WriteNdjsonStreamOptions {
+  /**
+   * The signal of the request. Its abort stops the stream. The iterator of the items gets
+   * `return()`, and a response that is still open gets the error line `ABORTED`.
+   */
+  readonly signal?: AbortSignal | undefined;
+  /**
+   * The quiet time after which the writer sends a keep-alive line. Each line starts the time again.
+   * `false`, or a duration of zero or less, sends no keep-alive line.
+   * @default seconds(15) (`TIMER_DEFAULTS.httpServer.keepAliveMs`)
+   */
+  readonly keepAlive?: Duration | false | undefined;
+  /**
+   * The function that gives the `error` line of an error of the stream. The default gives the code
+   * of the error (`errorCodeOf`), its message and its own retryable flag, or `false`.
+   */
+  readonly errorOf?: ((error: unknown) => NdjsonError) | undefined;
+  /**
+   * The clock of the keep-alive timer (roadmap R35). The default is the clock of the platform. A
+   * test gives a fake clock.
+   */
+  readonly clock?: Clock | undefined;
+}
+
+/**
+ * This function gives the `error` line of a thrown error: its code, its message and its retryable
+ * flag (deep dive TRN-7). A code that is not a string gives `HANDLER_ERROR`.
+ */
+export function defaultNdjsonError(error: unknown): NdjsonError {
+  const retryable = (error as { retryable?: unknown } | null | undefined)?.retryable;
+  return {
+    code: errorCodeOf(error),
+    message: error instanceof Error ? error.message : String(error),
+    retryable: typeof retryable === "boolean" ? retryable : false,
+  };
+}
+
+/**
+ * This function gives the keep-alive time in milliseconds, or 0 for no keep-alive. A value that is
+ * not a duration throws a `TypeError`.
+ */
+export function keepAliveMsOf(keepAlive: Duration | false | undefined): number {
+  if (keepAlive === false) return 0;
+  if (keepAlive === undefined) return TIMER_DEFAULTS.httpServer.keepAliveMs;
+  const value = toMs(keepAlive, "keepAlive");
+  return value > 0 ? Math.min(value, MAX_TIMER_DELAY_MS) : 0;
+}
+
+/** One JSON line of the stream. */
+function lineOf(frame: unknown): string {
+  return `${JSON.stringify(frame)}\n`;
+}
+
+/**
+ * This function gives the next result of the iterator, or `undefined` when the stop signal
+ * aborts first. Thus a quiet iterator does not keep a stopped stream open. The listener goes
+ * away after each step, so a long stream adds no listener.
+ */
+function nextOrStop<T>(iterator: AsyncIterator<T>, stop: AbortSignal): Promise<IteratorResult<T> | undefined> {
+  if (stop.aborted) return Promise.resolve(undefined);
+  return new Promise<IteratorResult<T> | undefined>((resolve, reject) => {
+    const onStop = (): void => resolve(undefined);
+    stop.addEventListener("abort", onStop, { once: true });
+    Promise.resolve(iterator.next()).then(
+      (result) => {
+        stop.removeEventListener("abort", onStop);
+        resolve(result);
+      },
+      (error: unknown) => {
+        stop.removeEventListener("abort", onStop);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * This function waits until the response can take more data: the `drain` event. A closed
+ * connection or the stop signal also ends the wait (deep dive TRN-3).
+ */
+function drained(res: ServerResponse, stop: AbortSignal): Promise<void> {
+  if (stop.aborted) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    const done = (): void => {
+      res.off("drain", done);
+      res.off("close", done);
+      stop.removeEventListener("abort", done);
+      resolve();
+    };
+    res.on("drain", done);
+    res.on("close", done);
+    stop.addEventListener("abort", done, { once: true });
+  });
+}
+
+/**
+ * This function writes a stream of items as an NDJSON response of wire protocol v1.
+ *
+ * - It writes the status 200, the headers `Content-Type: application/x-ndjson`,
+ *   `Cache-Control: no-cache` and `Procedures-Protocol: 1`, and it sends them at once.
+ * - Each item gives the line `{"type":"item","seq":n,"payload":...}`. The `seq` counts from 1.
+ * - The end of the items gives `{"type":"done","seq":n}`. An error gives
+ *   `{"type":"error","error":{"code":...,"message":...,"retryable":...}}`, without `seq`.
+ * - After each quiet time of `keepAlive`, it writes a keep-alive line: a blank line. Each line
+ *   starts the time again. No keep-alive line comes after the last line.
+ * - When `write()` gives false, it waits for `drain` before it reads the next item.
+ * - A closed connection or an abort of `signal` stops it. The iterator gets `return()`. After an
+ *   abort, a response that is still open gets the error line `ABORTED`.
+ *
+ * The promise resolves when the response ends. It does not reject: an error of the items becomes
+ * the error line.
+ */
+export async function writeNdjsonStream(res: ServerResponse, items: AsyncIterable<unknown>, options: WriteNdjsonStreamOptions = {}): Promise<void> {
+  const interval = keepAliveMsOf(options.keepAlive);
+  const clock = options.clock ?? realClock;
+  const errorOf = options.errorOf ?? defaultNdjsonError;
+  const { signal } = options;
+
+  // One stop for the abort of the caller and for a closed connection
+  const stop = new AbortController();
+  const onAbort = (): void => stop.abort();
+  const onClose = (): void => {
+    if (!res.writableFinished) stop.abort();
+  };
+  if (signal?.aborted || res.destroyed) stop.abort();
+  signal?.addEventListener("abort", onAbort, { once: true });
+  res.on("close", onClose);
+
+  // The keep-alive timer. Each line starts the quiet time again, but a line does not start a new
+  // timer: when the timer comes due, it examines the time of the last line. Thus a fast stream
+  // has one timer for each quiet time, not one for each item.
+  let timer: Cancel | undefined;
+  let lastLine = 0;
+  const stopTimer = (): void => {
+    timer?.();
+    timer = undefined;
+  };
+  const arm = (delay: number): void => {
+    timer = clock.after(delay, keepAlive);
+    timer.unref?.();
+  };
+  /** This function records a line: the quiet time starts again. */
+  const startTimer = (): void => {
+    lastLine = clock.now();
+    if (timer === undefined && interval > 0 && !stop.signal.aborted && !res.writableEnded) arm(interval);
+  };
+  function keepAlive(): void {
+    timer = undefined;
+    if (stop.signal.aborted || res.writableEnded || res.destroyed) return;
+    const quiet = clock.now() - lastLine;
+    if (quiet < interval) {
+      // A line went out after the start of this timer: wait for the rest of the quiet time
+      arm(interval - quiet);
+      return;
+    }
+    // A full buffer waits for the reader. One more byte there does not reach the reader sooner.
+    if (!res.writableNeedDrain) res.write(KEEP_ALIVE_LINE);
+    startTimer();
+  }
+
+  /** This function ends an open response after an abort: the server stopped the request. */
+  const endAborted = (): void => {
+    if (!res.writableEnded && !res.destroyed) {
+      res.end(lineOf({ type: "error", error: { code: "ABORTED", message: "The server stopped the request", retryable: true } }));
+    }
+  };
+
+  const iterator = items[Symbol.asyncIterator]();
+  /** True when the iterator ended by itself: at its end, or with an error */
+  let ended = false;
+  let seq = 0;
+  try {
+    if (!res.headersSent && !res.destroyed) {
+      res.statusCode = 200;
+      res.setHeader(PROTOCOL_HEADER, String(PROTOCOL_VERSION));
+      res.setHeader("Content-Type", NDJSON_MEDIA_TYPE);
+      res.setHeader("Cache-Control", "no-cache");
+      res.flushHeaders();
+    }
+    startTimer();
+    for (;;) {
+      let next: IteratorResult<unknown> | undefined;
+      try {
+        next = await nextOrStop(iterator, stop.signal);
+      } catch (error) {
+        ended = true;
+        throw error;
+      }
+      if (next === undefined) break;
+      if (next.done) {
+        ended = true;
+        break;
+      }
+      if (stop.signal.aborted) break;
+      const room = res.write(lineOf({ type: "item", seq: ++seq, payload: next.value }));
+      startTimer();
+      if (!room) await drained(res, stop.signal);
+      if (stop.signal.aborted) break;
+    }
+    stopTimer();
+    if (stop.signal.aborted) {
+      endAborted();
+      return;
+    }
+    res.end(lineOf({ type: "done", seq: ++seq }));
+  } catch (error) {
+    stopTimer();
+    if (stop.signal.aborted) {
+      endAborted();
+      return;
+    }
+    let info: NdjsonError;
+    try {
+      info = errorOf(error);
+    } catch {
+      // A failed errorOf does not leave the response open
+      info = defaultNdjsonError(error);
+    }
+    res.end(lineOf({ type: "error", error: info }));
+  } finally {
+    stopTimer();
+    signal?.removeEventListener("abort", onAbort);
+    res.off("close", onClose);
+    // A stream that stopped early: its producer stops too. A pending next() keeps the return()
+    // waiting, so the writer does not wait for it.
+    if (!ended) void Promise.resolve().then(() => iterator.return?.()).catch(() => undefined);
+  }
+}

package/src/adapters/http/server/transport.ts

@@ -17,10 +17,10 @@ import type { HttpServerTransportOptions } from "./types.js";
 import { createPatternServerUrlStrategy } from "./strategies.js";
 import { checkBrowserRequest, type BrowserGuardOptions } from "../../../server/browser-guard.js";
 import { bearerOf, withoutSecretHeaders } from "../../../server/request-auth.js";
-import { PROTOCOL_HEADER, PROTOCOL_VERSION, errorCodeOf, httpStatusOf, protocolVersionOf } from "../../../protocol.js";
-
-/** The media type of a stream response: one JSON value on each line. */
-const NDJSON = "application/x-ndjson";
+import { PROTOCOL_HEADER, PROTOCOL_VERSION, httpStatusOf, protocolVersionOf } from "../../../protocol.js";
+import { realClock, type Clock } from "../../../clock.js";
+import { ms, type Duration } from "../../../duration.js";
+import { NDJSON_MEDIA_TYPE as NDJSON, defaultNdjsonError as errorOf, keepAliveMsOf, writeNdjsonStream } from "./ndjson.js";
 
 /** True when a stream response can run without an end (`STREAM_METADATA_KEY` of procedure-server.ts). */
 function isUnboundedStream(response: { metadata?: Record<string, unknown> | undefined }): boolean {
@@ -40,36 +40,6 @@ class BodyError extends Error {
   }
 }
 
-/** The code and message of a thrown error, with its retryable flag (deep dive TRN-7). */
-function errorOf(error: unknown): { code: string; message: string; retryable: boolean } {
-  const retryable = (error as { retryable?: unknown } | undefined)?.retryable;
-  return {
-    code: errorCodeOf(error),
-    message: error instanceof Error ? error.message : String(error),
-    retryable: typeof retryable === "boolean" ? retryable : false,
-  };
-}
-
-/**
- * Write one chunk. When the response's buffer is full, wait for "drain", or for the end of the
- * request (deep dive TRN-3: before, the server ignored the result of write() and ran a stream
- * to its end whatever the reader did).
- */
-function write(res: Response, chunk: string, signal: AbortSignal): Promise<void> {
-  if (res.write(chunk) || signal.aborted) return Promise.resolve();
-  return new Promise<void>((resolve) => {
-    const done = (): void => {
-      res.off("drain", done);
-      res.off("close", done);
-      signal.removeEventListener("abort", done);
-      resolve();
-    };
-    res.on("drain", done);
-    res.on("close", done);
-    signal.addEventListener("abort", done, { once: true });
-  });
-}
-
 /**
  * HTTP server transport adapter for Express.
  *
@@ -108,7 +78,7 @@ export class HttpServerTransport implements ServerTransport {
   private options: Required<
     Omit<
       HttpServerTransportOptions,
-      "app" | "corsOptions" | "httpServer" | "bodyLimit" | "allowedOrigins" | "allowedHosts" | "allowGet"
+      "app" | "corsOptions" | "httpServer" | "bodyLimit" | "allowedOrigins" | "allowedHosts" | "allowGet" | "keepAlive" | "clock"
     >
   > & {
     corsOptions: HttpServerTransportOptions["corsOptions"] | undefined;
@@ -121,6 +91,10 @@ export class HttpServerTransport implements ServerTransport {
   private readonly bodyLimit: number;
   /** The browser checks of each procedure call (see `server/browser-guard.ts`) */
   private readonly guard: BrowserGuardOptions;
+  /** The quiet time of an NDJSON stream before a keep-alive line, or false for none */
+  private readonly keepAlive: Duration | false;
+  /** The clock of the keep-alive timers (roadmap R35) */
+  private readonly clock: Clock;
 
   constructor(server: RequestHandler, options: HttpServerTransportOptions = {}) {
     this.server = server;
@@ -138,6 +112,10 @@ export class HttpServerTransport implements ServerTransport {
       httpServer: options.httpServer,
     };
     this.bodyLimit = options.bodyLimit ?? 1024 * 1024;
+    // A value that is not a duration fails here, not at the first stream
+    const keepAliveMs = keepAliveMsOf(options.keepAlive);
+    this.keepAlive = keepAliveMs > 0 ? ms(keepAliveMs) : false;
+    this.clock = options.clock ?? realClock;
     this.guard = {
       allowedOrigins: options.allowedOrigins ?? corsOrigins(options),
       allowedHosts: options.allowedHosts,
@@ -341,16 +319,14 @@ export class HttpServerTransport implements ServerTransport {
     }
   }
 
-  /**
-   * Convert HTTP request to ServerRequest.
-   */
   /**
    * Send a stream response.
    *
    * A client that accepts `application/x-ndjson` gets one JSON line for each item
    * (`{"type":"item","seq":1,"payload":...}`), then `{"type":"done","seq":...}`, or
    * `{"type":"error","error":...}`. The `seq` of the lines counts from 1, as in the `stream`
-   * frames of WebSocket.
+   * frames of WebSocket. A quiet stream gets a keep-alive line, a blank line, after each quiet
+   * time of `keepAlive`. `writeNdjsonStream` writes these lines.
    * Another client (curl, a browser fetch without the header) gets the last item as plain JSON,
    * the "sponge" mode, so a streaming procedure does not change its response format.
    */
@@ -406,37 +382,13 @@ export class HttpServerTransport implements ServerTransport {
       return;
     }
 
-    res.status(200);
-    res.setHeader("Content-Type", NDJSON);
-    res.setHeader("Cache-Control", "no-cache");
-    res.flushHeaders();
-    // stop() aborted the request while the reader still listens: end the stream with an error
-    const endAborted = (): void => {
-      if (!res.writableEnded && !res.destroyed) {
-        res.end(JSON.stringify({ type: "error", error: { code: "ABORTED", message: "The server stopped the request", retryable: true } }) + "\n");
-      }
-    };
-    let seq = 0;
-    try {
-      for await (const item of stream) {
-        if (signal.aborted) break;
-        await write(res, JSON.stringify({ type: "item", seq: ++seq, payload: item }) + "\n", signal);
-        if (signal.aborted) break;
-      }
-      if (signal.aborted) {
-        endAborted();
-        return;
-      }
-      res.end(JSON.stringify({ type: "done", seq: ++seq }) + "\n");
-    } catch (error) {
-      if (signal.aborted) {
-        endAborted();
-        return;
-      }
-      res.end(JSON.stringify({ type: "error", error: errorOf(error) }) + "\n");
-    }
+    // The lines, the backpressure, the keep-alive and the abort of stop() (WIRE-PROTOCOL.md)
+    await writeNdjsonStream(res, stream, { signal, keepAlive: this.keepAlive, errorOf, clock: this.clock });
   }
 
+  /**
+   * This method converts an HTTP request to a `ServerRequest`.
+   */
   private httpToServerRequest(req: Request, body: unknown): ServerRequest | null {
     // Parse method from URL using strategy
     const method = this.options.urlStrategy(req);

package/src/adapters/http/server/types.ts

@@ -8,6 +8,8 @@ import type { Request, Express } from "express";
 import type { Server as HttpServer } from "http";
 import type { Method } from "../../../client/types.js";
 import type { BrowserGuardOptions } from "../../../server/browser-guard.js";
+import type { Clock } from "../../../clock.js";
+import type { Duration } from "../../../duration.js";
 
 /**
  * URL strategy for converting HTTP requests to RPC methods.
@@ -68,6 +70,21 @@ export interface HttpServerTransportOptions extends BrowserGuardOptions {
    */
   bodyLimit?: number;
 
+  /**
+   * The quiet time of an NDJSON stream. After it, the server writes a keep-alive line: a blank
+   * line. Each line of the stream starts the time again. Thus a proxy or a client with an idle
+   * timeout does not close a quiet stream. `false`, or a duration of zero or less, sends no
+   * keep-alive line.
+   * @default seconds(15) (`TIMER_DEFAULTS.httpServer.keepAliveMs`)
+   */
+  keepAlive?: Duration | false;
+
+  /**
+   * The clock of the keep-alive timers (roadmap R35). The default is the clock of the platform. A
+   * test gives a fake clock.
+   */
+  clock?: Clock;
+
   /**
    * Custom CORS options. `origin` is "*", one origin or a list: the response names the
    * request's origin when it is in the list.

package/src/adapters/sequence.ts

@@ -10,6 +10,8 @@
  *   number of lost frames in its metadata key `stream-gap`, and the caller writes a warning. The
  *   caller also gives back the credit of the lost frames.
  * - A frame without `seq` comes from an older peer. The caller takes it as before.
+ * - A blank line of an NDJSON stream is a keep-alive line. It is not a frame and it has no `seq`,
+ *   so the reader skips it before the check.
  */
 
 /**
@@ -18,6 +20,14 @@
  */
 export const STREAM_GAP_METADATA_KEY = "stream-gap";
 
+/**
+ * The metadata key of an item that the HTTP client transport read from an NDJSON stream. Its value
+ * is `true`. The receiver sets it. It does not cross the wire, and the receiver removes a key of
+ * this name that the peer sent. The constant `STREAM_METADATA_KEY` of the server has the same
+ * name, with the value `unbounded` in the metadata of a response.
+ */
+export const STREAM_ITEM_METADATA_KEY = "stream";
+
 /** The order of the stream frames of one call, at the side that receives them. */
 export class StreamSequence {
   private last = 0;
@@ -48,6 +58,14 @@ export function itemMetadata(metadata: Record<string, unknown> | undefined, gap:
   return out;
 }
 
+/**
+ * This function gives the metadata of an item of an NDJSON stream: the metadata of `itemMetadata`,
+ * and the key `stream` with the value `true`. The value of the peer for this key goes away.
+ */
+export function streamItemMetadata(metadata: Record<string, unknown> | undefined, gap: number): Record<string, unknown> {
+  return { ...itemMetadata(metadata, gap), [STREAM_ITEM_METADATA_KEY]: true };
+}
+
 /** The number of frames that did not arrive immediately before an item: 0 without a gap. */
 export function gapOf(metadata: Record<string, unknown> | undefined): number {
   const gap = metadata?.[STREAM_GAP_METADATA_KEY];

package/src/browser.ts

@@ -323,8 +323,9 @@ export type { TraceContext } from "./tracing/traceparent.js";
 // Wire protocol v1: the version and the one list of error codes (roadmap R25)
 export { PROTOCOL_VERSION, PROTOCOL_HEADER, ERROR_CODES, isProtocolErrorCode, httpStatusOf, protocolVersionOf } from "./protocol.js";
 export type { ProtocolErrorCode, ErrorCodeInfo } from "./protocol.js";
-// The seq of the stream frames: the metadata key of an item after a gap (WIRE-PROTOCOL.md)
-export { STREAM_GAP_METADATA_KEY } from "./adapters/sequence.js";
+// The seq of the stream frames: the metadata key of an item after a gap, and the key of an item
+// that the HTTP client read from an NDJSON stream (WIRE-PROTOCOL.md)
+export { STREAM_GAP_METADATA_KEY, STREAM_ITEM_METADATA_KEY } from "./adapters/sequence.js";
 // The deadline of a call: the remaining time goes as procedure-timeout (roadmap R10)
 export { TIMEOUT_METADATA_KEY, DEADLINE_METADATA_KEY } from "./client/deadline.js";
 // Typed durations: each public option that is a time takes a Duration (roadmap R11)

package/src/node.ts

@@ -5,7 +5,13 @@
  * uses the `WebSocket` class of the `ws` package, so a drop ends a socket at once with
  * `terminate()` (finding of roadmap R36). The other entries keep the global `WebSocket`: a browser
  * bundle imports `@procedures/client/browser`, and that entry does not import `ws`.
+ *
+ * This entry also exports `writeNdjsonStream`: the writer of an NDJSON stream response of wire
+ * protocol v1, for a `ServerResponse` of `node:http`. `HttpServerTransport` uses it, so a server
+ * without Express writes the same bytes.
  */
 
 export { WebSocketTransport } from "./adapters/websocket/client/node.js";
 export type { WebSocketTransportOptions, WebSocketClass } from "./adapters/websocket/client/types.js";
+export { writeNdjsonStream } from "./adapters/http/server/ndjson.js";
+export type { WriteNdjsonStreamOptions, NdjsonError } from "./adapters/http/server/ndjson.js";

package/src/server/procedure-server.ts

@@ -143,13 +143,16 @@ export function isUnboundedStream(response: { metadata?: Record<string, unknown>
 }
 
 /**
- * True when the presented token is the expected one. The comparison takes the same time for each
- * presented token of the same length, so the time does not tell the token.
+ * True when the presented token is the expected one. The comparison reads each character of the
+ * expected token for each presented token, so its time depends only on the expected token. The
+ * time tells neither the token nor its length. The function runs in a browser too, so it uses
+ * no `node:crypto`.
  */
 export function tokenMatches(expected: string, presented: string | undefined): boolean {
-  if (presented === undefined || presented.length !== expected.length) return false;
-  let difference = 0;
-  for (let index = 0; index < expected.length; index++) difference |= expected.charCodeAt(index) ^ presented.charCodeAt(index);
+  if (presented === undefined) return false;
+  // A difference of the lengths makes the result false, after the same loop as an equal length
+  let difference = expected.length ^ presented.length;
+  for (let index = 0; index < expected.length; index++) difference |= expected.charCodeAt(index) ^ (presented.charCodeAt(index) | 0);
   return difference === 0;
 }
 

package/src/timers.ts

@@ -47,6 +47,10 @@ export interface TimerDefaults {
     /** The time until the first frame of a call of the server to a client. */
     readonly reverseRequestTimeoutMs: number;
   };
+  readonly httpServer: {
+    /** The quiet time of an NDJSON stream. After it, the server writes a keep-alive line. */
+    readonly keepAliveMs: number;
+  };
   readonly idempotency: {
     /** The time that the server keeps the result of a keyed write. */
     readonly ttlMs: number;
@@ -77,6 +81,9 @@ export const TIMER_DEFAULTS: TimerDefaults = Object.freeze({
   // 15 s: with 2 misses, the server finds a dead client after 30 s, not later than a call of the
   // server to it reaches its request time of 30 s. Before, 30 s gave 60 s (the timer law, R34).
   webSocketServer: Object.freeze({ heartbeatIntervalMs: 15_000, heartbeatMisses: 2, reverseRequestTimeoutMs: 30_000 }),
+  // 15 s: less than the idle time of 60 s that many proxies and load balancers use. A quiet NDJSON
+  // stream then stays open (WIRE-PROTOCOL.md, "The keep-alive of an NDJSON stream").
+  httpServer: Object.freeze({ keepAliveMs: 15_000 }),
   idempotency: Object.freeze({ ttlMs: 10 * 60_000 }),
   server: Object.freeze({ stopGraceMs: 0 }),
 });