@ingenioz-it/caits 0.7.0 → 0.8.0

package/src/messaging/Request.ts

@@ -0,0 +1,116 @@
+export class InvalidInputError extends Error {
+  constructor(message: string, readonly details?: unknown) {
+    super(message);
+    this.name = "InvalidInputError";
+  }
+}
+
+export class MalformedBodyError extends InvalidInputError {}
+
+export class UnsupportedMediaTypeError extends InvalidInputError {}
+
+export class BodyTooLargeError extends InvalidInputError {}
+
+export class CrossSiteRequestError extends InvalidInputError {}
+
+/** The largest body that content reads by default, in bytes: 1 MB. */
+export const MAX_BODY_SIZE = 1024 * 1024;
+
+/**
+ * A JSON media type, in any case: application/json, or a type with the suffix +json (application/merge-patch+json). Parameters can
+ * follow, after a ";". A parameter is not the type: a browser sends `text/plain;x+json` from any site, as text/plain.
+ */
+const JSON_MEDIA_TYPE = /^(?:application\/json|[^\s/]+\/[^\s/;]+\+json)\s*(?:;|$)/i;
+
+/** The media types of a form, in any case, with parameters after a ";": the boundary of the parts of multipart/form-data. */
+const FORM_MEDIA_TYPE = /^(?:multipart\/form-data|application\/x-www-form-urlencoded)\s*(?:;|$)/i;
+
+/** The headers of a request, which a controller reads and does not change. */
+export type RequestHeaders = Pick<Headers, "get" | "has" | "forEach" | "entries" | "keys" | "values" | typeof Symbol.iterator>;
+
+/** What content reads: the largest body, in bytes. */
+export type ContentOptions = { readonly maxSize?: number };
+
+/**
+ * The request that a controller reads. It gives the address, the method, the headers and the signal of a client that leaves, as the
+ * request of the web gives them, and the content of the body, which it reads once, and gives again at each call: the request of the web
+ * reads its body once only. A controller reads this request, never the request of the web (rule controllers-read-the-request-of-caits).
+ */
+export class Request {
+  readonly url: string;
+  readonly method: string;
+  readonly headers: RequestHeaders;
+  /** Aborts when the client leaves. */
+  readonly signal: AbortSignal;
+  readonly #request: globalThis.Request;
+  /** The bytes of the body, once read: the first call of content reads them, with its largest size. */
+  #body: Promise<Blob> | undefined;
+
+  constructor(request: globalThis.Request) {
+    this.#request = request;
+    this.url = request.url;
+    this.method = request.method;
+    this.headers = request.headers;
+    this.signal = request.signal;
+  }
+
+  /**
+   * The content of the body: the value of its JSON, or the fields of a form as an object, a text or a File for each name, a list for a
+   * name that comes more than once. The request must say what its body is: content-type application/json, or a type with the suffix
+   * +json, or a form, multipart/form-data or application/x-www-form-urlencoded. A browser sends a body of another type (text/plain) or a
+   * form from any site, without asking the server first, and says where the request comes from in its header Sec-Fetch-Site, which a
+   * client that is not a browser does not send: a form that a browser sends from another site is refused. The body must not be larger
+   * than `maxSize` bytes (MAX_BODY_SIZE, 1 MB, by default): the rest of a larger body is not read. The first call reads the body, with its
+   * `maxSize`; the next calls give its content again.
+   * @throws {UnsupportedMediaTypeError} when the request does not say that its body is JSON or a form: the Controller answers 415.
+   * @throws {CrossSiteRequestError} when a browser sends the form from another site: the Controller answers 403.
+   * @throws {BodyTooLargeError} when the body is larger than `maxSize`: the Controller answers 413.
+   * @throws {MalformedBodyError} when the body is not JSON, or not the form that it says: the Controller answers 400.
+   */
+  async content({ maxSize = MAX_BODY_SIZE }: ContentOptions = {}): Promise<unknown> {
+    const contentType = this.headers.get("content-type");
+    if (contentType?.match(JSON_MEDIA_TYPE)) {
+      const text = await (await this.#bytes(maxSize)).text();
+      try {
+        return JSON.parse(text);
+      } catch {
+        throw new MalformedBodyError("Invalid JSON");
+      }
+    }
+    if (!contentType?.match(FORM_MEDIA_TYPE)) throw new UnsupportedMediaTypeError("The content type must be application/json, multipart/form-data or application/x-www-form-urlencoded");
+    const site = this.headers.get("sec-fetch-site");
+    if (site === "cross-site" || site === "same-site") throw new CrossSiteRequestError("A browser sent this form from another site");
+    const bytes = await this.#bytes(maxSize);
+    let form: FormData;
+    try {
+      form = await new Response(bytes, { headers: { "content-type": contentType } }).formData();
+    } catch {
+      throw new MalformedBodyError("Invalid form");
+    }
+    const fields: Record<string, FormDataEntryValue | FormDataEntryValue[]> = {};
+    for (const [name, value] of form) {
+      // A field of its own, as JSON.parse makes it, also for a name such as __proto__.
+      const known = Object.hasOwn(fields, name) ? fields[name] : undefined;
+      Object.defineProperty(fields, name, { value: known === undefined ? value : [known, value].flat(), enumerable: true, writable: true, configurable: true });
+    }
+    return fields;
+  }
+
+  #bytes(maxSize: number): Promise<Blob> {
+    this.#body ??= bytesOf(this.#request, maxSize);
+    return this.#body;
+  }
+}
+
+/** The bytes of the body, read chunk by chunk: the reading stops at the first chunk after `maxSize` bytes. */
+async function bytesOf(request: globalThis.Request, maxSize: number): Promise<Blob> {
+  const chunks: Uint8Array<ArrayBuffer>[] = [];
+  let size = 0;
+  const reader = request.body?.getReader();
+  for (let chunk = await reader?.read(); chunk && !chunk.done; chunk = await reader?.read()) {
+    size += chunk.value.byteLength;
+    if (size > maxSize) throw new BodyTooLargeError(`The body is larger than ${maxSize} bytes`);
+    chunks.push(chunk.value);
+  }
+  return new Blob(chunks);
+}

