velocious 1.0.431 → 1.0.433

package/build/beacon/types.js

@@ -0,0 +1,55 @@
+// @ts-check
+
+/**
+ * Wire-message typedefs for the Beacon broadcast bus.
+ *
+ * Beacon is Velocious's cross-process pub/sub bus. The daemon
+ * (`velocious beacon`) accepts JsonSocket connections from any number
+ * of peer processes (HTTP server, background-jobs main, background-jobs
+ * worker, etc.) and fans every `broadcast` message out to every
+ * connected peer — including the sender, so each process can deliver
+ * to its local websocket subscribers via a single code path.
+ */
+
+/**
+ * @typedef {"client"} BeaconSocketRole
+ *
+ * Beacon currently only has one role. The role field is kept on the
+ * `hello` handshake so future roles (e.g. an admin/inspector role) can
+ * be added without bumping the wire format.
+ */
+
+/**
+ * @typedef {{type: "hello", role: BeaconSocketRole, peerId: string, peerType?: string}} BeaconHelloMessage
+ *
+ * `peerId` uniquely identifies the connecting process for echo
+ * suppression and logging. `peerType` is an optional human-readable
+ * label such as `"server"`, `"background-jobs-worker"` — informational
+ * only.
+ */
+
+/**
+ * @typedef {{type: "hello-ack", peerId: string}} BeaconHelloAckMessage
+ *
+ * Sent by the daemon after it has registered the peer. Clients can use
+ * this as a deterministic readiness boundary before publishing events
+ * that must not fall back to local-only delivery.
+ */
+
+/**
+ * @typedef {{type: "broadcast", channel: string, broadcastParams: Record<string, ?>, body: ?, originPeerId?: string}} BeaconBroadcastMessage
+ *
+ * `channel`, `broadcastParams`, and `body` mirror the
+ * `configuration.broadcastToChannel(channel, broadcastParams, body)`
+ * arguments. `originPeerId` is stamped by the publishing client and
+ * preserved through the daemon so receivers can choose to skip echoes
+ * of their own broadcasts (the default Configuration integration does
+ * not skip — synapse-style fan-out always returns to sender so every
+ * peer follows the same delivery path).
+ */
+
+/**
+ * @typedef {BeaconHelloMessage | BeaconHelloAckMessage | BeaconBroadcastMessage} BeaconSocketMessage
+ */
+
+export const nothing = {}

package/build/cli/base-command.js

