ldap-rest 1.2.1 → 2.0.0

package/docs/usage/upgrading.md

@@ -4,6 +4,259 @@ What to check before deploying, newest first. Only releases that need a
 decision or a configuration change appear here; see the
 [CHANGELOG](../../CHANGELOG.md) for everything else.
 
+## From 1.3.0
+
+### A plugin with its own `service` member
+
+**Who is affected:** a plugin built outside this repository that declares a
+field, getter or method named `service`.
+
+`DmPlugin` now has `service(token)`, which returns the instance another plugin
+provides under a service token. Rename the plugin's own `service` member. See
+[plugin services](../plugin-development/services.md).
+
+### A plugin with its own `provides` member
+
+**Who is affected:** a plugin built outside this repository that declares a
+field named `provides`.
+
+`DmPlugin` now has `provides`, the services a plugin offers to others. Rename
+the plugin's own `provides` member, or it becomes the list of services the
+plugin declares. See
+[plugin services](../plugin-development/services.md#providing-a-service).
+
+### A path parameter is percent-decoded once
+
+**Who is affected:** a client that encoded a path parameter twice to reach an
+identifier holding `%`, sending `/users/100%2525` for the entry `100%`.
+
+The parameter is decoded once now, as RFC 3986 spells it: an identifier
+holding `%` goes out as `100%25`. A parameter still encoded twice names the
+escaped text, so `/users/100%2525` addresses the entry `100%25`
+([details](../client-development/api/rest-api.md#url-encoding)).
+
+### A paged search opens its connection on the first page
+
+**Who is affected:** a plugin calling `ldap.search()` with paging, leaving the
+returned generator unread and expecting a connection to have been opened, or
+expecting a connection or hook error from the call itself.
+
+A paged search takes its pooled connection when the first page is read, not
+when `search()` is called. A generator that is never walked holds no
+connection, and the next request can use the slot. A connection or bind
+failure, the 30 s wait for a pooled connection and an `ldapsearchresult` hook
+that refuses are answered on the first page, not by the call; a read that
+must fail when it is made uses `paged: false`.
+
+### A deletion date written in another shape
+
+**Who is affected:** a deployment whose writer writes the lifecycle deletion
+date as something other than an ISO 8601 date or a GeneralizedTime with its
+zone — for example `date '+%F %T'` (`2025-01-01 12:00:00`), an RFC 2822 date,
+or a US-style `01/02/2025`.
+
+The deletion date is read only in those two shapes now, where the default
+`iso8601` mode handed anything else to `new Date()`. An unreadable date makes
+`erase` answer `409` without `force`, leaves `deletedAt` out of the events,
+and a rule whose payload holds only `$changed.<date>` publishes nothing. Write
+an ISO 8601 date, such as with `date -u '+%Y-%m-%dT%H:%M:%SZ'`, or a
+GeneralizedTime with its zone, and see
+[lifecycle events](plugins/integrations/lifecycle-events.md#configuration).
+
+## From 1.2.1
+
+### A plugin written against the old hooks API
+
+**Who is affected:** a deployment loading a plugin built outside this
+repository that calls `launchHooks` / `launchHooksChained`, or subscribes
+to a `*done` hook with its arguments packed in one tuple.
+
+Hooks are raised through `this.hookBus`, and every hook is declared in
+`src/hooks.ts`: a plugin raising or subscribing to a hook the server does
+not declare no longer compiles. A notified hook — `ldapadddone`,
+`ldapaddafter`, `ldapmodifydone`, `ldaprenamedone`, `ldapgroupadddone`,
+`ldapgroupmodifydone`, `ldapgrouprenamedone`, `ldapexternaluseradded` — now
+gets its arguments one by one: `(dn, entry, context) => …`, not
+`([dn, entry], context) => …`. The packed form still compiles — parameters
+are bivariant — and then reads the DN's first character, so a plugin left
+as it was stops reacting without saying so. `ldapgroupdeletemember` threads
+`[cn, member]`, a single member DN, as it always handed one.
+
+A test waiting for a hook to land waits on `await server.hookBus.settled()`
+rather than sleeping. See [hooks](../plugin-development/hooks.md#the-bus).
+
+### A plugin with its own `options` or `optionDefinitions` member
+
+**Who is affected:** a plugin built outside this repository that declares a
+field, getter or method named `options`, or a static field named
+`optionDefinitions`.
+
+`DmPlugin` now has `options()`, which returns the values a plugin declared
+through `optionDefinitions`. Rename the plugin's own `options` member; a
+plugin that does not declare options keeps reading `this.config` as before.
+
+### A plugin extending `TwakePlugin`
+
+**Who is affected:** a plugin built outside this repository whose class extends
+`TwakePlugin`.
+
+The base constructor takes the WebAdmin URL, token and concurrency instead of
+the names of the options holding them:
+
+```ts
+import { jamesOptionsOf } from 'ldap-rest/plugin-twake-james.options';
+
+const options = jamesOptionsOf(server.config);
+super(server, {
+  url: options.james_webadmin_url,
+  token: options.james_webadmin_token,
+  concurrency: options.james_concurrency,
+  urlOption: 'james_webadmin_url',
+  tokenOption: 'james_webadmin_token',
+  concurrencyOption: 'james_concurrency',
+});
+```
+
+The three `*Option` fields only name the option in the startup error and the
+missing-token warning. `concurrency` must be a positive integer; the base
+refuses anything else, naming `concurrencyOption`.
+
+### A plugin building SCIM's exported helpers
+
+**Who is affected:** a plugin built outside this repository that constructs
+`ScimUsers`, `ScimGroups`, `ScimBulk`, `ScimDiscovery` or `BaseResolver`, or
+calls `scimBodyParser`.
+
+These take the SCIM options instead of a plain `Config`:
+
+```ts
+import { scimOptionsOf } from 'ldap-rest/plugin-scim-scim.options';
+
+const options = scimOptionsOf(config);
+```
+
+`BaseResolver` keeps its `(config, options)` form; the others take the checked
+values beside what they already require.
+
+### An invalid SCIM or Twake value
+
+**Who is affected:** a deployment setting a SCIM limit to zero or a negative
+number, giving a per-instance override of the wrong JSON type, or setting the
+James, Calendar, Drive or migration proxy concurrency to the wrong type.
+
+These options now refuse a value below 1 when the plugin loads: a zero used
+to be silently replaced by the default, and a negative value used as it was.
+Remove the option to keep the default, or give it a positive number.
+
+A per-instance override (`--plugin core/scim:name:{...}`) must also use the
+option's JSON type: `{"scim_max_results": "50"}` and `{"scim_user_base":
+null}` are refused, where the quoted number used to be coerced and the null
+treated as unset. The applicative accounts options refuse the same:
+`{"max_app_accounts": "5"}` used to be kept as the string, and
+`{"applicative_account_attribute": "cn"}` was spread into `['c', 'n']`.
+
+The James, Calendar, Drive and migration proxy concurrency used to replace a
+value that was not a number with `10`, and now refuses it. A zero or a
+negative value was already refused by `p-limit`, and the message now names
+the option. The other Twake options also refuse a value of the wrong JSON
+type in an override.
+
+A zero `--twake-group-max-page-limit`, `--twake-instance-timeout`,
+`--cloudery-workflow-poll-interval-ms` or
+`--cloudery-workflow-max-attempts` used to be replaced by the default and is
+now refused.
+
+The authentication and authorization options are checked the same way. A zero
+`--rate-limit-window-ms`, `--rate-limit-max`, `--crowdsec-cache-ttl`,
+`--authz-per-branch-cache-ttl` or `--authz-dynamic-cache-ttl` used to be
+replaced by the default and is now refused. A zero `--auth-totp-step` or
+`--auth-hmac-window` was accepted and broke the plugin — every counter was
+`Infinity`, every signature not made in the same millisecond was refused — and
+is now refused at startup. A zero `--ldap-organization-max-subnodes`,
+`--ldap-raw-max-results`, `--ppolicy-warn-days`, `--ppolicy-min-length` or
+`--bcl-retention` used to be replaced by the default and is now refused.
+
+`ConfigParser` keeps an empty string for a string option. A plugin reads the
+declared default instead when that default is not empty, as its `|| default`
+used to: `DM_COZY_ADMIN_USER=` gives `admin`, `DM_CLOUDERY_OFFER=` gives
+`b2b_twake_default`. An option whose empty value means something says so in
+its declaration (`--cozy-apps`, `--cozy-user-deleted-routing-key`,
+`--twake-instance-cozy-apps`, `--twake-instance-cozy-context`,
+`--twake-instance-cloudery-offer`) and keeps it; an option whose default is
+empty keeps the empty string.
+
+### The group member check option
+
+**Who is affected:** a deployment passing `--group-allow-unexistent-members`.
+
+That spelling was stored under a key the groups plugin never read, so it never
+disabled member validation. The option is now `--groups-allow-unexistent-members`
+and `DM_ALLOW_UNEXISTENT_MEMBERS`, which the plugin reads; the old spelling is
+gone.
+
+### A config key a plugin did not declare
+
+**Who is affected:** a plugin built outside this repository reading an option
+through `this.config.<name>` without declaring it.
+
+`Config` no longer has an index signature, so such a read does not compile.
+Declare the option with `defineOptions` and read it through `this.options()`
+(see [plugin options](../plugin-development/options.md)); the declaration also
+makes the option known to the startup report and its `env` variable read.
+
+### Node 22 or later is required
+
+**Who is affected:** a deployment running on Node 20 (end of life
+2026-04-30). A deployment of the published image is not: it is built on Node 24.
+
+`engines` declares `>=22`, and the CI runs the suite on 22, 24 and 26. Node
+20 is neither tested nor supported.
+
+### Values past 4096 characters, and an address with a trailing or empty label
+
+**Who is affected:** a deployment whose schemas accept a value longer than
+4096 characters, or an address such as `a@b.c.` or `a@b..c` in an attribute
+whose pattern came with the shipped schemas.
+
+A schema `test` pattern is no longer run on a value longer than 4096
+characters; the value is answered 400, naming the length, before the pattern
+sees it, so that a pattern cannot be made to walk several kilobytes. This
+holds for every attribute in every schema which carries a pattern, a
+deployment's own included, and none of the shipped schemas declares a longer
+limit. An attribute holding longer values declares its own `maxLength`, a
+whole number of characters, or the server refuses to load the schema:
+
+```json
+{
+  "sshPublicKey": {
+    "type": "array",
+    "items": { "type": "string", "maxLength": 16384, "test": "^[^\\r\\n]*$" }
+  }
+}
+```
+
+The address patterns shipped with the schemas no longer accept a trailing dot
+or an empty label: `a@b.c.`, `a@b..c` and `a@.b.c` are refused. Entries already holding
+such a value stay as they are; the value is refused the next time that
+attribute is written. A deployment that copied one of these patterns keeps
+its own copy, unbounded only if it declares no `maxLength`; the patterns to
+use are in the
+[schema reference](../../docs/client-development/schemas/README.md#test-optional).
+
+### A `null` under a name the schema does not declare
+
+**Who is affected:** a client sending `null` to an entity whose schema does
+not declare the attribute, or to an entity without a schema — the
+`dhcpHosts` and `dnsRecords` schemas shipped with `"strict": false` among
+them.
+
+Such a write answered 500, with nothing written. It now succeeds: the key is
+left out of a creation or an `add`, and clears the attribute in a `replace`.
+No action is required. A strict schema still answers 400 for such a name, and
+the value is written as if the key were left out, so a client relying on the
+500 to notice a misspelt attribute no longer hears about it — see
+[what a value must look like](../client-development/schemas/README.md#what-a-value-must-look-like).
+
 ## From 1.2.0 to 1.2.1
 
 ### `{org}` once in a Twake branch pattern