ldap-rest 0.17.0 → 0.18.0

package/docs/client-development/api/rest-api.md

@@ -1075,6 +1075,16 @@ curl -X POST \
 }
 ```
 
+A member that does not exist answers 400 naming it, and none of the members
+is added (unless `--group-allow-unexistent-members` is set). Group creation
+checks its `member` list the same way:
+
+```json
+{
+  "error": "Member uid=nobody,ou=users,dc=example,dc=com not found"
+}
+```
+
 ### Remove Group Member
 
 Remove a user from a group.
@@ -1146,7 +1156,7 @@ All errors return a JSON object with an error message:
 
 ```json
 {
-  "error": "Invalid value for attribute \"uid\": must match ^[a-zA-Z0-9._-]{1,255}$"
+  "error": "Invalid value for attribute \"uid\""
 }
 ```
 

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

@@ -335,18 +335,23 @@ Complete reference for all attribute properties.
 
 ### Attribute Properties Table
 
-| Property   | Type         | Applies To          | Description                                                                      | Example                             |
-| ---------- | ------------ | ------------------- | -------------------------------------------------------------------------------- | ----------------------------------- |
-| `type`     | string       | All                 | Attribute data type: `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"` | `"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              | Semantic role 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)                          | `{}`                                |
-| `group`    | string       | All                 | UI grouping for form organization (future feature)                               | `"contact"`                         |
-| `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                 | Attribute data type: `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`      | `"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": "..."}` |
+
+A _text_ is a plain string or a map keyed by language tag,
+`{ "en": "Mailbox Settings", "fr": "Paramètres de messagerie" }`, picked as
+[labels are](../../usage/plugins/ldap/flat-generic.md#naming-things-in-the-readers-language).
 
 ### Property Details
 
@@ -394,7 +399,7 @@ Marks the attribute as immutable after creation. Useful for objectClass or ident
 
 #### `role` (Optional)
 
-Assigns semantic meaning to attributes for special handling by the application. See [Semantic Roles](#semantic-roles).
+Assigns semantic meaning to attributes for special handling by the application. See [Semantic Roles](#semantic-roles). An attribute holding several roles lists them: `"role": ["domainName", "displayName"]`.
 
 ```json
 {

package/docs/plugin-development/dependencies.md

@@ -18,6 +18,12 @@ dependencies = {
 };
 ```
 
+A dependency is loaded when the plugin registers, unless a plugin of that
+name already is. A module requested again under the same name and without
+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.
+
 ### Hook Dependencies
 
 **Hook Providers**: Plugins that implement hooks (via `hooks: Hooks = { ... }`)
@@ -194,9 +200,7 @@ dependencies = {
   - `onLdapForwardChange` - Syncs forwarding
   - `onLdapChange` - General LDAP change handling
   - `onLdapDisplayNameChange` - Syncs display name
-  - `ldapgroupadddone` - After group added
-  - `ldapgroupmodifydone` - After group modified
-  - `ldapgroupdeletedone` - After group deleted
+  - `onLdapEntryChange` - Follows team mailboxes
 - **Consumes Hooks**: (Hooks provided by `onLdapChange`)
 - **Notes**: Synchronizes LDAP users/groups with Apache James mail server
 

package/docs/presentations/en.md

@@ -115,7 +115,6 @@ export default class MyPlugin extends DmPlugin {
 - 📧 **Automatic LDAP → James Sync**
 - 🔄 **Mail Address Changes** - Account renaming + data
 - 💾 **Quota Management** - Automatic updates
-- 👥 **Mailing Lists** - LDAP Groups → Address Groups
 - 📨 **Mail Aliases** - mailAlternateAddress → James aliases
 - 🎯 **WebAdmin API** - REST Communication
 
@@ -159,33 +158,6 @@ James WebAdmin: PUT /quota/users/alice@.../size
 
 <!-- end_slide -->
 
-# James Plugin - List Consistency
-
-## LDAP Groups → James Address Groups
-
-```bash
-# Create a group with mail attribute
-POST /api/v1/ldap/groups
-{
-  "cn": "engineering",
-  "mail": "engineering@company.com",
-  "member": ["uid=alice,...", "uid=bob,..."]
-}
-```
-
-### Automatic List Consistency
-
-1. ✅ **Creation** → Group created in James + members added
-2. ✅ **Add Member** → Member added to James list
-3. ✅ **Remove Member** → Member removed from James list
-4. ✅ **Delete Group** → List deleted in James
-
-### Guarantee
-
-**LDAP is the source of truth, James stays synchronized**
-
-<!-- end_slide -->
-
 # LDAP Consistency
 
 ## Automatic Consistency Plugins

package/docs/presentations/fr.md

@@ -115,7 +115,6 @@ export default class MyPlugin extends DmPlugin {
 - 📧 **Synchronisation automatique LDAP → James**
 - 🔄 **Changement d'adresse mail** - Renommage compte + données
 - 💾 **Gestion des quotas** - Mise à jour automatique
-- 👥 **Listes de diffusion** - Groupes LDAP → Address Groups
 - 📨 **Alias mail** - mailAlternateAddress → James aliases
 - 🎯 **WebAdmin API** - Communication via REST
 
@@ -159,33 +158,6 @@ James WebAdmin: PUT /quota/users/alice@.../size
 
 <!-- end_slide -->
 
-# Plugin James - Cohérence des listes
-
-## Groupes LDAP → James Address Groups
-
-```bash
-# Création d'un groupe avec attribut mail
-POST /api/v1/ldap/groups
-{
-  "cn": "engineering",
-  "mail": "engineering@company.com",
-  "member": ["uid=alice,...", "uid=bob,..."]
-}
-```
-
-### Cohérence automatique des listes
-
-1. ✅ **Création** → Groupe créé dans James + membres ajoutés
-2. ✅ **Ajout membre** → Membre ajouté à la liste James
-3. ✅ **Retrait membre** → Membre retiré de la liste James
-4. ✅ **Suppression groupe** → Liste supprimée dans James
-
-### Garantie
-
-**LDAP est la source de vérité, James reste synchronisé**
-
-<!-- end_slide -->
-
 # Cohérence LDAP
 
 ## Plugins de cohérence automatique

package/docs/usage/configuration.md

@@ -452,16 +452,20 @@ whichever of the two names it selects. A value other than `req.user` or
 
 #### `core/twake/james`
 
-| CLI                              | Plural                          | Env                               | Default                 | Description                 |
-| -------------------------------- | ------------------------------- | --------------------------------- | ----------------------- | --------------------------- |
-| `--james-webadmin-url`           |                                 | `DM_JAMES_WEBADMIN_URL`           | `http://localhost:8000` | James WebAdmin API URL      |
-| `--james-webadmin-token`         |                                 | `DM_JAMES_WEBADMIN_TOKEN`         |                         | James authentication token  |
-| `--james-signature-template`     |                                 | `DM_JAMES_SIGNATURE_TEMPLATE`     |                         | Email signature template    |
-| `--james-concurrency`            |                                 | `DM_JAMES_CONCURRENCY`            | `10`                    | James API concurrency       |
-| `--james-init-delay`             |                                 | `DM_JAMES_INIT_DELAY`             | `1000`                  | Init delay (ms)             |
-| `--james-mailing-list-branch`    | `--james-mailing-list-branches` | `DM_JAMES_MAILING_LIST_BRANCHES`  | `[]`                    | Mailing list branches       |
-| `--james-mailbox-type-attribute` |                                 | `DM_JAMES_MAILBOX_TYPE_ATTRIBUTE` | `twakeMailboxType`      | Mailbox type attribute      |
-| `--ldap-concurrency`             |                                 | `DM_LDAP_CONCURRENCY`             | `10`                    | LDAP operations concurrency |
+| CLI                              | Plural                          | Env                               | Default                 | Description                        |
+| -------------------------------- | ------------------------------- | --------------------------------- | ----------------------- | ---------------------------------- |
+| `--james-webadmin-url`           |                                 | `DM_JAMES_WEBADMIN_URL`           | `http://localhost:8000` | James WebAdmin API URL             |
+| `--james-webadmin-token`         |                                 | `DM_JAMES_WEBADMIN_TOKEN`         |                         | James authentication token         |
+| `--james-signature-template`     |                                 | `DM_JAMES_SIGNATURE_TEMPLATE`     |                         | Email signature template           |
+| `--james-concurrency`            |                                 | `DM_JAMES_CONCURRENCY`            | `10`                    | James API concurrency              |
+| `--james-init-delay`             |                                 | `DM_JAMES_INIT_DELAY`             | `1000`                  | Init delay (ms)                    |
+| `--james-retry-attempts`         |                                 | `DM_JAMES_RETRY_ATTEMPTS`         | `5`                     | Attempts per user call             |
+| `--james-retry-delay`            |                                 | `DM_JAMES_RETRY_DELAY`            | `1000`                  | Base retry delay (ms)              |
+| `--james-mailing-list-branch`    | `--james-mailing-list-branches` | `DM_JAMES_MAILING_LIST_BRANCHES`  | `[]`                    | Branches refused to team mailboxes |
+| `--james-mailbox-type-attribute` |                                 | `DM_JAMES_MAILBOX_TYPE_ATTRIBUTE` | `twakeMailboxType`      | Mailbox type attribute             |
+| `--ldap-concurrency`             |                                 | `DM_LDAP_CONCURRENCY`             | `10`                    | LDAP operations concurrency        |
+
+The wait before each retry grows with the attempt, so the total wait is `--james-retry-delay` × n(n−1)/2 for n attempts: 10 s with the defaults, 190 s with 20 attempts.
 
 #### `core/twake/calendar`
 

package/docs/usage/plugins/integrations/james-mail.md

@@ -40,60 +40,29 @@ DM_JAMES_WEBADMIN_TOKEN="your-admin-token"
 - `--quota-attribute`: LDAP attribute for quota (default: `mailQuotaSize`)
 - `--alias-attribute`: LDAP attribute for email aliases (default: `mailAlternateAddress`)
 - `--james-mailbox-type-attribute`: LDAP attribute for mailbox type (default: `twakeMailboxType`)
+- `--james-retry-attempts`: attempts in all of a call about a user James may not see yet (default: `5`), see [Replication lag](#replication-lag)
+- `--james-retry-delay`: base delay between those attempts, in ms (default: `1000`); the total wait is delay × n(n−1)/2 for n attempts
 
 ## How It Works
 
 ### Mailing Lists
 
-When a group with a `mail` attribute is created or modified:
+Mailing lists are not synchronized: Twake Mail reads them from LDAP, see
+[Mailing lists](james-mailboxes.md#mailing-lists). Groups whose
+`twakeMailboxType` is `teamMailbox` become James team mailboxes, see
+[James Team Mailboxes](james-mailboxes.md).
 
-1. **Create mailing list**
+### Groups
 
-   ```bash
-   POST /api/v1/ldap/groups
-   {
-     "cn": "engineering",
-     "mail": "engineering@company.com",
-     "member": [
-       "uid=alice,ou=users,dc=example,dc=com",
-       "uid=bob,ou=users,dc=example,dc=com"
-     ]
-   }
-   ```
-
-2. **James plugin** creates address group and adds all members:
-
-   ```http
-   PUT /address/groups/engineering@company.com/alice@company.com
-   PUT /address/groups/engineering@company.com/bob@company.com
-   ```
+James has accounts for users only. An entry whose classes include
+`groupOfNames`, `groupOfUniqueNames` or `groupOfURLs` is a group: the plugin
+creates no identity, quota, alias, forward or delegation for its address, and
+does not rename it in James when its `mail` changes. Its address is a mailing
+list or a team mailbox, as above.
 
-3. **Add/remove members** - when group members change:
-
-   ```bash
-   POST /api/v1/ldap/groups/engineering/members
-   {"member": "uid=charlie,ou=users,dc=example,dc=com"}
-   ```
-
-   James plugin automatically syncs:
-
-   ```http
-   PUT /address/groups/engineering@company.com/charlie@company.com
-   ```
-
-4. **Delete mailing list** - when group is deleted:
-
-   ```http
-   DELETE /address/groups/engineering@company.com
-   ```
-
-**Notes:**
-
-- Only groups with a `mail` attribute are synchronized to James
-- Groups without `mail` are ignored (regular LDAP groups)
-- James Address Groups are simple distribution lists
-- All group members receive emails sent to the group address
-- List type attributes (open/restricted) are stored in LDAP but not enforced by James
+A deployment whose groups (`--group-class`) carry none of these classes has
+its groups handled as users. So is an entry whose classes cannot be read when
+the change is followed.
 
 ### Mail Address Changes
 
@@ -573,18 +542,15 @@ const type = await james.getGroupMailboxType(
 
 ### Endpoints Used
 
-| Operation           | Endpoint                                   | Method |
-| ------------------- | ------------------------------------------ | ------ |
-| Rename account      | `/users/{old}/rename/{new}?action=rename`  | POST   |
-| Update quota        | `/quota/users/{mail}/size`                 | PUT    |
-| Get quota           | `/quota/users/{mail}`                      | GET    |
-| Add delegation      | `/users/{mail}/authorizedUsers/{delegate}` | PUT    |
-| Remove delegation   | `/users/{mail}/authorizedUsers/{delegate}` | DELETE |
-| Add alias           | `/address/aliases/{mail}/sources/{alias}`  | PUT    |
-| Remove alias        | `/address/aliases/{mail}/sources/{alias}`  | DELETE |
-| Add group member    | `/address/groups/{group}/{member}`         | PUT    |
-| Remove group member | `/address/groups/{group}/{member}`         | DELETE |
-| Delete group        | `/address/groups/{group}`                  | DELETE |
+| Operation         | Endpoint                                   | Method |
+| ----------------- | ------------------------------------------ | ------ |
+| Rename account    | `/users/{old}/rename/{new}?action=rename`  | POST   |
+| Update quota      | `/quota/users/{mail}/size`                 | PUT    |
+| Get quota         | `/quota/users/{mail}`                      | GET    |
+| Add delegation    | `/users/{mail}/authorizedUsers/{delegate}` | PUT    |
+| Remove delegation | `/users/{mail}/authorizedUsers/{delegate}` | DELETE |
+| Add alias         | `/address/aliases/{mail}/sources/{alias}`  | PUT    |
+| Remove alias      | `/address/aliases/{mail}/sources/{alias}`  | DELETE |
 
 ### Authentication
 
@@ -707,6 +673,32 @@ The plugin logs all operations:
 
 ## Error Handling
 
+### Replication lag
+
+James reads its users from LDAP, and may read them from a replica that has
+not received the latest write yet: for up to a few seconds after a user is
+created or renamed, James does not know the new address. A call about that
+address fails meanwhile, with 400 (rename) or 404 (quota, alias, identity).
+
+The calls that need James to know the user are therefore retried on 400 and
+404: the rename, the quota, an alias or a forward added, a delegation added,
+and the identity. Each failed attempt logs a warning
+(`"result": "retry"`, with the attempt number); the error is logged when the
+last attempt fails. With the defaults, 5 attempts, the waits are 1, 2, 3 and
+4 seconds: `--james-retry-delay` times the number of attempts made, so
+`--james-retry-delay` × n(n−1)/2 in all for n attempts: 10 seconds with the
+defaults, 190 seconds with 20 attempts. `--james-retry-attempts 1` disables
+the retries. Other
+failures, such as 401 or 500, are not retried, nor are deletions.
+
+The team mailbox calls are not retried: their member routes do not check
+the user in James's users repository; their only 404 is a missing team
+mailbox, which is avoided by creating it before adding the members.
+
+The retries run in the background, after the LDAP write has answered; a
+call waiting for its next attempt does not take a slot of
+`--james-concurrency`.
+
 ### Non-Existent User
 
 If mail account doesn't exist in James:
@@ -816,68 +808,12 @@ Quota values are in **bytes**:
 3. If user is over new quota, James may block incoming mail
 4. User must delete mail to get under quota
 
-## Mailing List Examples
-
-### Creating a Mailing List
-
-```bash
-# Create a group with mail attribute
-curl -X POST http://localhost:8081/api/v1/ldap/groups \
-  -H "Authorization: Bearer admin-token" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "cn": "engineering",
-    "mail": "engineering@company.com",
-    "member": [
-      "uid=alice,ou=users,dc=example,dc=com",
-      "uid=bob,ou=users,dc=example,dc=com"
-    ],
-    "twakeDepartmentLink": "ou=organization,dc=example,dc=com",
-    "twakeDepartmentPath": "Engineering"
-  }'
-```
-
-The James plugin automatically creates the mailing list and adds all members.
-
-### Adding a Member
-
-```bash
-# Add member to existing group
-curl -X POST http://localhost:8081/api/v1/ldap/groups/engineering/members \
-  -H "Authorization: Bearer admin-token" \
-  -H "Content-Type: application/json" \
-  -d '{"member": "uid=charlie,ou=users,dc=example,dc=com"}'
-```
-
-James is automatically updated to include charlie@company.com in the distribution list.
-
-### Removing a Member
-
-```bash
-# Remove member from group
-curl -X DELETE http://localhost:8081/api/v1/ldap/groups/engineering/members/uid=alice,ou=users,dc=example,dc=com \
-  -H "Authorization: Bearer admin-token"
-```
-
-James removes alice@company.com from the mailing list.
-
-### Deleting a Mailing List
-
-```bash
-# Delete the entire group
-curl -X DELETE http://localhost:8081/api/v1/ldap/groups/engineering \
-  -H "Authorization: Bearer admin-token"
-```
-
-James deletes the entire address group.
-
 ## Limitations
 
 1. **One-way sync**: LDAP → James only. James changes don't sync back to LDAP.
 2. **No account creation**: Plugin doesn't create James accounts, only updates existing ones.
-3. **No user deletion**: Plugin doesn't delete James accounts when LDAP users are deleted.
+3. **No user deletion**: deleting an LDAP user leaves its James data (mailboxes, quota, aliases) as it is; purging it is left to James.
 4. **Synchronous**: James API calls block LDAP response. Slow James = slow LDAP.
-5. **No send restrictions**: James doesn't enforce list type restrictions (open/member/owner-only). These are metadata in LDAP only.
 
 ## Advanced Configuration