velocious 1.0.489 → 1.0.492

package/src/sync/sync-scope-store.js

@@ -0,0 +1,327 @@
+// @ts-check
+
+import TableData from "../database/table-data/index.js"
+import UUID from "pure-uuid"
+
+import {scopeKey} from "./query-scope.js"
+import stableJsonStringify from "./stable-json.js"
+
+const TABLE_NAME = "velocious_sync_scopes"
+const SCOPE_DIGEST_PREFIX = "velocious-sync-scope:"
+
+/**
+ * Digests a serialized scope into a fixed-size deterministic key, so scope
+ * identities with long condition values fit an indexed string column.
+ * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
+ * @returns {string} Deterministic UUIDv5 digest of the canonical scope key.
+ */
+function scopeDigestForScope(scope) {
+  return new UUID(5, "ns:URL", `${SCOPE_DIGEST_PREFIX}${scopeKey(scope)}`).format()
+}
+
+/**
+ * @typedef {object} SyncScopeRow
+ * @property {Record<string, ?>} conditions - Scope attribute conditions.
+ * @property {string | null} cursorPayload - Persisted cursor JSON payload.
+ * @property {string} id - Scope row id.
+ * @property {string} resourceType - Scope resource/model name.
+ * @property {string} scopeDigest - Fixed-size deterministic digest of the canonical scope key.
+ * @property {string} state - Scope state ("active" or "removed").
+ */
+
+/**
+ * Framework-owned local persistence for declared sync scopes and their cursors.
+ *
+ * Backed by an auto-created `velocious_sync_scopes` table on the configured
+ * database, with a process-local memory fallback when no database is
+ * configured (mirroring the server change-feed store).
+ */
+export default class SyncScopeStore {
+  /**
+   * Creates a sync scope store.
+   * @param {object} args - Options.
+   * @param {import("../configuration.js").default} args.configuration - Configuration owning the database.
+   * @param {string} [args.databaseIdentifier] - Database identifier.
+   */
+  constructor({configuration, databaseIdentifier = "default"}) {
+    this.configuration = configuration
+    this.databaseIdentifier = databaseIdentifier
+    /** @type {Map<string, SyncScopeRow>} */
+    this._memoryScopes = new Map()
+    this._isReady = false
+    /** @type {Promise<void> | null} */
+    this._readyPromise = null
+  }
+
+  /**
+   * Ensures the backing table exists.
+   * @returns {Promise<void>} Resolves when ready.
+   */
+  async ensureReady() {
+    if (this._isReady) return
+
+    if (this._usesMemoryStorage()) {
+      this._isReady = true
+      return
+    }
+
+    if (this._readyPromise) return await this._readyPromise
+
+    this._readyPromise = this._withDb(async (db) => {
+      await this._ensureScopesTable(db)
+      this._isReady = true
+    })
+
+    try {
+      await this._readyPromise
+    } finally {
+      if (!this._isReady) this._readyPromise = null
+    }
+  }
+
+  /**
+   * Finds or creates the scope row for a serialized scope, reactivating removed scopes.
+   * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
+   * @returns {Promise<SyncScopeRow>} Persisted scope row.
+   */
+  async findOrCreateScope(scope) {
+    await this.ensureReady()
+
+    const digest = scopeDigestForScope(scope)
+
+    if (this._usesMemoryStorage()) {
+      const existingScope = this._memoryScopes.get(digest)
+
+      if (existingScope) {
+        if (existingScope.state !== "active") existingScope.state = "active"
+
+        return existingScope
+      }
+
+      const newScope = {
+        conditions: scope.conditions,
+        cursorPayload: null,
+        id: new UUID(4).format(),
+        resourceType: scope.resourceType,
+        scopeDigest: digest,
+        state: "active"
+      }
+
+      this._memoryScopes.set(digest, newScope)
+
+      return newScope
+    }
+
+    return await this._withDb(async (db) => {
+      const existingRow = await this._rowByScopeDigest(db, digest)
+
+      if (existingRow) {
+        if (existingRow.state !== "active") {
+          await db.update({conditions: {id: existingRow.id}, data: {state: "active", updated_at: new Date()}, tableName: TABLE_NAME})
+          existingRow.state = "active"
+        }
+
+        return existingRow
+      }
+
+      await db.insert({
+        tableName: TABLE_NAME,
+        data: {
+          conditions_json: stableJsonStringify(scope.conditions),
+          created_at: new Date(),
+          cursor_json: null,
+          id: new UUID(4).format(),
+          resource_type: scope.resourceType,
+          scope_digest: digest,
+          state: "active",
+          updated_at: new Date()
+        }
+      })
+
+      const createdRow = await this._rowByScopeDigest(db, digest)
+
+      if (!createdRow) throw new Error("Failed to persist sync scope")
+
+      return createdRow
+    })
+  }
+
+  /**
+   * Returns all active scope rows.
+   * @returns {Promise<SyncScopeRow[]>} Active scope rows.
+   */
+  async activeScopes() {
+    await this.ensureReady()
+
+    if (this._usesMemoryStorage()) {
+      return [...this._memoryScopes.values()].filter((scope) => scope.state === "active")
+    }
+
+    return await this._withDb(async (db) => {
+      const rows = /** @type {Array<Record<string, ?>>} */ (await db
+        .newQuery()
+        .from(TABLE_NAME)
+        .where({state: "active"})
+        .order("created_at ASC")
+        .results())
+
+      return rows.map((row) => this._normalizeScopeRow(row))
+    })
+  }
+
+  /**
+   * Loads the persisted cursor payload for a scope row.
+   * @param {SyncScopeRow} scopeRow - Scope row.
+   * @returns {Promise<string | null>} Cursor JSON payload.
+   */
+  async loadCursor(scopeRow) {
+    await this.ensureReady()
+
+    if (this._usesMemoryStorage()) {
+      return this._memoryScopes.get(scopeRow.scopeDigest)?.cursorPayload ?? null
+    }
+
+    return await this._withDb(async (db) => {
+      const row = await this._rowByScopeDigest(db, scopeRow.scopeDigest)
+
+      return row ? row.cursorPayload : null
+    })
+  }
+
+  /**
+   * Persists the acknowledged cursor for a scope row.
+   * @param {SyncScopeRow} scopeRow - Scope row.
+   * @param {import("./sync-api-client-types.js").SyncCursor} cursor - Acknowledged cursor.
+   * @returns {Promise<void>}
+   */
+  async saveCursor(scopeRow, cursor) {
+    if (!cursor) return
+
+    await this.ensureReady()
+
+    const cursorPayload = JSON.stringify(cursor)
+
+    if (this._usesMemoryStorage()) {
+      const memoryScope = this._memoryScopes.get(scopeRow.scopeDigest)
+
+      if (!memoryScope) throw new Error(`No sync scope found for: ${scopeRow.scopeDigest}`)
+
+      memoryScope.cursorPayload = cursorPayload
+      return
+    }
+
+    await this._withDb(async (db) => {
+      await db.update({
+        conditions: {scope_digest: scopeRow.scopeDigest},
+        data: {cursor_json: cursorPayload, updated_at: new Date()},
+        tableName: TABLE_NAME
+      })
+    })
+  }
+
+  /**
+   * Deactivates the scope row for a serialized scope.
+   * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
+   * @returns {Promise<void>}
+   */
+  async deactivate(scope) {
+    await this.ensureReady()
+
+    const digest = scopeDigestForScope(scope)
+
+    if (this._usesMemoryStorage()) {
+      const memoryScope = this._memoryScopes.get(digest)
+
+      if (memoryScope) memoryScope.state = "removed"
+
+      return
+    }
+
+    await this._withDb(async (db) => {
+      await db.update({conditions: {scope_digest: digest}, data: {state: "removed", updated_at: new Date()}, tableName: TABLE_NAME})
+    })
+  }
+
+  /**
+   * Whether the store runs without a configured database.
+   * @returns {boolean} Whether memory storage is used.
+   */
+  _usesMemoryStorage() {
+    try {
+      return !this.configuration.getDatabaseConfiguration()[this.databaseIdentifier]
+    } catch {
+      return true
+    }
+  }
+
+  /**
+   * Runs a callback with a database connection.
+   * @template Result
+   * @param {(db: import("../database/drivers/base.js").default) => Promise<Result>} callback - Database callback.
+   * @returns {Promise<Result>} Callback result.
+   */
+  async _withDb(callback) {
+    return await this.configuration.ensureConnections({name: "Sync scope store"}, async (dbs) => {
+      const db = dbs[this.databaseIdentifier]
+
+      if (!db) throw new Error(`No database connection available for identifier: ${this.databaseIdentifier}`)
+
+      return await callback(db)
+    })
+  }
+
+  /**
+   * Ensures the scopes table exists.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>}
+   */
+  async _ensureScopesTable(db) {
+    if (await db.tableExists(TABLE_NAME)) return
+
+    const table = new TableData(TABLE_NAME, {ifNotExists: true})
+
+    table.string("id", {null: false, primaryKey: true})
+    table.string("scope_digest", {index: true, null: false})
+    table.string("resource_type", {index: true, null: false})
+    table.text("conditions_json", {null: false})
+    table.text("cursor_json", {null: true})
+    table.string("state", {index: true, null: false})
+    table.datetime("created_at", {null: false})
+    table.datetime("updated_at", {null: false})
+
+    await db.createTable(table)
+  }
+
+  /**
+   * Resolves a scope row by its digest.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string} digest - Fixed-size scope digest.
+   * @returns {Promise<SyncScopeRow | null>} Scope row or null.
+   */
+  async _rowByScopeDigest(db, digest) {
+    const rows = /** @type {Array<Record<string, ?>>} */ (await db
+      .newQuery()
+      .from(TABLE_NAME)
+      .where({scope_digest: digest})
+      .limit(1)
+      .results())
+
+    return rows[0] ? this._normalizeScopeRow(rows[0]) : null
+  }
+
+  /**
+   * Normalizes a raw scope table row.
+   * @param {Record<string, ?>} row - Raw table row.
+   * @returns {SyncScopeRow} Normalized scope row.
+   */
+  _normalizeScopeRow(row) {
+    return {
+      conditions: /** @type {Record<string, ?>} */ (JSON.parse(String(row.conditions_json))),
+      cursorPayload: row.cursor_json === null || row.cursor_json === undefined ? null : String(row.cursor_json),
+      id: String(row.id),
+      resourceType: String(row.resource_type),
+      scopeDigest: String(row.scope_digest),
+      state: String(row.state)
+    }
+  }
+}

