velocious 1.0.509 → 1.0.511

package/src/database/drivers/mysql/index.js

@@ -31,6 +31,9 @@ import Update from "./sql/update.js"
 const MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS = 60 * 60 * 24 * 365
 
 export default class VelociousDatabaseDriversMysql extends Base{
+  /** @type {import("mysql").Pool | undefined} */
+  pool = undefined
+
   /** @type {string | null} */
   _desiredSessionTimeZone = "+00:00"
 

package/src/database/record/index.js

@@ -24,7 +24,7 @@
 
 /** @typedef {import("../../configuration-types.js").TenantDatabaseProviderType} TenantDatabaseProviderType */
 
-import timeout from "awaitery/build/timeout.js"
+import AdvisoryLockRunner, {AdvisoryLockBusyError, AdvisoryLockHoldTimeoutError, AdvisoryLockTimeoutError} from "../advisory-lock-runner.js"
 import BelongsToInstanceRelationship from "./instance-relationships/belongs-to.js"
 import BelongsToRelationship from "./relationships/belongs-to.js"
 import Configuration from "../../configuration.js"
@@ -164,60 +164,6 @@ function buildRelatedRecordWithInverse(parent, relationshipName, attributes, all
   return record
 }
 
-/**
- * Thrown by `Record.withAdvisoryLock` when the caller supplied a
- * `timeoutMs` and the lock was not granted before it elapsed.
- */
-class AdvisoryLockTimeoutError extends Error {
-  /**
-   * Runs constructor.
-   * @param {string} message - Error message.
-   * @param {{name: string}} args - The advisory lock name that timed out.
-   */
-  constructor(message, {name}) {
-    super(message)
-    this.name = "AdvisoryLockTimeoutError"
-    this.lockName = name
-  }
-}
-
-/**
- * Thrown by `Record.withAdvisoryLockOrFail` when the lock is already held
- * by another session at the moment of the call.
- */
-class AdvisoryLockBusyError extends Error {
-  /**
-   * Runs constructor.
-   * @param {string} message - Error message.
-   * @param {{name: string}} args - The advisory lock name that was already held.
-   */
-  constructor(message, {name}) {
-    super(message)
-    this.name = "AdvisoryLockBusyError"
-    this.lockName = name
-  }
-}
-
-/**
- * Thrown by `Record.withAdvisoryLock` / `withAdvisoryLockOrFail` when the
- * caller supplied a `holdTimeoutMs` and the callback ran longer than it. The
- * lock is released before this is thrown, so a hung holder can't block other
- * sessions indefinitely. Note: the callback itself is not cancelled — pass an
- * AbortSignal to the work if it needs to stop.
- */
-class AdvisoryLockHoldTimeoutError extends Error {
-  /**
-   * Runs constructor.
-   * @param {string} message - Error message.
-   * @param {{name: string}} args - The advisory lock name whose hold timed out.
-   */
-  constructor(message, {name}) {
-    super(message)
-    this.name = "AdvisoryLockHoldTimeoutError"
-    this.lockName = name
-  }
-}
-
 class TenantDatabaseScopeError extends Error {
   /**
    * Runs constructor.
@@ -2675,10 +2621,13 @@ class VelociousDatabaseRecord {
   }
 
   /**
-   * Runs the callback while holding a named advisory lock on the current
-   * connection. Advisory locks are cooperative and connection-scoped: they
-   * serialize callers that opt into the same `name`, without touching row
-   * or table locks, so unrelated traffic is free to proceed.
+   * Runs the callback while holding a named advisory lock. Calls without
+   * a positive `holdTimeoutMs` use the caller connection; calls with a positive
+   * `holdTimeoutMs` use a dedicated lock connection so timeout cleanup can
+   * release the lock even when callback database work is stuck. Advisory locks
+   * are cooperative and session-scoped: they serialize callers that opt into
+   * the same `name`, without touching row or table locks, so unrelated traffic
+   * is free to proceed.
    *
    * The lock is acquired before the callback runs and released in a
    * `finally` block afterwards, so the callback's return value is
@@ -2694,18 +2643,13 @@ class VelociousDatabaseRecord {
   static async withAdvisoryLock(name, callback, args = {}) {
     await this.ensureInitialized()
 
-    const connection = this.connection()
-    const acquired = await connection.acquireAdvisoryLock(name, args)
-
-    if (!acquired) {
-      throw new AdvisoryLockTimeoutError(`Timed out waiting for advisory lock ${JSON.stringify(name)}`, {name})
-    }
+    const runner = new AdvisoryLockRunner({
+      configuration: this._getConfiguration(),
+      connectionProvider: () => this.connection(),
+      databaseIdentifier: this.getDatabaseIdentifier()
+    })
 
-    try {
-      return await this.runWithAdvisoryLockHoldTimeout(name, callback, args.holdTimeoutMs)
-    } finally {
-      await connection.releaseAdvisoryLock(name)
-    }
+    return await runner.withAdvisoryLock(name, callback, args)
   }
 
   /**
@@ -2725,31 +2669,19 @@ class VelociousDatabaseRecord {
   static async withAdvisoryLockOrFail(name, callback, args = {}) {
     await this.ensureInitialized()
 
-    const connection = this.connection()
-    const acquired = await connection.tryAcquireAdvisoryLock(name)
-
-    if (!acquired) {
-      throw new AdvisoryLockBusyError(`Advisory lock ${JSON.stringify(name)} is already held`, {name})
-    }
+    const runner = new AdvisoryLockRunner({
+      configuration: this._getConfiguration(),
+      connectionProvider: () => this.connection(),
+      databaseIdentifier: this.getDatabaseIdentifier()
+    })
 
-    try {
-      return await this.runWithAdvisoryLockHoldTimeout(name, callback, args.holdTimeoutMs)
-    } finally {
-      await connection.releaseAdvisoryLock(name)
-    }
+    return await runner.withAdvisoryLockOrFail(name, callback, args)
   }
 
   /**
    * Runs `callback`, rejecting with `AdvisoryLockHoldTimeoutError` if it has
-   * not settled within `holdTimeoutMs`. The caller's `finally` then releases
-   * the lock, so a hung holder can't block other sessions forever. The
-   * callback is not cancelled — this is a safety net, not cancellation.
-   *
-   * Uses `awaitery`'s shared `timeout` helper for the hard timeout, then
-   * translates its timeout into the typed `AdvisoryLockHoldTimeoutError` so
-   * callers can catch it like the other advisory-lock errors. A `callbackSettled`
-   * flag distinguishes the timeout from a rejection thrown by the callback
-   * itself, which is rethrown unchanged.
+   * not settled within `holdTimeoutMs`. The callback is not cancelled — this is
+   * a safety net, not cancellation.
    * @template T
    * @param {string} name - Lock name (for the error message).
    * @param {() => Promise<T>} callback - Callback holding the lock.
@@ -2757,27 +2689,7 @@ class VelociousDatabaseRecord {
    * @returns {Promise<T>}
    */
   static async runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs) {
-    if (!holdTimeoutMs || holdTimeoutMs <= 0) {
-      return await callback()
-    }
-
-    let callbackSettled = false
-
-    try {
-      return await timeout({timeout: holdTimeoutMs}, async () => {
-        try {
-          return await callback()
-        } finally {
-          callbackSettled = true
-        }
-      })
-    } catch (error) {
-      if (!callbackSettled) {
-        throw new AdvisoryLockHoldTimeoutError(`Advisory lock ${JSON.stringify(name)} held longer than ${holdTimeoutMs}ms`, {name})
-      }
-
-      throw error
-    }
+    return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs)
   }
 
   /**

package/src/database/tenants/schema-cloner.js

@@ -152,7 +152,8 @@ export default class SchemaCloner {
 
   /**
    * Creates non-primary-key indexes present on the source but missing from the target,
-   * and throws if an existing target index diverges from the source.
+   * and replaces target indexes whose definition (columns or uniqueness) drifted from
+   * the source.
    * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args
    * @returns {Promise<void>}
    */