@@ -0,0 +1,67 @@
+import restArgsError from "../utils/rest-args-error.js"
+
+/**
+ * VelociousCliCommandArgs type.
+ * @typedef {object} VelociousCliCommandArgs
+ * @property {import("../configuration.js").default} [configuration] - Configuration instance for the CLI.
+ * @property {Record<string, string | number | boolean | undefined>} [parsedProcessArgs] - Parsed CLI arguments.
+ * @property {string[]} [processArgs] - Raw CLI arguments array.
+ * @property {boolean} [testing] - Whether the CLI is running in test mode.
+ */
+
+export default class VelociousCliBaseCommand {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {VelociousCliCommandArgs} args.args - Options object.
+   * @param {import("./index.js").default} args.cli - Cli.
+   */
+  constructor({args = {}, cli, ...restArgs}) {
+    restArgsError(restArgs)
+
+    if (!args.configuration) throw new Error("configuration argument is required")
+
+    this.args = args
+    this.cli = cli
+    this._configuration = args.configuration
+    this._environmentHandler = args.configuration.getEnvironmentHandler()
+    this.processArgs = args.processArgs
+  }
+
+  /**
+   * Runs directory.
+   * @returns {string} - The directory.
+   */
+  directory() { return this.getConfiguration().getDirectory() }
+
+  /**
+   * Runs execute.
+   * @abstract
+   * @returns {Promise<?>} - Resolves with the execute.
+   */
+  execute() {
+    throw new Error("execute not implemented")
+  }
+
+  /**
+   * Runs get configuration.
+   * @returns {import("../configuration.js").default} - The configuration.
+   */
+  getConfiguration() { return this._configuration }
+
+  /**
+   * Runs get environment handler.
+   * @returns {import("../environment-handlers/base.js").default} - The environment handler.
+   */
+  getEnvironmentHandler() { return this._environmentHandler }
+
+  /**
+   * Runs initialize.
+   * @abstract
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async initialize() {
+    // Do nothing
+  }
+}
+

package/build/cli/browser-cli.js

@@ -0,0 +1,45 @@
+import Cli from "./index.js"
+import restArgsError from "../utils/rest-args-error.js"
+
+export default class VelociousBrowserCli {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../configuration.js").default} args.configuration - Configuration instance.
+   */
+  constructor({configuration, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this.configuration = configuration
+  }
+
+  /**
+   * Runs enable.
+   * @description Enable the CLI in the global scope. This is useful for debugging and testing.
+   * @returns {void} - No return value.
+   */
+  enable() {
+    /**
+     * Global scope.
+      @type {typeof globalThis & {velociousCLI?: VelociousBrowserCli}} */
+    const globalScope = globalThis
+
+    globalScope.velociousCLI = this
+  }
+
+  /**
+   * Runs run.
+   * @description Run a command. This is useful for debugging and testing. This is a wrapper around the Cli class.
+   * @param {string} command - Command.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async run(command) {
+    const processArgs = command.split(/\s+/)
+    const cli = new Cli({
+      configuration: this.configuration,
+      processArgs
+    })
+
+    await cli.execute()
+  }
+}

package/build/cli/commands/background-jobs-main.js

@@ -0,0 +1,7 @@
+import BaseCommand from "../base-command.js"
+
+export default class BackgroundJobsMainCommand extends BaseCommand {
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsBackgroundJobsMain(this)
+  }
+}

package/build/cli/commands/background-jobs-runner.js

@@ -0,0 +1,7 @@
+import BaseCommand from "../base-command.js"
+
+export default class BackgroundJobsRunnerCommand extends BaseCommand {
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsBackgroundJobsRunner(this)
+  }
+}

package/build/cli/commands/background-jobs-worker.js

@@ -0,0 +1,7 @@
+import BaseCommand from "../base-command.js"
+
+export default class BackgroundJobsWorkerCommand extends BaseCommand {
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsBackgroundJobsWorker(this)
+  }
+}

package/build/cli/commands/beacon.js

@@ -0,0 +1,7 @@
+import BaseCommand from "../base-command.js"
+
+export default class BeaconCommand extends BaseCommand {
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsBeacon(this)
+  }
+}

package/build/cli/commands/console.js

@@ -0,0 +1,12 @@
+import BaseCommand from "../base-command.js"
+
+/** Velocious console command. */
+export default class VelociousCliCommandsConsole extends BaseCommand{
+  /**
+   * Runs execute.
+   * @returns {Promise<?>} - Resolves with the command result.
+   */
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsConsole(this)
+  }
+}

package/build/cli/commands/db/base-command.js

@@ -0,0 +1,82 @@
+import BaseCommand from "../../base-command.js"
+import {digg} from "diggerize"
+
+export default class DbBaseCommand extends BaseCommand {
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {import("../../../database/drivers/base.js").default | undefined} */
+  databaseConnection
+
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {Array<object> | undefined} */
+  result
+
+  /**
+   * Runs with direct database connection.
+   * @param {object} driverConfiguration - Driver configuration.
+   * @param {() => Promise<void>} callback - Callback to run while the connection is open.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async withDirectDatabaseConnection(driverConfiguration, callback) {
+    const DriverClass = digg(driverConfiguration, "driver")
+    const databaseConnection = new DriverClass(driverConfiguration, this.getConfiguration())
+    this.databaseConnection = databaseConnection
+
+    try {
+      await databaseConnection.connect()
+      await callback()
+    } finally {
+      await databaseConnection.close()
+    }
+  }
+
+  /**
+   * Runs get database connection.
+   * @returns {import("../../../database/drivers/base.js").default} - Active database connection.
+   */
+  getDatabaseConnection() {
+    if (!this.databaseConnection) throw new Error("Database connection was not initialized")
+
+    return this.databaseConnection
+  }
+
+  /**
+   * Runs query or collect sqls.
+   * @param {string[]} sqls - SQL statements.
+   * @param {(sql: string) => object} resultEntryForSql - Test result entry builder.
+   * @returns {Promise<void>} - Resolves when SQLs have been collected or executed.
+   */
+  async queryOrCollectSqls(sqls, resultEntryForSql) {
+    if (this.args.testing) {
+      this.collectSqlResults(sqls, resultEntryForSql)
+    } else {
+      await this.querySqls(sqls)
+    }
+  }
+
+  /**
+   * Runs collect sql results.
+   * @param {string[]} sqls - SQL statements.
+   * @param {(sql: string) => object} resultEntryForSql - Test result entry builder.
+   * @returns {void}
+   */
+  collectSqlResults(sqls, resultEntryForSql) {
+    if (!this.result) throw new Error("Expected test result collection to be initialized")
+
+    for (const sql of sqls) {
+      this.result.push(resultEntryForSql(sql))
+    }
+  }
+
+  /**
+   * Runs query sqls.
+   * @param {string[]} sqls - SQL statements.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async querySqls(sqls) {
+    for (const sql of sqls) {
+      await this.getDatabaseConnection().query(sql)
+    }
+  }
+}

package/build/cli/commands/db/create.js

@@ -0,0 +1,64 @@
+import DbBaseCommand from "./base-command.js"
+import {digg} from "diggerize"
+import {incorporate} from "incorporator"
+import TableData from "../../../database/table-data/index.js"
+
+export default class DbCreate extends DbBaseCommand{
+  /**
+   * Runs execute.
+   * @returns {Promise<void | Array<object>>} - Resolves with SQL statements when running in dry mode.
+   */
+  async execute() {
+    for (const databaseIdentifier of this.getConfiguration().getDatabaseIdentifiers()) {
+      const databaseType = this.getConfiguration().getDatabaseType(databaseIdentifier)
+      const databasePool = this.getConfiguration().getDatabasePool(databaseIdentifier)
+      const newConfiguration = incorporate({}, databasePool.getConfiguration())
+
+      if (this.args.testing) this.result = []
+
+      // Use a database known to exist. Since we are creating the database, it shouldn't actually exist which would make connecting fail.
+      newConfiguration.database = newConfiguration.useDatabase || "mysql"
+
+      // Login can fail because given db name doesn't exist, which it might not because we are trying to create it right now.
+      if (databaseType == "mssql" && newConfiguration.sqlConfig?.database) {
+        delete newConfiguration.sqlConfig.database
+      }
+
+      await this.withDirectDatabaseConnection(newConfiguration, async () => {
+        if (databaseType != "sqlite") {
+          await this.createDatabase(databaseIdentifier)
+        }
+
+        await this.createSchemaMigrationsTable()
+      })
+
+      if (this.args.testing) return this.result
+    }
+  }
+
+  /**
+   * Runs create database.
+   * @param {string} databaseIdentifier - Database identifier.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async createDatabase(databaseIdentifier) {
+    const databaseConfiguration = digg(this.getConfiguration().getDatabaseConfiguration(), databaseIdentifier)
+    const databaseName = digg(databaseConfiguration, "database")
+    const {databaseCharset, databaseCollation} = databaseConfiguration
+    const sqls = this.getDatabaseConnection().createDatabaseSql(databaseName, {ifNotExists: true, databaseCharset, databaseCollation})
+    await this.queryOrCollectSqls(sqls, (sql) => ({databaseName, sql}))
+  }
+
+  /**
+   * Runs create schema migrations table.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async createSchemaMigrationsTable() {
+    const schemaMigrationsTable = new TableData("schema_migrations", {ifNotExists: true})
+
+    schemaMigrationsTable.string("version", {null: false, primaryKey: true})
+
+    const createSchemaMigrationsTableSqls = await this.getDatabaseConnection().createTableSql(schemaMigrationsTable)
+    await this.queryOrCollectSqls(createSchemaMigrationsTableSqls, (createSchemaMigrationsTableSql) => ({createSchemaMigrationsTableSql}))
+  }
+}

package/build/cli/commands/db/drop.js

@@ -0,0 +1,75 @@
+import DbBaseCommand from "./base-command.js"
+import {digg} from "diggerize"
+import {incorporate} from "incorporator"
+
+export default class DbDrop extends DbBaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<void | Array<object>>} - Resolves with SQL statements when running in dry mode.
+   */
+  async execute() {
+    const environment = this.getConfiguration().getEnvironment()
+
+    if (environment != "development" && environment != "test") {
+      throw new Error(`This command should only be executed on development and test environments and not: ${environment}`)
+    }
+
+    for (const databaseIdentifier of this.getConfiguration().getDatabaseIdentifiers()) {
+      const databaseType = this.getConfiguration().getDatabaseType(databaseIdentifier)
+
+      if (this.args.testing) this.result = []
+
+      if (databaseType != "sqlite") {
+        const databasePool = this.getConfiguration().getDatabasePool(databaseIdentifier)
+        const newConfiguration = incorporate({}, databasePool.getConfiguration())
+        const targetDatabaseName = digg(this.getConfiguration().getDatabaseConfiguration(), databaseIdentifier, "database")
+
+        // Connect to a known-existing system database: the target is about to
+        // be dropped (so we can't be connected to it), Postgres rejects
+        // DROP DATABASE while connected to it, and configured `useDatabase`
+        // may happen to equal the target — in that case fall through to the
+        // driver's system default.
+        const configuredFallback = newConfiguration.useDatabase
+        const useConfiguredFallback = typeof configuredFallback == "string" && configuredFallback.length > 0 && configuredFallback != targetDatabaseName
+
+        newConfiguration.database = useConfiguredFallback
+          ? configuredFallback
+          : this.systemFallbackDatabaseName(databaseType)
+
+        if (databaseType == "mssql" && newConfiguration.sqlConfig?.database) {
+          delete newConfiguration.sqlConfig.database
+        }
+
+        await this.withDirectDatabaseConnection(newConfiguration, async () => {
+          await this.dropDatabase(databaseIdentifier)
+        })
+      }
+
+      if (this.args.testing) return this.result
+    }
+  }
+
+  /**
+   * Runs system fallback database name.
+   * @param {string} databaseType - Database type.
+   * @returns {string} - System/maintenance database name for that driver.
+   */
+  systemFallbackDatabaseName(databaseType) {
+    if (databaseType == "pgsql") return "postgres"
+    if (databaseType == "mssql") return "master"
+
+    return "mysql"
+  }
+
+  /**
+   * Runs drop database.
+   * @param {string} databaseIdentifier - Database identifier.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async dropDatabase(databaseIdentifier) {
+    const databaseName = digg(this.getConfiguration().getDatabaseConfiguration(), databaseIdentifier, "database")
+    const sqls = this.getDatabaseConnection().dropDatabaseSql(databaseName, {ifExists: true})
+
+    await this.queryOrCollectSqls(sqls, (sql) => ({databaseName, sql}))
+  }
+}

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

@@ -0,0 +1,17 @@
+import BaseCommand from "../../base-command.js"
+import {digg} from "diggerize"
+import Migrator from "../../../database/migrator.js"
+
+export default class DbMigrate extends BaseCommand {
+  async execute() {
+    const migrations = await this.getEnvironmentHandler().findMigrations()
+    const migrator = new Migrator({configuration: this.getConfiguration()})
+
+    console.log(`Running ${migrations.length} migrations`)
+
+    await this.getConfiguration().ensureConnections({name: "DB migrate"}, async () => {
+      await migrator.prepare()
+      await migrator.migrateFiles(migrations, digg(this.getEnvironmentHandler(), "requireMigration"))
+    })
+  }
+}

package/build/cli/commands/db/reset.js

@@ -0,0 +1,22 @@
+import BaseCommand from "../../base-command.js"
+import {digg} from "diggerize"
+import Migrator from "../../../database/migrator.js"
+
+export default class DbReset extends BaseCommand {
+  async execute() {
+    const environment = this.getConfiguration().getEnvironment()
+
+    if (environment != "development" && environment != "test") {
+      throw new Error(`This command should only be executed on development and test environments and not: ${environment}`)
+    }
+
+    const migrations = await this.getEnvironmentHandler().findMigrations()
+    const migrator = new Migrator({configuration: this.getConfiguration()})
+
+    await this.getConfiguration().ensureConnections({name: "DB reset"}, async () => {
+      await migrator.reset()
+      await migrator.prepare()
+      await migrator.migrateFiles(migrations, digg(this.getEnvironmentHandler(), "requireMigration"))
+    })
+  }
+}

package/build/cli/commands/db/rollback.js

@@ -0,0 +1,15 @@
+import BaseCommand from "../../base-command.js"
+import {digg} from "diggerize"
+import Migrator from "../../../database/migrator.js"
+
+export default class DbRollback extends BaseCommand {
+  async execute() {
+    const migrations = await this.getEnvironmentHandler().findMigrations()
+    const migrator = new Migrator({configuration: this.getConfiguration()})
+
+    await this.getConfiguration().ensureConnections({name: "DB rollback"}, async () => {
+      await migrator.prepare()
+      await migrator.rollback(migrations, digg(this.getEnvironmentHandler(), "requireMigration"))
+    })
+  }
+}

package/build/cli/commands/db/schema/dump.js

@@ -0,0 +1,12 @@
+import BaseCommand from "../../../base-command.js"
+
+/** CLI command for dumping DB structure SQL files. */
+export default class DbSchemaDump extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<?>} - Resolves with the command result.
+   */
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsDbSchemaDump(this)
+  }
+}

