velocious 1.0.430 → 1.0.432

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

@@ -0,0 +1,394 @@
+// @ts-check
+
+import {createHash} from "node:crypto"
+import wait from "awaitery/build/wait.js"
+import fs from "fs/promises"
+import os from "node:os"
+import path from "node:path"
+import query from "./query.js"
+import sqlite3 from "sqlite3"
+import {open} from "sqlite"
+
+import Base from "./base.js"
+import fileExists from "../../../utils/file-exists.js"
+
+export default class VelociousDatabaseDriversSqliteNode extends Base {
+  /**
+   * Connection.
+    @type {import("sqlite3").Database | undefined} */
+  connection = undefined
+
+  /**
+   * Advisory lock directory.
+    @type {string | undefined} */
+  _advisoryLockDirectory = undefined
+
+  async connect() {
+    const args = this.getArgs()
+    const databaseDir = `${this.getConfiguration().getDirectory()}/db`
+    const databasePath = `${databaseDir}/${this.localStorageName()}.sqlite`
+
+    if (!await fileExists(databaseDir)) {
+      await fs.mkdir(databaseDir, {recursive: true})
+    }
+
+    if (args.reset) {
+      await fs.unlink(databasePath)
+    }
+
+    this._advisoryLockDirectory = path.join(databaseDir, `${this.localStorageName()}.velocious-advisory-locks`)
+
+    try {
+      // @ts-expect-error
+      this.connection = /** Narrows the runtime value to the documented type. @type {import("sqlite3").Database} */ (await open({
+        filename: databasePath,
+        driver: sqlite3.Database
+      }))
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Couldn't open database ${databasePath} because of ${error.constructor.name}: ${error.message}`, {cause: error})
+      } else {
+        throw new Error(`Couldn't open database ${databasePath} because of ${typeof error}: ${error}`, {cause: error})
+      }
+    }
+
+    await this.registerVersion()
+  }
+
+  localStorageName() {
+    const args = this.getArgs()
+
+    if (!args.name) throw new Error("No name given for SQLite Node")
+
+    return `VelociousDatabaseDriversSqlite---${args.name}`
+  }
+
+  async close() {
+    await this.connection?.close()
+    this.connection = undefined
+  }
+
+  /**
+   * Runs query actual.
+   * @param {string} sql - SQL string.
+   * @returns {Promise<Record<string, ?>[]>} - Resolves with the query actual.
+   */
+  async _queryActual(sql) {
+    if (!this.connection) throw new Error("No connection")
+
+    return await query(this.connection, sql)
+  }
+
+  /**
+   * Layers a filesystem lock directory on top of the in-process waiter
+   * queue so SQLite deployments with multiple Node processes writing to
+   * the same database file see consistent advisory-lock mutual exclusion
+   * across processes, not just within a single process.
+   *
+   * The in-process queue from the shared SQLite base class is still used
+   * for the fast intra-process path (no polling, waiters wake each other
+   * through the `Set<string>` + waiter queue); the filesystem lock is
+   * only checked once the in-process queue has granted the caller, so
+   * typical single-process traffic pays at most two `fs.mkdir` calls
+   * (create and remove) per critical section.
+   * @param {string} name - Lock name.
+   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
+   * @returns {Promise<boolean>}
+   */
+  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+    const deadline = typeof timeoutMs === "number" && timeoutMs >= 0 ? Date.now() + timeoutMs : null
+    const remainingForInProcess = deadline !== null ? Math.max(0, deadline - Date.now()) : null
+    const inProcessAcquired = await super.acquireAdvisoryLock(name, {timeoutMs: remainingForInProcess})
+
+    if (!inProcessAcquired) return false
+
+    try {
+      const remainingForFile = deadline !== null ? Math.max(0, deadline - Date.now()) : null
+      const fileAcquired = await this._acquireAdvisoryLockFile(name, {timeoutMs: remainingForFile})
+
+      if (!fileAcquired) {
+        await super.releaseAdvisoryLock(name)
+        return false
+      }
+    } catch (error) {
+      await super.releaseAdvisoryLock(name)
+      throw error
+    }
+
+    return true
+  }
+
+  /**
+   * Runs try acquire advisory lock.
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>}
+   */
+  async tryAcquireAdvisoryLock(name) {
+    const inProcessAcquired = await super.tryAcquireAdvisoryLock(name)
+
+    if (!inProcessAcquired) return false
+
+    try {
+      const fileAcquired = await this._tryAcquireAdvisoryLockFile(name)
+
+      if (!fileAcquired) {
+        await super.releaseAdvisoryLock(name)
+        return false
+      }
+    } catch (error) {
+      await super.releaseAdvisoryLock(name)
+      throw error
+    }
+
+    return true
+  }
+
+  /**
+   * Releases the lock only if **this** driver instance acquired it, both
+   * in the shared in-process owner table and in the on-disk lock
+   * directory. A caller that tries to release a lock it never acquired
+   * (or that was already released by another driver) gets `false` back
+   * and the filesystem state is left alone so we never delete somebody
+   * else's lock directory.
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>}
+   */
+  async releaseAdvisoryLock(name) {
+    const inProcessReleased = await super.releaseAdvisoryLock(name)
+
+    if (inProcessReleased) {
+      await this._releaseAdvisoryLockFile(name)
+    }
+
+    return inProcessReleased
+  }
+
+  /**
+   * Runs is advisory lock held.
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>}
+   */
+  async isAdvisoryLockHeld(name) {
+    if (await super.isAdvisoryLockHeld(name)) return true
+
+    return await this._isAdvisoryLockFileHeld(name)
+  }
+
+  /**
+   * Runs resolve advisory lock directory.
+    @returns {string} */
+  _resolveAdvisoryLockDirectory() {
+    if (!this._advisoryLockDirectory) {
+      // Fall back to deriving the directory for callers that invoked
+      // advisory lock methods before `connect()` wired the field in.
+      const databaseDir = `${this.getConfiguration().getDirectory()}/db`
+
+      this._advisoryLockDirectory = path.join(databaseDir, `${this.localStorageName()}.velocious-advisory-locks`)
+    }
+
+    return this._advisoryLockDirectory
+  }
+
+  /**
+   * Runs advisory lock path.
+   * @param {string} name - Lock name.
+   * @returns {string}
+   */
+  _advisoryLockPath(name) {
+    const hash = createHash("sha256").update(name).digest("hex").slice(0, 16)
+    const safeName = name.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 64)
+
+    return path.join(this._resolveAdvisoryLockDirectory(), `${safeName}-${hash}.lock`)
+  }
+
+  /**
+   * Runs ensure advisory lock directory.
+    @returns {Promise<void>} */
+  async _ensureAdvisoryLockDirectory() {
+    await fs.mkdir(this._resolveAdvisoryLockDirectory(), {recursive: true})
+  }
+
+  /**
+   * Runs write advisory lock metadata.
+   * @param {string} lockDirPath - Absolute path of the lock directory.
+   * @returns {Promise<void>}
+   */
+  async _writeAdvisoryLockMetadata(lockDirPath) {
+    const ownerPath = path.join(lockDirPath, "owner.json")
+    const payload = JSON.stringify({
+      pid: process.pid,
+      hostname: os.hostname(),
+      acquiredAt: new Date().toISOString()
+    })
+
+    await fs.writeFile(ownerPath, payload)
+  }
+
+  /**
+   * Runs acquire advisory lock file.
+   * @param {string} name - Lock name.
+   * @param {{timeoutMs?: number | null}} args - Timeout args.
+   * @returns {Promise<boolean>}
+   */
+  async _acquireAdvisoryLockFile(name, {timeoutMs}) {
+    await this._ensureAdvisoryLockDirectory()
+
+    const lockPath = this._advisoryLockPath(name)
+    const deadline = typeof timeoutMs === "number" && timeoutMs >= 0 ? Date.now() + timeoutMs : null
+    const pollIntervalMs = 50
+
+    // Intentionally looping without a fixed iteration cap — either the
+    // mkdir succeeds, the deadline elapses, or an unexpected error is
+    // re-thrown.
+    while (true) {
+      try {
+        await fs.mkdir(lockPath)
+        await this._writeAdvisoryLockMetadata(lockPath)
+
+        return true
+      } catch (error) {
+        if (/**
+             * Narrows the runtime value to the documented type.
+              @type {NodeJS.ErrnoException} */ (error)?.code !== "EEXIST") throw error
+
+        if (await this._isAdvisoryLockStale(lockPath)) {
+          await fs.rm(lockPath, {recursive: true, force: true})
+          continue
+        }
+
+        if (deadline !== null) {
+          const remaining = deadline - Date.now()
+
+          if (remaining <= 0) return false
+
+          await wait(Math.min(pollIntervalMs, remaining))
+        } else {
+          await wait(pollIntervalMs)
+        }
+      }
+    }
+  }
+
+  /**
+   * Runs try acquire advisory lock file.
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>}
+   */
+  async _tryAcquireAdvisoryLockFile(name) {
+    await this._ensureAdvisoryLockDirectory()
+
+    const lockPath = this._advisoryLockPath(name)
+
+    try {
+      await fs.mkdir(lockPath)
+      await this._writeAdvisoryLockMetadata(lockPath)
+
+      return true
+    } catch (error) {
+      if (/**
+           * Narrows the runtime value to the documented type.
+            @type {NodeJS.ErrnoException} */ (error)?.code !== "EEXIST") throw error
+
+      if (await this._isAdvisoryLockStale(lockPath)) {
+        await fs.rm(lockPath, {recursive: true, force: true})
+
+        try {
+          await fs.mkdir(lockPath)
+          await this._writeAdvisoryLockMetadata(lockPath)
+
+          return true
+        } catch (retryError) {
+          if (/**
+               * Narrows the runtime value to the documented type.
+                @type {NodeJS.ErrnoException} */ (retryError)?.code === "EEXIST") return false
+
+          throw retryError
+        }
+      }
+
+      return false
+    }
+  }
+
+  /**
+   * Runs release advisory lock file.
+   * @param {string} name - Lock name.
+   * @returns {Promise<void>}
+   */
+  async _releaseAdvisoryLockFile(name) {
+    const lockPath = this._advisoryLockPath(name)
+
+    try {
+      await fs.rm(lockPath, {recursive: true, force: true})
+    } catch {
+      // Best-effort release; in-process state is still authoritative and
+      // stale-lock cleanup on the next acquire will remove the directory
+      // if it really is still lingering.
+    }
+  }
+
+  /**
+   * Runs is advisory lock file held.
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>}
+   */
+  async _isAdvisoryLockFileHeld(name) {
+    const lockPath = this._advisoryLockPath(name)
+
+    try {
+      await fs.stat(lockPath)
+    } catch {
+      return false
+    }
+
+    return !await this._isAdvisoryLockStale(lockPath)
+  }
+
+  /**
+   * A lock directory is considered stale when its owner metadata names a
+   * PID on this host that is no longer running. Cross-host ownership (a
+   * different `hostname`) is treated as live because we cannot reliably
+   * probe a PID on another machine; operators in that situation should
+   * remove stale lock directories by hand if they linger.
+   * @param {string} lockPath - Absolute path of the lock directory.
+   * @returns {Promise<boolean>}
+   */
+  async _isAdvisoryLockStale(lockPath) {
+    /**
+     * Defines rawOwner.
+      @type {string} */
+    let rawOwner
+
+    try {
+      rawOwner = await fs.readFile(path.join(lockPath, "owner.json"), "utf8")
+    } catch {
+      // Missing or unreadable metadata — treat as stale so we can reclaim.
+      return true
+    }
+
+    /**
+     * Defines owner.
+      @type {{pid?: number, hostname?: string}} */
+    let owner
+
+    try {
+      owner = JSON.parse(rawOwner)
+    } catch {
+      return true
+    }
+
+    if (!owner || typeof owner.pid !== "number") return true
+    if (owner.hostname && owner.hostname !== os.hostname()) return false
+
+    try {
+      // `kill(pid, 0)` is a no-op signal that fails with ESRCH if the
+      // process is not running; permission errors still indicate the
+      // process exists so we treat those as "not stale".
+      process.kill(owner.pid, 0)
+
+      return false
+    } catch (error) {
+      return /** Narrows the runtime value to the documented type. @type {NodeJS.ErrnoException} */ (error)?.code === "ESRCH"
+    }
+  }
+}

