soajs.controller 4.3.17 → 4.3.19

package/.github/workflows/ci.yml

@@ -17,7 +17,10 @@ jobs:
 
     services:
       mongodb:
-        image: mongo:8
+        # TODO: back to mongo:8 once it starts on the GitHub runners again. Since 2026-10-19 mongod 8
+        #       exits on start with "Linux kernel versions 6.19 and newer has a known incompatibility
+        #       with this version of MongoDB" (https://jira.mongodb.org/browse/SERVER-121912).
+        image: mongo:7.0
         ports:
           - 27017:27017
 

package/.github/workflows/release.yml

@@ -17,7 +17,10 @@ jobs:
 
     services:
       mongodb:
-        image: mongo:8
+        # TODO: back to mongo:8 once it starts on the GitHub runners again. Since 2026-10-19 mongod 8
+        #       exits on start with "Linux kernel versions 6.19 and newer has a known incompatibility
+        #       with this version of MongoDB" (https://jira.mongodb.org/browse/SERVER-121912).
+        image: mongo:7.0
         ports:
           - 27017:27017
 

package/ARCHITECTURE.md

@@ -156,6 +156,7 @@ The gateway processes requests through a sequential middleware pipeline:
 | [External Integrations](docs/external-integrations.md) | OAuth, URAC, and infrastructure integrations |
 | [Deployment Architecture](docs/deployment.md) | High availability deployment patterns |
 | [Custom Registry Configuration](docs/configuration-custom-registry.md) | Environment-specific gateway settings |
+| [Tenant Access Resolver Guide](docs/tenant-access-resolver.md) | Step by step: give a group of users access to a tenant through an API of your app |
 | [Services Config](docs/configuration-services-config.md) | Tenant key-specific configuration |
 | [Gateway Routes](docs/gateway-routes.md) | Built-in gateway routes (/soajs/acl, /soajs/proxy) |
 | [Maintenance Routes](docs/maintenance-routes.md) | Health check and admin endpoints |

package/docs/configuration-custom-registry.md

@@ -4,7 +4,7 @@ Environment-specific gateway settings stored in the Core DB custom registry.
 
 ## Configuration Structure Overview
 
-These settings are accessed via `registry.custom.gateway.value.*` and `registry.custom.oauth.value.*`.
+These settings are accessed via `registry.custom.gateway.value.*`, `registry.custom.oauth.value.*` and `registry.custom.urac.value.*`.
 
 ```
 registry.custom
@@ -35,11 +35,15 @@ registry.custom
 │       └── gotoService
 │           ├── monitor             # Request monitoring config
 │           └── renewReqMonitorOff  # Disable timeout renewal
-└── oauth
+├── oauth
+│   └── value
+│       ├── roaming                 # Cross-environment access
+│       ├── pinWrapper              # PIN-based login endpoint
+│       └── pinWhitelist            # PIN login API whitelist
+└── urac
     └── value
-        ├── roaming                 # Cross-environment access
-        ├── pinWrapper              # PIN-based login endpoint
-        └── pinWhitelist            # PIN login API whitelist
+        └── tenantAccessResolvers   # APIs that grant access to a tenant
+            └── [resolver]          # One API per resolver name
 ```
 
 ---
@@ -577,6 +581,185 @@ loaded from urac per request and the membership is current.
 
 ---
 
