orez-lite 0.10.7 → 0.11.0

package/dist/cf-do/worker.js

@@ -97,15 +97,17 @@ const APPLICATION_SQL_DISPOSE = Symbol('applicationSqlDispose');
 class ApplicationSqlSessionTarget extends RpcTarget {
     owner;
     sessionID;
+    readOnly;
     state = 'created';
     changed = false;
     mutated = false;
-    constructor(owner, sessionID) {
+    constructor(owner, sessionID, readOnly) {
         super();
         this.owner = owner;
         this.sessionID = sessionID;
+        this.readOnly = readOnly;
     }
-    async begin() {
+    begin() {
         return this.owner[APPLICATION_SQL_ACQUIRE](this);
     }
     query(sql, params = []) {
@@ -142,7 +144,9 @@ export class ZeroDO extends DurableObject {
     activeWriteMeasurements = null;
     writeBudgetTripStatement;
     pendingChangesSchemaReady = false;
-    activeApplicationSqlSession = null;
+    applicationSqlWriter = null;
+    applicationSqlReaders = new Set();
+    applicationSqlQueue = [];
     applicationSqlDidCommit(_changed, _mutated) { }
     recordWriteBudgetRows(rows, statement) {
         const wasTripped = this.writeBudget.status().tripped;
@@ -990,70 +994,150 @@ export class ZeroDO extends DurableObject {
         }));
     }
     assertApplicationSqlSession(session) {
-        if (session.state !== 'active' || this.activeApplicationSqlSession !== session) {
+        const admitted = session.readOnly
+            ? this.applicationSqlReaders.has(session)
+            : this.applicationSqlWriter === session;
+        if (session.state !== 'active' || !admitted) {
             throw new Error('application SQLite session is not active');
         }
     }
-    [APPLICATION_SQL_ACQUIRE](session) {
-        if (session.state === 'active' && this.activeApplicationSqlSession === session) {
-            return true;
+    /**
+     * Read sessions never mutate, so no lane can escalate and there is nothing to
+     * deadlock over: a reader waits only on the writer, and the writer waits only
+     * on the reader set draining.
+     */
+    canAdmitApplicationSqlSession(session) {
+        if (this.applicationSqlWriter)
+            return false;
+        return session.readOnly || this.applicationSqlReaders.size === 0;
+    }
+    /**
+     * Admit from the head of the arrival queue and stop at the first waiter that
+     * cannot run yet.
+     *
+     * The stop is what makes this fair. Scanning past a blocked writer to admit
+     * younger readers would let a steady read load hold the turn away from it
+     * indefinitely, which is the starvation the competitive `begin()` poll this
+     * replaces produced in production: callers raced a 25 ms timer for one
+     * ownership flag, so admission order was decided by poll phase, and sessions
+     * that had arrived ten seconds earlier watched later ones complete.
+     */
+    pumpApplicationSqlQueue() {
+        while (this.applicationSqlQueue.length > 0) {
+            const waiter = this.applicationSqlQueue[0];
+            if (waiter.session.state !== 'waiting') {
+                this.applicationSqlQueue.shift();
+                clearTimeout(waiter.timer);
+                continue;
+            }
+            if (!this.canAdmitApplicationSqlSession(waiter.session))
+                return;
+            this.applicationSqlQueue.shift();
+            clearTimeout(waiter.timer);
+            waiter.session.state = 'active';
+            if (waiter.session.readOnly)
+                this.applicationSqlReaders.add(waiter.session);
+            else
+                this.applicationSqlWriter = waiter.session;
+            waiter.admit();
         }
+    }
+    /**
+     * Join the arrival queue and resolve when this session owns its turn.
+     *
+     * A waiting session holds one queue entry and one timer, and nothing else:
+     * cancellation, rollback and RPC stub disposal all route through
+     * `releaseApplicationSqlTurn`, which drops the entry and re-pumps. The
+     * deadline bounds a queue entry whose caller neither cancels nor disposes,
+     * and reports the wait as an error instead of hanging the request.
+     */
+    [APPLICATION_SQL_ACQUIRE](session) {
         if (session.state !== 'created') {
-            throw new Error('application SQLite session cannot begin again');
-        }
-        if (this.activeApplicationSqlSession)
-            return false;
-        session.state = 'active';
-        this.activeApplicationSqlSession = session;
-        return true;
+            return Promise.reject(new Error('application SQLite session cannot begin again'));
+        }
+        session.state = 'waiting';
+        const admission = new Promise((resolve, reject) => {
+            const waiter = {
+                session,
+                admit: resolve,
+                reject,
+                timer: setTimeout(() => {
+                    const index = this.applicationSqlQueue.indexOf(waiter);
+                    if (index < 0)
+                        return;
+                    this.applicationSqlQueue.splice(index, 1);
+                    session.state = 'closed';
+                    reject(new Error('timed out acquiring the application SQLite session'));
+                }, APPLICATION_SQL_TURN_WAIT_MS),
+            };
+            this.applicationSqlQueue.push(waiter);
+            this.pumpApplicationSqlQueue();
+        });
+        return admission;
     }
+    /**
+     * Close a session in any state and hand the turn to the next arrival.
+     *
+     * A session that is still queued has never touched SQLite, so dropping its
+     * queue entry is the whole of its cleanup.
+     */
     releaseApplicationSqlTurn(session) {
+        if (session.state === 'closed')
+            return;
+        if (session.state === 'created') {
+            session.state = 'closed';
+            return;
+        }
+        if (session.state === 'waiting') {
+            const index = this.applicationSqlQueue.findIndex((waiter) => waiter.session === session);
+            if (index >= 0) {
+                const [waiter] = this.applicationSqlQueue.splice(index, 1);
+                clearTimeout(waiter.timer);
+            }
+            // The in-flight `begin()` is left unsettled on purpose. Only this
+            // session's own caller can close it while it waits, and by then that
+            // caller has stopped awaiting admission and is on its way to disposing
+            // the stub, which cancels the call. Rejecting instead delivers an error
+            // nobody is listening for, and workerd reports every one of those as an
+            // uncaught error — measured, one per cancellation.
+            session.state = 'closed';
+            return;
+        }
         this.assertApplicationSqlSession(session);
         session.state = 'closed';
-        this.activeApplicationSqlSession = null;
+        if (session.readOnly)
+            this.applicationSqlReaders.delete(session);
+        else
+            this.applicationSqlWriter = null;
+        this.pumpApplicationSqlQueue();
     }
     async withApplicationSqlTurn(work, signal) {
-        const session = await this.applicationSqlSession(crypto.randomUUID());
+        const session = await this.applicationSqlSession(crypto.randomUUID(), {
+            readOnly: true,
+        });
         const dispose = () => session[Symbol.dispose]();
         signal?.addEventListener('abort', dispose, { once: true });
         try {
-            while (!(await session.begin())) {
-                if (signal?.aborted)
-                    throw new Error('application SQLite request was canceled');
-                await new Promise((resolve) => setTimeout(resolve, 25));
-            }
+            await session.begin();
             return await work();
         }
         finally {
             signal?.removeEventListener('abort', dispose);
-            if (session.state === 'active')
-                this.releaseApplicationSqlTurn(session);
-            else if (session.state !== 'closed')
-                dispose();
+            dispose();
         }
     }
     /**
      * drive one application SQLite session from INSIDE this durable object.
      *
      * identical to the client-side session helper in application-sql.ts — same
-     * ownership acquisition, same per-statement journal, same commit/rollback —
-     * except the begin poll and every statement are local calls instead of RPCs.
-     * the caller must already be running in this object.
+     * admission, same per-statement journal, same commit/rollback — except every
+     * call is local instead of an RPC. the caller must already be running in this
+     * object.
      */
-    async withLocalApplicationSqlSession(work) {
-        const session = await this.applicationSqlSession(crypto.randomUUID());
+    async withLocalApplicationSqlSession(readOnly, work) {
+        const session = await this.applicationSqlSession(crypto.randomUUID(), { readOnly });
         try {
-            // bounded, unlike the client-side poll. a remote caller that goes away
-            // stops polling and frees the turn; a local caller has no signal to
-            // observe, so an unbounded loop would spin for the life of the object
-            // every time somebody abandoned a request mid-reconcile.
-            const deadline = Date.now() + APPLICATION_SQL_TURN_WAIT_MS;
-            while (!(await session.begin())) {
-                if (Date.now() >= deadline) {
-                    throw new Error('timed out acquiring the application SQLite session');
-                }
-                await scheduler.wait(25);
-            }
+            await session.begin();
             const value = await work(session);
             await session.commit();
             return value;
@@ -1079,20 +1163,22 @@ export class ZeroDO extends DurableObject {
      * the transport is.
      */
     applicationSqlLocalClient(namespace) {
-        const run = (work) => this.withLocalApplicationSqlSession(work);
+        const run = (readOnly, work) => this.withLocalApplicationSqlSession(readOnly, work);
+        const transaction = (readOnly, compileQuery, work, queryBudget) => run(readOnly, async (session) => work({
+            exec: (sql, params = [], metadata) => session.exec(sql, params, metadata),
+            query: (sql, params = []) => session.query(sql, params),
+            registerTables: (tables) => session.registerTables(tables),
+            async queryAst(ast, format, queryName) {
+                return session.queryPlan(await compileQuery(ast, format), queryName, queryBudget);
+            },
+        }));
         return {
             namespace,
-            query: (sql, params = []) => run((session) => session.query(sql, params)),
-            exec: (sql, params = [], metadata) => run((session) => session.exec(sql, params, metadata)),
-            registerTables: (tables) => run((session) => session.registerTables(tables)),
-            transaction: (compileQuery, work, queryBudget) => run(async (session) => work({
-                exec: (sql, params = [], metadata) => session.exec(sql, params, metadata),
-                query: (sql, params = []) => session.query(sql, params),
-                registerTables: (tables) => session.registerTables(tables),
-                async queryAst(ast, format, queryName) {
-                    return session.queryPlan(await compileQuery(ast, format), queryName, queryBudget);
-                },
-            })),
+            query: (sql, params = []) => run(true, (session) => session.query(sql, params)),
+            exec: (sql, params = [], metadata) => run(false, (session) => session.exec(sql, params, metadata)),
+            registerTables: (tables) => run(false, (session) => session.registerTables(tables)),
+            transaction: (compileQuery, work, queryBudget) => transaction(false, compileQuery, work, queryBudget),
+            readTransaction: (compileQuery, work, queryBudget) => transaction(true, compileQuery, work, queryBudget),
         };
     }
     registerApplicationSqlTables(tables) {
@@ -1106,14 +1192,25 @@ export class ZeroDO extends DurableObject {
     }
     /**
      * private durable object RPC surface for the application SQLite client. the
-     * disposable target exists before ownership acquisition, so waiting callers
-     * hold no server state and active cancellation rolls back the transaction.
-     * this method is intentionally absent from fetch().
+     * disposable target exists before admission, so a queued caller can cancel by
+     * disposing it and an active one rolls its transaction back. this method is
+     * intentionally absent from fetch().
      */
-    async applicationSqlSession(sessionID) {
+    async applicationSqlSession(sessionID, options = {}) {
         if (!sessionID)
             throw new TypeError('application SQLite session id is required');
-        return new ApplicationSqlSessionTarget(this, sessionID);
+        return new ApplicationSqlSessionTarget(this, sessionID, options.readOnly === true);
+    }
+    /**
+     * Run one read statement end to end in a single round trip.
+     *
+     * A single statement is already atomic, so a session that exists only to
+     * carry it costs four sequential RPCs (open, admit, run, commit) for one
+     * SELECT — the shape every authenticated read on the sync path pays. This
+     * opens, admits, runs and closes the same read session locally instead.
+     */
+    async applicationSqlQuery(sql, params = []) {
+        return this.withLocalApplicationSqlSession(true, (session) => session.query(sql, params));
     }
     prepareApplicationSqlMutation(sessionID, sql) {
         if (!isSqlMutation(sql))
@@ -1132,8 +1229,20 @@ export class ZeroDO extends DurableObject {
         beginTxJournal(this.sql, sessionID, 'application');
         return true;
     }
-    async [APPLICATION_SQL_QUERY](session, sql, params = []) {
+    /**
+     * A read session declared its lane before it was admitted, and readers run
+     * alongside each other on the strength of that declaration. Escalating one
+     * mid-session would strand every other reader on a state that is no longer
+     * committed, so a mutation here is an error rather than an upgrade.
+     */
+    assertApplicationSqlStatement(session, sql) {
         this.assertApplicationSqlSession(session);
+        if (session.readOnly && classifySql(sql).mutation) {
+            throw new Error('read-only application SQLite session cannot execute a mutation');
+        }
+    }
+    async [APPLICATION_SQL_QUERY](session, sql, params = []) {
+        this.assertApplicationSqlStatement(session, sql);
         return this.atomically(() => {
             if (this.prepareApplicationSqlMutation(session.sessionID, sql)) {
                 session.mutated = true;
@@ -1142,7 +1251,7 @@ export class ZeroDO extends DurableObject {
         });
     }
     async [APPLICATION_SQL_EXEC](session, sql, params = [], metadata) {
-        this.assertApplicationSqlSession(session);
+        this.assertApplicationSqlStatement(session, sql);
         return this.atomically(() => {
             if (this.prepareApplicationSqlMutation(session.sessionID, sql)) {
                 session.mutated = true;
@@ -1155,10 +1264,16 @@ export class ZeroDO extends DurableObject {
     }
     async [APPLICATION_SQL_QUERY_PLAN](session, plan, queryName, queryBudget) {
         this.assertApplicationSqlSession(session);
-        return this.atomically(() => executeTransactionQueryPlan(plan, (sql, params) => this.executeSQL(sql, params, undefined, session.sessionID).rows, { queryName, budget: queryBudget }));
+        return this.atomically(() => executeTransactionQueryPlan(plan, (sql, params) => {
+            this.assertApplicationSqlStatement(session, sql);
+            return this.executeSQL(sql, params, undefined, session.sessionID).rows;
+        }, { queryName, budget: queryBudget }));
     }
     async [APPLICATION_SQL_REGISTER_TABLES](session, tables) {
         this.assertApplicationSqlSession(session);
+        if (session.readOnly) {
+            throw new Error('read-only application SQLite session cannot register tables');
+        }
         await this.atomically(() => this.registerApplicationSqlTables(tables));
     }
     async [APPLICATION_SQL_COMMIT](session) {
@@ -1176,14 +1291,16 @@ export class ZeroDO extends DurableObject {
         }
         this.applicationSqlDidCommit(session.changed, session.mutated);
     }
-    async [APPLICATION_SQL_ROLLBACK](session) {
-        if (session.state === 'created') {
-            session.state = 'closed';
-            return;
-        }
-        this.assertApplicationSqlSession(session);
-        try {
-            if (session.mutated) {
+    /**
+     * Undo whatever this session wrote and hand its turn on.
+     *
+     * Rollback, cancellation and RPC stub disposal are the same operation: a
+     * session that never reached SQLite only has to leave the queue, and one that
+     * did has to replay its row images before releasing.
+     */
+    closeApplicationSqlSession(session) {
+        if (session.state === 'active' && session.mutated) {
+            try {
                 this.rollbackAtomicallyWithoutForeignKeys(() => {
                     this.rollbackPendingTrackedChanges(session.sessionID);
                     rollbackTxJournal(this.sql, session.sessionID);
@@ -1191,32 +1308,18 @@ export class ZeroDO extends DurableObject {
                 });
                 this.invalidateSchemaCaches();
             }
+            finally {
+                this.releaseApplicationSqlTurn(session);
+            }
+            return;
         }
-        finally {
-            this.releaseApplicationSqlTurn(session);
-        }
+        this.releaseApplicationSqlTurn(session);
+    }
+    async [APPLICATION_SQL_ROLLBACK](session) {
+        this.closeApplicationSqlSession(session);
     }
     [APPLICATION_SQL_DISPOSE](session) {
-        if (session.state === 'closed')
-            return;
-        if (session.state === 'created') {
-            session.state = 'closed';
-            return;
-        }
-        this.assertApplicationSqlSession(session);
-        try {
-            if (session.mutated) {
-                this.rollbackAtomicallyWithoutForeignKeys(() => {
-                    this.rollbackPendingTrackedChanges(session.sessionID);
-                    rollbackTxJournal(this.sql, session.sessionID);
-                    this.deletePendingTrackedChanges(session.sessionID);
-                });
-                this.invalidateSchemaCaches();
-            }
-        }
-        finally {
-            this.releaseApplicationSqlTurn(session);
-        }
+        this.closeApplicationSqlSession(session);
     }
     atomicallySync(work) {
         try {