velocious 1.0.482 → 1.0.483

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,86 @@
+// @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/reading delegate to {@link Current} (which owns the async-context
+ * tenant state), so they compose with the existing connection pools and request lifecycle;
+ * 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.
+   * @param {object} tenant Descriptor understood by the app's tenantDatabaseResolver.
+   * @param {() => Promise<?>} callback
+   * @returns {Promise<?>}
+   */
+  static async with(tenant, callback) {
+    return await Current.withTenant(tenant, 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. 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})
+
+    return await iterator.run(tenants, callback)
+  }
+
+  /**
+   * 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
+      })
+    })
+  }
+}