cursedbelt-server 4.46.1 → 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) ───────────────
  *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.46.1",
+	"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.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;