@sproutboat/toolchain 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @sproutboat/toolchain
 
+## 0.4.6
+
+### Patch Changes
+
+- a357b91: Compile direct R2 transfer support only into artifacts that declare an R2 binding.
+
+## 0.4.5
+
+### Patch Changes
+
+- 5ee065c: Stream standalone direct R2 byte ranges safely and support ETag conditionals.
+
 ## 0.4.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/toolchain",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "license": "MIT",
   "type": "module",
   "repository": {

package/src/acquire.test.ts

@@ -28,7 +28,9 @@ async function fixture(): Promise<{ archive: string; sha256: string }> {
       "  }\n" +
       "  return -1;\n" +
       "}\n",
-    "compiler/index.js": "          '-xc', '-', '-c',\n          uSocketsArchive,\n          '-lm'\n",
+    "compiler/index.js":
+      "          '-xc', '-', '-c',\n          uSocketsArchive,\n          '-lm'\n" +
+      "          '-I', `${uwsDir}/uSockets/src`,\n",
     "compiler/uwebsockets.js":
       "static const size_t REQUEST_BODY_MAX_BYTES = 1024u * 1024u;\n" +
       "int porf_native_fetch_read_value(struct jsval value, const char** out_buf, size_t* out_len, char** out_owned);\n" +

package/src/patch.test.ts

@@ -2,7 +2,8 @@ import { expect, test } from "bun:test";
 import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { patchRenderJs, patchUwebsockets } from "./patch";
+import { EMPTY_BINDINGS, wrapNativeFetchHandler } from "../../runtime/src/wrap";
+import { patchCompilerArgs, patchRenderJs, patchUwebsockets } from "./patch";
 
 // The parts of Porffor's compiler/render.js the patch anchors to.
 const RENDER = `void porf_native_fetch_runtime_init(void) {
@@ -36,6 +37,16 @@ int porf_native_fetch_read_value(jsval value, const char** out_buf, size_t* out_
 }
 `;
 
+const COMPILER_INDEX = `const compileArgs = [
+          '-xc', '-', '-c',
+];
+const linkArgs = [
+          '-I', \`${"${uwsDir}"}/uSockets/src\`,
+          uSocketsArchive,
+          '-lm'
+];
+`;
+
 // Porffor's compiler/uwebsockets.js, trimmed to the parts the patch touches:
 // body limit (#56), the #156 status-line switch, #163's collect_headers, and
 // #176's read_value forward decl / is_forbidden_response_header /
@@ -171,6 +182,8 @@ test("#156: status-line fallback synthesizes a line for unlisted codes, idempote
     expect(once).toContain("try_handle_r2_transfer(res, req, method)");
     expect(once).toContain("sb_r2_transfer_download_open");
     expect(once).toContain("sb_r2_transfer_download_v1");
+    expect(once).toContain("sb_r2_transfer_range_v1");
+    expect(once).toContain("sb_r2_transfer_conditional_v1");
 
     // #163: collect_headers takes res, drops a client-sent x-sb-remote-addr, and
     // appends the real peer; the call site passes res through.
@@ -228,6 +241,86 @@ test("a drifted shim fails loudly instead of silently no-op'ing", async () => {
   }
 });
 
+test("native capability flags reach both the generated C and socket-shim C++ compiles", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sb-patch-compiler-"));
+  try {
+    await mkdir(join(root, "compiler"), { recursive: true });
+    await writeFile(join(root, "compiler/index.js"), COMPILER_INDEX);
+    await patchCompilerArgs(root);
+    const once = await readFile(join(root, "compiler/index.js"), "utf8");
+    expect(once.match(/SB_EXTRA_CFLAGS/g)).toHaveLength(4);
+    expect(once).toContain("SB_UWS_EXTRA_CFLAGS");
+    await patchCompilerArgs(root);
+    expect(await readFile(join(root, "compiler/index.js"), "utf8")).toBe(once);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("R2 builds define every direct transfer symbol the gated socket shim calls", async () => {
+  const root = await shimDir();
+  try {
+    await patchUwebsockets(root);
+    const shim = await readFile(join(root, "compiler/uwebsockets.js"), "utf8");
+    const abi = shim.match(/extern "C" \{([\s\S]*?)\n\}/)?.[1];
+    if (abi === undefined) throw new Error("patched shim did not contain the R2 transfer ABI");
+    const required = [...abi.matchAll(/\b(sb_r2_transfer_[a-z_]+)\s*\(/g)].map((match) => match[1]);
+    const wrapped = wrapNativeFetchHandler(
+      "export default { fetch() { return new Response('ok'); } }",
+      "",
+      {},
+      { ...EMPTY_BINDINGS, r2: ["OBJECTS"] },
+      8080,
+      "2026-08-26",
+      "test",
+      undefined,
+      "broker",
+    );
+
+    for (const symbol of new Set(required)) {
+      expect(wrapped).toMatch(new RegExp(`\\b${symbol}\\s*\\([^)]*\\)\\s*\\{`));
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("the direct R2 socket path is excluded unless the compiler enables it", async () => {
+  const root = await shimDir();
+  try {
+    await patchUwebsockets(root);
+    const shim = await readFile(join(root, "compiler/uwebsockets.js"), "utf8");
+    expect(shim).toContain("#ifdef SB_R2_TRANSFER");
+    expect(shim).toContain("#endif\n  __porffor_js_enter();");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("an existing compiler cache upgrades to the gated R2 socket path", async () => {
+  const root = await shimDir();
+  try {
+    await patchUwebsockets(root);
+    const file = join(root, "compiler/uwebsockets.js");
+    const current = await readFile(file, "utf8");
+    const legacy = current
+      .replace('#ifdef SB_R2_TRANSFER\nextern "C" {', 'extern "C" {')
+      .replace("\n#endif\nstatic void on_request", "\nstatic void on_request")
+      .replace(
+        "#ifdef SB_R2_TRANSFER\n  if (try_handle_r2_transfer(res, req, method)) return;\n#endif\n",
+        "  if (try_handle_r2_transfer(res, req, method)) return;\n",
+      );
+    await writeFile(file, legacy);
+
+    await patchUwebsockets(root);
+    const upgraded = await readFile(file, "utf8");
+    expect(upgraded).toContain('#ifdef SB_R2_TRANSFER\nextern "C" {');
+    expect(upgraded).toContain("#endif\n  __porffor_js_enter();");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test("#165: render.js routes console output to stderr, unbuffered, idempotently", async () => {
   const root = await mkdtemp(join(tmpdir(), "sb-patch-render-"));
   try {

package/src/patch.ts

@@ -167,6 +167,14 @@ const CFLAGS_INJECT =
   "          ...(process.env.SB_EXTRA_CFLAGS ? process.env.SB_EXTRA_CFLAGS.split(' ').filter(Boolean) : []),\n";
 const CFLAGS_MARKER = "SB_EXTRA_CFLAGS";
 
+/** The native-fetch socket shim is a separately compiled C++ translation unit.
+ * It needs the same optional capability flags as the generated C object. */
+const UWS_CFLAGS_ANCHOR = "          '-I', `${uwsDir}/uSockets/src`,\n";
+const UWS_CFLAGS_INJECT =
+  "          // SB_UWS_EXTRA_CFLAGS\n" +
+  "          ...(process.env.SB_EXTRA_CFLAGS ? process.env.SB_EXTRA_CFLAGS.split(' ').filter(Boolean) : []),\n";
+const UWS_CFLAGS_MARKER = "SB_UWS_EXTRA_CFLAGS";
+
 /**
  * #56 — make the inbound request-body limit configurable.
  *
@@ -416,8 +424,10 @@ const WRITE_RESPONSE_MARKER = "porf_native_fetch_read_raw_bytes(body_value";
 // #195: reserve a direct-transfer ticket before native-fetch allocates the
 // ordinary in-memory PendingRequest. uWS then gives each wire chunk directly
 // to the runtime C ABI, which owns the temporary object file.
-const R2_TRANSFER_ANCHOR = "static void on_request(uWS::HttpResponse<false>* res, uWS::HttpRequest* req) {\n";
-const R2_TRANSFER_INJECT = `extern "C" {
+const R2_TRANSFER_ANCHOR =
+  "static void on_request(uWS::HttpResponse<false>* res, uWS::HttpRequest* req) {\n";
+const R2_TRANSFER_INJECT = `#ifdef SB_R2_TRANSFER
+extern "C" {
   struct sb_r2_transfer_ctx;
   int sb_r2_transfer_open(const char*, const char*, size_t, sb_r2_transfer_ctx**);
   int sb_r2_transfer_write(sb_r2_transfer_ctx*, const char*, size_t);
@@ -425,6 +435,7 @@ const R2_TRANSFER_INJECT = `extern "C" {
   void sb_r2_transfer_abort(sb_r2_transfer_ctx*);
   int sb_r2_transfer_download_open(const char*, const char*, sb_r2_transfer_ctx**);
   size_t sb_r2_transfer_download_size(sb_r2_transfer_ctx*);
+  const char* sb_r2_transfer_download_etag(sb_r2_transfer_ctx*);
   size_t sb_r2_transfer_download_read(sb_r2_transfer_ctx*, size_t, char*, size_t);
   void sb_r2_transfer_download_close(sb_r2_transfer_ctx*);
 }
@@ -452,22 +463,58 @@ static bool try_handle_r2_transfer(uWS::HttpResponse<false>* res, uWS::HttpReque
   std::string bucket, token;
   if (!sb_r2_transfer_path(req->getUrl(), &bucket, &token)) return false;
   // sb_r2_transfer_download_v1
+  // sb_r2_transfer_range_v1
+  // sb_r2_transfer_range_header_v2
+  // sb_r2_transfer_conditional_v1
+  // sb_r2_transfer_streaming_v2
   if (method == "GET") {
     sb_r2_transfer_ctx* download = nullptr;
     const int open_status = sb_r2_transfer_download_open(bucket.c_str(), token.c_str(), &download);
     if (open_status != 0 || !download) { respond_with_error(res, sb_r2_transfer_status(open_status), "R2 transfer unavailable", true); return true; }
-    struct Download { sb_r2_transfer_ctx* ctx; uintmax_t size; bool closed = false; };
-    auto state = std::make_shared<Download>(Download{download, sb_r2_transfer_download_size(download)});
+    const std::string etag = sb_r2_transfer_download_etag(download);
+    const std::string_view if_none_match = req->getHeader("if-none-match");
+    if (if_none_match == "*" || if_none_match == etag || (if_none_match.size() == etag.size() + 2 && if_none_match.front() == '"' && if_none_match.back() == '"' && if_none_match.substr(1, etag.size()) == etag)) {
+      sb_r2_transfer_download_close(download); res->writeStatus("304 Not Modified"); res->writeHeader("ETag", etag); res->end(); return true;
+    }
+    const uintmax_t full_size = sb_r2_transfer_download_size(download);
+    uintmax_t first = 0, last = full_size ? full_size - 1 : 0;
+    std::string_view range = req->getHeader("range"); if (range.empty()) range = req->getHeader("Range");
+    if (!range.empty()) {
+      if (range.substr(0, 6) != "bytes=") { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; }
+      const std::string_view spec = range.substr(6); const size_t dash = spec.find('-');
+      if (dash == std::string_view::npos || dash == 0) { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; }
+      first = 0; for (char c : spec.substr(0, dash)) { if (c < '0' || c > '9') { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; } first = first * 10 + (c - '0'); }
+      if (dash + 1 < spec.size()) { last = 0; for (char c : spec.substr(dash + 1)) { if (c < '0' || c > '9') { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; } last = last * 10 + (c - '0'); } }
+      if (first >= full_size || last < first) { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "range outside object", true); return true; }
+      if (last >= full_size) last = full_size - 1;
+      char content_range[96]; snprintf(content_range, sizeof(content_range), "bytes %llu-%llu/%llu", (unsigned long long)first, (unsigned long long)last, (unsigned long long)full_size);
+      res->writeStatus("206 Partial Content"); res->writeHeader("Content-Range", content_range);
+    }
+    res->writeHeader("ETag", etag); res->writeHeader("Accept-Ranges", "bytes");
+    struct Download { sb_r2_transfer_ctx* ctx; uintmax_t base; uintmax_t size; uintmax_t sent = 0; bool closed = false; char chunk[65536]; };
+    auto state = std::make_shared<Download>(Download{download, first, last - first + 1});
     auto pump = std::make_shared<std::function<bool()>>();
     *pump = [res, state, pump]() {
       if (state->closed) return false;
-      const uintmax_t offset = res->getWriteOffset();
-      char chunk[65536];
-      const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)offset, chunk, sizeof(chunk));
-      const auto result = res->tryEnd(std::string_view(chunk, bytes), state->size);
-      if (result.second) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
-      if (!result.first) res->onWritable([pump](uintmax_t) { return (*pump)(); });
-      return false;
+      for (;;) {
+        const size_t want = state->size - state->sent < sizeof(state->chunk) ? (size_t)(state->size - state->sent) : sizeof(state->chunk);
+        const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)(state->base + state->sent), state->chunk, want);
+        const auto result = res->tryEnd(std::string_view(state->chunk, bytes), state->size);
+        if (result.second || bytes == 0) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
+        if (!result.first) {
+          res->onWritable([res, state](uintmax_t offset) {
+            if (state->closed) return true;
+            const size_t want = state->size - offset < sizeof(state->chunk) ? (size_t)(state->size - offset) : sizeof(state->chunk);
+            const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)(state->base + offset), state->chunk, want);
+            const auto resumed = res->tryEnd(std::string_view(state->chunk, bytes), state->size);
+            if (resumed.second || bytes == 0) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return true; }
+            return resumed.first;
+          });
+          return false;
+        }
+        state->sent += bytes;
+        if (state->sent == state->size) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
+      }
     };
     res->writeHeader("Content-Type", "application/octet-stream");
     res->onAborted([state]() { if (!state->closed) { sb_r2_transfer_download_close(state->ctx); state->closed = true; } });
@@ -496,37 +543,84 @@ static bool try_handle_r2_transfer(uWS::HttpResponse<false>* res, uWS::HttpReque
   return true;
 }
 static void on_request(uWS::HttpResponse<false>* res, uWS::HttpRequest* req) {
+#endif
 `;
 const R2_TRANSFER_MARKER = "sb_r2_transfer_path(std::string_view path";
-const R2_TRANSFER_CALL_ANCHOR = "  __porffor_js_enter();\n  const i32 url_ptr = alloc_request_url(req);";
+const R2_TRANSFER_CALL_ANCHOR =
+  "  __porffor_js_enter();\n  const i32 url_ptr = alloc_request_url(req);";
 const R2_TRANSFER_CALL_INJECT =
-  "  if (try_handle_r2_transfer(res, req, method)) return;\n" + R2_TRANSFER_CALL_ANCHOR;
+  "#ifdef SB_R2_TRANSFER\n  if (try_handle_r2_transfer(res, req, method)) return;\n#endif\n" +
+  R2_TRANSFER_CALL_ANCHOR;
 const R2_TRANSFER_CALL_MARKER = "try_handle_r2_transfer(res, req, method)";
+const R2_GATE_MARKER = "#ifdef SB_R2_TRANSFER";
 const R2_DOWNLOAD_CACHE_MARKER = "sb_r2_transfer_download_v1";
+const R2_RANGE_CACHE_MARKER = "sb_r2_transfer_range_v1";
+const R2_CONDITIONAL_CACHE_MARKER = "sb_r2_transfer_conditional_v1";
+const R2_STREAMING_CACHE_MARKER = "sb_r2_transfer_streaming_v2";
+const R2_RANGE_HEADER_CACHE_MARKER = "sb_r2_transfer_range_header_v2";
 const R2_DOWNLOAD_DECL_ANCHOR = "  void sb_r2_transfer_abort(sb_r2_transfer_ctx*);\n}";
 const R2_DOWNLOAD_DECL_INJECT =
   "  void sb_r2_transfer_abort(sb_r2_transfer_ctx*);\n" +
   "  int sb_r2_transfer_download_open(const char*, const char*, sb_r2_transfer_ctx**);\n" +
   "  size_t sb_r2_transfer_download_size(sb_r2_transfer_ctx*);\n" +
+  "  const char* sb_r2_transfer_download_etag(sb_r2_transfer_ctx*);\n" +
   "  size_t sb_r2_transfer_download_read(sb_r2_transfer_ctx*, size_t, char*, size_t);\n" +
   "  void sb_r2_transfer_download_close(sb_r2_transfer_ctx*);\n}";
-const R2_DOWNLOAD_BRANCH_ANCHOR = '  if (method != "PUT") { respond_with_error(res, "405 Method Not Allowed", "R2 transfer requires PUT", true); return true; }';
+const R2_DOWNLOAD_BRANCH_ANCHOR =
+  '  if (method != "PUT") { respond_with_error(res, "405 Method Not Allowed", "R2 transfer requires PUT", true); return true; }';
 const R2_DOWNLOAD_BRANCH_INJECT = `  // sb_r2_transfer_download_v1
+  // sb_r2_transfer_range_v1
+  // sb_r2_transfer_range_header_v2
+  // sb_r2_transfer_conditional_v1
+  // sb_r2_transfer_streaming_v2
   if (method == "GET") {
     sb_r2_transfer_ctx* download = nullptr;
     const int status = sb_r2_transfer_download_open(bucket.c_str(), token.c_str(), &download);
     if (status != 0 || !download) { respond_with_error(res, sb_r2_transfer_status(status), "R2 transfer unavailable", true); return true; }
-    struct Download { sb_r2_transfer_ctx* ctx; uintmax_t size; bool closed = false; };
-    auto state = std::make_shared<Download>(Download{download, sb_r2_transfer_download_size(download)});
+    const std::string etag = sb_r2_transfer_download_etag(download);
+    const std::string_view if_none_match = req->getHeader("if-none-match");
+    if (if_none_match == "*" || if_none_match == etag || (if_none_match.size() == etag.size() + 2 && if_none_match.front() == '"' && if_none_match.back() == '"' && if_none_match.substr(1, etag.size()) == etag)) {
+      sb_r2_transfer_download_close(download); res->writeStatus("304 Not Modified"); res->writeHeader("ETag", etag); res->end(); return true;
+    }
+    const uintmax_t full_size = sb_r2_transfer_download_size(download);
+    uintmax_t first = 0, last = full_size ? full_size - 1 : 0;
+    std::string_view range = req->getHeader("range"); if (range.empty()) range = req->getHeader("Range");
+    if (!range.empty()) {
+      if (range.substr(0, 6) != "bytes=") { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; }
+      const std::string_view spec = range.substr(6); const size_t dash = spec.find('-');
+      if (dash == std::string_view::npos || dash == 0) { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; }
+      first = 0; for (char c : spec.substr(0, dash)) { if (c < '0' || c > '9') { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; } first = first * 10 + (c - '0'); }
+      if (dash + 1 < spec.size()) { last = 0; for (char c : spec.substr(dash + 1)) { if (c < '0' || c > '9') { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; } last = last * 10 + (c - '0'); } }
+      if (first >= full_size || last < first) { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "range outside object", true); return true; }
+      if (last >= full_size) last = full_size - 1;
+      char content_range[96]; snprintf(content_range, sizeof(content_range), "bytes %llu-%llu/%llu", (unsigned long long)first, (unsigned long long)last, (unsigned long long)full_size);
+      res->writeStatus("206 Partial Content"); res->writeHeader("Content-Range", content_range);
+    }
+    res->writeHeader("ETag", etag); res->writeHeader("Accept-Ranges", "bytes");
+    struct Download { sb_r2_transfer_ctx* ctx; uintmax_t base; uintmax_t size; uintmax_t sent = 0; bool closed = false; char chunk[65536]; };
+    auto state = std::make_shared<Download>(Download{download, first, last - first + 1});
     auto pump = std::make_shared<std::function<bool()>>();
     *pump = [res, state, pump]() {
       if (state->closed) return false;
-      const uintmax_t offset = res->getWriteOffset(); char chunk[65536];
-      const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)offset, chunk, sizeof(chunk));
-      const auto result = res->tryEnd(std::string_view(chunk, bytes), state->size);
-      if (result.second) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
-      if (!result.first) res->onWritable([pump](uintmax_t) { return (*pump)(); });
-      return false;
+      for (;;) {
+        const size_t want = state->size - state->sent < sizeof(state->chunk) ? (size_t)(state->size - state->sent) : sizeof(state->chunk);
+        const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)(state->base + state->sent), state->chunk, want);
+        const auto result = res->tryEnd(std::string_view(state->chunk, bytes), state->size);
+        if (result.second || bytes == 0) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
+        if (!result.first) {
+          res->onWritable([res, state](uintmax_t offset) {
+            if (state->closed) return true;
+            const size_t want = state->size - offset < sizeof(state->chunk) ? (size_t)(state->size - offset) : sizeof(state->chunk);
+            const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)(state->base + offset), state->chunk, want);
+            const auto resumed = res->tryEnd(std::string_view(state->chunk, bytes), state->size);
+            if (resumed.second || bytes == 0) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return true; }
+            return resumed.first;
+          });
+          return false;
+        }
+        state->sent += bytes;
+        if (state->sent == state->size) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
+      }
     };
     res->writeHeader("Content-Type", "application/octet-stream");
     res->onAborted([state]() { if (!state->closed) { sb_r2_transfer_download_close(state->ctx); state->closed = true; } });
@@ -566,8 +660,18 @@ const UWS_EDITS = [
     WRITE_RESPONSE_INJECT,
     "detect x-sb-raw-body, steer the body read (#176)",
   ],
-  [R2_TRANSFER_MARKER, R2_TRANSFER_ANCHOR, R2_TRANSFER_INJECT, "native direct R2 transfer ingress (#195)"],
-  [R2_TRANSFER_CALL_MARKER, R2_TRANSFER_CALL_ANCHOR, R2_TRANSFER_CALL_INJECT, "direct R2 transfer dispatch (#195)"],
+  [
+    R2_TRANSFER_MARKER,
+    R2_TRANSFER_ANCHOR,
+    R2_TRANSFER_INJECT,
+    "native direct R2 transfer ingress (#195)",
+  ],
+  [
+    R2_TRANSFER_CALL_MARKER,
+    R2_TRANSFER_CALL_ANCHOR,
+    R2_TRANSFER_CALL_INJECT,
+    "direct R2 transfer dispatch (#195)",
+  ],
 ] as const;
 
 /** The uWebSockets shim source: body limit + the #156 status-line fix. Exported for tests. */
@@ -575,16 +679,237 @@ export async function patchUwebsockets(root: string): Promise<void> {
   const file = resolve(root, "compiler/uwebsockets.js");
   let src = await readFile(file, "utf8");
   let changed = false;
+  // Existing shared compiler caches already contain the direct-transfer patch.
+  // Upgrade them in place so a cache built before #202 does not keep linking
+  // the R2 path into every subsequent artifact.
+  if (src.includes(R2_TRANSFER_MARKER) && !src.includes(R2_GATE_MARKER)) {
+    const oldOpen = 'extern "C" {\n  struct sb_r2_transfer_ctx;';
+    const newOpen = '#ifdef SB_R2_TRANSFER\nextern "C" {\n  struct sb_r2_transfer_ctx;';
+    const oldClose = `}\n${R2_TRANSFER_ANCHOR}`;
+    const newClose = `}\n#endif\n${R2_TRANSFER_ANCHOR}`;
+    const oldCall =
+      "  if (try_handle_r2_transfer(res, req, method)) return;\n" + R2_TRANSFER_CALL_ANCHOR;
+    if (!src.includes(oldOpen) || !src.includes(oldClose) || !src.includes(oldCall))
+      throw new Error(
+        `could not gate Porffor's direct R2 transfer bridge: anchor not found in ${file}.`,
+      );
+    src = src
+      .replace(oldOpen, newOpen)
+      .replace(oldClose, newClose)
+      .replace(oldCall, R2_TRANSFER_CALL_INJECT);
+    changed = true;
+  }
   // Upgrade already-patched caches from the initial upload-only bridge. New
   // caches receive the full bridge below; old ones need declarations plus the
   // GET dispatch grafted onto their existing transfer handler.
   if (src.includes(R2_TRANSFER_MARKER) && !src.includes(R2_DOWNLOAD_CACHE_MARKER)) {
     if (!src.includes(R2_DOWNLOAD_DECL_ANCHOR) || !src.includes(R2_DOWNLOAD_BRANCH_ANCHOR))
-      throw new Error(`could not upgrade Porffor's direct R2 transfer bridge: anchor not found in ${file}.`);
+      throw new Error(
+        `could not upgrade Porffor's direct R2 transfer bridge: anchor not found in ${file}.`,
+      );
     src = src.replace(R2_DOWNLOAD_DECL_ANCHOR, R2_DOWNLOAD_DECL_INJECT);
     src = src.replace(R2_DOWNLOAD_BRANCH_ANCHOR, R2_DOWNLOAD_BRANCH_INJECT);
     changed = true;
   }
+  if (src.includes(R2_DOWNLOAD_CACHE_MARKER) && !src.includes(R2_RANGE_CACHE_MARKER)) {
+    const stateAnchor =
+      "    struct Download { sb_r2_transfer_ctx* ctx; uintmax_t size; bool closed = false; };\n    auto state = std::make_shared<Download>(Download{download, sb_r2_transfer_download_size(download)});";
+    const range = `    const uintmax_t full_size = sb_r2_transfer_download_size(download);
+    uintmax_t first = 0, last = full_size ? full_size - 1 : 0;
+    const std::string_view range = req->getHeader("range");
+    if (!range.empty()) {
+      if (range.substr(0, 6) != "bytes=") { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; }
+      const std::string_view spec = range.substr(6); const size_t dash = spec.find('-');
+      if (dash == std::string_view::npos || dash == 0) { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; }
+      first = 0; for (char c : spec.substr(0, dash)) { if (c < '0' || c > '9') { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; } first = first * 10 + (c - '0'); }
+      if (dash + 1 < spec.size()) { last = 0; for (char c : spec.substr(dash + 1)) { if (c < '0' || c > '9') { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "invalid range", true); return true; } last = last * 10 + (c - '0'); } }
+      if (first >= full_size || last < first) { sb_r2_transfer_download_close(download); respond_with_error(res, "416 Range Not Satisfiable", "range outside object", true); return true; }
+      if (last >= full_size) last = full_size - 1;
+      char content_range[96]; snprintf(content_range, sizeof(content_range), "bytes %llu-%llu/%llu", (unsigned long long)first, (unsigned long long)last, (unsigned long long)full_size);
+      res->writeStatus("206 Partial Content"); res->writeHeader("Content-Range", content_range);
+    }
+`;
+    const state =
+      "    struct Download { sb_r2_transfer_ctx* ctx; uintmax_t base; uintmax_t size; bool closed = false; };\n    auto state = std::make_shared<Download>(Download{download, first, last - first + 1});";
+    if (!src.includes(stateAnchor))
+      throw new Error(
+        `could not upgrade Porffor's direct R2 range bridge: anchor not found in ${file}.`,
+      );
+    src = src.replace(
+      "  // sb_r2_transfer_download_v1\n",
+      "  // sb_r2_transfer_download_v1\n  // sb_r2_transfer_range_v1\n",
+    );
+    src = src.replace(stateAnchor, range + state);
+    src = src.replace(
+      "sb_r2_transfer_download_read(state->ctx, (size_t)offset, chunk, sizeof(chunk))",
+      "sb_r2_transfer_download_read(state->ctx, (size_t)(state->base + offset), chunk, sizeof(chunk))",
+    );
+    changed = true;
+  }
+  if (src.includes(R2_RANGE_CACHE_MARKER) && !src.includes(R2_CONDITIONAL_CACHE_MARKER)) {
+    const declaration = "  size_t sb_r2_transfer_download_size(sb_r2_transfer_ctx*);\n";
+    const declarationReplacement =
+      declaration + "  const char* sb_r2_transfer_download_etag(sb_r2_transfer_ctx*);\n";
+    const anchor = "    const uintmax_t full_size = sb_r2_transfer_download_size(download);\n";
+    const inject =
+      `    // sb_r2_transfer_conditional_v1
+    const std::string etag = sb_r2_transfer_download_etag(download);
+    res->writeHeader("ETag", etag); res->writeHeader("Accept-Ranges", "bytes");
+    const std::string_view if_none_match = req->getHeader("if-none-match");
+    if (if_none_match == "*" || if_none_match == etag || (if_none_match.size() == etag.size() + 2 && if_none_match.front() == '"' && if_none_match.back() == '"' && if_none_match.substr(1, etag.size()) == etag)) {
+      sb_r2_transfer_download_close(download); res->writeStatus("304 Not Modified"); res->end(); return true;
+    }
+` + anchor;
+    if (!src.includes(declaration) || !src.includes(anchor))
+      throw new Error(
+        `could not upgrade Porffor's direct R2 conditional bridge: anchor not found in ${file}.`,
+      );
+    src = src.replace(declaration, declarationReplacement).replace(anchor, inject);
+    changed = true;
+  }
+  if (src.includes(R2_CONDITIONAL_CACHE_MARKER) && !src.includes(R2_STREAMING_CACHE_MARKER)) {
+    const oldPump = `      const uintmax_t offset = res->getWriteOffset();
+      char chunk[65536];
+      const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)(state->base + offset), chunk, sizeof(chunk));
+      const auto result = res->tryEnd(std::string_view(chunk, bytes), state->size);
+      if (result.second) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
+      if (!result.first) res->onWritable([pump](uintmax_t) { return (*pump)(); });
+      return false;`;
+    const newPump = `      for (;;) {
+        const uintmax_t offset = res->getWriteOffset(); char chunk[65536];
+        const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)(state->base + offset), chunk, sizeof(chunk));
+        const auto result = res->tryEnd(std::string_view(chunk, bytes), state->size);
+        if (result.second) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
+        if (!result.first) { res->onWritable([pump](uintmax_t) { return (*pump)(); }); return false; }
+      }`;
+    if (!src.includes(oldPump))
+      throw new Error(
+        `could not upgrade Porffor's direct R2 streaming bridge: anchor not found in ${file}.`,
+      );
+    src = src
+      .replace(
+        "  // sb_r2_transfer_conditional_v1\n",
+        "  // sb_r2_transfer_conditional_v1\n  // sb_r2_transfer_streaming_v2\n",
+      )
+      .replace(oldPump, newPump);
+    changed = true;
+  }
+  // A short-lived v2 cache marker was written before its pump fix. Repair
+  // those caches as well as applying the current form to future upgrades.
+  if (
+    src.includes("state->base + offset") &&
+    src.includes("uintmax_t size; bool closed = false;")
+  ) {
+    const oldState =
+      "struct Download { sb_r2_transfer_ctx* ctx; uintmax_t base; uintmax_t size; bool closed = false; };";
+    const newState =
+      "struct Download { sb_r2_transfer_ctx* ctx; uintmax_t base; uintmax_t size; uintmax_t sent = 0; bool closed = false; };";
+    const oldPump = `      const uintmax_t offset = res->getWriteOffset(); char chunk[65536];
+        const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)(state->base + offset), chunk, sizeof(chunk));
+        const auto result = res->tryEnd(std::string_view(chunk, bytes), state->size);
+        if (result.second) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
+        if (!result.first) { res->onWritable([pump](uintmax_t) { return (*pump)(); }); return false; }
+      }`;
+    const newPump = `      char chunk[65536];
+        const size_t bytes = sb_r2_transfer_download_read(state->ctx, (size_t)(state->base + state->sent), chunk, sizeof(chunk));
+        const auto result = res->tryEnd(std::string_view(chunk, bytes), state->size);
+        if (result.second) { sb_r2_transfer_download_close(state->ctx); state->closed = true; return false; }
+        if (!result.first) { res->onWritable([pump, state](uintmax_t offset) { state->sent = offset; return (*pump)(); }); return false; }
+        state->sent += bytes;
+      }`;
+    if (!src.includes(oldState) || !src.includes(oldPump))
+      throw new Error(
+        `could not repair Porffor's direct R2 streaming bridge: anchor not found in ${file}.`,
+      );
+    src = src.replace(oldState, newState).replace(oldPump, newPump);
+    changed = true;
+  }
+  const duplicatePump = "      for (;;) {\n        char chunk[65536];\n      for (;;) {\n";
+  if (src.includes(duplicatePump)) {
+    src = src.replace(duplicatePump, "      for (;;) {\n        char chunk[65536];\n");
+    changed = true;
+  }
+  const unclosedPump = "        state->sent += bytes;\n    };\n";
+  if (src.includes(unclosedPump)) {
+    src = src.replace(unclosedPump, "        state->sent += bytes;\n      }\n    };\n");
+    changed = true;
+  }
+  if (src.includes(R2_STREAMING_CACHE_MARKER) && !src.includes(R2_RANGE_HEADER_CACHE_MARKER)) {
+    const rangeHeader = '    const std::string_view range = req->getHeader("range");\n';
+    if (!src.includes(rangeHeader))
+      throw new Error(
+        `could not upgrade Porffor's direct R2 range-header bridge: anchor not found in ${file}.`,
+      );
+    src = src.replace(
+      "  // sb_r2_transfer_range_v1\n",
+      "  // sb_r2_transfer_range_v1\n  // sb_r2_transfer_range_header_v2\n",
+    );
+    src = src.replace(
+      rangeHeader,
+      '    std::string_view range = req->getHeader("range"); if (range.empty()) range = req->getHeader("Range");\n',
+    );
+    changed = true;
+  }
+  const earlyConditionalHeaders =
+    '    res->writeHeader("ETag", etag); res->writeHeader("Accept-Ranges", "bytes");\n';
+  if (
+    src.includes(earlyConditionalHeaders) &&
+    src.indexOf(earlyConditionalHeaders) <
+      src.indexOf("    const uintmax_t full_size = sb_r2_transfer_download_size(download);")
+  ) {
+    const old304 =
+      '      sb_r2_transfer_download_close(download); res->writeStatus("304 Not Modified"); res->end(); return true;';
+    const new304 =
+      '      sb_r2_transfer_download_close(download); res->writeStatus("304 Not Modified"); res->writeHeader("ETag", etag); res->end(); return true;';
+    const rangeEnd =
+      '      res->writeStatus("206 Partial Content"); res->writeHeader("Content-Range", content_range);\n    }\n';
+    if (!src.includes(old304) || !src.includes(rangeEnd))
+      throw new Error(
+        `could not repair Porffor's direct R2 response ordering: anchor not found in ${file}.`,
+      );
+    src = src
+      .replace(earlyConditionalHeaders, "")
+      .replace(old304, new304)
+      .replace(
+        rangeEnd,
+        rangeEnd +
+          '    res->writeHeader("ETag", etag); res->writeHeader("Accept-Ranges", "bytes");\n',
+      );
+    changed = true;
+  }
+  if (src.includes("state->sent") && src.includes(R2_DOWNLOAD_CACHE_MARKER)) {
+    const stateStart = src.indexOf("    struct Download {", src.indexOf(R2_DOWNLOAD_CACHE_MARKER));
+    const stateEnd = src.indexOf('    res->writeHeader("Content-Type"', stateStart);
+    const freshStart = R2_DOWNLOAD_BRANCH_INJECT.indexOf("    struct Download {");
+    const freshEnd = R2_DOWNLOAD_BRANCH_INJECT.indexOf(
+      '    res->writeHeader("Content-Type"',
+      freshStart,
+    );
+    if (stateStart < 0 || stateEnd < 0 || freshStart < 0 || freshEnd < 0)
+      throw new Error(
+        `could not replace Porffor's direct R2 stream pump: anchor not found in ${file}.`,
+      );
+    src =
+      src.slice(0, stateStart) +
+      R2_DOWNLOAD_BRANCH_INJECT.slice(freshStart, freshEnd) +
+      src.slice(stateEnd);
+    changed = true;
+  }
+  if (src.includes("writable_offset") && src.includes(R2_DOWNLOAD_CACHE_MARKER)) {
+    const stateStart = src.indexOf("    struct Download {", src.indexOf(R2_DOWNLOAD_CACHE_MARKER));
+    const stateEnd = src.indexOf('    res->writeHeader("Content-Type"', stateStart);
+    const freshStart = R2_TRANSFER_INJECT.indexOf("    struct Download {");
+    const freshEnd = R2_TRANSFER_INJECT.indexOf('    res->writeHeader("Content-Type"', freshStart);
+    if (stateStart < 0 || stateEnd < 0 || freshStart < 0 || freshEnd < 0)
+      throw new Error(
+        `could not restore Porffor's direct R2 stream pump: anchor not found in ${file}.`,
+      );
+    src =
+      src.slice(0, stateStart) +
+      R2_TRANSFER_INJECT.slice(freshStart, freshEnd) +
+      src.slice(stateEnd);
+    changed = true;
+  }
   for (const [marker, anchor, inject, what] of UWS_EDITS) {
     if (src.includes(marker)) continue;
     if (!src.includes(anchor)) {
@@ -599,13 +924,14 @@ export async function patchUwebsockets(root: string): Promise<void> {
   if (changed) await writeFile(file, src);
 }
 
-async function patchCompilerArgs(root: string): Promise<void> {
+export async function patchCompilerArgs(root: string): Promise<void> {
   const file = resolve(root, "compiler/index.js");
   let src = await readFile(file, "utf8");
   let changed = false;
   for (const [marker, anchor, inject, what] of [
     [LINK_MARKER, LINK_ANCHOR, LINK_INJECT, "extra link args"],
     [CFLAGS_MARKER, CFLAGS_ANCHOR, CFLAGS_INJECT, "extra compiler flags"],
+    [UWS_CFLAGS_MARKER, UWS_CFLAGS_ANCHOR, UWS_CFLAGS_INJECT, "native-fetch shim compiler flags"],
   ] as const) {
     if (src.includes(marker)) continue;
     const at = src.indexOf(anchor);
@@ -615,10 +941,10 @@ async function patchCompilerArgs(root: string): Promise<void> {
           "Porffor's native-fetch build changed — check patches/UPSTREAM.md.",
       );
     }
-    // After the anchor for cflags (the args follow it), before it for the link
-    // line (the object list ends with it).
+    // After the anchor for compiler flags (the args follow it), before it for
+    // the link line (the object list ends with it).
     src =
-      marker === CFLAGS_MARKER
+      marker === CFLAGS_MARKER || marker === UWS_CFLAGS_MARKER
         ? src.slice(0, at + anchor.length) + inject + src.slice(at + anchor.length)
         : src.slice(0, at) + inject + src.slice(at);
     changed = true;