@starlove/orbit 1.4.0 → 2.0.0

package/lib/adapters/sqlite/database.js

@@ -0,0 +1,285 @@
+/**
+ * Connections to Orbit's SQLite files, and the rules every statement runs
+ * under: SQLite never waits on the server's thread (busy_timeout 0, retried
+ * here on a timer), a database's own error never reaches an answer (each is
+ * mapped to the port's codes), and a file without v2's version is never
+ * opened for writing.
+ */
+import { randomUUID } from "node:crypto";
+import { closeSync, linkSync, openSync, readSync, renameSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { isOrbitError, OrbitError } from "../../core/errors.js";
+import { APPLICATION_ID, SCHEMA_VERSION } from "./schema.js";
+/**
+ * The port's code for each UNIQUE constraint in the schema, as SQLite names
+ * it ("UNIQUE constraint failed: states.name"). A repeated record id is
+ * `duplicate_id` everywhere.
+ */
+const UNIQUE_CODES = {
+    "boards.slug": "board_slug_taken",
+    "states.name": "state_name_taken",
+    "labels.name": "label_name_taken",
+    "tickets.number": "ticket_number_taken",
+    "relations.source_ticket_id, relations.target_ticket_id, relations.type": "relation_exists",
+    "cross_board_relations.source_ticket_id, cross_board_relations.target_board_id, cross_board_relations.target_ticket_id, cross_board_relations.type": "relation_exists"
+};
+const SQLITE_BUSY = 5;
+const SQLITE_LOCKED = 6;
+const SQLITE_FULL = 13;
+const SQLITE_CONSTRAINT_FOREIGNKEY = 787;
+const SQLITE_CONSTRAINT_PRIMARYKEY = 1555;
+const SQLITE_CONSTRAINT_UNIQUE = 2067;
+/** SQLite's code from its message, for a Node whose errors don't carry `errcode`. */
+function codeFromMessage(error) {
+    const message = error instanceof Error ? error.message : "";
+    if (/database (table )?is locked|database is busy/.test(message))
+        return SQLITE_BUSY;
+    if (message.includes("database or disk is full"))
+        return SQLITE_FULL;
+    if (message.includes("FOREIGN KEY constraint failed"))
+        return SQLITE_CONSTRAINT_FOREIGNKEY;
+    if (message.startsWith("UNIQUE constraint failed"))
+        return SQLITE_CONSTRAINT_UNIQUE;
+    return undefined;
+}
+/** An OrbitError for anything a statement throws, the original kept as its cause. */
+export function storageError(error, meaning = {}) {
+    if (isOrbitError(error))
+        return error;
+    const code = error?.errcode ?? codeFromMessage(error);
+    if (typeof code !== "number")
+        return new OrbitError("storage_failed", { cause: error });
+    const primary = code & 0xff;
+    if (primary === SQLITE_BUSY || primary === SQLITE_LOCKED)
+        return new OrbitError("storage_busy", { cause: error });
+    if (primary === SQLITE_FULL)
+        return new OrbitError("storage_full", { cause: error });
+    if (code === SQLITE_CONSTRAINT_FOREIGNKEY)
+        return new OrbitError(meaning.foreignKey ?? "invalid_reference", { cause: error });
+    if (code === SQLITE_CONSTRAINT_UNIQUE || code === SQLITE_CONSTRAINT_PRIMARYKEY) {
+        const columns = error.message.replace(/^UNIQUE constraint failed: /, "");
+        const known = UNIQUE_CODES[columns] ?? (/^\w+\.id$/.test(columns) ? "duplicate_id" : undefined);
+        if (known)
+            return new OrbitError(known, { cause: error });
+    }
+    return new OrbitError("storage_failed", { cause: error });
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Runs `attempt` until it isn't refused as busy, waiting on a timer between
+ * tries (1 ms, doubling to 50 ms), so the thread stays free for everything
+ * else. After `deadline` (a Date.now() value) the refusal stands: `storage_busy`.
+ */
+export async function untilFree(attempt, deadline) {
+    let delay = 1;
+    for (;;) {
+        try {
+            return attempt();
+        }
+        catch (error) {
+            const mapped = storageError(error);
+            if (mapped.code !== "storage_busy" || Date.now() + delay > deadline)
+                throw mapped;
+            await sleep(delay);
+            delay = Math.min(delay * 2, 50);
+        }
+    }
+}
+/** One connection to one file, with each statement prepared once. */
+export class Connection {
+    path;
+    db;
+    prepared = new Map();
+    closed = false;
+    constructor(path, options = {}) {
+        this.path = path;
+        try {
+            this.db = new DatabaseSync(path);
+        }
+        catch (error) {
+            throw storageError(error);
+        }
+        try {
+            this.db.exec(`PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 0; PRAGMA synchronous = NORMAL;${options.queryOnly ? " PRAGMA query_only = ON;" : ""}`);
+        }
+        catch (error) {
+            this.db.close();
+            throw storageError(error);
+        }
+    }
+    exec(sql) {
+        try {
+            this.db.exec(sql);
+        }
+        catch (error) {
+            throw storageError(error);
+        }
+    }
+    statement(sql) {
+        let statement = this.prepared.get(sql);
+        if (!statement) {
+            statement = this.db.prepare(sql);
+            this.prepared.set(sql, statement);
+        }
+        return statement;
+    }
+    run(sql, params = [], meaning) {
+        try {
+            const result = this.statement(sql).run(...params);
+            return { changes: Number(result.changes), lastInsertRowid: Number(result.lastInsertRowid) };
+        }
+        catch (error) {
+            throw storageError(error, meaning);
+        }
+    }
+    get(sql, params = [], meaning) {
+        try {
+            return this.statement(sql).get(...params);
+        }
+        catch (error) {
+            throw storageError(error, meaning);
+        }
+    }
+    all(sql, params = []) {
+        try {
+            return this.statement(sql).all(...params);
+        }
+        catch (error) {
+            throw storageError(error);
+        }
+    }
+    /**
+     * Ends a transaction left open by a failure; quiet if there is none (SQLite
+     * may have ended it with the failure). It asks SQLite by trying, which
+     * reads the same on every Node.
+     */
+    rollback() {
+        if (this.closed)
+            return;
+        try {
+            this.db.exec("ROLLBACK");
+        }
+        catch {
+            // No transaction was open.
+        }
+    }
+    /** Ends a read's transaction. */
+    finishRead() {
+        if (this.closed)
+            return;
+        try {
+            this.db.exec("COMMIT");
+        }
+        catch {
+            this.rollback();
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.prepared.clear();
+        this.db.close();
+    }
+}
+// The files themselves
+/** The header fields that say whose file it is (SQLite's file format: offsets 60 and 68, big-endian). */
+function readHeader(path) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new OrbitError("storage_failed", { cause: error });
+    }
+    try {
+        const header = Buffer.alloc(100);
+        const length = readSync(fd, header, 0, 100, 0);
+        const sqlite = length === 100 && header.toString("latin1", 0, 16) === "SQLite format 3\0";
+        return { sqlite, userVersion: sqlite ? header.readInt32BE(60) : 0, applicationId: sqlite ? header.readInt32BE(68) : 0 };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const OLDER_DATA = "This data folder holds boards from an older Orbit (1.x, or 2.0 before its rebuild), which this Orbit doesn't open. Nothing in it was changed. Keep it as it is: ";
+/**
+ * The way out for a folder of older data. The older Orbit's own default,
+ * ~/.orbit (os.homedir() reads HOME, as Orbit does), takes the short form,
+ * which reads it into this Orbit's default folder.
+ */
+function migrationNeeded(path) {
+    const older = join(homedir(), ".orbit");
+    if (resolve(path).startsWith(older + sep))
+        return `${OLDER_DATA}with DATA_DIR unset, \`orbit migrate\` brings its boards into ~/.starscape/orbit, the folder this Orbit uses, and orbit run then opens them.`;
+    return `${OLDER_DATA}\`orbit migrate <this folder> --to <a new folder>\` brings its boards into a new folder, and DATA_DIR then points there.`;
+}
+const NEWER_ORBIT = "This data folder was written by a newer Orbit. Nothing in it was changed. Update Orbit to open it.";
+/**
+ * Whether the file at `path` is one this build may open: true when it is v2's
+ * at this schema version, false when there is no file. Anything else is
+ * refused without being opened, so its bytes stay as they are: a file of 1.x
+ * or the first 2.0 (no version) with `data_needs_migration`, a newer
+ * schema's with `data_from_newer_orbit`.
+ */
+export function checkFile(path) {
+    const header = readHeader(path);
+    if (header === null)
+        return false;
+    if (!header.sqlite)
+        throw new OrbitError("storage_failed", { message: `${basename(path)} in this data folder isn't a database.` });
+    if (header.applicationId !== APPLICATION_ID || header.userVersion < 1)
+        throw new OrbitError("data_needs_migration", { message: migrationNeeded(path) });
+    if (header.userVersion > SCHEMA_VERSION)
+        throw new OrbitError("data_from_newer_orbit", { message: NEWER_ORBIT });
+    // v2 has one schema version so far; a later one upgrades older v2 files here instead.
+    if (header.userVersion < SCHEMA_VERSION)
+        throw new OrbitError("data_needs_migration", { message: migrationNeeded(path) });
+    return true;
+}
+/**
+ * Makes a database at `path` with `schema`, all at once: it is built under a
+ * temporary name and linked into place, so no other process ever sees a file
+ * without its version, and when two make the same file at once one wins and
+ * the other's attempt is discarded. True when this call made it.
+ */
+export function createFile(path, schema) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.creating`);
+    try {
+        const db = new DatabaseSync(temporary);
+        try {
+            db.exec(`PRAGMA application_id = ${String(APPLICATION_ID)}; PRAGMA user_version = ${String(SCHEMA_VERSION)}; PRAGMA journal_mode = WAL;`);
+            db.exec(`BEGIN; ${schema} COMMIT;`);
+        }
+        finally {
+            db.close();
+        }
+        try {
+            linkSync(temporary, path);
+            return true;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "EEXIST")
+                return false;
+            if (code !== "EPERM" && code !== "ENOTSUP" && code !== "EXDEV")
+                throw error;
+            // A file system without hard links: a rename, checked first.
+            if (readHeader(path) !== null)
+                return false;
+            renameSync(temporary, path);
+            return true;
+        }
+    }
+    catch (error) {
+        throw storageError(error);
+    }
+    finally {
+        for (const suffix of ["", "-wal", "-shm", "-journal"])
+            rmSync(`${temporary}${suffix}`, { force: true });
+    }
+}

package/lib/adapters/sqlite/index.d.ts

@@ -0,0 +1,3 @@
+export { openSqliteStore } from "./store.ts";
+export type { SqliteStore, SqliteStoreOptions } from "./store.ts";
+export { createSqliteBlobStore } from "./blobs.ts";

package/lib/adapters/sqlite/index.js

@@ -0,0 +1,2 @@
+export { openSqliteStore } from "./store.js";
+export { createSqliteBlobStore } from "./blobs.js";

package/lib/adapters/sqlite/lock.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runs bodies one at a time, in the order they asked: the in-process half of
+ * keeping a board's writes one at a time (SQLite's write lock is the other,
+ * between processes).
+ */
+export declare class Lock {
+    private tail;
+    /** Waits for every earlier holder, then returns the function that lets go. */
+    acquire(): Promise<() => void>;
+    run<T>(body: () => Promise<T>): Promise<T>;
+}

package/lib/adapters/sqlite/lock.js

@@ -0,0 +1,34 @@
+/**
+ * Runs bodies one at a time, in the order they asked: the in-process half of
+ * keeping a board's writes one at a time (SQLite's write lock is the other,
+ * between processes).
+ */
+export class Lock {
+    tail = Promise.resolve();
+    /** Waits for every earlier holder, then returns the function that lets go. */
+    async acquire() {
+        let release = () => undefined;
+        const next = new Promise((resolve) => {
+            release = resolve;
+        });
+        const previous = this.tail;
+        this.tail = previous.then(() => next);
+        await previous;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            release();
+        };
+    }
+    async run(body) {
+        const release = await this.acquire();
+        try {
+            return await body();
+        }
+        finally {
+            release();
+        }
+    }
+}

package/lib/adapters/sqlite/records.d.ts

@@ -0,0 +1,54 @@
+/**
+ * One board's records in SQL: the port's BoardReader and BoardWriter over a
+ * connection. Each method is one statement, prepared once per connection, and
+ * reads that serve a whole board return every row at once. Records come back
+ * built field for field in the order src/core/model.ts lists them, with the
+ * board's id added where a record names its board (board.db holds one board,
+ * so its rows don't repeat it).
+ */
+import type { Board, CrossBoardRelation, Id, OrbitEvent } from "../../core/model.ts";
+import type { BoardReader, BoardWriter } from "../../store/types.ts";
+import type { Connection, Row } from "./database.ts";
+/** A kind of record: its table, its fields in the model's order, and the statements every kind shares. */
+interface Kind<T> {
+    table: string;
+    fields: readonly (keyof T & string)[];
+    /** The fields stored as columns: all but `board_id`. */
+    columns: readonly string[];
+    select: string;
+    insert: string;
+}
+export declare const BOARD: Kind<Board>;
+export declare const CROSS: Kind<CrossBoardRelation>;
+export declare const EVENT: Kind<OrbitEvent>;
+/** The record a row holds, built in the model's field order. */
+export declare function toRecord<T>(of: Kind<T>, row: Row, boardId: Id): T;
+/** What a reader or writer works over. */
+export interface Over {
+    c: Connection;
+    boardId: Id;
+    /** Awaited before each call: the writer's check that its write is still open. */
+    before: () => Promise<void>;
+}
+/** For readers, which have nothing to check before a call. */
+export declare const noWait: () => Promise<void>;
+/** The port's BoardReader over a connection. */
+export declare function reader({ c, boardId, before }: Over): BoardReader;
+/** What a write did that its store acts on once it commits. */
+export interface WriteLog {
+    /** Events appended, with their place in the board's history. */
+    events: {
+        seq: number;
+        event: OrbitEvent;
+    }[];
+    /** The board's own record as the write left it, when the write changed it. */
+    board: Board | null;
+}
+/** Checks a writer makes against the rest of the data folder. */
+export interface WriteChecks {
+    /** Another board has this slug. */
+    slugTaken(slug: string): boolean;
+}
+/** The port's BoardWriter over a connection in an open transaction. */
+export declare function writer(over: Over, log: WriteLog, checks: WriteChecks): BoardWriter;
+export {};