ldap-rest 1.2.1 → 2.0.0

package/docs/client-development/schemas/README.md

@@ -66,7 +66,7 @@ A complete schema consists of two main sections: entity metadata and attribute d
     },
     "mail": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
       "required": false,
       "role": "primaryEmail"
     },
@@ -74,7 +74,7 @@ A complete schema consists of two main sections: entity metadata and attribute d
       "type": "array",
       "items": {
         "type": "string",
-        "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+        "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
       },
       "required": false,
       "role": "emailAliases"
@@ -197,7 +197,7 @@ Simple text values.
   },
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
     "required": false,
     "role": "primaryEmail"
   },
@@ -237,7 +237,7 @@ Multi-valued attributes containing multiple items of the same type.
     "type": "array",
     "items": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
     },
     "required": false,
     "role": "emailAliases"
@@ -338,19 +338,20 @@ Complete reference for all attribute properties.
 
 ### Attribute Properties Table
 
-| Property   | Type            | Applies To          | Description                                                                           | Example                             |
-| ---------- | --------------- | ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
-| `type`     | string          | All                 | `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`, `"boolean"`, `"date"`    | `"string"`                          |
-| `required` | boolean         | All                 | Whether the attribute must be present                                                 | `true`                              |
-| `fixed`    | boolean         | All                 | Whether the attribute value cannot be changed after creation                          | `true`                              |
-| `role`     | string/string[] | String              | Semantic role, or roles, for special handling (see [Semantic Roles](#semantic-roles)) | `"identifier"`                      |
-| `test`     | string/regex    | String, Array items | Regular expression for validation                                                     | `"^[a-zA-Z0-9._-]{1,255}$"`         |
-| `branch`   | string[]        | Pointer             | LDAP branches where referenced entries exist                                          | `["ou=users,dc=example,dc=com"]`    |
-| `ui`       | object          | Pointer             | UI configuration for pointer selection (future feature)                               | `{}`                                |
-| `hint`     | text            | String, Array items | What a valid value looks like, shown under the field and quoted in refusals           | `"Expected pattern 999 9999"`       |
-| `group`    | text            | All                 | Form section the attribute is shown in                                                | `"Mailbox Settings"`                |
-| `default`  | any             | All                 | Default value for new entries                                                         | `["top", "person"]`                 |
-| `items`    | object          | Array               | Schema for array element validation                                                   | `{"type": "string", "test": "..."}` |
+| Property    | Type            | Applies To          | Description                                                                           | Example                             |
+| ----------- | --------------- | ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
+| `type`      | string          | All                 | `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`, `"boolean"`, `"date"`    | `"string"`                          |
+| `required`  | boolean         | All                 | Whether the attribute must be present                                                 | `true`                              |
+| `fixed`     | boolean         | All                 | Whether the attribute value cannot be changed after creation                          | `true`                              |
+| `role`      | string/string[] | String              | Semantic role, or roles, for special handling (see [Semantic Roles](#semantic-roles)) | `"identifier"`                      |
+| `test`      | string/regex    | String, Array items | Regular expression for validation                                                     | `"^[a-zA-Z0-9._-]{1,255}$"`         |
+| `maxLength` | number          | String, Array items | Longest value accepted, in characters; a longer one is refused before `test` (4096)   | `255`                               |
+| `branch`    | string[]        | Pointer             | LDAP branches where referenced entries exist                                          | `["ou=users,dc=example,dc=com"]`    |
+| `ui`        | object          | Pointer             | UI configuration for pointer selection (future feature)                               | `{}`                                |
+| `hint`      | text            | String, Array items | What a valid value looks like, shown under the field and quoted in refusals           | `"Expected pattern 999 9999"`       |
+| `group`     | text            | All                 | Form section the attribute is shown in                                                | `"Mailbox Settings"`                |
+| `default`   | any             | All                 | Default value for new entries                                                         | `["top", "person"]`                 |
+| `items`     | object          | Array               | Schema for array element validation                                                   | `{"type": "string", "test": "..."}` |
 
 A _text_ is a plain string or a map keyed by language tag,
 `{ "en": "Mailbox Settings", "fr": "Paramètres de messagerie" }`, picked as
@@ -378,16 +379,40 @@ answers, one value where the attribute holds one, can be sent back as is;
 two values or more for a single-valued attribute are refused. Each element
 of an `array` follows `items.type`, text without `items`. A `number` or
 `integer` is a JSON number or its text (`42`, `"42"`), a `boolean` a JSON
-boolean or the directory's `TRUE` / `FALSE`; anything else for them, and
+boolean or the directory's `TRUE` / `FALSE`. A JSON number is judged on the
+text written for it, what the directory is sent: `1e21` and `1e-7` are
+written `1e+21` and `1e-7`, so they are refused like that text, and a whole
+number beyond 2⁵³ is refused whatever the type, as the JSON parser has
+already lost its digits. Anything else for them, and
 anything but text for a `string`, `date` or `pointer`, is refused; an
 attribute with `normalize` takes any text, read after validation. In a
 `replace`, `null` or `[]` clears an attribute; in an `add` or on a creation
-they are refused as no value. A `delete` naming the attribute, or naming it
-with no value, removes it, unless it is `required`; naming values removes
-those, every value it holds included, as the server does not read what
-remains, and `''` names no value. An empty string sent as a value is
-checked against `test`, refused for a pointer, and missing for a `required`
-attribute. Every refusal answers 400 with the attribute's name.
+they are refused as no value when the schema declares the attribute. A
+`null` under a name the schema does not declare — and, for an entity without
+a schema, under any name — is dropped from a creation and from an `add`, as
+if the key were left out, and clears the attribute in a `replace`. A
+`delete` naming the attribute, or naming it with no value, removes it,
+unless it is `required`; naming values removes those, every value it holds
+included, as the server does not read what remains, and `''` names no
+value. An empty string sent as a value is checked against `test`, refused
+for a pointer, and missing for a `required` attribute. Every refusal answers
+400 with the attribute's name.
+
+#### What an attribute may be called
+
+A name is read as the directory reads it: case and the `;binary` option do
+not change the attribute it names, so `Cn`, `CN` and `cn;binary` all name
+`cn`. Each key the schema declares is written under the schema's spelling —
+`Cn` becomes `cn`, `L;binary` becomes `l;binary` — before any check, so that
+a `required` attribute counts as present wherever it was sent, and a `fixed`
+one is written once, at its default. The attribute's type is read the same
+way when a value is converted, so a boolean sent as `pwdReset;binary` is
+written `TRUE`.
+
+Two keys of an entry or of one part of a change naming one attribute are
+refused; the option does not make them two, so `l` and `l;binary` are
+refused together. A name the schema does not declare is left as sent, and a
+strict schema refuses it.
 
 Every entity route applies these rules; `test/lib/entitySchema.contract.test.ts`
 asserts them on a flat entity, a group and an organization alike. In the
@@ -451,7 +476,10 @@ Assigns semantic meaning to attributes for special handling by the application.
 
 #### `test` (Optional)
 
-Regular expression pattern for validating attribute values.
+Regular expression pattern for validating attribute values. The value is
+judged only up to its attribute's length: see
+[`maxLength`](#maxlength-optional) below, which a deployment writing its own
+pattern should read.
 
 ```json
 {
@@ -461,7 +489,7 @@ Regular expression pattern for validating attribute values.
   },
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
   }
 }
 ```
@@ -474,7 +502,38 @@ Regular expression pattern for validating attribute values.
     "type": "array",
     "items": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
+    }
+  }
+}
+```
+
+#### `maxLength` (Optional)
+
+Longest value, in UTF-16 code units (what `.length` counts, so an emoji or an
+accented letter outside the basic plane counts as two), accepted before `test`
+runs on it. A value past
+it is refused with 400, and the pattern never reads it — whether or not it
+would have matched. On an array, `maxLength` on the attribute governs every
+item; one declared under `items` is read only when the attribute declares
+none. It is a positive whole number of characters: the server refuses to load
+a schema where it is not.
+
+A pattern is written for values of its attribute, not for a payload of any
+size: handed several kilobytes, a pattern whose parts overlap walks the value
+in quadratic time, on the event loop that answers every other request
+meanwhile. The limit keeps the pattern within what it was written for. It is
+**4096** unless the schema says otherwise; an attribute holding longer values
+— a description, a public key — declares its own.
+
+```json
+{
+  "sshPublicKey": {
+    "type": "array",
+    "items": {
+      "type": "string",
+      "maxLength": 16384,
+      "test": "^[^\\r\\n]*$"
     }
   }
 }
@@ -594,7 +653,7 @@ Email-related roles help applications handle email addresses consistently across
 {
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
     "required": false,
     "role": "primaryEmail"
   }
@@ -609,7 +668,7 @@ Email-related roles help applications handle email addresses consistently across
     "type": "array",
     "items": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
     },
     "required": false,
     "role": "emailAliases"
@@ -686,9 +745,14 @@ Common validation patterns:
 **Email:**
 
 ```regex
-^[^@\s]+@[^@\s]+\.[^@\s]+$
+^[^@\s]+@[^@\s.]+(\.[^@\s.]+)+$
 ```
 
+The domain part holds no dot of its own: where it did, the pattern tried every
+dot as the last separator and read the value again each time — seconds for a
+value of a few kilobytes. The result is that a trailing dot (`a@b.c.`) is
+refused, where the older form accepted it.
+
 **DN (Distinguished Name):**
 
 ```regex
@@ -1045,7 +1109,7 @@ Start with the schema that most closely matches your directory type:
   "attributes": {
     "mail": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
       "required": false,
       "role": "primaryEmail"
     },
@@ -1238,7 +1302,7 @@ Use `test` patterns to enforce data quality:
   },
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
   }
 }
 ```

package/docs/development/contracts.md

@@ -0,0 +1,109 @@
+# Published contracts
+
+Other code depends on three things ldap-rest publishes. A change to one that
+is not additive breaks that code, so it needs a major release and the pull
+request says so before it merges.
+
+- **Configuration**: the CLI options and `DM_*` variables of
+  [Configuration](../usage/configuration.md) and of each plugin's page.
+- **REST API**: the routes, request bodies and answers of the
+  [REST API](../client-development/api/rest-api.md), their parameters,
+  responses (references resolved), statuses and response headers. The error
+  `code` values are reviewed by hand: the document types them as strings.
+- **Plugin API**: what the npm sub-path exports declare — `ldap-rest`,
+  `./hooks`, `./plugin`, `./ldapactions`, `./expressformatedresponses`, the
+  `./plugin-*`, `./abstract-*` and `./browser-*` entries — and the JSON
+  schema format of the `./schema-*` entries.
+
+[API stability](../README.md#api-stability) says what a minor or patch
+release promises. This page says how a change is detected, and what to do
+when it is not additive.
+
+## Committed snapshots
+
+Two snapshots are generated locally and checked in CI, so a change to a
+contract shows up as a diff instead of a surprise after the release:
+
+- `docs/usage/options.snapshot.json` lists every option's CLI name, plural
+  form, environment variable, type, default, kind, required flag and aliases.
+  Regenerate it with `npm run snapshot:options`; `npm run check:options`, part
+  of `npm run check`, fails when it is stale.
+- `openapi.json` is the REST API document the published reference is built
+  from. Regenerate it with `npm run generate:openapi`; `npm run check:openapi`
+  fails when it is stale.
+
+The plugin types have no snapshot yet: one api-extractor report per sub-path
+export is a change of its own. Until it lands, a change to an exported type is
+reviewed by hand.
+
+The snapshot records what the parser reads. A narrowed `choices` list, a
+raised `min` or a lowered `max` is checked when a plugin reads its options,
+not by the snapshot, and is reviewed by hand, as is a custom error `code`.
+
+## The pull request gate
+
+The `contracts` job of `.github/workflows/contracts.yml` generates the
+snapshots from the pull request and compares them with the base branch's
+committed ones. It reports:
+
+- additive changes — a new option, route or field — and lets them through;
+- non-additive changes, and fails unless the pull request carries the
+  `breaking` label.
+
+A change is non-additive when it removes or narrows what was published:
+a removed option or environment variable, a changed type, default, bound,
+`const`, enum or required flag, a request value that becomes an enum, a
+request object that stops accepting additional properties, a removed route,
+method, parameter, response status, response header or field, a request field
+that becomes required, a response that may now be null, changed security
+requirements, a removed union variant, a value an alternative of the type
+closes with an enum or a `const` where the type used to accept any, an
+untyped request value that becomes a union, an `allOf` that adds a
+constraint, or — once the plugin snapshot exists — a removed export or a
+narrowed signature. Renaming an option is a deprecation, not a removal, as
+long as the old CLI name and environment variable stay in its `aliases` and
+`envAliases`. Adding a union variant, a field or an optional parameter is
+additive, and so is a request union with an alternative that still accepts
+everything the base did — in a response the client reads every alternative,
+so a field the others drop is still a removal. A `oneOf` is the exception:
+it refuses a value two alternatives match, so an alternative as wide as the
+base narrows the others away, and the alternatives are not told apart from
+one another — a disjoint `oneOf` therefore asks for the label too.
+Documentation-only edits, such as a summary or description, are ignored.
+
+The job runs the scripts from the pull request, so a change to them is
+reviewed like any other code, as `.github/CODEOWNERS` requires.
+
+The `breaking` label records that the maintainers accepted the break, and the
+`CHANGELOG.md` section must say so: the release gate below reads the section,
+not the label, and refuses to ship the break as a minor or patch release. The
+workflow listens to label events, so adding the label runs the job again; it
+has its own concurrency group, so that event does not cancel the test matrix.
+
+To try the comparison locally against your base branch:
+
+```bash
+npx tsx scripts/contracts.ts --base origin/master
+```
+
+## The release gate
+
+`.github/workflows/release.yml` runs `scripts/check-release.ts` on the tag. A
+non-major tag whose `CHANGELOG.md` section lists `### Breaking Changes` is
+refused. For a 0.x version, a minor release counts as major, as semantic
+versioning lets it break. When the tag has no section of its own, the gate
+reads `## Unreleased`, so a tag cut before the section was renamed is still
+checked; with neither section it fails. When the CHANGELOG lists no earlier
+release, only a first `X.0.0` counts as major, so a trimmed file cannot open
+the gate.
+
+## Deprecating instead of breaking
+
+The window and the rules are in
+[CONTRIBUTING.md](../../CONTRIBUTING.md#deprecating-a-published-contract).
+The mechanics of an option alias are in
+[plugin options](../plugin-development/options.md#deprecating-an-option): the
+old CLI name and environment variable go in `aliases` and `envAliases`, and
+the server warns at startup while it still reads them. An array option's
+plural form has no alias slot: renaming it is a breaking change, so it waits
+for a major release.

package/docs/plugin-development/README.md

@@ -7,7 +7,9 @@ This guide will help you create powerful, production-ready plugins for LDAP-Rest
 - [Why Create a Plugin](#why-create-a-plugin)
 - [Plugin Structure](#plugin-structure)
 - [Creating Your Plugin](#creating-your-plugin)
+- [Plugin services](./services.md)
 - [Custom Configuration Options](#custom-configuration-options)
+  - [Plugin options](./options.md)
 - [Loading Your Plugin](#loading-your-plugin)
 - [Plugin Features](#plugin-features)
 - [Configuration Best Practices](#configuration-best-practices)
@@ -53,14 +55,21 @@ export default class MyPlugin extends DmPlugin {
 - **roles** (optional): Array categorizing plugin purpose
 - **dependencies** (optional): Required plugins that must load first
 - **hooks** (optional): Callbacks for LDAP operations
+- **provides** (optional): Typed services this plugin offers, see
+  [plugin services](services.md)
 - **api()** (optional): Method to register REST endpoints
 
 ### Available from Base Class
 
 - **this.server**: DM server instance
 - **this.config**: Complete configuration object
+- **this.options(declarations)**: Values of the options the plugin declares,
+  typed and checked, see [plugin options](options.md)
 - **this.logger**: Winston logger instance
-- **this.registeredHooks**: Access to global hook registry
+- **this.hookBus**: The server's hooks: chain, notify and wait on them, see
+  [hooks](hooks.md#the-bus)
+- **this.service(token)**: The instance another plugin provides under a
+  service token, or `null`, see [plugin services](services.md)
 - **this.fetch**: `fetch` timed into the
   [outbound metrics](../usage/operations.md#metrics) under the plugin's
   name; the lint refuses a bare `fetch` or `node-fetch` under `src`, and a
@@ -272,99 +281,15 @@ npx ldap-rest
 
 ## Custom Configuration Options
 
-LDAP-Rest automatically accepts and stores any unknown command-line options in the config object. This allows your plugin to define custom configuration without modifying core files.
+A core plugin declares its options next to its code, in a
+`<plugin>.options.ts` file, and reads them through `this.options()` with their
+types, defaults and checks. See [plugin options](options.md).
 
-### How It Works
-
-1. **Command-line option format**: `--option-name value`
-2. **Converted to config key**: `option_name` (dashes become underscores)
-3. **Environment variable format**: `DM_OPTION_NAME` (uppercase with underscores)
-4. **Access in plugin**: `this.config.option_name`
-
-### Single Value Options
-
-```bash
-# Command line
-npx ldap-rest \
-  --webhook-url https://example.com/webhook \
-  --webhook-timeout 5000 \
-  --webhook-retry true
-
-# Environment variables
-export DM_WEBHOOK_URL=https://example.com/webhook
-export DM_WEBHOOK_TIMEOUT=5000
-export DM_WEBHOOK_RETRY=true
-```
-
-In your plugin:
-
-```typescript
-constructor(server: DM) {
-  super(server);
-
-  // Access custom options (converted to snake_case)
-  const url = this.config.webhook_url;        // string
-  const timeout = this.config.webhook_timeout; // string (convert if needed)
-  const retry = this.config.webhook_retry;     // string 'true' (convert if needed)
-
-  // Type conversion
-  const timeoutNum = parseInt(timeout as string || '3000');
-  const retryBool = (retry as string) === 'true';
-}
-```
-
-### Multiple Value Options
-
-Repeat the same option multiple times to create an array:
-
-```bash
-# Command line
-npx ldap-rest \
-  --allowed-domain example.com \
-  --allowed-domain test.com \
-  --allowed-domain dev.com
-
-# Environment variable (comma or semicolon separated)
-export DM_ALLOWED_DOMAINS=example.com,test.com,dev.com
-```
-
-In your plugin:
-
-```typescript
-constructor(server: DM) {
-  super(server);
-
-  // Access as array (note: singular becomes plural in config key)
-  const domains = this.config.allowed_domain as string[];
-  // or sometimes stored as: this.config.allowed_domains
-
-  this.logger.info(`Allowed domains: ${domains.join(', ')}`);
-}
-```
-
-### Configuration Priority
-
-Values are resolved in this order (later overrides earlier):
-
-1. **Default value** in your plugin
-2. **Environment variable** (`DM_OPTION_NAME`)
-3. **Command-line argument** (`--option-name`)
-
-```typescript
-constructor(server: DM) {
-  super(server);
-
-  // Provide defaults for optional configuration
-  const webhookUrl = this.config.webhook_url || 'http://localhost:8080/webhook';
-  const webhookTimeout = parseInt(this.config.webhook_timeout as string || '3000');
-  const maxRetries = parseInt(this.config.max_retries as string || '3');
-
-  // Validate required configuration
-  if (!this.config.webhook_secret) {
-    throw new Error('--webhook-secret is required for authentication');
-  }
-}
-```
+A plugin outside the repository cannot add to `src/config/args.ts` yet. It keeps
+reading `this.config.<name>`: LDAP-Rest accepts and stores unknown
+`--option-name value` pairs under `option_name`, with `--option-name` and
+`DM_OPTION_NAME` overriding in that order. See
+[configuration](../usage/configuration.md#environment-variables).
 
 ---
 
@@ -532,7 +457,8 @@ const results = await this.server.ldap.search(
   'ou=users,dc=example,dc=com'
 );
 
-// Search with pagination (returns AsyncGenerator)
+// Search with pagination (returns AsyncGenerator; the connection is taken
+// when the first page is read)
 const pagedResults = await this.server.ldap.search(
   {
     paged: true,
@@ -684,7 +610,15 @@ hooks: Hooks = {
 
 ### Exposing API Endpoints
 
-Create REST API endpoints for your plugin. **Important:** Always use the `asyncHandler` wrapper for async routes to ensure errors are properly handled and don't crash the server.
+Declare routes with [`defineRoute`](routes.md): it types and validates the
+request (`params`, `query`, `body`), answers a failing request with a 400
+naming the paths at fault, and records the route for the OpenAPI document.
+The `asyncHandler` form below remains for routes that have not been migrated
+yet.
+
+Create REST API endpoints for your plugin. Always use the `asyncHandler`
+wrapper for async routes, so that errors are properly handled and do not
+crash the server.
 
 ```typescript
 import DmPlugin, { asyncHandler } from '../../abstract/plugin';
@@ -791,6 +725,29 @@ app.get(
 );
 ```
 
+**Wrapping an error keeps its answer:**
+
+Wrap with `cause` rather than in the message alone. The status and the class
+of what was thrown are read through the chain, so a refusal stays a 403 and
+a timeout a 504 wherever it surfaces:
+
+```typescript
+// ✅ GOOD: the refusal keeps its 403 when it reaches the client
+throw new Error(`Failed to add group ${dn}: ${String(err)}`, { cause: err });
+
+// ❌ BAD: a 403 becomes a 500, and its message is all that is left
+throw new Error(`Failed to add group ${dn}: ${String(err)}`);
+```
+
+**Refusing a caller:**
+
+An authorization plugin throws `AuthzRefusedError`, whose message is for the
+operator: it names the model and the branch it judged. The client is told
+`AUTHZ_REFUSED` with `code: "forbidden"` instead, whatever a plugin wrapped
+it in on the way. A refusal that is not an authorization plugin's is any
+`ForbiddenError`, answered with its own message; `isAuthzRefusal(err)` tells
+the two apart.
+
 **Custom error handling:**
 
 ```typescript
@@ -1369,6 +1326,7 @@ See [Tests and checks](../../CONTRIBUTING.md#tests-and-checks).
 
 - [Contributing Guide](../../CONTRIBUTING.md) - Git workflow and PR guidelines
 - [Hooks Reference](./hooks.md) - Complete list of available hooks
+- [Plugin services](./services.md) - Typed interfaces between plugins
 - [Core Plugin Examples](../../src/plugins/) - Browse existing plugins
 - [Test Examples](../../test/plugins/) - See how core plugins are tested
 

package/docs/plugin-development/dependencies.md

@@ -1,9 +1,10 @@
 # Plugin Dependency Graph
 
-This document describes the dependencies between LDAP-Rest plugins. There are two types of dependencies:
+This document describes the dependencies between LDAP-Rest plugins. There are three types of dependencies:
 
 1. **Explicit Dependencies**: Defined in the `dependencies` property of a plugin class
-2. **Hook Dependencies**: Implicit dependencies through hooks (one plugin provides a hook, another consumes it)
+2. **Service Dependencies**: A plugin reaches a typed interface another one provides, see [plugin services](services.md)
+3. **Hook Dependencies**: Implicit dependencies through hooks (one plugin provides a hook, another consumes it)
 
 ## Dependency Types
 
@@ -24,10 +25,20 @@ overrides — a dependency also given to `--plugin`, or an entry listed twice
 is loaded once: the second request waits for the first. Only an entry with
 overrides builds a second instance, and it needs a name of its own.
 
+### Service Dependencies
+
+A plugin provides a typed interface under a token, and a consumer reaches it
+with `this.service(token)`. The token replaces the registry name as the way to
+find another plugin's code; `dependencies` still decides what loads first. A
+consumer whose provider is absent gets `null` and a single warning.
+
+See [plugin services](services.md) for the token, the provided interface and
+the registration rules.
+
 ### Hook Dependencies
 
 **Hook Providers**: Plugins that implement hooks (via `hooks: Hooks = { ... }`)
-**Hook Consumers**: Plugins that call hooks (via `runHook()` or `launchHooks()`)
+**Hook Consumers**: Plugins that raise hooks (via `this.hookBus`)
 
 ## Complete Dependency Graph
 
@@ -601,10 +612,10 @@ refused before a plugin judges its content, or replaces it.
 2. Returns modified data to next plugin
 3. Last plugin's return value is used
 
-For non-chained hooks:
+For notified hooks, see [hooks](hooks.md#the-bus):
 
-- All hooks execute in parallel
-- Order doesn't matter
+- All hooks run one after the other, in load order
+- A failing one is logged and the next still runs
 
 **Example**: `ldapdeleterequest` chain
 
@@ -642,11 +653,16 @@ export default class MyPlugin extends DmPlugin {
 
 ### Providing Hooks
 
+A hook is declared in `src/hooks.ts` before anything raises it, and raised
+through the bus of the kind it is, see [hooks](hooks.md#the-bus):
+
 ```typescript
 export default class MyPlugin extends DmPlugin {
   async someMethod() {
-    // Fire a hook for other plugins to consume
-    await this.server.launchHooks('myCustomHook', [param1, param2]);
+    // Thread a value through the subscribers of a chained hook
+    value = await this.hookBus.chain('ldapsearchopts', value);
+    // Tell the subscribers of a notified one, without waiting for them
+    this.hookBus.notify('ldapadddone', dn, entry, changeContext(req));
   }
 }
 ```