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.
Files changed (155) hide show
  1. package/README.md +2 -2
  2. package/bin/velocious.js +2 -19
  3. package/build/application.js +32 -3
  4. package/build/background-jobs/main.js +9 -1
  5. package/build/background-jobs/worker.js +69 -6
  6. package/build/bin/velocious.js +2 -19
  7. package/build/cli/process-args.js +34 -0
  8. package/build/configuration-types.js +1 -1
  9. package/build/configuration.js +43 -2
  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/drivers/base.js +34 -12
  17. package/build/database/drivers/mssql/index.js +17 -18
  18. package/build/database/drivers/mssql/table.js +28 -25
  19. package/build/database/drivers/mysql/index.js +15 -18
  20. package/build/database/drivers/mysql/table.js +31 -23
  21. package/build/database/drivers/pgsql/index.js +15 -18
  22. package/build/database/drivers/pgsql/table.js +28 -26
  23. package/build/database/drivers/sqlite/base.js +7 -9
  24. package/build/database/drivers/sqlite/table.js +32 -26
  25. package/build/database/pool/async-tracked-multi-connection.js +1 -0
  26. package/build/database/pool/base.js +14 -4
  27. package/build/database/pool/single-multi-use.js +1 -0
  28. package/build/database/record/auditing.js +89 -11
  29. package/build/database/record/index.js +1 -1
  30. package/build/environment-handlers/base.js +50 -9
  31. package/build/environment-handlers/node/advisory-lock-lock-server-local-server.js +206 -0
  32. package/build/environment-handlers/node/cli/commands/server.js +1 -0
  33. package/build/environment-handlers/node.js +30 -3
  34. package/build/http-server/server-lock.js +55 -18
  35. package/build/src/application.d.ts +7 -4
  36. package/build/src/application.d.ts.map +1 -1
  37. package/build/src/application.js +27 -4
  38. package/build/src/background-jobs/main.d.ts +2 -1
  39. package/build/src/background-jobs/main.d.ts.map +1 -1
  40. package/build/src/background-jobs/main.js +10 -2
  41. package/build/src/background-jobs/worker.d.ts +42 -0
  42. package/build/src/background-jobs/worker.d.ts.map +1 -1
  43. package/build/src/background-jobs/worker.js +61 -5
  44. package/build/src/cli/process-args.d.ts +11 -0
  45. package/build/src/cli/process-args.d.ts.map +1 -0
  46. package/build/src/cli/process-args.js +34 -0
  47. package/build/src/configuration-types.d.ts +3 -1
  48. package/build/src/configuration-types.d.ts.map +1 -1
  49. package/build/src/configuration-types.js +2 -2
  50. package/build/src/configuration.d.ts +16 -1
  51. package/build/src/configuration.d.ts.map +1 -1
  52. package/build/src/configuration.js +39 -3
  53. package/build/src/database/advisory-lock-lock-server-backend.d.ts +10 -3
  54. package/build/src/database/advisory-lock-lock-server-backend.d.ts.map +1 -1
  55. package/build/src/database/advisory-lock-lock-server-backend.js +25 -22
  56. package/build/src/database/advisory-lock-lock-server-embedded-client.d.ts +24 -0
  57. package/build/src/database/advisory-lock-lock-server-embedded-client.d.ts.map +1 -0
  58. package/build/src/database/advisory-lock-lock-server-embedded-client.js +64 -0
  59. package/build/src/database/advisory-lock-lock-server-engine.d.ts +285 -0
  60. package/build/src/database/advisory-lock-lock-server-engine.d.ts.map +1 -0
  61. package/build/src/database/advisory-lock-lock-server-engine.js +460 -0
  62. package/build/src/database/advisory-lock-lock-server-local-client.d.ts +114 -0
  63. package/build/src/database/advisory-lock-lock-server-local-client.d.ts.map +1 -0
  64. package/build/src/database/advisory-lock-lock-server-local-client.js +227 -0
  65. package/build/src/database/advisory-lock-lock-server-socket-path.d.ts +9 -0
  66. package/build/src/database/advisory-lock-lock-server-socket-path.d.ts.map +1 -0
  67. package/build/src/database/advisory-lock-lock-server-socket-path.js +16 -0
  68. package/build/src/database/advisory-lock-lock-server-transport.d.ts +18 -0
  69. package/build/src/database/advisory-lock-lock-server-transport.d.ts.map +1 -0
  70. package/build/src/database/advisory-lock-lock-server-transport.js +27 -0
  71. package/build/src/database/drivers/base.d.ts +15 -2
  72. package/build/src/database/drivers/base.d.ts.map +1 -1
  73. package/build/src/database/drivers/base.js +33 -13
  74. package/build/src/database/drivers/mssql/index.d.ts +2 -2
  75. package/build/src/database/drivers/mssql/index.d.ts.map +1 -1
  76. package/build/src/database/drivers/mssql/index.js +17 -18
  77. package/build/src/database/drivers/mssql/table.d.ts.map +1 -1
  78. package/build/src/database/drivers/mssql/table.js +25 -23
  79. package/build/src/database/drivers/mysql/index.d.ts +2 -2
  80. package/build/src/database/drivers/mysql/index.d.ts.map +1 -1
  81. package/build/src/database/drivers/mysql/index.js +16 -19
  82. package/build/src/database/drivers/mysql/table.d.ts.map +1 -1
  83. package/build/src/database/drivers/mysql/table.js +27 -22
  84. package/build/src/database/drivers/pgsql/index.d.ts +2 -2
  85. package/build/src/database/drivers/pgsql/index.d.ts.map +1 -1
  86. package/build/src/database/drivers/pgsql/index.js +16 -19
  87. package/build/src/database/drivers/pgsql/table.d.ts.map +1 -1
  88. package/build/src/database/drivers/pgsql/table.js +25 -23
  89. package/build/src/database/drivers/sqlite/base.d.ts.map +1 -1
  90. package/build/src/database/drivers/sqlite/base.js +8 -10
  91. package/build/src/database/drivers/sqlite/table.d.ts.map +1 -1
  92. package/build/src/database/drivers/sqlite/table.js +29 -25
  93. package/build/src/database/pool/async-tracked-multi-connection.d.ts.map +1 -1
  94. package/build/src/database/pool/async-tracked-multi-connection.js +2 -1
  95. package/build/src/database/pool/base.d.ts +6 -0
  96. package/build/src/database/pool/base.d.ts.map +1 -1
  97. package/build/src/database/pool/base.js +14 -5
  98. package/build/src/database/pool/single-multi-use.d.ts.map +1 -1
  99. package/build/src/database/pool/single-multi-use.js +2 -1
  100. package/build/src/database/record/auditing.d.ts +14 -4
  101. package/build/src/database/record/auditing.d.ts.map +1 -1
  102. package/build/src/database/record/auditing.js +77 -12
  103. package/build/src/database/record/index.d.ts +4 -2
  104. package/build/src/database/record/index.d.ts.map +1 -1
  105. package/build/src/database/record/index.js +2 -2
  106. package/build/src/environment-handlers/base.d.ts +86 -7
  107. package/build/src/environment-handlers/base.d.ts.map +1 -1
  108. package/build/src/environment-handlers/base.js +48 -9
  109. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.d.ts +2 -0
  110. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.d.ts.map +1 -0
  111. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +179 -0
  112. package/build/src/environment-handlers/node/cli/commands/server.d.ts.map +1 -1
  113. package/build/src/environment-handlers/node/cli/commands/server.js +2 -1
  114. package/build/src/environment-handlers/node.d.ts +10 -4
  115. package/build/src/environment-handlers/node.d.ts.map +1 -1
  116. package/build/src/environment-handlers/node.js +30 -4
  117. package/build/src/http-server/server-lock.d.ts +43 -14
  118. package/build/src/http-server/server-lock.d.ts.map +1 -1
  119. package/build/src/http-server/server-lock.js +54 -19
  120. package/build/src/tenants/default-tenant-database-provisioning.d.ts.map +1 -1
  121. package/build/src/tenants/default-tenant-database-provisioning.js +7 -1
  122. package/build/tenants/default-tenant-database-provisioning.js +8 -0
  123. package/package.json +2 -2
  124. package/src/application.js +32 -3
  125. package/src/background-jobs/main.js +9 -1
  126. package/src/background-jobs/worker.js +69 -6
  127. package/src/cli/process-args.js +34 -0
  128. package/src/configuration-types.js +1 -1
  129. package/src/configuration.js +43 -2
  130. package/src/database/advisory-lock-lock-server-backend.js +30 -24
  131. package/src/database/advisory-lock-lock-server-embedded-client.js +74 -0
  132. package/src/database/advisory-lock-lock-server-engine.js +544 -0
  133. package/src/database/advisory-lock-lock-server-local-client.js +260 -0
  134. package/src/database/advisory-lock-lock-server-socket-path.js +17 -0
  135. package/src/database/advisory-lock-lock-server-transport.js +30 -0
  136. package/src/database/drivers/base.js +34 -12
  137. package/src/database/drivers/mssql/index.js +17 -18
  138. package/src/database/drivers/mssql/table.js +28 -25
  139. package/src/database/drivers/mysql/index.js +15 -18
  140. package/src/database/drivers/mysql/table.js +31 -23
  141. package/src/database/drivers/pgsql/index.js +15 -18
  142. package/src/database/drivers/pgsql/table.js +28 -26
  143. package/src/database/drivers/sqlite/base.js +7 -9
  144. package/src/database/drivers/sqlite/table.js +32 -26
  145. package/src/database/pool/async-tracked-multi-connection.js +1 -0
  146. package/src/database/pool/base.js +14 -4
  147. package/src/database/pool/single-multi-use.js +1 -0
  148. package/src/database/record/auditing.js +89 -11
  149. package/src/database/record/index.js +1 -1
  150. package/src/environment-handlers/base.js +50 -9
  151. package/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +206 -0
  152. package/src/environment-handlers/node/cli/commands/server.js +1 -0
  153. package/src/environment-handlers/node.js +30 -3
  154. package/src/http-server/server-lock.js +55 -18
  155. package/src/tenants/default-tenant-database-provisioning.js +8 -0
