velocious 1.0.633 → 1.0.635

package/src/background-jobs/main.js

@@ -602,10 +602,14 @@ export default class BackgroundJobsMain {
    * @returns {Promise<void>} - Activation completion.
    */
   async _activate() {
+    this.logger.info(() => ["Background jobs generation activation starting", {generationId: this.generationId}])
     await this._startActiveOwnership()
     this.lifecycleState = "active"
     this._creditReadyWorkers()
-    await this._drain()
+    this.logger.info(() => ["Background jobs generation activation acknowledged", {generationId: this.generationId}])
+    void this._drain().catch((error) => {
+      this.logger.error(() => ["Background jobs generation post-activation drain failed", {error, generationId: this.generationId}])
+    })
   }
 
   /**
@@ -614,7 +618,7 @@ export default class BackgroundJobsMain {
    */
   retire() {
     if (!this.generationId) throw new Error("Background jobs generation retirement requires generation mode")
-    if (this.lifecycleState === "retiring" || this.lifecycleState === "retired") return this._retirementPromise || Promise.resolve()
+    if (this.lifecycleState === "retiring" || this.lifecycleState === "retired") return Promise.resolve()
     if (this.lifecycleState !== "active") throw new Error(`Cannot retire background jobs generation from ${this.lifecycleState}`)
 
     this.lifecycleState = "retiring"
@@ -624,8 +628,9 @@ export default class BackgroundJobsMain {
     this._clearDispatchTimers()
     this._disconnectBeaconHandlers()
     this._retirementPromise = this._retire()
+    void this._retirementPromise.catch((error) => this._reportConnectionHandlerError(error))
 
-    return this._retirementPromise
+    return Promise.resolve()
   }
 
   /**
@@ -636,6 +641,7 @@ export default class BackgroundJobsMain {
     await this.scheduler?.stop()
     this.scheduler = undefined
     if (this._drainPromise) await this._drainPromise
+    if (this._stopped) return
 
     for (const worker of this.workers) {
       worker.isDraining = true

package/src/cli/commands/db/migrate.js

@@ -1,11 +1,13 @@
 import BaseCommand from "../../base-command.js"
 import {digg} from "diggerize"
 import Migrator from "../../../database/migrator.js"
+import migrationExecutionPhaseArgument from "../../migration-execution-phase-argument.js"
 
 export default class DbMigrate extends BaseCommand {
   async execute() {
+    const executionPhase = migrationExecutionPhaseArgument(this.processArgs || [])
     const migrations = await this.getEnvironmentHandler().findMigrations()
-    const migrator = new Migrator({configuration: this.getConfiguration()})
+    const migrator = new Migrator({configuration: this.getConfiguration(), executionPhase})
 
     console.log(`Running ${migrations.length} migrations`)
 

package/src/cli/commands/db/tenants/migrate.js

@@ -4,6 +4,7 @@ import {digg} from "diggerize"
 import BaseCommand from "../../../base-command.js"
 import Migrator from "../../../../database/migrator.js"
 import TenantDatabaseCommandHelper from "../../../tenant-database-command-helper.js"
+import migrationExecutionPhaseArgument from "../../../migration-execution-phase-argument.js"
 
 export default class DbTenantsMigrate extends BaseCommand {
   /**
@@ -11,6 +12,7 @@ export default class DbTenantsMigrate extends BaseCommand {
    * @returns {Promise<{identifier: string, migrationCount: number, tenantCount: number} | void>} - Result in test mode.
    */
   async execute() {
+    const executionPhase = migrationExecutionPhaseArgument(this.processArgs || [])
     const helper = new TenantDatabaseCommandHelper({
       command: this,
       identifier: this.processArgs?.[1]
@@ -19,7 +21,8 @@ export default class DbTenantsMigrate extends BaseCommand {
     const tenantCount = await helper.eachTenant(async ({databaseConfiguration, tenant}) => {
       const migrator = new Migrator({
         configuration: this.getConfiguration(),
-        databaseIdentifiers: [helper.identifier]
+        databaseIdentifiers: [helper.identifier],
+        executionPhase
       })
 
       let migrationsApplied = 0

package/src/cli/commands/db/tenants/migrations/pending.js

@@ -4,6 +4,8 @@ import {digg} from "diggerize"
 import BaseCommand from "../../../../base-command.js"
 import TenantDatabaseCommandHelper from "../../../../tenant-database-command-helper.js"
 import TenantMigrationPendingInspector from "../../../../../database/tenants/migration-pending-inspector.js"
+import { migrationRunsInExecutionPhase } from "../../../../../database/migration-execution-phase.js"
+import migrationExecutionPhaseArgument from "../../../../migration-execution-phase-argument.js"
 
 export default class DbTenantsMigrationsPending extends BaseCommand {
   /**
@@ -11,6 +13,7 @@ export default class DbTenantsMigrationsPending extends BaseCommand {
    * @returns {Promise<{hasPendingMigrations: boolean, identifier: string, migrationCount: number, pendingTenantCount: number, tenantCount: number}>} - Deploy preflight result.
    */
   async execute() {
+    const executionPhase = migrationExecutionPhaseArgument(this.processArgs || [])
     const helper = new TenantDatabaseCommandHelper({
       command: this,
       identifier: this.processArgs?.[1]
@@ -24,7 +27,7 @@ export default class DbTenantsMigrationsPending extends BaseCommand {
 
       const MigrationClass = await requireMigration(migration.fullPath)
 
-      if ((MigrationClass.getDatabaseIdentifiers() || ["default"]).includes(helper.identifier)) {
+      if (migrationRunsInExecutionPhase(MigrationClass, executionPhase) && (MigrationClass.getDatabaseIdentifiers() || ["default"]).includes(helper.identifier)) {
         applicableMigrationVersions.push(migration.date)
       }
     }

package/src/cli/index.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-const COMMAND_VALUE_OPTIONS = new Set(["--generation", "--initial-generation-state", "--lifecycle-socket", "--socket", "--tenant"])
+const COMMAND_VALUE_OPTIONS = new Set(["--generation", "--initial-generation-state", "--lifecycle-socket", "--phase", "--socket", "--tenant"])
 
 export default class VelociousCli {
   /**

package/src/cli/migration-execution-phase-argument.js

@@ -0,0 +1,20 @@
+// @ts-check
+
+import { migrationExecutionPhase } from "../database/migration-execution-phase.js"
+
+/**
+ * Reads an optional `--phase` value from one command's raw arguments.
+ * @param {string[]} processArgs - Raw command arguments including the command name.
+ * @returns {import("../database/migration-execution-phase.js").MigrationExecutionPhase | undefined} - Selected phase.
+ */
+export default function migrationExecutionPhaseArgument(processArgs) {
+  const phaseArgumentIndex = processArgs.indexOf("--phase")
+
+  if (phaseArgumentIndex < 0) return undefined
+
+  const phase = processArgs[phaseArgumentIndex + 1]
+
+  if (!phase || phase.startsWith("-")) throw new Error("Missing value for --phase")
+
+  return migrationExecutionPhase(phase)
+}

package/src/database/migration/index.js

@@ -28,6 +28,7 @@
 import { convertLegacyDateValueToUtcStorage } from "../datetime-storage.js"
 import * as inflection from "inflection"
 import restArgsError from "../../utils/rest-args-error.js"
+import { DEFAULT_MIGRATION_EXECUTION_PHASE, migrationExecutionPhase } from "../migration-execution-phase.js"
 import ChangeTable from "./change-table.js"
 import CreateIndexBase from "../query/create-index-base.js"
 import TableColumn from "../table-data/table-column.js"
@@ -38,6 +39,26 @@ class NotImplementedError extends Error {}
 export {NotImplementedError}
 
 export default class VelociousDatabaseMigration {
+  /** @type {import("../migration-execution-phase.js").MigrationExecutionPhase | undefined} */
+  static _executionPhase
+
+  /**
+   * Declares when this migration is eligible to run.
+   * @param {import("../migration-execution-phase.js").MigrationExecutionPhase} phase - Execution phase.
+   * @returns {void} - No return value.
+   */
+  static runInPhase(phase) {
+    this._executionPhase = migrationExecutionPhase(phase)
+  }
+
+  /**
+   * Gets the declared execution phase.
+   * @returns {import("../migration-execution-phase.js").MigrationExecutionPhase} - Declared execution phase.
+   */
+  static getExecutionPhase() {
+    return this._executionPhase || DEFAULT_MIGRATION_EXECUTION_PHASE
+  }
+
   /**
    * Runs on databases.
    * @param {string[]} databaseIdentifiers - Database identifiers.

package/src/database/migration-execution-phase.js

@@ -0,0 +1,34 @@
+// @ts-check
+
+/** @typedef {"post-publication" | "pre-runtime"} MigrationExecutionPhase */
+
+/** @type {MigrationExecutionPhase} */
+export const DEFAULT_MIGRATION_EXECUTION_PHASE = "pre-runtime"
+
+/**
+ * Validates and returns one supported migration execution phase.
+ * @param {string | undefined} phase - Migration execution phase.
+ * @returns {MigrationExecutionPhase} - Validated execution phase.
+ */
+export function migrationExecutionPhase(phase) {
+  if (phase === undefined) {
+    throw new Error("Missing migration execution phase. Expected one of: pre-runtime, post-publication")
+  }
+  if (phase !== "pre-runtime" && phase !== "post-publication") {
+    throw new Error(`Unknown migration execution phase ${JSON.stringify(phase)}. Expected one of: pre-runtime, post-publication`)
+  }
+
+  return phase
+}
+
+/**
+ * Tests whether a migration class belongs to an optional selected phase.
+ * @param {typeof import("./migration/index.js").default} MigrationClass - Migration class.
+ * @param {MigrationExecutionPhase | undefined} executionPhase - Optional selected phase.
+ * @returns {boolean} - Whether the migration belongs to the selection.
+ */
+export function migrationRunsInExecutionPhase(MigrationClass, executionPhase) {
+  if (executionPhase === undefined) return true
+
+  return MigrationClass.getExecutionPhase() === executionPhase
+}

package/src/database/migrator.js

@@ -5,6 +5,7 @@ import * as inflection from "inflection"
 import Logger from "../logger.js"
 import MigrationsLedger from "./migrations-ledger.js"
 import {NotImplementedError} from "./migration/index.js"
+import { migrationExecutionPhase, migrationRunsInExecutionPhase } from "./migration-execution-phase.js"
 import restArgsError from "../utils/rest-args-error.js"
 
 export default class VelociousDatabaseMigrator {
@@ -18,14 +19,16 @@ export default class VelociousDatabaseMigrator {
    * @param {object} args - Options object.
    * @param {import("../configuration.js").default} args.configuration - Configuration instance.
    * @param {string[]} [args.databaseIdentifiers] - Optional database identifiers to migrate.
+   * @param {import("./migration-execution-phase.js").MigrationExecutionPhase} [args.executionPhase] - Optional migration execution phase to select.
    */
-  constructor({configuration, databaseIdentifiers, ...restArgs}) {
+  constructor({configuration, databaseIdentifiers, executionPhase, ...restArgs}) {
     restArgsError(restArgs)
 
     if (!configuration) throw new Error("configuration argument is required")
 
     this.configuration = configuration
     this.databaseIdentifiers = databaseIdentifiers
+    this.executionPhase = executionPhase === undefined ? undefined : migrationExecutionPhase(executionPhase)
     this.logger = new Logger(this)
   }
 
@@ -188,6 +191,7 @@ export default class VelociousDatabaseMigrator {
       if (!MigrationClass || typeof MigrationClass !== "function") {
         throw new Error(`Migration ${migration.file} must export a default migration class. Type: ${typeof MigrationClass}`)
       }
+      if (!migrationRunsInExecutionPhase(MigrationClass, this.executionPhase)) continue
       if (!(MigrationClass.getDatabaseIdentifiers() || ["default"]).includes(databaseIdentifier)) continue
 
       const migrationInstance = new MigrationClass({configuration: this.configuration, databaseIdentifier, db})
@@ -519,6 +523,7 @@ export default class VelociousDatabaseMigrator {
     if (!migrationClass || typeof migrationClass !== "function") {
       throw new Error(`Migration ${migration.file} must export a default migration class. Type: ${typeof migrationClass}`)
     }
+    if (direction == "up" && !migrationRunsInExecutionPhase(migrationClass, this.executionPhase)) return false
 
     const migrationDatabaseIdentifiers = migrationClass.getDatabaseIdentifiers() || ["default"]