package/src/messaging/RequestEvents.ts

@@ -0,0 +1,8 @@
+import type { DomainEvent } from "../DomainEvent.js";
+import { Token } from "../Token.js";
+import type { EventSubscriber } from "./EventSubscriber.js";
+
+/** The events that the handlers of a request publish, as they publish them: a controller that streams writes them in its response. */
+export type RequestEvents = EventSubscriber<DomainEvent>;
+
+export const RequestEvents = new Token<RequestEvents>();

package/src/messaging/StreamController.ts

@@ -0,0 +1,261 @@
+import type { DomainEvent } from "../DomainEvent.js";
+import type { ContextEvents } from "./ContextEvents.js";
+import { errorResponseOf } from "./Controller.js";
+import type { MessageBus } from "./MessageBus.js";
+import { reportToConsole, type ReportError } from "./ReportError.js";
+import { Request } from "./Request.js";
+import type { RequestEvents } from "./RequestEvents.js";
+import { SSE_HEADERS, sseComment, sseEvent } from "./sse.js";
+
+/**
+ * What comes to the stream: an event that a handler published, the output of the handler, or its error; or the text of an event of a
+ * request, which came before the stream started.
+ */
+type Item = { readonly event: DomainEvent } | { readonly output: unknown } | { readonly error: unknown } | { readonly text: string };
+
+/**
+ * Turns a request into an input DTO, sends it to the message bus, and streams the answer as server-sent events: what the handler
+ * publishes, as it publishes it, then its output. It answers before the handler ends.
+ * - `follows` says which events it writes: those that the handlers of its request publish ("request"), until the handler answers; or
+ *   those of every request of its context ("context"), after the output of its handler, the state at the start, until the client leaves.
+ *   An event of the context may come while the handler reads the state, and be in it already: `stateHolds` says so, and the feed does
+ *   not write it again. A feed ends when the events of its context end, as the backend stops: its client comes back to the next one. A
+ *   stream of a request goes on, as any request that the server lets end.
+ * - An EventSource, in a browser, connects again to a stream that ends, with the same GET: a feed gives its state again. It would run the
+ *   use case of a stream of a request again and again: its client closes it at the last event, or the API takes POST.
+ * - Until the first event that it writes, or the output, an error is a response, as a Controller gives it (`toErrorResponse`): an event
+ *   that it does not write, as one for another context, decides nothing, since the client reads nothing of it. An event that it cannot
+ *   write is then an error too. Once the stream started, an error goes in the stream (`toErrorChunk`), which ends: an error of the
+ *   handler, or of the controller as it writes the stream (`toChunk`, `toOutputChunk`, `stateHolds`, `toKeepAlive`). An error that
+ *   `toErrorChunk` cannot write is reported, with the error of `toErrorChunk`.
+ * - When the stream says nothing for `keepAliveMs`, a comment keeps the connection alive.
+ * - It gives the bus the signal of the request with the DTO: the signal aborts when the client leaves, or stops reading the stream, or
+ *   when the controller cannot write the stream, and the handler reads it in its RequestContext.
+ * - A request that asks for no stream (`streams`) gets the response to the output (`toResponse`), once the handler answers, as from a
+ *   Controller: an API that streams or not at the same address, as the request says.
+ * - It reads the request through the Request of CAITS, which gives the content of the body at each call.
+ */
+export abstract class StreamController<Dto extends object, Output> {
+  /** The events that it writes: those of its request, or those of its context. */
+  protected readonly follows: "request" | "context" = "request";
+  /** How long the stream may stay silent before a comment keeps the connection alive, in milliseconds. */
+  protected readonly keepAliveMs: number = 15_000;
+
+  constructor(
+    private bus: MessageBus,
+    private requestEvents: RequestEvents,
+    private contextEvents: ContextEvents,
+    protected readonly reportError: ReportError = reportToConsole
+  ) {}
+
+  protected abstract toDto(request: Request): Dto | Promise<Dto>;
+
+  /** The text of an event in the stream: nothing writes nothing. */
+  protected abstract toChunk(event: DomainEvent): string | undefined;
+
+  /** The text of the output in the stream: the end of the answer of a request, or the state at the start of a feed. */
+  protected abstract toOutputChunk(output: Output): string | undefined;
+
+  /** The response to an error before the stream starts: as a Controller gives it. A controller answers its own errors first. */
+  protected toErrorResponse(error: unknown, _request: Request): Response | Promise<Response> {
+    return errorResponseOf(error, this.reportError);
+  }
+
+  /**
+   * The text of an error once the stream started: the error is reported, and the event tells nothing of it. The event is a "problem",
+   * as CAITS names its errors: an EventSource, in a browser, gives the name "error" to a connection that fails or ends.
+   */
+  protected toErrorChunk(error: unknown): string {
+    this.reportError(error);
+    return sseEvent(JSON.stringify({ title: "Internal server error" }), { event: "problem" });
+  }
+
+  /**
+   * Whether the state at the start of a feed holds an event that came before it already: the feed writes it only when the state does
+   * not hold it. It writes each event that comes after the state. A state holds no event by default.
+   */
+  protected stateHolds(_state: Output, _event: DomainEvent): boolean {
+    return false;
+  }
+
+  /** Whether the request asks for a stream: each one does by default. */
+  protected streams(_dto: Dto): boolean {
+    return true;
+  }
+
+  /** The response to the output, for a request that asks for no stream: the output in JSON by default. */
+  protected toResponse(output: Output, _request: Request): Response | Promise<Response> {
+    return Response.json(output);
+  }
+
+  protected headers(): HeadersInit {
+    return SSE_HEADERS;
+  }
+
+  protected toKeepAlive(): string {
+    return sseComment("keep-alive");
+  }
+
+  /** Answers a request of the web: the methods of the controller read it through the Request of CAITS. */
+  async handle(received: globalThis.Request): Promise<Response> {
+    try {
+      return await this.respond(new Request(received));
+    } catch (failure) {
+      // A response to an error that fails too: the answer of a Controller.
+      return errorResponseOf(failure, this.reportError);
+    }
+  }
+
+  private async respond(request: Request): Promise<Response> {
+    let dto: Dto;
+    try {
+      dto = await this.toDto(request);
+    } catch (error) {
+      return this.toErrorResponse(error, request);
+    }
+    if (!this.streams(dto)) return this.answer(dto, request);
+    const queue: Item[] = [];
+    let wake: () => void = () => {};
+    // The client leaves when its request aborts, or when it stops reading the stream.
+    const cancelled = new AbortController();
+    // Before the stream starts, a stream of a request writes each event as it comes: the first text that it writes starts the stream. A
+    // feed keeps its events, which its state may hold.
+    let take: (item: Item) => void = item => {
+      let kept = item;
+      if (this.follows === "request" && "event" in item) {
+        try {
+          const text = this.toChunk(item.event);
+          if (text === undefined) return;
+          kept = { text };
+        } catch (error) {
+          // No one reads what the handler does next: it stops.
+          cancelled.abort();
+          kept = { error };
+        }
+      }
+      queue.push(kept);
+      wake();
+    };
+    const stopListening = (this.follows === "request" ? this.requestEvents : this.contextEvents).subscribe(event => { take({ event }); });
+    const answering = this.bus.send(dto, { signal: AbortSignal.any([request.signal, cancelled.signal]) }).then(output => ({ output }), (error: unknown) => ({ error }));
+    void answering.then(item => {
+      // The output of a feed is its start: it goes first, below.
+      if (this.follows === "request") take(item);
+    });
+    // A request waits for what comes first; a feed, for its start; both, until the client leaves.
+    const { promise: left, resolve: leftNow } = Promise.withResolvers<undefined>();
+    const leaveEarly = () => { leftNow(undefined); };
+    request.signal.addEventListener("abort", leaveEarly);
+    if (request.signal.aborted) leaveEarly();
+    const first = await Promise.race([
+      this.follows === "request" ? new Promise<Item>(resolve => { wake = () => { resolve(queue[0]); }; if (queue.length > 0) wake(); }) : answering,
+      left
+    ]);
+    if (first === undefined) {
+      stopListening();
+      // No one reads it: 499, as servers write in their logs a client that left.
+      return new Response(null, { status: 499 });
+    }
+    if ("error" in first) {
+      stopListening();
+      return this.toErrorResponse(first.error, request);
+    }
+    // A feed starts with its state, the output of its handler. The events that came before it may be in it already. A stream of a
+    // request keeps no event before it starts: it wrote each one as it came.
+    const early = new Set(queue);
+    if (this.follows === "context") queue.unshift(first);
+
+    const encoder = new TextEncoder();
+    let open = true;
+    let silence: ReturnType<typeof setTimeout> | undefined;
+    const ended = new AbortController();
+    const end = () => {
+      open = false;
+      clearTimeout(silence);
+      stopListening();
+      ended.abort();
+    };
+    const leave = () => {
+      end();
+      cancelled.abort();
+    };
+    request.signal.addEventListener("abort", leave);
+    const body = new ReadableStream<Uint8Array>({
+      start: stream => {
+        const close = () => {
+          end();
+          stream.close();
+        };
+        // The silence counts from the last text written: an event that writes nothing breaks no silence.
+        const quiet = () => {
+          clearTimeout(silence);
+          silence = setTimeout(() => {
+            try {
+              write(this.toKeepAlive());
+            } catch (error) {
+              failToWrite(error);
+            }
+          }, this.keepAliveMs);
+        };
+        const write = (text: string | undefined) => {
+          if (text === undefined) return;
+          stream.enqueue(encoder.encode(text));
+          quiet();
+        };
+        // An error ends the stream with its event; when the controller cannot write the event, it reports both errors.
+        const fail = (error: unknown) => {
+          try {
+            write(this.toErrorChunk(error));
+          } catch (failure) {
+            this.reportError(error);
+            this.reportError(failure);
+          }
+          close();
+        };
+        // No one reads what the handler does next: it stops, as when the client leaves.
+        const failToWrite = (error: unknown) => {
+          fail(error);
+          cancelled.abort();
+        };
+        take = item => {
+          if (!open) return;
+          try {
+            if ("text" in item) {
+              write(item.text);
+            } else if ("event" in item) {
+              if (!(early.has(item) && this.stateHolds((first as { readonly output: Output }).output, item.event))) write(this.toChunk(item.event));
+            } else if ("error" in item) {
+              fail(item.error);
+            } else {
+              write(this.toOutputChunk(item.output as Output));
+              if (this.follows === "request") close();
+            }
+          } catch (error) {
+            failToWrite(error);
+          }
+        };
+        quiet();
+        for (const item of queue.splice(0)) take(item);
+        // A feed ends with the events of its context, as the backend stops.
+        if (open && this.follows === "context") {
+          const { signal } = this.contextEvents;
+          signal.addEventListener("abort", close, { signal: ended.signal });
+          if (signal.aborted) close();
+        }
+      },
+      cancel: leave
+    });
+    return new Response(body, { status: 200, headers: this.headers() });
+  }
+
+  /** Sends the DTO with the signal of the request, and answers as a Controller does once the handler answers. */
+  private async answer(dto: Dto, request: Request): Promise<Response> {
+    let output: Output;
+    try {
+      output = await this.bus.send(dto, { signal: request.signal }) as Output;
+    } catch (error) {
+      return await this.toErrorResponse(error, request);
+    }
+    return await this.toResponse(output, request);
+  }
+}

