cursedbelt-server 4.9.0 → 4.11.0

package/src/server/d1/invocation.spec.ts

@@ -1,7 +1,7 @@
 import { Database } from 'bun:sqlite';
 import { beforeEach, describe, expect, test } from 'bun:test';
 import { createFakeD1Binding } from './fakeD1';
-import { perInvocation } from './invocation';
+import { createPendingWrites, perInvocation } from './invocation';
 import { LIMITS } from './limits';
 import { createLocalD1 } from './local';
 import { createRemoteD1 } from './remote';
@@ -172,3 +172,67 @@ describe('the budget counts the REMOTE driver identically', () => {
 		expect(db.used).toBe(2);
 	});
 });
+
+describe('the pending writes of one invocation', () => {
+	test('settle() waits for every collected write before it resolves', async () => {
+		const landed: number[] = [];
+		const writes = createPendingWrites();
+		const slow = (n: number, ms: number) =>
+			new Promise<void>((resolve) =>
+				setTimeout(() => {
+					landed.push(n);
+					resolve();
+				}, ms),
+			);
+
+		writes.add(slow(1, 20));
+		writes.add(slow(2, 5));
+		// Nothing has landed yet: this is the state a response sent without settling escapes in.
+		expect(landed).toEqual([]);
+
+		await writes.settle();
+		expect(landed.sort()).toEqual([1, 2]);
+	});
+
+	test('🔴 a failed write REJECTS settle() — `all`, not `allSettled`', async () => {
+		// The failure path this primitive exists for. `allSettled` would swallow the rejection
+		// and the entry point would answer 200 to a write that never landed, which reads to the
+		// person as the sign-out having taken.
+		const writes = createPendingWrites();
+		writes.add(Promise.resolve('this one is fine'));
+		writes.add(Promise.reject(new Error('D1_ERROR: no such table: sessions')));
+		await expect(writes.settle()).rejects.toThrow('no such table: sessions');
+	});
+
+	test('it collects the real statements a store queues, and they are durable after settle()', async () => {
+		// The whole shape in miniature: a synchronous caller queues D1 work it cannot await,
+		// and the row exists only because somebody settled.
+		const sqlite = seeded();
+		const db = perInvocation(createLocalD1(sqlite));
+		const writes = createPendingWrites();
+
+		const revoke = (id: number, name: string): void => {
+			writes.add(db.prepare('INSERT INTO people (id, name) VALUES (?, ?)').bind(id, name).run());
+		};
+		revoke(90, 'p90');
+		revoke(91, 'p91');
+
+		await writes.settle();
+		const rows = await db.prepare('SELECT name FROM people WHERE id >= 90 ORDER BY id').all<{ name: string }>();
+		expect(rows.results.map((r) => r.name)).toEqual(['p90', 'p91']);
+		// Two writes plus the read back — the collector adds no queries of its own.
+		expect(db.used).toBe(3);
+	});
+
+	test('an invocation that wrote nothing settles clean', async () => {
+		await expect(createPendingWrites().settle()).resolves.toBeUndefined();
+	});
+
+	test('it satisfies the two-method collector a store is handed', async () => {
+		// `cursedauth/d1-stores` declares this shape under its own name and may not import it
+		// from here. Structural, in both directions — this is that assertion at compile time.
+		const collector: { add(promise: Promise<unknown>): void } = createPendingWrites();
+		collector.add(Promise.resolve());
+		expect(typeof collector.add).toBe('function');
+	});
+});

package/src/server/d1/invocation.ts

@@ -39,6 +39,14 @@
  * It wraps either driver, because it sits ABOVE the seam and only counts. That is what
  * makes the local gate able to prove a production-only limit: wrap a local database in a
  * test, run the loop, and the laptop fails exactly where the Worker would.