package/build/cli/commands/db/schema/load.js

@@ -0,0 +1,12 @@
+import BaseCommand from "../../../base-command.js"
+
+/** CLI command for loading DB structure SQL files. */
+export default class DbSchemaLoad extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<?>} - Resolves with the command result.
+   */
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsDbSchemaLoad(this)
+  }
+}

package/build/cli/commands/db/seed.js

@@ -0,0 +1,12 @@
+import BaseCommand from "../../base-command.js"
+
+/** CLI command for loading and running src/db/seed.js. */
+export default class DbSeed extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<?>} - Resolves with the command result.
+   */
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsDbSeed(this)
+  }
+}

package/build/cli/commands/db/tenants/check.js

@@ -0,0 +1,38 @@
+// @ts-check
+
+import BaseCommand from "../../../base-command.js"
+import TenantDatabaseCommandHelper from "../../../tenant-database-command-helper.js"
+
+export default class DbTenantsCheck extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<{identifier: string, tenantCount: number} | void>} - Result in test mode.
+   */
+  async execute() {
+    const helper = new TenantDatabaseCommandHelper({
+      command: this,
+      identifier: this.processArgs?.[1]
+    })
+    const provider = helper.provider
+    const tenantCount = await helper.eachTenant(async ({databaseConfiguration, tenant}) => {
+      if (typeof provider.checkTenant === "function") {
+        await provider.checkTenant({
+          configuration: this.getConfiguration(),
+          databaseConfiguration,
+          identifier: helper.identifier,
+          tenant
+        })
+      }
+
+      await this.getConfiguration().ensureConnections({name: `DB tenants check: ${helper.identifier}`}, async (dbs) => {
+        const db = dbs[helper.identifier]
+
+        if (!db) throw new Error(`Tenant database identifier ${helper.identifier} did not open a connection`)
+
+        await db.query("SELECT 1")
+      })
+    })
+
+    if (this.args.testing) return {identifier: helper.identifier, tenantCount}
+  }
+}

