velocious 1.0.725 → 1.0.727

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/README.md +1 -1
  2. package/build/background-jobs/adapter.js +16 -0
  3. package/build/background-jobs/job-record.js +3 -1
  4. package/build/background-jobs/main.js +62 -2
  5. package/build/background-jobs/owner-liveness.js +27 -5
  6. package/build/background-jobs/store.js +74 -0
  7. package/build/background-jobs/types.js +3 -0
  8. package/build/configuration-types.js +1 -1
  9. package/build/configuration.js +53 -3
  10. package/build/database/advisory-lock-lock-server-backend.js +30 -24
  11. package/build/database/advisory-lock-lock-server-embedded-client.js +74 -0
  12. package/build/database/advisory-lock-lock-server-engine.js +544 -0
  13. package/build/database/advisory-lock-lock-server-local-client.js +260 -0
  14. package/build/database/advisory-lock-lock-server-socket-path.js +17 -0
  15. package/build/database/advisory-lock-lock-server-transport.js +30 -0
  16. package/build/database/record/auditing.js +89 -11
  17. package/build/database/record/index.js +1 -1
  18. package/build/environment-handlers/base.js +50 -9
  19. package/build/environment-handlers/node/advisory-lock-lock-server-local-server.js +206 -0
  20. package/build/environment-handlers/node.js +30 -3
  21. package/build/http-server/server-lock.js +29 -16
  22. package/build/src/background-jobs/adapter.d.ts +23 -0
  23. package/build/src/background-jobs/adapter.d.ts.map +1 -1
  24. package/build/src/background-jobs/adapter.js +15 -1
  25. package/build/src/background-jobs/job-record.d.ts +3 -1
  26. package/build/src/background-jobs/job-record.d.ts.map +1 -1
  27. package/build/src/background-jobs/job-record.js +4 -2
  28. package/build/src/background-jobs/main.d.ts +33 -0
  29. package/build/src/background-jobs/main.d.ts.map +1 -1
  30. package/build/src/background-jobs/main.js +59 -3
  31. package/build/src/background-jobs/owner-liveness.d.ts +25 -3
  32. package/build/src/background-jobs/owner-liveness.d.ts.map +1 -1
  33. package/build/src/background-jobs/owner-liveness.js +26 -7
  34. package/build/src/background-jobs/store.d.ts +39 -0
  35. package/build/src/background-jobs/store.d.ts.map +1 -1
  36. package/build/src/background-jobs/store.js +66 -1
  37. package/build/src/background-jobs/types.d.ts +6 -0
  38. package/build/src/background-jobs/types.d.ts.map +1 -1
  39. package/build/src/background-jobs/types.js +4 -1
  40. package/build/src/configuration-types.d.ts +3 -1
  41. package/build/src/configuration-types.d.ts.map +1 -1
  42. package/build/src/configuration-types.js +2 -2
  43. package/build/src/configuration.d.ts +25 -1
  44. package/build/src/configuration.d.ts.map +1 -1
  45. package/build/src/configuration.js +47 -4
  46. package/build/src/database/advisory-lock-lock-server-backend.d.ts +10 -3
  47. package/build/src/database/advisory-lock-lock-server-backend.d.ts.map +1 -1
  48. package/build/src/database/advisory-lock-lock-server-backend.js +25 -22
  49. package/build/src/database/advisory-lock-lock-server-embedded-client.d.ts +24 -0
  50. package/build/src/database/advisory-lock-lock-server-embedded-client.d.ts.map +1 -0
  51. package/build/src/database/advisory-lock-lock-server-embedded-client.js +64 -0
  52. package/build/src/database/advisory-lock-lock-server-engine.d.ts +285 -0
  53. package/build/src/database/advisory-lock-lock-server-engine.d.ts.map +1 -0
  54. package/build/src/database/advisory-lock-lock-server-engine.js +460 -0
  55. package/build/src/database/advisory-lock-lock-server-local-client.d.ts +114 -0
  56. package/build/src/database/advisory-lock-lock-server-local-client.d.ts.map +1 -0
  57. package/build/src/database/advisory-lock-lock-server-local-client.js +227 -0
  58. package/build/src/database/advisory-lock-lock-server-socket-path.d.ts +9 -0
  59. package/build/src/database/advisory-lock-lock-server-socket-path.d.ts.map +1 -0
  60. package/build/src/database/advisory-lock-lock-server-socket-path.js +16 -0
  61. package/build/src/database/advisory-lock-lock-server-transport.d.ts +18 -0
  62. package/build/src/database/advisory-lock-lock-server-transport.d.ts.map +1 -0
  63. package/build/src/database/advisory-lock-lock-server-transport.js +27 -0
  64. package/build/src/database/record/auditing.d.ts +14 -4
  65. package/build/src/database/record/auditing.d.ts.map +1 -1
  66. package/build/src/database/record/auditing.js +77 -12
  67. package/build/src/database/record/index.d.ts +4 -2
  68. package/build/src/database/record/index.d.ts.map +1 -1
  69. package/build/src/database/record/index.js +2 -2
  70. package/build/src/environment-handlers/base.d.ts +86 -7
  71. package/build/src/environment-handlers/base.d.ts.map +1 -1
  72. package/build/src/environment-handlers/base.js +48 -9
  73. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.d.ts +2 -0
  74. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.d.ts.map +1 -0
  75. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +179 -0
  76. package/build/src/environment-handlers/node.d.ts +10 -4
  77. package/build/src/environment-handlers/node.d.ts.map +1 -1
  78. package/build/src/environment-handlers/node.js +30 -4
  79. package/build/src/http-server/server-lock.d.ts +22 -11
  80. package/build/src/http-server/server-lock.d.ts.map +1 -1
  81. package/build/src/http-server/server-lock.js +30 -17
  82. package/package.json +1 -1
  83. package/src/background-jobs/adapter.js +16 -0
  84. package/src/background-jobs/job-record.js +3 -1
  85. package/src/background-jobs/main.js +62 -2
  86. package/src/background-jobs/owner-liveness.js +27 -5
  87. package/src/background-jobs/store.js +74 -0
  88. package/src/background-jobs/types.js +3 -0
  89. package/src/configuration-types.js +1 -1
  90. package/src/configuration.js +53 -3
  91. package/src/database/advisory-lock-lock-server-backend.js +30 -24
  92. package/src/database/advisory-lock-lock-server-embedded-client.js +74 -0
  93. package/src/database/advisory-lock-lock-server-engine.js +544 -0
  94. package/src/database/advisory-lock-lock-server-local-client.js +260 -0
  95. package/src/database/advisory-lock-lock-server-socket-path.js +17 -0
  96. package/src/database/advisory-lock-lock-server-transport.js +30 -0
  97. package/src/database/record/auditing.js +89 -11
  98. package/src/database/record/index.js +1 -1
  99. package/src/environment-handlers/base.js +50 -9
  100. package/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +206 -0
  101. package/src/environment-handlers/node.js +30 -3
  102. package/src/http-server/server-lock.js +29 -16
