ldap-rest 1.1.0 → 1.2.1

package/docs/usage/plugins/ldap/organizations.md

@@ -28,13 +28,13 @@ This plugin manages hierarchical organizations stored as `organizationalUnit` (o
 
 ### Configuration Options
 
-| Argument                                                    | Environment Variable                  | Default                         | Description                                         |
-| ----------------------------------------------------------- | ------------------------------------- | ------------------------------- | --------------------------------------------------- |
-| `--ldap-top-organization`                                   | `DM_LDAP_TOP_ORGANIZATION`            | _Required_                      | DN of the top-level organization                    |
-| `--ldap-organization-class` / `--ldap-organization-classes` | `DM_LDAP_ORGANIZATION_CLASSES`        | `["top", "organizationalUnit"]` | Object classes for organizations                    |
-| `--ldap-organization-link-attribute`                        | `DM_LDAP_ORGANIZATION_LINK_ATTRIBUTE` | `twakeDepartmentLink`           | Attribute for linking users/groups to organizations |
-| `--ldap-organization-path-attribute`                        | `DM_LDAP_ORGANIZATION_PATH_ATTRIBUTE` | `twakeDepartmentPath`           | Attribute for the organizational path               |
-| `--ldap-organization-path-separator`                        | `DM_LDAP_ORGANIZATION_PATH_SEPARATOR` | `" / "`                         | Separator for path components                       |
+| Argument                                                    | Environment Variable                  | Default                                  | Description                                         |
+| ----------------------------------------------------------- | ------------------------------------- | ---------------------------------------- | --------------------------------------------------- |
+| `--ldap-top-organization`                                   | `DM_LDAP_TOP_ORGANIZATION`            | _Required_                               | DN of the top-level organization                    |
+| `--ldap-organization-class` / `--ldap-organization-classes` | `DM_LDAP_ORGANIZATION_CLASSES`        | `top,organizationalUnit,twakeDepartment` | Object classes for organizations                    |
+| `--ldap-organization-link-attribute`                        | `DM_LDAP_ORGANIZATION_LINK_ATTRIBUTE` | `twakeDepartmentLink`                    | Attribute for linking users/groups to organizations |
+| `--ldap-organization-path-attribute`                        | `DM_LDAP_ORGANIZATION_PATH_ATTRIBUTE` | `twakeDepartmentPath`                    | Attribute for the organizational path               |
+| `--ldap-organization-path-separator`                        | `DM_LDAP_ORGANIZATION_PATH_SEPARATOR` | `" / "`                                  | Separator for path components                       |
 
 ### Important Notes
 

package/docs/usage/plugins/utilities/metrics.md

@@ -0,0 +1,21 @@
+# Metrics Plugin
+
+Prometheus metrics of the server, on a port of their own.
+
+## Configuration
+
+```bash
+--plugin core/metrics --metrics-port 9464
+```
+
+`--metrics-port` (`DM_METRICS_PORT`, 9464) is the port `GET /metrics` is
+served on, see [configuration](../../configuration.md#coremetrics).
+
+The port is separate from the API's: nothing on it goes through the
+authentication, the rate limiting or the request id, so it must not be
+reachable from outside the cluster or the host. The Helm chart exposes it
+on the Service and to a Prometheus operator with `metrics.enabled` and
+`metrics.serviceMonitor.enabled`.
+
+What is measured, and how to read it, is in
+[operations](../../operations.md#metrics).

package/docs/usage/plugins/utilities/static.md

@@ -242,12 +242,7 @@ for instance to `/static/index.html`.
 
 ### Example 4: Multiple Static Plugins
 
-Not directly supported, but you can nest directories:
-
-```bash
---plugin core/static \
---static-path ./static
-```
+One plugin serves several applications from sub-directories:
 
 ```
 ./static/
@@ -259,14 +254,27 @@ Not directly supported, but you can nest directories:
     users.json
 ```
 
-Access via:
-
 ```
 /static/docs/index.html
 /static/app/index.html
 /static/schemas/users.json
 ```
 
+A second directory takes a second instance, loaded under a name of its own
+with its own `static_name` and `static_path`
+([`module:name:{json}`](../auth/README.md#serving-several-populations-from-one-server)):
+
+```bash
+--plugin core/static --static-path ./static \
+--plugin 'core/static:console:{"static_name":"console","static_path":"./console"}'
+```
+
+Give them paths that do not nest: `console` and `console/app` would have the
+first one answer requests meant for the second. The plugins that announce a
+schema URL (groups, organizations, flat entities, SCIM) ask every instance,
+the one registered as `static` first, and leave out one whose path lies under
+an earlier one's, or holds it.
+
 ## Security Considerations
 
 ### Path Traversal

package/docs/usage/plugins/utilities/storage.md

@@ -110,6 +110,13 @@ answer "absent" with a warning and writes fail at once instead of waiting.
 does not answer or a package that is not installed; the server starts anyway,
 and every operation tries to connect again.
 
+## Readiness
+
+`GET /readyz` lists the plugin as `degraded` when the backend does not
+answer; the `ldap` backend keeps its records in the directory the probe
+checks on its own, see
+[operations](../../operations.md#what-the-shipped-plugins-report).
+
 ## Expiry
 
 Two rules the backends do not get to reinterpret:

package/docs/usage/plugins/utilities/weblogs.md

@@ -18,6 +18,9 @@ No additional configuration required.
 
 ### Request Logging
 
+Each line carries the `requestId` of the answer's `X-Request-Id`, see
+[operations](../../operations.md#request-id).
+
 Each request is logged when it arrives:
 
 ```
@@ -31,26 +34,31 @@ Each response is logged when completed at **notice** level (between info and war
 ```json
 {
   "level": "notice",
-  "message": "GET /api/v1/ldap/users 200 45ms",
-  "user": "admin",
-  "method": "GET",
-  "url": "/api/v1/ldap/users",
-  "status": 200,
-  "responseTime": "45ms"
+  "message": {
+    "requestId": "6effd260-b079-4335-b727-544189ed33a6",
+    "method": "GET",
+    "url": "/api/v1/ldap/users",
+    "status": 200,
+    "duration": 45,
+    "ip": "10.0.9.12",
+    "user": "admin"
+  },
+  "requestId": "6effd260-b079-4335-b727-544189ed33a6",
+  "timestamp": "2026-10-26T18:07:03.286Z"
 }
 ```
 
 ## Log Fields
 
-| Field          | Description                     | Example                           |
-| -------------- | ------------------------------- | --------------------------------- |
-| `message`      | Summary line                    | `GET /api/v1/ldap/users 200 45ms` |
-| `user`         | Authenticated user (if any)     | `admin`                           |
-| `method`       | HTTP method                     | `GET`, `POST`, `PUT`, `DELETE`    |
-| `url`          | Full URL including query params | `/api/v1/ldap/users?match=*`      |
-| `status`       | HTTP status code                | `200`, `404`, `500`               |
-| `responseTime` | Request duration                | `45ms`, `123ms`                   |
-| `error`        | Error message (if applicable)   | `Connection timeout`              |
+| Field       | Description                     | Example                        |
+| ----------- | ------------------------------- | ------------------------------ |
+| `user`      | Authenticated user (if any)     | `admin`                        |
+| `requestId` | The answer's `X-Request-Id`     | `6effd260-b079-…`              |
+| `method`    | HTTP method                     | `GET`, `POST`, `PUT`, `DELETE` |
+| `url`       | Full URL including query params | `/api/v1/ldap/users?match=*`   |
+| `status`    | HTTP status code                | `200`, `404`, `500`            |
+| `duration`  | Request duration, in ms         | `45`, `123`                    |
+| `error`     | Error message (if applicable)   | `Connection timeout`           |
 
 ## Enriching the Log Line From Another Plugin
 
@@ -77,6 +85,7 @@ Output:
   "level": "notice",
   "message": {
     "uids": ["jdoe", "asmith"],
+    "requestId": "6effd260-b079-4335-b727-544189ed33a6",
     "method": "POST",
     "url": "/api/_getldapentries",
     "status": 200,
@@ -89,7 +98,7 @@ Output:
 
 Notes:
 
-- Core fields (`method`, `url`, `status`, `duration`, `ip`, `user`, `error`)
+- Core fields (`requestId`, `method`, `url`, `status`, `duration`, `ip`, `user`, `error`)
   always take precedence: a plugin cannot overwrite them.
 - The value must be set **before** the response completes (i.e. before
   `res.json()` / `res.end()`), since the entry is written on the `finish` event.
@@ -319,27 +328,40 @@ res.on('close', () => {
 Logs are in JSON format for easy parsing:
 
 ```bash
-cat app.log | jq 'select(.status >= 400)'
+cat app.log | jq 'select(.message.status? >= 400)'
 ```
 
 Filters 4xx and 5xx responses:
 
 ```json
 {
-  "level": "info",
-  "message": "GET /api/v1/ldap/users/notfound 404 12ms",
-  "status": 404,
-  "method": "GET",
-  "url": "/api/v1/ldap/users/notfound"
+  "level": "notice",
+  "message": {
+    "requestId": "6effd260-b079-4335-b727-544189ed33a6",
+    "method": "GET",
+    "url": "/api/v1/ldap/users/notfound",
+    "status": 404,
+    "duration": 12,
+    "ip": "10.0.9.12"
+  },
+  "requestId": "6effd260-b079-4335-b727-544189ed33a6",
+  "timestamp": "2026-10-26T18:07:03.286Z"
 }
 ```
 
+The lines of one request, the access line and what the server logged while
+serving it:
+
+```bash
+cat app.log | jq 'select(.requestId == "6effd260-b079-4335-b727-544189ed33a6")'
+```
+
 ### Statistics
 
 Generate request statistics:
 
 ```bash
-cat app.log | jq -r '.message' | awk '{print $1}' | sort | uniq -c
+cat app.log | jq -r 'select(.message.method?) | .message.method' | sort | uniq -c
 ```
 
 Output:
@@ -356,8 +378,7 @@ Output:
 Average response time per endpoint:
 
 ```bash
-cat app.log | jq -r 'select(.responseTime) | "\(.url) \(.responseTime)"' | \
-  sed 's/ms$//' | \
+cat app.log | jq -r 'select(.message.duration?) | "\(.message.url) \(.message.duration)"' | \
   awk '{sum[$1]+=$2; count[$1]++} END {for (url in sum) print url, sum[url]/count[url] "ms"}'
 ```
 
@@ -377,16 +398,16 @@ For high-traffic deployments:
 
 ## Log Rotation
 
-Configure log rotation using environment or external tools:
+Rotate the log file with external tools:
 
-### Using Winston File Transport
+### Writing to a file
 
 ```bash
---log-file ./logs/ldap-rest.log \
---log-max-size 10485760 \    # 10MB
---log-max-files 5
+--logger file --log-file ./logs/ldap-rest.log
 ```
 
+The server does not rotate the file itself.
+
 ### Using logrotate (Linux)
 
 ```

package/docs/usage/upgrading.md

@@ -4,6 +4,90 @@ 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.2.0 to 1.2.1
+
+### `{org}` once in a Twake branch pattern
+
+**Who is affected:** a deployment whose `--twake-group-base`,
+`--twake-group-user-base` or `--twake-space-base` holds `{org}` more than
+once. None is known.
+
+The server refuses to start on such a pattern. It filled the first `{org}`
+only and read the organization back from the first one, so a second
+occurrence never worked; now that every occurrence is filled, the two
+readings would disagree.
+
+## From 1.1 to 1.2.0
+
+### The process stops on an uncaught exception
+
+**Who is affected:** every deployment; a supervisor, Kubernetes or systemd,
+restarts the process, as it should.
+
+An exception nothing caught was logged and the process kept serving in a
+state nobody knew. The binary now shuts down and exits with 1. On
+`SIGTERM` it also drains what is in flight within `--shutdown-timeout`
+(20 s) and closes its connections before the signal ends it, where the
+signal ended the process at once, the broker connection closed first when
+`core/rabbitmq` was loaded. A host assembling the server in its own
+process gets neither unless it asks: `run()` no longer installs the handlers
+that logged an uncaught exception or an unhandled rejection and kept the
+process alive, so without `exitOnCrash()` or handlers of its own, Node's
+action applies and the process ends on either. See
+[shutdown](operations.md#shutdown).
+
+### The readiness of a pod follows the directory
+
+**Who is affected:** a deployment of the Helm chart, whose probes now call
+`GET /healthz` and `GET /readyz` instead of opening the listen port.
+
+A pod leaves the endpoints while the directory does not answer, where it
+kept receiving requests and answering 500; a rollout started during a
+directory outage waits for the directory. Both routes are served without
+authentication: an Ingress routing `/` exposes them, keep the two paths to
+the cluster. See [operations](operations.md#health-and-readiness).
+
+### `--ldap-dn` and `--ldap-pwd` are required
+
+**Who is affected:** a deployment that left one of them unset, and so bound
+as `cn=admin,dc=example,dc=com` or with the password `admin`; the published
+Docker image carried both in its `ENV`, and the Helm chart's example only set
+the password.
+
+The server now stops at startup naming the missing option. Set `DM_LDAP_DN`
+and `DM_LDAP_PWD` (or `--ldap-dn` and `--ldap-pwd`) to the values that were
+implied.
+
+### Every entity route checks the shape of a value
+
+**Who is affected:** a script or connector writing through `/api/v1/ldap/<entity>`,
+`/api/v1/ldap/groups` or `/api/v1/ldap/organizations` text that is not a
+number for a `number` or `integer`, a `delete` of a `required` attribute as
+a whole, or a change naming an attribute a strict schema does not declare;
+one writing through `/api/v1/ldap/<entity>` several values for an attribute
+the schema does not type `array`; and one changing a `fixed` attribute of a
+group, which the server dropped from the change and answered 200. The
+server now answers 400, naming the attribute. A group creation sending a
+value under a `fixed` attribute now writes the schema's default, or the
+value when the schema gives none, where it wrote nothing. The shipped LSC connector sends shapes that stay
+accepted, a list of one in a `replace` and one value for an `array` on a
+creation; its whole-attribute delete is refused for a `required` attribute,
+as any, and a group synchronisation that forces `objectClass` or another
+`fixed` attribute now has the whole update refused: keep those attributes
+out of the group updates.
+
+Send one value for a single-valued attribute, a list for an `array` (one
+value, or a list of one, is taken either way), numbers as numbers or digits,
+and `null` or `[]` in a `replace` to clear an attribute. The rules are in
+[what a value must look like](../client-development/schemas/README.md#what-a-value-must-look-like).
+
+### `--logger`: `console` or `file`
+
+A `DM_LOGGER` set to anything else wrote `error.log` in the working
+directory; the server now stops at startup. Set `DM_LOGGER=file` to keep
+that file, and `DM_LOG_FILE` to name another one. An empty `DM_LOGGER` is
+`console`.
+
 ## From 1.0 to 1.1.0
 
 ### The static files can no longer be framed by another origin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -160,6 +160,10 @@
       "types": "./dist/src/plugins/ldap/trash.d.ts",
       "import": "./dist/plugins/ldap/trash.js"
     },
+    "./plugin-metrics": {
+      "types": "./dist/src/plugins/metrics.d.ts",
+      "import": "./dist/plugins/metrics.js"
+    },
     "./plugin-rabbitmq": {
       "types": "./dist/src/plugins/rabbitmq.d.ts",
       "import": "./dist/plugins/rabbitmq.js"
@@ -288,6 +292,10 @@
       "types": "./dist/src/plugins/twake/lifecycleEvents.d.ts",
       "import": "./dist/plugins/twake/lifecycleEvents.js"
     },
+    "./plugin-twake-migrationproxy": {
+      "types": "./dist/src/plugins/twake/migrationProxy.d.ts",
+      "import": "./dist/plugins/twake/migrationProxy.js"
+    },
     "./plugin-twake-spaces": {
       "types": "./dist/src/plugins/twake/spaces.d.ts",
       "import": "./dist/plugins/twake/spaces.js"
@@ -754,6 +762,7 @@
     "multer": "^2.0.2",
     "node-fetch": "^3.3.2",
     "p-limit": "^7.1.1",
+    "prom-client": "^15.1.3",
     "winston": "^3.17.0"
   },
   "devDependencies": {
@@ -795,7 +804,7 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@linagora/rabbitmq-client": "^0.1.2",
+    "@linagora/rabbitmq-client": "^0.7.2",
     "express-openid-connect": "^2.19.2",
     "iovalkey": "^0.4.0",
     "lemonldap-ng-handler": "^0.7.3",

package/static/schemas/example/README.md

@@ -20,6 +20,7 @@ Point a server at them with:
 ```sh
 node bin/index.mjs \
   --ldap-base dc=example,dc=org \
+  --ldap-dn cn=admin,dc=example,dc=org --ldap-pwd secret \
   --ldap-top-organization ou=organization,dc=example,dc=org \
   --ldap-group-base ou=lists,ou=groups,dc=example,dc=org \
   --group-schema static/schemas/example/groups.json \