velocious 1.0.580 → 1.0.582

package/README.md

@@ -8,6 +8,7 @@
 * Built-in record auditing for model lifecycle changes (see [docs/auditing.md](docs/auditing.md))
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
 * Migrations for schema changes and UTC datetime storage (see [docs/database-migrations.md](docs/database-migrations.md))
+* Tenant-selected base-model and structure generation with one immutable, fail-closed physical database context; tenant-only model metadata initializes only after that context is active (see [docs/tenant-selected-database-generation.md](docs/tenant-selected-database-generation.md))
 * External packages (engines) that contribute data models, frontend-model resources and migrations to a consuming app (see [docs/packages.md](docs/packages.md))
 * Optional Rampway-owned durable deployment control plane mounted through the standard routes DSL on Velocious 1.0.577 or newer (see [docs/rampway-integration.md](docs/rampway-integration.md))
 * Controllers and views for HTTP endpoints
@@ -289,10 +290,26 @@ npx velocious test --groups=4 --group-number=2
 
 # Combine with tags
 npx velocious test --groups=3 --group-number=1 --tag fast
+
+# Prefer recorded file durations when balancing groups
+npx velocious test --groups=4 --group-number=1 --timing-manifest=tmp/test-timings.json
 ```
 
 Files are distributed using a greedy load-balancing algorithm. Each file is
-weighted by its spec directory (`system/` = 20, `frontend-models/` = 10,
+primarily weighted by a positive finite duration from the optional timing
+manifest. Manifest keys are normalized project-relative test paths using `/`
+separators:
+
+```json
+{
+  "spec/system/sign-in-spec.js": 42.7,
+  "spec/controller/accounts-spec.js": 8.1
+}
+```
+
+Files absent from the manifest, unknown files, invalid duration values, and
+unreadable or malformed JSON all fall back to the existing deterministic
+heuristic. The heuristic weights files by spec directory (`system/` = 20, `frontend-models/` = 10,
 `controller/` = 3, default = 1) with a 2x multiplier for `.browser-spec.js`
 files. The heaviest files are assigned first to the group with the least
 accumulated weight, producing balanced wall-clock times across groups.

package/build/cli/command-arguments.js

@@ -0,0 +1,45 @@
+// @ts-check
+
+/**
+ * @typedef {object} CommandArgumentDefinition
+ * @property {string[]} [booleanOptions] - Flags that do not accept a value.
+ * @property {string[]} [valueOptions] - Flags that require one value.
+ */
+
+/**
+ * Parses and validates one command's arguments.
+ * @param {object} args - Parser arguments.
+ * @param {CommandArgumentDefinition} args.definition - Accepted command options.
+ * @param {string[]} args.processArgs - Raw command arguments including the command name.
+ * @returns {Record<string, string | boolean>} - Values keyed by long option name without `--`.
+ */
+export default function commandArguments({definition, processArgs}) {
+  const commandName = processArgs[0] || "command"
+  const booleanOptions = new Set(definition.booleanOptions || [])
+  const valueOptions = new Set(definition.valueOptions || [])
+  /** @type {Record<string, string | boolean>} */
+  const parsed = {}
+
+  for (let index = 1; index < processArgs.length; index++) {
+    const argument = processArgs[index]
+
+    if (booleanOptions.has(argument)) {
+      parsed[argument.slice(2)] = true
+      continue
+    }
+
+    if (valueOptions.has(argument)) {
+      const value = processArgs[index + 1]
+
+      if (!value || value.startsWith("-")) throw new Error(`Missing value for ${argument}`)
+
+      parsed[argument.slice(2)] = value
+      index++
+      continue
+    }
+
+    throw new Error(`Unknown argument for ${commandName}: ${argument}`)
+  }
+
+  return parsed
+}

package/build/cli/index.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+const COMMAND_VALUE_OPTIONS = new Set(["--tenant"])
+
 export default class VelociousCli {
   /**
    * Runs constructor.
@@ -94,6 +96,7 @@ export default class VelociousCli {
      * Current group.
      * @type {string[]} */
     let currentGroup = []
+    let expectsOptionValue = false
 
     for (const processArg of processArgs) {
       if (currentGroup.length == 0) {
@@ -103,11 +106,18 @@ export default class VelociousCli {
         continue
       }
 
+      if (expectsOptionValue) {
+        currentGroup.push(processArg)
+        expectsOptionValue = false
+        continue
+      }
+
       if (!processArg.startsWith("-") && commandNames.has(processArg)) {
         groups.push(currentGroup)
         currentGroup = [processArg]
       } else {
         currentGroup.push(processArg)
+        expectsOptionValue = COMMAND_VALUE_OPTIONS.has(processArg)
       }
     }
 

package/build/configuration-types.js

@@ -661,6 +661,7 @@
 /**
  * @typedef {object} TenantDatabaseProviderType
  * @property {(args: {configuration: import("./configuration.js").default, identifier: string}) => Array<ReturnType<typeof JSON.parse>> | Promise<Array<ReturnType<typeof JSON.parse>>>} listTenants - Lists tenants that should be created, checked, or migrated for this database identifier.
+ * @property {(args: {configuration: import("./configuration.js").default, identifier: string}) => ReturnType<typeof JSON.parse> | void | Promise<ReturnType<typeof JSON.parse> | void>} [resolveGenerationTenant] - Resolves one explicit tenant descriptor for schema/base-model generation without enumerating lifecycle tenants.
  * @property {(args: {configuration: import("./configuration.js").default, identifier: string}) => Array<ReturnType<typeof JSON.parse>> | Promise<Array<ReturnType<typeof JSON.parse>>>} [listRestrictTenants] - Lists existing tenants that should be checked for dependent restrict destroys. Defaults to listTenants.
  * @property {(args: {configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ReturnType<typeof JSON.parse>}) => void | Promise<void>} [createDatabase] - Creates the tenant database/schema for one tenant.
  * @property {(args: {configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ReturnType<typeof JSON.parse>}) => void | Promise<void>} [dropDatabase] - Drops the tenant database/schema for one tenant.

package/build/database/drivers/base.js

@@ -118,6 +118,14 @@
  * @property {string[]} updateColumns - Columns to update on conflict.
  */
 
+/**
+ * SqlTokenResult type.
+ * @typedef {object} SqlTokenResult
+ * @property {boolean} incomplete - Whether the scan hit its bound before finishing trivia/token parsing.
+ * @property {string | undefined} token - Lowercased token when parsing completed; undefined when no token was found.
+ * @property {number} index - Index immediately after the parsed token or trivia.
+ */
+
 import BacktraceCleaner from "../../utils/backtrace-cleaner.js"
 import { getDatabaseAnnotations } from "../annotations.js"
 import { formatDateForDatabase } from "../datetime-storage.js"
@@ -134,6 +142,11 @@ import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/build/wait.js"
 import {optionalPositiveInteger} from "typanic"
 
+/** Maximum characters inspected when building the debug SQL preview. */
+const SQL_PREVIEW_SCAN_LIMIT = 4096
+/** Maximum characters inspected when deciding whether a statement invalidates schema metadata. */
+const SCHEMA_INVALIDATION_SCAN_LIMIT = 8192
+
 /**
  * Marks a callback failure that happened after the owning transaction was durably committed.
  * The public transaction boundary unwraps it before deadlock classification.
@@ -1604,13 +1617,25 @@ export default class VelociousDatabaseDriversBase {
     }
   }
 
+  /**
+   * Returns a bounded prefix of `sql` for lightweight diagnostic scanning.
+   * @param {string} sql - SQL string.
+   * @param {number} limit - Maximum code units to inspect.
+   * @returns {string} - Prefix of `sql`.
+   */
+  _diagnosticSqlPrefix(sql, limit) {
+    return sql.length <= limit ? sql : sql.slice(0, limit)
+  }
+
   /**
    * Runs debug sql preview.
    * @param {string} sql - SQL to preview.
    * @returns {string} - Normalized truncated SQL preview for diagnostics.
    */
   _debugSqlPreview(sql) {
-    return sql
+    const prefix = this._diagnosticSqlPrefix(sql, SQL_PREVIEW_SCAN_LIMIT)
+
+    return prefix
       .replace(/\s+/g, " ")
       .trim()
       .slice(0, 500)
@@ -1664,25 +1689,121 @@ export default class VelociousDatabaseDriversBase {
       .replace(/"/g, "'")
   }
 
+  /**
+   * Reads the next SQL token starting at `startIndex`, skipping leading trivia
+   * (BOM, whitespace, block comments, line comments). If the scan cannot finish
+   * skipping trivia before `limit`, the result is marked incomplete so callers
+   * can conservatively treat the statement as schema-invalidating.
+   * @param {string} sql - SQL string.
+   * @param {number} startIndex - Index to start scanning.
+   * @param {number} limit - Maximum absolute index to scan while skipping leading trivia.
+   * @returns {SqlTokenResult} - Token result.
+   */
+  _readSqlToken(sql, startIndex, limit) {
+    let i = startIndex
+    const len = sql.length
+
+    while (i < len && i < limit) {
+      const char = sql[i]
+
+      if (char === "\ufeff" || /\s/.test(char)) {
+        i++
+        continue
+      }
+
+      if (char === "/" && sql[i + 1] === "*") {
+        const close = sql.indexOf("*/", i + 2)
+
+        if (close === -1 || close + 2 > limit) {
+          return {incomplete: true, index: i, token: undefined}
+        }
+
+        i = close + 2
+        continue
+      }
+
+      if (char === "-" && sql[i + 1] === "-") {
+        const newline = sql.indexOf("\n", i + 2)
+
+        if (newline === -1) {
+          return {incomplete: false, index: len, token: undefined}
+        }
+
+        if (newline + 1 > limit) {
+          return {incomplete: true, index: i, token: undefined}
+        }
+
+        i = newline + 1
+        continue
+      }
+
+      let token = ""
+
+      while (i < len) {
+        const c = sql[i]
+
+        if (/\s/.test(c) || c === "\ufeff") break
+        if (c === "/" && sql[i + 1] === "*") break
+        if (c === "-" && sql[i + 1] === "-") break
+
+        token += c
+        i++
+      }
+
+      return {incomplete: false, token: token.toLowerCase(), index: i}
+    }
+
+    if (i >= len) {
+      return {incomplete: false, index: len, token: undefined}
+    }
+
+    return {incomplete: true, index: i, token: undefined}
+  }
+
   /**
    * Runs schema cache invalidating sql.
    * @param {string} sql - SQL string.
    * @returns {boolean} - Whether the SQL should invalidate schema metadata.
    */
   _schemaCacheInvalidatingSql(sql) {
-    const normalized = sql
-      .trim()
-      .replace(/^\ufeff/, "")
-      .replace(/\/\*[\s\S]*?\*\//g, " ")
-      .replace(/--[^\n]*(\n|$)/g, " ")
-      .replace(/\s+/g, " ")
-      .toLowerCase()
+    const first = this._readSqlToken(sql, 0, SCHEMA_INVALIDATION_SCAN_LIMIT)
 
-    if (!normalized) return false
-    if (/^(create|alter|drop|rename)\b/.test(normalized)) return true
-    if (/^comment\s+on\b/.test(normalized)) return true
-    if (/^exec(?:ute)?\s+sp_rename\b/.test(normalized)) return true
-    if (/^if\b[\s\S]*\bbegin\s+(create|alter|drop|rename)\b/.test(normalized)) return true
+    if (first.incomplete) return true
+
+    const firstToken = first.token
+
+    if (!firstToken) return false
+    if (/^(create|alter|drop|rename)$/.test(firstToken)) return true
+
+    if (firstToken === "comment") {
+      const next = this._readSqlToken(sql, first.index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+      return next.incomplete || next.token === "on"
+    }
+
+    if (firstToken === "exec" || firstToken === "execute") {
+      const next = this._readSqlToken(sql, first.index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+      return next.incomplete || next.token === "sp_rename"
+    }
+
+    if (firstToken === "if") {
+      let index = first.index
+
+      while (true) {
+        const result = this._readSqlToken(sql, index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+        if (result.incomplete) return true
+        if (!result.token) return false
+        if (result.token === "begin") {
+          const ddlResult = this._readSqlToken(sql, result.index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+          return ddlResult.incomplete || /^(create|alter|drop|rename)$/.test(ddlResult.token || "")
+        }
+
+        index = result.index
+      }
+    }
 
     return false
   }

package/build/database/generation-context.js

@@ -0,0 +1,121 @@
+// @ts-check
+
+import Tenant from "../tenants/tenant.js"
+
+/**
+ * Immutable selection of one logical tenant database and one provider-resolved
+ * physical tenant. Schema tools can share this contract without ambient or
+ * process-global selection state.
+ */
+export default class DatabaseGenerationContext {
+  /**
+   * Resolves one tenant-only database from its provider and captures its physical identity.
+   * @param {object} args - Selection arguments.
+   * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+   * @param {string} args.databaseIdentifier - Logical tenant-only database identifier.
+   * @returns {Promise<DatabaseGenerationContext>} - Immutable selected database context.
+   */
+  static async resolve({configuration, databaseIdentifier}) {
+    const databaseConfiguration = configuration.getDatabaseConfiguration()[databaseIdentifier]
+
+    if (!databaseConfiguration) {
+      throw new Error(`No such tenant database identifier configured: ${databaseIdentifier}`)
+    }
+    if (!databaseConfiguration.tenantOnly) {
+      throw new Error(`Database identifier ${databaseIdentifier} is not configured with tenantOnly: true`)
+    }
+    if (configuration.getDisabledDatabaseIdentifiers().has(databaseIdentifier)) {
+      throw new Error(`Tenant database identifier ${databaseIdentifier} is disabled by VELOCIOUS_DISABLED_DATABASE_IDENTIFIERS`)
+    }
+
+    const provider = configuration.getTenantDatabaseProvider(databaseIdentifier)
+
+    await configuration.initialize({type: "database-generation"})
+
+    const tenants = await configuration.ensureConnections({name: `Resolve database generation context: ${databaseIdentifier}`}, async () => {
+      if (provider.resolveGenerationTenant) {
+        const tenant = await provider.resolveGenerationTenant({configuration, identifier: databaseIdentifier})
+
+        return tenant === undefined ? [] : [tenant]
+      }
+
+      return await provider.listTenants({configuration, identifier: databaseIdentifier})
+    })
+
+    if (!Array.isArray(tenants)) {
+      throw new Error(`Tenant database provider for ${databaseIdentifier} must return an array from listTenants`)
+    }
+    if (tenants.length === 0) {
+      throw new Error(`Tenant database selection ${databaseIdentifier} resolved no tenants`)
+    }
+    if (tenants.length !== 1) {
+      throw new Error(`Tenant database selection ${databaseIdentifier} is ambiguous: provider returned ${tenants.length} tenants`)
+    }
+
+    const tenant = tenants[0]
+
+    if (!tenant || typeof tenant !== "object" || Array.isArray(tenant)) {
+      throw new Error(`Tenant database selection ${databaseIdentifier} returned an invalid tenant descriptor`)
+    }
+
+    const handle = Tenant.handle(tenant, configuration)
+
+    // Resolve now so an inactive/stale descriptor fails before a selected
+    // schema connection can be checked out or read.
+    handle.databaseConfiguration(databaseIdentifier)
+
+    return new DatabaseGenerationContext({configuration, databaseIdentifier, handle})
+  }
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Captured selection.
+   * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+   * @param {string} args.databaseIdentifier - Logical database identifier.
+   * @param {ReturnType<typeof Tenant.handle>} args.handle - Captured tenant handle.
+   */
+  constructor({configuration, databaseIdentifier, handle}) {
+    this._configuration = configuration
+    this._databaseIdentifier = databaseIdentifier
+    this._handle = handle
+
+    Object.freeze(this)
+  }
+
+  /**
+   * Returns the captured logical database identifier.
+   * @returns {string} - Captured logical database identifier.
+   */
+  databaseIdentifier() { return this._databaseIdentifier }
+
+  /**
+   * Returns the captured physical database configuration.
+   * @returns {import("../configuration-types.js").DatabaseConfigurationType} - Captured physical database configuration.
+   */
+  databaseConfiguration() { return this._handle.databaseConfiguration(this._databaseIdentifier) }
+
+  /**
+   * Returns the captured tenant descriptor.
+   * @returns {ReturnType<ReturnType<typeof Tenant.handle>["tenant"]>} - Captured immutable tenant descriptor.
+   */
+  tenant() { return this._handle.tenant() }
+
+  /**
+   * Runs work on one connection pinned to the captured physical database.
+   * @template T
+   * @param {object} args - Work arguments.
+   * @param {(connection: import("./drivers/base.js").default) => Promise<T>} args.callback - Selected database work.
+   * @param {string} args.name - Checkout name.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async run({callback, name}) {
+    return await this._configuration.runWithTenant(this.tenant(), async () => {
+      return await this._configuration.withDatabaseOperation({
+        databaseConfiguration: this.databaseConfiguration(),
+        databaseIdentifier: this.databaseIdentifier(),
+        name,
+        tenant: this.tenant()
+      }, async (operation) => await callback(operation.connection()))
+    })
+  }
+}

package/build/database/initializer-from-require-context.js

@@ -43,6 +43,13 @@ export default class VelociousDatabaseInitializerFromRequireContext {
 
       if (!modelClass) throw new Error(`Model wasn't exported from: ${fileName}`)
 