package/build/cli/commands/db/tenants/create.js

@@ -0,0 +1,33 @@
+// @ts-check
+
+import BaseCommand from "../../../base-command.js"
+import TenantDatabaseCommandHelper from "../../../tenant-database-command-helper.js"
+
+export default class DbTenantsCreate extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<{identifier: string, tenantCount: number} | void>} - Result in test mode.
+   */
+  async execute() {
+    const helper = new TenantDatabaseCommandHelper({
+      command: this,
+      identifier: this.processArgs?.[1]
+    })
+    const provider = helper.provider
+
+    if (typeof provider.createDatabase !== "function") {
+      throw new Error(`Tenant database provider for ${helper.identifier} must define createDatabase to use db:tenants:create`)
+    }
+
+    const tenantCount = await helper.eachTenant(async ({databaseConfiguration, tenant}) => {
+      await provider.createDatabase?.({
+        configuration: this.getConfiguration(),
+        databaseConfiguration,
+        identifier: helper.identifier,
+        tenant
+      })
+    })
+
+    if (this.args.testing) return {identifier: helper.identifier, tenantCount}
+  }
+}

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

@@ -0,0 +1,49 @@
+// @ts-check
+
+import {digg} from "diggerize"
+import BaseCommand from "../../../base-command.js"
+import Migrator from "../../../../database/migrator.js"
+import TenantDatabaseCommandHelper from "../../../tenant-database-command-helper.js"
+
+export default class DbTenantsMigrate extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<{identifier: string, migrationCount: number, tenantCount: number} | void>} - Result in test mode.
+   */
+  async execute() {
+    const helper = new TenantDatabaseCommandHelper({
+      command: this,
+      identifier: this.processArgs?.[1]
+    })
+    const migrations = await this.getEnvironmentHandler().findMigrations()
+    const tenantCount = await helper.eachTenant(async ({databaseConfiguration, tenant}) => {
+      const migrator = new Migrator({
+        configuration: this.getConfiguration(),
+        databaseIdentifiers: [helper.identifier]
+      })
+
+      await this.getConfiguration().ensureConnections({name: `DB tenants migrate: ${helper.identifier}`}, async () => {
+        await migrator.prepare()
+        const migrationsApplied = await migrator.migrateFiles(migrations, digg(this.getEnvironmentHandler(), "requireMigration"))
+
+        if (typeof helper.provider.afterMigrateTenant === "function") {
+          await helper.provider.afterMigrateTenant({
+            configuration: this.getConfiguration(),
+            databaseConfiguration,
+            identifier: helper.identifier,
+            migrationsApplied,
+            tenant
+          })
+        }
+      })
+    })
+
+    if (this.args.testing) {
+      return {
+        identifier: helper.identifier,
+        migrationCount: migrations.length,
+        tenantCount
+      }
+    }
+  }
+}

package/build/cli/commands/destroy/migration.js

@@ -0,0 +1,7 @@
+import BaseCommand from "../../base-command.js"
+
+export default class DbDestroyMigration extends BaseCommand {
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsMigrationDestroy(this)
+  }
+}