package/src/database/drivers/sqlite/index.native.js

@@ -0,0 +1,72 @@
+import {digg} from "diggerize"
+import envSense from "env-sense/build/use-env-sense.js"
+
+// @ts-expect-error
+import query from "./query"
+
+// @ts-expect-error
+import * as SQLite from "expo-sqlite"
+
+import Base from "./base.js"
+
+export default class VelociousDatabaseDriversSqliteNative extends Base {
+  async connect() {
+    const {isBrowser, isNative, isServer} = envSense()
+
+    if (!isNative) throw new Error(`SQLite native driver running inside non-native environment: ${JSON.stringify({isBrowser, isNative, isServer})}`)
+
+    const args = this.getArgs()
+
+    if (!args.name) throw new Error("No name given for SQLite Native")
+
+    const databaseName = args.name
+
+    if (args.reset) {
+      try {
+        await SQLite.deleteDatabaseAsync(databaseName)
+      } catch (error) {
+        if (error instanceof Error && error.message.match(/Database '(.+)' not found/)) {
+          // Ignore not found
+        } else {
+          throw error
+        }
+      }
+    }
+
+    this.connection = await SQLite.openDatabaseAsync(databaseName)
+    await this.registerVersion()
+  }
+
+  connectArgs() {
+    const args = this.getArgs()
+    /**
+     * Connect args.
+      @type {Record<string, ?>} */
+    const connectArgs = {}
+    const forward = ["database", "host", "password"]
+
+    for (const forwardValue of forward) {
+      if (forwardValue in args) connectArgs[forwardValue] = digg(args, forwardValue)
+    }
+
+    if ("username" in args) connectArgs["user"] = args["username"]
+
+    return connectArgs
+  }
+
+  async close() {
+    await this.connection.closeAsync()
+    this.connection = undefined
+  }
+
+  /**
+   * Runs query actual.
+   * @param {string} sql - SQL string.
+   * @returns {Promise<Record<string, ?>[]>} - Query result rows.
+   */
+  async _queryActual(sql) {
+    if (!this.connection) throw new Error("Not connected yet")
+
+    return await query(this.connection, sql)
+  }
+}

