cursedbelt-server 4.0.0 → 4.1.0

package/src/server/storage/binaryStoreFake.ts

@@ -0,0 +1,111 @@
+/**
+ * A `BinaryStore` that does nothing, so adding a method to the interface stops
+ * breaking twenty-two test files in apps nobody touched.
+ *
+ * ── The measurement (2026-09-08) ────────────────────────────────────────────
+ * `BinaryStore.fetchMedia` was added to serve audio off this Mac while
+ * Cloudflare's daily Worker quota was spent — a good change, landed on `main`,
+ * with apps/music green. It also broke **apps/collections and apps/roms**, four
+ * test files each, with `Property 'fetchMedia' is missing in type`. Both apps
+ * were left unable to typecheck, and therefore unable to gate or deploy, by a
+ * commit neither of them appears in. Nobody noticed for hours: a worker's
+ * `verify:scoped` only typechecks the workspaces its own diff touches, which is
+ * exactly the property that makes it fast.
+ *
+ * The owner's rule, in his words: *"a change to roms for example cannot block
+ * family tree app from passing its tests."* This is that rule for the one
+ * interface twenty-two suites all fake by hand.
+ *
+ * 🔴 **This is why the fake travels WITH the interface, into this package.** An
+ * interface whose change can break two other apps from a third app's commit is a
+ * shared interface already; a fake living in a different repo from the interface it
+ * fakes cannot do the job it exists for, because the two can be changed
+ * independently. Published as `cursedbelt-server/binary-store/testing`, beside
+ * `cursedbelt-server/binary-store` — the same split as `./d1` and `./d1/testing`, and
+ * for the same reason: a consumer's PRODUCTION graph must not be able to reach a
+ * fake.
+ *
+ * ── 🔴 Why defaults and not optional members ────────────────────────────────
+ * The obvious alternative is to mark each new capability `fetchMedia?:` on the
+ * interface. That moves the cost to every REAL consumer — each one then has to
+ * narrow before calling, for a method the production store always has — and it
+ * makes "did we implement this?" unanswerable by the typechecker, which is the
+ * one question the interface exists to answer. The fakes are the side that
+ * should absorb the change, so the defaults live here.
+ *
+ * ── What a default may do ───────────────────────────────────────────────────
+ * As little as possible, and never something a test could mistake for a result.
+ * `get` and `meta` answer "not here"; `fetchMedia` answers 404; the mutators do
+ * nothing. A suite that cares about any of them overrides it — spread this first
+ * and the file's own members win:
+ *
+ *     const store: BinaryStore = {
+ *       ...binaryStoreFakeDefaults("collections"),
+ *       async meta(key) { … what this suite is actually about … },
+ *     };
+ */
+import type { BinaryStore, FileTokenClaims } from './binaryStore';
+
+/**
+ * Every member of {@link BinaryStore}, inert.
+ *
+ * @param appId the tenant the fake claims to be. Required, and deliberately so —
+ *        a blank tenant is the mistake `binaryStoreTenant` exists to catch, and a
+ *        fake that quietly defaults it would hide a test written against the
+ *        wrong app.
+ */
+export function binaryStoreFakeDefaults(appId: string): BinaryStore {
+  return {
+    appId,
+    async put(): Promise<void> {},
+    async putLarge(): Promise<void> {},
+    async get(): Promise<Uint8Array | null> {
+      return null;
+    },
+    async meta(): Promise<null> {
+      return null;
+    },
+    async stat(): Promise<null> {
+      return null;
+    },
+    async has(): Promise<boolean> {
+      return false;
+    },
+    // 🔴 `"unknown"`, never `"absent"`. A fake that claimed to know a key is missing
+    // would let a listing route's "answer only from the memo" branch look exercised
+    // when nothing was ever memoized — the one thing a test of that branch is for.
+    known(): 'present' | 'absent' | 'unknown' {
+      return 'unknown';
+    },
+    // 🔴 `0`, and never a lie about work done. The real one returns how many
+    // negative memos it dropped, and an app's repair route reports that number to
+    // the owner — a fake that invented one would make a broken repair read as a
+    // working one in the only test that could catch it.
+    forgetMisses(): number {
+      return 0;
+    },
+    cacheStats(): { present: number; absent: number } {
+      return { present: 0, absent: 0 };
+    },
+    async remove(): Promise<void> {},
+    async removePrefix(): Promise<void> {},
+    async mediaUrl(key: string): Promise<string> {
+      // Carries the key, so an assertion on "which object was linked" reads.
+      return `https://binary-server.test/media/${appId}/${key}`;
+    },
+    async mediaPrefixUrl(prefix: string, master: string): Promise<string> {
+      // Carries BOTH, because the bug this shape exists to prevent is signing the wrong
+      // one of them — a URL pointing at the master but scoped to the wrong prefix 403s
+      // every segment while the master itself loads fine.
+      return `https://binary-server.test/media/${appId}/${master}?p=${encodeURIComponent(prefix)}`;
+    },
+    async fetchMedia(): Promise<Response> {
+      // 🔴 404, not an empty 200. A fake that answers "here are zero bytes" makes a
+      // streaming route look like it worked on an object that does not exist.
+      return new Response(null, { status: 404 });
+    },
+    async signToken(_claims: FileTokenClaims, _ttlSeconds: number): Promise<string> {
+      return 'fake-token';
+    },
+  };
+}