@ingenioz-it/caits 0.6.0 → 0.8.0

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/state/createStore.ts

@@ -1,5 +1,4 @@
 import type { EventSubscriber } from "../messaging/EventSubscriber.js";
-import type { Input } from "../messaging/Input.js";
 import type { MessageBus } from "../messaging/MessageBus.js";
 import { reportToConsole, type ReportError } from "../messaging/ReportError.js";
 
@@ -9,7 +8,7 @@ export interface StoreDefinition<S, E> {
   /** The state after the event. */
   reduce(state: S, event: E): S;
   /** The input DTO that the event asks the store to send to the message bus, or undefined. It reads the state before the event. */
-  send(state: S, event: E): Input<unknown> | undefined;
+  send(state: S, event: E): object | undefined;
 }
 
 export interface Store<S> {

package/src/testing/backend/application.ts

@@ -2,7 +2,7 @@ import { test as base } from "vitest";
 import { createTestApplication, type TestApplication } from "./applications.js";
 
 /** Everything an application test of the backend imports: the test of a use case, written as a scenario. */
-export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, vi } from "vitest";
+export { afterAll, afterEach, assert, beforeAll, beforeEach, describe, expect, vi } from "vitest";
 export { applicationScenario } from "./applicationScenario.js";
 export type { TestApplication } from "./applications.js";
 

package/src/testing/backend/applicationScenario.ts

@@ -1,19 +1,18 @@
 import { expect } from "vitest";
 import type { DomainEvent } from "../../DomainEvent.js";
-import type { Input } from "../../messaging/Input.js";
 import type { TestApplication } from "./applications.js";
 
-type Result<Output> = { output: Output } | { error: unknown };
+type Result = { output: unknown } | { error: unknown };
 
 /**
  * An application test, written as a presentation test: the input DTO, the events the handler publishes, then the output DTO or the error
  * that the message bus gives. The events are checked only when the test says which ones it expects.
  */
-export class ApplicationScenario<Output> {
+export class ApplicationScenario {
   private readonly expected: DomainEvent[] = [];
   private checksEvents = false;
 
-  constructor(private readonly app: TestApplication, private readonly dto: Input<Output>) {}
+  constructor(private readonly app: TestApplication, private readonly dto: object) {}
 
   expectItToPublish(event: DomainEvent): this {
     this.expected.push(event);
@@ -26,7 +25,7 @@ export class ApplicationScenario<Output> {
     return this;
   }
 
-  async expectTheOutputToBe(output: Output): Promise<void> {
+  async expectTheOutputToBe(output: object): Promise<void> {
     const from = this.app.published.length;
     const result = await this.run();
     if ("error" in result) throw result.error;
@@ -42,7 +41,7 @@ export class ApplicationScenario<Output> {
     expect(result.error).toStrictEqual(error);
   }
 
-  private async run(): Promise<Result<Output>> {
+  private async run(): Promise<Result> {
     try {
       return { output: await this.app.send(this.dto) };
     } catch (error) {
@@ -56,5 +55,5 @@ export class ApplicationScenario<Output> {
 }
 
 export const applicationScenario = (app: TestApplication) => ({
-  givenTheDto: <Output>(dto: Input<Output>) => new ApplicationScenario(app, dto)
+  givenTheDto: (dto: object) => new ApplicationScenario(app, dto)
 });

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,

package/src/testing/backend/context-map.ts

@@ -5,7 +5,7 @@ import { createTestBackendApplication, type TestBackendApplication } from "./app
  * Everything a test of the context map imports. `test` checks what the `ContextMap` gives: the input DTOs for an event of shared
  * (`inputsFor`), the events of shared for an event of the context (`eventsFor`).
  */
-export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+export { afterAll, afterEach, assert, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
 export { ContextMap } from "../../messaging/ContextMap.js";
 export type { TestBackendApplication } from "./applications.js";
 

package/src/testing/backend/integration.ts

@@ -2,7 +2,7 @@ import { createBackend } from "../../di/createBackend.js";
 import { discovered } from "../../di/discovered.js";
 
 /** Everything an integration test imports: flows of the context map again, with the real infra implementations. */
-export { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+export { afterAll, afterEach, assert, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
 
 /** The whole backend, built from the di.ts of the contexts only: the real infra implementations, as in production. */
 export const productionBackend = () => createBackend(discovered);

package/src/testing/backend/presentationApplication.ts

@@ -1,21 +1,41 @@
 /// <reference path="../../virtual-modules.d.ts" />
 import "virtual:marko-run/__marko-run__router.js";
 import { fetch } from "@marko/run/router";
-import { startBackend } from "../../di/backend.js";
+import { controller, startBackend } from "../../di/backend.js";
 import { bind } from "../../di/Container.js";
+import type { DomainEvent } from "../../DomainEvent.js";
+import { ContextEvents } from "../../messaging/ContextEvents.js";
 import { MessageBus } from "../../messaging/MessageBus.js";
+import { RequestEvents } from "../../messaging/RequestEvents.js";
+import type { TimerController } from "../../messaging/TimerController.js";
 import { FakeMessageBus } from "../shared/FakeMessageBus.js";
 
 /** The real routes and controllers, over a bus that only records: each test says what the application answers. */
 export function startPresentationApplication() {
-  const messageBus = new FakeMessageBus();
+  // The events that the application publishes, as the test says: the controllers that stream hear them, of their request and of their context.
+  const listeners = new Set<(event: DomainEvent) => void>();
+  // They never end: a feed ends when the client of the test leaves.
+  const events: ContextEvents = {
+    subscribe: listener => {
+      listeners.add(listener);
+      return () => { listeners.delete(listener); };
+    },
+    signal: new AbortController().signal
+  };
+  const messageBus = new FakeMessageBus(event => { for (const listener of [...listeners]) listener(event); });
   const reportedErrors: unknown[] = [];
   const reportError = (error: unknown) => { reportedErrors.push(error); };
-  startBackend({ reportError, replace: { shared: [bind(MessageBus).toValue(messageBus)] } });
+  startBackend({ reportError, replace: { shared: [bind(MessageBus).toValue(messageBus), bind(RequestEvents).toValue(events), bind(ContextEvents).toValue(events)] } });
 
   return {
     messageBus,
     reportedErrors,
+    /** Runs one turn of a timer controller, as the kernel does while the server runs, in a request of its own. Gives its rhythm. */
+    async tick(timer: abstract new (...args: never[]) => TimerController<object>): Promise<number> {
+      const turn = controller(timer);
+      await turn.tick();
+      return turn.every;
+    },
     async fetch(request: Request): Promise<Response> {
       const response = await fetch(request, {} as never);
       if (!response) throw new Error(`No route answers ${request.method} ${new URL(request.url).pathname}`);