@statewalker/cellb 0.0.0-stage → 0.1.1

package/dist/core/object-host.js

@@ -0,0 +1,616 @@
+import { sha256 } from "@noble/hashes/sha2";
+import { bytesToHex } from "@noble/hashes/utils";
+import { CELLD_SCHEMA, LOG_SEQ_READ, LOG_SEQ_WRITE, LOG_TABLE, scopeOf } from "./celld-schema.js";
+import { InputGate, OutputGate } from "./gates.js";
+import { asyncStub, isClassHandle, } from "./handles.js";
+import { DurableObjectId as DurableObjectIdClass } from "./id.js";
+import { SqlStorage } from "./sql-storage.js";
+import { DurableObjectState } from "./state.js";
+import { DurableObjectStorage, SyncKvStorage } from "./storage.js";
+export class BrokenObjectError extends Error {
+    constructor(cause, reason = "its storage failed to commit durably") {
+        const detail = cause instanceof Error ? `: ${cause.message}` : "";
+        super(`Durable Object reset because ${reason}${detail}`, { cause });
+        this.name = "BrokenObjectError";
+    }
+}
+/**
+ * One live instance of one Durable Object: its SQLite, gates and dispatcher.
+ * Everything that reaches the object (fetch, RPC, later alarms/WebSockets)
+ * goes through `deliver()`.
+ */
+export class ObjectHost {
+    cellKey;
+    #gate = new InputGate();
+    #out = new OutputGate();
+    /** The open database; `#driver` follows it, so it can be closed while idle and reopened. */
+    #db;
+    #driver = new Proxy({}, {
+        get: (_t, k) => {
+            const v = this.#db[k];
+            return typeof v === "function" ? v.bind(this.#db) : v;
+        },
+    });
+    #sql;
+    #instance;
+    #backup;
+    #backedUpSeq = 0;
+    #saving;
+    state;
+    #seq = 0;
+    broken = false;
+    #brokenCause;
+    /** blockConcurrencyWhile() rejected (CF: the object is reset; queued events fail). */
+    #breakOn(e) {
+        this.broken = true;
+        this.#brokenCause = e;
+    }
+    constructor(opts) {
+        this.#backup = opts.backup;
+        this.cellKey = opts.cellKey;
+        this.#epoch = opts.epoch;
+        this.#opts = opts;
+        this.#open = () => {
+            this.#db = opts.openSql(opts.cellKey);
+            for (const ext of opts.sqlExtensions ?? [])
+                this.#db.loadExtension(ext);
+        };
+        this.#open();
+        this.#sql = new SqlStorage(this.#driver, (changes) => {
+            if (changes && this.#epoch !== undefined)
+                changes.epoch = this.#epoch;
+            // Page-level logs (LTX): the changed pages straight from the page hook when the driver
+            // has one; the image only on demand (a generation's first snapshot, or no hook).
+            const d = this.#driver;
+            const seq = ++this.#seq;
+            const pages = opts.durability.capturePages ? d.takeDirtyPages() : undefined;
+            const snap = () => d.pageImage?.() ?? d.image?.();
+            // The log runs later, after the next event may have opened its transaction, and an
+            // image cannot be taken inside one (VACUUM INTO). When the log will surely need it
+            // (no page hook) or likely does (this host's first commit), take it now.
+            const image = opts.durability.capturePages
+                ? !pages || seq === 1
+                    ? snap()
+                    : snap
+                : undefined;
+            const durable = opts.durability.committed(this.cellKey, {
+                seq,
+                changes,
+                image,
+                pages,
+                epoch: this.#epoch,
+            });
+            const wake = this.#wakeAfterCommit();
+            return this.#out.track(wake ? durable.then(wake) : durable);
+        }, { capture: !!opts.durability.captureChanges });
+        // The cell's scope in celld's tables ("Class:idhex"), so its database is celld's format.
+        const kv = new SyncKvStorage(this.#sql, opts.codec, scopeOf(opts.cellKey));
+        if (!opts.facet)
+            kv.actorName = opts.id.name;
+        const storage = new DurableObjectStorage(this.#sql, kv, this.#gate, () => this.#barrier());
+        if (opts.onAlarmChange)
+            storage.onAlarmChange = opts.onAlarmChange;
+        storage.deleteAllPreservesAlarm = !!opts.deleteAllPreservesAlarm;
+        const state = new DurableObjectState(opts.id, storage, this.#gate, opts.waitUntil, (e) => this.#breakOn(e));
+        this.state = state;
+        state.attachDispatcher((fn) => this.deliver(fn));
+        // ctx.abort(reason) (workerd, celld): the object resets — a fresh instance on the same
+        // database serves the next event; the calling event fails with the reason. Writes the event
+        // already made still commit (celld: celld's workflow cell aborts after its delete commit).
+        state.abort = (reason) => {
+            queueMicrotask(() => this.restart());
+            throw reason ?? new Error("Durable Object reset because its code calls abort()");
+        };
+        state.exports = opts.exports ?? {};
+        state.props = opts.props;
+        state.facets = createFacets({ ...opts, epoch: () => this.#epoch }, (name, cls, env, id, props) => {
+            const facet = new ObjectHost({
+                ...opts,
+                // celld's facet stream: <parent>/facets/<SHA-256(name)[0..16] hex> (engine_api.rs)
+                cellKey: `${opts.cellKey}/facets/${facetSegment(name)}`,
+                id,
+                cls,
+                env,
+                props,
+                onAlarmChange: undefined,
+                // A facet is part of its root's cell: no lease of its own, the root's epoch.
+                acquire: undefined,
+                epoch: this.#epoch,
+                facet: true,
+            });
+            this.#facets.add(facet); // closed with its root
+            return facet;
+        });
+        const root = opts.asyncRoot ?? ((fn) => fn());
+        this.#root = root;
+        const construct = () => root(() => (this.#instance = new opts.cls(state, opts.env)));
+        this.#construct = construct;
+        const load = opts.backup?.load;
+        const replay = opts.backup?.replay;
+        const acquire = opts.acquire;
+        if (!load && !replay && !acquire) {
+            this.#nameFromMetadata(state);
+            construct();
+            return;
+        }
+        // Restore-on-open: events queue behind the closed gate until the image is in.
+        void this.#gate
+            .runClosed(async () => {
+            if (acquire) {
+                const lease = await acquire(this.cellKey);
+                if (!lease)
+                    throw new CellOwnedElsewhereError(this.cellKey);
+                this.#epoch = lease.epoch;
+                this.#release = lease.release;
+                lease.lost.addEventListener("abort", () => this.#breakOn(new Error(`lease of ${this.cellKey} lost`)), {
+                    once: true,
+                });
+            }
+            // Under a lease (the cell's own, or its root's for a facet) the bucket is the cell's
+            // truth: a local file kept from an earlier ownership is older than what other owners
+            // wrote since, and may hold commits that never became durable.
+            await this.#catchUp(this.#epoch !== undefined);
+            if (opts.facet)
+                this.#rescope(scopeOf(opts.cellKey));
+            else {
+                this.#initWake();
+                this.#scheduleRestoredAlarm(opts.onAlarmChange);
+            }
+            this.#nameFromMetadata(state);
+            construct();
+        })
+            .catch((e) => this.#breakOn(e));
+    }
+    /**
+     * Takes an image if the cell changed since the last successful save and hands
+     * it to `backup.save`. Taken synchronously between events → a consistent image.
+     * Skipped while an async transaction() holds the database or a save is running.
+     */
+    backupIfDirty(reason, now) {
+        const b = this.#backup;
+        if (!b || this.broken || this.#saving || this.#seq === this.#backedUpSeq)
+            return this.#saving ?? Promise.resolve();
+        if (!this.#driver.image)
+            return Promise.reject(new Error("SyncSqlDriver has no image(): cannot back up"));
+        if (this.#sql.held)
+            return Promise.resolve(); // mid-transaction: next round
+        this.#sql.commit();
+        const seq = this.#seq;
+        let logSeq = 0;
+        try {
+            logSeq = Number(this.#driver.exec(LOG_SEQ_READ, []).rows[0]?.[0] ?? 0);
+        }
+        catch {
+            // no _cf_LOG yet
+        }
+        const image = this.#driver.image();
+        this.#saving = b
+            .save(this.cellKey, image, { seq, takenAt: now, reason, logSeq })
+            .then(() => {
+            this.#backedUpSeq = Math.max(this.#backedUpSeq, seq);
+        }, (e) => b.onError?.(this.cellKey, e))
+            .finally(() => (this.#saving = undefined));
+        return this.#saving;
+    }
+    /**
+     * Input gate → handler → commit → output gate (durability) → result.
+     *
+     * Events are queued and STARTED synchronously by a pump only while the gate
+     * is open: the first storage op of a handler closes the gate before the
+     * next event can start (checking the gate in an `await` continuation is too
+     * late — every queued continuation would see it open).
+     */
+    deliver(fn) {
+        if (this.broken)
+            return Promise.reject(new BrokenObjectError(undefined));
+        return new Promise((resolve, reject) => {
+            this.#queue.push(() => {
+                if (this.broken)
+                    return reject(new BrokenObjectError(this.#brokenCause, "its initialization failed"));
+                let started;
+                this.#active++;
+                try {
+                    started = Promise.resolve(this.#root(() => fn(this.#instance, this.state)));
+                }
+                catch (e) {
+                    started = Promise.reject(e);
+                }
+                const done = () => {
+                    this.#active--;
+                    this.lastActive = Date.now();
+                };
+                started.then((r) => {
+                    this.#pinIfStandardWebSocket(r);
+                    this.#barrier().then(() => (done(), resolve(r)), (e) => (done(), reject(e)));
+                }, (e) => this.#barrier().then(() => (done(), reject(e)), (e2) => (done(), reject(e2))));
+            });
+            this.#pump();
+        });
+    }
+    #queue = [];
+    #pumpWaiting = false;
+    #pump = () => {
+        this.#pumpWaiting = false;
+        while (this.#queue.length && this.#gate.isOpen) {
+            // A database closed while idle: reopen it (and catch up) before anything runs.
+            if (this.#dbClosed) {
+                this.#dbClosed = false;
+                void this.#gate
+                    .runClosed(async () => {
+                    this.#open();
+                    // The lease was held throughout: a kept file is current, an empty one is restored.
+                    await this.#catchUp(false);
+                })
+                    .catch((e) => this.#breakOn(e));
+                continue;
+            }
+            // Waking from hibernation: the constructor runs again before the event (and may
+            // close the gate with blockConcurrencyWhile, which the loop then respects).
+            if (this.#hibernated) {
+                this.#hibernated = false;
+                this.#construct?.();
+                continue;
+            }
+            this.#queue.shift()();
+        }
+        if (this.#queue.length && !this.#pumpWaiting) {
+            this.#pumpWaiting = true;
+            this.#gate.onOpen(this.#pump);
+        }
+    };
+    async #barrier() {
+        try {
+            this.#sql.commit();
+            await this.#out.barrier();
+        }
+        catch (e) {
+            this.broken = true;
+            try {
+                this.#sql.rollback();
+            }
+            catch { }
+            throw new BrokenObjectError(e);
+        }
+    }
+    /** Settles once the cell lease is released (a store closed earlier would keep it held). */
+    close() {
+        for (const facet of this.#facets)
+            void facet.close();
+        this.#facets.clear();
+        if (!this.#dbClosed)
+            this.#db.close();
+        // Hand the cell over at once instead of letting the lease expire.
+        const released = this.#release?.().catch(() => { });
+        this.#release = undefined;
+        return released ?? Promise.resolve();
+    }
+    #release;
+    /** The hosts of this cell's facets: their databases close with the root's. */
+    #facets = new Set();
+    /**
+     * Brings the local database to the storage's state: restores the image, then replays the log.
+     * Without `rebuild` only an empty database is restored (the local file is the primary copy);
+     * with it, a non-empty one is replaced too — dropped first when the storage has no image.
+     */
+    async #catchUp(rebuild) {
+        const { load, replay } = this.#backup ?? {};
+        if (!load && !replay)
+            return;
+        const d = this.#driver;
+        const empty = Number(d.exec("SELECT count(*) FROM sqlite_master", []).rows[0][0]) === 0;
+        if (!empty && !rebuild)
+            return;
+        const image = await load?.(this.cellKey);
+        if (image) {
+            if (!d.restore)
+                throw new Error("SyncSqlDriver has no restore(): cannot restore a backup");
+            d.restore(image);
+        }
+        else if (!empty) {
+            // Indexes and triggers go with their tables; sqlite_* tables cannot be dropped. Foreign
+            // keys are off meanwhile, so a parent table can go before its children.
+            const objects = d.exec("SELECT type, name FROM sqlite_master WHERE type IN ('view', 'table') AND name NOT LIKE 'sqlite_%'", []).rows;
+            const fk = Number(d.exec("PRAGMA foreign_keys", []).rows[0][0]);
+            d.exec("PRAGMA foreign_keys = OFF", []);
+            try {
+                for (const [type, name] of objects)
+                    d.exec(`DROP ${type} IF EXISTS "${String(name).replace(/"/g, '""')}"`, []);
+            }
+            finally {
+                d.exec(`PRAGMA foreign_keys = ${fk}`, []);
+            }
+        }
+        // Then every logged transaction the image does not contain, in order.
+        if (replay)
+            await this.#replayLog(replay);
+    }
+    /** Applies log segments newer than the database's own log sequence (restore path). */
+    async #replayLog(replay) {
+        const d = this.#driver;
+        d.exec(LOG_TABLE, []);
+        const row = d.exec(LOG_SEQ_READ, []).rows[0];
+        const after = Number(row?.[0] ?? 0);
+        for await (const seg of replay(this.cellKey, after)) {
+            if (!d.applyChangeset)
+                throw new Error("SyncSqlDriver cannot apply changesets: cannot replay a log");
+            d.exec("BEGIN", []);
+            try {
+                for (const ddl of seg.ddl)
+                    d.exec(ddl, []);
+                d.applyChangeset(seg.changeset);
+                for (const [sql, params] of seg.statements)
+                    d.exec(sql, params);
+                d.exec(LOG_SEQ_WRITE, [seg.logSeq]);
+                d.exec("COMMIT", []);
+            }
+            catch (e) {
+                d.exec("ROLLBACK", []);
+                throw e;
+            }
+        }
+    }
+    #construct;
+    #root = (fn) => fn();
+    #open;
+    #epoch;
+    /**
+     * celld gives each run of a facet its own scope and moves the facet database's rows to it
+     * on open (storage.rs open_embedded); doing the same here reads a facet database celld
+     * wrote, whatever scope it used.
+     */
+    /**
+     * celld's alarm publication identity (storage/wake_record.rs initialize): one `_cf_WAKE`
+     * row per cell carrying the writer epoch; triggers bump its sequence on every alarm change.
+     */
+    #initWake() {
+        if (!this.#epoch || !this.#opts.durability.publishWake)
+            return;
+        const scope = scopeOf(this.cellKey);
+        for (const ddl of CELLD_SCHEMA)
+            this.#driver.exec(ddl, []);
+        this.#driver.exec(`INSERT INTO _cf_WAKE(scope,epoch,sequence,at_ms)
+       VALUES(?1,?2,0,(SELECT at_ms FROM _cf_ALARM WHERE scope=?1))
+       ON CONFLICT(scope) DO UPDATE SET epoch=excluded.epoch WHERE excluded.epoch>_cf_WAKE.epoch`, [scope, this.#epoch.toString(16).padStart(16, "0")]);
+        this.#wakeSeq = this.#wakeRow()?.sequence;
+    }
+    /**
+     * A cell restored on open may carry an alarm armed by its previous owner (another node, or
+     * celld). This node owns the cell now, so the alarm is its to fire: hand it to the scheduler,
+     * which otherwise only hears of alarms set here (or of a later wake-index poll).
+     */
+    #scheduleRestoredAlarm(onAlarmChange) {
+        let at;
+        try {
+            at = this.#driver.exec("SELECT at_ms FROM _cf_ALARM WHERE scope = ?", [scopeOf(this.cellKey)])
+                .rows[0]?.[0];
+        }
+        catch {
+            return; // no alarm table: the cell never had an alarm
+        }
+        if (at != null)
+            onAlarmChange?.(Number(at));
+    }
+    #wakeSeq;
+    #wakeRow() {
+        try {
+            const r = this.#driver.exec("SELECT epoch, sequence, at_ms FROM _cf_WAKE WHERE scope = ?", [
+                scopeOf(this.cellKey),
+            ]).rows[0];
+            return r
+                ? {
+                    epoch: Number.parseInt(String(r[0]), 16),
+                    sequence: Number(r[1]),
+                    at: r[2] == null ? null : Number(r[2]),
+                }
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * After a commit: if it changed the alarm, a publication to run once the commit is durable
+     * (celld publishes after replication).
+     */
+    #wakeAfterCommit() {
+        const publish = this.#opts.durability.publishWake;
+        if (!publish || this.#opts.facet || !this.#epoch)
+            return undefined;
+        const row = this.#wakeRow();
+        if (!row || row.sequence === this.#wakeSeq)
+            return undefined;
+        this.#wakeSeq = row.sequence;
+        return () => publish(this.cellKey, row);
+    }
+    #opts;
+    /**
+     * celld records the name an object was addressed by (`_cf_METADATA.actor_name`) and gives it
+     * back as `ctx.id.name` when the object is woken by id alone (an alarm, a wake entry) —
+     * celld's own queue cells rely on it. Both directions here: restore it, and record it.
+     */
+    #nameFromMetadata(state) {
+        if (this.#opts.facet)
+            return;
+        const scope = scopeOf(this.cellKey);
+        // Reading only: no DDL or write outside a logged transaction (a changeset log replays
+        // only what it captured). The name is recorded with the cell's first storage write.
+        if (state.id.name !== undefined)
+            return;
+        try {
+            const r = this.#driver.exec("SELECT actor_name FROM _cf_METADATA WHERE scope = ?", [scope])
+                .rows[0];
+            if (r?.[0] != null)
+                state.id = new DurableObjectIdClass(state.id.toString(), String(r[0]));
+        }
+        catch {
+            // no _cf_METADATA yet
+        }
+    }
+    #rescope(scope) {
+        for (const table of ["_cf_KV", "_cf_ALARM", "_cf_METADATA"])
+            try {
+                this.#driver.exec(`UPDATE ${table} SET scope = ? WHERE scope <> ?`, [scope, scope]);
+            }
+            catch {
+                // table not created yet
+            }
+    }
+    // ---- hibernation ---------------------------------------------------------------------
+    #active = 0;
+    #hibernated = false;
+    #pinned = 0;
+    /** Time of the last event's completion (the runtime's idle sweep reads it). */
+    lastActive = Date.now();
+    get hibernated() {
+        return this.#hibernated;
+    }
+    /**
+     * A 101 response whose server end was accepted with `accept()` (not acceptWebSocket)
+     * holds a standard WebSocket: the object cannot hibernate until that socket closes —
+     * as on Cloudflare, only the hibernation API lets an object sleep with open sockets.
+     */
+    #pinIfStandardWebSocket(r) {
+        const server = r?.webSocket?.peer;
+        if (!server || server.hibernatable || !server.accepted)
+            return;
+        this.#pinned++;
+        server.addEventListener("close", () => this.#pinned--, { once: true });
+    }
+    /**
+     * Drops the instance when nothing runs: no event in flight or queued, no open async
+     * transaction, no standard WebSocket. Storage, alarms and hibernatable sockets stay; the
+     * next event constructs the class again. Returns whether it hibernated.
+     */
+    hibernate() {
+        if (this.#hibernated ||
+            this.broken ||
+            this.#active ||
+            this.#queue.length ||
+            this.#sql.held ||
+            this.#pinned)
+            return false;
+        if (!this.#gate.isOpen)
+            return false;
+        this.#sql.commit();
+        this.#instance = undefined;
+        this.#hibernated = true;
+        return true;
+    }
+    #dbClosed = false;
+    /**
+     * Closes the database of a hibernated cell (the cell lease stays); the next event reopens it.
+     * A cell with changes its backup has not taken yet stays open. Returns whether it closed.
+     */
+    closeDatabase() {
+        if (!this.#hibernated || this.#dbClosed || this.#queue.length || !this.#gate.isOpen)
+            return false;
+        if (this.#backup && (this.#saving || this.#seq !== this.#backedUpSeq))
+            return false;
+        this.#db.close();
+        this.#dbClosed = true;
+        return true;
+    }
+    /** Replaces the instance with a fresh one on the SAME database (facet abort/delete). */
+    restart() {
+        if (this.#dbClosed)
+            return; // the next event reopens it with a fresh instance
+        this.#construct?.();
+    }
+}
+function createFacets(parent, spawn) {
+    const running = new Map();
+    // abort() stops the stubs handed out so far (their calls throw the reason); a later
+    // get() starts the facet again on the same database — as celld does.
+    const generation = new Map();
+    const local = (h) => ({
+        call: (method, args) => h.deliver((obj) => {
+            const fn = obj[method];
+            if (typeof fn !== "function")
+                throw new TypeError(`${method} is not a function`);
+            return fn.apply(obj, args);
+        }),
+        fetch: (req) => h.deliver((obj) => obj.fetch(req)),
+        restart: () => h.restart(),
+        delete: async () => {
+            await h.deliver((_o, state) => state.storage.deleteAll());
+            h.restart();
+        },
+    });
+    /** A class of isolated loaded code: the facet's instance and SQLite live in the isolate. */
+    const isolated = (iso, cellKey) => {
+        const attached = iso.attach?.(cellKey, parent.epoch?.());
+        const ready = async () => attached;
+        return {
+            call: async (method, args) => (await ready(), iso.call(cellKey, method, args)),
+            fetch: async (req) => (await ready(), iso.fetch(cellKey, req)),
+            restart: async () => (await ready(), iso.restart(cellKey)),
+            delete: async () => (await ready(), iso.delete(cellKey)),
+        };
+    };
+    const targetOf = (name, start) => {
+        let p = running.get(name);
+        if (!p) {
+            if (!start)
+                return Promise.reject(new Error(`Facet "${name}" is not running`));
+            p = (async () => {
+                const info = (await start());
+                let cls;
+                let env = parent.env;
+                let props;
+                if (isClassHandle(info.class)) {
+                    const r = await info.class.resolve();
+                    if ("isolated" in r)
+                        return isolated(r.isolated, `${parent.cellKey}/facets/${facetSegment(name)}`);
+                    ({ cls, env, props } = r);
+                }
+                else
+                    cls = info.class;
+                const id = info.id instanceof DurableObjectIdClass ? info.id : parent.id;
+                return local(spawn(name, cls, env, id, props));
+            })();
+            p.catch(() => running.delete(name));
+            running.set(name, p);
+        }
+        return p;
+    };
+    return {
+        get(name, start) {
+            if (new TextEncoder().encode(name).byteLength > 256)
+                throw new Error("A facet name has a limit of 256 bytes");
+            const gen = generation.get(name)?.n ?? 0;
+            const live = () => {
+                const g = generation.get(name);
+                if (g && g.n !== gen)
+                    throw g.reason;
+            };
+            return asyncStub(async (method, args) => (live(), await targetOf(name, start)).call(method, args), async (req) => (live(), await targetOf(name, start)).fetch(req));
+        },
+        abort(name, reason) {
+            const n = (generation.get(name)?.n ?? 0) + 1;
+            generation.set(name, { n, reason: reason ?? new Error(`Facet "${name}" was aborted`) });
+            // The database stays: the next call on a new stub gets a fresh instance over it.
+            void running.get(name)?.then((t) => t.restart());
+        },
+        async delete(name) {
+            const p = running.get(name);
+            generation.set(name, {
+                n: (generation.get(name)?.n ?? 0) + 1,
+                reason: new Error(`Facet "${name}" was deleted`),
+            });
+            if (p)
+                await (await p).delete();
+        },
+    };
+}
+/** The cell's lease is held by another owner (route the request there, or retry later). */
+export class CellOwnedElsewhereError extends Error {
+    constructor(cellKey) {
+        super(`Durable Object ${cellKey} is owned by another node`);
+        this.name = "CellOwnedElsewhereError";
+    }
+}
+/** celld's path segment for a facet name: the first 16 bytes of SHA-256(name), hex. */
+export function facetSegment(name) {
+    return bytesToHex(sha256(new TextEncoder().encode(name)).subarray(0, 16));
+}
+//# sourceMappingURL=object-host.js.map