@sproutboat/wire 0.13.2 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @sproutboat/wire
 
+## 0.14.0
+
+### Minor Changes
+
+- f2d2b72: Service-binding calls behave as in workerd in two more ways, on a platform edge that vouches for them:
+  
+  - **The callee sees the caller's URL.** `request.url` is the URL the caller passed (`https://peer/path`), where it used to be the callee deployment's own hostname.
+  - **A callee that throws makes the caller throw.** The caller's `fetch()` rejects with the callee's error, keeping its class for standard errors and its message, where it used to get a plain 500 response.
+  
+  How the platform vouches for a call:
+  
+  1. The broker sends each service call with the edge's secret (`SB_EDGE_SECRET`, which the edge gives only to brokers) and the caller's URL.
+  2. The edge forwards the call to the callee with that sprout's own token (`SB_EDGE_TOKEN`).
+  3. The callee trusts a call only when the token matches.
+  
+  A client can forge none of this. The edge removes its headers from every other request, and the error marker never reaches a client.
+  
+  A vouched call also no longer shows the broker's loopback address as `x-sb-remote-addr`. The edge's internal headers are removed before any handler sees a request.
+  
+  In `@sproutboat/wire`, the broker reads `SB_EDGE_SECRET` and takes an `edgeSecret` option.
+- b287117: `fetch()` and service bindings honour an abort signal, set as `init.signal` or a `Request`'s `signal`:
+  
+  - A signal that is already aborted rejects the call at once.
+  - Aborting it later, by hand or through `AbortSignal.timeout()`, rejects the pending call with the signal's reason.
+  
+  In a deployed sprout the abort also stops the work. The sprout closes the call's broker connection, the broker aborts its upstream request when a sprout's connection closes, and the platform's edge stops the callee's request in turn. Before, an abandoned call ran to the end anyway.
+  
+  In sproutd the request still runs to the end, and its late reply is dropped.
+  
+  In `@sproutboat/wire`, `Broker.handleFrame` takes an optional `AbortSignal`, which the broker server aborts when the connection closes.
+- 3798994: Responses to `fetch()` and service-binding calls stream. In a deployed sprout with compatibility date `2026-10-21` or later, the call resolves as soon as the status and headers arrive. `response.body` is then a `ReadableStream` that receives each chunk as the upstream sends it.
+  
+  Before, the whole body had to arrive first. A response streamed over several seconds, such as server-sent events or a long download, reached the caller only at the end.
+  
+  The 32 MiB `SB_FETCH_MAX_BYTES` cap still applies to the total. Cancelling the body, or aborting the call's signal, stops the upstream request.
+  
+  In `@sproutboat/wire`:
+  - the broker streams a `fetch` or `service.fetch` that asks for it (`stream: true`), sending the head and each chunk as `FRAME_V1_MORE` frames through the new `emit` argument of `handleFrame`;
+  - the final frame ends the response;
+  - a request that doesn't ask is answered whole, as before.
+
+### Patch Changes
+
+- Updated dependencies [85aa74d]
+- Updated dependencies [f2d2b72]
+- Updated dependencies [b287117]
+- Updated dependencies [9773e45]
+- Updated dependencies [3798994]
+  - @sproutboat/runtime@0.20.0
+
 ## 0.13.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/wire",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -12,7 +12,7 @@
   "types": "./src/index.ts",
   "dependencies": {
     "@sproutboat/assets": "^0.3.0",
-    "@sproutboat/runtime": "^0.19.0"
+    "@sproutboat/runtime": "^0.20.0"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/broker.ts

@@ -76,6 +76,12 @@ export type BrokerOptions = {
    * of where a deployment is running.
    */
   edgeUrl?: string;
+  /**
+   * The edge's secret for service-binding calls (`SB_EDGE_SECRET`). With it, a call
+   * carries the secret and the caller's URL, so the edge can vouch for the call to the
+   * callee: the callee then sees that URL, and a callee that throws throws in the caller.
+   */
+  edgeSecret?: string;
   /**
    * #48 — binding name -> the target's hostname, resolved by the control plane
    * at activation. Not part of the artifact: the same binary deploys to boxes
@@ -185,9 +191,13 @@ export type Broker = {
    * v1 starts with a 0x01 marker and carries `[u32 LE json length][json][bytes]`,
    * so an object body never has to be escaped into the JSON. A token's first
    * character is never 0x01, which is what makes the two tellable apart without
-   * negotiation.
+   * negotiation. `signal` aborts when the sprout's connection closes: a `fetch` or
+   * `service.fetch` in flight then stops its upstream request too. With `emit`, a
+   * `fetch` or `service.fetch` that asks to stream (`stream: true`) sends its head and
+   * each body chunk through it as they arrive (FRAME_V1_MORE frames); the returned
+   * frame ends the response.
    */
-  handleFrame(payload: Buffer): Promise<Buffer>;
+  handleFrame(payload: Buffer, signal?: AbortSignal, emit?: FrameEmitter): Promise<Buffer>;
   /** Serve one reserved direct R2 upload or download request. */
   transfer(request: Request): Promise<Response>;
   close(): void;
@@ -195,6 +205,10 @@ export type Broker = {
 
 /** First byte of a v1 payload. */
 export const FRAME_V1 = 1;
+/** A v1 frame with more to follow for the same request: a streamed response's head and chunks. */
+export const FRAME_V1_MORE = 2;
+/** Sends one frame for the request being handled, ahead of its final one. */
+export type FrameEmitter = (frame: Buffer) => Promise<void>;
 
 /** Wrap a payload in the [u32 LE length] header every frame carries. */
 export function frameOf(payload: Buffer): Buffer {
@@ -205,11 +219,11 @@ export function frameOf(payload: Buffer): Buffer {
 }
 
 /** Build a v1 payload: marker, json length, json, then the bytes. */
-export function encodeV1(json: Frame, binary?: Uint8Array): Buffer {
+export function encodeV1(json: Frame, binary?: Uint8Array, more = false): Buffer {
   const body = Buffer.from(JSON.stringify(json), "utf8");
   const bin = binary ?? new Uint8Array(0);
   const out = Buffer.allocUnsafe(1 + 4 + body.length + bin.length);
-  out.writeUInt8(FRAME_V1, 0);
+  out.writeUInt8(more ? FRAME_V1_MORE : FRAME_V1, 0);
   out.writeUInt32LE(body.length, 1);
   body.copy(out, 5);
   if (bin.length) Buffer.from(bin.buffer, bin.byteOffset, bin.length).copy(out, 5 + body.length);
@@ -1095,8 +1109,9 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
    * end the process. 32 MiB by default, and the same variable the embedded
    * transport reads so both backends agree.
    */
+  const fetchMaxBytes = () => Number(process.env.SB_FETCH_MAX_BYTES) || 32 * 1024 * 1024;
   async function readCapped(response: Response, host: string): Promise<Buffer> {
-    const cap = Number(process.env.SB_FETCH_MAX_BYTES) || 32 * 1024 * 1024;
+    const cap = fetchMaxBytes();
     const declared = Number(response.headers.get("content-length") || 0);
     if (declared > cap) throw new Error(`response exceeds SB_FETCH_MAX_BYTES from ${host}`);
     const reader = response.body?.getReader();
@@ -1148,7 +1163,32 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     return res;
   }
 
-  async function proxyFetch(msg: Frame): Promise<Upstream> {
+  /**
+   * An upstream response, streamed: its head now, then each body chunk as it arrives,
+   * under the same cap as a whole body. `emit` resolves once the sprout's socket has
+   * taken the frame, so a slow reader slows the upstream read too.
+   */
+  async function streamUpstream(res: Response, host: string, emit: FrameEmitter): Promise<Upstream> {
+    const headers: Array<[string, string]> = [];
+    res.headers.forEach((v, k) => headers.push([k, v]));
+    await emit(frameOf(encodeV1({ ok: true, status: res.status, headers, stream: true }, undefined, true)));
+    const reader = res.body?.getReader();
+    if (!reader) return { reply: { ok: true, end: true }, bytes: Buffer.alloc(0) };
+    const cap = fetchMaxBytes();
+    let total = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return { reply: { ok: true, end: true }, bytes: Buffer.alloc(0) };
+      total += value.byteLength;
+      if (total > cap) {
+        await reader.cancel();
+        throw new Error(`response exceeds SB_FETCH_MAX_BYTES from ${host}`);
+      }
+      await emit(frameOf(encodeV1({ ok: true, chunk: true }, value, true)));
+    }
+  }
+
+  async function proxyFetch(msg: Frame, signal?: AbortSignal, emit?: FrameEmitter): Promise<Upstream> {
     let url: URL;
     try {
       url = new URL(str(msg.url));
@@ -1169,12 +1209,14 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       headers,
       body: method === "GET" || method === "HEAD" ? undefined : upstreamBody(msg),
       redirect: "manual",
+      signal,
     };
     const res = egressUrl
       ? await viaEgressService(url, init)
       : await vettedFetch(url, init, { resolve: resolveHost, allow: egressAllow, fetchImpl: doFetch });
     const outHeaders: Array<[string, string]> = [];
     res.headers.forEach((v, k) => outHeaders.push([k, v]));
+    if (msg.stream === true && emit) return streamUpstream(res, url.host, emit);
     return { reply: { ok: true, status: res.status, headers: outHeaders }, bytes: await readCapped(res, url.host) };
   }
 
@@ -1186,7 +1228,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
    * minus the trip through the network (and therefore minus TLS and the
    * default-deny egress rules, which is why this is not `fetch`).
    */
-  async function serviceFetch(msg: Frame): Promise<Upstream> {
+  async function serviceFetch(msg: Frame, signal?: AbortSignal, emit?: FrameEmitter): Promise<Upstream> {
     const binding = str(msg.binding);
     const declared = bindings.services.find((entry) => entry.binding === binding);
     if (!declared) throw new Error(`service not bound: ${binding}`);
@@ -1211,6 +1253,10 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
     }
     headers.set("host", host);
+    if (opts.edgeSecret) {
+      headers.set("x-sb-edge-secret", opts.edgeSecret);
+      headers.set("x-sb-url", str(msg.url));
+    }
     const method = str(msg.method || "GET").toUpperCase();
     const target = new URL(path, opts.edgeUrl);
     const res = await doFetch(target, {
@@ -1218,9 +1264,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       headers,
       body: method === "GET" || method === "HEAD" ? undefined : upstreamBody(msg),
       redirect: "manual",
+      signal,
     });
     const outHeaders: Array<[string, string]> = [];
     res.headers.forEach((v, k) => outHeaders.push([k, v]));
+    if (msg.stream === true && emit) return streamUpstream(res, host, emit);
     return { reply: { ok: true, status: res.status, headers: outHeaders }, bytes: await readCapped(res, host) };
   }
 
@@ -1658,7 +1706,12 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
    * #63 — the ops that carry bytes rather than escaping them into the frame.
    * Everything else goes through `dispatch` untouched.
    */
-  async function dispatchBinary(msg: Frame, binary: Uint8Array): Promise<{ reply: Frame; bytes?: Uint8Array }> {
+  async function dispatchBinary(
+    msg: Frame,
+    binary: Uint8Array,
+    signal?: AbortSignal,
+    emit?: FrameEmitter,
+  ): Promise<{ reply: Frame; bytes?: Uint8Array }> {
     if (msg.op === "r2.put") {
       // The body arrived as bytes; write it straight to its own file rather
       // than into SQLite (#56) — no escape, no parse, no re-encode, and no
@@ -1708,8 +1761,8 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     }
 
     // #232 — a v1 fetch gets the upstream body as raw bytes, not decoded text.
-    if (msg.op === "fetch") return proxyFetch(msg);
-    if (msg.op === "service.fetch") return serviceFetch(msg);
+    if (msg.op === "fetch") return proxyFetch(msg, signal, emit);
+    if (msg.op === "service.fetch") return serviceFetch(msg, signal, emit);
 
     if (msg.op === "assets.get") {
       if (!bindings.assets) throw new Error("assets not bound");
@@ -1741,7 +1794,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   }
 
   /** One wire frame in, one out. See `handleFrame` on the Broker type. */
-  async function handleFrame(payload: Buffer): Promise<Buffer> {
+  async function handleFrame(payload: Buffer, signal?: AbortSignal, emit?: FrameEmitter): Promise<Buffer> {
     if (payload.length === 0 || payload[0] !== FRAME_V1) {
       return encodeFrame(await handlePayload(payload.toString("utf8")));
     }
@@ -1757,7 +1810,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         const seen = replayed.get(replayKey);
         if (seen) return frameOf(encodeV1(seen));
       }
-      const { reply, bytes } = await dispatchBinary(msg, binary);
+      const { reply, bytes } = await dispatchBinary(msg, binary, signal, emit);
       if (replayKey && REPLAYABLE.has(str(msg.op))) rememberReplay(replayKey, reply);
       return frameOf(encodeV1(reply, bytes));
     } catch (e) {
@@ -2124,6 +2177,8 @@ export function listen(broker: Broker, hostname: string, port: number): BrokerSe
     output: Buffer | null;
     offset: number;
     written: (() => void) | null;
+    /** Aborted when the connection closes, so upstream requests it started stop. */
+    abort: AbortController;
   };
   const flush = (socket: Bun.Socket<SocketState>): void => {
     const state = socket.data;
@@ -2152,12 +2207,22 @@ export function listen(broker: Broker, hostname: string, port: number): BrokerSe
     port,
     socket: {
       open(socket) {
-        socket.data = { chunks: [], size: 0, processing: false, closed: false, output: null, offset: 0, written: null };
+        socket.data = {
+          chunks: [],
+          size: 0,
+          processing: false,
+          closed: false,
+          output: null,
+          offset: 0,
+          written: null,
+          abort: new AbortController(),
+        };
       },
       drain: flush,
       close(socket) {
         const state = socket.data;
         state.closed = true;
+        state.abort.abort();
         state.chunks = [];
         state.size = 0;
         state.output = null;
@@ -2193,7 +2258,7 @@ export function listen(broker: Broker, hostname: string, port: number): BrokerSe
           state.size = rest.length;
           // Bun does not buffer unwritten bytes. Serialize replies and retain
           // the unsent suffix until drain, including binary R2 responses.
-          await send(socket, await broker.handleFrame(payload));
+          await send(socket, await broker.handleFrame(payload, state.abort.signal, (frame) => send(socket, frame)));
         } } finally { state.processing = false; }
       },
     },
@@ -2287,6 +2352,7 @@ export function startBroker(argv: string[], d1Pool?: D1Pool) {
     sproutUrl: values["sprout-url"] ?? process.env.SB_SPROUT_URL,
     assetsDir: values["assets-dir"],
     edgeUrl: values["edge-url"],
+    edgeSecret: process.env.SB_EDGE_SECRET || undefined,
     services,
     dispatchEnabled: () => dispatchEnabled,
   });