@sproutboat/runtime 0.44.0 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sproutboat/runtime
 
+## 0.45.0
+
+### Minor Changes
+
+- 2b6d912: R2 large objects on the embedded transport (sproutd #99 and #100). `get()` reads an object as asked: a `range` reads only its window from the object's file, and `body` is a stream of 256 KiB reads, so an object of any size can be returned with `new Response(object.body)`; `text()`, `json()`, `arrayBuffer()` and `blob()` still read the whole window. A streamed response now has flow control on a host that offers it (sproutd): the pump reads no more of its source while a window of its bytes is unacknowledged, and a response with a declared `content-length` is sent with it. A worker whose host forwards `/__sb/r2/transfer/BUCKET/TOKEN` (sproutd) serves the ticket itself, with the standalone server's statuses and headers: uploads and downloads move a window at a time between the connection and the object's file. A standalone executable answers a HEAD request with the length the app declared.
+
 ## 0.44.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/runtime",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/native-fetch-prelude.js

@@ -11024,28 +11024,63 @@ function __sbR2StrictObject(meta, bytes, range, include) {
   };
   if (bytes == null) return obj;
   let used = false;
+  // A lazy body (bytes.lazy: the object's file, read as asked) is never read whole unless text(), json(),
+  // arrayBuffer() or blob() ask for all of it; its stream reads one chunk at a time.
+  const lazy = bytes.lazy === true;
   const take = () => {
     if (used) throw new TypeError("Body has already been used. It can only be used once. Use tee() first if you need to read it twice.");
     used = true;
-    return bytes;
+    return lazy ? __sbR2ReadAll(bytes, range) : bytes;
   };
   // The stream is made when first asked for: text() and friends read the bytes directly,
   // so an object read as text never holds a second copy (sproutd #22).
   let stream = null;
   Object.defineProperty(obj, "body", {
     get: () => {
-      if (stream === null) stream = new Response(__sbBufFrom(bytes)).body;
+      if (stream === null) stream = lazy ? __sbR2LazyStream(bytes, range) : new Response(__sbBufFrom(bytes)).body;
       return stream;
     },
     enumerable: true,
   });
   Object.defineProperty(obj, "bodyUsed", { get: () => used, enumerable: true });
-  obj.text = async () => __sbFromUtf8(take());
-  obj.json = async () => JSON.parse(__sbFromUtf8(take()));
-  obj.arrayBuffer = async () => __sbBufFrom(take());
-  obj.blob = async () => new Blob([__sbBufFrom(take())], { type: obj.httpMetadata.contentType || "" });
+  // A lazy body reads into a Uint8Array (never a bytestring), so each of these takes bytes, not text.
+  obj.text = async () => (lazy ? new TextDecoder().decode(take()) : __sbFromUtf8(take()));
+  obj.json = async () => JSON.parse(lazy ? new TextDecoder().decode(take()) : __sbFromUtf8(take()));
+  obj.arrayBuffer = async () => (lazy ? take().buffer : __sbBufFrom(take()));
+  obj.blob = async () => new Blob([lazy ? take().buffer : __sbBufFrom(take())], { type: obj.httpMetadata.contentType || "" });
   return obj;
 }