package/src/messaging/TimerController.ts

@@ -0,0 +1,25 @@
+import type { MessageBus } from "./MessageBus.js";
+import { reportToConsole, type ReportError } from "./ReportError.js";
+
+/**
+ * Sends an input DTO at each turn of a timer: what an HTTP controller does for a request, with time for the trigger. The kernel runs it
+ * every `every` milliseconds while the server runs, in a request of its own at each turn, and skips a turn while the last one runs. An
+ * error is reported, never thrown: the next turn comes anyway.
+ */
+export abstract class TimerController<Dto extends object> {
+  constructor(private bus: MessageBus, private reportError: ReportError = reportToConsole) {}
+
+  /** How often the kernel runs it, in milliseconds. */
+  abstract readonly every: number;
+
+  protected abstract toDto(): Dto | Promise<Dto>;
+
+  /** Sends the DTO of this turn, and waits for its handler. */
+  async tick(): Promise<void> {
+    try {
+      await this.bus.send(await this.toDto());
+    } catch (error) {
+      this.reportError(error);
+    }
+  }
+}

package/src/messaging/sse.ts

@@ -0,0 +1,23 @@
+/** The headers of a stream of server-sent events: no cache, and no compression that would hold its chunks back. */
+export const SSE_HEADERS: Readonly<Record<string, string>> = { "content-type": "text/event-stream; charset=utf-8", "cache-control": "no-cache, no-transform" };
+
+/** Where a client of server-sent events ends a line. */
+const LINE_BREAK = /\r\n|\r|\n/;
+
+/** The value of a field that has one line: a line break would end the field, and start another one. */
+function oneLine(field: "event" | "id", value: string): string {
+  if (/[\r\n]/.test(value)) throw new Error(`The ${field} of a server-sent event holds no line break: ${JSON.stringify(value)}`);
+  return value;
+}
+
+/** A server-sent event: its name and its id when it has them, then its data, line by line. */
+export function sseEvent(data: string, { event, id }: { readonly event?: string; readonly id?: string } = {}): string {
+  const name = event === undefined ? "" : `event: ${oneLine("event", event)}\n`;
+  const identity = id === undefined ? "" : `id: ${oneLine("id", id)}\n`;
+  return `${name}${identity}${data.split(LINE_BREAK).map(line => `data: ${line}`).join("\n")}\n\n`;
+}
+
+/** A comment, which a client of server-sent events ignores: it keeps the connection alive, and can tell a person what happens. */
+export function sseComment(text: string): string {
+  return `${text.split(LINE_BREAK).map(line => `: ${line}`).join("\n")}\n\n`;
+}

