velocious 1.0.755 → 1.0.756
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/build/configuration-types.js +1 -1
- package/build/configuration.js +4 -1
- package/build/database/advisory-lock-lock-server-local-client.js +28 -1
- package/build/environment-handlers/base.js +2 -0
- package/build/environment-handlers/node/advisory-lock-lock-server-local-server.js +260 -23
- package/build/environment-handlers/node.js +7 -4
- package/build/src/configuration-types.d.ts +3 -2
- package/build/src/configuration-types.d.ts.map +1 -1
- package/build/src/configuration-types.js +2 -2
- package/build/src/configuration.d.ts +2 -1
- package/build/src/configuration.d.ts.map +1 -1
- package/build/src/configuration.js +5 -2
- package/build/src/database/advisory-lock-lock-server-local-client.d.ts +10 -1
- package/build/src/database/advisory-lock-lock-server-local-client.d.ts.map +1 -1
- package/build/src/database/advisory-lock-lock-server-local-client.js +25 -2
- package/build/src/environment-handlers/base.d.ts +7 -0
- package/build/src/environment-handlers/base.d.ts.map +1 -1
- package/build/src/environment-handlers/base.js +3 -1
- package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +239 -28
- package/build/src/environment-handlers/node.d.ts +5 -3
- package/build/src/environment-handlers/node.d.ts.map +1 -1
- package/build/src/environment-handlers/node.js +8 -5
- package/package.json +1 -1
- package/src/configuration-types.js +1 -1
- package/src/configuration.js +4 -1
- package/src/database/advisory-lock-lock-server-local-client.js +28 -1
- package/src/environment-handlers/base.js +2 -0
- package/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +260 -23
- package/src/environment-handlers/node.js +7 -4
|
@@ -916,7 +916,7 @@
|
|
|
916
916
|
* behavior; the file backend is disabled by default and only selectable by
|
|
917
917
|
* explicit configuration.
|
|
918
918
|
* @typedef {object} AdvisoryLocksConfiguration
|
|
919
|
-
* @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}, lockServer?: {authToken?: string, connectTimeoutMs?: number, enabled?: boolean, host?: string, leaseMs?: number, mode?: "embedded" | "external" | "local", port?: number, reprobeCooldownMs?: number, socketPath?: string, url?: string}}} [backends] - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration. `lockServer` defaults to enabled when a host/port/url or the `VELOCIOUS_LOCK_SERVER_HOST`/`_PORT` env pair is configured.
|
|
919
|
+
* @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}, lockServer?: {authToken?: string, connectTimeoutMs?: number, enabled?: boolean, host?: string, leaseMs?: number, mode?: "embedded" | "external" | "local", port?: number, reprobeCooldownMs?: number, socketPath?: string, spawnEngine?: boolean, url?: string}}} [backends] - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration. `lockServer` defaults to enabled when a host/port/url or the `VELOCIOUS_LOCK_SERVER_HOST`/`_PORT` env pair is configured. `lockServer.spawnEngine` is `local`-only and defaults to true; false means a supervisor owns the engine and this process never spawns one.
|
|
920
920
|
* @property {import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]} [policy] - Per-lock-name minimum/allowed/preferred tier rules (design §5).
|
|
921
921
|
*/
|
|
922
922
|
|
package/build/configuration.js
CHANGED
|
@@ -4333,7 +4333,7 @@ export default class VelociousConfiguration {
|
|
|
4333
4333
|
* Full backward compatibility: an app that configures nothing gets today's
|
|
4334
4334
|
* driver-native-only behavior — the file backend is **disabled by default**
|
|
4335
4335
|
* and only ever selectable by explicit configuration.
|
|
4336
|
-
* @returns {{backends: {file: {directory?: string, enabled: boolean, leaseMs: number, renewIntervalMs: number}, lockServer: {authToken: string, connectTimeoutMs: number, enabled: boolean, leaseMs: number, mode: "embedded" | "external" | "local", reprobeCooldownMs: number, socketPath: string, url: string}}, policy: import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]}} - Advisory-lock configuration with defaults applied.
|
|
4336
|
+
* @returns {{backends: {file: {directory?: string, enabled: boolean, leaseMs: number, renewIntervalMs: number}, lockServer: {authToken: string, connectTimeoutMs: number, enabled: boolean, leaseMs: number, mode: "embedded" | "external" | "local", reprobeCooldownMs: number, socketPath: string, spawnEngine: boolean, url: string}}, policy: import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]}} - Advisory-lock configuration with defaults applied.
|
|
4337
4337
|
*/
|
|
4338
4338
|
getAdvisoryLockConfig() {
|
|
4339
4339
|
const configured = this._advisoryLocks || {}
|
|
@@ -4379,6 +4379,8 @@ export default class VelociousConfiguration {
|
|
|
4379
4379
|
leaseMs: typeof lockServerConfigured.leaseMs === "number" ? lockServerConfigured.leaseMs : 30_000,
|
|
4380
4380
|
mode: lockServerMode,
|
|
4381
4381
|
reprobeCooldownMs: typeof lockServerConfigured.reprobeCooldownMs === "number" ? lockServerConfigured.reprobeCooldownMs : 5000,
|
|
4382
|
+
// `local` mode spawns its engine on demand. Set false when a supervisor (a Rollbridge service, for example) owns the engine, so no client can put a second unsupervised authority on the same socket path.
|
|
4383
|
+
spawnEngine: typeof lockServerConfigured.spawnEngine === "boolean" ? lockServerConfigured.spawnEngine : true,
|
|
4382
4384
|
socketPath: typeof lockServerConfigured.socketPath === "string" ? lockServerConfigured.socketPath : "",
|
|
4383
4385
|
url: lockServerUrl
|
|
4384
4386
|
}
|
|
@@ -4478,6 +4480,7 @@ export default class VelociousConfiguration {
|
|
|
4478
4480
|
},
|
|
4479
4481
|
reprobeCooldownMs: config.backends.lockServer.reprobeCooldownMs,
|
|
4480
4482
|
socketPath: config.backends.lockServer.socketPath,
|
|
4483
|
+
spawnEngine: config.backends.lockServer.spawnEngine,
|
|
4481
4484
|
url: config.backends.lockServer.url
|
|
4482
4485
|
})
|
|
4483
4486
|
|
|
@@ -21,6 +21,12 @@ import {fileURLToPath} from "node:url"
|
|
|
21
21
|
* acquisition after the cooldown reconnects — respawning the engine child when
|
|
22
22
|
* the socket file is gone. The cooldown IS the restart backoff; there is no
|
|
23
23
|
* separate respawn loop.
|
|
24
|
+
*
|
|
25
|
+
* With `spawnEngine: false` the engine belongs to a supervisor (a Rollbridge
|
|
26
|
+
* service, for example) and this client never spawns one, so exactly one
|
|
27
|
+
* process on the host can own the socket. A missing engine then surfaces as an
|
|
28
|
+
* outage, and the engine server's takeover path replaces a retiring authority
|
|
29
|
+
* without a window where nothing is listening.
|
|
24
30
|
*/
|
|
25
31
|
export default class AdvisoryLockLockServerLocalClient {
|
|
26
32
|
/**
|
|
@@ -30,13 +36,15 @@ export default class AdvisoryLockLockServerLocalClient {
|
|
|
30
36
|
* @param {string} [args.authToken] - Shared secret forwarded in the hello params.
|
|
31
37
|
* @param {number} [args.connectTimeoutMs] - Bounded wait for the socket/engine child to become ready.
|
|
32
38
|
* @param {number} [args.leaseMs] - Lease duration the engine child should use.
|
|
39
|
+
* @param {boolean} [args.spawnEngine] - When false the engine is owned by a supervisor and this client never spawns one: a missing engine is reported as an outage instead of being replaced by an unsupervised child that would fight the supervisor for the socket.
|
|
33
40
|
* @param {string} args.socketPath - Unix socket path of the local engine.
|
|
34
41
|
*/
|
|
35
|
-
constructor({authToken = "", connectTimeoutMs = 3000, leaseMs = 30_000, socketPath}) {
|
|
42
|
+
constructor({authToken = "", connectTimeoutMs = 3000, leaseMs = 30_000, socketPath, spawnEngine = true}) {
|
|
36
43
|
this.authToken = authToken
|
|
37
44
|
this.connectTimeoutMs = connectTimeoutMs
|
|
38
45
|
this.leaseMs = leaseMs
|
|
39
46
|
this.socketPath = socketPath
|
|
47
|
+
this.spawnEngine = spawnEngine !== false
|
|
40
48
|
this.connectionId = `client-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
|
|
41
49
|
/** @type {net.Socket | null} */
|
|
42
50
|
this.socket = null
|
|
@@ -64,6 +72,13 @@ export default class AdvisoryLockLockServerLocalClient {
|
|
|
64
72
|
} catch (error) {
|
|
65
73
|
if (!this.socketMissingError(error)) throw error
|
|
66
74
|
|
|
75
|
+
if (!this.spawnEngine) {
|
|
76
|
+
// The engine is a supervised process: spawning a child here would put a
|
|
77
|
+
// second, unsupervised authority on the same socket path. Report the
|
|
78
|
+
// outage and let the supervisor's own restart heal it.
|
|
79
|
+
throw new Error(`No supervised local lock server is listening at ${this.socketPath}`, {cause: error})
|
|
80
|
+
}
|
|
81
|
+
|
|
67
82
|
// No engine is listening (missing socket, or a stale socket file left by
|
|
68
83
|
// a crashed engine): spawn the engine child and poll until it is live.
|
|
69
84
|
this.spawnEngineChild()
|
|
@@ -222,6 +237,18 @@ export default class AdvisoryLockLockServerLocalClient {
|
|
|
222
237
|
try {
|
|
223
238
|
const parsed = /** @type {Record<string, unknown>} */ (JSON.parse(line))
|
|
224
239
|
|
|
240
|
+
if (parsed.type === "server-retiring") {
|
|
241
|
+
// The engine is handing the host over to its successor: drop this
|
|
242
|
+
// transport now so the next acquisition reconnects to the successor
|
|
243
|
+
// instead of staying bound to an engine that is on its way out.
|
|
244
|
+
const socket = this.socket
|
|
245
|
+
|
|
246
|
+
this.handleTransportDeath(new Error("Local lock server is retiring"))
|
|
247
|
+
socket?.destroy()
|
|
248
|
+
|
|
249
|
+
continue
|
|
250
|
+
}
|
|
251
|
+
|
|
225
252
|
this.onMessage?.(parsed)
|
|
226
253
|
} catch {
|
|
227
254
|
// A malformed engine line is not a lock answer: the adapter's
|
|
@@ -39,6 +39,7 @@ import {validateTimeZone} from "../time-zone.js"
|
|
|
39
39
|
* @property {(error: Error) => void} [onError] - Async error reporter.
|
|
40
40
|
* @property {number} [reprobeCooldownMs] - How long an unavailable server is not re-probed.
|
|
41
41
|
* @property {string} [socketPath] - Unix socket path for `local` mode (defaults to a short path under os.tmpdir()).
|
|
42
|
+
* @property {boolean} [spawnEngine] - `local` mode only: false when a supervisor owns the engine, so this process never spawns a rival authority on the socket path.
|
|
42
43
|
* @property {string} url - Lock-server endpoint (websocket URL for external mode; informational for embedded/local modes).
|
|
43
44
|
*/
|
|
44
45
|
|
|
@@ -85,6 +86,7 @@ export default class VelociousEnvironmentHandlerBase {
|
|
|
85
86
|
* @param {(error: Error) => void} [args.onError] - Async error reporter.
|
|
86
87
|
* @param {number} [args.reprobeCooldownMs] - Unavailability cache window.
|
|
87
88
|
* @param {string} [args.socketPath] - Unix socket path for `local` mode.
|
|
89
|
+
* @param {boolean} [args.spawnEngine] - `local` mode only: false when a supervisor owns the engine.
|
|
88
90
|
* @param {string} args.url - Lock-server endpoint.
|
|
89
91
|
* @returns {Promise<import("../database/advisory-lock-lock-server-backend.js").default>} - Resolves with the created backend in capable handlers.
|
|
90
92
|
*/
|
|
@@ -18,15 +18,26 @@ import net from "node:net"
|
|
|
18
18
|
* has been gone for `VELOCIOUS_LOCK_SERVER_IDLE_SHUTDOWN_MS` — so a host never
|
|
19
19
|
* accumulates orphan engines. SIGTERM/SIGINT shut it down cleanly.
|
|
20
20
|
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
21
|
+
* Two startup shapes, selected by `VELOCIOUS_LOCK_SERVER_TAKEOVER`:
|
|
22
|
+
*
|
|
23
|
+
* - unset (a client-spawned candidate): if another live engine already owns
|
|
24
|
+
* the socket path, this candidate exits quietly — that engine serves the
|
|
25
|
+
* host. A stale socket file from a crashed engine is removed before listening.
|
|
26
|
+
* - `1` (a supervisor-owned engine, e.g. a Rollbridge service): the candidate
|
|
27
|
+
* retires the incumbent instead of yielding to it. It asks the incumbent to
|
|
28
|
+
* stop accepting and tell its clients to reconnect, takes the socket path
|
|
29
|
+
* over while the incumbent finishes its in-flight requests, and binds. The
|
|
30
|
+
* incumbent's clients land on this engine, so a supervised authority can be
|
|
31
|
+
* replaced without a window where nothing is listening.
|
|
24
32
|
*/
|
|
25
33
|
|
|
26
34
|
const socketPath = defaultLockServerSocketPath(process.env.VELOCIOUS_LOCK_SERVER_SOCKET_PATH)
|
|
27
35
|
const leaseMsRaw = Number(process.env.CONSENS_LOCK_LEASE_MS)
|
|
28
36
|
const idleShutdownMsRaw = Number(process.env.VELOCIOUS_LOCK_SERVER_IDLE_SHUTDOWN_MS)
|
|
29
37
|
const idleShutdownMs = Number.isFinite(idleShutdownMsRaw) && idleShutdownMsRaw >= 0 ? idleShutdownMsRaw : 30_000
|
|
38
|
+
const drainTimeoutMsRaw = Number(process.env.VELOCIOUS_LOCK_SERVER_DRAIN_TIMEOUT_MS)
|
|
39
|
+
const drainTimeoutMs = Number.isFinite(drainTimeoutMsRaw) && drainTimeoutMsRaw >= 0 ? drainTimeoutMsRaw : 10_000
|
|
40
|
+
const takeoverRequested = /^(1|true|yes)$/i.test(String(process.env.VELOCIOUS_LOCK_SERVER_TAKEOVER || ""))
|
|
30
41
|
|
|
31
42
|
const engine = new AdvisoryLockLockServerEngine({
|
|
32
43
|
leaseMs: Number.isFinite(leaseMsRaw) && leaseMsRaw > 0 ? leaseMsRaw : 30_000
|
|
@@ -36,8 +47,15 @@ engine.startSweeper()
|
|
|
36
47
|
|
|
37
48
|
let closing = false
|
|
38
49
|
let connectionCount = 0
|
|
50
|
+
let listening = false
|
|
51
|
+
let retiring = false
|
|
52
|
+
// Set when this engine was retired by a successor: the successor owns the
|
|
53
|
+
// socket path now, so this engine must not unlink it on its way out.
|
|
54
|
+
let socketHandedOff = false
|
|
39
55
|
/** @type {ReturnType<typeof setTimeout> | null} */
|
|
40
56
|
let idleTimer = null
|
|
57
|
+
/** @type {Map<net.Socket, Set<string>>} */
|
|
58
|
+
const clientConnections = new Map()
|
|
41
59
|
|
|
42
60
|
/**
|
|
43
61
|
* Answers a startup race: is another live engine already listening on the
|
|
@@ -59,6 +77,15 @@ function probeExistingEngine() {
|
|
|
59
77
|
})
|
|
60
78
|
}
|
|
61
79
|
|
|
80
|
+
/**
|
|
81
|
+
* Waits for one protocol beat.
|
|
82
|
+
* @param {number} ms - Delay.
|
|
83
|
+
* @returns {Promise<void>} - Resolves after the delay.
|
|
84
|
+
*/
|
|
85
|
+
function sleep(ms) {
|
|
86
|
+
return new Promise((resolve) => setTimeout(resolve, ms))
|
|
87
|
+
}
|
|
88
|
+
|
|
62
89
|
/**
|
|
63
90
|
* Cancels a pending idle-shutdown countdown (a client is back).
|
|
64
91
|
* @returns {void}
|
|
@@ -77,13 +104,73 @@ function cancelIdleShutdown() {
|
|
|
77
104
|
* @returns {void}
|
|
78
105
|
*/
|
|
79
106
|
function scheduleIdleShutdown() {
|
|
80
|
-
if (closing || connectionCount > 0) return
|
|
107
|
+
if (closing || retiring || connectionCount > 0) return
|
|
81
108
|
|
|
82
109
|
cancelIdleShutdown()
|
|
83
110
|
idleTimer = setTimeout(() => shutdown(), idleShutdownMs)
|
|
84
111
|
idleTimer.unref?.()
|
|
85
112
|
}
|
|
86
113
|
|
|
114
|
+
/**
|
|
115
|
+
* Tells every live client that this engine is going away, so its transport
|
|
116
|
+
* reconnects to the successor instead of discovering the outage request by
|
|
117
|
+
* request.
|
|
118
|
+
* @returns {void}
|
|
119
|
+
*/
|
|
120
|
+
function notifyClientsRetiring() {
|
|
121
|
+
for (const [socket, connectionIds] of clientConnections) {
|
|
122
|
+
if (socket.destroyed) continue
|
|
123
|
+
|
|
124
|
+
for (const connectionId of connectionIds) {
|
|
125
|
+
try {
|
|
126
|
+
socket.write(`${JSON.stringify({connectionId, type: "server-retiring"})}\n`)
|
|
127
|
+
} catch {
|
|
128
|
+
// A transport that cannot take the notice is already gone; its leases
|
|
129
|
+
// are released by the engine close below.
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Removes this engine's socket file. Skipped after a handoff, because the
|
|
137
|
+
* successor already bound the same path and unlinking it would take the
|
|
138
|
+
* authority's address away from the host.
|
|
139
|
+
* @returns {void}
|
|
140
|
+
*/
|
|
141
|
+
function releaseSocketPath() {
|
|
142
|
+
if (socketHandedOff) return
|
|
143
|
+
|
|
144
|
+
try {
|
|
145
|
+
fs.unlinkSync(socketPath)
|
|
146
|
+
} catch {
|
|
147
|
+
// The socket file may already be gone; nothing left to clean.
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Stops listening, releases the socket path, and exits.
|
|
153
|
+
* @returns {void}
|
|
154
|
+
*/
|
|
155
|
+
function exitCleanly() {
|
|
156
|
+
if (listening) {
|
|
157
|
+
listening = false
|
|
158
|
+
server.close(() => {
|
|
159
|
+
releaseSocketPath()
|
|
160
|
+
process.exit(0)
|
|
161
|
+
})
|
|
162
|
+
setTimeout(() => {
|
|
163
|
+
releaseSocketPath()
|
|
164
|
+
process.exit(0)
|
|
165
|
+
}, 2000).unref?.()
|
|
166
|
+
|
|
167
|
+
return
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
releaseSocketPath()
|
|
171
|
+
process.exit(0)
|
|
172
|
+
}
|
|
173
|
+
|
|
87
174
|
/**
|
|
88
175
|
* Clean shutdown: close the engine, stop listening, remove the socket file.
|
|
89
176
|
* @returns {void}
|
|
@@ -93,17 +180,146 @@ function shutdown() {
|
|
|
93
180
|
|
|
94
181
|
closing = true
|
|
95
182
|
cancelIdleShutdown()
|
|
183
|
+
notifyClientsRetiring()
|
|
96
184
|
engine.close()
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
185
|
+
exitCleanly()
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Retirement requested by the successor engine (or by an operator hook): stop
|
|
190
|
+
* accepting new connections, tell the live clients to reconnect elsewhere, let
|
|
191
|
+
* in-flight requests finish, then exit without taking the socket path away
|
|
192
|
+
* from the successor.
|
|
193
|
+
* @returns {void}
|
|
194
|
+
*/
|
|
195
|
+
function beginRetire() {
|
|
196
|
+
if (closing || retiring) return
|
|
103
197
|
|
|
198
|
+
retiring = true
|
|
199
|
+
socketHandedOff = true
|
|
200
|
+
cancelIdleShutdown()
|
|
201
|
+
// A supervisor sees this exit as unexpected, so the reason has to be in the log it keeps.
|
|
202
|
+
process.stderr.write(`lock server retiring: handing ${socketPath} to a successor engine\n`)
|
|
203
|
+
notifyClientsRetiring()
|
|
204
|
+
|
|
205
|
+
if (listening) {
|
|
206
|
+
listening = false
|
|
207
|
+
server.close(() => {
|
|
208
|
+
engine.close()
|
|
209
|
+
releaseSocketPath()
|
|
210
|
+
process.exit(0)
|
|
211
|
+
})
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
// Clients close on the retiring notice. One that ignores it must not keep the
|
|
215
|
+
// retired engine — and the leases on its connections — alive past the drain
|
|
216
|
+
// bound, so the bound cuts the transports and lets `server.close()` settle.
|
|
217
|
+
setTimeout(() => {
|
|
218
|
+
for (const socket of clientConnections.keys()) socket.destroy()
|
|
219
|
+
}, drainTimeoutMs).unref?.()
|
|
220
|
+
|
|
221
|
+
// Hard ceiling: a transport that cannot settle after being cut must not hold
|
|
222
|
+
// this process open forever.
|
|
223
|
+
setTimeout(() => {
|
|
224
|
+
engine.close()
|
|
225
|
+
releaseSocketPath()
|
|
104
226
|
process.exit(0)
|
|
227
|
+
}, drainTimeoutMs + 2000).unref?.()
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/**
|
|
231
|
+
* Asks the incumbent engine on this socket path to retire, and waits until it
|
|
232
|
+
* has stopped listening so this candidate can bind.
|
|
233
|
+
*
|
|
234
|
+
* The incumbent's `retire-ack` is the handoff signal: it stops accepting and
|
|
235
|
+
* removes the socket file at that moment, so the successor binds as soon as the
|
|
236
|
+
* path stops answering. Waiting for the connection to close instead would make
|
|
237
|
+
* the handoff depend on when the incumbent happens to finish draining.
|
|
238
|
+
* @returns {Promise<boolean>} - True when the incumbent stopped listening.
|
|
239
|
+
*/
|
|
240
|
+
async function retireIncumbentEngine() {
|
|
241
|
+
const acked = await new Promise((resolve) => {
|
|
242
|
+
const socket = net.connect(socketPath)
|
|
243
|
+
let buffer = ""
|
|
244
|
+
const deadline = setTimeout(() => {
|
|
245
|
+
socket.destroy()
|
|
246
|
+
resolve(false)
|
|
247
|
+
}, drainTimeoutMs + 5000)
|
|
248
|
+
|
|
249
|
+
deadline.unref?.()
|
|
250
|
+
|
|
251
|
+
const finish = (/** @type {boolean} */ result) => {
|
|
252
|
+
clearTimeout(deadline)
|
|
253
|
+
socket.destroy()
|
|
254
|
+
resolve(result)
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
socket.once("error", () => finish(false))
|
|
258
|
+
socket.once("connect", () => {
|
|
259
|
+
socket.write(`${JSON.stringify({connectionId: `takeover-${process.pid}`, type: "retire"})}\n`)
|
|
260
|
+
})
|
|
261
|
+
socket.setEncoding("utf8")
|
|
262
|
+
socket.on("data", (/** @type {string} */ chunk) => {
|
|
263
|
+
buffer += chunk
|
|
264
|
+
|
|
265
|
+
let newlineIndex = buffer.indexOf("\n")
|
|
266
|
+
|
|
267
|
+
while (newlineIndex >= 0) {
|
|
268
|
+
const line = buffer.slice(0, newlineIndex)
|
|
269
|
+
|
|
270
|
+
buffer = buffer.slice(newlineIndex + 1)
|
|
271
|
+
|
|
272
|
+
if (!line.trim()) {
|
|
273
|
+
newlineIndex = buffer.indexOf("\n")
|
|
274
|
+
|
|
275
|
+
continue
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
try {
|
|
279
|
+
const message = /** @type {Record<string, unknown>} */ (JSON.parse(line))
|
|
280
|
+
|
|
281
|
+
if (message.type === "retire-ack") {
|
|
282
|
+
finish(true)
|
|
283
|
+
|
|
284
|
+
return
|
|
285
|
+
}
|
|
286
|
+
} catch {
|
|
287
|
+
// Not a protocol answer; keep waiting for the ack until the deadline.
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
newlineIndex = buffer.indexOf("\n")
|
|
291
|
+
}
|
|
292
|
+
})
|
|
105
293
|
})
|
|
106
|
-
|
|
294
|
+
|
|
295
|
+
if (!acked) return false
|
|
296
|
+
|
|
297
|
+
// The incumbent stopped accepting and removed its socket file; confirm the
|
|
298
|
+
// path really stopped answering before binding to it.
|
|
299
|
+
const deadline = Date.now() + drainTimeoutMs + 5000
|
|
300
|
+
|
|
301
|
+
while (Date.now() < deadline) {
|
|
302
|
+
if (!(await probeExistingEngine())) return true
|
|
303
|
+
|
|
304
|
+
await sleep(25)
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
return false
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/**
|
|
311
|
+
* Binds this engine to the socket path, clearing a stale socket file first.
|
|
312
|
+
* @returns {void}
|
|
313
|
+
*/
|
|
314
|
+
function bindSocketPath() {
|
|
315
|
+
try {
|
|
316
|
+
fs.unlinkSync(socketPath)
|
|
317
|
+
} catch {
|
|
318
|
+
// No stale socket to remove.
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
server.listen(socketPath)
|
|
322
|
+
listening = true
|
|
107
323
|
}
|
|
108
324
|
|
|
109
325
|
/**
|
|
@@ -119,6 +335,9 @@ function handleClientSocket(socket) {
|
|
|
119
335
|
|
|
120
336
|
/** @type {Set<string>} */
|
|
121
337
|
const socketConnectionIds = new Set()
|
|
338
|
+
|
|
339
|
+
clientConnections.set(socket, socketConnectionIds)
|
|
340
|
+
|
|
122
341
|
let buffer = ""
|
|
123
342
|
|
|
124
343
|
socket.on("data", (/** @type {string} */ chunk) => {
|
|
@@ -139,7 +358,16 @@ function handleClientSocket(socket) {
|
|
|
139
358
|
if (connectionId) {
|
|
140
359
|
socketConnectionIds.add(connectionId)
|
|
141
360
|
|
|
142
|
-
|
|
361
|
+
// The retirement frame is a transport control message, not a lock
|
|
362
|
+
// request: it is answered here and never reaches the engine.
|
|
363
|
+
if (message.type === "retire") {
|
|
364
|
+
socket.write(`${JSON.stringify({connectionId, status: "retiring", type: "retire-ack"})}\n`)
|
|
365
|
+
beginRetire()
|
|
366
|
+
// The successor is not a client to drain: it is waiting for this
|
|
367
|
+
// connection to end, and keeping it open would hold the retired
|
|
368
|
+
// engine's own `server.close()` until the drain bound expires.
|
|
369
|
+
socket.end()
|
|
370
|
+
} else if (message.type === "hello") {
|
|
143
371
|
socket.write(`${JSON.stringify({connectionId, leaseMs: engine.leaseMs, protocolVersion: LOCK_SERVER_PROTOCOL_VERSION, type: "hello-ack"})}\n`)
|
|
144
372
|
} else {
|
|
145
373
|
engine.ensureConnection(connectionId, {
|
|
@@ -162,6 +390,7 @@ function handleClientSocket(socket) {
|
|
|
162
390
|
|
|
163
391
|
socket.on("close", () => {
|
|
164
392
|
connectionCount -= 1
|
|
393
|
+
clientConnections.delete(socket)
|
|
165
394
|
|
|
166
395
|
// The transport died: the engine releases every lease this socket held,
|
|
167
396
|
// exactly like the external daemon does on a websocket close.
|
|
@@ -176,12 +405,19 @@ const server = net.createServer((socket) => handleClientSocket(socket))
|
|
|
176
405
|
|
|
177
406
|
server.on("error", async (/** @type {{code?: string}} */ error) => {
|
|
178
407
|
if (error.code === "EADDRINUSE") {
|
|
179
|
-
// Either a live engine owns the path
|
|
180
|
-
//
|
|
181
|
-
|
|
408
|
+
// Either a live engine owns the path or a crashed one left a stale socket
|
|
409
|
+
// behind. A supervisor-owned candidate retires the live engine; a
|
|
410
|
+
// client-spawned candidate yields to it and exits quietly.
|
|
411
|
+
if (await probeExistingEngine()) {
|
|
412
|
+
if (!takeoverRequested) process.exit(0)
|
|
413
|
+
|
|
414
|
+
if (!(await retireIncumbentEngine())) {
|
|
415
|
+
process.stderr.write(`lock-server takeover refused: the engine at ${socketPath} did not retire within ${drainTimeoutMs + 5000}ms\n`)
|
|
416
|
+
process.exit(1)
|
|
417
|
+
}
|
|
418
|
+
}
|
|
182
419
|
|
|
183
|
-
|
|
184
|
-
server.listen(socketPath)
|
|
420
|
+
bindSocketPath()
|
|
185
421
|
|
|
186
422
|
return
|
|
187
423
|
}
|
|
@@ -191,15 +427,16 @@ server.on("error", async (/** @type {{code?: string}} */ error) => {
|
|
|
191
427
|
|
|
192
428
|
const alreadyLive = await probeExistingEngine()
|
|
193
429
|
|
|
194
|
-
if (alreadyLive)
|
|
430
|
+
if (alreadyLive) {
|
|
431
|
+
if (!takeoverRequested) process.exit(0)
|
|
195
432
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
433
|
+
if (!(await retireIncumbentEngine())) {
|
|
434
|
+
process.stderr.write(`lock-server takeover refused: the engine at ${socketPath} did not retire within ${drainTimeoutMs + 5000}ms\n`)
|
|
435
|
+
process.exit(1)
|
|
436
|
+
}
|
|
200
437
|
}
|
|
201
438
|
|
|
202
|
-
|
|
439
|
+
bindSocketPath()
|
|
203
440
|
|
|
204
441
|
for (const signal of ["SIGTERM", "SIGINT"]) {
|
|
205
442
|
process.on(signal, () => shutdown())
|
|
@@ -127,9 +127,11 @@ export default class VelociousEnvironmentHandlerNode extends Base{
|
|
|
127
127
|
*
|
|
128
128
|
* - `external` (default): the Node websocket transport to the shared
|
|
129
129
|
* consens-lock daemon — unchanged behavior for existing configurations.
|
|
130
|
-
* - `local`:
|
|
131
|
-
*
|
|
132
|
-
* environment, crash detection via the
|
|
130
|
+
* - `local`: connects to the engine server on a Unix socket, spawning it as
|
|
131
|
+
* a child of this process when nothing is listening — no listening network
|
|
132
|
+
* port, lifecycle follows the environment, crash detection via the
|
|
133
|
+
* adapter's unavailability cache. `spawnEngine: false` keeps a supervised
|
|
134
|
+
* engine (a Rollbridge service) as the only process that can own the socket.
|
|
133
135
|
* - `embedded`: the base handler's in-process engine (no sockets at all).
|
|
134
136
|
* @param {import("./base.js").AdvisoryLockLockServerBackendOptions} args - Backend options.
|
|
135
137
|
* @returns {Promise<import("../database/advisory-lock-lock-server-backend.js").default>} - Created backend.
|
|
@@ -142,7 +144,8 @@ export default class VelociousEnvironmentHandlerNode extends Base{
|
|
|
142
144
|
authToken,
|
|
143
145
|
connectTimeoutMs: args.connectTimeoutMs,
|
|
144
146
|
leaseMs: args.leaseMs,
|
|
145
|
-
socketPath: args.socketPath || defaultLockServerSocketPath()
|
|
147
|
+
socketPath: args.socketPath || defaultLockServerSocketPath(),
|
|
148
|
+
spawnEngine: args.spawnEngine
|
|
146
149
|
})
|
|
147
150
|
})
|
|
148
151
|
}
|
|
@@ -1847,7 +1847,7 @@ export type TenantDatabaseProviderType = {
|
|
|
1847
1847
|
};
|
|
1848
1848
|
export type AdvisoryLocksConfiguration = {
|
|
1849
1849
|
/**
|
|
1850
|
-
* - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration. `lockServer` defaults to enabled when a host/port/url or the `VELOCIOUS_LOCK_SERVER_HOST`/`_PORT` env pair is configured.
|
|
1850
|
+
* - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration. `lockServer` defaults to enabled when a host/port/url or the `VELOCIOUS_LOCK_SERVER_HOST`/`_PORT` env pair is configured. `lockServer.spawnEngine` is `local`-only and defaults to true; false means a supervisor owns the engine and this process never spawns one.
|
|
1851
1851
|
*/
|
|
1852
1852
|
backends?: {
|
|
1853
1853
|
file?: {
|
|
@@ -1866,6 +1866,7 @@ export type AdvisoryLocksConfiguration = {
|
|
|
1866
1866
|
port?: number;
|
|
1867
1867
|
reprobeCooldownMs?: number;
|
|
1868
1868
|
socketPath?: string;
|
|
1869
|
+
spawnEngine?: boolean;
|
|
1869
1870
|
url?: string;
|
|
1870
1871
|
};
|
|
1871
1872
|
};
|
|
@@ -2890,7 +2891,7 @@ export type ConfigurationArgsType = {
|
|
|
2890
2891
|
* behavior; the file backend is disabled by default and only selectable by
|
|
2891
2892
|
* explicit configuration.
|
|
2892
2893
|
* @typedef {object} AdvisoryLocksConfiguration
|
|
2893
|
-
* @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}, lockServer?: {authToken?: string, connectTimeoutMs?: number, enabled?: boolean, host?: string, leaseMs?: number, mode?: "embedded" | "external" | "local", port?: number, reprobeCooldownMs?: number, socketPath?: string, url?: string}}} [backends] - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration. `lockServer` defaults to enabled when a host/port/url or the `VELOCIOUS_LOCK_SERVER_HOST`/`_PORT` env pair is configured.
|
|
2894
|
+
* @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}, lockServer?: {authToken?: string, connectTimeoutMs?: number, enabled?: boolean, host?: string, leaseMs?: number, mode?: "embedded" | "external" | "local", port?: number, reprobeCooldownMs?: number, socketPath?: string, spawnEngine?: boolean, url?: string}}} [backends] - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration. `lockServer` defaults to enabled when a host/port/url or the `VELOCIOUS_LOCK_SERVER_HOST`/`_PORT` env pair is configured. `lockServer.spawnEngine` is `local`-only and defaults to true; false means a supervisor owns the engine and this process never spawns one.
|
|
2894
2895
|
* @property {import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]} [policy] - Per-lock-name minimum/allowed/preferred tier rules (design §5).
|
|
2895
2896
|
*/
|
|
2896
2897
|
/**
|