Support single byte ranges for static assets

Preserve conditional range handling and storage response headers.

Co-authored-by: Claude Haiku 5.5 <noreply@anthropic.com>
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: billf

src/client/index.test.ts

@@ -85,6 +85,56 @@ describe("registerStaticRoutes", () => {
     expect(await response.text()).toBe("<h1>Hello</h1>");
   });
 
+  test("does not advertise Accept-Ranges when storage ignores Range", async () => {
+    const handler = staticHandler();
+    const runQuery = vi.fn().mockResolvedValue({
+      storageUrl: "https://storage.example/ep.mp3",
+      contentType: "audio/mpeg",
+      etag: '"storage-id"',
+    });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(new Response("0123456789")),
+    );
+
+    const response = await invokeHandler(
+      handler,
+      runQuery,
+      new Request("https://app.convex.site/ep.mp3", {
+        headers: { Range: "bytes=2-4" },
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("Accept-Ranges")).toBeNull();
+  });
+
+  test("ignores Range when If-Range does not match the current ETag", async () => {
+    const handler = staticHandler();
+    const runQuery = vi.fn().mockResolvedValue({
+      storageUrl: "https://storage.example/ep.mp3",
+      contentType: "audio/mpeg",
+      etag: '"storage-id"',
+    });
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(new Response("0123456789", { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const response = await invokeHandler(
+      handler,
+      runQuery,
+      new Request("https://app.convex.site/ep.mp3", {
+        headers: { Range: "bytes=2-4", "If-Range": '"old-storage-id"' },
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe("0123456789");
+    const init = fetchMock.mock.calls[0]?.[1] as RequestInit | undefined;
+    expect(new Headers(init?.headers).get("Range")).toBeNull();
+  });
+
   test("serves an inherited v1 asset from the app's storage during migration", async () => {
     const handler = staticHandler();
     const runQuery = vi.fn().mockResolvedValue({
@@ -302,3 +352,141 @@ describe("exposeDeploymentQuery", () => {
     });
   });
 });
+
+describe("storage-URL Range passthrough", () => {
+  const storedFile = {
+    storageUrl: "https://storage.example/ep.mp3",
+    contentType: "audio/mpeg",
+    etag: '"storage-id"',
+  };
+
+  test("passes a storage 206 through with its Content-Range and Accept-Ranges", async () => {
+    const handler = staticHandler();
+    const runQuery = vi.fn().mockResolvedValue(storedFile);
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response("234", {
+        status: 206,
+        headers: { "Content-Range": "bytes 2-4/10", "Accept-Ranges": "bytes" },
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const response = await invokeHandler(
+      handler,
+      runQuery,
+      new Request("https://app.convex.site/ep.mp3", {
+        headers: { Range: "bytes=2-4" },
+      }),
+    );
+
+    expect(response.status).toBe(206);
+    expect(response.headers.get("Content-Range")).toBe("bytes 2-4/10");
+    expect(response.headers.get("Accept-Ranges")).toBe("bytes");
+    expect(await response.text()).toBe("234");
+    const init = fetchMock.mock.calls[0]?.[1] as RequestInit | undefined;
+    expect(new Headers(init?.headers).get("Range")).toBe("bytes=2-4");
+  });
+
+  test("passes a storage 416 through with its Content-Range", async () => {
+    const handler = staticHandler();
+    const runQuery = vi.fn().mockResolvedValue(storedFile);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(null, {
+          status: 416,
+          headers: { "Content-Range": "bytes */10" },
+        }),
+      ),
+    );
+
+    const response = await invokeHandler(
+      handler,
+      runQuery,
+      new Request("https://app.convex.site/ep.mp3", {
+        headers: { Range: "bytes=50-" },
+      }),
+    );
+
+    expect(response.status).toBe(416);
+    expect(response.headers.get("Content-Range")).toBe("bytes */10");
+    expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff");
+    expect(response.headers.get("Cache-Control")).toBe("no-store");
+    expect(response.headers.get("ETag")).toBe('"storage-id"');
+  });
+
+  test("forwards Range when If-Range matches the current ETag", async () => {
+    const handler = staticHandler();
+    const runQuery = vi.fn().mockResolvedValue(storedFile);
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response("234", {
+        status: 206,
+        headers: { "Content-Range": "bytes 2-4/10" },
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const response = await invokeHandler(
+      handler,
+      runQuery,
+      new Request("https://app.convex.site/ep.mp3", {
+        headers: { Range: "bytes=2-4", "If-Range": '"storage-id"' },
+      }),
+    );
+
+    expect(response.status).toBe(206);
+    const init = fetchMock.mock.calls[0]?.[1] as RequestInit | undefined;
+    expect(new Headers(init?.headers).get("Range")).toBe("bytes=2-4");
+  });
+});
+
+describe("storage Accept-Ranges advertisement", () => {
+  test("does not advertise bytes when storage answers Accept-Ranges: none", async () => {
+    const handler = staticHandler();
+    const runQuery = vi.fn().mockResolvedValue({
+      storageUrl: "https://storage.example/ep.mp3",
+      contentType: "audio/mpeg",
+      etag: '"storage-id"',
+    });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response("0123456789", { headers: { "Accept-Ranges": "none" } }),
+      ),
+    );
+
+    const response = await invokeHandler(
+      handler,
+      runQuery,
+      new Request("https://app.convex.site/ep.mp3"),
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("Accept-Ranges")).toBeNull();
+  });
+});
+
+describe("storage passthrough with multi-range headers", () => {
+  test("a multi-range header is not forwarded to storage", async () => {
+    const handler = staticHandler();
+    const runQuery = vi.fn().mockResolvedValue({
+      storageUrl: "https://storage.example/ep.mp3",
+      contentType: "audio/mpeg",
+      etag: '"storage-id"',
+    });
+    const fetchMock = vi.fn().mockResolvedValue(new Response("0123456789"));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const response = await invokeHandler(
+      handler,
+      runQuery,
+      new Request("https://app.convex.site/ep.mp3", {
+        headers: { Range: "bytes=0-1,3-4" },
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    const init = fetchMock.mock.calls[0]?.[1] as RequestInit | undefined;
+    expect(new Headers(init?.headers).get("Range")).toBeNull();
+  });
+});

src/client/index.ts

@@ -10,9 +10,13 @@ import {
   decodeRequestPath,
   etagMatches,
   getSetupHtml,
-  resolveContentType,
   isHtmlContentType,
 } from "../component/serving.js";
+import {
+  blobResponse,
+  ifRangeMatches,
+  resolveContentType,
+} from "../mime/mime.js";
 
 const deploymentInfoValidator = v.object({
   _id: v.string(),
@@ -160,15 +164,17 @@ export function registerStaticRoutes(
           headers: { "Content-Type": "text/plain" },
         });
       }
-      return new Response(blob, {
-        status: 200,
-        headers: {
+      return blobResponse(
+        blob,
+        {
           "Content-Type": contentType,
           "Cache-Control": cacheControl,
           ...(asset.etag ? { ETag: asset.etag } : {}),
           "X-Content-Type-Options": "nosniff",
         },
-      });
+        request.headers.get("Range"),
+        request.headers.get("If-Range"),
+      );
     }
 
     if (!asset.storageUrl) {
@@ -188,21 +194,58 @@ export function registerStaticRoutes(
       });
     }
 
-    const storageResponse = await fetch(asset.storageUrl);
+    // Forward Range so audio/video can seek; the storage response's 206 and
+    // range headers are passed through below. A stale If-Range drops Range so
+    // storage returns the full representation.
+    // Only a single byte range is forwarded. A multi-range header is ignored here,
+    // as the local parser does, so storage never frames a multipart body under the asset type.
+    const requestedRange = request.headers.get("Range");
+    const rangeHeader =
+      ifRangeMatches(request.headers.get("If-Range"), asset.etag) &&
+      requestedRange !== null &&
+      !requestedRange.includes(",")
+        ? requestedRange
+        : null;
+    const storageResponse = await fetch(
+      asset.storageUrl,
+      rangeHeader ? { headers: { Range: rangeHeader } } : undefined,
+    );
+    if (storageResponse.status === 416) {
+      const contentRange = storageResponse.headers.get("Content-Range");
+      return new Response(null, {
+        status: 416,
+        headers: {
+          "Cache-Control": "no-store",
+          "X-Content-Type-Options": "nosniff",
+          ...(asset.etag ? { ETag: asset.etag } : {}),
+          ...(contentRange ? { "Content-Range": contentRange } : {}),
+        },
+      });
+    }
     if (!storageResponse.ok || !storageResponse.body) {
       return new Response("Storage error", {
         status: 500,
         headers: { "Content-Type": "text/plain" },
       });
     }
 
+    const contentRange = storageResponse.headers.get("Content-Range");
+    // Advertise bytes only when storage actually lists it, so "none" does not count.
+    const storageAcceptsBytes = (storageResponse.headers.get("Accept-Ranges") ?? "")
+      .split(",")
+      .map((unit) => unit.trim().toLowerCase())
+      .includes("bytes");
+    const storageSupportsRanges =
+      storageResponse.status === 206 || storageAcceptsBytes;
     return new Response(storageResponse.body, {
-      status: 200,
+      status: storageResponse.status === 206 ? 206 : 200,
       headers: {
         "Content-Type": contentType,
         "Cache-Control": cacheControl,
         ...(asset.etag ? { ETag: asset.etag } : {}),
         "X-Content-Type-Options": "nosniff",
+        ...(storageSupportsRanges ? { "Accept-Ranges": "bytes" } : {}),
+        ...(contentRange ? { "Content-Range": contentRange } : {}),
       },
     });
   });