package/src/server/entry.ts

@@ -0,0 +1,37 @@
+// What `npm start` runs: `npm run build` builds the server of the app from this file, which the adapter of CAITS (adapter.js) gives to
+// @marko/run. It serves the files, the pages and the handlers of the app as the entry of @marko/run does, boots the backend first, and
+// stops it on SIGTERM or SIGINT.
+import { createMiddleware } from "@marko/run/adapter/middleware";
+import { fetch } from "@marko/run/router";
+import compression from "compression";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import zlib from "node:zlib";
+import createStaticServe from "serve-static";
+import { boot } from "./kernel.js";
+import { serve, stopOnSignals } from "./serve.js";
+
+const folder = dirname(fileURLToPath(import.meta.url));
+const middleware = createMiddleware(fetch);
+const compress = compression({ flush: zlib.constants.Z_PARTIAL_FLUSH, threshold: 500 });
+const servePublic = createStaticServe(`${folder}/public`, { index: false, redirect: false, maxAge: "10 minutes" });
+const serveAssets = createStaticServe(`${folder}/public/assets`, { index: false, redirect: false, immutable: true, fallthrough: false, maxAge: "365 days" });
+
+const served = await serve({
+  port: Number(process.env.PORT ?? 3000),
+  boot,
+  handle: (request, response) => {
+    compress(request, response, () => {
+      if (request.url?.startsWith("/assets/")) {
+        request.url = request.url.slice("/assets".length);
+        serveAssets(request, response, () => {
+          response.statusCode = 404;
+          response.end();
+        });
+      } else {
+        servePublic(request, response, () => { middleware(request, response); });
+      }
+    });
+  }
+});
+stopOnSignals(served.close);

