@ingenioz-it/caits 0.7.0 → 0.8.0

package/src/di/Container.ts

@@ -40,6 +40,13 @@ export function bind<T>(key: Key<T>) {
 }
 
 const describe = (route: readonly Key[]) => route.map(key => key.name).join(" → ");
+
+/** Releases an instance that holds a resource: with Symbol.asyncDispose, else Symbol.dispose. Another instance holds none. */
+async function release(instance: unknown): Promise<void> {
+  const { [Symbol.asyncDispose]: asyncDispose, [Symbol.dispose]: dispose } = Object(instance) as Partial<AsyncDisposable & Disposable>;
+  if (typeof asyncDispose === "function") await asyncDispose.call(instance);
+  else if (typeof dispose === "function") dispose.call(instance);
+}
 const isKey = (value: unknown): value is Key => value instanceof Token || typeof value === "function";
 
 /**
@@ -90,6 +97,26 @@ export class Container {
     return value;
   }
 
+  /**
+   * Releases what this container built, the last built first, so a dependency outlives what needs it: each instance with
+   * Symbol.asyncDispose or Symbol.dispose. A value that a binding gives belongs to whoever made it, and what the parent built to the
+   * parent. Every instance is released, even when another fails: the errors come together, after. What it released, it builds again if
+   * something needs it.
+   */
+  async dispose(): Promise<void> {
+    const instances = [...this.built.values()].reverse();
+    this.built.clear();
+    const errors: unknown[] = [];
+    for (const instance of instances) {
+      try {
+        await release(instance);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length > 0) throw new AggregateError(errors, `${errors.length} instance${errors.length === 1 ? "" : "s"} failed to release`);
+  }
+
   private resolve(key: Key, path: readonly Key[], make: boolean): unknown {
     const binding = this.bindings.get(key);
     if (!binding && this.parent?.has(key)) return this.parent.resolve(key, path, make);

package/src/di/RequestContext.ts

@@ -1,6 +1,12 @@
 import { Token } from "../Token.js";
 
-/** What the backend knows of the request that a handler or a controller serves. */
-export type RequestContext = { readonly correlationId: string };
+/**
+ * What the backend knows of the request that a handler or a controller serves: its correlation id, and its signal, which aborts when its
+ * client leaves. A handler gives the signal to the ports whose work the client waits for: a call to a model, to a service, to a database.
+ * A request without a client sees the backend stop: the signal of a turn of a timer aborts as soon as the server stops, that of a reaction
+ * to an event once the grace of the server ends. A DTO that the backend sends without a signal, as a test does, gets one that does not
+ * abort.
+ */
+export type RequestContext = { readonly correlationId: string; readonly signal: AbortSignal };
 
 export const RequestContext = new Token<RequestContext>();

package/src/di/backend.ts

@@ -8,6 +8,18 @@ export function startBackend(options: BackendOptions = {}): Backend {
   return current = createBackend(discovered, options);
 }
 
+/**
+ * Stops the backend that serves the requests, if one started, then forgets it: its feeds, its timers, the turns that run, the requests
+ * that the server still serves (the promise that it gives), the reactions, until the grace ends (the signal), then what its containers
+ * built. The next use starts a new one. A request that comes
+ * while it stops gets it: a new backend would outlive the server, since nothing would stop it.
+ */
+export async function stopBackend(requestsDone?: Promise<unknown>, graceOver?: AbortSignal): Promise<void> {
+  const stopping = current;
+  await stopping?.stop(requestsDone, graceOver);
+  if (current === stopping) current = undefined;
+}
+
 /** The backend that serves the requests, started with the production bindings on first use. */
 export function backend(): Backend {
   return current ?? startBackend();

package/src/di/createBackend.ts

@@ -1,11 +1,15 @@
 import type { DomainEvent } from "../DomainEvent.js";
 import type { Token } from "../Token.js";
 import { BackendEventBus, type Published } from "../messaging/BackendEventBus.js";
+import { ContextEvents } from "../messaging/ContextEvents.js";
 import { ContextMap, type Envelope, type Translation } from "../messaging/ContextMap.js";
 import { EventPublisher } from "../messaging/EventPublisher.js";
 import { InProcessMessageBus, UnknownInputError } from "../messaging/InProcessMessageBus.js";
+import type { EventSubscriber } from "../messaging/EventSubscriber.js";
 import { MessageBus } from "../messaging/MessageBus.js";
 import { ReportError, reportToConsole } from "../messaging/ReportError.js";
+import { RequestEvents } from "../messaging/RequestEvents.js";
+import { TimerController } from "../messaging/TimerController.js";
 import { bind, Container, type Binding, type Concrete } from "./Container.js";
 import type { BackendModules, Class, UseCase } from "./discover.js";
 import { RequestContext } from "./RequestContext.js";
@@ -15,20 +19,69 @@ export type BackendOptions = {
   replace?: Partial<Record<string, readonly Binding[]>>;
   reportError?: ReportError;
   nextEventId?: () => string;
+  /** The clock of the timer controllers: setInterval when not given. */
+  schedule?: Schedule;
 };
 
-/** A context, and the events of shared that an event of its handlers gives. */
-type Context = { readonly container: Container; readonly useCases: readonly UseCase[]; readonly shares: (event: DomainEvent) => DomainEvent[] };
+/** Runs a turn every `every` milliseconds, until the function that it gives is called. */
+export type Schedule = (every: number, turn: () => void) => () => void;
 
-const SYSTEM: RequestContext = { correlationId: "system" };
+/** The longest delay of setInterval, about 24 days: Node runs a timer with a longer one every millisecond. */
+const MAX_EVERY = 2 ** 31 - 1;
+
+/** How long the turns and the reactions that still run get, once the grace ends and their signal aborted, in milliseconds. */
+const LAST_WAIT_MS = 1000;
+
+/** Waits until the work ends, or the signal aborts. */
+const untilEndOrAbort = (work: Promise<unknown>, signal: AbortSignal) => new Promise<void>(resolve => {
+  signal.addEventListener("abort", () => { resolve(); });
+  if (signal.aborted) resolve();
+  void work.then(() => { resolve(); });
+});
+
+
+const everyInterval: Schedule = (every, turn) => {
+  const timer = setInterval(turn, every);
+  return () => { clearInterval(timer); };
+};
+
+const isTimer = (type: Class): type is Concrete<TimerController<object>> => type.prototype instanceof TimerController;
+
+type Listener = (event: DomainEvent) => void;
+
+/**
+ * A context, its timer controllers, the events of shared that an event of its handlers gives, and who listens to the events of its
+ * handlers.
+ */
+type Context = {
+  readonly container: Container;
+  readonly useCases: readonly UseCase[];
+  readonly timers: readonly Concrete<TimerController<object>>[];
+  readonly shares: (event: DomainEvent) => DomainEvent[];
+  readonly listeners: Set<Listener>;
+};
+
+/** What subscribes to the events that come to these listeners. */
+const subscriberOf = (listeners: Set<Listener>): EventSubscriber<DomainEvent> => ({
+  subscribe: listener => {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+  }
+});
+
+/** Where a request of the backend comes from: its correlation id. */
+type Correlation = Pick<RequestContext, "correlationId">;
+
+const SYSTEM: Correlation = { correlationId: "system" };
 
 /** The context whose events are those of shared: its handlers publish them on the shared bus. */
 const SHARED = "shared";
 
 /**
  * Builds every context in a container of its own, child of the container of shared: the dependencies of a context are private to it,
- * those of shared are built once for all. Each request gets a child of its context, with its correlation id, the publisher of its events
- * and its message bus: its handlers and its controllers are built there. The backend event bus is the shared bus: the context map of a
+ * those of shared are built once for all. Each request gets a child of its context, with its correlation id, its signal, the publisher of
+ * its events and its message bus: its handlers and its controllers are built there. Its signal aborts when the signal that goes with its
+ * DTO aborts: a controller gives the signal of its request, so its handler sees its client leave. The backend event bus is the shared bus: the context map of a
  * context shares there the events of shared that the events of its handlers give, and the context map of each context turns the events
  * of shared that it hears into inputs of the context. The handlers of the context shared publish its events there.
  */
@@ -37,7 +90,12 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
   const shared = new Container([bind(ReportError).toValue(reportError), ...modules.shared, ...(options.replace?.shared ?? [])]);
   const contexts = new Map<string, Context>();
   const owners = new Map<unknown, Context>();
-  const listeners = new Set<(event: DomainEvent) => void>();
+  const listeners = new Set<Listener>();
+  /** Aborts when the backend stops: the events of the contexts end. */
+  const stopping = new AbortController();
+  /** The requests without a client see the backend stop: the turns of the timers at once, the reactions to the events once the grace ends. */
+  const turnsEnd = new AbortController();
+  const reactionsEnd = new AbortController();
 
   /** The context of an input DTO, or of a controller: the error of an input is that of the message bus, which names the fix. */
   const ownerOf = (owned: Class, refusal: () => Error): Context => {
@@ -47,27 +105,61 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
   };
   const ownerOfInput = (input: object): Context => ownerOf(input.constructor as Class, () => new UnknownInputError(input.constructor.name));
 
-  /** The container of a request, and its message bus: each input DTO gets a new handler. */
-  const requestOf = ({ container, useCases, shares }: Context, request: RequestContext) => {
+  /**
+   * The container of a request, and its message bus: each input DTO gets a new handler. A request without a client follows `ends`: its
+   * signal aborts when the backend stops it.
+   */
+  const requestOf = (context: Context, { correlationId }: Correlation, ends?: AbortSignal) => {
+    const { container, useCases } = context;
     const bus = new InProcessMessageBus();
+    const left = new AbortController();
+    const request: RequestContext = { correlationId, signal: ends === undefined ? left.signal : AbortSignal.any([left.signal, ends]) };
+    /** The signal of the request follows the one that goes with a DTO: it aborts with it, or at once if it came aborted. */
+    const follow = (signal: AbortSignal | undefined) => {
+      if (signal?.aborted) left.abort(signal.reason);
+      else signal?.addEventListener("abort", () => { left.abort(signal.reason); });
+    };
+    // Who listens to the events that the handlers of this request publish: a controller that streams them.
+    const heard = new Set<Listener>();
     const scope = container.child([
       bind(RequestContext).toValue(request),
-      bind(EventPublisher).toValue({ publish: (event: DomainEvent) => { tell(shares, event, request); } }),
-      ...(container.has(MessageBus) ? [] : [bind(MessageBus).toValue(bus)])
+      bind(EventPublisher).toValue({ publish: (event: DomainEvent) => {
+        for (const listener of [...heard]) listener(event);
+        tell(context, event, request);
+      } }),
+      ...(container.has(MessageBus) ? [] : [bind(MessageBus).toValue(bus)]),
+      ...(container.has(RequestEvents) ? [] : [bind(RequestEvents).toValue(subscriberOf(heard))])
     ]);
-    for (const { input, handler } of useCases) bus.subscribe(input as never, received => scope.create(handler as Concrete<{ execute(input: unknown): unknown }>).execute(received) as never);
+    for (const { input, handler } of useCases) {
+      bus.subscribe(input as never, (received, { signal }) => {
+        follow(signal);
+        return scope.create(handler as Concrete<{ execute(input: unknown): unknown }>).execute(received);
+      });
+    }
     return { scope, bus };
   };
 
-  const send = async (input: object, request: RequestContext = SYSTEM): Promise<unknown> =>
-    requestOf(ownerOfInput(input), request).bus.send(input);
+  /** Sends an input DTO in a request of its own: with a correlation id, "system" by default, and the signal of its client, if it has one. */
+  const send = async (input: object, { correlationId = SYSTEM.correlationId, signal }: Partial<Correlation> & { readonly signal?: AbortSignal } = {}): Promise<unknown> =>
+    requestOf(ownerOfInput(input), { correlationId }).bus.send(input, { signal });
+
+  /** The reactions to the events that run, and the name of their input: the stop reports those that outlive it. */
+  const reactions = new Map<Promise<unknown>, string>();
+  /** Sends the input that an event gives, in a request of its own, which ends when the backend stops the reactions. */
+  const react = (input: object, correlationId: string): Promise<unknown> => {
+    const reaction = (async () => requestOf(ownerOfInput(input), { correlationId }, reactionsEnd.signal).bus.send(input))();
+    reactions.set(reaction, input.constructor.name);
+    const forget = () => { reactions.delete(reaction); };
+    void reaction.then(forget, forget);
+    return reaction;
+  };
 
   /**
    * An event that a handler publishes, in its context: the events of shared that the lines of its map that share give go to the shared
    * bus, in the request of the handler. A line that fails is reported: the handler never waits for the other contexts, nor fails for them.
    */
-  const tell = (shares: Context["shares"], event: DomainEvent, request: RequestContext) => {
-    for (const listener of [...listeners]) listener(event);
+  const tell = ({ shares, listeners: contextListeners }: Context, event: DomainEvent, request: Correlation) => {
+    for (const listener of [...listeners, ...contextListeners]) listener(event);
     let told: DomainEvent[];
     try {
       told = shares(event);
@@ -91,7 +183,7 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
   }]));
   const eventBus = new BackendEventBus({
     map: new ContextMap(lines),
-    send: (input, envelope) => send(input, { correlationId: envelope.correlationId }),
+    send: (input, envelope) => react(input, envelope.correlationId),
     nextEventId: options.nextEventId ?? (() => crypto.randomUUID()),
     reportError
   });
@@ -99,7 +191,8 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
   for (const [name, { bindings, useCases, controllers, map }] of Object.entries(modules.contexts)) {
     const contextMap = new ContextMap(map);
     const shares = name === SHARED ? (event: DomainEvent) => [event] : (event: DomainEvent) => contextMap.eventsFor(event);
-    const context = { container: shared.child([...bindings, ...(options.replace?.[name] ?? [])]), useCases, shares };
+    const context = { container: shared.child([...bindings, ...(options.replace?.[name] ?? [])]), useCases, timers: controllers.filter(isTimer), shares, listeners: new Set<Listener>() };
+    if (!context.container.has(ContextEvents)) context.container.use(ContextEvents, { ...subscriberOf(context.listeners), signal: stopping.signal });
     for (const { input } of useCases) owners.set(input, context);
     for (const controller of controllers) owners.set(controller, context);
     contexts.set(name, context);
@@ -115,15 +208,92 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
     return found;
   };
 
+  const schedule = options.schedule ?? everyInterval;
+  const cancels: (() => void)[] = [];
+  /** The turns that run, and the name of their timer controller. */
+  const turns = new Map<Promise<void>, string>();
+
+  /** The rhythm of a timer controller of a context, in milliseconds: one that Node cannot keep is refused. */
+  const rhythmOf = (context: Context, timer: Concrete<TimerController<object>>) => {
+    const { every } = requestOf(context, SYSTEM).scope.create(timer);
+    if (!(every > 0 && every <= MAX_EVERY)) throw new Error(`${timer.name} runs every ${every} ms, but its every is a number of milliseconds above 0, up to ${MAX_EVERY} (24 days): Node runs a longer one every millisecond`);
+    return every;
+  };
+
+  /** Runs a timer controller of a context every `every` milliseconds, each turn in a request of its own, and never two turns at once. */
+  const run = (context: Context, timer: Concrete<TimerController<object>>, every: number) => {
+    let running = false;
+    cancels.push(schedule(every, () => {
+      if (running) return;
+      running = true;
+      const turn = (async () => {
+        try {
+          await requestOf(context, { correlationId: crypto.randomUUID() }, turnsEnd.signal).scope.create(timer).tick();
+        } catch (error) {
+          reportError(error);
+        }
+      })().finally(() => {
+        running = false;
+        turns.delete(turn);
+      });
+      turns.set(turn, timer.name);
+    }));
+  };
+
   return {
+    /**
+     * Starts the timer controllers of the contexts: the server calls it once it serves. A second call starts nothing more. Each rhythm is
+     * checked before any timer runs: a timer that is refused leaves none running.
+     */
+    start: () => {
+      if (cancels.length > 0) return;
+      const timers = [...contexts.values()].flatMap(context => context.timers.map(timer => ({ context, timer, every: rhythmOf(context, timer) })));
+      for (const { context, timer, every } of timers) run(context, timer, every);
+    },
+    /**
+     * Stops what start started, and releases what the containers built: the server calls it when it stops. It ends the events of the
+     * contexts first: a feed has no end, and would hold the requests that the server waits for. Then it cancels the timers, and aborts
+     * the signal of the turns that run: a work in the background stops with the server. It waits for the turns, for the requests that the
+     * server still serves (`requestsDone`), and for the reactions to the events, until the grace ends (`graceOver`, no limit without it).
+     * Then the signal of the reactions aborts, and the turns and the reactions that still run get one more second, after which the backend
+     * reports them. Last, it releases what each context built, then what shared built. A failure to release is reported.
+     */
+    stop: async (requestsDone?: Promise<unknown>, graceOver?: AbortSignal) => {
+      stopping.abort();
+      for (const cancel of cancels.splice(0)) cancel();
+      turnsEnd.abort();
+      const done = (async () => {
+        while (turns.size > 0) await Promise.all([...turns.keys()]);
+        await requestsDone;
+        await eventBus.settled();
+      })();
+      if (graceOver === undefined) await done;
+      else {
+        await untilEndOrAbort(done, graceOver);
+        reactionsEnd.abort();
+        const late = new AbortController();
+        const timer = setTimeout(() => { late.abort(); }, LAST_WAIT_MS);
+        await untilEndOrAbort(done, late.signal);
+        clearTimeout(timer);
+        const running = [...[...turns.values()].map(name => `a turn of ${name}`), ...[...reactions.values()].map(name => `a reaction with ${name}`)];
+        if (running.length > 0) reportError(new Error(`The backend stopped before these ended: ${running.join(", ")}`));
+      }
+      for (const container of [...[...contexts.values()].map(({ container }) => container), shared]) {
+        try {
+          await container.dispose();
+        } catch (error) {
+          reportError(error);
+        }
+      }
+    },
     /** Sends an input DTO to the context that handles it, in a request of its own. */
     send,
     /** The controller of a context, built for a request. */
-    controller: <C>(controller: abstract new (...args: never[]) => C, request: RequestContext = SYSTEM): C =>
+    controller: <C>(controller: abstract new (...args: never[]) => C, request: Correlation = SYSTEM): C =>
       requestOf(ownerOf(controller, () => new Error(`No context has the controller ${controller.name}: write it in the folder of its use case, as <use-case>.<name>.controller.ts`)), request)
         .scope.create(controller as unknown as Concrete<C>),
     /** Publishes an event of shared on the shared bus. */
-    publish: (event: DomainEvent, request: RequestContext = SYSTEM) => { eventBus.publish(event, request); },
+    publish: (event: DomainEvent, request: Correlation = SYSTEM) => { eventBus.publish(event, request); },
     redeliver: (published: Published) => { eventBus.redeliver(published.event, published.envelope); },
     /** Watches every event on the shared bus, in its envelope. */
     subscribe: (listener: (published: Published) => void) => eventBus.subscribe(listener),

package/src/messaging/ContextEvents.ts

@@ -0,0 +1,11 @@
+import type { DomainEvent } from "../DomainEvent.js";
+import { Token } from "../Token.js";
+import type { EventSubscriber } from "./EventSubscriber.js";
+
+/**
+ * The events that the handlers of a context publish, in every request: a controller that streams a feed writes them. They end when the
+ * backend stops: then `signal` aborts, and a feed ends with them.
+ */
+export type ContextEvents = EventSubscriber<DomainEvent> & { readonly signal: AbortSignal };
+
+export const ContextEvents = new Token<ContextEvents>();

package/src/messaging/Controller.ts

@@ -1,61 +1,9 @@
 import type { MessageBus } from "./MessageBus.js";
 import { reportToConsole, type ReportError } from "./ReportError.js";
+import { BodyTooLargeError, CrossSiteRequestError, InvalidInputError, MalformedBodyError, Request, UnsupportedMediaTypeError } from "./Request.js";
 
-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 {}
-
-/** The largest body that readBody 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 JSON of the body. The request must say that its body is JSON: content-type application/json, or a type with the suffix +json.
- * A browser sends a body of another type (text/plain, a form) from any site, without asking the server first: such a request cannot
- * change the data of the app. 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 request stays readable.
- * @throws {UnsupportedMediaTypeError} when the request does not say that its body is JSON: the Controller answers 415.
- * @throws {BodyTooLargeError} when the body is larger than `maxSize`: the Controller answers 413.
- * @throws {MalformedBodyError} when the body is not JSON: the Controller answers 400.
- */
-export async function readBody(request: Request, maxSize = MAX_BODY_SIZE): Promise<unknown> {
-  const contentType = request.headers.get("content-type");
-  if (!contentType?.match(JSON_MEDIA_TYPE)) throw new UnsupportedMediaTypeError("The content type must be application/json");
-  const text = await textOf(request.clone(), maxSize);
-  try {
-    return JSON.parse(text);
-  } catch {
-    throw new MalformedBodyError("Invalid JSON");
-  }
-}
-
-/** The text of the body, read chunk by chunk: the reading stops at the first chunk after `maxSize` bytes. */
-async function textOf(request: Request, maxSize: number): Promise<string> {
-  const decoder = new TextDecoder();
-  let text = "";
-  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`);
-    text += decoder.decode(chunk.value, { stream: true });
-  }
-  return text + decoder.decode();
-}
+// The errors of a request that a controller reads, which its toErrorResponse answers.
+export { BodyTooLargeError, CrossSiteRequestError, InvalidInputError, MalformedBodyError, MAX_BODY_SIZE, UnsupportedMediaTypeError } from "./Request.js";
 
 const problemType = (slug: string) => `urn:caits:problem:${slug}`;
 
@@ -66,43 +14,57 @@ export function problem(status: number, slug: string, title: string, detail?: st
   });
 }
 
-/** Turns a request into an input DTO, sends it to the message bus of the request, and turns the output or the error into a response. */
+/**
+ * The response to an error of the request or of the application. A body that is neither JSON nor a form is a 415, a
+ * body too large a 413, a form that a browser sends from another site a 403, a body that is not JSON, or not the form that it says, a
+ * 400, a body that toDto refuses a 422 with its issues, and any other error is an internal server error, which is reported and tells
+ * nothing.
+ */
+export function errorResponseOf(error: unknown, reportError: ReportError): Response {
+  if (error instanceof UnsupportedMediaTypeError) return problem(415, "unsupported-media-type", "Unsupported media type", error.message);
+  if (error instanceof BodyTooLargeError) return problem(413, "request-body-too-large", "Request body too large", error.message);
+  if (error instanceof CrossSiteRequestError) return problem(403, "cross-site-request", "Cross-site request", error.message);
+  if (error instanceof MalformedBodyError) return problem(400, "invalid-request-body", "Invalid request body", error.message);
+  if (error instanceof InvalidInputError) return problem(422, "invalid-request-body", "Invalid request body", error.message, { issues: error.details });
+  reportError(error);
+  return problem(500, "internal-server-error", "Internal server error");
+}
+
+/**
+ * Turns a request into an input DTO, sends it to the message bus of the request, and turns the output or the error into a response. It
+ * reads the request through the Request of CAITS, which gives the content of the body at each call, and gives the bus the signal of the
+ * request with the DTO: its handler sees its client leave.
+ */
 export abstract class Controller<Dto extends object, Output> {
-  constructor(private bus: MessageBus, private reportError: ReportError = reportToConsole) {}
+  constructor(private bus: MessageBus, protected readonly reportError: ReportError = reportToConsole) {}
 
   protected abstract toDto(request: Request): Dto | Promise<Dto>;
 
   protected abstract toResponse(output: Output, request: Request): Response | Promise<Response>;
 
   /**
-   * The response to an error of the request or of the application. A body that does not say it is JSON is a 415, a body too large a 413,
-   * a body that is not JSON a 400, a body that toDto refuses a 422 with its issues, and any other error is an internal server error. A
-   * controller answers its own errors first, then calls super.
+   * The response to an error of the request or of the application. A body that is neither JSON nor a form is a 415, a
+   * body too large a 413, a form that a browser sends from another site a 403, a body that is not JSON, or not the form that it says, a
+   * 400, a body that toDto refuses a 422 with its issues, and any other error is an internal server error. A controller answers its own
+   * errors first, then calls super.
    */
   protected toErrorResponse(error: unknown, _request: Request): Response | Promise<Response> {
-    if (error instanceof UnsupportedMediaTypeError) return problem(415, "unsupported-media-type", "Unsupported media type", error.message);
-    if (error instanceof BodyTooLargeError) return problem(413, "request-body-too-large", "Request body too large", error.message);
-    if (error instanceof MalformedBodyError) return problem(400, "invalid-request-body", "Invalid request body", error.message);
-    if (error instanceof InvalidInputError) return problem(422, "invalid-request-body", "Invalid request body", error.message, { issues: error.details });
-    return this.internalServerError(error);
+    return errorResponseOf(error, this.reportError);
   }
 
-  async handle(request: Request): Promise<Response> {
+  /** Answers a request of the web: toDto, toResponse and toErrorResponse read it through the Request of CAITS. */
+  async handle(received: globalThis.Request): Promise<Response> {
+    const request = new Request(received);
     try {
       let output: Output;
       try {
-        output = await this.bus.send(await this.toDto(request)) as Output;
+        output = await this.bus.send(await this.toDto(request), { signal: request.signal }) as Output;
       } catch (error) {
         return await this.toErrorResponse(error, request);
       }
       return await this.toResponse(output, request);
     } catch (failure) {
-      return this.internalServerError(failure);
+      return errorResponseOf(failure, this.reportError);
     }
   }
-
-  private internalServerError(error: unknown): Response {
-    this.reportError(error);
-    return problem(500, "internal-server-error", "Internal server error");
-  }
 }

package/src/messaging/EventSubscriber.ts

@@ -1,4 +1,4 @@
-/** Subscribes to the events of a frontend context: the store gets it. It cannot publish. */
+/** Subscribes to the events of a context: in the frontend, the store gets it; in the backend, the controllers that stream. It cannot publish. */
 export interface EventSubscriber<E> {
   subscribe(listener: (event: E) => void): () => void;
 }

package/src/messaging/InProcessMessageBus.ts

@@ -1,4 +1,4 @@
-import type { MessageBus } from "./MessageBus.js";
+import type { MessageBus, Sending } from "./MessageBus.js";
 
 type InputClass<I> = abstract new (...args: never[]) => I;
 
@@ -18,16 +18,17 @@ export class DuplicateHandlerError extends Error {
 
 /** The message bus of one context, in the process: each handler subscribes to the class of the input DTO it handles. */
 export class InProcessMessageBus implements MessageBus {
-  private handlers = new Map<unknown, (input: never) => unknown>();
+  private handlers = new Map<unknown, (input: never, sending: Sending) => unknown>();
 
-  subscribe<I extends object>(input: InputClass<I>, handler: (input: I) => unknown): void {
+  /** The handler gets the input, and what goes with it: the signal of its request. */
+  subscribe<I extends object>(input: InputClass<I>, handler: (input: I, sending: Sending) => unknown): void {
     if (this.handlers.has(input)) throw new DuplicateHandlerError(input.name);
     this.handlers.set(input, handler);
   }
 
-  async send(input: object): Promise<unknown> {
+  async send(input: object, sending: Sending = {}): Promise<unknown> {
     const handler = this.handlers.get(input.constructor);
     if (!handler) throw new UnknownInputError(input.constructor.name);
-    return await handler(input as never);
+    return await handler(input as never, sending);
   }
 }

package/src/messaging/MessageBus.ts

@@ -1,11 +1,14 @@
 import { Token } from "../Token.js";
 
+/** What goes with an input DTO: the signal of its request, which aborts when its client leaves. Its handler reads it in its RequestContext. */
+export type Sending = { readonly signal?: AbortSignal };
+
 /**
  * Where a controller or a store sends an input DTO: the message bus gives it to the handler of its class, and gives back the output of
  * the handler.
  */
 export interface MessageBus {
-  send(input: object): Promise<unknown>;
+  send(input: object, sending?: Sending): Promise<unknown>;
 }
 
 export const MessageBus = new Token<MessageBus>();