+      const configuredDatabase = configuration.getDatabaseConfiguration()[modelClass.getConfiguredDatabaseIdentifier()]
+
+      if (configuredDatabase?.tenantOnly && !configuration.isDatabaseIdentifierActive(modelClass.getConfiguredDatabaseIdentifier())) {
+        modelClass.registerRecordClass({configuration})
+        continue
+      }
+
       if (!modelClass.getEagerLoadRecordMetadata()) {
         modelClass.registerRecordClass({configuration})
         await this._bestEffortInitializeDeferredModel({configuration, modelClass})

package/build/environment-handlers/node/cli/commands/db/schema/dump.js

@@ -1,4 +1,6 @@
 import BaseCommand from "../../../../../../cli/base-command.js"
+import commandArguments from "../../../../../../cli/command-arguments.js"
+import DatabaseGenerationContext from "../../../../../../database/generation-context.js"
 import fileExists from "../../../../../../utils/file-exists.js"
 import path from "path"
 
@@ -8,6 +10,29 @@ export default class DbSchemaDump extends BaseCommand {
    * Runs execute.
    * @returns {Promise<void>} */
   async execute() {
+    const parsedArguments = commandArguments({
+      definition: {valueOptions: ["--tenant"]},
+      processArgs: this.processArgs || []
+    })
+    const tenantDatabaseIdentifier = parsedArguments.tenant
+
+    if (typeof tenantDatabaseIdentifier === "string") {
+      const context = await DatabaseGenerationContext.resolve({
+        configuration: this.getConfiguration(),
+        databaseIdentifier: tenantDatabaseIdentifier
+      })
+
+      await context.run({name: "DB selected tenant schema dump", callback: async (db) => {
+        const dbs = {[context.databaseIdentifier()]: db}
+        const shouldGenerate = await this.shouldGenerateStructureSql({dbs})
+
+        if (!shouldGenerate) return
+
+        await this.getEnvironmentHandler().afterMigrations({dbs, reason: "schemaDump"})
+      }})
+      return
+    }
+
     await this.getConfiguration().ensureConnections({name: "DB schema dump"}, async (dbs) => {
       const shouldGenerate = await this.shouldGenerateStructureSql({dbs})
 

package/build/environment-handlers/node/cli/commands/db/schema/load.js

@@ -1,4 +1,6 @@
 import BaseCommand from "../../../../../../cli/base-command.js"
+import commandArguments from "../../../../../../cli/command-arguments.js"
+import DatabaseGenerationContext from "../../../../../../database/generation-context.js"
 import fs from "fs/promises"
 import path from "path"
 import StructureSqlLoader from "../../../../../../database/structure-sql-loader.js"
@@ -9,17 +11,44 @@ export default class DbSchemaLoad extends BaseCommand {
    * Runs execute.
    * @returns {Promise<void>} */
   async execute() {
-    await this.getConfiguration().ensureConnections({name: "DB schema load"}, async (dbs) => {
-      const dbDir = path.join(this.directory(), "db")
-      const loader = new StructureSqlLoader()
+    const parsedArguments = commandArguments({
+      definition: {valueOptions: ["--tenant"]},
+      processArgs: this.processArgs || []
+    })
+    const tenantDatabaseIdentifier = parsedArguments.tenant
 
-      for (const identifier of Object.keys(dbs)) {
-        const db = dbs[identifier]
-        const structureFilePath = path.join(dbDir, `structure-${identifier}.sql`)
-        const structureSql = await fs.readFile(structureFilePath, "utf8")
+    if (typeof tenantDatabaseIdentifier === "string") {
+      const context = await DatabaseGenerationContext.resolve({
+        configuration: this.getConfiguration(),
+        databaseIdentifier: tenantDatabaseIdentifier
+      })
 
-        await loader.load({db, structureSql})
+      await context.run({name: "DB selected tenant schema load", callback: async (db) => {
+        await this.loadStructureSql({db, identifier: context.databaseIdentifier()})
+      }})
+      return
+    }
+
+    await this.getConfiguration().ensureConnections({name: "DB schema load"}, async (dbs) => {
+      for (const identifier of Object.keys(dbs)) {
+        await this.loadStructureSql({db: dbs[identifier], identifier})
       }
     })
   }
+
+  /**
+   * Loads one identifier's explicit structure file into one selected connection.
+   * @param {object} args - Load arguments.
+   * @param {import("../../../../../../database/drivers/base.js").default} args.db - Target connection.
+   * @param {string} args.identifier - Logical database identifier used in the file name.
+   * @returns {Promise<void>} - Resolves after loading.
+   */
+  async loadStructureSql({db, identifier}) {
+    const dbDir = path.join(this.directory(), "db")
+    const loader = new StructureSqlLoader()
+    const structureFilePath = path.join(dbDir, `structure-${identifier}.sql`)
+    const structureSql = await fs.readFile(structureFilePath, "utf8")
+
+    await loader.load({db, structureSql})
+  }
 }