package/src/server/kernel.ts

@@ -0,0 +1,19 @@
+import { startBackend, stopBackend } from "../di/backend.js";
+import type { BackendOptions } from "../di/createBackend.js";
+import type { Stop } from "./serve.js";
+
+/**
+ * Boots the backend of the server, with the bindings of the di.ts of the contexts, and starts its timers. Gives what stops it: the server
+ * of `npm start` and that of `caits dev` call it when they stop, and `caits dev` before it boots the backend again. A backend whose timers
+ * cannot start stops at once, and releases what it built: the boot fails.
+ */
+export async function boot(options: BackendOptions = {}): Promise<Stop> {
+  const backend = startBackend(options);
+  try {
+    backend.start();
+  } catch (error) {
+    await stopBackend();
+    throw error;
+  }
+  return (requestsDone, graceOver) => stopBackend(requestsDone, graceOver);
+}

package/src/server/packages.d.ts

@@ -0,0 +1,12 @@
+/** The packages that the entry of the server (entry.ts) uses as the entry of @marko/run does. CAITS depends on them, as @marko/run does: they have no types. */
+declare module "compression" {
+  import type { IncomingMessage, ServerResponse } from "node:http";
+  type Options = { readonly flush?: number; readonly threshold?: number };
+  export default function compression(options?: Options): (request: IncomingMessage, response: ServerResponse, next: () => void) => void;
+}
+
+declare module "serve-static" {
+  import type { IncomingMessage, ServerResponse } from "node:http";
+  type Options = { readonly index?: false; readonly redirect?: boolean; readonly maxAge?: string; readonly immutable?: boolean; readonly fallthrough?: boolean };
+  export default function serveStatic(root: string, options?: Options): (request: IncomingMessage, response: ServerResponse, next: () => void) => void;
+}

