velocious 1.0.726 → 1.0.728
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.
- package/README.md +2 -2
- package/bin/velocious.js +2 -19
- package/build/application.js +32 -3
- package/build/background-jobs/main.js +9 -1
- package/build/background-jobs/worker.js +69 -6
- package/build/bin/velocious.js +2 -19
- package/build/cli/process-args.js +34 -0
- package/build/configuration-types.js +1 -1
- package/build/configuration.js +43 -2
- package/build/database/advisory-lock-lock-server-backend.js +30 -24
- package/build/database/advisory-lock-lock-server-embedded-client.js +74 -0
- package/build/database/advisory-lock-lock-server-engine.js +544 -0
- package/build/database/advisory-lock-lock-server-local-client.js +260 -0
- package/build/database/advisory-lock-lock-server-socket-path.js +17 -0
- package/build/database/advisory-lock-lock-server-transport.js +30 -0
- package/build/database/drivers/base.js +34 -12
- package/build/database/drivers/mssql/index.js +17 -18
- package/build/database/drivers/mssql/table.js +28 -25
- package/build/database/drivers/mysql/index.js +15 -18
- package/build/database/drivers/mysql/table.js +31 -23
- package/build/database/drivers/pgsql/index.js +15 -18
- package/build/database/drivers/pgsql/table.js +28 -26
- package/build/database/drivers/sqlite/base.js +7 -9
- package/build/database/drivers/sqlite/table.js +32 -26
- package/build/database/pool/async-tracked-multi-connection.js +1 -0
- package/build/database/pool/base.js +14 -4
- package/build/database/pool/single-multi-use.js +1 -0
- package/build/database/record/auditing.js +89 -11
- package/build/database/record/index.js +1 -1
- package/build/environment-handlers/base.js +50 -9
- package/build/environment-handlers/node/advisory-lock-lock-server-local-server.js +206 -0
- package/build/environment-handlers/node/cli/commands/server.js +1 -0
- package/build/environment-handlers/node.js +30 -3
- package/build/http-server/server-lock.js +55 -18
- package/build/src/application.d.ts +7 -4
- package/build/src/application.d.ts.map +1 -1
- package/build/src/application.js +27 -4
- package/build/src/background-jobs/main.d.ts +2 -1
- package/build/src/background-jobs/main.d.ts.map +1 -1
- package/build/src/background-jobs/main.js +10 -2
- package/build/src/background-jobs/worker.d.ts +42 -0
- package/build/src/background-jobs/worker.d.ts.map +1 -1
- package/build/src/background-jobs/worker.js +61 -5
- package/build/src/cli/process-args.d.ts +11 -0
- package/build/src/cli/process-args.d.ts.map +1 -0
- package/build/src/cli/process-args.js +34 -0
- package/build/src/configuration-types.d.ts +3 -1
- package/build/src/configuration-types.d.ts.map +1 -1
- package/build/src/configuration-types.js +2 -2
- package/build/src/configuration.d.ts +16 -1
- package/build/src/configuration.d.ts.map +1 -1
- package/build/src/configuration.js +39 -3
- package/build/src/database/advisory-lock-lock-server-backend.d.ts +10 -3
- package/build/src/database/advisory-lock-lock-server-backend.d.ts.map +1 -1
- package/build/src/database/advisory-lock-lock-server-backend.js +25 -22
- package/build/src/database/advisory-lock-lock-server-embedded-client.d.ts +24 -0
- package/build/src/database/advisory-lock-lock-server-embedded-client.d.ts.map +1 -0
- package/build/src/database/advisory-lock-lock-server-embedded-client.js +64 -0
- package/build/src/database/advisory-lock-lock-server-engine.d.ts +285 -0
- package/build/src/database/advisory-lock-lock-server-engine.d.ts.map +1 -0
- package/build/src/database/advisory-lock-lock-server-engine.js +460 -0
- package/build/src/database/advisory-lock-lock-server-local-client.d.ts +114 -0
- package/build/src/database/advisory-lock-lock-server-local-client.d.ts.map +1 -0
- package/build/src/database/advisory-lock-lock-server-local-client.js +227 -0
- package/build/src/database/advisory-lock-lock-server-socket-path.d.ts +9 -0
- package/build/src/database/advisory-lock-lock-server-socket-path.d.ts.map +1 -0
- package/build/src/database/advisory-lock-lock-server-socket-path.js +16 -0
- package/build/src/database/advisory-lock-lock-server-transport.d.ts +18 -0
- package/build/src/database/advisory-lock-lock-server-transport.d.ts.map +1 -0
- package/build/src/database/advisory-lock-lock-server-transport.js +27 -0
- package/build/src/database/drivers/base.d.ts +15 -2
- package/build/src/database/drivers/base.d.ts.map +1 -1
- package/build/src/database/drivers/base.js +33 -13
- package/build/src/database/drivers/mssql/index.d.ts +2 -2
- package/build/src/database/drivers/mssql/index.d.ts.map +1 -1
- package/build/src/database/drivers/mssql/index.js +17 -18
- package/build/src/database/drivers/mssql/table.d.ts.map +1 -1
- package/build/src/database/drivers/mssql/table.js +25 -23
- package/build/src/database/drivers/mysql/index.d.ts +2 -2
- package/build/src/database/drivers/mysql/index.d.ts.map +1 -1
- package/build/src/database/drivers/mysql/index.js +16 -19
- package/build/src/database/drivers/mysql/table.d.ts.map +1 -1
- package/build/src/database/drivers/mysql/table.js +27 -22
- package/build/src/database/drivers/pgsql/index.d.ts +2 -2
- package/build/src/database/drivers/pgsql/index.d.ts.map +1 -1
- package/build/src/database/drivers/pgsql/index.js +16 -19
- package/build/src/database/drivers/pgsql/table.d.ts.map +1 -1
- package/build/src/database/drivers/pgsql/table.js +25 -23
- package/build/src/database/drivers/sqlite/base.d.ts.map +1 -1
- package/build/src/database/drivers/sqlite/base.js +8 -10
- package/build/src/database/drivers/sqlite/table.d.ts.map +1 -1
- package/build/src/database/drivers/sqlite/table.js +29 -25
- package/build/src/database/pool/async-tracked-multi-connection.d.ts.map +1 -1
- package/build/src/database/pool/async-tracked-multi-connection.js +2 -1
- package/build/src/database/pool/base.d.ts +6 -0
- package/build/src/database/pool/base.d.ts.map +1 -1
- package/build/src/database/pool/base.js +14 -5
- package/build/src/database/pool/single-multi-use.d.ts.map +1 -1
- package/build/src/database/pool/single-multi-use.js +2 -1
- package/build/src/database/record/auditing.d.ts +14 -4
- package/build/src/database/record/auditing.d.ts.map +1 -1
- package/build/src/database/record/auditing.js +77 -12
- package/build/src/database/record/index.d.ts +4 -2
- package/build/src/database/record/index.d.ts.map +1 -1
- package/build/src/database/record/index.js +2 -2
- package/build/src/environment-handlers/base.d.ts +86 -7
- package/build/src/environment-handlers/base.d.ts.map +1 -1
- package/build/src/environment-handlers/base.js +48 -9
- package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.d.ts +2 -0
- package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.d.ts.map +1 -0
- package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +179 -0
- package/build/src/environment-handlers/node/cli/commands/server.d.ts.map +1 -1
- package/build/src/environment-handlers/node/cli/commands/server.js +2 -1
- package/build/src/environment-handlers/node.d.ts +10 -4
- package/build/src/environment-handlers/node.d.ts.map +1 -1
- package/build/src/environment-handlers/node.js +30 -4
- package/build/src/http-server/server-lock.d.ts +43 -14
- package/build/src/http-server/server-lock.d.ts.map +1 -1
- package/build/src/http-server/server-lock.js +54 -19
- package/build/src/tenants/default-tenant-database-provisioning.d.ts.map +1 -1
- package/build/src/tenants/default-tenant-database-provisioning.js +7 -1
- package/build/tenants/default-tenant-database-provisioning.js +8 -0
- package/package.json +2 -2
- package/src/application.js +32 -3
- package/src/background-jobs/main.js +9 -1
- package/src/background-jobs/worker.js +69 -6
- package/src/cli/process-args.js +34 -0
- package/src/configuration-types.js +1 -1
- package/src/configuration.js +43 -2
- package/src/database/advisory-lock-lock-server-backend.js +30 -24
- package/src/database/advisory-lock-lock-server-embedded-client.js +74 -0
- package/src/database/advisory-lock-lock-server-engine.js +544 -0
- package/src/database/advisory-lock-lock-server-local-client.js +260 -0
- package/src/database/advisory-lock-lock-server-socket-path.js +17 -0
- package/src/database/advisory-lock-lock-server-transport.js +30 -0
- package/src/database/drivers/base.js +34 -12
- package/src/database/drivers/mssql/index.js +17 -18
- package/src/database/drivers/mssql/table.js +28 -25
- package/src/database/drivers/mysql/index.js +15 -18
- package/src/database/drivers/mysql/table.js +31 -23
- package/src/database/drivers/pgsql/index.js +15 -18
- package/src/database/drivers/pgsql/table.js +28 -26
- package/src/database/drivers/sqlite/base.js +7 -9
- package/src/database/drivers/sqlite/table.js +32 -26
- package/src/database/pool/async-tracked-multi-connection.js +1 -0
- package/src/database/pool/base.js +14 -4
- package/src/database/pool/single-multi-use.js +1 -0
- package/src/database/record/auditing.js +89 -11
- package/src/database/record/index.js +1 -1
- package/src/environment-handlers/base.js +50 -9
- package/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +206 -0
- package/src/environment-handlers/node/cli/commands/server.js +1 -0
- package/src/environment-handlers/node.js +30 -3
- package/src/http-server/server-lock.js +55 -18
- package/src/tenants/default-tenant-database-provisioning.js +8 -0
|
@@ -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
|
+
}
|