package/README.md CHANGED
@@ -1598,7 +1598,7 @@ await new StructureSqlLoader().load({db, structureSql})
1598
1598
 
1599
1599
  ## Schema metadata cache
1600
1600
 
1601
- Velocious caches schema metadata on each database driver instance so repeated model initialization, table lookups, column introspection, and structure SQL generation can reuse the same database results. The cache is cleared automatically after schema-changing SQL runs through Velocious, such as migrations, `createTable`, `dropTable`, `renameColumn`, `ALTER TABLE`, `CREATE INDEX`, and `COMMENT ON`. See [docs/schema-metadata-cache.md](docs/schema-metadata-cache.md) for details.
1601
+ Velocious caches schema metadata per physical database so repeated model initialization, table lookups, column introspection, and structure SQL generation can reuse the same database results. Every connection to one physical database shares the cache, so pooled drivers do not re-introspect after idle-connection reaping or connection churn. The cache is cleared automatically after schema-changing SQL runs through Velocious, such as migrations, `createTable`, `dropTable`, `renameColumn`, `ALTER TABLE`, `CREATE INDEX`, and `COMMENT ON`. See [docs/schema-metadata-cache.md](docs/schema-metadata-cache.md) for details.
1602
1602
 
1603
1603
  If another process changes the schema outside Velocious while the current process is still running, clear the cache before reading metadata again:
