cursedbelt-server 4.46.0 → 4.47.0

package/dist/server/storage/binaryServerMeta.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What binary-server holds under MANY keys — `POST /internal/ops/meta`, one request per
+ * {@link BINARY_META_KEYS_MAX} keys (forge task 3385).
+ *
+ * 🔴 One client, because two hand-rolled copies drifted into being: collections' media-cipher
+ * sweep (forge task 2634 — ~880 per-key `/meta` asks a run against its 8/s bulk ceiling, ~2,300
+ * refusals an hour) and music's nightly missing-bytes check (forge task 3382) each carried the
+ * loop and a copied `1_000`. A change to the route's cap or shape is now one edit here, and
+ * binary-server takes its own cap from {@link BINARY_META_KEYS_MAX}, so the two cannot disagree.
+ *
+ * The route is internal-secret gated and loopback-only (`/internal/ops/*` 404s on the public
+ * hostname), so `baseUrl` is binary-server's INTERNAL origin, never the tunnel's.
+ */
+/** Keys per `POST /internal/ops/meta` — binary-server's `META_KEYS_MAX` is this constant. */
+export declare const BINARY_META_KEYS_MAX = 1000;
+/** One key's answer: an indexed, active row whose bytes exist. */
+export interface StoredMeta {
+    size: number;
+    mime: string | null;
+    checksum: string | null;
+}
+export interface MetaManyTarget {
+    /** binary-server's internal origin (`BINARY_SERVER_INTERNAL_URL`). */
+    baseUrl: string | undefined;
+    internalSecret: string | undefined;
+    /** The tenant the keys belong to. */
+    app: string;
+}
+export interface MetaManyOptions {
+    fetchImpl?: (url: string, init: RequestInit) => Promise<Response>;
+    /** Per batch. Default {@link BINARY_META_BATCH_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/**
+ * Every asked key → its {@link StoredMeta}, or `null` when the store holds nothing live there.
+ *
+ * The whole answer is `null` on ANY failure — no origin or secret, a refusal (an older
+ * binary-server without the route answers 404; a batch over its cap, 400), a timeout, a body of
+ * another shape. Callers then ask key by key, as before: slower, never wrong. A partial map is
+ * never returned, so "absent from the map" cannot be mistaken for "not held".
+ */
+export declare function metaMany(to: MetaManyTarget, keys: readonly string[], opts?: MetaManyOptions): Promise<Map<string, StoredMeta | null> | null>;

package/dist/server/storage/binaryServerMeta.js

@@ -0,0 +1,57 @@
+/**
+ * What binary-server holds under MANY keys — `POST /internal/ops/meta`, one request per
+ * {@link BINARY_META_KEYS_MAX} keys (forge task 3385).
+ *
+ * 🔴 One client, because two hand-rolled copies drifted into being: collections' media-cipher
+ * sweep (forge task 2634 — ~880 per-key `/meta` asks a run against its 8/s bulk ceiling, ~2,300
+ * refusals an hour) and music's nightly missing-bytes check (forge task 3382) each carried the
+ * loop and a copied `1_000`. A change to the route's cap or shape is now one edit here, and
+ * binary-server takes its own cap from {@link BINARY_META_KEYS_MAX}, so the two cannot disagree.
+ *
+ * The route is internal-secret gated and loopback-only (`/internal/ops/*` 404s on the public
+ * hostname), so `baseUrl` is binary-server's INTERNAL origin, never the tunnel's.
+ */
+/** Keys per `POST /internal/ops/meta` — binary-server's `META_KEYS_MAX` is this constant. */
+export const BINARY_META_KEYS_MAX = 1_000;
+/** How long one batch may take: a batch of keys the store's memo lacks is HEADed eight at a time. */
+const BINARY_META_BATCH_TIMEOUT_MS = 180_000;
+/**
+ * Every asked key → its {@link StoredMeta}, or `null` when the store holds nothing live there.
+ *
+ * The whole answer is `null` on ANY failure — no origin or secret, a refusal (an older
+ * binary-server without the route answers 404; a batch over its cap, 400), a timeout, a body of
+ * another shape. Callers then ask key by key, as before: slower, never wrong. A partial map is
+ * never returned, so "absent from the map" cannot be mistaken for "not held".
+ */
+export async function metaMany(to, keys, opts = {}) {
+    if (!to.baseUrl || !to.internalSecret)
+        return null;
+    const doFetch = opts.fetchImpl ?? fetch;
+    const url = `${to.baseUrl.replace(/\/+$/, '')}/internal/ops/meta`;
+    const out = new Map();
+    try {
+        for (let i = 0; i < keys.length; i += BINARY_META_KEYS_MAX) {
+            const batch = keys.slice(i, i + BINARY_META_KEYS_MAX);
+            const res = await doFetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-internal-secret': to.internalSecret },
+                body: JSON.stringify({ app: to.app, keys: batch }),
+                signal: AbortSignal.timeout(opts.timeoutMs ?? BINARY_META_BATCH_TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            if (!body?.metas || typeof body.metas !== 'object')
+                return null;
+            const metas = body.metas;
+            for (const key of batch) {
+                const m = metas[key];
+                out.set(key, m && typeof m.size === 'number' ? { size: m.size, mime: m.mime ?? null, checksum: m.checksum ?? null } : null);
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return out;
+}

package/dist/server/storage/binaryStore.d.ts

@@ -6,6 +6,8 @@ import type { FileTokenClaims } from './types.js';
  * this module read unchanged.
  */
 export type { FileTokenClaims };
+/** The batched `/internal/ops/meta` client — its own module so the store's graph stays the store's. */
+export { BINARY_META_KEYS_MAX, metaMany, type StoredMeta } from './binaryServerMeta.js';
 export interface BinaryStoreConfig {
     /** e.g. `http://127.0.0.1:3099` or `https://binary-server.cursedalchemy.com`. */
     baseUrl: string;

package/dist/server/storage/binaryStore.js

@@ -41,6 +41,8 @@
  * behavioural difference in any of the three, so nothing was dropped to land the union.
  */
 import { createHash, createPrivateKey, createPublicKey, sign as cryptoSign } from 'node:crypto';
+/** The batched `/internal/ops/meta` client — its own module so the store's graph stays the store's. */
+export { BINARY_META_KEYS_MAX, metaMany } from './binaryServerMeta.js';
 /*
  * ── The process-wide repeat register (§ the repeat-key counter) ───────────────
  *
@@ -417,13 +419,16 @@ export function createBinaryStore(cfg) {
      * caller asked for `paced` and the budget allows, otherwise thrown as a typed error that
      * keeps the `[binary-store] <op> <key>: 429` message batch callers already match.
      */
-    const sendRead = async (op, key, url, init, opts) => {
+    const sendRead = async (op, key, 
+    /** Signs the URL. Called for EVERY attempt: a read token lives 60 s and a paced read may wait
+     *  120 s, so a URL signed once went out dead after the first long retry-after (forge task 3302). */
+    mint, init, opts) => {
         const budget = opts?.paced
             ? (typeof opts.paced === 'object' ? opts.paced.maxWaitMs : undefined) ?? BINARY_PACED_MAX_WAIT_MS
             : 0;
         let waited = 0;
         for (let attempt = 0;; attempt++) {
-            const res = await send(url, init);
+            const res = await send(await mint(), init);
             if (res.status !== 429)
                 return res;
             const retryAfterSec = retryAfterSeconds(res.headers.get('retry-after'), attempt);
@@ -548,7 +553,7 @@ export function createBinaryStore(cfg) {
             if (!opts?.fresh && knownAbsent(key))
                 return null;
             countWireRead(key);
-            const res = await sendRead('get', key, await internalMediaUrl(key), undefined, opts);
+            const res = await sendRead('get', key, () => internalMediaUrl(key), undefined, opts);
             if (res.status === 404) {
                 rememberAbsent(key);
                 return null;
@@ -624,7 +629,7 @@ export function createBinaryStore(cfg) {
                     return null;
             }
             countWireRead(key);
-            const res = await sendRead('meta', key, await metaUrl(key), undefined, opts);
+            const res = await sendRead('meta', key, () => metaUrl(key), undefined, opts);
             if (res.status === 404) {
                 rememberAbsent(key);
                 return null;
@@ -671,7 +676,7 @@ export function createBinaryStore(cfg) {
                     throw why;
             }
             countWireRead(key);
-            const res = await sendRead('stat', key, await internalMediaUrl(key), { headers: { Range: 'bytes=0-0' } }, opts);
+            const res = await sendRead('stat', key, () => internalMediaUrl(key), { headers: { Range: 'bytes=0-0' } }, opts);
             if (res.status === 404) {
                 rememberAbsent(key);
                 return null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.46.0",
+	"version": "4.47.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",

package/src/leafSubpathsImportNothing.spec.ts

@@ -144,8 +144,10 @@ const LEAVES = [
      * in `src/server/storage/` beside the file-catalogue and transcode graph, which is
      * exactly the barrel this must never be reached through: `./storage`'s index is heavy
      * and this module's whole point is that it costs `node:crypto` and nothing else.
+     * Its batched `/internal/ops/meta` client (4.47.0) is a sibling that imports nothing.
      */
     evaluates: 'createBinaryStore',
+    siblings: ['src/server/storage/binaryServerMeta.ts'],
   },
   {
     subpath: './binary-store/testing',

package/src/server/storage/binaryServerMeta.spec.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'bun:test';
+import { BINARY_META_KEYS_MAX, metaMany } from './binaryStore.js';
+
+type Call = { url: string; init: RequestInit };
+const target = { baseUrl: 'http://127.0.0.1:3099/', internalSecret: 's3cret', app: 'music' };
+
+/** A store that holds every key whose name starts with `held/`, answering in the route's shape. */
+function store(calls: Call[], answer?: (keys: string[]) => Response) {
+  return async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    const { keys } = JSON.parse(String(init.body)) as { keys: string[] };
+    if (answer) return answer(keys);
+    const metas = Object.fromEntries(keys.map((k) => [k, k.startsWith('held/') ? { size: 7, mime: 'audio/mp4', checksum: 'abc' } : null]));
+    return Response.json({ app: 'music', metas });
+  };
+}
+
+describe('metaMany', () => {
+  it('asks one request per BINARY_META_KEYS_MAX keys, and answers every key', async () => {
+    const calls: Call[] = [];
+    const keys = Array.from({ length: BINARY_META_KEYS_MAX * 2 + 1 }, (_, i) => (i % 2 ? `held/${i}` : `gone/${i}`));
+    const got = await metaMany(target, keys, { fetchImpl: store(calls) });
+    expect(calls.map((c) => (JSON.parse(String(c.init.body)) as { keys: string[] }).keys.length)).toEqual([BINARY_META_KEYS_MAX, BINARY_META_KEYS_MAX, 1]);
+    expect(calls[0]?.url).toBe('http://127.0.0.1:3099/internal/ops/meta');
+    expect(calls[0]?.init.headers).toMatchObject({ 'x-internal-secret': 's3cret' });
+    expect(got?.size).toBe(keys.length);
+    expect(got?.get('held/1')).toEqual({ size: 7, mime: 'audio/mp4', checksum: 'abc' });
+    expect(got?.get('gone/0')).toBeNull();
+  });
+
+  it('is null — never a partial map — when any batch fails', async () => {
+    let n = 0;
+    const keys = Array.from({ length: BINARY_META_KEYS_MAX + 1 }, (_, i) => `held/${i}`);
+    const second404 = store([], (asked) => (n++ === 0 ? Response.json({ metas: Object.fromEntries(asked.map((k) => [k, null])) }) : new Response('nope', { status: 404 })));
+    expect(await metaMany(target, keys, { fetchImpl: second404 })).toBeNull();
+  });
+
+  it('is null on a body of another shape, a throw, or no origin/secret — and asks nothing then', async () => {
+    expect(await metaMany(target, ['k'], { fetchImpl: store([], () => Response.json({ ok: true })) })).toBeNull();
+    expect(await metaMany(target, ['k'], { fetchImpl: async () => { throw new Error('ECONNREFUSED'); } })).toBeNull();
+    const calls: Call[] = [];
+    expect(await metaMany({ ...target, internalSecret: undefined }, ['k'], { fetchImpl: store(calls) })).toBeNull();
+    expect(await metaMany({ ...target, baseUrl: '' }, ['k'], { fetchImpl: store(calls) })).toBeNull();
+    expect(calls).toHaveLength(0);
+  });
+
+  it('reads a key the store left out of its answer as not held', async () => {
+    const got = await metaMany(target, ['held/a', 'held/b'], { fetchImpl: store([], () => Response.json({ metas: { 'held/a': { size: 1 } } })) });
+    expect(got?.get('held/a')).toEqual({ size: 1, mime: null, checksum: null });
+    expect(got?.get('held/b')).toBeNull();
+  });
+});

package/src/server/storage/binaryServerMeta.ts

@@ -0,0 +1,81 @@
+/**
+ * What binary-server holds under MANY keys — `POST /internal/ops/meta`, one request per
+ * {@link BINARY_META_KEYS_MAX} keys (forge task 3385).
+ *
+ * 🔴 One client, because two hand-rolled copies drifted into being: collections' media-cipher
+ * sweep (forge task 2634 — ~880 per-key `/meta` asks a run against its 8/s bulk ceiling, ~2,300
+ * refusals an hour) and music's nightly missing-bytes check (forge task 3382) each carried the
+ * loop and a copied `1_000`. A change to the route's cap or shape is now one edit here, and
+ * binary-server takes its own cap from {@link BINARY_META_KEYS_MAX}, so the two cannot disagree.
+ *
+ * The route is internal-secret gated and loopback-only (`/internal/ops/*` 404s on the public
+ * hostname), so `baseUrl` is binary-server's INTERNAL origin, never the tunnel's.
+ */
+
+/** Keys per `POST /internal/ops/meta` — binary-server's `META_KEYS_MAX` is this constant. */
+export const BINARY_META_KEYS_MAX = 1_000;
+
+/** How long one batch may take: a batch of keys the store's memo lacks is HEADed eight at a time. */
+const BINARY_META_BATCH_TIMEOUT_MS = 180_000;
+
+/** One key's answer: an indexed, active row whose bytes exist. */
+export interface StoredMeta {
+  size: number;
+  mime: string | null;
+  checksum: string | null;
+}
+
+export interface MetaManyTarget {
+  /** binary-server's internal origin (`BINARY_SERVER_INTERNAL_URL`). */
+  baseUrl: string | undefined;
+  internalSecret: string | undefined;
+  /** The tenant the keys belong to. */
+  app: string;
+}
+
+export interface MetaManyOptions {
+  fetchImpl?: (url: string, init: RequestInit) => Promise<Response>;
+  /** Per batch. Default {@link BINARY_META_BATCH_TIMEOUT_MS}. */
+  timeoutMs?: number;
+}
+
+/**
+ * Every asked key → its {@link StoredMeta}, or `null` when the store holds nothing live there.
+ *
+ * The whole answer is `null` on ANY failure — no origin or secret, a refusal (an older
+ * binary-server without the route answers 404; a batch over its cap, 400), a timeout, a body of
+ * another shape. Callers then ask key by key, as before: slower, never wrong. A partial map is
+ * never returned, so "absent from the map" cannot be mistaken for "not held".
+ */
+export async function metaMany(
+  to: MetaManyTarget,
+  keys: readonly string[],
+  opts: MetaManyOptions = {},
+): Promise<Map<string, StoredMeta | null> | null> {
+  if (!to.baseUrl || !to.internalSecret) return null;
+  const doFetch = opts.fetchImpl ?? fetch;
+  const url = `${to.baseUrl.replace(/\/+$/, '')}/internal/ops/meta`;
+  const out = new Map<string, StoredMeta | null>();
+  try {
+    for (let i = 0; i < keys.length; i += BINARY_META_KEYS_MAX) {
+      const batch = keys.slice(i, i + BINARY_META_KEYS_MAX);
+      const res = await doFetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-internal-secret': to.internalSecret },
+        body: JSON.stringify({ app: to.app, keys: batch }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? BINARY_META_BATCH_TIMEOUT_MS),
+      });
+      if (!res.ok) return null;
+      const body = (await res.json()) as { metas?: unknown } | null;
+      if (!body?.metas || typeof body.metas !== 'object') return null;
+      const metas = body.metas as Record<string, Partial<StoredMeta> | null | undefined>;
+      for (const key of batch) {
+        const m = metas[key];
+        out.set(key, m && typeof m.size === 'number' ? { size: m.size, mime: m.mime ?? null, checksum: m.checksum ?? null } : null);
+      }
+    }
+  } catch {
+    return null;
+  }
+  return out;
+}

package/src/server/storage/binaryStore.spec.ts

@@ -26,7 +26,7 @@
  * server; the RSA keypair is generated in-process and the signature is verified with
  * `node:crypto`, which is what makes the token assertions real rather than shape-deep.
  */
-import { afterAll, afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { afterAll, afterEach, beforeEach, describe, expect, it, setSystemTime } from 'bun:test';
 import { generateKeyPairSync, verify as cryptoVerify } from 'node:crypto';
 import {
   AUTO_CHUNK_THRESHOLD_BYTES,
@@ -1056,6 +1056,29 @@ describe('🔴 a read the store PACES is waited out when asked, typed when not (
     expect(calls).toHaveLength(4);
   });
 
+  it('🔴 every attempt goes with a token signed for IT — a 60 s token outlives no 120 s wait (forge task 3302)', async () => {
+    // The URL was signed once, before the first attempt, so a paced read that waited out 30 s
+    // refusals sent a dead token on its third try, and binary-server answered 403 — not 429.
+    try {
+      let n = 0;
+      reply = () => (n++ < 3 ? limited('30') : ok(new Uint8Array([7, 8])));
+      const store = makeStore({
+        sleep: (ms) => {
+          setSystemTime(new Date(Date.now() + ms));
+          return Promise.resolve();
+        },
+      });
+      await store.get('parts/0', { paced: true });
+      expect(calls).toHaveLength(4);
+      // The last attempt went 90 s after the first: its token must still have time left.
+      const token = new URL(String(calls.at(-1)?.url)).searchParams.get('token') ?? '';
+      const { exp } = JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString('utf8')) as { exp: number };
+      expect(exp * 1000).toBeGreaterThan(Date.now());
+    } finally {
+      setSystemTime();
+    }
+  });
+
   it('without paced, a 429 is the typed error carrying retryAfterSec — and the old message', async () => {
     const { store, slept } = pacedStore(1, '7');
     const error = await store.get('parts/0').catch((e: unknown) => e);

package/src/server/storage/binaryStore.ts

@@ -51,6 +51,9 @@ import type { FileTokenClaims } from './types.js';
  */
 export type { FileTokenClaims };
 
+/** The batched `/internal/ops/meta` client — its own module so the store's graph stays the store's. */
+export { BINARY_META_KEYS_MAX, metaMany, type StoredMeta } from './binaryServerMeta.js';
+
 export interface BinaryStoreConfig {
   /** e.g. `http://127.0.0.1:3099` or `https://binary-server.cursedalchemy.com`. */
   baseUrl: string;
@@ -728,7 +731,9 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
   const sendRead = async (
     op: string,
     key: string,
-    url: string,
+    /** Signs the URL. Called for EVERY attempt: a read token lives 60 s and a paced read may wait
+     *  120 s, so a URL signed once went out dead after the first long retry-after (forge task 3302). */
+    mint: () => Promise<string>,
     init: RequestInit | undefined,
     opts: ReadOptions | undefined,
   ): Promise<Response> => {
@@ -737,7 +742,7 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
       : 0;
     let waited = 0;
     for (let attempt = 0; ; attempt++) {
-      const res = await send(url, init);
+      const res = await send(await mint(), init);
       if (res.status !== 429) return res;
       const retryAfterSec = retryAfterSeconds(res.headers.get('retry-after'), attempt);
       const ms = retryAfterSec * 1000;
@@ -875,7 +880,7 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
       // short-circuit here — we want the bytes, and only the store has them.
       if (!opts?.fresh && knownAbsent(key)) return null;
       countWireRead(key);
-      const res = await sendRead('get', key, await internalMediaUrl(key), undefined, opts);
+      const res = await sendRead('get', key, () => internalMediaUrl(key), undefined, opts);
       if (res.status === 404) {
         rememberAbsent(key);
         return null;
@@ -952,7 +957,7 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
         if (knownAbsent(key)) return null;
       }
       countWireRead(key);
-      const res = await sendRead('meta', key, await metaUrl(key), undefined, opts);
+      const res = await sendRead('meta', key, () => metaUrl(key), undefined, opts);
       if (res.status === 404) {
         rememberAbsent(key);
         return null;
@@ -995,7 +1000,7 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
         if (why instanceof BinaryStoreRateLimitedError) throw why;
       }
       countWireRead(key);
-      const res = await sendRead('stat', key, await internalMediaUrl(key), { headers: { Range: 'bytes=0-0' } }, opts);
+      const res = await sendRead('stat', key, () => internalMediaUrl(key), { headers: { Range: 'bytes=0-0' } }, opts);
       if (res.status === 404) {
         rememberAbsent(key);
         return null;