package/src/database/drivers/sqlite/index.web.js

@@ -0,0 +1,99 @@
+// @ts-check
+
+import BetterLocalStorage from "better-localstorage"
+import ConnectionSqlJs from "./connection-sql-js.js"
+import initSqlJs from "sql.js"
+
+import Base from "./base.js"
+
+/**
+ * VelociousDatabaseDriversSqliteWeb class.
+ * @typedef {{query: (sql: string) => Promise<Record<string, ?>[]>, close: () => Promise<void>}} SqliteWebConnection
+ */
+
+export default class VelociousDatabaseDriversSqliteWeb extends Base {
+  /**
+   * Better local storage.
+    @type {BetterLocalStorage | undefined} */
+  betterLocalStorage = undefined
+  /**
+   * Connection.
+    @type {ConnectionSqlJs | undefined} */
+  _connection = undefined
+
+  /**
+   * Runs sql js locate file.
+   * @returns {(file: string) => string} - locateFile callback for sql.js.
+   */
+  sqlJsLocateFile() {
+    const locateFile = this.getArgs().locateFile
+
+    if (typeof locateFile === "function") {
+      return locateFile
+    }
+
+    return (file) => `https://sql.js.org/dist/${file}`
+  }
+
+  async connect() {
+    this.args = this.getArgs()
+
+    if (!this.args.getConnection) {
+      this.betterLocalStorage ||= new BetterLocalStorage()
+
+      if (this.args.reset) {
+        await this.betterLocalStorage.delete(this.localStorageName())
+      }
+
+      const SQL = await initSqlJs({locateFile: this.sqlJsLocateFile()})
+
+      const databaseContent = await this.betterLocalStorage.get(this.localStorageName())
+      const connectionSqlJs = new ConnectionSqlJs(this, new SQL.Database(databaseContent))
+
+      this._connection = connectionSqlJs
+    }
+  }
+
+  async close() {
+    await this.getConnection().close()
+  }
+
+  /**
+   * Runs get connection.
+   * @returns {ConnectionSqlJs | SqliteWebConnection} - The connection.
+   */
+  getConnection() {
+    if (this.args?.getConnection) {
+      return /** Narrows the runtime value to the documented type. @type {SqliteWebConnection} */ (this.args.getConnection())
+    } else {
+      if (!this._connection) throw new Error("SQLite web connection has not been initialized")
+      return this._connection
+    }
+  }
+
+  localStorageName() {
+    if (!this.args?.name) {
+      throw new Error("No name given in arguments for SQLite Web database")
+    }
+
+    return `VelociousDatabaseDriversSqliteWeb---${this.args?.name}`
+  }
+
+  /**
+   * Runs query actual.
+   * @param {string} sql - SQL string.
+   * @returns {Promise<Record<string, ?>[]>} - Resolves with the query actual.
+   */
+  async _queryActual(sql) {
+    const result = await this.getConnection().query(sql)
+
+    if (!Array.isArray(result)) {
+      const connection = this.getConnection()
+      const connectionName = connection?.constructor?.name || "UnknownConnection"
+
+      throw new Error(`Sqlite web connection ${connectionName} returned a non-array result: ${typeof result}`)
+    }
+
+    return result
+  }
+}