+## 15. Tenant Access Resolver
+
+**Path:** `registry.custom.urac.value.tenantAccessResolvers`
+
+**Middleware:** `mw/mt/urac.js`, called by `mw/mt/tenantAccess.js`
+
+Gives a group of users access to a tenant without inviting each of them, for example
+every user of a department of an app. The tenant names a resolver, and the resolver is
+an API of that app that answers, per user, whether they have access and with what
+groups. Nothing is written on the users, `allowedTenants` stays untouched.
+
+Users always log in at their home tenant and then switch, by calling the gateway with
+their token and the key of the other tenant. The resolver is asked on those calls.
+
+Setting it up takes three steps:
+
+1. Build the API in a service of the app, see [The API to build](#the-api-to-build)
+2. Add the resolver to the `urac` custom registry, see [The resolver](#the-resolver)
+3. Name the resolver in the profile of each tenant, see [The tenant](#the-tenant)
+
+### The API to build
+
+Any route of a service in the registry. The gateway calls it directly, not through the
+gateway, so it does not need to be granted in any package. Keep it out of every ACL,
+its answer is trusted as is.
+
+It receives:
+
+```javascript
+// Body
+{
+  "user": {
+    "id": "5c8d0c505653de3985aa1001",
+    "username": "ann",
+    "tenant": { "id": "...", "code": "HOME" }   // Home tenant of the user
+  },
+  "tenant": {
+    "id": "...",
+    "code": "DEPT",
+    "main": { "id": "...", "code": "MAIN" }     // Only for a sub tenant
+  },
+  "subject": "dept_1"                           // From the tenant profile
+}
+```
+
+The `soajsinjectobj` header carries the tenant, the key with `commonFields` and the
+config of the resolver service, and the application of the request, so a service with
+`extKeyRequired` accepts the call. It carries no user and no ACL.
+
+It answers with a standard SOAJS response:
+
+```javascript
+// Access
+{
+  "result": true,
+  "data": {
+    "access": true,
+    "groups": ["member"],
+    "groupsConfig": {
+      "allowedPackages": { "PROD": ["PROD_USER"] }
+    }
+  }
+}
+
+// No access
+{ "result": true, "data": { "access": false } }
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `access` | yes | `true` to grant access |
+| `groupsConfig.allowedPackages` | yes, with access | Packages per product, the shape urac builds from the user's groups |
+| `groups` | no | Group codes services see on the urac object, `[]` when absent |
+
+The answer is the ACL. Nothing caps it, a package the API returns is granted. Only the
+entry of the product of the key is used.
+
+It runs on every call under the tenant, keep it fast.
+
+### The resolver
+
+```javascript
+{
+  "name": "urac",
+  "value": {
+    "tenantAccessResolvers": {
+      "department": {
+        "service": "departments",
+        "version": "1",
+        "method": "post",
+        "api": "/tenant/access",
+        "timeout": 2000
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `service` | string | - | Service that answers, must be in the registry |
+| `version` | string | latest | Version of the service |
+| `method` | string | `post` | HTTP method |
+| `api` | string | - | Route on the service, without the service name |
+| `timeout` | number | `2000` | Milliseconds before the call counts as no access |
+
+The tenant names the resolver and the registry defines the call, so the API can move
+without touching any tenant. A tenant naming a resolver that is not defined here is
+logged as an error and treated as having none.
+
+### The tenant
+
+The tenant profile names the resolver and the subject the API should check, here the
+department:
+
+```javascript
+{
+  "profile": {
+    "access": {
+      "resolver": "department",   // A key of tenantAccessResolvers
+      "subject": "dept_1"         // Passed to the API as is
+    }
+  }
+}
+```
+
+The profile is loaded with the key, so a change applies once the key cache refreshes.
+`PUT /tenant/profile` of multitenant replaces the whole profile, whatever edits it must
+keep `access`.
+
+### When it is asked
+
+For every call made with a token under a tenant that is not the user's home tenant, in
+this order:
+
+| Order | Condition | Result |
+|-------|-----------|--------|
+| 1 | The token's `config.allowedTenants` lists the tenant | Invited, urac driver as before, the resolver is not asked |
+| 2 | The tenant profile names a resolver | The resolver is asked |
+| 3 | The resolver says no, fails or times out, or there is no resolver | urac driver as before |
+
+It is never asked for the user's home tenant, for a token issued for this tenant, for
+roaming, or for `loginMode: "oauth"` tokens.
+
+On access the gateway takes the user from the token, sets its tenant to the tenant of
+the key, its `groups` and `groupsConfig` to the answer, and builds the ACL as for any
+user. The packages come from the provision cache, so urac is not read at all.
+
+The fallback catches an invitation made after the token was issued, the token does not
+show it yet. Everyone else gets what they got before, error 146.
+
+### When access is refused
+
+Anything but a well formed access answer is no access, and the urac driver decides:
+
+| | |
+|---|---|
+| the service is not in the registry, or has no host | logged as an error |
+| non 2xx status, `result: false`, or not JSON | logged as an error |
+| no answer within `timeout` | logged as an error |
+| `access: true` without `groupsConfig.allowedPackages` | logged as an error |
+| `access` is not `true` | not logged, a normal answer |
+
+### Behaviour
+
+- **Cost.** One API call per call under the tenant, in place of the user and groups
+  reads of urac. Invited users cost what they did before.
+- **Freshness.** Nothing is cached, adding or removing a user in the app applies on
+  their next call.
+- **Outage.** While the service is down, users of the resolver get 146 under that
+  tenant, each call after waiting up to `timeout`, keep it short. Their home tenant and
+  invited users are not affected, except users invited after their token was issued,
+  who also wait for the timeout before the fallback lets them in.
+- **Invitations win.** A user both invited and covered by the resolver gets the groups
+  of the invitation. If the invitation was made after the token was issued, they get
+  the resolver's until their next login.
+
+---
+
 ## Complete Configuration Example
 
 ```javascript
@@ -681,6 +864,22 @@ loaded from urac per request and the membership is current.
     }
   }
 }
+
+// Separate URAC custom registry entry
+{
+  "_id": ObjectId("..."),
+  "name": "urac",
+  "value": {
+    "tenantAccessResolvers": {
+      "department": {
+        "service": "departments",
+        "version": "1",
+        "api": "/tenant/access",
+        "timeout": 2000
+      }
+    }
+  }
+}
 ```
 
 ---
@@ -698,7 +897,8 @@ Custom registry configurations are processed in this order:
 | 5 | gotoService/redirectToService | `gotoService.monitor` |
 | 6 | mt (security checks) | `mt.whitelist`, `oauth.value.pinWrapper`, `oauth.value.pinWhitelist` |
 | 6a | oauth (called from mt) | `oauth.deviceIdCheck` |
-| 6b | mt (inject object) | `membership` |
+| 6b | mt (uracCheck) | `urac.value.tenantAccessResolvers` |
+| 6c | mt (inject object) | `membership` |
 | 7 | idempotency | `idempotency.model`, `idempotency.services.[name]` |
 | 8 | traffic | `traffic.model`, `traffic.throttling` |
 | 9 | cache | `cache.model`, `cache.defaultTTL`, `cache.services.[name]` |

package/docs/middleware/idempotency.md

@@ -48,7 +48,8 @@ The Idempotency middleware prevents duplicate write operations by tracking reque
            │
            ├─── Found (in_flight) ──▶ 409 Conflict (code: 181)
            │
-           └─── Not found ──▶ Lock key → Execute → Store response
+           └─── Not found ──▶ Lock key → Execute → Store response (status < 500)
+                                                 or release the key
 ```
 
 ## Configuration
@@ -140,12 +141,39 @@ Content-Type: application/json
 {"caller": "user1", "callee": "user2"}
 ```
 
+## How a Locked Key Ends
+
+The key is locked before the request goes on to throttling, caching and the proxy. How the
+request ends decides what happens to it:
+
+| The request ends with | The key | A retry with the same key |
+|---|---|---|
+| An answer of the service below 500 (2xx, 3xx, 4xx) | Completed, the answer is stored for the TTL | Gets the stored answer, the service is not called |
+| An answer of the service of 500 or more | Released | Reaches the service again |
+| A proxy error (service down, connection closed) | Released | Reaches the service again |
+| An answer of the gateway before the service: throttling (429), an error, a refusal | Released | Runs again |
+| The client disconnecting before the request reaches the service | Released | Runs again |
+| The client disconnecting while the service is answering | Follows the service answer above | |
+
+Only an answer the service actually produced is replayed. A 4xx is the service's answer to that
+request and replaying it is correct. A 5xx, a throttling refusal or any other answer of the gateway
+says nothing about the operation, so the key is released and the client's retry runs instead of
+getting the same refusal for the whole TTL.
+
+While the request is running, a duplicate with the same key gets 409, code 181.
+
+A service that can fail with a 5xx after part of the work is done must protect that work itself,
+the retry reaches it again.
+
+The release only removes a key still in flight and locked by that request: never a completed
+one, and never a lock taken by a retry after the TTL of the first ran out.
+
 ## Response Scenarios
 
 ### New Request (First Time)
 
 ```
-Request processed normally, response cached
+Request processed normally, a service answer below 500 is stored
 ```
 
 ### Replay (Completed)
@@ -235,6 +263,7 @@ Keys are isolated per tenant to prevent cross-tenant collisions.
 - Only applies to non-GET requests (POST, PUT, DELETE, PATCH)
 - GET requests always pass through (idempotent by nature)
 - Keys expire after TTL (default 60 seconds)
+- A key is never left in flight by a request that does not reach the service, see [How a Locked Key Ends](#how-a-locked-key-ends)
 - Clients should generate a new UUID for each unique operation
 - Same UUID = same operation (for retries)
 - MongoDB backend required for horizontal scaling

package/docs/middleware/mt.md

@@ -285,6 +285,23 @@ PIN login is a two-factor authentication mechanism where users must enter a PIN
 - Skipped if `obj.skipOAUTH = true` or no bearer token present
 - Creates `req.soajs.uracDriver` instance
 - Handles **roaming** across environments (e.g., dashboard token used in dev environment)
+- Asks the **tenant access resolver** when a user switches to a tenant whose profile names one
+
+**Tenant Access Resolver:**
+
+A tenant can name a resolver in its profile (`profile.access`), an API of an app that answers per
+user whether they have access to the tenant and with what groups, so a group of users, a department
+for example, gets access without being invited one by one.
+
+For a call under a tenant that is not the user's home tenant, and that the token's
+`config.allowedTenants` does not list, `mw/mt/urac.js` calls the API defined in
+`registry.custom.urac.value.tenantAccessResolvers` (`mw/mt/tenantAccess.js`). On access the user
+comes from the token with that tenant and the groups of the answer, and urac is not read. No
+access, an error or a timeout falls back to the urac driver as before.
+
+See [Custom Registry, Tenant Access Resolver](../configuration-custom-registry.md#15-tenant-access-resolver)
+for the API to build, the registry entry and the tenant profile.
+To add one step by step, see the [Tenant Access Resolver Guide](../tenant-access-resolver.md).
 
 **Roaming Support:**
 
@@ -560,6 +577,7 @@ Service-level configuration that affects MT processing:
 
 - `mw/mt/utils.js` - Security check implementations
 - `mw/mt/urac.js` - URAC driver integration
+- `mw/mt/tenantAccess.js` - Tenant access resolver call
 
 ## Usage Notes
 

package/docs/multi-tenant-security.md

@@ -111,6 +111,7 @@ Loads user profile from URAC for authenticated requests.
 - Resolves user groups
 - Applies user-specific ACL overrides
 - Handles network package override for user packages
+- Asks the tenant access resolver for a user switching to a tenant that names one, see [Custom Registry](configuration-custom-registry.md#15-tenant-access-resolver)
 
 ## IP Whitelist Configuration
 

package/docs/tenant-access-resolver.md

@@ -0,0 +1,81 @@
+# Adding a Tenant Access Resolver
+
+A step by step guide to give a group of users, a department of your app for example, access
+to a tenant without inviting them one by one.
+
+Every detail lives in [Custom Registry, Tenant Access Resolver](configuration-custom-registry.md#15-tenant-access-resolver),
+this guide only walks through it in order.
+
+## Before you start
+
+- Users log in at their home tenant and switch inside the app, the resolver is asked on the
+  calls they make under the other tenant. See [When it is asked](configuration-custom-registry.md#when-it-is-asked).
+- Your app is the source of truth for who belongs to what, and its answer becomes the ACL of
+  the user under that tenant.
+
+## Step 1: Build the API
+
+In a service of your app that is in the registry, add a route that tells the gateway if a user
+has access to a tenant and with what groups.
+
+1. Read the body the gateway sends, `user`, `tenant` and `subject`.
+2. Look up whether `user` belongs to `subject` in your app.
+3. Answer with `access` and, when granted, `groups` and `groupsConfig.allowedPackages` for the
+   product of the tenant.
+
+The request and the response are in [The API to build](configuration-custom-registry.md#the-api-to-build).
+
+Keep in mind:
+
+- Keep the route out of every package ACL, the gateway calls the service directly.
+- It runs on every call the user makes under the tenant, keep it fast.
+- Anything but a well formed yes is no access, see [When access is refused](configuration-custom-registry.md#when-access-is-refused).
+
+## Step 2: Add the resolver to the custom registry
+
+In the environment's custom registry, add or edit the entry named `urac` and add your resolver
+under `tenantAccessResolvers`, giving it a name, the service, the route and a short timeout.
+
+The fields are in [The resolver](configuration-custom-registry.md#the-resolver).
+
+The name you give it is what tenants refer to, keep it stable. The service, route or timeout can
+change later without touching any tenant.
+
+## Step 3: Point the tenant at the resolver
+
+On each tenant the group should reach, set `profile.access` with the resolver name from step 2
+and the `subject` your API checks, the department id for example.
+
+See [The tenant](configuration-custom-registry.md#the-tenant).
+
+Whatever edits tenant profiles must keep `access`, `PUT /tenant/profile` replaces the whole
+profile.
+
+## Step 4: Check it
+
+With a user of the group, logged in at their home tenant:
+
+1. Call an API of the tenant with their token and the tenant's key. It should succeed with the
+   packages your API returned.
+2. Call it with a user outside the group. It should fail with error 146, as before.
+3. Call it with a user invited to the tenant. Your API is not called, the invitation decides.
+
+If a user of the group gets 146, look for `Tenant access resolver` in the gateway logs, every
+failed call is logged with the resolver, the user and the tenant.
+
+Changes in your app apply on the next call. Changes to the tenant profile apply once the key
+cache refreshes.
+
+## Before going live
+
+Read [Behaviour](configuration-custom-registry.md#behaviour): what each call costs, what users
+see while your service is down, and how invitations and the resolver combine.
+
+## Reference
+
+| Topic | Where |
+|-------|-------|
+| Full reference | [Custom Registry, Tenant Access Resolver](configuration-custom-registry.md#15-tenant-access-resolver) |
+| Where it runs in the pipeline | [MT middleware, uracCheck](middleware/mt.md#6-uraccheck) |
+| Code | `mw/mt/urac.js`, `mw/mt/tenantAccess.js` |
+| Example test | `test/integration/UC5-tenant-access/index.js`, a mock resolver |

package/mw/gotoService/redirectToService.js

@@ -11,6 +11,7 @@
 const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
 
 const { httpRequestLight, proxyRequestMonitor } = require("../../lib/request.js");
+const idempotency_mw = require("../idempotency/index.js");
 
 // Monitor buffer for batch uploads
 let monitorBuffer = [];
@@ -395,6 +396,11 @@ module.exports = (configuration) => {
 				};
 			}
 
+			//NOTE: from here the outcome of the service decides the key, the release on finish in the
+			//		idempotency middleware stands down
+			if (idempotencyContext) {
+				idempotencyContext.proxied = true;
+			}
 			proxyRequestMonitor(req, res, requestOptions, extraOptions)
 				.then(() => {
 					// Save to cache if applicable
@@ -408,14 +414,20 @@ module.exports = (configuration) => {
 						cacheContext.model.set(cacheContext.key, cacheData, cacheContext.ttl);
 					}
 					// Complete idempotency if applicable
+					//NOTE: only an answer of the service is replayed, a 5xx means it could not answer, release
+					//		the key so the retry reaches the service again
 					if (idempotencyContext) {
-						let idempotencyBody = Buffer.concat(idempotencyResponseChunks).toString('utf8');
-						let idempotencyData = {
-							statusCode: idempotencyResponseStatusCode,
-							headers: idempotencyResponseHeaders,
-							body: idempotencyBody
-						};
-						idempotencyContext.model.complete(idempotencyContext.key, idempotencyData, idempotencyContext.ttl);
+						if (idempotencyResponseStatusCode < 500) {
+							let idempotencyBody = Buffer.concat(idempotencyResponseChunks).toString('utf8');
+							let idempotencyData = {
+								statusCode: idempotencyResponseStatusCode,
+								headers: idempotencyResponseHeaders,
+								body: idempotencyBody
+							};
+							idempotencyContext.model.complete(idempotencyContext.key, idempotencyData, idempotencyContext.ttl);
+						} else {
+							idempotency_mw.unlock(idempotencyContext.model, idempotencyContext.key, idempotencyContext.lockId, req.soajs.log);
+						}
 					}
 					if (monitor && !monitor_service_blacklist && monitor.req_response) {
 						monitoObj.time.res_end = new Date().getTime();
@@ -430,7 +442,7 @@ module.exports = (configuration) => {
 					}
 					// Unlock idempotency on error
 					if (idempotencyContext) {
-						idempotencyContext.model.unlock(idempotencyContext.key);
+						idempotency_mw.unlock(idempotencyContext.model, idempotencyContext.key, idempotencyContext.lockId, req.soajs.log);
 					}
 					if (!req.soajs.controller.monitorEndingReq) {
 						req.soajs.controllerResponse(core.error.getError(135));

package/mw/idempotency/index.js

@@ -8,6 +8,7 @@
  * found in the LICENSE file at the root of this repository
  */
 
+const crypto = require('crypto');
 const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
 const memory = require('./model/memory.js');
 const mongo = require('./model/mongo.js');
@@ -56,6 +57,21 @@ function matchesApi(method, path, apis) {
 	return false;
 }
 
+/**
+ * Release a key this request locked, only while it is still in flight and still ours
+ * @param modelObj memory or mongo
+ * @param key
+ * @param lockId
+ * @param log
+ */
+function unlock(modelObj, key, lockId, log) {
+	Promise.resolve()
+		.then(() => modelObj.unlock(key, lockId))
+		.catch((err) => {
+			log.error('Idempotency unlock:', err.message);
+		});
+}
+
 module.exports = function (configuration) {
 	model.memory.init(configuration.log);
 	model.mongo.init(configuration.log, configuration.gatewayDB);
@@ -131,6 +147,7 @@ module.exports = function (configuration) {
 			'l2': idempotencyKey
 		};
 
+		let lockId = null;
 		const processIdempotency = async () => {
 			try {
 				const existing = await model[modelType].get(key);
@@ -152,7 +169,8 @@ module.exports = function (configuration) {
 					}
 				}
 
-				const locked = await model[modelType].lock(key, ttl);
+				lockId = crypto.randomUUID();
+				const locked = await model[modelType].lock(key, ttl, lockId);
 				if (!locked) {
 					req.soajs.controllerResponse({
 						'status': 409,
@@ -163,18 +181,37 @@ module.exports = function (configuration) {
 				}
 
 				// Store idempotency context for gotoService to use
-				req.soajs.idempotencyContext = {
+				const context = {
 					key: key,
 					ttl: ttl,
+					lockId: lockId,
 					modelType: modelType,
 					model: model[modelType],
-					log: configuration.log
+					log: configuration.log,
+					proxied: false
 				};
+				req.soajs.idempotencyContext = context;
+
+				//NOTE: a request answered before it reaches the service, throttled, refused or dropped by
+				//		the client, must not keep the key in flight until the ttl, release it once the response
+				//		is over. A proxied request is completed or released by gotoService, never here.
+				let released = false;
+				const release = () => {
+					if (released || context.proxied) {
+						return;
+					}
+					released = true;
+					unlock(model[modelType], key, lockId, configuration.log);
+				};
+				res.on('finish', release);
+				res.on('close', release);
 
 				next();
 			} catch (err) {
 				configuration.log.error('Idempotency error:', err);
-				model[modelType].unlock(key).catch(() => {});
+				if (lockId) {
+					unlock(model[modelType], key, lockId, configuration.log);
+				}
 				next();
 			}
 		};
@@ -185,3 +222,4 @@ module.exports = function (configuration) {
 
 // Export model for external use
 module.exports.model = model;
+module.exports.unlock = unlock;

package/mw/idempotency/model/memory.js

@@ -75,7 +75,7 @@ let model = {
 		return entry;
 	},
 
-	'lock': (key, ttl) => {
+	'lock': (key, ttl, lockId) => {
 		if (!dataHolder[key.l1]) {
 			dataHolder[key.l1] = {};
 		}
@@ -85,6 +85,7 @@ let model = {
 		}
 		dataHolder[key.l1][key.l2] = {
 			'status': 'in_flight',
+			'lockId': lockId || null,
 			'lockedAt': Date.now(),
 			'expiresAt': Date.now() + ttl
 		};
@@ -103,8 +104,17 @@ let model = {
 		};
 	},
 
-	'unlock': (key) => {
+	//NOTE: only an entry still in flight is removed, never a completed one, and with a lockId only
+	//		the lock of that request, not one taken by a retry after the ttl
+	'unlock': (key, lockId) => {
 		if (dataHolder[key.l1] && dataHolder[key.l1][key.l2]) {
+			const entry = dataHolder[key.l1][key.l2];
+			if (entry.status !== 'in_flight') {
+				return;
+			}
+			if (lockId && entry.lockId !== lockId) {
+				return;
+			}
 			delete dataHolder[key.l1][key.l2];
 		}
 	},