package/src/server/serve.js

@@ -0,0 +1,121 @@
+// The HTTP server of an app, for `npm start` (entry.ts) and for `caits dev` (adapter.js). JavaScript, not TypeScript: `caits dev` loads
+// it with Node, which strips no types in node_modules, where a project installs the kernel.
+import { createServer } from "node:http";
+
+/** @import { IncomingMessage, ServerResponse } from "node:http" */
+/** @import { AddressInfo } from "node:net" */
+
+/**
+ * What stops the backend: its feeds and its timers, then, once the requests that the server serves are done (the promise), what its
+ * containers built. The signal aborts when the grace ends: the backend waits for its turns and its reactions until then at most.
+ * @typedef {(requestsDone: Promise<unknown>, graceOver: AbortSignal) => Promise<void>} Stop
+ */
+
+/**
+ * @typedef {object} ServeOptions
+ * @property {(request: IncomingMessage, response: ServerResponse) => void} handle The requests: the pages, the handlers, the files.
+ * @property {number} port The port, 0 for any free port.
+ * @property {() => Stop | Promise<Stop>} boot Boots the backend, and gives what stops it.
+ * @property {number} [grace] How long the requests, the turns of the timers and the reactions that run may still run once the server
+ *   stops, in milliseconds: 10 s by default.
+ * @property {(error: unknown) => void} [reportError] Reports a boot that fails at a reboot: the console by default.
+ */
+
+/** What stops no backend: that of a reboot whose boot failed. */
+const NO_STOP = async () => {};
+
+/**
+ * Boots the backend, then serves the requests on the port.
+ * - `reboot` stops the backend, then boots it again (`caits dev` does it when its code changes): never two backends at once. A request
+ *   that comes meanwhile waits for the new backend. A boot that fails is reported: the server serves on, and the next reboot boots again.
+ * - `close` serves no new request, stops the backend (which ends its feeds, then its timers), lets the requests that run end (after the
+ *   grace, it closes their connections), then releases what the backend built. The connection of a request that ends closes. A request
+ *   that comes meanwhile on a connection that still serves another gets a 503, which closes the connection. A reboot after it boots
+ *   nothing.
+ * @param {ServeOptions} options
+ */
+export async function serve({ handle, port, boot, grace = 10_000, reportError = error => { console.error(error); } }) {
+  let stop = await boot();
+  /** @type {Promise<void>} the reboots, one after the other */
+  let reboots = Promise.resolve();
+  /** @type {Promise<void> | undefined} */
+  let closing;
+  const server = createServer((request, response) => {
+    if (closing) {
+      response.writeHead(503, { connection: "close" }).end();
+      return;
+    }
+    // A response that ends while the server closes frees its connection: the server closes it. A stream that started before said that
+    // the connection stays open, and the client would keep it until its own delay, a few seconds, which the close would wait for.
+    response.once("finish", () => { if (closing) server.closeIdleConnections(); });
+    void reboots.then(() => { handle(request, response); });
+  });
+  try {
+    await new Promise((resolve, reject) => { server.once("error", reject).listen(port, () => { resolve(undefined); }); });
+  } catch (error) {
+    await stop(Promise.resolve(), AbortSignal.abort());
+    throw error;
+  }
+  return {
+    port: /** @type {AddressInfo} */ (server.address()).port,
+    /** @returns {Promise<void>} */
+    reboot: () => (reboots = reboots.then(async () => {
+      if (closing) return;
+      try {
+        // A reboot lets no request end: no grace.
+        await stop(Promise.resolve(), AbortSignal.abort());
+        stop = NO_STOP;
+        stop = await boot();
+      } catch (error) {
+        reportError(error);
+      }
+    })),
+    /** @returns {Promise<void>} */
+    close: () => (closing ??= (async () => {
+      await reboots;
+      const requestsDone = new Promise(resolve => { server.close(() => { resolve(undefined); }); });
+      const graceOver = new AbortController();
+      const cut = setTimeout(() => {
+        server.closeAllConnections();
+        graceOver.abort();
+      }, grace);
+      await stop(requestsDone, graceOver.signal);
+      clearTimeout(cut);
+    })())
+  };
+}
+
+/**
+ * @typedef {object} SignalOptions
+ * @property {{ on(signal: "SIGTERM" | "SIGINT", listener: () => void): unknown }} [signals] Where the signals come: the process by default.
+ * @property {(code: number) => void} [exit] Ends the process: process.exit by default.
+ * @property {(error: unknown) => void} [reportError] Reports a close that fails: the console by default.
+ */
+
+/** How long after the first signal a second one ends the process at once, in milliseconds. */
+const SECOND_SIGNAL_MS = 1000;
+
+/**
+ * Closes the server on SIGTERM (`docker stop`) or SIGINT (Ctrl+C), then ends the process: 0 when the close succeeds, 1 when it fails. A
+ * second signal, a second or more after the first, ends it at once, with 1. A signal often comes twice at once: Ctrl+C reaches each
+ * process of the group of the terminal, and npm, in `npm start`, passes it on to the server. It counts once.
+ * @param {() => Promise<void>} close
+ * @param {SignalOptions} [options]
+ */
+export function stopOnSignals(close, { signals = process, exit = code => process.exit(code), reportError = error => { console.error(error); } } = {}) {
+  /** @type {number | undefined} */
+  let stoppedAt;
+  const stopNow = () => {
+    if (stoppedAt !== undefined) {
+      if (Date.now() - stoppedAt >= SECOND_SIGNAL_MS) exit(1);
+      return;
+    }
+    stoppedAt = Date.now();
+    close().then(() => { exit(0); }, error => {
+      reportError(error);
+      exit(1);
+    });
+  };
+  signals.on("SIGTERM", stopNow);
+  signals.on("SIGINT", stopNow);
+}

package/src/testing/backend/applications.ts

@@ -47,7 +47,10 @@ export function createTestApplication() {
   backend.subscribeToContexts(event => { published.push(event); });
 
   return {
-    /** Sends an input DTO to the message bus of the context that handles it. */
+    /**
+     * Sends an input DTO to the message bus of the context that handles it: with the signal of a client, `send(dto, { signal })`, its
+     * handler sees the client leave when the test aborts it.
+     */
     send: backend.send,
     /** The dependency with this token, built now if no handler needed it before. */
     get: backend.get,