+ *
+ * ## The other thing that is true for the span of one request: {@link createPendingWrites}
+ *
+ * A Worker port's synchronous stores answer from a snapshot and queue their durable writes
+ * as promises, which the entry point awaits BEFORE the response leaves. That collector has
+ * the same lifetime as the budget above — one per invocation, constructed by the caller in
+ * the same breath — so it lives in the same file. See its own header for why it was moved
+ * here on 2026-09-19.
  */
 
 import { LIMITS } from './limits';
@@ -205,3 +213,81 @@ export function perInvocation(db: D1LikeDatabase, opts: { max?: number } = {}):
 		},
 	};
 }
+
+/**
+ * Where a durable write goes on its way out of one invocation.
+ *
+ * Deliberately two members, and the narrower `add`-only half is what a STORE takes. A store
+ * that also held `settle` could end the request's writes from inside the request, which is
+ * the entry point's job and nobody else's. `cursedauth/d1-stores` declares exactly this
+ * two-method shape under its own name (`WriteCollector`) because that package sits UNDER
+ * this one and may not import it — structural typing means an object made here satisfies it
+ * verbatim, with no dependency edge in either direction.
+ */
+export interface WriteCollector {
+	add(promise: Promise<unknown>): void;
+}
+
+/** A write that must land before the response is returned. See {@link createPendingWrites}. */
+export interface PendingWrites extends WriteCollector {
+	/** Await every collected write. Called BEFORE the response is returned, never after. */
+	settle(): Promise<void>;
+}
+
+/**
+ * Collect the durable writes of ONE invocation, to be awaited before the response leaves.
+ *
+ * ## Why this is the Worker-write primitive and not a convenience
+ *
+ * A ported app's synchronous stores cannot await — their signatures are somebody else's
+ * published contract — so the shape every port lands on is: one read fills a snapshot, every
+ * sync call answers from it, and every mutation both updates the snapshot and pushes its
+ * statement's promise in here. The entry point then does the awaiting:
+ *
+ * ```ts
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const db     = perInvocation(createRemoteD1(env.DB));
+ *     const writes = createPendingWrites();
+ *     const res    = await app.fetch(req, { db, writes });
+ *     await writes.settle();          // 🔴 BEFORE the response, never after
+ *     return res;
+ *   },
+ * };
+ * ```
+ *
+ * 🔴 **`settle()` before the response, never `ctx.waitUntil`.** A Worker isolate is per-colo
+ * and short-lived; a write acknowledged by a 200 and then dropped means "sign out" reported
+ * success and left the credential live — a failure invisible to any single-process test and
+ * indistinguishable, to the person, from the feature being broken.
+ *
+ * 🔴 **`Promise.all`, not `allSettled`.** A failed durable write must not be reported as a
+ * success. It surfaces as a 500 from the entry point, which is the honest answer to "did my
+ * sign-out take". `allSettled` here would convert every lost write into a silent 200 — the
+ * same outcome as not collecting them at all, reached by a road that looks careful.
+ *
+ * ## Why it lives here
+ *
+ * It was written three times before it was published once — `apps/patterns/worker/stores.ts`,
+ * `apps/collections/worker/stores.ts` and `libs/cursedauth/src/d1Stores.ts`, byte-identical
+ * but for a comment, with six more ports queued behind them. It is a D1-INVOCATION primitive
+ * rather than an auth one, so it belongs beside {@link perInvocation}: both are constructed
+ * per request, both describe what is true for the span of one, and neither knows anything
+ * about who is signed in.
+ *
+ * Ordering is NOT what this gives you. Everything added is already in flight, so two writes
+ * that must land in order go in one `batch()`, never in two `add`s — a DELETE that must
+ * precede its INSERT will otherwise race and trip a unique index.
+ */
+export function createPendingWrites(): PendingWrites {
+	const pending: Promise<unknown>[] = [];
+	return {
+		add: (promise) => void pending.push(promise),
+		async settle() {
+			// `all`, not `allSettled`: a failed durable write must not be reported as a
+			// success. It surfaces as a 500 from the entry point, which is the honest answer
+			// to "did my sign-out take".
+			await Promise.all(pending);
+		},
+	};
+}