@@ -0,0 +1,544 @@
1
+ // @ts-check
2
+
3
+ /**
4
+ * One engine connection: the transport-side view of a lock client. `send`
5
+ * delivers engine messages (responses and `lost` pushes) back to the client.
6
+ * @typedef {object} LockServerEngineConnection
7
+ * @property {(body: Record<string, unknown>) => void} send - Delivers one engine message to this connection.
8
+ * @property {() => void} [onClose] - Engine-side close hook (transport teardown).
9
+ */
10
+ /**
11
+ * One registered engine connection with its held lock names.
12
+ * @typedef {object} LockServerEngineRegisteredConnection
13
+ * @property {Map<string, number>} held - Lock names this connection holds, mapped to their granted epoch.
14
+ * @property {LockServerEngineConnection} connection - Transport-side connection.
15
+ * @property {string} id - Server-minted holder id.
16
+ * @property {boolean} open - False once the connection was closed.
17
+ */
18
+ /**
19
+ * One queued acquire request waiting on the FIFO queue.
20
+ * @typedef {object} LockServerEngineWaiter
21
+ * @property {LockServerEngineRegisteredConnection} connection - Waiting connection.
22
+ * @property {string} correlationId - Request correlation echoed on the response.
23
+ * @property {number} [deadline] - Absolute deadline; absent waits indefinitely.
24
+ * @property {string} name - Lock name.
25
+ * @property {ReturnType<typeof setTimeout> | null} timer - Bounded-wait timeout timer.
26
+ */
27
+ /**
28
+ * One lock name's live state in the engine.
29
+ * @typedef {object} LockServerEngineLockRecord
30
+ * @property {LockServerEngineRegisteredConnection | null} holder - Current lease holder, null when free.
31
+ * @property {number} epoch - Last granted fencing epoch (0 before the first grant).
32
+ * @property {number} leaseExpiresAt - When the current lease expires without renewal.
33
+ * @property {string} name - Lock name.
34
+ * @property {LockServerEngineWaiter[]} waiters - FIFO queue of pending acquires.
35
+ */
36
+ /**
37
+ * One engine request message.
38
+ * @typedef {object} LockServerEngineRequest
39
+ * @property {string} correlationId - Client-generated id echoed on the response.
40
+ * @property {number} [epoch] - Holder epoch for `renew`/`release`.
41
+ * @property {string} name - Lock name.
42
+ * @property {number} [timeoutMs] - Bounded wait for `acquire`.
43
+ */
44
+ /**
45
+ * Registers one engine connection with its server-minted holder id — exactly
46
+ * like the consens-lock daemon mints the holder id from the transport, so a
47
+ * client can only renew or release its own leases.
48
+ * @param {LockServerEngineConnection} connection - Transport-side connection.
49
+ * @param {string} id - Holder id.
50
+ * @returns {LockServerEngineRegisteredConnection} - Registered connection.
51
+ */
52
+ function registeredConnection(connection, id) {
53
+ return {connection, held: new Map(), id, open: true}
54
+ }
55
+
56
+ /**
57
+ * Shared lock-server engine implementing the consens-lock protocol v2 semantics
58
+ * in plain JS with no Node builtins and no sockets (STC-715). It is the single
59
+ * lease/epoch/fencing authority reused by every lock-server mode:
60
+ *
61
+ * - `embedded` mode runs it directly inside the environment process (the
62
+ * in-process transport feeds this same message surface over function calls),
63
+ * so browser/Expo bundles can use the lock-server tier without `ws`.
64
+ * - `local` mode runs it in a spawned child process over stdio JSON-lines
65
+ * (`src/environment-handlers/node/advisory-lock-lock-server-server.js`).
66
+ *
67
+ * Semantics mirror the external daemon (`docs/protocol.md` in
68
+ * `diestoeckels/consens-lock`): server-minted holder ids bound to the
69
+ * connection, leases renewed per third of `leaseMs`, a monotonic fencing epoch
70
+ * per lock name bumped on every grant and on every invalidation, a FIFO waiter
71
+ * queue per name, an expired-lease sweeper, and an asynchronous `lost` push so
72
+ * a fenced holder learns without waiting for its next renew.
73
+ *
74
+ * Grant decisions run synchronously in the engine's single event loop: the
75
+ * check-and-set on the holder map has no `await` between read and write, so
76
+ * two concurrent acquires can never both be granted.
77
+ */
78
+ export default class AdvisoryLockLockServerEngine {
79
+ /**
80
+ * Creates one engine instance. No I/O happens here.
81
+ * @param {object} [args] - Engine options.
82
+ * @param {number} [args.leaseMs] - Lease duration per grant. Defaults to 30000.
83
+ * @param {number} [args.sweepIntervalMs] - Expired-lease sweep interval. Defaults to 200.
84
+ */
85
+ constructor({leaseMs = 30_000, sweepIntervalMs = 200} = {}) {
86
+ this.leaseMs = leaseMs
87
+ this.sweepIntervalMs = sweepIntervalMs
88
+ /** @type {Map<string, LockServerEngineLockRecord>} */
89
+ this.locks = new Map()
90
+ /** @type {Map<string, number>} */
91
+ this.epochByLock = new Map()
92
+ /** @type {Map<string, LockServerEngineRegisteredConnection>} */
93
+ this.connections = new Map()
94
+ this.connectionCounter = 0
95
+ this.closed = false
96
+ /** @type {ReturnType<typeof setInterval> | null} */
97
+ this.sweepTimer = null
98
+ }
99
+
100
+ /**
101
+ * Starts the expired-lease sweeper (idempotent). Long-lived transports call
102
+ * this; the sweeper is the backstop for holders whose transport died without
103
+ * a close event.
104
+ * @returns {void}
105
+ */
106
+ startSweeper() {
107
+ if (this.closed || this.sweepTimer) return
108
+
109
+ const timer = setInterval(() => this.sweep(), this.sweepIntervalMs)
110
+
111
+ timer.unref?.()
112
+ this.sweepTimer = timer
113
+ }
114
+
115
+ /**
116
+ * Registers one connection (the transport opened it) and returns its
117
+ * server-minted holder id.
118
+ * @param {LockServerEngineConnection} connection - Transport-side connection.
119
+ * @returns {string} - Holder id bound to this connection.
120
+ */
121
+ openConnection(connection) {
122
+ if (this.closed) throw new Error("Lock server engine is closed")
123
+
124
+ const id = `engine-holder-${++this.connectionCounter}`
125
+ const registered = registeredConnection(connection, id)
126
+
127
+ this.connections.set(id, registered)
128
+ this.connectionCounter = Math.max(this.connectionCounter, this.connections.size)
129
+
130
+ return id
131
+ }
132
+
133
+ /**
134
+ * Returns the registered connection for one transport connection id,
135
+ * auto-registering the given transport view when the first message arrives
136
+ * before an explicit open (the stdio server has no separate connection-open
137
+ * frame per client).
138
+ * @param {string} connectionId - Transport connection id.
139
+ * @param {LockServerEngineConnection} [transport] - Transport view to register when the id is new.
140
+ * @returns {LockServerEngineRegisteredConnection | null} - Registered connection, or null when the engine is closed.
141
+ */
142
+ ensureConnection(connectionId, transport) {
143
+ if (this.closed) return null
144
+
145
+ const existing = this.connections.get(connectionId)
146
+
147
+ if (existing) return existing
148
+
149
+ const registered = registeredConnection(transport || {send: () => {}}, connectionId)
150
+
151
+ this.connections.set(connectionId, registered)
152
+ this.connectionCounter = Math.max(this.connectionCounter, this.connections.size)
153
+
154
+ return registered
155
+ }
156
+
157
+ /**
158
+ * Handles one request message from a connection and answers it (or queues
159
+ * the wait) through the connection's `send`.
160
+ * @param {string} connectionId - Connection the message arrived on.
161
+ * @param {Record<string, unknown>} body - Request message.
162
+ * @returns {void}
163
+ */
164
+ handleMessage(connectionId, body) {
165
+ const registered = this.ensureConnection(connectionId)
166
+
167
+ if (this.closed || !registered || !registered.open || !body || typeof body !== "object") return
168
+
169
+ // Transport-level frames (the connection-open params carrying auth and
170
+ // protocol version) are answered by the transport's hello-ack, not here;
171
+ // only request/response traffic with a correlationId reaches the engine.
172
+ if (body.type === "hello" || typeof body.correlationId !== "string") return
173
+
174
+ const correlationId = typeof body.correlationId === "string" ? body.correlationId : ""
175
+ const name = typeof body.name === "string" ? body.name : ""
176
+
177
+ switch (body.type) {
178
+ case "acquire":
179
+ this.handleAcquire(registered, {correlationId, name, timeoutMs: typeof body.timeoutMs === "number" ? body.timeoutMs : undefined})
180
+
181
+ return
182
+ case "try-acquire":
183
+ this.handleTryAcquire(registered, {correlationId, name})
184
+
185
+ return
186
+ case "renew":
187
+ this.handleRenew(registered, {correlationId, epoch: typeof body.epoch === "number" ? body.epoch : -1, name})
188
+
189
+ return
190
+ case "release":
191
+ this.handleRelease(registered, {correlationId, epoch: typeof body.epoch === "number" ? body.epoch : undefined, name})
192
+
193
+ return
194
+ case "who-holds":
195
+ this.respond(registered, correlationId, {holder: this.holderInfo(name), type: "response"})
196
+
197
+ return
198
+ case "list":
199
+ this.respond(registered, correlationId, {holders: this.listHolders(), type: "response"})
200
+
201
+ return
202
+ default:
203
+ this.respond(registered, correlationId, {error: `Unknown lock-server request type: ${String(body.type)}`, status: "error", type: "response"})
204
+ }
205
+ }
206
+
207
+ /**
208
+ * Removes a connection and releases every lease it holds immediately — the
209
+ * same transport-close semantics the external daemon has.
210
+ * @param {string} connectionId - Registered connection id.
211
+ * @returns {void}
212
+ */
213
+ connectionClose(connectionId) {
214
+ const registered = this.connections.get(connectionId)
215
+
216
+ if (!registered) return
217
+
218
+ this.connections.delete(connectionId)
219
+ registered.open = false
220
+
221
+ for (const name of [...registered.held.keys()]) {
222
+ const record = this.locks.get(name)
223
+
224
+ if (!record || record.holder !== registered) continue
225
+
226
+ record.holder = null
227
+ registered.held.delete(name)
228
+ this.grantNext(record)
229
+ }
230
+ }
231
+
232
+ /**
233
+ * Stops the sweeper and closes every connection (shutdown path).
234
+ * @returns {void}
235
+ */
236
+ close() {
237
+ this.closed = true
238
+
239
+ if (this.sweepTimer) {
240
+ clearInterval(this.sweepTimer)
241
+ this.sweepTimer = null
242
+ }
243
+
244
+ for (const registered of [...this.connections.values()]) {
245
+ try {
246
+ registered.connection.onClose?.()
247
+ } catch {
248
+ // A failing transport close hook must not block the shutdown of the
249
+ // remaining connections.
250
+ }
251
+
252
+ this.connections.delete(registered.id)
253
+ registered.open = false
254
+ }
255
+ }
256
+
257
+ /**
258
+ * Handles `acquire`: grants immediately, answers `already-held` for a
259
+ * re-entrant acquisition, or joins the name's FIFO waiter queue with a
260
+ * bounded timeout.
261
+ * @param {LockServerEngineRegisteredConnection} registered - Requesting connection.
262
+ * @param {LockServerEngineRequest & {timeoutMs?: number}} request - Request fields.
263
+ * @returns {void}
264
+ */
265
+ handleAcquire(registered, request) {
266
+ const {correlationId, name, timeoutMs} = request
267
+
268
+ if (!name) {
269
+ this.respond(registered, correlationId, {error: "acquire requires a lock name", status: "error", type: "response"})
270
+
271
+ return
272
+ }
273
+
274
+ const record = this.lockRecord(name)
275
+ const heldEpoch = registered.held.get(name)
276
+
277
+ if (record.holder === registered && typeof heldEpoch === "number") {
278
+ this.respond(registered, correlationId, {epoch: heldEpoch, leaseExpiresAt: record.leaseExpiresAt, status: "already-held", type: "response"})
279
+
280
+ return
281
+ }
282
+
283
+ if (!record.holder) {
284
+ this.grant(registered, record, correlationId)
285
+
286
+ return
287
+ }
288
+
289
+ const waiter = /** @type {LockServerEngineWaiter} */ ({connection: registered, correlationId, name})
290
+
291
+ if (typeof timeoutMs === "number" && timeoutMs >= 0) {
292
+ waiter.deadline = Date.now() + timeoutMs
293
+ const timer = setTimeout(() => this.expireWaiter(record, waiter), timeoutMs)
294
+
295
+ timer.unref?.()
296
+ waiter.timer = timer
297
+ }
298
+
299
+ record.waiters.push(waiter)
300
+ }
301
+
302
+ /**
303
+ * Handles `try-acquire`: grants when free, answers `busy` when held.
304
+ * @param {LockServerEngineRegisteredConnection} registered - Requesting connection.
305
+ * @param {LockServerEngineRequest} request - Request fields.
306
+ * @returns {void}
307
+ */
308
+ handleTryAcquire(registered, request) {
309
+ const {correlationId, name} = request
310
+
311
+ if (!name) {
312
+ this.respond(registered, correlationId, {error: "try-acquire requires a lock name", status: "error", type: "response"})
313
+
314
+ return
315
+ }
316
+
317
+ const record = this.lockRecord(name)
318
+ const heldEpoch = registered.held.get(name)
319
+
320
+ if (record.holder === registered && typeof heldEpoch === "number") {
321
+ this.respond(registered, correlationId, {epoch: heldEpoch, leaseExpiresAt: record.leaseExpiresAt, status: "already-held", type: "response"})
322
+
323
+ return
324
+ }
325
+
326
+ if (record.holder) {
327
+ this.respond(registered, correlationId, {ownerId: record.holder.id, status: "busy", type: "response"})
328
+
329
+ return
330
+ }
331
+
332
+ this.grant(registered, record, correlationId)
333
+ }
334
+
335
+ /**
336
+ * Handles `renew` with the fencing check: only the current holder with the
337
+ * matching epoch may extend the lease; a superseded holder gets `lost` with
338
+ * the current epoch.
339
+ * @param {LockServerEngineRegisteredConnection} registered - Renewing connection.
340
+ * @param {LockServerEngineRequest & {epoch: number}} request - Request fields.
341
+ * @returns {void}
342
+ */
343
+ handleRenew(registered, request) {
344
+ const {correlationId, epoch, name} = request
345
+ const record = this.locks.get(name)
346
+
347
+ if (!record) {
348
+ this.respond(registered, correlationId, {status: "not-found", type: "response"})
349
+
350
+ return
351
+ }
352
+
353
+ if (record.holder !== registered || record.epoch !== epoch) {
354
+ const status = registered.held.has(name) ? "lost" : "not-found"
355
+
356
+ this.respond(registered, correlationId, {currentEpoch: record.epoch, status, type: "response"})
357
+
358
+ return
359
+ }
360
+
361
+ record.leaseExpiresAt = Date.now() + this.leaseMs
362
+ this.respond(registered, correlationId, {leaseExpiresAt: record.leaseExpiresAt, status: "renewed", type: "response"})
363
+ }
364
+
365
+ /**
366
+ * Handles `release`: idempotent for the holder; `not-holder` after an epoch
367
+ * bump is the expected answer for a superseded holder.
368
+ * @param {LockServerEngineRegisteredConnection} registered - Releasing connection.
369
+ * @param {LockServerEngineRequest & {epoch?: number}} request - Request fields.
370
+ * @returns {void}
371
+ */
372
+ handleRelease(registered, request) {
373
+ const {correlationId, epoch, name} = request
374
+ const record = this.locks.get(name)
375
+
376
+ if (!record) {
377
+ this.respond(registered, correlationId, {status: "not-found", type: "response"})
378
+
379
+ return
380
+ }
381
+
382
+ if (record.holder !== registered) {
383
+ const status = registered.held.has(name) ? "not-holder" : "not-found"
384
+
385
+ this.respond(registered, correlationId, {currentEpoch: record.epoch, status, type: "response"})
386
+
387
+ return
388
+ }
389
+
390
+ if (typeof epoch === "number" && epoch !== record.epoch) {
391
+ this.respond(registered, correlationId, {currentEpoch: record.epoch, status: "not-holder", type: "response"})
392
+
393
+ return
394
+ }
395
+
396
+ record.holder = null
397
+ registered.held.delete(name)
398
+ this.respond(registered, correlationId, {status: "released", type: "response"})
399
+ this.grantNext(record)
400
+ }
401
+
402
+ /**
403
+ * Grants the lock to a connection: bumps the monotonic per-name epoch,
404
+ * installs the holder, and answers `acquired` echoing the correlation.
405
+ * @param {LockServerEngineRegisteredConnection} registered - Granted connection.
406
+ * @param {LockServerEngineLockRecord} record - Lock record.
407
+ * @param {string} correlationId - Correlation to echo.
408
+ * @returns {void}
409
+ */
410
+ grant(registered, record, correlationId) {
411
+ const epoch = (this.epochByLock.get(record.name) ?? 0) + 1
412
+
413
+ this.epochByLock.set(record.name, epoch)
414
+ record.epoch = epoch
415
+ record.holder = registered
416
+ record.leaseExpiresAt = Date.now() + this.leaseMs
417
+ registered.held.set(record.name, epoch)
418
+
419
+ this.respond(registered, correlationId, {epoch, leaseExpiresAt: record.leaseExpiresAt, status: "acquired", type: "response"})
420
+ }
421
+
422
+ /**
423
+ * Moves the FIFO queue's first live waiter into the grant path.
424
+ * @param {LockServerEngineLockRecord} record - Freed lock record.
425
+ * @returns {void}
426
+ */
427
+ grantNext(record) {
428
+ while (record.waiters.length > 0) {
429
+ const waiter = /** @type {LockServerEngineWaiter} */ (record.waiters.shift())
430
+
431
+ if (waiter.timer) clearTimeout(waiter.timer)
432
+ if (!waiter.connection.open) continue
433
+
434
+ this.grant(waiter.connection, record, waiter.correlationId)
435
+
436
+ return
437
+ }
438
+ }
439
+
440
+ /**
441
+ * Removes a waiter whose bounded wait elapsed and answers `timeout`.
442
+ * @param {LockServerEngineLockRecord} record - Lock record the waiter queued on.
443
+ * @param {LockServerEngineWaiter} waiter - Expired waiter.
444
+ * @returns {void}
445
+ */
446
+ expireWaiter(record, waiter) {
447
+ const index = record.waiters.indexOf(waiter)
448
+
449
+ if (index >= 0) record.waiters.splice(index, 1)
450
+ if (!waiter.connection.open) return
451
+
452
+ this.respond(waiter.connection, waiter.correlationId, {status: "timeout", type: "response"})
453
+ }
454
+
455
+ /**
456
+ * Sweeps expired leases: bumps the epoch (the old holder is fenced), pushes
457
+ * `lost` to the old holder, and grants the next waiter.
458
+ * @returns {void}
459
+ */
460
+ sweep() {
461
+ if (this.closed) return
462
+
463
+ const now = Date.now()
464
+
465
+ for (const record of this.locks.values()) {
466
+ const holder = record.holder
467
+
468
+ if (!holder || record.leaseExpiresAt > now) continue
469
+
470
+ const fencedEpoch = record.epoch
471
+
472
+ record.holder = null
473
+ holder.held.delete(record.name)
474
+ this.epochByLock.set(record.name, fencedEpoch + 1)
475
+ record.epoch = fencedEpoch + 1
476
+
477
+ try {
478
+ holder.connection.send({epoch: record.epoch, name: record.name, type: "lost"})
479
+ } catch {
480
+ // A dead transport cannot receive the push; the lease is already gone.
481
+ }
482
+
483
+ this.grantNext(record)
484
+ }
485
+ }
486
+
487
+ /**
488
+ * Returns (creating when needed) the live record for one lock name.
489
+ * @param {string} name - Lock name.
490
+ * @returns {LockServerEngineLockRecord} - Live record.
491
+ */
492
+ lockRecord(name) {
493
+ const existing = this.locks.get(name)
494
+
495
+ if (existing) return existing
496
+
497
+ /** @type {LockServerEngineLockRecord} */
498
+ const record = {epoch: this.epochByLock.get(name) ?? 0, holder: null, leaseExpiresAt: 0, name, waiters: []}
499
+
500
+ this.locks.set(name, record)
501
+
502
+ return record
503
+ }
504
+
505
+ /**
506
+ * Current holder info for one name (diagnostics).
507
+ * @param {string} name - Lock name.
508
+ * @returns {{epoch: number, holderId: string, leaseExpiresAt: number, name: string, waiterCount: number} | null} - Holder info, or null when free.
509
+ */
510
+ holderInfo(name) {
511
+ const record = this.locks.get(name)
512
+
513
+ if (!record || !record.holder) return null
514
+
515
+ return {epoch: record.epoch, holderId: record.holder.id, leaseExpiresAt: record.leaseExpiresAt, name, waiterCount: record.waiters.length}
516
+ }
517
+
518
+ /**
519
+ * Live holder list (diagnostics).
520
+ * @returns {{epoch: number, holderId: string, leaseExpiresAt: number, name: string, waiterCount: number}[]} - Live holders.
521
+ */
522
+ listHolders() {
523
+ const holders = []
524
+
525
+ for (const record of this.locks.values()) {
526
+ if (!record.holder) continue
527
+
528
+ holders.push({epoch: record.epoch, holderId: record.holder.id, leaseExpiresAt: record.leaseExpiresAt, name: record.name, waiterCount: record.waiters.length})
529
+ }
530
+
531
+ return holders
532
+ }
533
+
534
+ /**
535
+ * Sends one response to a connection.
536
+ * @param {LockServerEngineRegisteredConnection} registered - Target connection.
537
+ * @param {string} correlationId - Correlation to echo.
538
+ * @param {Record<string, unknown>} body - Response fields.
539
+ * @returns {void}
540
+ */
541
+ respond(registered, correlationId, body) {
542
+ registered.connection.send({...body, correlationId})
543
+ }
544
+ }