package/src/tenants/default-tenant-database-provisioning.js

@@ -0,0 +1,124 @@
+// @ts-check
+
+/**
+ * Default tenant-database provisioning used by `db:tenants:create`,
+ * `db:tenants:drop`, and `Tenant.drop` when a tenant-database provider does not
+ * define its own `createDatabase`/`dropDatabase`. This is the generic,
+ * driver-agnostic lifecycle every app on the tenant framework needs, so it lives
+ * in the framework instead of being reimplemented in each consuming project.
+ *
+ * File-backed drivers (sqlite) have no server-side CREATE/DROP DATABASE — the file
+ * is created on connect and left in place on drop — so creating just ensures the
+ * tenant's connection and dropping is a no-op. Server drivers (mysql, pgsql, …)
+ * connect to the configured maintenance database (`useDatabase`) and run the
+ * driver's own `createDatabaseSql`/`dropDatabaseSql`.
+ */
+
+const SAFE_TENANT_DATABASE_NAME = /^[a-z0-9_]+$/
+
+/**
+ * Whether the driver stores each database as a local file instead of on a server.
+ * @param {import("../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Resolved tenant database configuration.
+ * @returns {boolean} - True for file-backed drivers such as sqlite.
+ */
+function fileBackedDriver(databaseConfiguration) {
+  return databaseConfiguration.type === "sqlite"
+}
+
+/**
+ * Validates the tenant database name against a strict allowlist before it is
+ * interpolated into DDL.
+ * @param {import("../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Resolved tenant database configuration.
+ * @returns {string} - The validated tenant database name.
+ */
+function guardedDatabaseName(databaseConfiguration) {
+  const databaseName = databaseConfiguration.database
+
+  if (!databaseName || !SAFE_TENANT_DATABASE_NAME.test(databaseName)) {
+    throw new Error(`Unsafe tenant database name: ${databaseName}`)
+  }
+
+  return databaseName
+}
+
+/**
+ * Opens a driver connected to the server's maintenance database (`useDatabase`),
+ * from which `CREATE DATABASE` / `DROP DATABASE` for the tenant can be issued.
+ * @param {import("../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Resolved tenant database configuration.
+ * @param {import("../configuration.js").default} configuration - The Velocious configuration.
+ * @returns {import("../database/drivers/base.js").default} - A driver bound to the maintenance database.
+ */
+function maintenanceConnection(databaseConfiguration, configuration) {
+  const DriverClass = databaseConfiguration.driver
+
+  if (!DriverClass) {
+    throw new Error("Tenant database configuration is missing a driver.")
+  }
+
+  if (!databaseConfiguration.useDatabase) {
+    throw new Error("Tenant database configuration is missing a maintenance database in useDatabase.")
+  }
+
+  return new DriverClass({...databaseConfiguration, database: databaseConfiguration.useDatabase}, configuration)
+}
+
+/**
+ * Creates the tenant database for one tenant.
+ * @param {{configuration: import("../configuration.js").default, databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}} args - Provisioning arguments.
+ * @returns {Promise<void>} - Resolves once the tenant database exists.
+ */
+export async function createTenantDatabase({configuration, databaseConfiguration, tenant}) {
+  if (fileBackedDriver(databaseConfiguration)) {
+    await configuration.runWithTenant(tenant, async () => {
+      await configuration.ensureConnections(async () => {})
+    })
+
+    return
+  }
+
+  const databaseName = guardedDatabaseName(databaseConfiguration)
+  const connection = maintenanceConnection(databaseConfiguration, configuration)
+
+  await connection.connect()
+
+  try {
+    const sqls = connection.createDatabaseSql(databaseName, {
+      databaseCharset: databaseConfiguration.databaseCharset,
+      databaseCollation: databaseConfiguration.databaseCollation,
+      ifNotExists: true
+    })
+
+    for (const sql of sqls) {
+      await connection.query(sql)
+    }
+  } finally {
+    await connection.close()
+  }
+}
+
+/**
+ * Drops the tenant database for one tenant. Uses `DROP DATABASE IF EXISTS`, so it
+ * is a safe no-op for a tenant that was never fully provisioned.
+ * @param {{configuration: import("../configuration.js").default, databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType}} args - Provisioning arguments.
+ * @returns {Promise<void>} - Resolves once the tenant database is gone.
+ */
+export async function dropTenantDatabase({configuration, databaseConfiguration}) {
+  if (fileBackedDriver(databaseConfiguration)) {
+    return
+  }
+
+  const databaseName = guardedDatabaseName(databaseConfiguration)
+  const connection = maintenanceConnection(databaseConfiguration, configuration)
+
+  await connection.connect()
+
+  try {
+    const sqls = connection.dropDatabaseSql(databaseName, {ifExists: true})
+
+    for (const sql of sqls) {
+      await connection.query(sql)
+    }
+  } finally {
+    await connection.close()
+  }
+}

package/src/tenants/tenant.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import Current from "../current.js"
+import {dropTenantDatabase} from "./default-tenant-database-provisioning.js"
 import TenantIterator from "./tenant-iterator.js"
 
 /**
@@ -80,10 +81,9 @@ export default class Tenant {
    */
   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`)
-    }
+    const dropDatabase = typeof provider.dropDatabase === "function"
+      ? provider.dropDatabase.bind(provider)
+      : dropTenantDatabase
 
     await configuration.runWithTenant(tenant, async () => {
       // Guard against an unresolved tenant. resolveDatabaseConfiguration falls back to the
@@ -94,7 +94,7 @@ export default class Tenant {
         throw new Error(`Tenant database identifier ${identifier} is inactive for tenant: ${TenantIterator.tenantLabel(tenant)}`)
       }
 
-      await provider.dropDatabase?.({
+      await dropDatabase({
         configuration,
         databaseConfiguration: configuration.resolveDatabaseConfiguration(identifier),
         identifier,