cursedbelt-server 4.8.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);
+		},
+	};
+}

package/src/server/storage/files/chunkedUpload.spec.ts

@@ -39,7 +39,7 @@ describe('chunked upload', () => {
       now: () => ++clock,
     });
     const ledger = createStorageOpsLedger(db, () => ++clock);
-    const minted: Array<{ key: string; sid: string; ci: number; tc: number }> = [];
+    const minted: Array<{ key: string; sid: string; ci: number; tc: number; sz?: number }> = [];
     const svc = createChunkedUploadService({
       catalogue,
       ledger,
@@ -67,6 +67,10 @@ describe('chunked upload', () => {
     expect(init.chunkUploadUrls).toHaveLength(3);
     expect(minted.map((m) => m.ci)).toEqual([0, 1, 2]);
     expect(minted.every((m) => m.tc === 3 && m.sid === init.sid)).toBe(true);
+    // 🔴 The SOURCE length, on every chunk. `tc` is derived from it and a count is not a length:
+    // without this the minter has nothing to put in the token's `sz` claim, and binary-server's
+    // only end-to-end check of the finished object against its source stays inert.
+    expect(minted.map((m) => m.sz)).toEqual([20 * 1024 * 1024, 20 * 1024 * 1024, 20 * 1024 * 1024]);
     // The mint targets exactly the key the catalogue will look for on complete.
     expect(init.key).toBe(catalogueUploadKey('u1', init.fileId, 'image/png'));
 
@@ -78,6 +82,16 @@ describe('chunked upload', () => {
     expect(svc.pending()).toBe(1);
   });
 
+  test('🔴 a size the caller could not state is OMITTED, never declared as zero', async () => {
+    // `sz: 0` would compare zero to the assembled length and refuse every assemble — so an
+    // unknown size degrades to exactly today's behaviour (no claim, recorded undeclared) rather
+    // than to a 422. `chunkCount` still clamps to one chunk, which is the old `req.size || 1`.
+    const { svc, minted } = build();
+    const init = await svc.init(CTX, { name: 'unknown.bin', mime: 'application/octet-stream', size: 0 });
+    expect(init.chunkCount).toBe(1);
+    expect(minted.map((m) => m.sz)).toEqual([undefined]);
+  });
+
   test('complete registers the catalogue row over the assembled bytes + marks the op done', async () => {
     const { catalogue, ledger, svc } = build();
     const init = await svc.init(CTX, {

package/src/server/storage/files/chunkedUpload.ts

@@ -64,7 +64,7 @@ export interface ChunkedUploadService {
 /**
  * Mint the direct-to-backend PUT URL for one chunk. The app supplies this so the module stays
  * backend-agnostic. For binary-server: `${base}/upload-chunk/${app}/${key}?token=` with a token
- * carrying { k, uid, sid, ci, tc }.
+ * carrying { k, uid, sid, ci, tc, sz }.
  */
 export type MintChunkUpload = (args: {
   key: string;
@@ -72,6 +72,17 @@ export type MintChunkUpload = (args: {
   ci: number;
   tc: number;
   owner: string;
+  /**
+   * The SOURCE byte length this session was opened with — pass it straight into the token's `sz`
+   * claim (`FileTokenClaims.sz`), which is the only end-to-end integrity check the upload path
+   * has: binary-server compares it to the assembled object and answers 422 instead of indexing a
+   * short one.
+   *
+   * 🔴 `undefined` when the caller could not state a positive length, and then the claim must be
+   * OMITTED rather than sent as `0` — a declared zero refuses every assemble. That is the same
+   * posture the claim itself has: optional, so that declaring it could never take an upload down.
+   */
+  sz?: number;
 }) => Promise<string>;
 
 export function createChunkedUploadService(cfg: {
@@ -110,9 +121,14 @@ export function createChunkedUploadService(cfg: {
         tags: req.tags,
         createdAt: now(),
       });
+      // 🔴 The source length rides along, because `chunkCount` above is derived from it and a
+      // count is not a length: a session that splits the file wrongly stores whatever it sent,
+      // faithfully, with a 201. Omitted rather than zeroed when the caller stated no positive
+      // size — `sz: 0` would refuse every assemble. See `MintChunkUpload.sz`.
+      const declaredSize = Number.isFinite(req.size) && req.size > 0 ? req.size : undefined;
       const chunkUploadUrls = await Promise.all(
         Array.from({ length: chunkCount }, (_, ci) =>
-          cfg.mintChunkUpload({ key, sid, ci, tc: chunkCount, owner }),
+          cfg.mintChunkUpload({ key, sid, ci, tc: chunkCount, owner, sz: declaredSize }),
         ),
       );
       return { fileId, sid, key, chunkSize, chunkCount, chunkUploadUrls };