+// The chunk a streamed R2 body reads at a time (a Uint8Array of this size, then collected): a chunk is
+// what the worker's heap holds per read, and what the response's flow control hands to the host.
+const __SB_R2_CHUNK = 256 * 1024;
+// The bytes of a lazy body's window, all of them: text(), json(), arrayBuffer() and blob() need the whole
+// object in memory whatever they are called on.
+function __sbR2ReadAll(src, range) {
+  const out = new Uint8Array(range.length);
+  if (range.length > 0 && __sbR2ReadRange(src.bucket, src.key, src.blobId, range.offset, out) !== range.length)
+    throw new Error("sproutboat r2.get: the object could not be read");
+  return out;
+}
+// A lazy body's window as a ReadableStream of __SB_R2_CHUNK-byte reads.
+function __sbR2LazyStream(src, range) {
+  let at = 0;
+  return new ReadableStream({
+    pull(controller) {
+      if (at >= range.length) {
+        controller.close();
+        return;
+      }
+      const n = Math.min(__SB_R2_CHUNK, range.length - at);
+      const chunk = new Uint8Array(n);
+      if (__sbR2ReadRange(src.bucket, src.key, src.blobId, range.offset + at, chunk) !== n) {
+        controller.error(new Error("sproutboat r2.get: the object could not be read"));
+        return;
+      }
+      at += n;
+      controller.enqueue(chunk);
+    },
+  });
+}
 // A hex string's bytes, one char per byte.
 function __sbR2Bytes(hex) {
   let out = "";
@@ -11092,7 +11127,19 @@ function __sbMakeR2(name) {
     get(key, options) {
       return attempt(() => {
         const o = options || {};
-        const r = __sbR2Get(name, __sbR2Key(key, "get"));
+        const objectKey = __sbR2Key(key, "get");
+        // Where the transport can read an object's file as asked (embedded: sproutd and standalone), get() takes its
+        // metadata and no bytes: a range reads only its own window, a body streams. The broker answers null here
+        // and returns the object whole, as before.
+        const opened = __sbR2Open(name, objectKey);
+        if (opened !== null) {
+          if (!opened.found) return null;
+          const meta = opened.object;
+          if (!__sbR2OnlyIf(o.onlyIf, meta.md5 || meta.etag, meta.uploaded)) return __sbR2StrictObject(meta, null, { offset: 0, length: meta.size });
+          const window = o.range == null ? { offset: 0, length: meta.size } : __sbR2Range(o.range, meta.size);
+          return __sbR2StrictObject(meta, { lazy: true, bucket: name, key: objectKey, blobId: opened.blobId }, window);
+        }
+        const r = __sbR2Get(name, objectKey);
         if (!r.found) return null;
         const meta = r.object;
         if (!__sbR2OnlyIf(o.onlyIf, meta.md5 || meta.etag, meta.uploaded)) return __sbR2StrictObject(meta, null, { offset: 0, length: meta.size });
@@ -14090,7 +14137,8 @@ function __sbHasStreamBody(res) {
 // x-sb-stream header, the native writer sends the status and headers and holds the
 // connection open, and each chunk is written as it arrives. Hosts that do not stream
 // (sproutd's workers, for now) link the weak fallbacks, report unsupported and keep buffering.
-// op: "s" supported, "o" open, "w" write data, "e" end. Returns a short string.
+// op: "s" supported, "o" open, "w" write data (a bytestring), "W" write the Uint8Array in data, "p" the bytes written
+// the client's connection has not taken yet, "k" park the timer in data until that falls, "e" end. Returns a short string.
 // oxlint-disable-next-line no-unused-vars -- read inside the RawC block, not by JS.
 function __sbStreamOp(op, id, data) {
   let out = "";
@@ -14100,6 +14148,11 @@ function __sbStreamOp(op, id, data) {
     extern unsigned int sb_stream_open(void);
     extern int sb_stream_write(unsigned int, const char*, size_t);
     extern void sb_stream_end(unsigned int);
+    // Flow control (sproutd): the bytes written and not yet taken by the client's connection, and a timer the
+    // host fires when that falls. A host without them (a standalone executable, whose server buffers by itself)
+    // reports none, so a stream is never held back there.
+    extern size_t sb_stream_pending(unsigned int) __attribute__((weak));
+    extern void sb_stream_wait(unsigned int, unsigned int) __attribute__((weak));
     const char* __o; size_t __ol; char* __oo = 0;
     porf_native_fetch_read_value(op, &__o, &__ol, &__oo);
     char __op = __ol ? __o[0] : 0;
@@ -14119,7 +14172,17 @@ function __sbStreamOp(op, id, data) {
         int __w = -1;
         if (porf_native_fetch_read_raw_bytes(data, &__d, &__dl) == 0) __w = sb_stream_write(__id, __d, __dl);
         snprintf(__r, sizeof(__r), "%d", __w);
-      } else if (__op == 'e') { sb_stream_end(__id); snprintf(__r, sizeof(__r), "0"); }
+      } else if (__op == 'W' && data.type == 81) {
+        // A Uint8Array written as it is, with no bytestring copy of it.
+        const u32 __ta = (u32)data.val;
+        const int32_t __len = *(int32_t*)(MEM + __ta);
+        const u32 __at = *(u32*)(MEM + __ta + 4) + 4;
+        int __w = -1;
+        if (__len >= 0) __w = sb_stream_write(__id, (const char*)(MEM + __at), (size_t)__len);
+        snprintf(__r, sizeof(__r), "%d", __w);
+      } else if (__op == 'p') snprintf(__r, sizeof(__r), "%zu", sb_stream_pending ? sb_stream_pending(__id) : (size_t)0);
+      else if (__op == 'k') { if (sb_stream_wait && data.type == 1 && data.val > 0) sb_stream_wait(__id, (unsigned int)data.val); }
+      else if (__op == 'e') { sb_stream_end(__id); snprintf(__r, sizeof(__r), "0"); }
     }
     out = porf_box((f64)porf_native_fetch_alloc_bytestring(__r, strlen(__r)), 195);
   `;
@@ -14130,6 +14193,16 @@ function __sbStreamingSupported() {
   if (__sbStreaming < 0) __sbStreaming = __sbStreamOp("s", "0", "") === "1" ? 1 : 0;
   return __sbStreaming === 1;
 }
+// What the client's connection may hold of a stream before the pump waits for it (the host credits bytes as
+// they leave): a client slower than the app is waited for, not buffered for or cut off.
+const __SB_STREAM_WINDOW = 1024 * 1024;
+// Resolves when the host says the stream's unsent bytes fell (or the client went away).
+function __sbStreamDrained(id) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, 2147483647);
+    __sbStreamOp("k", id, timer);
+  });
+}
 function __sbStreamResponse(response) {
   const stream = __sbRawBody(response);
   const id = __sbStreamOp("o", "0", "");
@@ -14148,10 +14221,22 @@ function __sbStreamResponse(response) {
         else if (value instanceof ArrayBuffer) bytes = new Uint8Array(value);
         else if (ArrayBuffer.isView(value)) bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
         else throw new TypeError("This ReadableStream did not return bytes.");
-        if (bytes.length > 0 && __sbStreamOp("w", id, __sbToBytes(bytes)) !== "0") {
-          // The client went away: stop the source.
-          reader.cancel();
-          break;
+        if (bytes.length > 0) {
+          // A whole Uint8Array goes to the host without a copy; a view of part of a buffer is copied.
+          const wrote =
+            bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+              ? __sbStreamOp("W", id, bytes)
+              : __sbStreamOp("w", id, __sbToBytes(bytes));
+          if (wrote !== "0") {
+            // The client went away: stop the source.
+            reader.cancel();
+            break;
+          }
+          // Flow control: while the connection holds more than the window, read no more of the source.
+          while (Number(__sbStreamOp("p", id, "")) > __SB_STREAM_WINDOW) {
+            await __sbStreamDrained(id);
+            // Woken by the client going away: the next write says so (-1).
+          }
         }
       }
     } catch (error) {
@@ -15891,7 +15976,164 @@ function __sbTrustedProxiesOnce() {
   return __sbTrustedCache;
 }
 
+// R2 transfer tickets (createUploadUrl, createDownloadUrl): /__sb/r2/transfer/BUCKET/TOKEN, scoped to one object and
+// good once. A standalone executable's native server answers them before JavaScript runs (patchR2Transfer, #195);
+// on a host that forwards every path to the worker (sproutd) the worker answers them here with the same statuses
+// and headers, before the app's fetch() sees the request. The body goes straight between the connection and the
+// object's file, one step at a time (__sbR2XferOp): at most a window of it is ever in the worker.
+const __SB_R2_TRANSFER = "/__sb/r2/transfer/";
+// Set by the embedded transport (it has the ticket contexts and their steps); the broker's own listener owns the path.
+// oxlint-disable-next-line no-unassigned-vars -- set by the embedded transport, above
+var __sbR2TransferOn; // no initializer: the embedded transport (above) sets it, and an initializer here would run after it
+// [bucket, token] when the request is for a ticket (the same shape the native server accepts), else null.
+function __sbR2TransferTarget(request) {
+  const method = request.method;
+  if (method !== "GET" && method !== "PUT" && method !== "HEAD" && method !== "POST" && method !== "DELETE") return null;
+  const url = request.url;
+  const at = url.indexOf(__SB_R2_TRANSFER);
+  if (at < 0) return null;
+  const hostEnd = url.indexOf("/", url.indexOf("//") + 2);
+  if (at !== hostEnd) return null;
+  let rest = url.slice(at + __SB_R2_TRANSFER.length);
+  const cut = rest.search(/[?#]/);
+  if (cut >= 0) rest = rest.slice(0, cut);
+  const slash = rest.indexOf("/");
+  if (slash <= 0 || slash > 255 || rest.indexOf("/", slash + 1) >= 0) return null;
+  const bucket = rest.slice(0, slash);
+  const token = rest.slice(slash + 1);
+  if (token.length !== 24 || !/^[0-9a-f]+$/.test(token) || !/^[A-Za-z0-9_]+$/.test(bucket)) return null;
+  return [bucket, token];
+}
+function __sbR2TransferError(status, text) {
+  return new Response(text, { status, headers: { "content-type": "text/plain" } });
+}
+// A transfer status as a response (the native server's table: anything else is a 500).
+function __sbR2TransferFailed(status, text) {
+  const known = status === 404 || status === 410 || status === 413 || status === 422 || status === 503 || status === 507;
+  return __sbR2TransferError(known ? status : 500, text);
+}
+// Resolves when the streamed request body `body` has more (or ended or failed): the host fires the parked timer.
+function __sbR2BodyWait(body) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, 2147483647);
+    __sbReqBodyOp("w", body, timer);
+  });
+}
+async function __sbR2TransferUpload(request, bucket, token, body) {
+  let declared = 0;
+  const length = request.headers.get("content-length");
+  if (length !== null && length !== "") {
+    if (!/^[0-9]+$/.test(length) || length.length > 15) return __sbR2TransferError(400, "invalid content-length");
+    declared = Number(length);
+  }
+  const opened = __sbR2XferOp("u", bucket, token, declared).split(" ");
+  if (opened[0] !== "0") return __sbR2TransferFailed(Number(opened[0]), "R2 transfer unavailable");
+  const handle = opened[1];
+  let status = 0;
+  if (body === 0) {
+    // The host delivered the body whole (or there is none): one write.
+    const raw = __sbRawBody(request);
+    if (raw != null && raw !== "") status = Number(__sbR2XferOp("b", handle, raw, 0));
+  } else {
+    for (;;) {
+      const step = __sbR2XferOp("s", handle, "", body).split(" ");
+      const kind = step[0];
+      if (kind === "d") continue;
+      if (kind === "w") {
+        await __sbR2BodyWait(body);
+        continue;
+      }
+      if (kind === "e") break;
+      // 'f': the client went away; 's': a status refused the bytes (the ticket is released with it).
+      status = kind === "s" ? Number(step[1]) : 500;
+      if (kind === "f") __sbR2XferOp("x", "0", "", Number(handle));
+      __sbReqBodyOp("c", body, "");
+      return kind === "f" ? __sbR2TransferError(500, "R2 transfer failed") : __sbR2TransferFailed(status, "R2 transfer failed");
+    }
+    __sbReqBodyOp("c", body, "");
+  }
+  if (status !== 0) return __sbR2TransferFailed(status, "R2 transfer failed");
+  const finished = Number(__sbR2XferOp("f", handle, "", 0));
+  if (finished === 201) return new Response(null, { status: 201 });
+  return __sbR2TransferFailed(finished, "R2 transfer failed");
+}
+function __sbR2TransferDownload(request, bucket, token) {
+  const opened = __sbR2XferOp("d", bucket, token, 0).split(" ");
+  if (opened[0] !== "0") return __sbR2TransferFailed(Number(opened[0]), "R2 transfer unavailable");
+  const handle = Number(opened[1]);
+  const size = Number(opened[2]);
+  const etag = opened[3];
+  const close = () => __sbR2XferOp("c", "0", "", handle);
+  const match = request.headers.get("if-none-match");
+  if (match === "*" || match === etag || match === '"' + etag + '"') {
+    close();
+    return new Response(null, { status: 304, headers: { etag } });
+  }
+  let first = 0;
+  let last = size ? size - 1 : 0;
+  let partial = false;
+  const range = request.headers.get("range");
+  if (range) {
+    const refuse = (why) => {
+      close();
+      return __sbR2TransferError(416, why);
+    };
+    if (range.slice(0, 6) !== "bytes=") return refuse("invalid range");
+    const spec = range.slice(6);
+    const dash = spec.indexOf("-");
+    if (dash <= 0) return refuse("invalid range");
+    const from = spec.slice(0, dash);
+    const to = spec.slice(dash + 1);
+    if (!/^[0-9]+$/.test(from) || (to !== "" && !/^[0-9]+$/.test(to))) return refuse("invalid range");
+    first = Number(from);
+    if (to !== "") last = Number(to);
+    if (first >= size || last < first) return refuse("range outside object");
+    if (last >= size) last = size - 1;
+    partial = true;
+  }
+  const total = size === 0 ? 0 : last - first + 1;
+  const headers = { "content-type": "application/octet-stream", etag, "accept-ranges": "bytes", "content-length": String(total) };
+  if (partial) headers["content-range"] = "bytes " + first + "-" + last + "/" + size;
+  let sent = 0;
+  const stream = new ReadableStream({
+    pull(controller) {
+      if (sent >= total) {
+        close();
+        controller.close();
+        return;
+      }
+      const chunk = new Uint8Array(Math.min(__SB_R2_CHUNK, total - sent));
+      const got = Number(__sbR2XferOp("r", String(handle), "", first + sent, chunk));
+      if (got !== chunk.length) {
+        close();
+        controller.error(new Error("R2 transfer failed"));
+        return;
+      }
+      sent += got;
+      controller.enqueue(chunk);
+    },
+    cancel() {
+      close();
+    },
+  });
+  return new Response(stream, { status: partial ? 206 : 200, headers });
+}
+// The response for a ticket request, or a Promise of it.
+function __sbR2Transfer(request, target) {
+  // The streamed body's id, taken now: a ticket request never reaches __sbDecodeIngress.
+  const body = __sbReqBodyTake();
+  const method = request.method;
+  if (method === "GET") return __sbR2TransferDownload(request, target[0], target[1]);
+  if (method !== "PUT") return __sbR2TransferError(405, "R2 transfer requires GET or PUT");
+  return __sbR2TransferUpload(request, target[0], target[1], body);
+}
+
 globalThis.__sbEntry = function (handlers, request) {
+  if (__sbR2TransferOn) {
+    const ticket = __sbR2TransferTarget(request);
+    // Through the same finish as the app's answer (promise, then a stream body is sent as it is read).
+    if (ticket !== null) return __sbFetchWithDrain(__sbR2Transfer(request, ticket), [], false, false, true, null, null);
+  }
   __sbDecodeIngress(request);
   const trigger = __sbHeader(request.headers, "x-sb-trigger");
   if (!trigger) {

package/src/r2-lazy.test.js

@@ -0,0 +1,101 @@
+// R2 get() reads an object as asked (sproutd #99): a range reads only its window, a body streams one chunk at
+// a time, and nothing reads the whole object unless text(), json(), arrayBuffer() or blob() ask for all of it.
+// The prelude is text, so this lifts the strict R2 object block out and runs it against a fake file whose reads
+// are recorded, as r2-object.test.js does for the legacy object.
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const src = readFileSync(fileURLToPath(new URL("./native-fetch-prelude.js", import.meta.url)), "utf8");
+const start = src.indexOf("function __sbR2Key(");
+const end = src.indexOf("function __sbMakeR2(");
+const isStrStart = src.indexOf("function __sbIsStr(");
+const isStrEnd = src.indexOf("function __sbIsFn(");
+const bytesStart = src.indexOf("const __SB_BYTES_WINDOW");
+const utf8Start = src.indexOf("function __sbBufFrom(");
+const utf8End = src.indexOf("function __sbRawBodyResponse(");
+const lazyStart = src.indexOf("const __SB_R2_CHUNK");
+if (
+  [start, end, isStrStart, isStrEnd, bytesStart, utf8Start, utf8End, lazyStart].some((i) => i === -1) ||
+  end < start ||
+  lazyStart < start ||
+  lazyStart > end
+)
+  throw new Error("the strict R2 object block moved in the prelude");
+
+// oxlint-disable-next-line no-function-constructor -- lifting pure blocks out of the text-only prelude for test
+const load = new Function(
+  "__sbR2ReadRange",
+  `function __sbFromUtf8Native() { return ""; }\nfunction __sbToBytesNative() { return ""; }\nfunction __sbFillBytes() { return false; }\n${src.slice(isStrStart, isStrEnd)}\n${src.slice(bytesStart, utf8Start)}\n${src.slice(utf8Start, utf8End)}\n${src.slice(start, end)}\nreturn { __sbR2StrictObject, __SB_R2_CHUNK };`,
+);
+
+// An "object file" of SIZE bytes, byte i being i % 251, and the reads asked of it.
+const reads = [];
+const file = (size) => (_bucket, _key, _blob, offset, view) => {
+  reads.push({ offset, length: view.length });
+  const n = Math.max(0, Math.min(view.length, size - offset));
+  for (let i = 0; i < n; i++) view[i] = (offset + i) % 251;
+  return n;
+};
+const meta = (size) => ({ key: "big.bin", size, etag: "abc123", uploaded: "2026-09-14T00:00:00.000Z" });
+const lazy = { lazy: true, bucket: "B", key: "big.bin", blobId: "abc123" };
+const drain = async (stream) => {
+  const reader = stream.getReader();
+  const chunks = [];
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) return chunks;
+    chunks.push(value);
+  }
+};
+
+test("a body streams in chunks and never reads the object whole", async () => {
+  const { __sbR2StrictObject, __SB_R2_CHUNK } = load(file(3 * 1024 * 1024 + 100));
+  reads.length = 0;
+  const obj = __sbR2StrictObject(meta(3 * 1024 * 1024 + 100), lazy, { offset: 0, length: 3 * 1024 * 1024 + 100 });
+  expect(reads.length).toBe(0);
+  const chunks = await drain(obj.body);
+  expect(chunks.length).toBe(Math.ceil((3 * 1024 * 1024 + 100) / __SB_R2_CHUNK));
+  expect(Math.max(...reads.map((r) => r.length))).toBe(__SB_R2_CHUNK);
+  expect(reads.map((r) => r.offset)).toEqual(chunks.map((_, i) => i * __SB_R2_CHUNK));
+  expect(chunks[0][250]).toBe(250);
+  expect(chunks[1][0]).toBe(__SB_R2_CHUNK % 251);
+});
+
+test("a range reads only its window", async () => {
+  const { __sbR2StrictObject } = load(file(10 * 1024 * 1024));
+  reads.length = 0;
+  const range = { offset: 5 * 1024 * 1024 + 7, length: 1000 };
+  const obj = __sbR2StrictObject(meta(10 * 1024 * 1024), lazy, range);
+  const chunks = await drain(obj.body);
+  expect(chunks.length).toBe(1);
+  expect(reads).toEqual([{ offset: range.offset, length: 1000 }]);
+  expect(chunks[0].length).toBe(1000);
+  expect(chunks[0][0]).toBe(range.offset % 251);
+});
+
+test("arrayBuffer() and text() read the window in one read", async () => {
+  const { __sbR2StrictObject } = load(file(600));
+  reads.length = 0;
+  const range = { offset: 100, length: 400 };
+  const obj = __sbR2StrictObject(meta(600), lazy, range);
+  const buffer = await obj.arrayBuffer();
+  expect(buffer.byteLength).toBe(400);
+  expect(new Uint8Array(buffer)[0]).toBe(100);
+  expect(reads).toEqual([{ offset: 100, length: 400 }]);
+  await expect(obj.text()).rejects.toThrow(/already been used/);
+});
+
+test("an empty window closes at once without reading", async () => {
+  const { __sbR2StrictObject } = load(file(0));
+  reads.length = 0;
+  const obj = __sbR2StrictObject(meta(0), lazy, { offset: 0, length: 0 });
+  expect((await drain(obj.body)).length).toBe(0);
+  expect(reads.length).toBe(0);
+});
+
+test("a read that cannot be completed errors the stream", async () => {
+  const { __sbR2StrictObject } = load(() => -1);
+  const obj = __sbR2StrictObject(meta(100), lazy, { offset: 0, length: 100 });
+  await expect(drain(obj.body)).rejects.toThrow(/could not be read/);
+});

package/src/transport-broker.js

@@ -1400,6 +1400,19 @@ globalThis.__sbR2Get = function (bucket, key) {
   return { found: true, object: reply.object, body: __sbTakeBin() };
 };
 
+// The broker returns an object whole (r2.get); only the embedded transport reads a file as asked.
+globalThis.__sbR2Open = function () {
+  return null;
+};
+globalThis.__sbR2ReadRange = function () {
+  return -1;
+};
+
+// The broker's own transfer listener owns /__sb/r2/transfer/: this runtime serves none of it.
+function __sbR2XferOp() {
+  return "404";
+}
+
 globalThis.__sbR2MultipartPut = function (bucket, key, uploadId, partNumber, body) {
   const token = __sbEnv("SB_BROKER_TOKEN");
   const reply = JSON.parse(

package/src/transport-embedded.js

@@ -1879,6 +1879,22 @@ static u32 sb_r2_get_c(const char* path, const char* bucket, const char* key, co
   return out;
 }
 
+// Reads at most CAP bytes at OFFSET of an object's file into OUT, and nothing else of it: a range read
+// (R2 get with a range) and each chunk of a streamed body come through here, so an object of any size is
+// never in memory whole. Returns the byte count (short at the end of the object), or -1 when the file
+// cannot be read. The file is named by the object's generation, which a put never rewrites.
+static long sb_r2_read_into_c(const char* path, const char* bucket, const char* key, const char* generation, size_t offset, char* out, size_t cap) {
+  char blobpath[1024];
+  sb_r2_blob_path(blobpath, sizeof(blobpath), path, bucket, key, generation);
+  FILE* f = fopen(blobpath, "rb");
+  if (!f) return -1;
+  if (offset && fseek(f, (long)offset, SEEK_SET) != 0) { fclose(f); return -1; }
+  size_t rd = cap ? fread(out, 1, cap, f) : 0;
+  int bad = ferror(f);
+  fclose(f);
+  return bad ? -1 : (long)rd;
+}
+
 // Best-effort: a metadata row deleted with no blob file (or vice versa) is
 // still a correct end state, so a missing file here is not an error.
 static void sb_r2_delete_blob(const char* path, const char* bucket, const char* key, const char* generation) {
@@ -2119,6 +2135,95 @@ size_t sb_r2_transfer_download_read(sb_r2_transfer_ctx* ctx, size_t offset, char
 }
 void sb_r2_transfer_download_close(sb_r2_transfer_ctx* ctx) { if (ctx) { if (ctx->file) fclose(ctx->file); free(ctx); } }
 
+// A host whose workers serve transfer tickets themselves (sproutd: the frontend forwards /__sb/r2/transfer/...
+// like any request, with its body streamed) drives the same context from JavaScript, one step at a time.
+// The contexts live here, in a small table (a handle is its index plus one), so JavaScript never holds a
+// pointer; a handle is released by finishing, aborting or closing it. An upload step moves what the request
+// body has buffered (at most 1 MiB, in 64 KiB pieces from the stack) into the object's temporary file, and a
+// download read fills a Uint8Array from the object's file: object bytes are never strings or JSON.
+#define SB_XFER_MAX 16
+static sb_r2_transfer_ctx* sb_xfer[SB_XFER_MAX];
+static int sb_xfer_hold(sb_r2_transfer_ctx* ctx) {
+  for (int i = 0; i < SB_XFER_MAX; i++) if (!sb_xfer[i]) { sb_xfer[i] = ctx; return i + 1; }
+  return 0;
+}
+static sb_r2_transfer_ctx* sb_xfer_get(int handle) {
+  return handle >= 1 && handle <= SB_XFER_MAX ? sb_xfer[handle - 1] : 0;
+}
+extern long long sb_reqbody_poll(unsigned int);
+extern size_t sb_reqbody_take(unsigned int, char*, size_t);
+// Claims an upload ticket: the HTTP status (0: claimed, HANDLE set).
+static int sb_xfer_upload_open(const char* bucket, const char* token, size_t declared, int* handle) {
+  sb_r2_transfer_ctx* ctx = 0;
+  *handle = 0;
+  int status = sb_r2_transfer_open(bucket, token, declared, &ctx);
+  if (status != 0 || !ctx) return status ? status : 500;
+  *handle = sb_xfer_hold(ctx);
+  if (!*handle) { sb_r2_transfer_abort(ctx); return 503; }
+  return 0;
+}
+// One step of an upload from request body BODY: 'd' some bytes moved (*arg), 'w' none yet (wait for the
+// body's timer), 'e' the body ended (finish), 'f' the body failed (the client went away, abort), 's' a
+// status refused them (*arg; the ticket is released). A step stops after 1 MiB so other requests run.
+static char sb_xfer_upload_step(int handle, unsigned int body, long* arg) {
+  sb_r2_transfer_ctx* ctx = sb_xfer_get(handle);
+  *arg = 0;
+  if (!ctx) { *arg = 500; return 's'; }
+  char piece[65536];
+  long moved = 0;
+  while (moved < (1 << 20)) {
+    long long ready = sb_reqbody_poll(body);
+    if (ready == -1) { *arg = moved; return moved ? 'd' : 'e'; }
+    if (ready == -2) { *arg = moved; return moved ? 'd' : 'f'; }
+    if (ready == 0) { *arg = moved; return moved ? 'd' : 'w'; }
+    size_t n = sb_reqbody_take(body, piece, sizeof(piece));
+    if (!n) { *arg = moved; return moved ? 'd' : 'w'; }
+    int status = sb_r2_transfer_write(ctx, piece, n);
+    if (status != 0) { sb_r2_transfer_abort(ctx); sb_xfer[handle - 1] = 0; *arg = status; return 's'; }
+    moved += (long)n;
+  }
+  *arg = moved;
+  return 'd';
+}
+// A body that arrived whole (a request of a host that buffers it): written in one go.
+static int sb_xfer_upload_write(int handle, const char* bytes, size_t length) {
+  sb_r2_transfer_ctx* ctx = sb_xfer_get(handle);
+  if (!ctx) return 500;
+  int status = sb_r2_transfer_write(ctx, bytes, length);
+  if (status != 0) { sb_r2_transfer_abort(ctx); sb_xfer[handle - 1] = 0; }
+  return status;
+}
+static int sb_xfer_finish(int handle) {
+  sb_r2_transfer_ctx* ctx = sb_xfer_get(handle);
+  if (!ctx) return 500;
+  sb_xfer[handle - 1] = 0;
+  return sb_r2_transfer_finish(ctx);
+}
+static void sb_xfer_close(int handle) {
+  sb_r2_transfer_ctx* ctx = sb_xfer_get(handle);
+  if (!ctx) return;
+  sb_xfer[handle - 1] = 0;
+  sb_r2_transfer_abort(ctx);
+}
+// Claims a download ticket: the HTTP status (0: claimed, HANDLE, *size and *etag set).
+static int sb_xfer_download_open(const char* bucket, const char* token, int* handle, size_t* size, char* etag, size_t etag_cap) {
+  sb_r2_transfer_ctx* ctx = 0;
+  *handle = 0;
+  int status = sb_r2_transfer_download_open(bucket, token, &ctx);
+  if (status != 0 || !ctx) return status ? status : 500;
+  *handle = sb_xfer_hold(ctx);
+  if (!*handle) { sb_r2_transfer_download_close(ctx); return 503; }
+  *size = sb_r2_transfer_download_size(ctx);
+  snprintf(etag, etag_cap, "%s", sb_r2_transfer_download_etag(ctx));
+  return 0;
+}
+static void sb_xfer_download_close(int handle) {
+  sb_r2_transfer_ctx* ctx = sb_xfer_get(handle);
+  if (!ctx) return;
+  sb_xfer[handle - 1] = 0;
+  sb_r2_transfer_download_close(ctx);
+}
+
 // LTX capture (#141) failed after SQLite committed: the write is in the database but not in
 // the replication log, and the database refuses writes until the process restarts. Said as
 // such (SQLITE_IOERR), never as SQLite's own message, which still reads "not an error".
@@ -4342,6 +4447,112 @@ function __sbR2GetRaw(path, bucket, key, blobId) {
   return res;
 }
 
+// R2 get without the whole object: fills VIEW (a fresh Uint8Array) with the bytes at OFFSET of the object's
+// file. Returns how many it read (fewer at the end of the object), or -1 when the file cannot be read.
+// oxlint-disable-next-line no-unused-vars -- read inside the RawC block below, not by JS.
+function __sbR2ReadInto(path, bucket, key, blobId, offset, view) {
+  let got = -1;
+  // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
+  Porffor.c`
+    const char* __p; size_t __pl; char* __po = 0;
+    porf_native_fetch_read_value(path, &__p, &__pl, &__po);
+    char* __path = (char*)malloc(__pl + 1); memcpy(__path, __p, __pl); __path[__pl] = 0;
+    if (__po) free(__po);
+
+    const char* __bk; size_t __bkl; char* __bko = 0;
+    porf_native_fetch_read_value(bucket, &__bk, &__bkl, &__bko);
+    char* __bucket = (char*)malloc(__bkl + 1); memcpy(__bucket, __bk, __bkl); __bucket[__bkl] = 0;
+    if (__bko) free(__bko);
+
+    const char* __k; size_t __kl; char* __ko = 0;
+    porf_native_fetch_read_value(key, &__k, &__kl, &__ko);
+    char* __key = (char*)malloc(__kl + 1); memcpy(__key, __k, __kl); __key[__kl] = 0;
+    if (__ko) free(__ko);
+
+    const char* __g; size_t __gl; char* __go = 0;
+    porf_native_fetch_read_value(blobId, &__g, &__gl, &__go);
+    char* __generation = (char*)malloc(__gl + 1); memcpy(__generation, __g, __gl); __generation[__gl] = 0;
+    if (__go) free(__go);
+
+    long __n = -1;
+    if (view.type == 81 && offset.type == 1 && offset.val >= 0) {
+      const u32 __ta = (u32)view.val;
+      const int32_t __len = *(int32_t*)(MEM + __ta);
+      const u32 __at = *(u32*)(MEM + __ta + 4) + 4;
+      if (__len >= 0) __n = sb_r2_read_into_c(__path, __bucket, __key, __generation, (size_t)offset.val, (char*)(MEM + __at), (size_t)__len);
+    }
+    free(__path); free(__bucket); free(__key); free(__generation);
+    got = (f64)__n;
+  `;
+  return got;
+}
+
+// Transfer tickets served by the worker (see sb_xfer_* above). op: "u" claim an upload ticket (a = bucket, b = token,
+// n = the declared length; "0 HANDLE" or "STATUS"), "s" a step of the upload from body id n ("d BYTES", "w", "e", "f"
+// or "s STATUS"), "b" write the bytestring in a (a buffered body; the status), "f" finish ("STATUS"), "x" release the
+// handle in n, "d" claim a download ticket ("0 HANDLE SIZE ETAG" or "STATUS"), "r" read the object's file at offset n
+// into the Uint8Array in view (handle in a; the count), "c" release a download handle. Returns a short string.
+// oxlint-disable-next-line no-unused-vars -- read inside the RawC block below, not by JS.
+function __sbR2XferOp(op, a, b, n, view) {
+  let out = "";
+  // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
+  Porffor.c`
+    const char* __o; size_t __ol; char* __oo = 0;
+    porf_native_fetch_read_value(op, &__o, &__ol, &__oo);
+    char __op = __ol ? __o[0] : 0;
+    if (__oo) free(__oo);
+
+    const char* __a; size_t __al; char* __ao = 0;
+    porf_native_fetch_read_value(a, &__a, &__al, &__ao);
+    char* __as = (char*)malloc(__al + 1); memcpy(__as, __a, __al); __as[__al] = 0;
+    if (__ao) free(__ao);
+    const char* __b; size_t __bl; char* __bo = 0;
+    porf_native_fetch_read_value(b, &__b, &__bl, &__bo);
+    char* __bs = (char*)malloc(__bl + 1); memcpy(__bs, __b, __bl); __bs[__bl] = 0;
+    if (__bo) free(__bo);
+
+    const double __n = n.type == 1 ? n.val : 0;
+    const int __handle = (int)strtol(__as, 0, 10);
+    char __r[160]; __r[0] = 0;
+    if (__op == 'u') {
+      int __h = 0;
+      int __s = sb_xfer_upload_open(__as, __bs, (size_t)__n, &__h);
+      if (__s == 0) snprintf(__r, sizeof(__r), "0 %d", __h); else snprintf(__r, sizeof(__r), "%d", __s);
+    } else if (__op == 's') {
+      long __moved = 0;
+      char __k = sb_xfer_upload_step(__handle, (unsigned int)__n, &__moved);
+      snprintf(__r, sizeof(__r), "%c %ld", __k, __moved);
+    } else if (__op == 'b') {
+      const char* __d = 0; size_t __dl = 0;
+      int __s = 500;
+      if (porf_native_fetch_read_raw_bytes(b, &__d, &__dl) == 0) __s = sb_xfer_upload_write(__handle, __d, __dl);
+      snprintf(__r, sizeof(__r), "%d", __s);
+    } else if (__op == 'f') snprintf(__r, sizeof(__r), "%d", sb_xfer_finish(__handle));
+    else if (__op == 'x') sb_xfer_close((int)__n);
+    else if (__op == 'd') {
+      int __h = 0; size_t __size = 0; char __etag[80]; __etag[0] = 0;
+      int __s = sb_xfer_download_open(__as, __bs, &__h, &__size, __etag, sizeof(__etag));
+      if (__s == 0) snprintf(__r, sizeof(__r), "0 %d %zu %s", __h, __size, __etag); else snprintf(__r, sizeof(__r), "%d", __s);
+    } else if (__op == 'r') {
+      long __got = -1;
+      sb_r2_transfer_ctx* __ctx = sb_xfer_get(__handle);
+      if (__ctx && view.type == 81) {
+        const u32 __ta = (u32)view.val;
+        const int32_t __len = *(int32_t*)(MEM + __ta);
+        const u32 __at = *(u32*)(MEM + __ta + 4) + 4;
+        if (__len >= 0) __got = (long)sb_r2_transfer_download_read(__ctx, (size_t)__n, (char*)(MEM + __at), (size_t)__len);
+      }
+      snprintf(__r, sizeof(__r), "%ld", __got);
+    } else if (__op == 'c') sb_xfer_download_close((int)__n);
+    free(__as); free(__bs);
+    out = porf_box((f64)porf_native_fetch_alloc_bytestring(__r, strlen(__r)), 195);
+  `;
+  return out;
+}
+// This transport's workers serve transfer tickets themselves, on a host that forwards the path (sproutd); a
+// standalone executable's native server answers them before JavaScript runs, and never gets here.
+__sbR2TransferOn = true;
+
 // R2 delete: also removes the object's own file, not just the metadata row
 // (#56 — sb_r2_delete_blob is best-effort, a missing file is not an error).
 // oxlint-disable-next-line no-unused-vars -- read inside the RawC block below, not by JS.
@@ -5955,6 +6166,19 @@ globalThis.__sbR2Get = function (bucket, key) {
   };
 };
 
+// The object's metadata and where its bytes are, without the bytes: get() reads them as the caller asks for them
+// (range windows and a body stream), through __sbR2ReadRange.
+globalThis.__sbR2Open = function (bucket, key) {
+  const meta = __sbEmbeddedDispatch({ op: "r2.head", bucket, key });
+  if (!meta.found) return { found: false };
+  return { found: true, object: meta.object, blobId: String(meta.blobId || "") };
+};
+
+// Fills the Uint8Array VIEW with the object's bytes from OFFSET; the count read, or -1.
+globalThis.__sbR2ReadRange = function (bucket, key, blobId, offset, view) {
+  return __sbR2ReadInto(__sbStore(), String(bucket), String(key), String(blobId), offset, view);
+};
+
 globalThis.__sbR2MultipartPut = function (bucket, key, uploadId, partNumber, body) {
   __sbQuotaCheck("R2 uploadPart()");
   __sbEnsureSchema();