velocious 1.0.482 → 1.0.484

package/src/tenants/tenant-iterator.js

@@ -0,0 +1,111 @@
+// @ts-check
+
+/**
+ * Runs a callback once within each tenant's context for a tenant database identifier,
+ * optionally several tenants at a time. Each tenant is entered with `runWithTenant`, and a
+ * tenant whose database identifier is inactive throws rather than running the callback
+ * against the wrong connection. When iterating in parallel the per-tenant failures are
+ * collected and rethrown together as an `AggregateError` so one bad tenant does not hide the
+ * others. This is the iteration engine shared by the `db:tenants:*` CLI commands and the
+ * runtime {@link Tenant} façade; the caller is responsible for producing the tenant list.
+ */
+export default class TenantIterator {
+  /**
+   * Creates an iterator bound to a configuration and tenant database identifier.
+   * @param {{configuration: import("../configuration.js").default, identifier: string, parallelCount?: number}} args
+   */
+  constructor({configuration, identifier, parallelCount = 1}) {
+    this.configuration = configuration
+    this.identifier = identifier
+    this.parallelCount = parallelCount
+  }
+
+  /**
+   * Runs `callback` within each tenant's context and returns how many tenants were processed.
+   * @param {Array<?>} tenants
+   * @param {function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>} callback
+   * @returns {Promise<number>}
+   */
+  async run(tenants, callback) {
+    if (this.parallelCount <= 1) {
+      for (const tenant of tenants) {
+        await this.runTenantCallback({callback, tenant})
+      }
+
+      return tenants.length
+    }
+
+    /** @type {Array<{error: Error, tenant: ?}>} */
+    const failures = []
+    const workers = []
+    let tenantIndex = 0
+    const workerCount = Math.min(this.parallelCount, tenants.length)
+
+    for (let workerIndex = 0; workerIndex < workerCount; workerIndex++) {
+      workers.push((async () => {
+        while (tenantIndex < tenants.length) {
+          const tenant = tenants[tenantIndex]
+
+          tenantIndex++
+
+          try {
+            await this.runTenantCallback({callback, tenant})
+          } catch (error) {
+            failures.push({
+              error: error instanceof Error ? error : new Error(String(error)),
+              tenant
+            })
+          }
+        }
+      })())
+    }
+
+    await Promise.all(workers)
+
+    if (failures.length > 0) {
+      const failedTenantLabels = failures.map((failure) => TenantIterator.tenantLabel(failure.tenant)).join(", ")
+
+      throw new AggregateError(
+        failures.map((failure) => failure.error),
+        `Failed tenant database command for tenant(s): ${failedTenantLabels}`
+      )
+    }
+
+    return tenants.length
+  }
+
+  /**
+   * Enters one tenant's context and runs the callback, asserting the database is active first.
+   * @param {{callback: function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>, tenant: ?}} args
+   * @returns {Promise<void>}
+   */
+  async runTenantCallback({callback, tenant}) {
+    await this.configuration.runWithTenant(tenant, async () => {
+      if (!this.configuration.isDatabaseIdentifierActive(this.identifier)) {
+        throw new Error(`Tenant database identifier ${this.identifier} is inactive for tenant: ${TenantIterator.tenantLabel(tenant)}`)
+      }
+
+      await callback({
+        databaseConfiguration: this.configuration.resolveDatabaseConfiguration(this.identifier),
+        tenant
+      })
+    })
+  }
+
+  /**
+   * Builds a human-readable label for a tenant for use in error messages.
+   * @param {?} tenant
+   * @returns {string}
+   */
+  static tenantLabel(tenant) {
+    if (tenant && typeof tenant === "object") {
+      const tenantObject = /** @type {{id?: ?, name?: ?, slug?: ?}} */ (tenant)
+
+      if (tenantObject.slug) return String(tenantObject.slug)
+      if (tenantObject.name) return String(tenantObject.name)
+      if (tenantObject.id) return String(tenantObject.id)
+    }
+
+    return JSON.stringify(tenant)
+  }
+}

package/src/tenants/tenant.js