package/src/database/drivers/sqlite/options.js

@@ -0,0 +1,32 @@
+// @ts-check
+
+import QueryParserOptions from "../../query-parser/options.js"
+
+export default class VelociousDatabaseDriversSqliteOptions extends QueryParserOptions {
+  /**
+   * Runs constructor.
+   * @param {import("../base.js").default} driver - Database driver instance.
+   */
+  constructor(driver) {
+    const optionsArgs = {
+      driver,
+      columnQuote: "`",
+      indexQuote: "`",
+      stringQuote: "'",
+      tableQuote: "`"
+    }
+
+    super(optionsArgs)
+  }
+
+  /**
+   * Runs quote.
+   * @param {string} string - String.
+   * @returns {number | string} - The quote.
+   */
+  quote(string) {
+    if (!this.driver) throw new Error("Driver not set")
+
+    return this.driver.quote(string)
+  }
+}

package/src/database/drivers/sqlite/query-parser.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import BaseQueryParser from "../../query-parser/base-query-parser.js"
+
+export default class VelociousDatabaseConnectionDriversSqliteQueryParser extends BaseQueryParser {
+}

package/src/database/drivers/sqlite/query.js

@@ -0,0 +1,35 @@
+// @ts-check
+
+/**
+ * Runs query.
+ * @param {import("sqlite3").Database} connection - Connection.
+ * @param {string} sql - SQL string.
+ * @returns {Promise<Record<string, ?>[]>} - Resolves with string value.
+ */
+export default async function query(connection, sql) {
+  try {
+    /**
+     * Defines result.
+      @type {Record<string, ?>[]} */
+    let result
+
+    // @ts-expect-error
+    result = await connection.all(sql)
+
+    return result
+  } catch (error) {
+    let sqlInErrorMessage = `${sql}`
+
+    if (sqlInErrorMessage.length >= 4096) {
+      sqlInErrorMessage = `${sqlInErrorMessage.substring(0, 4096)}...`
+    }
+
+    if (error instanceof Error) {
+      error.message += `\n\n${sqlInErrorMessage}`
+
+      throw new Error(error.message, {cause: error})
+    } else {
+      throw new Error(`An error occurred: ${error}\n\n${sql}`, {cause: error})
+    }
+  }
+}

package/src/database/drivers/sqlite/query.native.js

@@ -0,0 +1,35 @@
+/**
+ * Run a query using the native SQLite async API.
+ * @param {import("sqlite3").Database & {getAllAsync: (sql: string) => Promise<Record<string, ?>[]>}} connection - SQLite connection instance.
+ * @param {string} sql - SQL string to execute.
+ * @returns {Promise<Record<string, ?>[]>} - Resolves with the result rows.
+ */
+export default async function query(connection, sql) {
+  const rows = []
+  let result
+
+  try {
+    result = await connection.getAllAsync(sql)
+  } catch (error) {
+    let sqlInErrorMessage = `${sql}`
+
+    if (sqlInErrorMessage.length >= 4096) {
+      sqlInErrorMessage = `${sqlInErrorMessage.substring(0, 4096)}...`
+    }
+
+    if (error instanceof Error) {
+      error.message += `\n\n${sqlInErrorMessage}`
+
+      // Re-throw to recover stack trace
+      throw new Error(error.message, {cause: error})
+    }
+
+    throw new Error(`An error occurred: ${error}\n\n${sqlInErrorMessage}`, {cause: error})
+  }
+
+  for await (const entry of result) {
+    rows.push(entry)
+  }
+
+  return rows
+}