@procedures/client 0.41.1 → 0.42.0

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

@@ -0,0 +1,237 @@
+/**
+ * A batch of calls in one HTTP request (roadmap CLI-32).
+ *
+ * The client sends `POST {base}` with the header `Procedures-Batch: 1` and the body
+ * `{"calls": [{"id", "path", "input", "headers", "metadata"}]}`. The answer is one NDJSON stream.
+ * Each item of the stream is a frame that names its call: the value of a call, an item of its
+ * stream, the end of its stream, or its error. Each call runs through `handle()` as a call of its
+ * own, so the authentication, the limits and the error policy apply to each call. The frames of
+ * the calls come in the order of their arrival. Refer to "A batch of calls" in WIRE-PROTOCOL.md.
+ */
+
+import type { IncomingMessage } from "node:http";
+import type { Method, Metadata, Status } from "../../../client/types.js";
+import type { RequestHandler, ServerRequest, ServerResponse } from "../../../server/types.js";
+import { lastResortError } from "../../../server/last-resort.js";
+import { pathToMethod } from "../../../server/method.js";
+import { segmentsOf } from "./addressing.js";
+import type { NdjsonError } from "./ndjson.js";
+import { BodyError } from "./body.js";
+
+/** The request header of a batch, and of the answer of a server that took the batch. */
+export const BATCH_HEADER = "Procedures-Batch";
+
+/** The options of the batches of `procedureHandler`. */
+export interface HandlerBatchOptions {
+  /**
+   * The most calls in one batch. A batch with more calls gets the status 413 and the code
+   * `PAYLOAD_TOO_LARGE`, and no call runs.
+   * @default 64
+   */
+  readonly maxCalls?: number | undefined;
+  /**
+   * The most calls of one batch that run at the same time. The next call starts when a call ends.
+   * @default 8
+   */
+  readonly concurrency?: number | undefined;
+}
+
+/** The options of the batches, with each default. */
+export interface ResolvedBatchOptions {
+  readonly maxCalls: number;
+  readonly concurrency: number;
+}
+
+/** The defaults of `HandlerBatchOptions`. */
+export const BATCH_DEFAULTS = { maxCalls: 64, concurrency: 8 } as const;
+
+/** The longest id of a call in a batch. */
+export const BATCH_CALL_ID_LIMIT = 128;
+
+/** One call of a batch, as the body gives it. */
+export interface BatchCall {
+  /** The id of the call, unique in its batch. Each frame of the call names it. */
+  readonly id: string;
+  readonly method: Method;
+  /** The input of the procedure. Without `input`, the input is `{}`. */
+  readonly input: unknown;
+  /** The headers of the call, as the headers of a request of one call. */
+  readonly headers: Readonly<Record<string, string>>;
+  /** The custom metadata of the call, as the `X-Metadata` header of a request of one call. */
+  readonly metadata: Readonly<Record<string, unknown>> | undefined;
+}
+
+/** A frame of the answer of a batch: the payload of one NDJSON item. */
+export type BatchFrame =
+  | { readonly call: string; readonly type: "response"; readonly payload?: unknown }
+  | { readonly call: string; readonly type: "item"; readonly seq: number; readonly payload: unknown }
+  | { readonly call: string; readonly type: "done"; readonly seq: number }
+  | { readonly call: string; readonly type: "error"; readonly error: BatchError };
+
+/** The error of a call of a batch: the fields of the error body of one call. */
+export interface BatchError extends NdjsonError {
+  readonly reason?: string | undefined;
+  readonly retryAfterMs?: number | undefined;
+  readonly conflicts?: unknown[] | undefined;
+}
+
+/** True when the request is a batch: `POST` with the header `Procedures-Batch: 1`. */
+export function isBatchRequest(req: IncomingMessage): boolean {
+  return (req.method ?? "").toUpperCase() === "POST" && req.headers[BATCH_HEADER.toLowerCase()] === "1";
+}
+
+/** The resolved options of the batches, or undefined when the handler takes no batch. */
+export function batchOptionsOf(option: boolean | HandlerBatchOptions | undefined): ResolvedBatchOptions | undefined {
+  if (option === false) return undefined;
+  const given = option === true || option === undefined ? {} : option;
+  const count = (value: number | undefined, fallback: number, name: string): number => {
+    if (value === undefined) return fallback;
+    if (!Number.isInteger(value) || value < 1) throw new TypeError(`batch.${name} must be a positive integer, not ${String(value)}`);
+    return value;
+  };
+  return { maxCalls: count(given.maxCalls, BATCH_DEFAULTS.maxCalls, "maxCalls"), concurrency: count(given.concurrency, BATCH_DEFAULTS.concurrency, "concurrency") };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The calls of a batch body. A body that is not a batch throws a `BodyError` with the status 400,
+ * and a batch above `maxCalls` throws one with the status 413. Then no call runs.
+ */
+export function parseBatch(body: unknown, maxCalls: number): BatchCall[] {
+  const calls = isRecord(body) && Object.hasOwn(body, "calls") ? body["calls"] : undefined;
+  if (!Array.isArray(calls) || calls.length === 0) throw new BodyError('A batch body is {"calls": [...]} with one call or more', 400);
+  if (calls.length > maxCalls) throw new BodyError(`A batch has ${calls.length} calls, and the limit is ${maxCalls}`, 413);
+  const ids = new Set<string>();
+  return calls.map((value: unknown, index): BatchCall => {
+    if (!isRecord(value)) throw new BodyError(`The call ${index} of the batch is not an object`, 400);
+    const own = (key: string): unknown => (Object.hasOwn(value, key) ? value[key] : undefined);
+    const id = own("id");
+    if (typeof id !== "string" || id === "" || id.length > BATCH_CALL_ID_LIMIT) {
+      throw new BodyError(`The call ${index} of the batch needs an id: a text of 1 to ${BATCH_CALL_ID_LIMIT} characters`, 400);
+    }
+    if (ids.has(id)) throw new BodyError(`Two calls of the batch have the id "${id}"`, 400);
+    ids.add(id);
+    const path = segmentsOf(own("path"));
+    if (!path) throw new BodyError(`The call "${id}" of the batch has no valid path`, 400);
+    const headers = own("headers") ?? {};
+    if (!isRecord(headers) || !Object.values(headers).every((header) => typeof header === "string")) {
+      throw new BodyError(`The headers of the call "${id}" are not an object of texts`, 400);
+    }
+    const metadata = own("metadata");
+    if (metadata !== undefined && !isRecord(metadata)) throw new BodyError(`The metadata of the call "${id}" is not an object`, 400);
+    const input = own("input");
+    return { id, method: pathToMethod(path), input: input === undefined ? {} : input, headers: headers as Record<string, string>, metadata };
+  });
+}
+
+/** The error fields of an error response, as the error body of one call has them. */
+export function batchErrorOf(status: Extract<Status, { type: "error" }>, metadata: Metadata): BatchError {
+  const wait = metadata["retry-after"];
+  const reason = metadata["reason"];
+  const conflicts = metadata["conflicts"];
+  return {
+    code: status.code,
+    message: status.message,
+    retryable: status.retryable,
+    ...(typeof wait === "number" && Number.isFinite(wait) && wait >= 0 ? { retryAfterMs: wait } : {}),
+    ...(typeof reason === "string" ? { reason } : {}),
+    ...(Array.isArray(conflicts) ? { conflicts } : {}),
+  };
+}
+
+/** The frames of one call: its response, or the items and the end of its stream, or its error. */
+async function* callFrames(
+  server: RequestHandler,
+  call: string,
+  request: ServerRequest,
+  errorOf: (error: unknown, items: number) => NdjsonError,
+): AsyncGenerator<BatchFrame, void, undefined> {
+  let response: ServerResponse;
+  try {
+    response = await server.handle(request);
+  } catch (error) {
+    // The last-resort error of a call, as the face of one call sends it (CLI-80)
+    const exposed = lastResortError(server, error, request);
+    const wait = exposed.retryAfterMs;
+    yield {
+      call,
+      type: "error",
+      error: {
+        code: exposed.code,
+        message: exposed.message,
+        retryable: exposed.retryable === true,
+        ...(typeof wait === "number" && Number.isFinite(wait) && wait >= 0 ? { retryAfterMs: wait } : {}),
+      },
+    };
+    return;
+  }
+  if (response.stream) {
+    // The seq of the frames of a stream counts within the call, as in a stream of one call
+    let seq = 0;
+    try {
+      for await (const item of response.stream) yield { call, type: "item", seq: ++seq, payload: item };
+    } catch (error) {
+      yield { call, type: "error", error: errorOf(error, seq) };
+      return;
+    }
+    yield { call, type: "done", seq: ++seq };
+    return;
+  }
+  if (response.status.type === "error") {
+    yield { call, type: "error", error: batchErrorOf(response.status, response.metadata) };
+    return;
+  }
+  // No value: the frame has no payload, as a response of one call has no body (status 204)
+  yield response.payload === undefined ? { call, type: "response" } : { call, type: "response", payload: response.payload };
+}
+
+/** One call of a batch with its request. */
+export interface BatchRun {
+  readonly call: string;
+  readonly request: ServerRequest;
+}
+
+/**
+ * The frames of each call of a batch, in the order of their arrival. At most `concurrency` calls
+ * run at the same time. The function takes the next frame of a call only after the reader took the
+ * frame before it, so a slow reader slows each stream (backpressure). When the reader stops, each
+ * call that runs gets `return()`.
+ */
+export async function* batchFrames(
+  server: RequestHandler,
+  runs: readonly BatchRun[],
+  concurrency: number,
+  errorOf: (error: unknown, items: number) => NdjsonError,
+): AsyncGenerator<BatchFrame, void, undefined> {
+  type Next = { readonly key: number; readonly result: IteratorResult<BatchFrame, void> };
+  const running = new Map<number, { readonly iterator: AsyncIterator<BatchFrame, void>; next: Promise<Next> }>();
+  const pull = (key: number, iterator: AsyncIterator<BatchFrame, void>): Promise<Next> => iterator.next().then((result) => ({ key, result }));
+  let started = 0;
+  const start = (): void => {
+    while (running.size < concurrency && started < runs.length) {
+      const key = started++;
+      const run = runs[key]!;
+      const iterator = callFrames(server, run.call, run.request, errorOf);
+      running.set(key, { iterator, next: pull(key, iterator) });
+    }
+  };
+  try {
+    start();
+    while (running.size > 0) {
+      const { key, result } = await Promise.race(Array.from(running.values(), (entry) => entry.next));
+      const entry = running.get(key)!;
+      if (result.done) {
+        running.delete(key);
+        start();
+        continue;
+      }
+      yield result.value;
+      entry.next = pull(key, entry.iterator);
+    }
+  } finally {
+    for (const entry of running.values()) void Promise.resolve(entry.iterator.return?.()).catch(() => undefined);
+  }
+}

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

@@ -32,6 +32,7 @@ import { NDJSON_MEDIA_TYPE as NDJSON, defaultNdjsonError as errorOf, keepAliveMs
 import { applyCors, corsOrigins, corsPolicy, type CorsOptions, type CorsPolicy } from "./cors.js";
 import { urlAddressing, type Addressing } from "./addressing.js";
 import { BodyError, readJsonBody } from "./body.js";
+import { BATCH_HEADER, batchFrames, batchOptionsOf, isBatchRequest, parseBatch, type HandlerBatchOptions, type BatchRun } from "./batch.js";
 import { NARROWING_METADATA_KEY, addNarrowing } from "../../../procedures/narrowing.js";
 import { retryAfterSeconds } from "@mark1russell7/service/limiter";
 
@@ -107,6 +108,13 @@ export interface ProcedureHandlerOptions extends BrowserGuardOptions {
    * @default ["token"]
    */
   readonly secretQuery?: readonly string[] | undefined;
+  /**
+   * The batches of calls (roadmap CLI-32): `POST {basePath}` with the header `Procedures-Batch: 1`
+   * carries several calls, and the answer is one NDJSON stream of frames that name their call.
+   * Each call runs as a call of its own. `false` takes no batch: such a request goes on as before.
+   * @default { maxCalls: 64, concurrency: 8 }
+   */
+  readonly batch?: boolean | HandlerBatchOptions | undefined;
 }
 
 /**
@@ -196,7 +204,26 @@ const STANDARD_HEADERS = new Set([
 ]);
 
 /** The known custom headers whose metadata key is not the header name (lower case to camel case). */
-const HEADER_MAPPINGS: Record<string, string> = { collectionname: "collectionName" };
+/**
+ * The headers that a call of a batch cannot give (CLI-32): the headers of the connection, of the
+ * body, of the browser and of the protocol stay the headers of the HTTP request.
+ */
+const REQUEST_ONLY_HEADERS = new Set([
+  "host",
+  "connection",
+  "content-length",
+  "content-type",
+  "transfer-encoding",
+  "accept",
+  "accept-encoding",
+  "origin",
+  "referer",
+  "x-metadata",
+  "procedures-protocol",
+  "procedures-batch",
+]);
+
+const HEADER_MAPPINGS: Record<string, string> ={ collectionname: "collectionName" };
 
 /** This function sets a key as an own property, also the key `__proto__` (the `put` of the query language). */
 function put(target: Record<string, unknown>, key: string, value: unknown): void {
@@ -291,6 +318,7 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
   assertNamedOrigins(compat.face?.name ?? "procedureHandler", ambientMode, guard.allowedOrigins, compat.face?.originOption ?? "cors.origin");
   const secretHeaders = headerNames(options.secretHeaders);
   const secretQuery = new Set(options.secretQuery ?? (legacy ? [] : ["token"]));
+  const batch = batchOptionsOf(options.batch);
   // The addressing of a request (CLI-31): the option, or the URL strategy of the shim, or the URL
   // format of HttpTransport
   const compatMethodOf = compat.methodOf;
@@ -317,7 +345,14 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
   const matches = (req: IncomingMessage): boolean => {
     if (compat.matchAll === true) return true;
     const path = pathOf(req);
-    return path.startsWith(prefix) || (addressing.takesBasePath === true && path === bareBase);
+    return path.startsWith(prefix) || (path === bareBase && (addressing.takesBasePath === true || (batch !== undefined && isBatchRequest(req))));
+  };
+
+  /** True when the request is a batch at the base path (CLI-32). */
+  const isBatch = (req: IncomingMessage): boolean => {
+    if (batch === undefined || !isBatchRequest(req)) return false;
+    const path = pathOf(req);
+    return compat.matchAll === true || path === bareBase || path === prefix;
   };
 
   /** The error body of wire v1: the message, the code, the retryable flag and the more fields. */
@@ -340,9 +375,45 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
     const view: UrlRequest = { method: (req.method ?? "GET").toUpperCase(), path, url: req.url ?? "/", headers: req.headers, query: queryRecord(urlQuery) };
     const address = addressing(view, body, req);
     if (!address) return null;
-    const method = address.method;
-
     const id = (req.headers["x-request-id"] as string | undefined) ?? `req-${Date.now()}-${Math.random()}`;
+    const narrowing = req.headersDistinct?.[NARROWING_METADATA_KEY] ?? req.headers[NARROWING_METADATA_KEY];
+    return requestOf(req, { id, method: address.method, payload: address.payload, headers: req.headers, narrowing: [narrowing].flat(), custom: customOf(req.headers) });
+  };
+
+  /**
+   * The custom metadata of the `X-Metadata` header (deep dive TRN-11): any JSON value, any key.
+   * A header above the limit or a header that is not URI-encoded JSON throws a `BodyError`.
+   */
+  const customOf = (headers: IncomingHttpHeaders): Record<string, unknown>[] => {
+    const encoded = headers["x-metadata"];
+    if (typeof encoded !== "string") return [];
+    if (encoded.length > METADATA_HEADER_LIMIT) {
+      throw new BodyError(`The X-Metadata header is longer than ${METADATA_HEADER_LIMIT} characters`, 431);
+    }
+    const custom = decodeMetadataHeader(encoded);
+    if (!custom) throw new BodyError("The X-Metadata header is not URI-encoded JSON of an object", 400);
+    return [custom];
+  };
+
+  /**
+   * The `ServerRequest` of one call. A request of one call gives the headers of the HTTP request.
+   * A call of a batch gives the headers of the HTTP request with the headers of the call over
+   * them (CLI-32). The credentials always come from the HTTP request.
+   */
+  const requestOf = (
+    req: IncomingMessage,
+    call: {
+      readonly id: string;
+      readonly method: Method;
+      readonly payload: unknown;
+      readonly headers: IncomingHttpHeaders;
+      /** Each value of the narrowing header: each one is a source (CLI-30) */
+      readonly narrowing: readonly unknown[];
+      /** The custom metadata, in order: a later object replaces a key of an earlier one */
+      readonly custom: readonly Record<string, unknown>[];
+    }
+  ): ServerRequest => {
+    const { id, method, headers } = call;
 
     // The query without its secret parameters: they go into the credentials (CLI-2a)
     // An own property for each key, also `__proto__`: a key of the request changes no prototype
@@ -354,7 +425,7 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
     // query or params. The secret headers go into the credentials, not into the metadata, so a
     // handler and a nested call do not see them (roadmap R18)
     const metadata: Metadata = {
-      headers: withoutSecretHeaders(req.headers as Record<string, unknown>, secretHeaders),
+      headers: withoutSecretHeaders(headers as Record<string, unknown>, secretHeaders),
       query,
       params,
     };
@@ -364,7 +435,7 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
 
     // The custom headers at the root of the metadata, as the client's metadataToHeaders() sends
     // them. A secret header (Cookie too) does not go there.
-    for (const [key, value] of Object.entries(req.headers)) {
+    for (const [key, value] of Object.entries(headers)) {
       const lower = key.toLowerCase();
       if (STANDARD_HEADERS.has(lower) || isSecretHeader(lower, secretHeaders) || typeof value !== "string" || lower === NARROWING_METADATA_KEY) continue;
       const normalizedKey = HEADER_MAPPINGS[lower] ?? key;
@@ -372,17 +443,10 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
     }
     // Each value of the narrowing header is one source, also each line of a repeated header. No
     // source replaces another: a gateway's header and the client's key of X-Metadata both apply (CLI-30)
-    const narrowingHeader = req.headersDistinct?.[NARROWING_METADATA_KEY] ?? req.headers[NARROWING_METADATA_KEY];
-    for (const value of [narrowingHeader].flat()) if (typeof value === "string") setMetadata(metadata, NARROWING_METADATA_KEY, value);
+    for (const value of call.narrowing) if (typeof value === "string") setMetadata(metadata, NARROWING_METADATA_KEY, value);
 
     // The custom metadata of the HTTP client: any JSON value, any key (deep dive TRN-11)
-    const encoded = req.headers["x-metadata"];
-    if (typeof encoded === "string") {
-      if (encoded.length > METADATA_HEADER_LIMIT) {
-        throw new BodyError(`The X-Metadata header is longer than ${METADATA_HEADER_LIMIT} characters`, 431);
-      }
-      const custom = decodeMetadataHeader(encoded);
-      if (!custom) throw new BodyError("The X-Metadata header is not URI-encoded JSON of an object", 400);
+    for (const custom of call.custom) {
       for (const [key, value] of Object.entries(custom)) {
         if (!RESERVED_METADATA.has(key) && key !== "auth" && !key.startsWith("__")) setMetadata(metadata, key, value);
       }
@@ -390,7 +454,7 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
 
     // The payload of the addressing (the body, or the id of a RESTful GET). Only an absent payload
     // becomes {}: 0, false, "" and null stay (deep dive TRN-10)
-    const payload: unknown = address.payload === undefined ? {} : address.payload;
+    const payload: unknown = call.payload === undefined ? {} : call.payload;
 
     return {
       id,
@@ -405,6 +469,32 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
     };
   };
 
+  /**
+   * The runs of a batch (CLI-32). A bad body or a bad `X-Metadata` header throws a `BodyError`, and
+   * then no call runs. A header of a call cannot be a secret header, a header of the connection or
+   * a header of the body: the credentials and the body are the parts of the HTTP request.
+   */
+  const batchRuns = (req: IncomingMessage, body: unknown, signal: AbortSignal): BatchRun[] => {
+    const calls = parseBatch(body, batch!.maxCalls);
+    const outerCustom = customOf(req.headers);
+    const outerNarrowing = [req.headersDistinct?.[NARROWING_METADATA_KEY] ?? req.headers[NARROWING_METADATA_KEY]].flat();
+    const batchId = (req.headers["x-request-id"] as string | undefined) ?? `batch-${Date.now()}-${Math.random()}`;
+    return calls.map((call) => {
+      const headers: IncomingHttpHeaders = {};
+      for (const [key, value] of Object.entries(req.headers)) put(headers, key, value);
+      const narrowing = [...outerNarrowing];
+      for (const [key, value] of Object.entries(call.headers)) {
+        const lower = key.toLowerCase();
+        if (lower === NARROWING_METADATA_KEY) narrowing.push(value);
+        else if (!REQUEST_ONLY_HEADERS.has(lower) && !lower.startsWith("sec-") && !isSecretHeader(lower, secretHeaders)) put(headers, lower, value);
+      }
+      const custom = call.metadata ? [...outerCustom, call.metadata] : outerCustom;
+      const request = requestOf(req, { id: `${batchId}:${call.id}`, method: call.method, payload: call.input, headers, narrowing, custom });
+      request.signal = signal;
+      return { call: call.id, request };
+    });
+  };
+
   /** This function converts a `ServerResponse` to the HTTP response. */
   const toHttp = (serverResponse: ServerResponse, res: NodeResponse): void => {
     const { status, payload, metadata } = serverResponse;
@@ -517,6 +607,9 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
     if (cors && applyCors(req, res, cors)) return;
     // The protocol version of this server, on each response (roadmap R25)
     res.setHeader(PROTOCOL_HEADER, String(PROTOCOL_VERSION));
+    // A server that takes batches says so on each answer to a batch, also on an error. A client
+    // sends the calls of a batch alone after an answer without it (CLI-32).
+    if (isBatch(req)) res.setHeader(BATCH_HEADER, "1");
     const version = protocolVersionOf(req.headers[PROTOCOL_HEADER.toLowerCase()]);
     if (version !== undefined && version > PROTOCOL_VERSION) {
       sendJson(res, 400, {
@@ -557,14 +650,23 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
     });
     let serverRequest: ServerRequest | null = null;
     try {
+      let runs: BatchRun[] | undefined;
       try {
-        serverRequest = toServerRequest(req, await readBody(req));
+        const body = await readBody(req);
+        if (isBatch(req)) runs = batchRuns(req, body, controller.signal);
+        else serverRequest = toServerRequest(req, body);
       } catch (error) {
         const status = error instanceof BodyError ? error.httpStatus : 400;
         // A body above the limit is PAYLOAD_TOO_LARGE, as on the MCP face and the WebSocket face (CLI-85)
         sendError(res, status, (error as Error).message, status === 413 ? "PAYLOAD_TOO_LARGE" : "INVALID_REQUEST");
         return;
       }
+      if (runs) {
+        // One NDJSON stream for the calls of the batch: the lines, the backpressure and the
+        // keep-alive of a stream of one call (CLI-32)
+        await writeNdjsonStream(res, batchFrames(server, runs, batch!.concurrency, errorOf), { signal: controller.signal, keepAlive, errorOf, clock });
+        return;
+      }
       if (!serverRequest) {
         sendError(res, 400, "Invalid request: could not parse RPC method from URL", "INVALID_REQUEST");
         return;

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

@@ -17,6 +17,7 @@ import type { HttpServerTransportOptions } from "./types.js";
 import { createPatternServerUrlStrategy } from "./strategies.js";
 import { applyCors, corsOrigins, corsPolicy, type CorsPolicy } from "./cors.js";
 import { createProcedureHandler, type NodeProcedureHandler } from "./handler.js";
+import { isBatchRequest } from "./batch.js";
 
 /**
  * This function gives the route of the procedure handler: each path under the base path. With
@@ -54,7 +55,7 @@ export class HttpServerTransport implements ServerTransport {
 
   private app: Express;
   private httpServer: HttpServer | null = null;
-  private options: { port: number; host: string; basePath: string; cors: boolean; httpServer: HttpServer | undefined; takesBasePath: boolean };
+  private options: { port: number; host: string; basePath: string; cors: boolean; httpServer: HttpServer | undefined; takesBasePath: boolean; batch: boolean };
   /** The procedure handler that does the work of each request (CLI-3) */
   private readonly handler: NodeProcedureHandler;
   /** The CORS of the app, or undefined when it is off */
@@ -72,6 +73,8 @@ export class HttpServerTransport implements ServerTransport {
       httpServer: options.httpServer,
       // A single endpoint with the path in the body is the base path itself (CLI-31)
       takesBasePath: options.addressing?.takesBasePath === true,
+      // A batch of calls goes to the base path itself too (CLI-32)
+      batch: options.batch !== false,
     };
     // Route by URL path so the raw server matches the HTTP client's default URL format instead of
     // inferring the operation from the verb (BUGS-2026-07 C3, bug 16)
@@ -93,6 +96,7 @@ export class HttpServerTransport implements ServerTransport {
         secretHeaders: options.secretHeaders,
         secretQuery: options.secretQuery,
         addressing: options.addressing,
+        batch: options.batch,
       },
       {
         legacy: true,
@@ -133,10 +137,17 @@ export class HttpServerTransport implements ServerTransport {
     }
 
     // Catch-all route for RPC - use regex to match any path under basePath, and the base path
-    // itself for an addressing that takes it
+    // itself for an addressing that takes it. A batch also goes to the base path itself; another
+    // request there goes on to the app (CLI-32).
+    const { basePath, takesBasePath, batch } = this.options;
+    const bareBase = basePath.replace(/\/$/, "");
     this.app.all(
-      basePathRoute(this.options.basePath, this.options.takesBasePath),
-      async (req, res) => {
+      basePathRoute(basePath, takesBasePath || batch),
+      async (req, res, next) => {
+        if (!takesBasePath && req.path.replace(/\/$/, "") === bareBase && !isBatchRequest(req)) {
+          next();
+          return;
+        }
         await this.handler.handle(req, res);
       }
     );

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

@@ -11,6 +11,7 @@ import type { BrowserGuardOptions } from "../../../server/browser-guard.js";
 import type { Clock } from "../../../clock.js";
 import type { Duration } from "../../../duration.js";
 import type { Addressing } from "./addressing.js";
+import type { HandlerBatchOptions } from "./batch.js";
 import type { UrlStrategyRequest } from "./strategies.js";
 
 /**
@@ -62,6 +63,13 @@ export interface HttpServerTransportOptions extends BrowserGuardOptions {
    */
   addressing?: Addressing;
 
+  /**
+   * The batches of calls (CLI-32): `POST {base}` with the header `Procedures-Batch: 1` runs many
+   * calls and answers with one NDJSON stream. `false` turns batches off.
+   * @default true: `{ maxCalls: 64, concurrency: 8 }`
+   */
+  batch?: boolean | HandlerBatchOptions;
+
   /**
    * Base path for RPC endpoints.
    * @default "/api"

package/src/adapters/http/shared/errors.ts

@@ -7,6 +7,8 @@
 
 import { HTTPStatus } from "./constants.js";
 import { formatHTTPError, getStatusCode, isRetryableStatus } from "./status-codes.js";
+import { ErrorCode } from "../../../client/errors/codes.js";
+import { httpStatusToErrorCode } from "../../../client/errors/http-errors.js";
 
 /**
  * HTTP Error Codes (Type-safe)
@@ -75,18 +77,17 @@ export interface HTTPErrorDetails {
 /**
  * Create HTTP error details from status code
  *
- * `HttpTransport` uses these details when the body of an error response has no string code. At
- * this time the code comes from `HTTPStatusToCode`, and three of its codes are not in
- * `ERROR_REGISTRY`: `REQUEST_TIMEOUT`, `INTERNAL_SERVER_ERROR` and
- * `HTTP_NETWORK_CONNECT_TIMEOUT_ERROR`. These three codes are deprecated.
- *
- * The next MINOR of the client group takes the code from `httpStatusToErrorCode()` of
- * `ERROR_REGISTRY`. Then 408 gives `TIMEOUT` (retryable), 500 gives `INTERNAL_ERROR` (not
- * retryable) and 599 gives `HTTP_NETWORK_CONNECT_TIMEOUT` (retryable). `HTTPStatusToCode` has the table.
+ * `HttpTransport` uses these details when the body of an error response has no string code. The
+ * code is the code of `ERROR_REGISTRY` that `httpStatusToErrorCode()` gives. Thus 408 gives
+ * `TIMEOUT` (retryable), 500 gives `INTERNAL_ERROR` (not retryable) and 599 gives
+ * `HTTP_NETWORK_CONNECT_TIMEOUT` (retryable). A status without a code of the registry gives its
+ * name from `HTTPStatusToCode`, for example `NOT_MODIFIED` for 304. `isRetryableStatus()` gives the
+ * retryable flag.
  */
 export function createHTTPStatusError(status: HTTPStatus): HTTPErrorDetails {
+  const registryCode = httpStatusToErrorCode(status);
   return {
-    code: getStatusCode(status),
+    code: registryCode === ErrorCode.UNKNOWN ? getStatusCode(status) : registryCode,
     message: formatHTTPError(status),
     retryable: isRetryableStatus(status),
     status,