@@ -0,0 +1,104 @@
+// @ts-check
+
+import Current from "../current.js"
+import TenantIterator from "./tenant-iterator.js"
+
+/**
+ * Apartment-style runtime façade for multi-tenant apps. A "tenant" is whatever descriptor
+ * object the app's `tenantDatabaseResolver` understands (an account, a project, …); this
+ * class is the single discoverable home for switching into a tenant's context, reading the
+ * current one, iterating every tenant of a database identifier, and dropping a tenant's
+ * database. Switching delegates to {@link Current} (which owns the async-context tenant
+ * state) and additionally runs the callback inside `ensureConnections`, so entering a tenant
+ * makes its database immediately queryable — the apartment-style "switch" semantics — without
+ * the caller establishing connections itself; iteration and drop drive the app's tenant
+ * database provider hooks.
+ */
+export default class Tenant {
+  /**
+   * Runs `callback` with `tenant` as the current tenant, restoring the previous tenant after.
+   * The callback runs inside `ensureConnections`, so every database identifier the tenant
+   * activates (the global database plus the tenant's database) has a checked-out connection
+   * available for the callback's duration: switching into a tenant makes it queryable without
+   * the caller wiring up connections. Already-checked-out connections are reused, so nesting
+   * `Tenant.with` calls does not open redundant connections. The callback receives the active
+   * connections keyed by identifier, the same as `ensureConnections`.
+   * @param {object} tenant Descriptor understood by the app's tenantDatabaseResolver.
+   * @param {(connections: Record<string, import("../database/drivers/base.js").default>) => Promise<?>} callback
+   * @returns {Promise<?>}
+   */
+  static async with(tenant, callback) {
+    const configuration = Current.configuration()
+
+    return await Current.withTenant(tenant, async () => await configuration.ensureConnections(callback))
+  }
+
+  /**
+   * The current tenant descriptor, or undefined when running outside any tenant context.
+   * @returns {Record<string, unknown> | undefined}
+   */
+  static current() {
+    return Current.tenant()
+  }
+
+  /**
+   * Lists the tenants for a database identifier through the provider and runs `callback`
+   * within each tenant's context, optionally filtered and several at a time. Like
+   * {@link Tenant.with}, the callback runs inside `ensureConnections` so each tenant's
+   * database is queryable without the caller wiring up connections. Returns how many tenants
+   * the callback ran for (after filtering).
+   * @param {{identifier: string, callback: function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>, parallel?: number, filter?: (tenant: ?) => boolean, configuration?: import("../configuration.js").default}} args
+   * @returns {Promise<number>}
+   */
+  static async each({identifier, callback, parallel = 1, filter, configuration = Current.configuration()}) {
+    const provider = configuration.getTenantDatabaseProvider(identifier)
+    const listedTenants = await configuration.ensureConnections({name: `Tenant.each: ${identifier}`}, async () => {
+      return await provider.listTenants({configuration, identifier})
+    })
+
+    if (!Array.isArray(listedTenants)) {
+      throw new Error(`Tenant database provider for ${identifier} must return an array from listTenants`)
+    }
+
+    const tenants = filter ? listedTenants.filter(filter) : listedTenants
+    const iterator = new TenantIterator({configuration, identifier, parallelCount: parallel})
+
+    // Run each tenant's callback inside ensureConnections so the iterator stays
+    // connection-agnostic (the db:tenants:* CLI commands share TenantIterator and must run
+    // their callbacks, such as create, before the tenant database exists) while runtime
+    // iteration here gets the tenant's connections established the same way Tenant.with does.
+    return await iterator.run(tenants, async (callbackArgs) => {
+      await configuration.ensureConnections({name: `Tenant.each: ${identifier}`}, async () => await callback(callbackArgs))
+    })
+  }
+
+  /**
+   * Drops one tenant's database/schema through the provider's `dropDatabase` hook.
+   * @param {{identifier: string, tenant: object, configuration?: import("../configuration.js").default}} args
+   * @returns {Promise<void>}
+   */
+  static async drop({identifier, tenant, configuration = Current.configuration()}) {
+    const provider = configuration.getTenantDatabaseProvider(identifier)
+
+    if (typeof provider.dropDatabase !== "function") {
+      throw new Error(`Tenant database provider for ${identifier} must define dropDatabase to drop a tenant`)
+    }
+
+    await configuration.runWithTenant(tenant, async () => {
+      // Guard against an unresolved tenant. resolveDatabaseConfiguration falls back to the
+      // base (template/default) tenant database when the resolver returns nothing for this
+      // descriptor, so without this check a provider that drops by databaseConfiguration.name
+      // would drop the template database instead of rejecting the bad tenant.
+      if (!configuration.isDatabaseIdentifierActive(identifier)) {
+        throw new Error(`Tenant database identifier ${identifier} is inactive for tenant: ${TenantIterator.tenantLabel(tenant)}`)
+      }
+
+      await provider.dropDatabase?.({
+        configuration,
+        databaseConfiguration: configuration.resolveDatabaseConfiguration(identifier),
+        identifier,
+        tenant
+      })
+    })
+  }
+}