totalum-sdk 0.1.0-dev.11 → 0.1.0-dev.12

package/dist/d1/index.d.ts

@@ -90,7 +90,8 @@ declare const READ_YOUR_WRITES_COOKIE = "__tlm_d1_w";
  * Runs one request of a Worker with a replicated D1 (A3.23, research 46 §6.3): a `GET`/`HEAD` reads through a
  * `first-unconstrained` session — the nearest replica — unless the browser wrote in the last 10 s; any other method
  * uses the plain binding (writes go to the primary; measured faster than any session) and its response sets the short
- * cookie that sends that browser's next reads to the primary. `run` receives the env to hand to the app, whose
+ * cookie that sends that browser's next reads to the primary. A replica read that takes over `REPLICA_READ_TIMEOUT_MS`
+ * is answered by the primary instead, and the rest of that request reads the primary. `run` receives the env to hand to the app, whose
  * `totalumD1()` reads `TOTALUM_DB` from it on every statement. No D1 binding (Turso, a laptop): `run(env)` unchanged.
  */
 declare function withTotalumSession<E extends object>(request: Request, env: E, run: (env: E) => Promise<Response>): Promise<Response>;

package/dist/d1/session.js

@@ -3,11 +3,21 @@ export const READ_YOUR_WRITES_COOKIE = '__tlm_d1_w';
 /** Replicas lag the primary by 30–75 ms (Cloudflare); 10 s leaves a wide margin (research 46 §6.3). */
 const WINDOW_SECONDS = 10;
 const READS = new Set(['GET', 'HEAD']);
+/**
+ * A replica read slower than this is re-run on the primary, and the rest of the request reads the primary. Replicas
+ * answer in tens of ms; measured stalls last 10 s or more while the primary stays fast (ui-evidence/preview-hang).
+ * D1's Sessions API documents no timeout or fallback of its own.
+ */
+export const REPLICA_READ_TIMEOUT_MS = 2000;
+/** Only a `SELECT` is re-run: a write that stalled may still land, and running it twice would duplicate it. */
+const PURE_READ = /^\s*select\b/i;
+const LATE = Symbol('late');
 /**
  * Runs one request of a Worker with a replicated D1 (A3.23, research 46 §6.3): a `GET`/`HEAD` reads through a
  * `first-unconstrained` session — the nearest replica — unless the browser wrote in the last 10 s; any other method
  * uses the plain binding (writes go to the primary; measured faster than any session) and its response sets the short
- * cookie that sends that browser's next reads to the primary. `run` receives the env to hand to the app, whose
+ * cookie that sends that browser's next reads to the primary. A replica read that takes over `REPLICA_READ_TIMEOUT_MS`
+ * is answered by the primary instead, and the rest of that request reads the primary. `run` receives the env to hand to the app, whose
  * `totalumD1()` reads `TOTALUM_DB` from it on every statement. No D1 binding (Turso, a laptop): `run(env)` unchanged.
  */
 export async function withTotalumSession(request, env, run) {
@@ -26,13 +36,57 @@ export async function withTotalumSession(request, env, run) {
     const cookies = request.headers.get('cookie') ?? '';
     if (new RegExp(`(?:^|;\\s*)${READ_YOUR_WRITES_COOKIE}=`).test(cookies))
         return run(env);
-    const session = binding.withSession('first-unconstrained');
-    const replicaDb = {
-        prepare: (sql) => session.prepare(sql),
-        batch: (statements) => session.batch(statements),
+    return run({ ...env, TOTALUM_DB: boundedReplica(binding, binding.withSession('first-unconstrained')) });
+}
+/**
+ * The request's database on the nearest replica, each pure read bounded by `REPLICA_READ_TIMEOUT_MS`: past it, the read
+ * runs on the primary (the stalled replica call is abandoned) and so does every later statement of this request.
+ */
+function boundedReplica(binding, session) {
+    let primary = false;
+    const on = () => (primary ? binding : session);
+    async function read(sqls, call) {
+        if (primary || !sqls.every((sql) => PURE_READ.test(sql)))
+            return call(on());
+        let timer;
+        const late = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                resolve(LATE);
+            }, REPLICA_READ_TIMEOUT_MS);
+        });
+        try {
+            const out = await Promise.race([call(session), late]);
+            if (out !== LATE)
+                return out;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        primary = true;
+        console.warn(JSON.stringify({ event: 'd1_replica_read_timeout', ms: REPLICA_READ_TIMEOUT_MS }));
+        return call(binding);
+    }
+    const statement = (sql, params = []) => {
+        const real = (db) => db.prepare(sql).bind(...params);
+        const bounded = (method) => (...args) => read([sql], (db) => real(db)[method](...args));
+        return {
+            sql,
+            real,
+            bind: (...values) => statement(sql, values),
+            first: bounded('first'),
+            run: bounded('run'),
+            all: bounded('all'),
+            raw: bounded('raw'),
+        };
+    };
+    return {
+        prepare: (sql) => statement(sql),
+        batch: (statements) => {
+            const mine = statements;
+            return read(mine.map((s) => s.sql), (db) => db.batch(mine.map((s) => s.real(db))));
+        },
         exec: (sql) => binding.exec(sql),
         dump: () => binding.dump(),
         withSession: (c) => binding.withSession(c),
     };
-    return run({ ...env, TOTALUM_DB: replicaDb });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totalum-sdk",
-  "version": "0.1.0-dev.11",
+  "version": "0.1.0-dev.12",
   "description": "The SDK generated Totalum apps import: every integration namespace over SDK-API (totalum-sdk, or one subpath each: /files, /ai, /web, …) and totalum-sdk/d1, the D1 driver",
   "license": "UNLICENSED",
   "type": "module",