@sproutboat/runtime 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @sproutboat/runtime
 
+## 0.13.0
+
+### Minor Changes
+
+- 34083e1: Pass `(request, env, ctx)` to handlers built with compatibility dates from 2026-09-28. Older builds retain `(request, ctx)`. Add `Response.redirect()` for native fetch and decode request text as UTF-8 while preserving raw body bytes. The matching compiler Unicode fix shipped in `@sproutboat/toolchain@0.4.14`.
+
+## 0.12.1
+
+### Patch Changes
+
+- ed9640a: Point Porffor patch diagnostics, runtime comments, and historical notes to the
+  shared upstream notes in the Sproutboat platform repository.
+
 ## 0.12.0
 
 ### Minor Changes
@@ -131,11 +144,11 @@
   
   Verified end-to-end against both transports (kitchen-sink's full conformance suite, 24/24 standalone + 27/27 broker) and with new unit tests for file-backed persistence, the `:memory:` fallback, and a real binary round-trip over the v1 wire protocol.
   
-  **Known limitation found while verifying this, not fixed here:** a binary `put()` body (bytes ≥ 0x80) is corrupted on the way *in*, before it ever reaches storage — `porf_native_fetch_read_value` (the function every inline-C string read in the runtime goes through) always UTF-8-encodes a Latin-1-range string on read, which is correct for genuine text but wrong for opaque bytes coming off a raw HTTP body. This predates this change (the old SQLite-blob path had the identical corruption) and is not something the storage backend can fix — it needs an input-side counterpart to `#176`'s `x-sb-raw-body` marker, or real `ArrayBuffer`/`Uint8Array` body support (the upstream ask already filed as Draft G in `patches/UPSTREAM.md`).
+  **Known limitation found while verifying this, not fixed here:** a binary `put()` body (bytes ≥ 0x80) is corrupted on the way *in*, before it ever reaches storage: `porf_native_fetch_read_value` (the function every inline-C string read in the runtime goes through) always UTF-8-encodes a Latin-1-range string on read, which is correct for genuine text but wrong for opaque bytes coming off a raw HTTP body. This predates this change (the old SQLite-blob path had the identical corruption) and is not something the storage backend can fix. It needs an input-side counterpart to `#176`'s `x-sb-raw-body` marker, or real `ArrayBuffer`/`Uint8Array` body support (the upstream ask was filed as Porffor #386 and later retracted; see `https://github.com/baronunread/sproutboat/blob/main/patches/upstream/request-body-report-386.md`).
 
 ### Patch Changes
 
-- 188d8e4: Fix (baronunread/sproutboat#184): a `put()` body (R2, both transports) with bytes ≥ 0x80 was corrupted on the way *in*, before storage — `porf_native_fetch_read_value` (the one function every inline-C string read in the runtime funnels through) always UTF-8-encodes a Latin-1-range value, correct for genuine text, wrong for opaque bytes off a raw HTTP upload. A 256-byte binary upload landed as 384 stored bytes.
+- 188d8e4: Fix (baronunread/sproutboat#184): a `put()` body (R2, both transports) with bytes ≥ 0x80 was corrupted on the way *in*, before storage: `porf_native_fetch_read_value` (the one function every inline-C string read in the runtime funnels through) always UTF-8-encodes a Latin-1-range value, correct for genuine text, wrong for opaque bytes off a raw HTTP upload. A 256-byte binary upload landed as 384 stored bytes.
   
   `__sbR2PutRaw` (embedded) and `__sbCallBin` (broker, the only caller that ever passes it a real body) now try `porf_native_fetch_read_raw_bytes` first, falling back to the normal encoding path only for a genuine multi-byte JS string (which isn't a "bytestring" and so isn't eligible for the raw read anyway). This predates the #56 storage change — the old SQLite-blob `put()` called the identical `read_value`, so it was equally corrupted; the existing R2 conformance check never caught it because it only ever exercises a plain ASCII string.
   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/runtime",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "license": "MIT",
   "type": "module",
   "repository": {

package/src/ingress-utf8.test.js

@@ -0,0 +1,41 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+const src = readFileSync(new URL("./native-fetch-prelude.js", import.meta.url), "utf8");
+const decoder = src.slice(src.indexOf("function __sbFromUtf8("), src.indexOf("// sproutboat #181"));
+const ingress = src.slice(
+  src.indexOf("function __sbDecodeIngress("),
+  src.indexOf("globalThis.__sbEntry ="),
+);
+if (!decoder || !ingress) throw new Error("Ingress decoder source not found");
+// oxlint-disable-next-line no-function-constructor -- Exercise the text-only runtime prelude.
+const load = new Function(`${decoder}\n${ingress}\nreturn __sbDecodeIngress;`);
+const decode = load();
+const raw = (text) =>
+  Array.from(new TextEncoder().encode(text), (byte) => String.fromCharCode(byte)).join("");
+
+test("native ingress text and JSON decode Unicode without changing raw bytes", async () => {
+  const body = raw('{"id":"caffè-🚤"}');
+  const request = { body };
+  decode(request);
+  expect(await request.text()).toBe('{"id":"caffè-🚤"}');
+  expect(await request.json()).toEqual({ id: "caffè-🚤" });
+  expect(await request.text()).toBe('{"id":"caffè-🚤"}');
+  expect(request.body).toBe(body);
+});
+
+test("native ingress retains empty bodies and JSON parse errors", () => {
+  const empty = { body: "" };
+  decode(empty);
+  expect(empty.text()).toBe("");
+  expect(() => empty.json()).toThrow();
+  const invalid = { body: "{" };
+  decode(invalid);
+  expect(() => invalid.json()).toThrow();
+});
+
+test("a bodyless request keeps its existing methods", () => {
+  const text = () => "";
+  const request = { body: null, text };
+  decode(request);
+  expect(request.text).toBe(text);
+});

package/src/native-fetch-prelude.js

@@ -1,7 +1,7 @@
 // Prepended to every handler by tools/compile.ts, before Porffor's native-fetch
-// esbuild bundle. Porffor's runtime/fetch-globals.js (checked through alpha-4)
-// gives URL (href/origin/pathname/search only) and Response without a static
-// json(). This adds, additively, the rest of the WHATWG surface Worker code
+// bundled handler. Porffor's runtime/fetch-globals.js (checked through alpha-10)
+// gives URL (href/origin/pathname/search only) and Response without static
+// json() or redirect(). This adds, additively, the rest of the WHATWG surface Worker code
 // expects: URLSearchParams (read + write), URL.prototype.searchParams and the
 // protocol/host/hostname/port/hash accessors, static Response.json,
 // crypto.randomUUID / crypto.getRandomValues, crypto.subtle (digest + HMAC
@@ -9,14 +9,16 @@
 // formData()/bytes() (#60). Each is feature-detected; delete a block once
 // Porffor ships that global. crypto.scryptVerify (#153) is a Sproutboat
 // extension, not WHATWG, and stays.
-// Tracked upstream in patches/UPSTREAM.md.
+// Tracked in the platform's upstream notes:
+// https://github.com/baronunread/sproutboat/blob/main/patches/upstream/whatwg-fetch-globals.md
 //
 // Declared before it is referenced: a getter body that names a later top-level
-// class throws ReferenceError in Porffor (see patches/UPSTREAM.md draft B).
+// class throws ReferenceError in Porffor. See:
+// https://github.com/baronunread/sproutboat/blob/main/patches/upstream/class-declaration-scope.md
 
 // Duck-typing helpers, `typeof`-free (the repo's anti-slop lint bans `typeof`;
 // these express the same spec-mandated checks and are verified under Porffor
-// alpha-4 by examples/kitchen-sink/harness.ts).
+// alpha-10 by examples/kitchen-sink/harness.ts).
 function __sbIsStr(v) {
   return Object(v) !== v && v === String(v);
 }
@@ -66,7 +68,7 @@ function __sbCpuMs() {
   return res === "" ? 0 : parseFloat(res);
 }
 
-// #28 — stamp `x-sb-cpu-ms` onto a handler Response. Porffor alpha-4's
+// #28 — stamp `x-sb-cpu-ms` onto a handler Response. Porffor alpha-10's
 // native-fetch serializer only reads headers from the plain object passed to
 // `new Response(body, { headers })` — a later `.set()` or a `Headers` instance
 // is ignored on the wire — so the metric is carried by rebuilding the Response
@@ -202,6 +204,16 @@ if (Response.json == null) {
   };
 }
 
+// Porffor alpha-10 has no static Response.redirect().
+if (Response.redirect == null) {
+  Response.redirect = function (url, status = 302) {
+    if (status !== 301 && status !== 302 && status !== 303 && status !== 307 && status !== 308) {
+      throw new RangeError("invalid redirect status");
+    }
+    return new Response("", { status, headers: { location: String(url) } });
+  };
+}
+
 // #59 — caches.default / caches.open(name), backed by the broker's cache.*
 // ops (a sibling SQLite table, key on method+URL for v1 — no Vary yet).
 // Deliberately NOT async: every other buffered-body method on this runtime
@@ -386,7 +398,8 @@ if (!("bytes" in Response.prototype)) {
 // Porffor's URL exposes href / origin / pathname / search only. Add the rest of
 // the WHATWG read surface, derived from `origin` (scheme://host[:port]).
 // `hash` is always '' server-side — browsers strip the fragment before the
-// request, so there is nothing to recover. Tracked upstream (patches/UPSTREAM.md).
+// request, so there is nothing to recover. See:
+// https://github.com/baronunread/sproutboat/blob/main/patches/upstream/whatwg-fetch-globals.md
 function __sbDefineURLAccessor(name, get) {
   if (!(name in URL.prototype)) Object.defineProperty(URL.prototype, name, { configurable: true, get });
 }
@@ -1816,7 +1829,8 @@ function __sbTriggerAuthed(request) {
 // #163 — the connection's remote address, for `request.cf.clientIp`.
 //
 // `x-sb-remote-addr` is the TCP peer, appended by the server (see
-// patches/UPSTREAM.md #163) and stripped from anything a client sends, so it
+// https://github.com/baronunread/sproutboat/blob/main/patches/upstream/remote-address.md)
+// and stripped from anything a client sends, so it
 // cannot be forged. With no proxy in front, that is the client. Behind one, set
 // `SB_TRUSTED_PROXIES` to a comma-separated list of trusted CIDRs (or bare IPs):
 // when the peer is trusted, the client is the rightmost `x-forwarded-for` entry
@@ -2011,7 +2025,26 @@ async function __sbQueueWithDrain(result, tasks) {
   return new Response(JSON.stringify(r), { headers: { "content-type": "application/json" } });
 }
 
+// Native HTTP ingress stores the body as one character per raw byte. Keep
+// that representation for binary consumers, but decode text lazily before
+// handing the request to user code. Request.text() in Porffor otherwise treats
+// the raw bytes as already-decoded characters and corrupts Unicode/HMAC input.
+function __sbDecodeIngress(request) {
+  const raw = request.body;
+  if (raw == null) return;
+  let decoded = null;
+  request.text = function () {
+    if (decoded === null) decoded = __sbFromUtf8(raw);
+    return decoded;
+  };
+  request.json = function () {
+    if (decoded === null) decoded = __sbFromUtf8(raw);
+    return JSON.parse(decoded);
+  };
+}
+
 globalThis.__sbEntry = function (handlers, request) {
+  __sbDecodeIngress(request);
   const trigger = request.headers.get("x-sb-trigger");
   if (!trigger) {
     // #163/#128 — expose the request metadata the edge already has, the
@@ -2033,7 +2066,7 @@ globalThis.__sbEntry = function (handlers, request) {
     // concurrent in-process requests.
     //
     // Sync handlers only. An async handler's promise is handed straight back:
-    // Porffor alpha-4's native-fetch server resolves the promise the handler
+    // Porffor alpha-10's native-fetch server resolves the promise the handler
     // itself returned, but never one derived from `.then()`, so chaining the
     // tag on hangs the request forever. cpuMs is documented as absent for
     // async handlers (see LogEvent in services/edge) — that is this.
@@ -2046,7 +2079,9 @@ globalThis.__sbEntry = function (handlers, request) {
     };
     let __res;
     try {
-      __res = handlers.fetch(request, ctx);
+      __res = globalThis.__sbCompat >= "2026-09-28"
+        ? handlers.fetch(request, globalThis.env, ctx)
+        : handlers.fetch(request, ctx);
     } catch {
       // #179 — a synchronous throw anywhere in the handler must not take the
       // whole process (and every other in-flight request) down with it.
@@ -2073,10 +2108,10 @@ globalThis.__sbEntry = function (handlers, request) {
     };
     let __sres;
     try {
-      __sres = handlers.scheduled(
-        { cron: body.cron || "", scheduledTime: body.scheduledTime || Date.now(), noRetry() {} },
-        ctx,
-      );
+      const event = { cron: body.cron || "", scheduledTime: body.scheduledTime || Date.now(), noRetry() {} };
+      __sres = globalThis.__sbCompat >= "2026-09-28"
+        ? handlers.scheduled(event, globalThis.env, ctx)
+        : handlers.scheduled(event, ctx);
     } catch {
       // #179 — same rule as fetch: don't let a throw here crash the process.
       return new Response("", { status: 204 });
@@ -2163,7 +2198,9 @@ async function __sbRunQueueBatch(handlers, body, ctx) {
     },
   };
   try {
-    const __qres = handlers.queue(batch, ctx);
+    const __qres = globalThis.__sbCompat >= "2026-09-28"
+      ? handlers.queue(batch, globalThis.env, ctx)
+      : handlers.queue(batch, ctx);
     // Was fire-and-forget: an async `queue()` had this default-ack pass run (and
     // the response go out) before its own `await`s did, so any ack()/retry()
     // past the first one never counted.

package/src/source.ts

@@ -25,7 +25,7 @@ const alwaysForbidden: Array<[RegExp, string]> = [
   // match would also flag it appearing in an ordinary string a dependency
   // happens to construct (a doc link, a log message).
   [/['"`]node:/, "Node, Bun, and Deno APIs are not supported"],
-  // Porffor alpha-4 compiles `new Proxy(...)` and then ignores the handler: a
+  // The Porffor pin compiles `new Proxy(...)` and then ignores the handler: a
   // trapped property reads back as `undefined`, with no throw. Rejecting it
   // here is the difference between a build error and a 502 nobody can explain.
   // It is why itty-router and other Proxy-based routers do not work yet.

package/src/workers-handler.test.js

@@ -0,0 +1,59 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+
+const source = readFileSync(new URL("./native-fetch-prelude.js", import.meta.url), "utf8");
+// oxlint-disable-next-line no-function-constructor -- the prelude is prepended as text in production too
+const load = new Function(
+  "Porffor",
+  `${source}\n__sbTriggerAuthed = () => true; return { entry: __sbEntry, queue: __sbRunQueueBatch };`,
+);
+const { entry, queue } = load({ c: () => "" });
+const request = () => ({ headers: { get: () => null }, body: null });
+
+test("the Workers compatibility date passes env and ctx in their standard positions", async () => {
+  globalThis.__sbCompat = "2026-09-28";
+  globalThis.env = { GREETING: "hello" };
+  const response = entry({ fetch(_request, env, ctx) {
+    return new Response(env.GREETING + ":" + (ctx.waitUntil instanceof Function));
+  } }, request());
+  expect(await response.text()).toBe("hello:true");
+});
+
+test("earlier compatibility dates retain ctx as the second argument", async () => {
+  globalThis.__sbCompat = "2026-09-07";
+  const response = entry({ fetch(_request, ctx) {
+    return new Response(String(ctx.waitUntil instanceof Function));
+  } }, request());
+  expect(await response.text()).toBe("true");
+});
+
+test("Response.redirect produces a Location header and empty body", async () => {
+  const response = Response.redirect("https://example.com/next", 301);
+  expect(response.status).toBe(301);
+  expect(response.headers.get("location")).toBe("https://example.com/next");
+  expect(await response.text()).toBe("");
+});
+
+test("queue handlers receive env and ctx with the Workers compatibility date", async () => {
+  globalThis.__sbCompat = "2026-09-28";
+  globalThis.env = { GREETING: "hello" };
+  let seen = "";
+  await queue({ queue(_batch, env, ctx) {
+    seen = env.GREETING + ":" + (ctx.waitUntil instanceof Function);
+  } }, { messages: [] }, { waitUntil() {} });
+  expect(seen).toBe("hello:true");
+});
+
+test("scheduled handlers receive env and ctx with the Workers compatibility date", () => {
+  globalThis.__sbCompat = "2026-09-28";
+  globalThis.env = { GREETING: "hello" };
+  let seen = "";
+  const response = entry({ scheduled(_event, env, ctx) {
+    seen = env.GREETING + ":" + (ctx.waitUntil instanceof Function);
+  } }, {
+    headers: { get: (name) => name === "x-sb-trigger" ? "scheduled" : null },
+    body: "{}",
+  });
+  expect(response.status).toBe(204);
+  expect(seen).toBe("hello:true");
+});

package/test/native-crypto.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { ensurePorffor } from "../../toolchain/src/acquire";
 import { preludePath, TRANSPORT_MARKER, transportPath, wrapNativeFetchHandler } from "../src/wrap";
 
@@ -18,6 +18,7 @@ const expected = {
 };
 
 const handler = `
+import { keyBytes } from "./crypto-helper.js";
 const hex = (buffer) => {
   const bytes = new Uint8Array(buffer);
   let out = "";
@@ -28,7 +29,7 @@ export default {
   async fetch() {
     const key = await crypto.subtle.importKey(
       "raw",
-      new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]),
+      keyBytes(),
       { name: "HMAC", hash: "SHA-256" },
       false,
       ["sign"],
@@ -67,9 +68,8 @@ const workdir = await mkdtemp(join(tmpdir(), "sb-native-crypto-"));
 let server: ReturnType<typeof Bun.spawn> | undefined;
 try {
   const porffor = await ensurePorffor({ cacheRoot: workdir });
-  const esbuild = Bun.which("esbuild");
   const node = Bun.which("node");
-  if (!esbuild || !node) throw new Error("native crypto test needs esbuild and node on PATH");
+  if (!node) throw new Error("native crypto test needs node on PATH");
 
   const [core, broker] = await Promise.all([
     readFile(preludePath, "utf8"),
@@ -79,12 +79,15 @@ try {
   const prelude = core.replace(TRANSPORT_MARKER, broker);
   const generated = join(workdir, "crypto.generated.js");
   const binary = join(workdir, "crypto-native");
+  // This is a direct ESM import into Porffor, with no bundler in front of it.
+  await writeFile(join(workdir, "crypto-helper.js"),
+    "export const keyBytes = () => Uint8Array.from({ length: 16 }, (_, index) => index + 1);\n");
   await writeFile(generated, wrapNativeFetchHandler(handler, prelude));
   await rm(binary, { force: true });
 
   const compile = Bun.spawn([node, resolve(porffor, "runtime/index.js"), "native", generated, "-o", binary, "-s", "-O0"], {
     cwd: workdir,
-    env: { ...process.env, PATH: `${dirname(esbuild)}:${process.env.PATH ?? ""}` },
+    env: process.env,
     stdout: "pipe",
     stderr: "pipe",
   });