lakutata 3.0.0 → 3.1.0

package/doc/en/DockerIntegration.md

@@ -23,8 +23,9 @@ remote host.
 | TCP, HTTPS | `host`, `port`, `ca`, `cert`, `key` as PEM contents (`buildDockerHttpsConnectionOptions`) |
 | SSH | `host`, `port`, `username`, `sshAuthAgent` (`buildDockerSSHConnectionOptions`) |
 
-When it is created, the component pings the daemon and negotiates the API version: an unreachable daemon fails the
-launch with `DockerConnectionException`. `timeout` (milliseconds) is the time a request may stay idle.
+When it is created, the component pings the daemon and negotiates the API version: an unreachable daemon makes its
+creation fail with `DockerConnectionException`; when the component is listed in `bootstrap`, the application then fails
+to start. `timeout` (milliseconds) is how long a request may stay idle.
 
 ```typescript
 import {readFileSync} from 'node:fs'
@@ -185,13 +186,13 @@ async function containers(docker: Docker): Promise<void> {
 
 - A `DockerContainer` is a snapshot: its operations refresh it; the changes made by others are seen by getting it
   again (`docker.getContainer(id)`, which also takes a name or a short ID).
-- Starting a running container or stopping a stopped one does nothing, as the Docker CLI.
-- `exec()` runs without TTY nor stdin. An array command runs as it is; a string is a command line, run by
+- Starting a running container, or stopping a stopped one, does nothing, as with the Docker CLI.
+- `exec()` runs without a TTY or stdin. An array command runs as it is; a string is a command line, run by
   `/bin/sh -c`.
 - `kill()` sends `SIGKILL` by default, or the signal given.
 - `commit()` makes an image of a container, `exportDirectory()` writes a directory of a container as a tar archive.
-- Not provided: attaching to the main process, copying files into a container, the volumes (other than by `prune()`)
-  and the daemon's events.
+- Not provided: attaching to the main process, copying files into a container, managing the volumes (other than pruning
+  them) and the events of the daemon.
 
 ## 5. Networks
 

package/doc/en/Entities.md

@@ -0,0 +1,240 @@
+# Lakutata Entities, Queries and Transactions
+
+The entities, the repositories, the queries and the transactions are the ones of [TypeORM](https://typeorm.io) 1: the
+decorators come from `lakutata/decorator/orm`, the rest of the API from `lakutata/orm`. This guide shows the common
+uses; the documentation of TypeORM describes every option.
+
+## 1. Entities
+
+An entity is a class mapped to a table:
+
+```typescript
+import {
+    BeforeInsert, Column, CreateDateColumn, DeleteDateColumn, Entity, Index, JoinColumn, ManyToOne, OneToMany,
+    PrimaryGeneratedColumn, UpdateDateColumn, VersionColumn
+} from 'lakutata/decorator/orm'
+
+@Entity('orders')
+export class Order {
+    @PrimaryGeneratedColumn('uuid')
+    public id: string
+
+    @Index()
+    @Column()
+    public customer: string
+
+    //Saved with the order (cascade)
+    @OneToMany(() => OrderLine, (line: OrderLine) => line.order, {cascade: true})
+    public lines: OrderLine[]
+
+    @CreateDateColumn({type: 'timestamptz'})
+    public createdAt: Date
+
+    @UpdateDateColumn({type: 'timestamptz'})
+    public updatedAt: Date
+
+    //Set by softDelete(): the finds skip the order unless withDeleted is set
+    @DeleteDateColumn({type: 'timestamptz'})
+    public deletedAt: Date | null
+
+    //Incremented by each save
+    @VersionColumn()
+    public version: number
+
+    @BeforeInsert()
+    protected normalize(): void {
+        this.customer = this.customer.trim()
+    }
+}
+
+@Entity('order_lines')
+export class OrderLine {
+    @PrimaryGeneratedColumn()
+    public id: number
+
+    @Column()
+    public product: string
+
+    @Column('integer')
+    public quantity: number
+
+    @ManyToOne(() => Order, (order: Order) => order.lines, {onDelete: 'CASCADE'})
+    @JoinColumn({name: 'order_id'})
+    public order: Order
+}
+```
+
+| Decorators | Use |
+|---|---|
+| `@Entity(name)`, `@ViewEntity`, `@ChildEntity`, `@TableInheritance` | An entity, a view, the inheritance of tables |
+| `@PrimaryGeneratedColumn(strategy)`, `@PrimaryColumn` | The primary key: generated (`'increment'`, `'uuid'`, `'identity'`), or given |
+| `@Column(type, options)` | A column: its type, `length`, `nullable`, `default`, `unique`, `transformer`… |
+| `@CreateDateColumn`, `@UpdateDateColumn`, `@DeleteDateColumn`, `@VersionColumn` | Columns set by TypeORM |
+| `@OneToOne`, `@OneToMany`, `@ManyToOne`, `@ManyToMany`, `@JoinColumn`, `@JoinTable` | The relations |
+| `@Index`, `@Unique`, `@Check` | Indices and constraints |
+| `@BeforeInsert`, `@AfterLoad`, `@BeforeUpdate`… | Methods run around the operations |
+| `@ObjectIdColumn` | The `_id` of the entities of MongoDB |
+
+An entity is listed in the `entities` option of each database that uses it. An entity may also extend `BaseEntity` (from
+`lakutata/orm`) to save and find itself (`await Order.findOneBy({id})`, `await order.save()`): these use the last
+database connected with the entity.
+
+## 2. Queries
+
+A repository (`db.getRepository(Order)`) reads and writes the entities of a table:
+
+```typescript
+import {Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import {Database} from 'lakutata/com/database'
+import {Column, CreateDateColumn, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+import {Between, ILike, type Repository} from 'lakutata/orm'
+
+@Entity('orders')
+class Order {
+    @PrimaryGeneratedColumn('uuid')
+    public id: string
+
+    @Column()
+    public customer: string
+
+    @CreateDateColumn({type: 'timestamptz'})
+    public createdAt: Date
+}
+
+class Orders extends Component {
+    @Inject('db')
+    protected readonly db: Database
+
+    protected get orders(): Repository<Order> {
+        return this.db.getRepository(Order)
+    }
+
+    //A page of the orders of a period, and the count of all of them
+    public async search(customer: string, from: Date, to: Date, page: number): Promise<[Order[], number]> {
+        return await this.orders.findAndCount({
+            where: {customer: ILike(`%${customer}%`), createdAt: Between(from, to)},
+            order: {createdAt: 'DESC'},
+            skip: (page - 1) * 20,
+            take: 20
+        })
+    }
+
+    //A query builder
+    public async byCustomer(customer: string): Promise<Order[]> {
+        return await this.db.createQueryBuilder(Order, 'order')
+            .where('order.customer LIKE :customer', {customer: `%${customer}%`})
+            .orderBy('order.createdAt', 'DESC')
+            .getMany()
+    }
+
+    //SQL: the placeholders are $1, $2… on PostgreSQL, ? on MySQL and SQLite
+    public async count(customer: string): Promise<number> {
+        const rows: { count: string }[] = await this.db.query('SELECT COUNT(*) AS count FROM orders WHERE customer = $1', [customer])
+        return Number(rows[0].count)
+    }
+}
+```
+
+- **Finding:** `find`, `findBy`, `findOne`, `findOneBy`, `findAndCount`, `count`, `exists`; `findOneByOrFail` throws
+  an `EntityNotFoundError` when nothing is found.
+- **The find options** take objects: `where`, `relations: {lines: true}`, `select: {id: true, customer: true}`,
+  `order: {createdAt: 'DESC'}`, `skip` and `take`, `withDeleted`. A list of conditions in `where` is an `OR`.
+- **The find operators** of `lakutata/orm`: `In`, `Not`, `IsNull`, `Like`, `ILike`, `Between`, `MoreThan`,
+  `MoreThanOrEqual`, `LessThan`, `LessThanOrEqual`, `Any`, `ArrayContains`, `Raw`…
+- **Writing:** `save` (inserts or updates, with the cascades of the relations), `insert`, `update`, `delete`,
+  `softDelete` and `restore` (with a `@DeleteDateColumn`), `increment`, `upsert`.
+- **A query builder** (`createQueryBuilder`) writes the queries the find options cannot: joins with conditions, groups,
+  subqueries. Its values (`:customer`) are passed as parameters, never put into the SQL text.
+- **SQL** (`query(sql, parameters)`) returns the rows of the driver as they are: a `COUNT(*)` of PostgreSQL is a string.
+
+## 3. Transactions
+
+`transaction(fn)` runs a function in a transaction: committed when the function resolves, rolled back when it
+rejects, its error thrown again. Every operation of the transaction goes through the entity manager given to the
+function; the ones made through `db.manager` or `db.getRepository()` run outside of it.
+
+```typescript
+import {Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import {Database} from 'lakutata/com/database'
+import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+import {type EntityManager} from 'lakutata/orm'
+
+@Entity('accounts')
+class Account {
+    @PrimaryGeneratedColumn()
+    public id: number
+
+    @Column('integer')
+    public balance: number
+}
+
+class Transfers extends Component {
+    @Inject('db')
+    protected readonly db: Database
+
+    //Both updates, or none
+    public async transfer(from: number, to: number, amount: number): Promise<void> {
+        await this.db.transaction('SERIALIZABLE', async (manager: EntityManager): Promise<void> => {
+            await manager.decrement(Account, {id: from}, 'balance', amount)
+            await manager.increment(Account, {id: to}, 'balance', amount)
+        })
+    }
+}
+```
+
+- The isolation level is optional: `'READ UNCOMMITTED'`, `'READ COMMITTED'`, `'REPEATABLE READ'`, `'SERIALIZABLE'`.
+- `createQueryRunner()` gives a connection of its own, to control a transaction by hand (`startTransaction()`,
+  `commitTransaction()`, `rollbackTransaction()`, then `release()`).
+- MongoDB and the embedded MongoDB have no transactions: there, `transaction()` runs the function without one.
+
+## 4. Values to watch
+
+- **Big numbers.** PostgreSQL and MySQL return the `bigint` and `decimal` columns as strings, to keep their precision.
+  SQLite returns them as numbers, which lose precision beyond 2^53. A column `transformer` converts them where a
+  number is enough:
+
+  ```typescript
+  import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+  import type {ValueTransformer} from 'lakutata/orm'
+
+  const decimal: ValueTransformer = {
+      to: (value: number): number => value,
+      from: (value: string | null): number | null => value === null ? null : Number(value)
+  }
+
+  @Entity('invoices')
+  export class Invoice {
+      @PrimaryGeneratedColumn()
+      public id: number
+
+      @Column({type: 'decimal', precision: 10, scale: 2, transformer: decimal})
+      public total: number
+  }
+  ```
+
+- **`null` and `undefined` in the conditions** are left out of the condition by default: `findOneBy({id: undefined})`
+  finds the first row. See [Database](Database.md), section 2.
+- **Dates.** Prefer the columns with a time zone (`timestamptz` on PostgreSQL). On MySQL, the `timezone` option of the
+  connection tells how the dates are written and read.
+
+## 5. Errors
+
+The errors are the ones of TypeORM, exported by `lakutata/orm`:
+
+| Error | When |
+|---|---|
+| `QueryFailedError` | The database refused a query. Its `driverError` is the error of the driver: on PostgreSQL, the code `23505` is a duplicate key, its `constraint` the name of the constraint |
+| `EntityNotFoundError` | `findOneByOrFail()` and `findOneOrFail()` found nothing |
+| `EntityMetadataNotFoundError` | An entity that is not in the `entities` of the database |
+| `OptimisticLockVersionMismatchError` | A `@VersionColumn` did not match the version expected by a lock |
+| `CannotExecuteNotConnectedError` | A query on a database that is not connected, or no longer is |
+
+```typescript
+import {QueryFailedError} from 'lakutata/orm'
+
+export function isDuplicate(error: unknown): boolean {
+    return error instanceof QueryFailedError && (error.driverError as { code?: string }).code === '23505'
+}
+```

package/doc/en/Entrypoint.md

@@ -0,0 +1,216 @@
+# Lakutata Entrypoint
+
+The `entrypoint` component connects the controllers to the transports. It holds the controllers and the adapters of
+the transports (HTTP, command line, service calls, schedules, queues…): each adapter receives the requests of its
+transport, and the entrypoint runs the matching action, with its middlewares, its validation and its access control.
+
+## 1. Declaring the entrypoint
+
+The `lakutata` package already declares a component named `entrypoint`. An application gives it its options with
+`buildEntrypoints`, under the same name, and lists it in `bootstrap`:
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {GET} from 'lakutata/decorator/ctrl'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+
+class HealthController extends Controller {
+    @GET('/health')
+    public async health(): Promise<string> {
+        return 'ok'
+    }
+}
+
+Application.run(() => ({
+    id: 'api.app',
+    name: 'API',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [HealthController],
+            http: expressHTTPEntrypoint({port: 8080})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+A component is created the first time something needs it. No other object needs the entrypoint, so without
+`bootstrap: ['entrypoint']` it is never created: no server listens, no command runs, no job starts.
+
+## 2. Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `controllers` | `[]` | The controller classes |
+| `http`, `cli`, `service`, `schedule`, `queue`, `mcp`, `dbus` | | The adapters of the transports (below): one adapter, or an array of them |
+| `middlewares` | `[]` | The middlewares of every action (see [Middlewares](Middlewares.md)) |
+| `rules` | `[]` | The access rules of the actions declared with `acl: true` (see [Middlewares](Middlewares.md)) |
+| `shutdownTimeout` | `30000` | The milliseconds given to the requests in progress when the application stops (section 4) |
+| `httpActionGroups`, `cliActionGroups`, `serviceActionGroups` | `{}` | The groups the actions may use, with their names (section 5) |
+
+The adapters:
+
+| Option | Adapter | Imported from | To install | Guide |
+|---|---|---|---|---|
+| `http` | `expressHTTPEntrypoint()` | `lakutata/adapter/express` | `express` | [HTTP](HTTP.md) |
+| `http` | `fastifyHTTPEntrypoint()` | `lakutata/adapter/fastify` | `fastify` | [HTTP](HTTP.md) |
+| `cli` | `commanderCLIEntrypoint()` | `lakutata/adapter/commander` | `commander` | [CLI](CLI.md) |
+| `service` | `httpServiceEntrypoint()` | `lakutata/com/entrypoint` | | [ServiceCalls](ServiceCalls.md) |
+| `service` | `socketIOServiceEntrypoint()` | `lakutata/adapter/socket.io` | `socket.io` | [ServiceCalls](ServiceCalls.md) |
+| `service` | `jsonRPCServiceEntrypoint()` | `lakutata/adapter/jsonrpc` | `ws`, for WebSocket | [ServiceCalls](ServiceCalls.md) |
+| `service` | `electronIPCServiceEntrypoint()` | `lakutata/adapter/electron` | (Electron) | [ServiceCalls](ServiceCalls.md) |
+| `service` | `grpcServiceEntrypoint()` | `@lakutata/grpc/service` | `@lakutata/grpc` | [GRPC](GRPC.md) |
+| `service` | `natsServiceEntrypoint()` | `@lakutata/nats` | `@lakutata/nats` | [NATS](NATS.md) |
+| `schedule` | `scheduleEntrypoint()` | `lakutata/com/entrypoint` | | [Schedules](Schedules.md) |
+| `queue` | `queueEntrypoint()` | `lakutata/com/queue` | The client of the queue server | [Queue](Queue.md) |
+| `mcp` | `httpMCPEntrypoint()`, `stdioMCPEntrypoint()` | `@lakutata/mcp` | `@lakutata/mcp` | [MCP](MCP.md) |
+| `dbus` | `dbusEntrypoint()` | `@lakutata/dbus` | `@lakutata/dbus` | [DBus](DBus.md) |
+
+## 3. Several adapters
+
+Each option accepts an array, to serve one transport in several ways. For example, the service actions over Socket.IO
+for the browsers and over JSON-RPC for the scripts, or the HTTP actions on two ports:
+
+```typescript
+import {buildEntrypoints} from 'lakutata/com/entrypoint'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {jsonRPCServiceEntrypoint} from 'lakutata/adapter/jsonrpc'
+import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+
+export const entrypoint = buildEntrypoints({
+    controllers: [],
+    http: [
+        expressHTTPEntrypoint({name: 'public', port: 8080}),
+        expressHTTPEntrypoint({name: 'internal', host: '127.0.0.1', port: 9090})
+    ],
+    service: [
+        socketIOServiceEntrypoint({port: 3000}),
+        jsonRPCServiceEntrypoint({port: 4000, path: '/rpc'})
+    ]
+})
+```
+
+Every adapter of a transport serves all the actions of that transport. The `name` option tells the adapters apart.
+
+## 4. Starting and stopping
+
+**When the application launches**, the entrypoint first checks the controllers. Each of these mistakes stops the
+launch with its exception:
+
+- two actions of the same transport with the same name (`DuplicateActionNameException`);
+- an action in a group that its `*ActionGroups` option does not declare (`InvalidActionGroupException`);
+- a prefix that conflicts with the pattern of an action (`InvalidPrefixException`);
+- a middleware that is neither a function nor a `Middleware` class (`InvalidMiddlewareException`);
+- an adapter given under the key of another transport, or an option that is neither an option of the entrypoint nor a
+  transport (`InvalidEntrypointAdapterException`).
+
+Then the adapters start one after another, in the order of the options. One that fails, such as a server whose port is
+already in use, stops the launch. The command line and the scheduled jobs begin once the whole application has
+launched.
+
+**When the application stops** (on `SIGTERM` or `SIGINT`, or after `app.exit()`), the adapters stop in the reverse
+order:
+
+1. they stop accepting new requests. Depending on the transport, a request that still arrives is refused with an
+   `EntrypointStoppedException` (status 503 over HTTP);
+2. the requests in progress are given `shutdownTimeout` (30 seconds by default) to finish;
+3. the requests still running are aborted: their `this.signal` fires, and they are answered with an
+   `EntrypointStoppedException`;
+4. the adapters close their servers and connections.
+
+## 5. Groups and the list of the actions
+
+The `groups` option of an action puts it in groups. The access rules can use them (see [Middlewares](Middlewares.md)),
+and the entrypoint can list the actions by group, to build an index of an API or a list of permissions. The groups of
+the HTTP, command line and service actions must be declared, with their names:
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller, type Entrypoint} from 'lakutata/com/entrypoint'
+import {DELETE, GET} from 'lakutata/decorator/ctrl'
+import {Inject} from 'lakutata/decorator/di'
+
+class UserController extends Controller {
+    @Inject('entrypoint')
+    protected readonly entrypoint: Entrypoint
+
+    @GET('/users', {description: 'List the users'})
+    public async list(): Promise<string[]> {
+        return []
+    }
+
+    @DELETE('/users/:id', {description: 'Delete a user', groups: ['admin']})
+    public async remove(): Promise<void> {
+    }
+
+    //The actions of each group: [{"group":"Administration","actions":["Delete a user"]}]
+    @GET('/permissions')
+    public async permissions(): Promise<{ group: string, actions: string[] }[]> {
+        return this.entrypoint.getHttpActions().groups.map((group) => ({
+            group: group.name,
+            actions: group.actions.map((action): string => action.description)
+        }))
+    }
+}
+
+Application.run(() => ({
+    id: 'users.app',
+    name: 'Users',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [UserController],
+            httpActionGroups: {admin: 'Administration'}
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+`getHttpActions()`, `getCliActions()` and `getServiceActions()` return `{groups, actions}`: `groups` holds the declared
+groups (`id`, `name` and their `actions`), `actions` every action of the transport. `getActions(channel)` lists the
+actions of any other transport (`getActions('schedule')`). Each action is described by:
+
+| Property | Meaning |
+|---|---|
+| `id` | A stable id, computed from its controller, its method and its address |
+| `name`, `description`, `groups`, `acl` | Its options |
+| `controller`, `method` | The name of its controller class, and of its method |
+| `route` / `command` / `pattern` | Its address, prefix included |
+| `jsonSchema` | The JSON schema of its DTO |
+
+## 6. Pushing events to the clients
+
+The service transports that keep their clients connected (Socket.IO, Electron, the event stream of the HTTP service,
+JSON-RPC over WebSocket or stdio, gRPC) can receive events from the application.
+`entrypoint.notify(clientId, event, ...args)` sends an event to the client whose id an action found in
+`this.context.clientId`, and returns whether that client received it. `entrypoint.broadcast(event, ...args)` sends it to
+every connected client, and returns their number. See [GRPC](GRPC.md) and [ServiceCalls](ServiceCalls.md).
+
+## 7. Customizing the entrypoint
+
+A subclass of `Entrypoint` can replace the class of the component: declare it with `class`, and give the same options
+next to it.
+
+```typescript
+import {AccessControl, Entrypoint} from 'lakutata/com/entrypoint'
+
+//Logs every decision of the access control
+class AuditedAccessControl extends AccessControl {
+    protected async match(): Promise<boolean> {
+        const allowed: boolean = await super.match()
+        console.log(`${this.target.name}: ${allowed ? 'allowed' : 'denied'}`)
+        return allowed
+    }
+}
+
+export class AuditedEntrypoint extends Entrypoint {
+    protected readonly accessControl: typeof AccessControl = AuditedAccessControl
+}
+
+//components: {entrypoint: {class: AuditedEntrypoint, controllers: [...], http: ...}}, bootstrap: ['entrypoint']
+```
+
+An adapter for another transport implements the `EntrypointAdapter` interface of `@lakutata/entrypoint/channel`. The
+entrypoint functions of lakutata 2.x (`buildHTTPEntrypoint`, `buildCLIEntrypoint`, `buildServiceEntrypoint`) are still
+accepted by the `http`, `cli` and `service` options.

package/doc/en/Exceptions.md

@@ -0,0 +1,174 @@
+# Lakutata Exceptions
+
+`Exception`, from `lakutata`, is the base class of the errors of the framework, and of the application's own. An
+exception has a code (`errno`) that the clients and the logs identify the error by, a message built from a template, and
+the HTTP status of the error. The transports send these to the clients when an action fails.
+
+## 1. Declaring an exception
+
+Extend `Exception`, set `errno` and, for the errors that reach the clients, `statusCode`:
+
+```typescript
+import {Exception} from 'lakutata'
+
+export class OrderNotFoundException extends Exception {
+    public errno: string = 'E_ORDER_NOT_FOUND'
+
+    public readonly statusCode: number = 404
+}
+
+export class PaymentFailedException extends Exception {
+    public errno: string = 'E_PAYMENT_FAILED'
+
+    public readonly statusCode: number = 502
+
+    //A property of its own: sent and logged with the error
+    public readonly gateway: string = 'stripe'
+}
+
+export function findOrder(id: number): never {
+    throw new OrderNotFoundException('Order {id} not found', {id: id})
+}
+```
+
+An exception carries:
+
+| Property | What it is |
+|---|---|
+| `errno` | The code of the error, a string (`'E_ORDER_NOT_FOUND'`) or a number |
+| `message`, `errMsg` | The message; `errMsg` is a copy of it, sent to the clients |
+| `err` | The name of the class (`'OrderNotFoundException'`) |
+| `statusCode` | The HTTP status of the error; 500 by default |
+| `appId`, `appName` | The id and the name of the application, `'Unknown'` when the exception is created before the application has loaded its options |
+| `stack` | The stack trace |
+
+The properties of the subclass, such as `gateway` above, are sent and logged with the others.
+
+## 2. The message
+
+The arguments of the constructor build the message:
+
+| Created with | Message |
+|---|---|
+| `new OrderNotFoundException('Order {id} not found', {id: 7})` | `Order 7 not found` |
+| `new OrderNotFoundException('Order {0} of {1} not found', 7, 'ada')` | `Order 7 of ada not found` |
+| `new OrderNotFoundException('Order {0} of {1} not found', [7, 'ada'])` | `Order 7 of ada not found` |
+| `new OrderNotFoundException('Order {0} not found', 7)` | `Order 7 not found` |
+| `new OrderNotFoundException('Order %d not found (%s)', 7, 'archived')` | `Order 7 not found (archived)` |
+| `new OrderNotFoundException('Order {id} of {owner} not found', {id: 7})` | `Order 7 of {owner} not found` |
+| `new OrderNotFoundException('Order not found')` | `Order not found` |
+| `new OrderNotFoundException(new Error('timeout'))` | `timeout` |
+| `new OrderNotFoundException()` | `Order not found exception` |
+
+- A template takes its values from an object (`{id}`), or from the parameters that follow it, by position (`{0}`,
+  `{1}`), given one by one or as an array. The placeholders of `util.format()` (`%s`, `%d`, `%j`…) take the same
+  parameters.
+- A value that is missing leaves its placeholder in the message. Building the message never throws.
+- Without arguments, the message is made of the words of the class name; the acronyms are kept
+  (`HTTPRequestException` gives `HTTP request exception`).
+
+## 3. A default message and the cause
+
+To give an exception a default message, take it in a constructor and pass it to `super()`:
+
+```typescript
+import {Exception} from 'lakutata'
+
+export class QuotaExceededException extends Exception {
+    public errno: string = 'E_QUOTA_EXCEEDED'
+
+    public readonly statusCode: number = 429
+
+    constructor(message: string = 'The quota of the month is used up') {
+        super(message)
+    }
+}
+```
+
+Avoid setting `message` in a field: the field would replace the message given when the exception is thrown, and with
+the compiler option `useDefineForClassFields` set to `true`, `errMsg` would keep the default message. The
+`tsconfig.json` published by `lakutata` sets that option to `false`.
+
+`new XxxException(error)` keeps only the message of the error. To keep the error itself, set it as the `cause`:
+
+```typescript
+import {Exception} from 'lakutata'
+
+class PaymentFailedException extends Exception {
+    public errno: string = 'E_PAYMENT_FAILED'
+
+    public readonly statusCode: number = 502
+}
+
+export async function pay(orderId: number, charge: () => Promise<void>): Promise<void> {
+    try {
+        await charge()
+    } catch (error) {
+        const failure: PaymentFailedException = new PaymentFailedException('Payment of order {id} failed', {id: orderId})
+        failure.cause = error
+        throw failure
+    }
+}
+```
+
+The logger writes the causes after the error (see [Logger](Logger.md), section 2), and the HTTP adapters read the status
+along the causes: the first client error (4xx) found wins (see [HTTP](HTTP.md), section 6).
+
+## 4. What the clients receive
+
+When an action fails, its transport reports the exception:
+
+| Transport | The client receives |
+|---|---|
+| HTTP | The status `statusCode` and `{errno, errMsg}` (see [HTTP](HTTP.md), section 6) |
+| Socket.IO, Electron, the HTTP service, NATS, gRPC | The whole error: all its own properties (see [ServiceCalls](ServiceCalls.md), section 3) |
+| JSON-RPC | An error with the code `-32602` for an invalid input, `-32601` when no action matches, `-32001` while the application stops, `-32000` otherwise, and the whole error as its `data` |
+| The command line | `error: <message>` on the standard error, and the exit code 1 (see [CLI](CLI.md)) |
+| Schedules | No client: the exception is given to `onError`, or logged (see [Schedules](Schedules.md)) |
+
+- Choose `statusCode` by what the client can do about the error: 400 to 499 when the request is wrong (404 for a
+  missing resource, 409 for a conflict), 500 and above when the application failed.
+- An input refused by its DTO is an `InvalidValueException`, whose status is 400: an error of the client.
+
+## 5. Translating and recognizing an exception
+
+With the `I18nMiddleware`, the message of an exception is translated into the language of the request, from the key
+`errors.<errno>` and the parameters of its template (see
+[I18n](I18n.md#exception-messages)). Out of a request, `exceptionParams(exception)`, from `lakutata`, gives
+those parameters.
+
+To recognize an exception, use `instanceof` within the application, and `errno` across processes: the clients receive
+the properties of an error, not its class. The proxies of the HTTP service, NATS and gRPC throw a
+`ServiceInvokeException` that carries the `errno` of the remote error.
+
+```typescript
+import {Exception} from 'lakutata'
+
+class OrderNotFoundException extends Exception {
+    public errno: string = 'E_ORDER_NOT_FOUND'
+}
+
+export function isMissingOrder(error: unknown): boolean {
+    return error instanceof OrderNotFoundException || (error as { errno?: unknown })?.errno === 'E_ORDER_NOT_FOUND'
+}
+```
+
+## 6. The exceptions of the framework
+
+The framework throws exceptions of its own. The ones met most often:
+
+| Exception | `errno` | When |
+|---|---|---|
+| `InvalidValueException` | `E_INVALID_VALUE` | A DTO refuses a value: the input of an action, a call to `validate()` (400) |
+| `InvalidObjectOptionsException` | `E_INVALID_OBJECT_OPTIONS` | The options of an object are invalid, when the application starts |
+| `DependencyInjectionException` | `E_DEPENDENCY_INJECTION` | An object cannot be created: a dependency is missing |
+| `AccessDeniedException` | `E_ACCESS_DENY` | The access control refuses a request (403) |
+| `RouteNotFoundException` | `E_ROUTE_NOT_FOUND` | No HTTP action has this route and method (404) |
+| `ControllerActionNotFoundException` | `E_CONTROLLER_ACTION_NOT_FOUND` | No action matches a service message or a command (404) |
+| `EntrypointStoppedException` | `E_ENTRYPOINT_STOPPED` | The application is stopping (503) |
+| `ServiceInvokeException` | `E_SERVICE_INVOKE` | An action called through a proxy (HTTP service, NATS, gRPC) failed; it carries the properties of the remote error |
+| `ServiceUnavailableException` | `E_SERVICE_UNAVAILABLE` | The service called by an `HTTPServiceProxy` gave no response (503) |
+
+The README of each package lists its own exceptions. An exception that nothing catches, and an exception that stops the
+launch of the application, go to its handlers (`onUncaughtException`, `onFatalException`, see
+[Application](Application.md), section 2).