cursedbelt-server 4.33.1 → 4.34.0

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

@@ -405,6 +405,29 @@ export declare function binaryStoreTenant(appId: string, env?: Record<string, st
  * apps and that is precisely why the difference goes unnoticed when it is not.
  */
 export declare function resolvedMediaTenant(appId: string, env?: Record<string, string | undefined>): string | null;
+/**
+ * binary-server's origin did not ANSWER a write — as opposed to answering "no".
+ *
+ * binary-server itself never answers 502, 503 or 504; those, and Cloudflare's 52x family (530 is a
+ * tunnel with no connector), are the edge speaking for an origin it could not reach — the owner's
+ * Mac off, asleep, or restarting. A thrown `fetch` is the same fact. Since 2026-09-26 the edge
+ * Worker takes an R2-backed tenant's whole upload itself in that case
+ * (`apps/binary-server/edge-worker/src/upload.ts`), so for desk and family this is what is left
+ * when BOTH halves failed; for a tenant whose bytes rest on the Mac it is simply "the Mac is off".
+ */
+export declare function storeUnreachableStatus(status: number): boolean;
+/**
+ * The write could not reach the store. Carries `getResponse()`, so a Hono app that lets it escape
+ * a route answers a 503 that names the file store — Hono's default error handler returns
+ * `err.getResponse()` for any error that has one — instead of a bare `500 Internal Server Error`.
+ * The message keeps the `[binary-store] <op> <key>:` head every batch caller already prints.
+ */
+export declare class BinaryStoreUnreachableError extends Error {
+    readonly status = 503;
+    readonly code = "BYTE_STORE_UNREACHABLE";
+    constructor(op: string, key: string, detail: string);
+    getResponse(): Response;
+}
 /**
  * The standard env surface every tenant's secrets file carries
  * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):

package/dist/server/storage/binaryStore.js

@@ -430,7 +430,11 @@ export function createBinaryStore(cfg) {
                 method: 'PUT',
                 headers: mime ? { 'content-type': mime } : undefined,
                 body: bytes,
+            }).catch((cause) => {
+                throw new BinaryStoreUnreachableError('put', key, cause instanceof Error ? cause.message : String(cause));
             });
+            if (storeUnreachableStatus(res.status))
+                throw new BinaryStoreUnreachableError('put', key, String(res.status));
             if (!res.ok) {
                 // A 413 that reaches here despite the threshold above means the edge's
                 // real cap is lower than we think, or the caller disabled the
@@ -499,7 +503,12 @@ export function createBinaryStore(cfg) {
                     method: 'PUT',
                     headers: mime ? { 'content-type': mime } : undefined,
                     body: slice,
+                }).catch((cause) => {
+                    throw new BinaryStoreUnreachableError('putLarge', key, cause instanceof Error ? cause.message : String(cause));
                 });
+                if (storeUnreachableStatus(res.status)) {
+                    throw new BinaryStoreUnreachableError('putLarge', key, `chunk ${ci + 1}/${total}: ${res.status}`);
+                }
                 if (!res.ok) {
                     throw new Error(`[binary-store] putLarge ${key} chunk ${ci + 1}/${total}: ${res.status}`);
                 }
@@ -752,6 +761,40 @@ export function binaryStoreTenant(appId, env = process.env) {
 export function resolvedMediaTenant(appId, env = process.env) {
     return readBinaryStoreEnv(appId, env)?.appId ?? null;
 }
+/**
+ * binary-server's origin did not ANSWER a write — as opposed to answering "no".
+ *
+ * binary-server itself never answers 502, 503 or 504; those, and Cloudflare's 52x family (530 is a
+ * tunnel with no connector), are the edge speaking for an origin it could not reach — the owner's
+ * Mac off, asleep, or restarting. A thrown `fetch` is the same fact. Since 2026-09-26 the edge
+ * Worker takes an R2-backed tenant's whole upload itself in that case
+ * (`apps/binary-server/edge-worker/src/upload.ts`), so for desk and family this is what is left
+ * when BOTH halves failed; for a tenant whose bytes rest on the Mac it is simply "the Mac is off".
+ */
+export function storeUnreachableStatus(status) {
+    return status === 502 || status === 503 || status === 504 || (status >= 520 && status <= 530);
+}
+/**
+ * The write could not reach the store. Carries `getResponse()`, so a Hono app that lets it escape
+ * a route answers a 503 that names the file store — Hono's default error handler returns
+ * `err.getResponse()` for any error that has one — instead of a bare `500 Internal Server Error`.
+ * The message keeps the `[binary-store] <op> <key>:` head every batch caller already prints.
+ */
+export class BinaryStoreUnreachableError extends Error {
+    status = 503;
+    code = 'BYTE_STORE_UNREACHABLE';
+    constructor(op, key, detail) {
+        super(`[binary-store] ${op} ${key}: the file store did not answer (${detail}) — nothing was saved; ` +
+            'everything already stored still opens. Try again when the home server is on.');
+        this.name = 'BinaryStoreUnreachableError';
+    }
+    getResponse() {
+        return new Response(JSON.stringify({
+            error: this.code,
+            message: 'The file store did not answer, so nothing was saved. Everything already stored still opens — try again in a moment.',
+        }), { status: 503, headers: { 'content-type': 'application/json; charset=utf-8', 'retry-after': '30' } });
+    }
+}
 /**
  * The standard env surface every tenant's secrets file carries
  * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.33.1",
+	"version": "4.34.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/server/storage/binaryStore.spec.ts

@@ -34,6 +34,7 @@ import {
   BINARY_REPEAT_THRESHOLD,
   BINARY_REPEAT_WINDOW_MS,
   type BinaryStoreConfig,
+  BinaryStoreUnreachableError,
   binaryStoreTenant,
   createBinaryStore,
   normalizePrivateKeyPem,
@@ -41,6 +42,7 @@ import {
   repeatedBinaryKeys,
   resetRepeatedBinaryKeys,
   resolvedMediaTenant,
+  storeUnreachableStatus,
   wantsFresh,
 } from './binaryStore.js';
 import { binaryStoreFakeDefaults } from './binaryStoreFake.js';
@@ -962,3 +964,58 @@ describe('binaryStoreFakeDefaults', () => {
     expect(await fake.signToken({ k: 'c/a' }, 60)).toBe('fake-token');
   });
 });
+
+describe('🔴 a write the store could not ANSWER is a 503 that names it (2026-09-26)', () => {
+  it('502-504 and 52x/530 are the origin unreachable; everything else is its own answer', () => {
+    for (const status of [502, 503, 504, 520, 522, 524, 530]) expect(storeUnreachableStatus(status)).toBe(true);
+    for (const status of [400, 403, 404, 413, 422, 500, 507]) expect(storeUnreachableStatus(status)).toBe(false);
+  });
+
+  it('put on a 530 throws the typed error, keeping the [binary-store] head batch callers print', async () => {
+    reply = () => new Response('tunnel gone', { status: 530 });
+    const error = await makeStore().put('art/a.png', new Uint8Array([1])).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toStartWith('[binary-store] put art/a.png: the file store did not answer (530)');
+    expect((error as BinaryStoreUnreachableError).status).toBe(503);
+  });
+
+  it('a fetch that THROWS is the same fact', async () => {
+    const store = makeStore({ fetch: () => Promise.reject(new Error('connection refused')) });
+    const error = await store.put('k', new Uint8Array([1])).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toContain('connection refused');
+  });
+
+  it('putLarge says which chunk found the store gone', async () => {
+    reply = () => new Response('', { status: 502 });
+    const error = await makeStore()
+      .putLarge('v.mp4', new Uint8Array(10), 'video/mp4', { chunkBytes: 4 })
+      .catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toContain('chunk 1/3: 502');
+  });
+
+  it('🔴 getResponse() is the 503 a Hono app answers with when the error escapes a route', async () => {
+    const res = new BinaryStoreUnreachableError('put', 'k', '530').getResponse();
+    expect(res.status).toBe(503);
+    expect(res.headers.get('retry-after')).toBe('30');
+    expect(((await res.json()) as { error: string }).error).toBe('BYTE_STORE_UNREACHABLE');
+  });
+
+  it('…and a real Hono app DOES answer it, with no onError of its own', async () => {
+    const { Hono } = await import('hono');
+    const app = new Hono().post('/upload', () => {
+      throw new BinaryStoreUnreachableError('put', 'k', '530');
+    });
+    const res = await app.request('/upload', { method: 'POST' });
+    expect(res.status).toBe(503);
+    expect(((await res.json()) as { error: string }).error).toBe('BYTE_STORE_UNREACHABLE');
+  });
+
+  it("the origin's own refusals are unchanged — a 403 is still the plain status error", async () => {
+    reply = () => new Response('', { status: 403 });
+    const error = await makeStore().put('k', new Uint8Array([1])).catch((e: unknown) => e);
+    expect(error).not.toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toBe('[binary-store] put k: 403');
+  });
+});

package/src/server/storage/binaryStore.ts

@@ -725,7 +725,10 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
           headers: mime ? { 'content-type': mime } : undefined,
           body: bytes as unknown as BodyInit,
         },
-      );
+      ).catch((cause: unknown) => {
+        throw new BinaryStoreUnreachableError('put', key, cause instanceof Error ? cause.message : String(cause));
+      });
+      if (storeUnreachableStatus(res.status)) throw new BinaryStoreUnreachableError('put', key, String(res.status));
       if (!res.ok) {
         // A 413 that reaches here despite the threshold above means the edge's
         // real cap is lower than we think, or the caller disabled the
@@ -805,7 +808,12 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
             headers: mime ? { 'content-type': mime } : undefined,
             body: slice,
           },
-        );
+        ).catch((cause: unknown) => {
+          throw new BinaryStoreUnreachableError('putLarge', key, cause instanceof Error ? cause.message : String(cause));
+        });
+        if (storeUnreachableStatus(res.status)) {
+          throw new BinaryStoreUnreachableError('putLarge', key, `chunk ${ci + 1}/${total}: ${res.status}`);
+        }
         if (!res.ok) {
           throw new Error(`[binary-store] putLarge ${key} chunk ${ci + 1}/${total}: ${res.status}`);
         }
@@ -1071,6 +1079,48 @@ export function resolvedMediaTenant(
   return readBinaryStoreEnv(appId, env)?.appId ?? null;
 }
 
+/**
+ * binary-server's origin did not ANSWER a write — as opposed to answering "no".
+ *
+ * binary-server itself never answers 502, 503 or 504; those, and Cloudflare's 52x family (530 is a
+ * tunnel with no connector), are the edge speaking for an origin it could not reach — the owner's
+ * Mac off, asleep, or restarting. A thrown `fetch` is the same fact. Since 2026-09-26 the edge
+ * Worker takes an R2-backed tenant's whole upload itself in that case
+ * (`apps/binary-server/edge-worker/src/upload.ts`), so for desk and family this is what is left
+ * when BOTH halves failed; for a tenant whose bytes rest on the Mac it is simply "the Mac is off".
+ */
+export function storeUnreachableStatus(status: number): boolean {
+  return status === 502 || status === 503 || status === 504 || (status >= 520 && status <= 530);
+}
+
+/**
+ * The write could not reach the store. Carries `getResponse()`, so a Hono app that lets it escape
+ * a route answers a 503 that names the file store — Hono's default error handler returns
+ * `err.getResponse()` for any error that has one — instead of a bare `500 Internal Server Error`.
+ * The message keeps the `[binary-store] <op> <key>:` head every batch caller already prints.
+ */
+export class BinaryStoreUnreachableError extends Error {
+  readonly status = 503;
+  readonly code = 'BYTE_STORE_UNREACHABLE';
+  constructor(op: string, key: string, detail: string) {
+    super(
+      `[binary-store] ${op} ${key}: the file store did not answer (${detail}) — nothing was saved; ` +
+        'everything already stored still opens. Try again when the home server is on.',
+    );
+    this.name = 'BinaryStoreUnreachableError';
+  }
+  getResponse(): Response {
+    return new Response(
+      JSON.stringify({
+        error: this.code,
+        message:
+          'The file store did not answer, so nothing was saved. Everything already stored still opens — try again in a moment.',
+      }),
+      { status: 503, headers: { 'content-type': 'application/json; charset=utf-8', 'retry-after': '30' } },
+    );
+  }
+}
+
 /**
  * The standard env surface every tenant's secrets file carries
  * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):