@ingenioz-it/caits 0.6.0 → 0.8.0

package/src/di/discovered.ts

@@ -1,6 +1,6 @@
 /// <reference path="../virtual-modules.d.ts" />
-import { bindings, dtos, handlers, controllers, maps } from "virtual:kernel/backend";
+import { bindings, handlers, controllers, maps } from "virtual:kernel/backend";
 import { discover } from "./discover.js";
 
 /** Every context of the backend: its di.ts, its use cases, its controllers and its context map. The plugin of the kernel finds them. */
-export const discovered = discover({ bindings, dtos, handlers, controllers, maps });
+export const discovered = discover({ bindings, handlers, controllers, maps });

package/src/di/discoveredFrontends.ts

@@ -1,6 +1,6 @@
 /// <reference path="../virtual-modules.d.ts" />
-import { bindings, dtos, handlers, maps, stores } from "virtual:kernel/frontend";
+import { bindings, handlers, maps, stores } from "virtual:kernel/frontend";
 import { discoverFrontends } from "./discoverFrontends.js";
 
 /** Every context of the frontend: its di.ts, its use cases, its store and its context map. The plugin of the kernel finds them. */
-export const discoveredFrontends = discoverFrontends({ bindings, dtos, handlers, stores, maps });
+export const discoveredFrontends = discoverFrontends({ bindings, handlers, stores, maps });

package/src/messaging/BackendEventBus.ts

@@ -1,6 +1,5 @@
 import type { DomainEvent } from "../DomainEvent.js";
 import type { ContextMap, Envelope } from "./ContextMap.js";
-import type { Input } from "./Input.js";
 import type { ReportError } from "./ReportError.js";
 
 export type Published = { readonly event: DomainEvent; readonly envelope: Envelope };
@@ -18,7 +17,7 @@ export class BackendEventBus {
 
   constructor(private readonly options: {
     map: ContextMap;
-    send: (input: Input<unknown>, envelope: Envelope) => Promise<unknown>;
+    send: (input: object, envelope: Envelope) => Promise<unknown>;
     nextEventId: () => string;
     reportError: ReportError;
   }) {}
@@ -48,7 +47,7 @@ export class BackendEventBus {
 
   private async deliver(event: DomainEvent, envelope: Envelope): Promise<void> {
     await nextTurn();
-    let inputs: Input<unknown>[];
+    let inputs: object[];
     try {
       inputs = this.options.map.inputsFor(event, envelope);
     } catch (error) {

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/ContextMap.ts

@@ -1,5 +1,4 @@
 import type { DomainEvent } from "../DomainEvent.js";
-import type { Input } from "./Input.js";
 
 /** What the shared bus adds to an event it carries: an id of its own, and the correlation id of the request that published it. */
 export type Envelope = { readonly eventId: string; readonly correlationId: string };
@@ -11,14 +10,14 @@ type EventClass<E> = abstract new (...args: never[]) => E;
  * input DTOs of the context, or an event of the context that it shares, which becomes events of the context shared.
  */
 export type Translation =
-  | { readonly shares: false; readonly event: EventClass<DomainEvent>; readonly inputs: (event: never, envelope: Envelope) => Input<unknown>[] }
+  | { readonly shares: false; readonly event: EventClass<DomainEvent>; readonly inputs: (event: never, envelope: Envelope) => object[] }
   | { readonly shares: true; readonly event: EventClass<DomainEvent>; readonly events: (event: never) => DomainEvent[] };
 
 /**
  * A line that hears the context shared: when this event of shared comes on the shared bus, the handlers of the context execute these
  * input DTOs. A context map names only its own context and the context shared: two contexts never name each other.
  */
-export function when<E extends DomainEvent>(event: EventClass<E>, inputs: (event: E, envelope: Envelope) => Input<unknown>[]): Translation {
+export function when<E extends DomainEvent>(event: EventClass<E>, inputs: (event: E, envelope: Envelope) => object[]): Translation {
   return { shares: false, event, inputs };
 }
 
@@ -35,7 +34,7 @@ export class ContextMap {
   constructor(private readonly translations: Translation[]) {}
 
   /** The input DTOs that the lines that hear this event of shared give, none when no line hears it. */
-  inputsFor(event: DomainEvent, envelope: Envelope): Input<unknown>[] {
+  inputsFor(event: DomainEvent, envelope: Envelope): object[] {
     return this.translations.flatMap(translation => !translation.shares && event instanceof translation.event ? translation.inputs(event as never, envelope) : []);
   }
 

package/src/messaging/Controller.ts

@@ -1,62 +1,9 @@
-import type { Input } from "./Input.js";
 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}`;
 
@@ -67,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. */
-export abstract class Controller<Dto extends Input<Output>, Output> {
-  constructor(private bus: MessageBus, private reportError: ReportError = reportToConsole) {}
+/**
+ * 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, 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));
+        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,12 +1,10 @@
-import type { Input } from "./Input.js";
-import type { MessageBus } from "./MessageBus.js";
+import type { MessageBus, Sending } from "./MessageBus.js";
 
-export type OutputOf<I> = I extends Input<infer Output> ? Output : never;
-type InputClass<I extends Input<unknown>> = abstract new (...args: never[]) => I;
+type InputClass<I> = abstract new (...args: never[]) => I;
 
 export class UnknownInputError extends Error {
   constructor(readonly inputName: string) {
-    super(`No handler subscribes to ${inputName}`);
+    super(`No handler takes ${inputName}: write one next to its DTO, in <use-case>.handler.ts, with execute(input: ${inputName})`);
     this.name = "UnknownInputError";
   }
 }
@@ -20,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 Input<unknown>>(input: InputClass<I>, handler: (input: I) => OutputOf<I> | Promise<OutputOf<I>>): 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<Output>(input: Input<Output>): Promise<Output> {
+  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)) as Output;
+    return await handler(input as never, sending);
   }
 }

package/src/messaging/MessageBus.ts

@@ -1,12 +1,14 @@
 import { Token } from "../Token.js";
-import type { Input } from "./Input.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<Output>(input: Input<Output>): Promise<Output>;
+  send(input: object, sending?: Sending): Promise<unknown>;
 }
 
 export const MessageBus = new Token<MessageBus>();

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>();