@@ -161,7 +162,7 @@ export default class SchemaCloner {
     /** @type {Map<string, import("../drivers/base-columns-index.js").default>} */
     const targetIndexesByName = new Map()
     const targetIndexSignatures = new Set()
-    let createdIndex = false
+    let dirty = false
 
     for (const targetIndex of await targetTable.getIndexes()) {
       targetIndexesByName.set(targetIndex.getName(), targetIndex)
@@ -183,28 +184,63 @@ export default class SchemaCloner {
 
       const targetIndex = this.targetDb.getType() === "sqlite" ? undefined : targetIndexesByName.get(sourceIndex.getName())
 
-      if (!targetIndex) {
-        const createIndexSqls = await this.targetDb.createIndexSQLs(this.createIndexArgsFromSourceIndex({sourceIndex, tableName}))
-
-        for (const createIndexSql of createIndexSqls) {
-          await this.targetDb.query(createIndexSql)
+      if (targetIndex) {
+        if (!this.indexesMatch(sourceIndex, targetIndex)) {
+          // Replacing a non-unique index with a unique one is unsafe because
+          // the target may have duplicate values that will reject the new
+          // unique constraint, and the old index was already dropped by this
+          // point. The opposite direction (unique → non-unique) is always
+          // safe — non-unique indexes never fail on duplicate values.
+          if (sourceIndex.isUnique() && !targetIndex.isUnique()) {
+            throw new Error(`Schema clone index drift for ${tableName}.${sourceIndex.getName()}: cannot safely replace a non-unique index with a unique one.`)
+          }
+
+          await this.dropTargetIndex({tableName, targetIndex})
+          targetIndexesByName.delete(targetIndex.getName())
+          targetIndexSignatures.delete(this.indexSignature(targetIndex))
+        } else {
+          continue
         }
+      }
 
-        createdIndex = true
-        targetIndexSignatures.add(sourceIndexSignature)
-        continue
+      // Drop any target index that shares the source name but survived the
+      // drift check above because the driver was skipped (SQLite).
+      const sameNameTargetIndex = targetIndexesByName.get(sourceIndex.getName())
+
+      if (sameNameTargetIndex) {
+        await this.dropTargetIndex({tableName, targetIndex: sameNameTargetIndex})
+        targetIndexesByName.delete(sameNameTargetIndex.getName())
+        targetIndexSignatures.delete(this.indexSignature(sameNameTargetIndex))
       }
 
-      if (!this.indexesMatch(sourceIndex, targetIndex)) {
-        throw new Error(`Schema clone index drift for ${tableName}.${sourceIndex.getName()}`)
+      const createIndexSqls = await this.targetDb.createIndexSQLs(this.createIndexArgsFromSourceIndex({sourceIndex, tableName}))
+
+      for (const createIndexSql of createIndexSqls) {
+        await this.targetDb.query(createIndexSql)
       }
+
+      dirty = true
+      targetIndexSignatures.add(sourceIndexSignature)
     }
 
-    if (createdIndex) {
+    if (dirty) {
       this.targetDb.clearSchemaCache()
     }
   }
 
+  /**
+   * Drops an index on the target database.
+   * @param {{tableName: string, targetIndex: import("../drivers/base-columns-index.js").default}} args
+   * @returns {Promise<void>}
+   */
+  async dropTargetIndex({tableName, targetIndex}) {
+    const dropSqls = await this.targetDb.removeIndexSQLs({name: targetIndex.getName(), tableName})
+
+    for (const sql of dropSqls) {
+      await this.targetDb.query(sql)
+    }
+  }
+
   /**
    * Baselines the target ledger so the cloned schema is recorded as already-applied.
    * @returns {Promise<string[]>} The versions newly recorded on the target.

package/src/frontend-models/resource-definition.js

@@ -282,6 +282,150 @@ export function frontendModelSyncManifestForBackendProjects(backendProjects) {
   return manifest
 }
 
+/**
+ * Builds a frontend-safe API manifest for all registered frontend-model
+ * resources. The manifest is deterministic (sorted model names, sorted
+ * attributes, sorted commands) and includes only public-safe metadata: no
+ * secrets, no server callbacks, no backend file paths.
+ * @param {import("../configuration-types.js").BackendProjectConfiguration[]} backendProjects - Backend projects to scan.
+ * @returns {Record<string, unknown>} - Frontend-safe API manifest.
+ */
+export function frontendModelApiManifest(backendProjects) {
+  /** @type {Record<string, unknown>} */
+  const resources = {}
+
+  for (const backendProject of backendProjects) {
+    const projectResources = frontendModelResourcesForBackendProject(backendProject)
+
+    for (const configuredModelName of Object.keys(projectResources).sort()) {
+      const resourceDefinition = projectResources[configuredModelName]
+      const resourceConfiguration = frontendModelResourceConfigurationFromDefinition(resourceDefinition)
+
+      if (!resourceConfiguration) continue
+
+      const modelName = resourceConfiguration.modelName || configuredModelName
+      const resourcePath = `/${inflection.dasherize(inflection.pluralize(inflection.underscore(configuredModelName)))}`
+
+      /** @type {Record<string, unknown>} */
+      const entry = {
+        modelName,
+        path: resourcePath,
+        primaryKey: resourceConfiguration.primaryKey || "id",
+        attributes: manifestAttributes(resourceConfiguration.attributes),
+        abilities: resourceConfiguration.abilities,
+        builtInCommands: {
+          collection: resourceConfiguration.builtInCollectionCommands,
+          member: resourceConfiguration.builtInMemberCommands
+        }
+      }
+
+      const relationships = resourceConfiguration.relationships
+      if (relationships && relationships.length > 0) {
+        /** @type {Record<string, unknown>} */
+        const rels = {}
+        for (const relName of relationships) {
+          rels[relName] = {}
+        }
+        entry.relationships = rels
+      }
+
+      const attachments = resourceConfiguration.attachments
+      if (attachments && Object.keys(attachments).length > 0) {
+        entry.attachments = attachments
+      }
+
+      const collectionCommands = manifestCommandEntries({
+        commandMetadata: resourceConfiguration.commandMetadata || {},
+        commands: resourceConfiguration.collectionCommands,
+        resourcePath,
+        scope: "collection"
+      })
+      const memberCommands = manifestCommandEntries({
+        commandMetadata: resourceConfiguration.commandMetadata || {},
+        commands: resourceConfiguration.memberCommands,
+        resourcePath,
+        scope: "member"
+      })
+
+      if (collectionCommands.length > 0 || memberCommands.length > 0) {
+        /** @type {Record<string, unknown>} */
+        const cmds = {}
+        if (collectionCommands.length > 0) cmds["collection"] = collectionCommands
+        if (memberCommands.length > 0) cmds["member"] = memberCommands
+        entry.commands = cmds
+      }
+
+      if (resourceConfiguration.sync?.enabled) {
+        entry.sync = resourceConfiguration.sync
+      }
+
+      resources[configuredModelName] = entry
+    }
+  }
+
+  return {
+    formatVersion: 1,
+    resources: Object.keys(resources).sort().reduce((sorted, key) => {
+      /** @type {Record<string, unknown>} */ (sorted)[key] = resources[key]
+      return sorted
+    }, /** @type {Record<string, unknown>} */ ({}))
+  }
+}
+
+/**
+ * Normalizes resource attribute definitions into a sorted array of strings.
+ * @param {?} attributes - Raw attributes config (array or object).
+ * @returns {string[]} - Sorted attribute names.
+ */
+function manifestAttributes(attributes) {
+  if (!attributes) return []
+
+  let names
+
+  if (Array.isArray(attributes)) {
+    names = attributes.map((entry) => typeof entry === "string" ? entry : entry.name).filter(Boolean)
+  } else if (attributes && typeof attributes === "object") {
+    names = Object.keys(attributes)
+  } else {
+    return []
+  }
+
+  return names.sort()
+}
+
+/**
+ * Builds manifest-safe command entry list.
+ * @param {object} args - Arguments.
+ * @param {Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>} args.commandMetadata - Per-command metadata.
+ * @param {Record<string, string>} args.commands - Method name → kebab slug map.
+ * @param {string} args.resourcePath - Resource path.
+ * @param {"collection" | "member"} args.scope - Command scope.
+ * @returns {Record<string, unknown>[]} - Manifest command entries.
+ */
+function manifestCommandEntries({commandMetadata, commands, resourcePath, scope}) {
+  return Object.keys(commands).sort().map((methodName) => {
+    const slug = commands[methodName]
+    const metadata = commandMetadata[methodName] || {args: [], returnType: null}
+    const path = scope === "member"
+      ? `${resourcePath}/<id>/${slug}`
+      : `${resourcePath}/${slug}`
+
+    /** @type {Record<string, unknown>} */
+    const entry = {
+      methodName,
+      scope,
+      path,
+      args: metadata.args
+    }
+
+    if (metadata.returnType) {
+      entry.returnType = metadata.returnType
+    }
+
+    return entry
+  })
+}
+
 /**
  * Normalizes sync policy metadata and computes a deterministic hash from safe policy inputs.
  * @param {import("../configuration-types.js").FrontendModelResourceConfiguration} resourceConfiguration - Raw resource configuration.

package/src/routes/built-in/api-manifest/controller.js

@@ -0,0 +1,14 @@
+import Controller from "../../../controller.js"
+
+export default class BuiltInApiManifestController extends Controller {
+  /**
+   * Runs show.
+   * @returns {Promise<void>} - Resolves when the manifest has been rendered.
+   */
+  async show() {
+    const manifest = await this.getConfiguration().getApiManifest()
+
+    this._response.setHeader("Content-Type", "application/json; charset=UTF-8")
+    this._response.setBody(`${JSON.stringify(manifest, null, 2)}\n`)
+  }
+}

package/src/sync/sync-resource-base.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import {forcedNonBlankStringParam} from "typanic"
+import {forcedNonBlankString} from "typanic"
 
 import FrontendModelBaseResource from "../frontend-model-resource/base-resource.js"
 import SyncEnvelopeReplayService from "./sync-envelope-replay-service.js"
@@ -135,7 +135,7 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
     }
 
     const scopeParams = /** @type {Record<string, ?>} */ (scope)
-    const resourceType = forcedNonBlankStringParam(scopeParams, "resourceType")
+    const resourceType = forcedNonBlankString(scopeParams.resourceType, "resourceType")
     const conditions = scopeParams.conditions
 
     if (!conditions || typeof conditions !== "object" || Array.isArray(conditions)) {