Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(forge): stop telling users their network failed when our storage rejected the upload

nirholas80d52d28a7fd
diff --git a/api/_lib/r2.js b/api/_lib/r2.js
index e3c369b66..188f7a37e 100644
--- a/api/_lib/r2.js
+++ b/api/_lib/r2.js
@@ -7,6 +7,7 @@ import {
DeleteObjectCommand,
HeadObjectCommand,
CopyObjectCommand,
+ ListObjectsV2Command,
} from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { env } from './env.js';
@@ -92,6 +93,79 @@ export function isStorageInfrastructureError(err) {
return STORAGE_ERROR_RE.test(text);
}
+// Cached liveness of the storage credential, for the one caller shape that
+// cannot recover on its own: an endpoint that hands the BROWSER a presigned URL.
+// objectStorageConfigured() above only proves the vars are present, and a
+// present-but-rejected secret signs a URL that looks perfect and answers 403
+// SignatureDoesNotMatch on use. That 403 carries no CORS header, so the page
+// never sees a status at all: it sees a rejected fetch and reports a network
+// fault, which is how a rotated R2 token read as "Network error during upload"
+// to every /forge user on 2026-09-07 while the endpoint reported 200 OK.
+//
+// The probe is the same signed one-key list the health sensor uses (a rejected
+// credential fails identically for reads and writes, so one read proves both).
+// Results are cached and single-flighted so a six-slot burst costs one probe,
+// and a rejection is re-checked often enough that a fixed credential recovers
+// within seconds without a redeploy.
+const CRED_OK_TTL_MS = 60_000;
+const CRED_FAIL_TTL_MS = 15_000;
+let _credProbe = null;
+let _credProbeInFlight = null;
+
+async function runCredProbe() {
+ const started = Date.now();
+ try {
+ await r2.send(new ListObjectsV2Command({ Bucket: env.S3_BUCKET, MaxKeys: 1 }), {
+ abortSignal: AbortSignal.timeout(3_000),
+ });
+ return { at: started, ok: true, reason: null, message: null };
+ } catch (err) {
+ // Fail CLOSED only on the deterministic class (the credential itself was
+ // rejected): that never fixes itself on retry, and every presigned URL we
+ // hand out until it is fixed is guaranteed to fail in the browser. A
+ // timeout or a dropped socket is transient and may well be the probe's own
+ // bad luck, so fail OPEN there and let the real PUT decide rather than
+ // taking uploads down over one flaky list.
+ const transient = /timeout|aborted|econnreset|socket hang up/i.test(String(err?.message || ''));
+ const rejected = isStorageInfrastructureError(err) && !transient;
+ return {
+ at: started,
+ ok: !rejected,
+ reason: rejected ? 'rejected' : null,
+ message: rejected ? String(err?.message || err).slice(0, 200) : null,
+ };
+ }
+}
+
+/**
+ * @returns {Promise<{ ok: boolean, reason: 'unconfigured'|'rejected'|null, message: string|null }>}
+ */
+export async function objectStorageUsable() {
+ if (!objectStorageConfigured()) {
+ return { ok: false, reason: /** @type {const} */ ('unconfigured'), message: null };
+ }
+ const ttl = _credProbe?.ok ? CRED_OK_TTL_MS : CRED_FAIL_TTL_MS;
+ if (_credProbe && Date.now() - _credProbe.at < ttl) return _credProbe;
+ if (!_credProbeInFlight) {
+ _credProbeInFlight = runCredProbe()
+ .then((result) => {
+ _credProbe = result;
+ return result;
+ })
+ .finally(() => {
+ _credProbeInFlight = null;
+ });
+ }
+ return _credProbeInFlight;
+}
+
+// Drops the cached verdict. Tests use it to probe a fresh state; production
+// never needs it, because both TTLs above expire on their own.
+export function resetObjectStorageUsableCache() {
+ _credProbe = null;
+ _credProbeInFlight = null;
+}
+
// Short-lived signed URL for direct browser upload (PUT).
export async function presignUpload({ key, contentType, checksumSha256 }) {
// Do NOT include ContentLength in the command — that adds content-length to
diff --git a/api/forge-upload.js b/api/forge-upload.js
index 0cd5a4bae..79c3ebae3 100644
--- a/api/forge-upload.js
+++ b/api/forge-upload.js
@@ -11,14 +11,22 @@
*
* Auth-free, matching the rest of /forge: rate-limited by client IP and scoped
* to the anonymous browser handle (x-forge-client) so uploads land under that
- * client's key prefix. When object storage isn't configured the endpoint returns
- * a clean 503 and the page falls back to accepting public image URLs directly.
+ * client's key prefix.
+ *
+ * Because the only thing this endpoint returns is a URL the BROWSER dereferences,
+ * it verifies that storage will accept an upload rather than only that storage is
+ * configured. A signed URL made from a rejected credential is indistinguishable
+ * from a good one until the browser uses it, and the bucket's 403 arrives with no
+ * CORS header, so the page sees a rejected fetch and no status. Both unavailable
+ * cases answer 503: `unconfigured` (this deployment has no bucket, and the page
+ * falls back to accepting public image URLs) and `storage_unavailable` (the
+ * bucket is refusing us, and the user should come back shortly).
*/
import { randomUUID } from 'node:crypto';
import { cors, json, method, readJson, wrap, rateLimited } from './_lib/http.js';
import { limits, clientIp } from './_lib/rate-limit.js';
-import { presignUpload, publicUrl, objectStorageConfigured } from './_lib/r2.js';
+import { presignUpload, publicUrl, objectStorageUsable } from './_lib/r2.js';
import { hashClient } from './_lib/forge-store.js';
// Accepted reference-image types → file extension for the storage key.
@@ -30,17 +38,6 @@ const CONTENT_TYPE_EXT = Object.freeze({
const MAX_IMAGE_BYTES = 8 * 1024 * 1024; // matches forge-store's preview copy cap
-// Upload needs object storage (R2/S3), and the check lives in r2.js so this
-// route cannot drift from it. That module trims before testing: a credential
-// that is only a trailing newline reads truthy through a raw `process.env`
-// test, so an untrimmed copy here would call storage healthy and hand the
-// browser a presigned URL that answers 403 SignatureDoesNotMatch. The 403
-// carries no CORS header, so the page reports "Network error during upload"
-// instead of the designed "paste a URL" fallback below.
-function storageConfigured() {
- return objectStorageConfigured();
-}
-
function clientKeyFrom(req) {
const raw = req.headers['x-forge-client'];
return hashClient(Array.isArray(raw) ? raw[0] : raw);
@@ -50,7 +47,29 @@ export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS' })) return;
if (!method(req, res, ['POST'])) return;
- if (!storageConfigured()) {
+ // Ask whether storage will actually ACCEPT the bytes, not merely whether it
+ // is configured. This endpoint's whole output is a URL the browser uses
+ // itself, so a credential that is present but rejected produces a perfectly
+ // formed 200 here and a 403 SignatureDoesNotMatch there. Cross-origin, that
+ // 403 arrives without a CORS header and the page cannot read its status, so
+ // it surfaces as a bare "Network error during upload" with no way for the
+ // user to tell a broken photo from a broken platform (live on /forge from
+ // 2026-09-07). Answering honestly here is the only place that distinction
+ // still exists. The check is cached in r2.js, so this costs one signed list
+ // per minute, not one per upload.
+ const storage = await objectStorageUsable();
+ if (!storage.ok) {
+ if (storage.reason === 'rejected') {
+ console.error(`[forge-upload] object storage rejected our credential: ${storage.message}`);
+ res.setHeader('retry-after', '60');
+ return json(res, 503, {
+ error: 'storage_unavailable',
+ message:
+ 'Reference image upload is temporarily unavailable while our asset storage recovers. ' +
+ 'Please try again shortly.',
+ retry_after: 60,
+ });
+ }
return json(res, 503, {
error: 'unconfigured',
message:
diff --git a/api/print/upload.js b/api/print/upload.js
index 5d6892997..8cc8c21a8 100644
--- a/api/print/upload.js
+++ b/api/print/upload.js
@@ -16,7 +16,7 @@ import { randomUUID } from 'node:crypto';
import { cors, json, method, rateLimited, readJson, wrap } from '../_lib/http.js';
import { clientIp, limits } from '../_lib/rate-limit.js';
-import { objectStorageConfigured, presignUpload, publicUrl } from '../_lib/r2.js';
+import { objectStorageUsable, presignUpload, publicUrl } from '../_lib/r2.js';
import { hashClient } from '../_lib/forge-store.js';
import { MAX_INPUT_BYTES } from '../_lib/print/mesh-io.js';
@@ -32,7 +32,24 @@ export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS' })) return;
if (!method(req, res, ['POST'])) return;
- if (!objectStorageConfigured()) {
+ // Presence is not acceptance: a present-but-rejected credential signs a URL
+ // the browser cannot use, and the bucket's 403 comes back without a CORS
+ // header, so the page can only report a generic network failure. Ask whether
+ // storage will take the bytes. Cached in r2.js, so this is one signed list a
+ // minute across all callers (see objectStorageUsable).
+ const storage = await objectStorageUsable();
+ if (!storage.ok) {
+ if (storage.reason === 'rejected') {
+ console.error(`[print-upload] object storage rejected our credential: ${storage.message}`);
+ res.setHeader('retry-after', '60');
+ return json(res, 503, {
+ error: 'storage_unavailable',
+ message:
+ 'Model upload is temporarily unavailable while our asset storage recovers. ' +
+ 'Please try again shortly.',
+ retry_after: 60,
+ });
+ }
return json(res, 503, {
error: 'unconfigured',
message:
diff --git a/data/changelog.json b/data/changelog.json
index 34ef9f0bc..49bd6bc92 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-09-08",
+ "title": "Forge tells you when uploads are down, instead of blaming your connection",
+ "summary": "Adding a photo on the Forge could fail with \"Network error during upload\" when nothing was wrong with your network or your photo. Our asset storage had stopped accepting our credential, but the page had no way to know that: the browser is handed a short-lived upload address and sends the image straight to storage, and when storage refuses, the refusal comes back without the header a browser needs in order to show the page what happened. So a platform outage arrived looking exactly like a bad phone signal, and Retry could never fix it. The page now checks that storage will actually accept an upload before handing one out, and says so plainly when it will not, so you can tell \"come back in a few minutes\" apart from \"try a different photo\". The same fix covers the Forge Studio and 3D print upload paths.",
+ "tags": ["fix"],
+ "link": "/forge"
+ },
{
"date": "2026-09-08",
"title": "Robinhood Portfolios can now show you what a basket would have done, and what the rebalancing did to it",
diff --git a/docs/ops/production-log-triage.md b/docs/ops/production-log-triage.md
index 10ba27fb3..e9b4db824 100644
--- a/docs/ops/production-log-triage.md
+++ b/docs/ops/production-log-triage.md
@@ -114,13 +114,17 @@ thing:
hop never touches R2. But `materializeCreation` cannot copy it, so the reply carries
`durable:false`: no R2 copy, no DB creation row, no gallery entry, and the mesh is
only as long-lived as the raw bucket. This is the workaround to give users.
-- **Uploads cannot land**, which is what users actually report. `POST
- /api/forge-upload` presigns fine (200) and the R2 CORS preflight passes, then the
- browser's `PUT` answers `403 SignatureDoesNotMatch` with NO
- `Access-Control-Allow-Origin` on the 403 itself. The browser therefore hides the
- status, `fetch` throws, and `/forge` can only say **"Network error during upload"**
- (`src/forge.js`), never the `Storage rejected the file (403)` branch beside it. Treat
- that phrase in a user report as this outage until proven otherwise.
+- **Uploads cannot land**, which is what users actually report. The R2 CORS preflight
+ passes, then the browser's `PUT` answers `403 SignatureDoesNotMatch` with NO
+ `Access-Control-Allow-Origin` on the 403 itself, so the browser hides the status and
+ `fetch` throws with nothing to read. Until 2026-09-08 `POST /api/forge-upload`
+ presigned fine (200) regardless, so `/forge` could only say **"Network error during
+ upload"** and a user had no way to tell our outage from their own signal. The route
+ now asks `objectStorageUsable()` (`api/_lib/r2.js`) whether the bucket will accept an
+ upload before it mints a URL, and answers `503 storage_unavailable` when it will not,
+ which the page renders as "Uploads are down right now. Try again shortly."
+ `api/print/upload.js` does the same. Treat **either** phrase in a user report as this
+ outage until proven otherwise: the old one means the fix is not deployed yet.
- **Agent registration** cannot store its manifest. **`/cdn/*`** cannot read an object
and answers `502 upstream_error` until the public-bucket fallback (`36b67b8a8`,
`99c521446`, `2ab1cb56a`) is actually deployed; those commits sat on `main` unshipped
diff --git a/src/forge-studio/forge.js b/src/forge-studio/forge.js
index 588fc68a7..a70a08295 100644
--- a/src/forge-studio/forge.js
+++ b/src/forge-studio/forge.js
@@ -1092,31 +1092,53 @@ function handleFiles(startIndex, fileList) {
// Presign → PUT to object storage → public URL. Shared by the view slots and
// the sketch uploader. Returns { ok: true, url } or { ok: false, message }.
async function presignAndPut(file) {
+ // Two legs, two catches on purpose. The presign leg is same-origin, so a
+ // throw there really is the user's connection. The PUT leg is cross-origin to
+ // the bucket, where a rejected credential or a missing CORS rule answers 403
+ // with no Access-Control-Allow-Origin, and the browser hands us a rejected
+ // promise with no status to read. Reporting that as a network fault (one
+ // shared catch, as this had until 2026-09-08) blames the user's phone for our
+ // outage and sends them into an endless Retry loop.
+ let presign;
+ let presignRes;
try {
- const presignRes = await fetch('/api/forge-upload', {
+ presignRes = await fetch('/api/forge-upload', {
method: 'POST',
headers: { 'content-type': 'application/json', ...CLIENT_HEADERS },
body: JSON.stringify({ content_type: file.type, size_bytes: file.size }),
});
- const presign = await presignRes.json().catch(() => ({}));
- if (presignRes.status === 503)
- return { ok: false, message: 'Uploads unavailable — paste a URL.' };
- if (presignRes.status === 429)
- return { ok: false, message: 'Rate limited — retry shortly.' };
- if (!presignRes.ok || !presign.upload_url || !presign.public_url) {
- return { ok: false, message: presign.message || 'Upload failed.' };
- }
+ presign = await presignRes.json().catch(() => ({}));
+ } catch {
+ return { ok: false, message: 'No connection. Check your network.' };
+ }
+
+ if (presignRes.status === 503) {
+ // The server distinguishes "this deployment has no storage" from "our
+ // storage is refusing us right now"; only the second is worth asking the
+ // user to come back for.
+ return {
+ ok: false,
+ message:
+ presign.error === 'storage_unavailable'
+ ? 'Uploads are down right now. Try again shortly.'
+ : 'Uploads unavailable on this deployment.',
+ };
+ }
+ if (presignRes.status === 429) return { ok: false, message: 'Rate limited. Retry shortly.' };
+ if (!presignRes.ok || !presign.upload_url || !presign.public_url) {
+ return { ok: false, message: presign.message || 'Upload failed.' };
+ }
+ try {
const putRes = await fetch(presign.upload_url, {
method: 'PUT',
headers: { 'content-type': file.type },
body: file,
});
- if (!putRes.ok)
- return { ok: false, message: `Storage rejected the file (${putRes.status}).` };
+ if (!putRes.ok) return { ok: false, message: `Storage rejected the file (${putRes.status}).` };
return { ok: true, url: presign.public_url };
} catch {
- return { ok: false, message: 'Network error during upload.' };
+ return { ok: false, message: 'Storage refused the upload. Try again shortly.' };
}
}
diff --git a/src/forge.js b/src/forge.js
index 3aed8238f..e66b4a263 100644
--- a/src/forge.js
+++ b/src/forge.js
@@ -1256,31 +1256,53 @@ function handleFiles(startIndex, fileList) {
// Presign → PUT to object storage → public URL. Shared by the view slots and
// the sketch uploader. Returns { ok: true, url } or { ok: false, message }.
async function presignAndPut(file) {
+ // Two legs, two catches on purpose. The presign leg is same-origin, so a
+ // throw there really is the user's connection. The PUT leg is cross-origin to
+ // the bucket, where a rejected credential or a missing CORS rule answers 403
+ // with no Access-Control-Allow-Origin, and the browser hands us a rejected
+ // promise with no status to read. Reporting that as a network fault (one
+ // shared catch, as this had until 2026-09-08) blames the user's phone for our
+ // outage and sends them into an endless Retry loop.
+ let presign;
+ let presignRes;
try {
- const presignRes = await fetch('/api/forge-upload', {
+ presignRes = await fetch('/api/forge-upload', {
method: 'POST',
headers: { 'content-type': 'application/json', ...CLIENT_HEADERS },
body: JSON.stringify({ content_type: file.type, size_bytes: file.size }),
});
- const presign = await presignRes.json().catch(() => ({}));
- if (presignRes.status === 503)
- return { ok: false, message: 'Uploads unavailable — paste a URL.' };
- if (presignRes.status === 429)
- return { ok: false, message: 'Rate limited — retry shortly.' };
- if (!presignRes.ok || !presign.upload_url || !presign.public_url) {
- return { ok: false, message: presign.message || 'Upload failed.' };
- }
+ presign = await presignRes.json().catch(() => ({}));
+ } catch {
+ return { ok: false, message: 'No connection. Check your network.' };
+ }
+
+ if (presignRes.status === 503) {
+ // The server distinguishes "this deployment has no storage" from "our
+ // storage is refusing us right now"; only the second is worth asking the
+ // user to come back for.
+ return {
+ ok: false,
+ message:
+ presign.error === 'storage_unavailable'
+ ? 'Uploads are down right now. Try again shortly.'
+ : 'Uploads unavailable on this deployment.',
+ };
+ }
+ if (presignRes.status === 429) return { ok: false, message: 'Rate limited. Retry shortly.' };
+ if (!presignRes.ok || !presign.upload_url || !presign.public_url) {
+ return { ok: false, message: presign.message || 'Upload failed.' };
+ }
+ try {
const putRes = await fetch(presign.upload_url, {
method: 'PUT',
headers: { 'content-type': file.type },
body: file,
});
- if (!putRes.ok)
- return { ok: false, message: `Storage rejected the file (${putRes.status}).` };
+ if (!putRes.ok) return { ok: false, message: `Storage rejected the file (${putRes.status}).` };
return { ok: true, url: presign.public_url };
} catch {
- return { ok: false, message: 'Network error during upload.' };
+ return { ok: false, message: 'Storage refused the upload. Try again shortly.' };
}
}
diff --git a/tests/api/forge-pipeline-endpoints.test.js b/tests/api/forge-pipeline-endpoints.test.js
index 146c6470e..3694b6384 100644
--- a/tests/api/forge-pipeline-endpoints.test.js
+++ b/tests/api/forge-pipeline-endpoints.test.js
@@ -113,14 +113,22 @@ vi.mock('../../api/_lib/forge-store.js', () => ({
}));
const presignMock = vi.fn(async ({ key }) => `https://r2.example/${key}?sig=abc`);
-// Storage config is read through r2.js so the route cannot drift from the
-// trimmed check; default configured, flipped per test for the 503 fallback.
-const storageState = { configured: true };
+// Storage readiness is read through r2.js so the route cannot drift from it.
+// Two independent failure modes, because they need different answers: no bucket
+// on this deployment (`unconfigured`), and a bucket that refuses our credential
+// (`rejected`). Default healthy, flipped per test.
+const storageState = { configured: true, rejected: false };
vi.mock('../../api/_lib/r2.js', () => ({
presignUpload: (...a) => presignMock(...a),
publicUrl: (key) => `https://cdn.example/${key}`,
objectStorageConfigured: () => storageState.configured,
+ objectStorageUsable: async () => {
+ if (!storageState.configured) return { ok: false, reason: 'unconfigured', message: null };
+ if (storageState.rejected)
+ return { ok: false, reason: 'rejected', message: 'does not match the signature' };
+ return { ok: true, reason: null, message: null };
+ },
}));
vi.mock('../../api/_lib/auth.js', () => ({
@@ -335,6 +343,29 @@ describe('forge-upload', () => {
}
});
+ // The failure users actually hit on 2026-09-07: every var was present, so the
+ // old presence-only check called storage healthy and returned 200 with a URL
+ // the bucket then rejected. Cross-origin, that 403 has no CORS header, so the
+ // page could only say "Network error during upload" over a photo that was
+ // never at fault. The route must refuse to mint the URL at all.
+ it('503s without minting a URL when the bucket rejects our credential', async () => {
+ storageState.rejected = true;
+ try {
+ const res = await call(upload, {
+ method: 'POST',
+ url: '/api/forge-upload',
+ headers: { 'x-forge-client': 'browser-1' },
+ body: { content_type: 'image/png', size_bytes: 1_000 },
+ });
+ expect(res.statusCode).toBe(503);
+ expect(parse(res).error).toBe('storage_unavailable');
+ expect(res.headers['retry-after']).toBeDefined();
+ expect(presignMock).not.toHaveBeenCalled();
+ } finally {
+ storageState.rejected = false;
+ }
+ });
+
it('rejects a prototype key as a content type', async () => {
for (const contentType of ['constructor', '__proto__', 'tostring']) {
const res = await call(upload, {
diff --git a/tests/object-storage-usable.test.js b/tests/object-storage-usable.test.js
new file mode 100644
index 000000000..6d2b9d575
--- /dev/null
+++ b/tests/object-storage-usable.test.js
@@ -0,0 +1,122 @@
+/**
+ * objectStorageUsable(), unit test.
+ *
+ * On 2026-09-07 the R2 token was rolled and production kept the old secret.
+ * /api/forge-upload answered 200 with a perfectly formed presigned URL for
+ * another day, because it only checked that the credential vars were PRESENT.
+ * The bucket then answered the browser's PUT with 403 SignatureDoesNotMatch,
+ * and that 403 carries no Access-Control-Allow-Origin, so the page could not
+ * read a status and told every user "Network error during upload" over a photo
+ * that was never the problem.
+ *
+ * This pins the gate that now stands in front of every presigned URL we hand a
+ * browser, and the two judgement calls inside it: a rejected credential fails
+ * CLOSED (it never recovers on retry, so every URL minted until a human fixes
+ * it is waste), while a timeout fails OPEN (it may be the probe's own bad luck,
+ * and taking uploads down over one flaky list would be a worse outage than the
+ * one it guards).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const sendMock = vi.fn();
+
+vi.mock('@aws-sdk/client-s3', () => ({
+ S3Client: class {
+ send(...args) {
+ return sendMock(...args);
+ }
+ },
+ PutObjectCommand: class {},
+ GetObjectCommand: class {},
+ DeleteObjectCommand: class {},
+ HeadObjectCommand: class {},
+ CopyObjectCommand: class {},
+ ListObjectsV2Command: class {},
+}));
+vi.mock('@aws-sdk/s3-request-presigner', () => ({
+ getSignedUrl: async () => 'https://signed.example/put',
+}));
+
+const ENV = {
+ S3_ENDPOINT: 'https://acct.r2.cloudflarestorage.com',
+ S3_BUCKET: 'bucket',
+ S3_PUBLIC_DOMAIN: 'https://pub.r2.dev',
+ S3_ACCESS_KEY_ID: 'a'.repeat(32),
+ S3_SECRET_ACCESS_KEY: 'b'.repeat(64),
+};
+
+function signatureError() {
+ const err = new Error(
+ 'The request signature we calculated does not match the signature you provided. Check your secret access key and signing method.',
+ );
+ err.name = 'SignatureDoesNotMatch';
+ return err;
+}
+
+let r2;
+
+beforeEach(async () => {
+ for (const [k, v] of Object.entries(ENV)) vi.stubEnv(k, v);
+ sendMock.mockReset();
+ r2 = await import('../api/_lib/r2.js');
+ r2.resetObjectStorageUsableCache();
+});
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+});
+
+describe('objectStorageUsable', () => {
+ it('reports usable when the bucket answers a signed list', async () => {
+ sendMock.mockResolvedValue({ KeyCount: 0 });
+ const v = await r2.objectStorageUsable();
+ expect(v.ok).toBe(true);
+ expect(v.reason).toBe(null);
+ });
+
+ it('reports the credential rejected, so no presigned URL is minted from it', async () => {
+ sendMock.mockRejectedValue(signatureError());
+ const v = await r2.objectStorageUsable();
+ expect(v.ok).toBe(false);
+ expect(v.reason).toBe('rejected');
+ expect(v.message).toMatch(/does not match the signature/i);
+ });
+
+ it('stays usable through a transient timeout rather than taking uploads down', async () => {
+ const err = new Error('socket hang up');
+ err.name = 'TimeoutError';
+ sendMock.mockRejectedValue(err);
+ const v = await r2.objectStorageUsable();
+ expect(v.ok).toBe(true);
+ });
+
+ it('reports unconfigured without touching the network', async () => {
+ vi.stubEnv('S3_SECRET_ACCESS_KEY', '');
+ const v = await r2.objectStorageUsable();
+ expect(v).toEqual({ ok: false, reason: 'unconfigured', message: null });
+ expect(sendMock).not.toHaveBeenCalled();
+ });
+
+ it('treats a secret that is only whitespace as unconfigured, not as a rejection', async () => {
+ vi.stubEnv('S3_SECRET_ACCESS_KEY', '\n');
+ const v = await r2.objectStorageUsable();
+ expect(v.reason).toBe('unconfigured');
+ });
+
+ it('costs one probe for a burst of concurrent uploads, not one each', async () => {
+ sendMock.mockResolvedValue({ KeyCount: 0 });
+ const results = await Promise.all(
+ Array.from({ length: 6 }, () => r2.objectStorageUsable()),
+ );
+ expect(results.every((r) => r.ok)).toBe(true);
+ expect(sendMock).toHaveBeenCalledTimes(1);
+ });
+
+ it('caches the verdict, so a second upload does not re-probe', async () => {
+ sendMock.mockResolvedValue({ KeyCount: 0 });
+ await r2.objectStorageUsable();
+ await r2.objectStorageUsable();
+ expect(sendMock).toHaveBeenCalledTimes(1);
+ });
+});