1604
1604
 
@@ -2954,7 +2954,7 @@ request parser.
2954
2954
 
2955
2955
  When the server runs in the `development` environment, Velocious watches application `src/` trees and hot-reloads by recycling HTTP workers after `.js`/`.mjs`/`.cjs`/`.json`/`.ejs` changes. That picks up edited controllers, models, resources, routes, and views without a manual server restart while keeping production/test behavior unchanged.
2956
2956
 
2957
- Starting the HTTP server creates `tmp/server.lock` under the configured application directory before Beacon, workers, or the TCP listener start. A second server for the same app fails fast with the lock owner details instead of partially starting. Normal shutdown removes the lock; stale locks with a dead local PID are reclaimed automatically, while locks from another host or unreadable metadata should be removed manually only after confirming no server is running. See [docs/http-server.md](docs/http-server.md#server-lock).
2957
+ Starting the HTTP server creates `tmp/server.<environment>.lock` under the configured application directory before Beacon, workers, or the TCP listener start. A second server for the same app and environment fails fast with the lock owner details instead of partially starting. Normal shutdown removes the lock; stale locks with a dead local PID are reclaimed automatically, while locks from another host or unreadable metadata should be removed manually only after confirming no server is running. A caller that knowingly wants a second server in one (directory, environment) pair can opt out with `--no-server-lock` or `VELOCIOUS_HTTP_SERVER_LOCK=off`, which logs one warning naming the application directory and port; that escape hatch is for test-spawned backends, not production. See [docs/http-server.md](docs/http-server.md#server-lock).
2958
2958
 
2959
2959
  Set `database: false` for an explicitly database-free application; its HTTP and
2960
2960
  initializer lifecycle remains intact without creating a default pool or an
package/bin/velocious.js CHANGED
@@ -1,28 +1,11 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  import Cli from "../src/cli/index.js"
4
+ import parseProcessArgs from "../src/cli/process-args.js"
4
5
  import configurationResolver from "../src/configuration-resolver.js"
5
6
 
6
7
  const processArgs = process.argv.slice(2)
7
- /** @type {Record<string, string | boolean | undefined>} */
8
- const parsedProcessArgs = {}
9
-
10
- for (let i = 0; i < processArgs.length; i++) {
11
- const processArg = processArgs[i]
12
- const singleLetterArgMatch = processArg.match(/^-([a-z])$/)
13
- const multiLetterArgMatch = processArg.match(/^--([a-z]+)$/)
14
- const nextArg = processArgs[i + 1]
15
- const hasValue = typeof nextArg === "string" && !nextArg.startsWith("-")
16
- const parsedValue = hasValue ? nextArg : true
17
-
18
- if (singleLetterArgMatch) {
19
- parsedProcessArgs[singleLetterArgMatch[1]] = parsedValue
20
- if (hasValue) i++
21
- } else if (multiLetterArgMatch) {
22
- parsedProcessArgs[multiLetterArgMatch[1]] = parsedValue
23
- if (hasValue) i++
24
- }
25
- }
8
+ const parsedProcessArgs = parseProcessArgs(processArgs)
26
9
 
27
10
  const configuration = await configurationResolver()
28
11
  const debugEnabled = Boolean(parsedProcessArgs.d || parsedProcessArgs.debug)
@@ -15,15 +15,27 @@ import { runShutdownSteps } from "./utils/shutdown-lifecycle.js"
15
15
  * HttpServerConfiguration type.
16
16
  * @typedef {import("./configuration-types.js").HttpServerConfiguration} HttpServerConfiguration */
17
17
 
18
+ /**
19
+ * Reads the lock opt-out requested through the environment. Only an explicit
20
+ * off value opts out; anything else keeps the default protected behaviour.
21
+ * @returns {boolean} - Whether the environment asks for the HTTP server lock opt-out.
22
+ */
23
+ function environmentHttpServerLockOptOut() {
24
+ const value = (process.env.VELOCIOUS_HTTP_SERVER_LOCK || "").trim().toLowerCase()
25
+
26
+ return value === "off" || value === "false" || value === "0"
27
+ }
28
+
18
29
  export default class VelociousApplication {
19
30
  /**
20
31
  * Runs constructor.
21
32
  * @param {object} args - Options object.
22
33
  * @param {import("./configuration.js").default} args.configuration - Configuration instance.
23
34
  * @param {HttpServerConfiguration} [args.httpServer] - Http server.
35
+ * @param {boolean} [args.httpServerLockOptOut] - Start this server without the HTTP server lock, knowingly running unprotected against a duplicate server in the same application directory and environment.
24
36
  * @param {string} args.type - Type identifier.
25
37
  */
26
- constructor({configuration, httpServer, type, ...restArgs}) {
38
+ constructor({configuration, httpServer, httpServerLockOptOut, type, ...restArgs}) {
27
39
  restArgsError(restArgs)
28
40
 
29
41
  if (!configuration) throw new Error("configuration is required")
@@ -35,6 +47,11 @@ export default class VelociousApplication {
35
47
  * @type {HttpServerConfiguration} */
36
48
  this.httpServerConfiguration = httpServer ?? {}
37
49
 
50
+ /**
51
+ * Stores the explicit HTTP server lock opt-out for this application.
52
+ * @type {boolean} */
53
+ this.httpServerLockOptOut = httpServerLockOptOut === true
54
+
38
55
  this.logger = new Logger(this)
39
56
  this._type = type
40
57
  /**
@@ -165,8 +182,20 @@ export default class VelociousApplication {
165
182
  async acquireHttpServerLock({configuration, host, port}) {
166
183
  if (this.getType() === "test-runner") return
167
184
 
168
- const httpServerLock = new HttpServerLock({configuration, host, port})
169
- await httpServerLock.acquire()
185
+ const httpServerLock = new HttpServerLock({
186
+ configuration,
187
+ host,
188
+ port,
189
+ optOut: this.httpServerLockOptOut || environmentHttpServerLockOptOut()
190
+ })
191
+
192
+ const acquired = await httpServerLock.acquire()
193
+
194
+ if (!acquired) {
195
+ await this.logger.warn(httpServerLock.lockSkippedMessage())
196
+ return
197
+ }
198
+
170
199
  this.httpServerLock = httpServerLock
171
200
  }
172
201
 
@@ -1660,7 +1660,8 @@ export default class BackgroundJobsMain {
1660
1660
  }
1661
1661
 
1662
1662
  /**
1663
- * Forgets a successfully reported lease without relying on worker ids.
1663
+ * Forgets an in-memory lease that no longer exists durably — a reported lease or
1664
+ * one settled as orphaned — without relying on worker ids.
1664
1665
  * @param {object} args - Options.
1665
1666
  * @param {string} args.handoffId - Handoff lease id.
1666
1667
  * @param {string} args.jobId - Job id.
@@ -2793,6 +2794,13 @@ export default class BackgroundJobsMain {
2793
2794
  // Emit before awaiting the drain so a blocked dispatcher cannot delay
2794
2795
  // application recovery. Isolate handlers so one cannot suppress the rest.
2795
2796
  for (const job of jobs) {
2797
+ // The durable lease is gone, so the in-memory mirror must stop counting it.
2798
+ // A retired generation is pinned by `workerHandoffs`, and a row settled here
2799
+ // is no longer a live claim while its mirror still says it is — that is what
2800
+ // kept a retired main open after its worker's runner was proven gone
2801
+ // (STOE-1663), because the stop fence could never be reached.
2802
+ if (job.handoffId) this._forgetHandoff({handoffId: job.handoffId, jobId: job.id})
2803
+
2796
2804
  try {
2797
2805
  this._emitBackgroundJobOrphaned({job})
2798
2806
  } catch (error) {
@@ -13,6 +13,7 @@ import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
13
13
  import performBackgroundJob from "./perform-job.js"
14
14
  import { runWithBackgroundJobPayload } from "./execution-context.js"
15
15
  import { createGenerationWorkerId } from "./generation-identity.js"
16
+ import { isProcessAlive } from "./owner-liveness.js"
16
17
  import BackgroundJobsGenerationHandshakeTimeoutError, { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
17
18
  import { POOLED_RUNNER_INFLIGHT_JOB_ID_LIMIT, boundedPooledRunnerInflightJobIds, isPooledChildShutdownReason, isPooledChildShutdownSignal } from "./pooled-runner-shutdown.js"
18
19
 
@@ -33,7 +34,9 @@ import { POOLED_RUNNER_INFLIGHT_JOB_ID_LIMIT, boundedPooledRunnerInflightJobIds,
33
34
  * One live runner child, kept so a shutdown that runs out of drain time can name
34
35
  * the exact process it is still waiting on instead of a bare count.
35
36
  * @typedef {object} ProcessJobHolder
37
+ * @property {number | null} childPid - OS pid recorded for the runner, or null when the fork gave none.
36
38
  * @property {string} jobId - Job the child was handed.
39
+ * @property {(() => void)} settle - Frees the worker's in-flight entry for this job.
37
40
  * @property {number} startedAtMs - When the worker handed it that job.
38
41
  */
39
42
  /**
@@ -590,6 +593,7 @@ export default class BackgroundJobsWorker {
590
593
 
591
594
  await this._drainInflight(this.inflightInlineJobs, timeoutMs, {phase: "inline-jobs"})
592
595
  await this._drainInflight(this.inflightPooledJobs, timeoutMs, {phase: "pooled-jobs"})
596
+ this._releaseProcessJobHoldersWithGoneChildren()
593
597
  await this._drainInflight(this.inflightProcessJobs, timeoutMs, {phase: "process-jobs", describeHolders: () => this._describeProcessJobHolders()})
594
598
  await this._terminateProcessChildren()
595
599
  // Give in-flight result reports (now decoupled from job slots) a bounded
@@ -635,6 +639,7 @@ export default class BackgroundJobsWorker {
635
639
 
636
640
  await this._drainInflight(this.inflightInlineJobs)
637
641
  await this._drainInflight(this.inflightPooledJobs)
642
+ this._releaseProcessJobHoldersWithGoneChildren()
638
643
  await this._drainInflight(this.inflightProcessJobs)
639
644
  await this._drainInflight(this.inflightReports)
640
645
 
@@ -722,6 +727,48 @@ export default class BackgroundJobsWorker {
722
727
  return [...this.processChildJobs.values()].sort((left, right) => left.startedAtMs - right.startedAtMs)
723
728
  }
724
729
 
730
+ /**
731
+ * Frees in-flight process-job entries whose recorded runner pid no longer
732
+ * exists, so an unbounded drain can reach child termination.
733
+ *
734
+ * A drain that has no bound can only be pinned by work that is still able to
735
+ * report its outcome. A holder whose recorded pid has no process cannot report
736
+ * and cannot produce the exit observation that would have freed the entry, so
737
+ * the drain waits on it forever and never reaches `_terminateProcessChildren()`
738
+ * — the shape that kept a retired generation alive across four deploys on
739
+ * 2026-11-12 (STOE-1663). This is one proof-of-absence check at the point the
740
+ * drain begins, not a polling layer: a child that is still alive keeps the
741
+ * indefinite wait it was designed to have, because a live runner with a live
742
+ * job must never be cut off by this path (STOE-1077), and its exit observation
743
+ * is the event that frees its entry when it does go.
744
+ * @returns {ProcessJobHolder[]} - Holders freed, in recording order.
745
+ */
746
+ _releaseProcessJobHoldersWithGoneChildren() {
747
+ const released = []
748
+
749
+ for (const holder of [...this.processChildJobs.values()]) {
750
+ if (holder.childPid === null || isProcessAlive(holder.childPid)) continue
751
+
752
+ released.push(holder)
753
+ holder.settle()
754
+ }
755
+
756
+ if (released.length > 0) {
757
+ const nowMs = Date.now()
758
+
759
+ console.error(JSON.stringify({
760
+ event: "worker-shutdown-gone-runner-released",
761
+ runners: released.map((holder) => ({
762
+ childPid: holder.childPid,
763
+ heldMs: nowMs - holder.startedAtMs,
764
+ jobId: holder.jobId
765
+ }))
766
+ }))
767
+ }
768
+
769
+ return released
770
+ }
771
+
725
772
  /**
726
773
  * Logs one compact drain-timeout event to the worker's own stderr (the surface
727
774
  * that reaches the production log), naming the held processes and how long each
@@ -2234,9 +2281,6 @@ export default class BackgroundJobsWorker {
2234
2281
  _forkJob(payload) {
2235
2282
  const child = this._createForkedChild()
2236
2283
 
2237
- this.inflightProcessChildren.add(child)
2238
- this.processChildJobs.set(child, {jobId: payload.id, startedAtMs: Date.now()})
2239
-
2240
2284
  const finished = this._waitForForkedChild({child, payload})
2241
2285
 
2242
2286
  this._sendForkedPayload({child, payload})
@@ -2244,6 +2288,25 @@ export default class BackgroundJobsWorker {
2244
2288
  return finished
2245
2289
  }
2246
2290
 
2291
+ /**
2292
+ * Records the live runner child this worker handed a job to, with the resolver
2293
+ * that frees the worker's in-flight entry for it, so a drain can name the exact
2294
+ * process it is waiting on and can prove which of them is no longer there.
2295
+ * @param {object} args - Holder fields.
2296
+ * @param {import("node:child_process").ChildProcess} args.child - Runner child.
2297
+ * @param {import("./types.js").BackgroundJobPayload & {id: string}} args.payload - Job payload.
2298
+ * @param {(() => void)} args.settle - Frees the worker's in-flight entry for this job.
2299
+ * @returns {ProcessJobHolder} - Recorded holder.
2300
+ */
2301
+ _registerProcessJobHolder({child, payload, settle}) {
2302
+ const holder = {childPid: child.pid ?? null, jobId: payload.id, settle, startedAtMs: Date.now()}
2303
+
2304
+ this.inflightProcessChildren.add(child)
2305
+ this.processChildJobs.set(child, holder)
2306
+
2307
+ return holder
2308
+ }
2309
+
2247
2310
  /**
2248
2311
  * Runs create forked child.
2249
2312
  * @returns {import("node:child_process").ChildProcess} - Forked child process.
@@ -2283,6 +2346,7 @@ export default class BackgroundJobsWorker {
2283
2346
 
2284
2347
  return new Promise((resolve) => {
2285
2348
  state.resolve = resolve
2349
+ this._registerProcessJobHolder({child, payload, settle: () => this._settleForkedJob({child, state})})
2286
2350
  this._armForkedJobTimeout({child, payload, state})
2287
2351
 
2288
2352
  child.once("message", (message) => {
@@ -2557,10 +2621,9 @@ export default class BackgroundJobsWorker {
2557
2621
  env: Object.assign({}, process.env, this._childBackgroundJobsEnvironment(), {VELOCIOUS_JOB_PAYLOAD: encodedPayload})
2558
2622
  })
2559
2623
 
2560
- this.inflightProcessChildren.add(child)
2561
- this.processChildJobs.set(child, {jobId: payload.id, startedAtMs: Date.now()})
2562
-
2563
2624
  const finished = new Promise((resolve) => {
2625
+ this._registerProcessJobHolder({child, payload, settle: () => resolve(undefined)})
2626
+
2564
2627
  child.once("exit", () => {
2565
2628
  this.inflightProcessChildren.delete(child)
2566
2629
  this.processChildJobs.delete(child)
@@ -1,28 +1,11 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  import Cli from "../src/cli/index.js"
4
+ import parseProcessArgs from "../src/cli/process-args.js"
4
5
  import configurationResolver from "../src/configuration-resolver.js"
5
6
 
6
7
  const processArgs = process.argv.slice(2)
7
- /** @type {Record<string, string | boolean | undefined>} */
8
- const parsedProcessArgs = {}
9
-
10
- for (let i = 0; i < processArgs.length; i++) {
11
- const processArg = processArgs[i]
12
- const singleLetterArgMatch = processArg.match(/^-([a-z])$/)
13
- const multiLetterArgMatch = processArg.match(/^--([a-z]+)$/)
14
- const nextArg = processArgs[i + 1]
15
- const hasValue = typeof nextArg === "string" && !nextArg.startsWith("-")
16
- const parsedValue = hasValue ? nextArg : true
17
-
18
- if (singleLetterArgMatch) {
19
- parsedProcessArgs[singleLetterArgMatch[1]] = parsedValue
20
- if (hasValue) i++
21
- } else if (multiLetterArgMatch) {
22
- parsedProcessArgs[multiLetterArgMatch[1]] = parsedValue
23
- if (hasValue) i++
24
- }
25
- }
8
+ const parsedProcessArgs = parseProcessArgs(processArgs)
26
9
 
27
10
  const configuration = await configurationResolver()
28
11
  const debugEnabled = Boolean(parsedProcessArgs.d || parsedProcessArgs.debug)
@@ -0,0 +1,34 @@
1
+ // @ts-check
2
+
3
+ /**
4
+ * Parses CLI flags into values keyed by long option name without `--`.
5
+ *
6
+ * Hyphenated long flags are parsed as one option name (`--no-server-lock` →
7
+ * `no-server-lock`), so a boolean flag can carry its own words instead of
8
+ * being silently dropped by a single-word pattern.
9
+ * @param {string[]} processArgs - Raw CLI arguments.
10
+ * @returns {Record<string, string | boolean | undefined>} - Values keyed by option name.
11
+ */
12
+ export default function parseProcessArgs(processArgs) {
13
+ /** @type {Record<string, string | boolean | undefined>} */
14
+ const parsedProcessArgs = {}
15
+
16
+ for (let i = 0; i < processArgs.length; i++) {
17
+ const processArg = processArgs[i]
18
+ const singleLetterArgMatch = processArg.match(/^-([a-z])$/)
19
+ const multiLetterArgMatch = processArg.match(/^--([a-z][a-z-]*)$/)
20
+ const nextArg = processArgs[i + 1]
21
+ const hasValue = typeof nextArg === "string" && !nextArg.startsWith("-")
22
+ const parsedValue = hasValue ? nextArg : true
23
+
24
+ if (singleLetterArgMatch) {
25
+ parsedProcessArgs[singleLetterArgMatch[1]] = parsedValue
26
+ if (hasValue) i++
27
+ } else if (multiLetterArgMatch) {
28
+ parsedProcessArgs[multiLetterArgMatch[1]] = parsedValue
29
+ if (hasValue) i++
30
+ }
31
+ }
32
+
33
+ return parsedProcessArgs
34
+ }
@@ -882,7 +882,7 @@
882
882
  * behavior; the file backend is disabled by default and only selectable by
883
883
  * explicit configuration.
884
884
  * @typedef {object} AdvisoryLocksConfiguration
885
- * @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}, lockServer?: {authToken?: string, connectTimeoutMs?: number, enabled?: boolean, host?: string, leaseMs?: number, port?: number, reprobeCooldownMs?: number, 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.
885
+ * @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.
886
886
  * @property {import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]} [policy] - Per-lock-name minimum/allowed/preferred tier rules (design §5).
887
887
  */
888
888
 
@@ -286,6 +286,14 @@ export default class VelociousConfiguration {
286
286
  /** @type {Map<string, number>} */
287
287
  _schemaCacheGenerationsByReuseKey = new Map()
288
288
 
289
+ /**
290
+ * Schema-metadata cache maps keyed by physical database reuse key. Every
291
+ * connection to one physical database shares a single map, so cached table
292
+ * and column introspection survives pool connection churn instead of being
293
+ * re-run on every re-spawned connection.
294
+ * @type {Map<string, Map<string, Promise<ReturnType<typeof JSON.parse>>>>} */
295
+ _schemaCacheMapsByReuseKey = new Map()
296
+
289
297
  /**
290
298
  * Runs current.
291
299
  * @returns {VelociousConfiguration} - The current.
@@ -1422,6 +1430,8 @@ export default class VelociousConfiguration {
1422
1430
  this.schemaCacheGenerationForReuseKey(reuseKey) + 1
1423
1431
  )
1424
1432
 
1433
+ this.schemaCacheMapForReuseKey(reuseKey).clear()
1434
+
1425
1435
  for (const pool of Object.values(this.databasePools)) {
1426
1436
  if (pool.getConfigurationReuseKey() === reuseKey) {
1427
1437
  pool.clearSchemaCache()
@@ -1438,6 +1448,22 @@ export default class VelociousConfiguration {
1438
1448
  return this._schemaCacheGenerationsByReuseKey.get(reuseKey) || 0
1439
1449
  }
1440
1450
 
1451
+ /**
1452
+ * Returns the schema-metadata cache map shared by every connection to one physical database, creating it on first use.
1453
+ * @param {string} reuseKey - Connection reuse key identifying the physical database.
1454
+ * @returns {Map<string, Promise<ReturnType<typeof JSON.parse>>>} - Shared schema metadata cache map.
1455
+ */
1456
+ schemaCacheMapForReuseKey(reuseKey) {
1457
+ let schemaCacheMap = this._schemaCacheMapsByReuseKey.get(reuseKey)
1458
+
1459
+ if (!schemaCacheMap) {
1460
+ schemaCacheMap = new Map()
1461
+ this._schemaCacheMapsByReuseKey.set(reuseKey, schemaCacheMap)
1462
+ }
1463
+
1464
+ return schemaCacheMap
1465
+ }
1466
+
1441
1467
  /**
1442
1468
  * Invalidates record metadata owned by one closed/deleted physical tenant
1443
1469
  * database while preserving every other tenant generation.
@@ -4234,7 +4260,7 @@ export default class VelociousConfiguration {
4234
4260
  * Full backward compatibility: an app that configures nothing gets today's
4235
4261
  * driver-native-only behavior — the file backend is **disabled by default**
4236
4262
  * and only ever selectable by explicit configuration.
4237
- * @returns {{backends: {file: {directory?: string, enabled: boolean, leaseMs: number, renewIntervalMs: number}, lockServer: {authToken: string, connectTimeoutMs: number, enabled: boolean, leaseMs: number, reprobeCooldownMs: number, url: string}}, policy: import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]}} - Advisory-lock configuration with defaults applied.
4263
+ * @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.
4238
4264
  */
4239
4265
  getAdvisoryLockConfig() {
4240
4266
  const configured = this._advisoryLocks || {}
@@ -4249,6 +4275,15 @@ export default class VelociousConfiguration {
4249
4275
  : (typeof envPort === "number" && Number.isFinite(envPort) ? envPort : 3006)
4250
4276
  const lockServerUrl = lockServerConfigured.url
4251
4277
  || `ws://${lockServerHost || "127.0.0.1"}:${lockServerPort}/websocket`
4278
+ // STC-715: `embedded` runs the lock-server engine in this process, `local`
4279
+ // spawns it as a child over stdio JSON-lines. Both default `enabled` to true
4280
+ // when the mode is named explicitly — no host/port/url required. `external`
4281
+ // (the default) keeps today's rule: enabled only via url/host/port config
4282
+ // or the env pair, so an app that configures nothing is unchanged.
4283
+ const configuredMode = lockServerConfigured.mode
4284
+ const lockServerMode = configuredMode === "embedded" || configuredMode === "local" || configuredMode === "external"
4285
+ ? configuredMode
4286
+ : "external"
4252
4287
 
4253
4288
  return {
4254
4289
  backends: {
@@ -4265,9 +4300,13 @@ export default class VelociousConfiguration {
4265
4300
  connectTimeoutMs: typeof lockServerConfigured.connectTimeoutMs === "number" ? lockServerConfigured.connectTimeoutMs : 3000,
4266
4301
  enabled: typeof lockServerConfigured.enabled === "boolean"
4267
4302
  ? lockServerConfigured.enabled
4268
- : Boolean(lockServerConfigured.url || lockServerConfigured.host || envHost || typeof lockServerConfigured.port === "number" || envPortRaw),
4303
+ : lockServerMode === "external"
4304
+ ? Boolean(lockServerConfigured.url || lockServerConfigured.host || envHost || typeof lockServerConfigured.port === "number" || envPortRaw)
4305
+ : true,
4269
4306
  leaseMs: typeof lockServerConfigured.leaseMs === "number" ? lockServerConfigured.leaseMs : 30_000,
4307
+ mode: lockServerMode,
4270
4308
  reprobeCooldownMs: typeof lockServerConfigured.reprobeCooldownMs === "number" ? lockServerConfigured.reprobeCooldownMs : 5000,
4309
+ socketPath: typeof lockServerConfigured.socketPath === "string" ? lockServerConfigured.socketPath : "",
4271
4310
  url: lockServerUrl
4272
4311
  }
4273
4312
  },
@@ -4337,11 +4376,13 @@ export default class VelociousConfiguration {
4337
4376
  authToken: config.backends.lockServer.authToken,
4338
4377
  connectTimeoutMs: config.backends.lockServer.connectTimeoutMs,
4339
4378
  leaseMs: config.backends.lockServer.leaseMs,
4379
+ mode: config.backends.lockServer.mode,
4340
4380
  onError: (/** @type {Error} */ error) => {
4341
4381
  this.getErrorEvents().emit("framework-error", {context: "advisory-lock-lock-server", error})
4342
4382
  this.getErrorEvents().emit("all-error", {context: "advisory-lock-lock-server", error, errorType: "framework-error"})
4343
4383
  },
4344
4384
  reprobeCooldownMs: config.backends.lockServer.reprobeCooldownMs,
4385
+ socketPath: config.backends.lockServer.socketPath,
4345
4386
  url: config.backends.lockServer.url
4346
4387
  })
4347
4388
 
@@ -1,8 +1,5 @@
1
1
  // @ts-check
2
2
 
3
- import WebSocket from "ws"
4
-
5
- import VelociousWebsocketClient from "../http-client/websocket-client.js"
6
3
  import {AdvisoryLockServiceUnavailableError} from "./advisory-lock-errors.js"
7
4
 
8
5
  /**
@@ -40,6 +37,13 @@ const LOCK_SERVER_CONNECTION_TYPE = "lock"
40
37
  *
41
38
  * Unavailability is cached for `reprobeCooldownMs` so a flapping server cannot
42
39
  * turn every waiting caller into a connection attempt (design §2).
40
+ *
41
+ * The transport is injected through `clientFactory` (STC-715): this module no
42
+ * longer imports `ws` itself, so it is safe for browser/Expo bundles. The Node
43
+ * handler injects the websocket transport for `external` mode, the spawned
44
+ * stdio/UDS client for `local` mode, and the in-process engine client for
45
+ * `embedded` mode — all three speak the same protocol surface through this
46
+ * adapter.
43
47
  */
44
48
  export default class AdvisoryLockLockServerBackend {
45
49
  /**
@@ -47,14 +51,14 @@ export default class AdvisoryLockLockServerBackend {
47
51
  * constructing this object never performs I/O.
48
52
  * @param {object} args - Backend options.
49
53
  * @param {string} [args.authToken] - Shared secret; the server fails closed without a matching token.
50
- * @param {(args: {authToken: string, url: string}) => LockServerClientLike} [args.clientFactory] - Transport factory (tests inject a fake).
54
+ * @param {(args: {authToken: string, url: string}) => LockServerClientLike} args.clientFactory - Transport factory injected by the environment handler (websocket for external mode, spawned child for local mode, in-process engine for embedded mode).
51
55
  * @param {number} [args.connectTimeoutMs] - Handshake timeout.
52
56
  * @param {number} [args.leaseMs] - Lease duration used until the server advertises its own.
53
57
  * @param {(error: Error) => void} [args.onError] - Async error reporter.
54
58
  * @param {number} [args.reprobeCooldownMs] - How long an unavailable server is not re-probed.
55
- * @param {string} args.url - Lock-server websocket URL.
59
+ * @param {string} args.url - Lock-server endpoint (websocket URL for external mode; informational for embedded/local modes).
56
60
  */
57
- constructor({authToken = "", clientFactory = defaultClientFactory, connectTimeoutMs = 3000, leaseMs = 30_000, onError, reprobeCooldownMs = 5000, url}) {
61
+ constructor({authToken = "", clientFactory, connectTimeoutMs = 3000, leaseMs = 30_000, onError, reprobeCooldownMs = 5000, url}) {
58
62
  this.url = url
59
63
  this.authToken = authToken
60
64
  this.clientFactory = clientFactory
@@ -117,6 +121,8 @@ export default class AdvisoryLockLockServerBackend {
117
121
  this.status.lastProbeAt = new Date().toISOString()
118
122
 
119
123
  try {
124
+ if (typeof this.clientFactory !== "function") throw new Error("The lock-server backend requires a clientFactory transport from the environment handler")
125
+
120
126
  const client = this.clientFactory({authToken: this.authToken, url: this.url})
121
127
 
122
128
  this.client = client
@@ -350,6 +356,24 @@ export default class AdvisoryLockLockServerBackend {
350
356
  return
351
357
  }
352
358
 
359
+ // Transport-side death (spawned child exited, embedded engine closed):
360
+ // fail every pending request now and start the re-probe cooldown instead
361
+ // of letting each request burn its own timeout. This is the crash-detection
362
+ // half of the local-mode lifecycle (STC-715); the cooldown is the restart
363
+ // backoff and the next acquisition spawns the child again.
364
+ if (body.type === "response" && body.transportClosed === true) {
365
+ const error = new AdvisoryLockServiceUnavailableError(
366
+ `Lock server ${this.url} transport closed: ${String(body.error || "transport closed")}`,
367
+ {lockName: "", reason: "transport-closed"}
368
+ )
369
+
370
+ this.markUnavailable(error)
371
+ this.teardown()
372
+ this.reportError(error)
373
+
374
+ return
375
+ }
376
+
353
377
  if (body.type === "lost") {
354
378
  const name = String(body.name ?? "")
355
379
  const hold = this.holds.get(name)
@@ -547,21 +571,3 @@ export default class AdvisoryLockLockServerBackend {
547
571
  if (this.onError) this.onError(normalized)
548
572
  }
549
573
  }
550
-
551
- /**
552
- * Default transport factory: the framework websocket client with the Node
553
- * `ws` implementation bound explicitly (no global mutation).
554
- * @param {{authToken: string, url: string}} args - Connection args.
555
- * @returns {LockServerClientLike} - Websocket client.
556
- */
557
- function defaultClientFactory({url}) {
558
- // Node's global WebSocket is not guaranteed to exist, so the implementation is
559
- // bound explicitly instead of mutating `globalThis`.
560
- const webSocketImplementation = /** @type {typeof globalThis.WebSocket} */ (/** @type {unknown} */ (WebSocket))
561
-
562
- return /** @type {LockServerClientLike} */ (/** @type {unknown} */ (new VelociousWebsocketClient({
563
- heartbeatIntervalMs: 10_000,
564
- url,
565
- webSocketImplementation
566
- })))
567
- }
@@ -0,0 +1,74 @@
1
+ // @ts-check
2
+
3
+ import AdvisoryLockLockServerEngine from "./advisory-lock-lock-server-engine.js"
4
+
5
+ /**
6
+ * @typedef {import("./advisory-lock-lock-server-backend.js").LockServerClientLike} LockServerClientLike
7
+ * @typedef {import("./advisory-lock-lock-server-backend.js").LockServerConnectionLike} LockServerConnectionLike
8
+ */
9
+
10
+ /**
11
+ * In-process transport factory for the `embedded` lock-server mode (STC-715).
12
+ * It wires the lock-server backend adapter to an `AdvisoryLockLockServerEngine`
13
+ * living in the same process over plain function calls — no sockets, no `ws`,
14
+ * no Node builtins — so browser/Expo bundles can run the lock-server tier.
15
+ *
16
+ * The engine mints the holder id for the connection exactly like the external
17
+ * daemon does over the websocket transport, so the adapter's lease/epoch/
18
+ * fencing behavior is identical across modes.
19
+ * @param {AdvisoryLockLockServerEngine} engine - Engine this transport connects to.
20
+ * @returns {(args: {authToken: string, url: string}) => LockServerClientLike} - Client factory for the backend adapter.
21
+ */
22
+ export function createEmbeddedLockServerClientFactory(engine) {
23
+ return () => {
24
+ /** @type {string | null} */
25
+ let connectionId = null
26
+ /** @type {((body: Record<string, unknown>) => void) | null} */
27
+ let onMessage = null
28
+
29
+ /** @type {LockServerClientLike} */
30
+ const client = {
31
+ async connect() {},
32
+
33
+ close() {
34
+ if (connectionId !== null) engine.connectionClose(connectionId)
35
+
36
+ connectionId = null
37
+ },
38
+
39
+ openConnection(_type, {onMessage: messageHandler}) {
40
+ onMessage = messageHandler
41
+
42
+ connectionId = engine.openConnection({
43
+ onClose: () => {
44
+ onMessage?.({error: "Embedded lock server engine is closed", status: "transport-closed", transportClosed: true, type: "response"})
45
+ },
46
+ send: (/** @type {Record<string, unknown>} */ body) => messageHandler(body)
47
+ })
48
+
49
+ // The engine answers the connection-open frame with a hello-ack, just
50
+ // like the external daemon does after verifying auth and protocol.
51
+ queueMicrotask(() => messageHandler({leaseMs: engine.leaseMs, protocolVersion: 2, type: "hello-ack"}))
52
+
53
+ /** @type {LockServerConnectionLike} */
54
+ const connection = {
55
+ close: () => {
56
+ if (connectionId !== null) engine.connectionClose(connectionId)
57
+
58
+ connectionId = null
59
+ },
60
+ ready: Promise.resolve(),
61
+ sendMessage: (/** @type {Record<string, unknown>} */ body) => {
62
+ if (connectionId === null) throw new Error("Embedded lock server connection is not open")
63
+
64
+ engine.handleMessage(connectionId, body)
65
+ }
66
+ }
67
+
68
+ return connection
69
+ }
70
+ }
71
+
72
+ return client
73
+ }
74
+ }