sproutboat 0.7.0 → 0.8.0

package/src/compile.ts

@@ -13,7 +13,16 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { ensurePorfforPatched } from "./patch-porffor";
 import { ensureUWebSockets, porfforRoot, UwsUnavailableError } from "./toolchain";
-import { EMPTY_BINDINGS, preludePath, wrapNativeFetchHandler, type Bindings } from "./wrap";
+import {
+  EMPTY_BINDINGS,
+  preludePath,
+  transportPath,
+  wrapNativeFetchHandler,
+  TRANSPORT_MARKER,
+  type Bindings,
+  type Transport,
+} from "./wrap";
+export type { Transport } from "./wrap";
 
 export {
   BASELINE_COMPATIBILITY_DATE,
@@ -35,6 +44,16 @@ export type CompileInput = {
   /** The project's `compatibility_date`, baked in so the runtime can gate a
    *  behaviour change on it. Defaults to the baseline when absent. */
   compatibilityDate?: string;
+  /** #15 — which `__sbCall` to compile in. Defaults to the broker transport. */
+  transport?: Transport;
+  /** #15 — the project name, baked so an embedded build can default its data dir. */
+  appName?: string;
+  /** #15 — assets baked into the module (embedded builds have no files on disk). */
+  assets?: { manifest: unknown; files: Record<string, string> };
+  /** #15 — objects to add to the native-fetch link line (SQLite, BearSSL). */
+  extraLink?: string[];
+  /** #15 — flags for the compile step, so inline C can include BearSSL's header. */
+  extraCflags?: string[];
   /** Cross-compiler for `linux-x86_64`. Not needed, and not used, for `host`. */
   zigBin?: string;
   /**
@@ -46,6 +65,29 @@ export type CompileInput = {
   target?: "linux-x86_64" | "host";
 };
 
+/**
+ * The prelude with a transport spliced in — the exact text the compiler sees.
+ *
+ * Exported because more than one caller composes a sprout: the build, and the
+ * kitchen-sink harness that compiles one itself. Reading
+ * `native-fetch-prelude.js` alone yields a module with no `__sbCall` at all.
+ */
+export async function loadPrelude(transport: Transport = "broker"): Promise<string> {
+  const [core, chosen] = await Promise.all([readFile(preludePath, "utf8"), readFile(transportPath(transport), "utf8")]);
+  if (!core.includes(TRANSPORT_MARKER)) {
+    throw new Error("prelude is missing its transport marker — src/native-fetch-prelude.js changed shape");
+  }
+  return core.replace(TRANSPORT_MARKER, chosen);
+}
+
+/** Child env for the Porffor run. `SB_EXTRA_LINK` is read by the patched link
+ *  step (#15) and is absent entirely for a normal build. */
+function compileEnv(path: string, extraLink?: string[], extraCflags?: string[]) {
+  const link = extraLink && extraLink.length > 0 ? extraLink.join(" ") : undefined;
+  const cflags = extraCflags && extraCflags.length > 0 ? extraCflags.join(" ") : undefined;
+  return { ...process.env, PATH: path, SB_EXTRA_LINK: link, SB_EXTRA_CFLAGS: cflags };
+}
+
 /** Compile `sourcePath` to a native binary at `outPath` (mode 0555). */
 export async function compileSprout(input: CompileInput): Promise<void> {
   await ensurePorfforPatched();
@@ -83,7 +125,7 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   const generatedPath = resolve(outDir, "sprout.generated.js");
   const [source, prelude] = await Promise.all([
     input.source === undefined ? readFile(input.sourcePath, "utf8") : Promise.resolve(input.source),
-    readFile(preludePath, "utf8"),
+    loadPrelude(input.transport ?? "broker"),
   ]);
   await writeFile(
     generatedPath,
@@ -94,6 +136,8 @@ export async function compileSprout(input: CompileInput): Promise<void> {
       input.bindings ?? EMPTY_BINDINGS,
       undefined,
       input.compatibilityDate,
+      input.appName,
+      input.assets,
     ),
   );
 
@@ -113,7 +157,12 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   const crossFlags = input.target === "host" ? [] : ["--musl"];
   const child = Bun.spawn(
     [process.execPath, launcher, "native", generatedPath, "-o", input.outPath, ...crossFlags, "-s"],
-    { cwd: outDir, stdout: "pipe", stderr: "pipe", env: { ...process.env, PATH: path } },
+    {
+      cwd: outDir,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: compileEnv(path, input.extraLink, input.extraCflags),
+    },
   );
   let timedOut = false;
   const timer = setTimeout(() => {

package/src/config.ts

@@ -58,6 +58,9 @@ export type SproutboatConfig = {
   analytics_engine_datasets?: string[];
   /** Durable Object bindings: `{ BINDING_NAME: "ClassName" }`. The class is defined in the handler module. */
   durable_objects?: Record<string, string>;
+  /** #48 — worker-to-worker calls: `env.<BINDING>.fetch(request)` reaches another
+   *  project on this control plane, resolved to its hostname at activation. */
+  services?: Array<{ binding: string; service: string }>;
   /** Scheduled triggers, e.g. `{ "crons": ["0 3 * * *"] }` — a `scheduled(event)` handler runs on each tick. */
   triggers?: { crons?: string[] };
   /** Static assets: a directory served edge-first (like Cloudflare), optionally bound as `env.<BINDING>.fetch(request)`. */
@@ -114,6 +117,7 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     "queues",
     "analytics_engine_datasets",
     "durable_objects",
+    "services",
     "triggers",
     "assets",
   ]);
@@ -233,6 +237,25 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     }
   }
 
+  let services: Array<{ binding: string; service: string }> | undefined;
+  if (value.services !== undefined) {
+    if (!Array.isArray(value.services)) {
+      errors.push('services must be an array of { binding: "NAME", service: "project-name" }');
+    } else {
+      services = [];
+      for (const entry of value.services) {
+        const row = isRecord(entry) ? entry : null;
+        const binding = row && isString(row.binding) ? row.binding : "";
+        const service = row && isString(row.service) ? row.service : "";
+        if (!bindingName.test(binding) || !isProjectSlug(service)) {
+          errors.push('services entries must be { binding: "UPPER_SNAKE", service: "project-name" }');
+        } else if (services.some((s) => s.binding === binding)) {
+          errors.push(`services: duplicate binding ${binding}`);
+        } else services.push({ binding, service });
+      }
+    }
+  }
+
   let triggers: { crons?: string[] } | undefined;
   if (value.triggers !== undefined) {
     if (!isRecord(value.triggers)) {
@@ -301,6 +324,7 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     ...resourceNames(queues),
     ...(analytics_engine_datasets ?? []),
     ...Object.keys(durable_objects ?? {}),
+    ...(services ?? []).map((entry) => entry.binding),
     ...Object.keys(vars ?? {}),
     ...(assets?.binding ? [assets.binding] : []),
   ];
@@ -319,6 +343,7 @@ function validateConfig(value: ConfigInput): ConfigValidation {
   if ("queues" in value) config.queues = queues;
   if ("analytics_engine_datasets" in value) config.analytics_engine_datasets = analytics_engine_datasets;
   if ("durable_objects" in value) config.durable_objects = durable_objects;
+  if ("services" in value) config.services = services;
   if ("triggers" in value) config.triggers = triggers;
   if ("assets" in value) config.assets = assets;
   return { ok: true, value: config };

package/src/main.ts

@@ -8,6 +8,7 @@ import { validateHttpSyncSource } from "./source";
 import { buildArtifact } from "./build";
 import { bundleHandler, BundleError, type BundleResult } from "./bundle";
 import { runDev } from "./dev";
+import { buildStandalone } from "./standalone-build";
 import { hostTarget, validateManifest, type ArtifactManifest } from "./manifest";
 import { CLI_VERSION, printDeployReport } from "./report";
 import { activeApiUrl, forgetToken, savedToken, saveToken } from "./credentials";
@@ -251,6 +252,32 @@ async function build(directory?: string, target: "linux-x86_64" | "host" = "linu
   return { project, artifact };
 }
 
+/**
+ * #15 — one executable carrying the sprout, its assets and its bindings.
+ *
+ * Defaults to a host build: the point is a binary you can run right here. Pass
+ * `--target linux-x86_64` for a box, but note the Bun launcher is compiled for
+ * *this* machine either way in phase 0 — cross-compiling both halves comes with
+ * the embedded backend, which removes the launcher entirely.
+ */
+async function buildStandaloneBinary(directory: string | undefined, target: "linux-x86_64" | "host") {
+  const project = await readProject(directory);
+  console.log(dim(`Building a standalone ${project.config.name} (${target})…`));
+  try {
+    const result = await buildStandalone({
+      projectDir: project.directory,
+      config: project.config,
+      sourcePath: project.sourcePath,
+      source: project.bundle.code,
+      target,
+    });
+    console.log(ok(`built ${result.outPath} (${(result.bytes / 1_000_000).toFixed(1)} MB)`));
+    console.log(dim(`  run it: ${result.outPath}   ·   state lands in ./${project.config.name}.data`));
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
 /** #62 — build for this machine, run it against a real broker, rebuild on save. */
 async function dev(args: string[]) {
   const directory = args.find((arg) => !arg.startsWith("--") && !/^\d+$/.test(arg));
@@ -941,10 +968,9 @@ switch (command) {
     break;
   case "build": {
     const hostBuild = args.includes("--target") && args[args.indexOf("--target") + 1] === "host";
-    await build(
-      args.find((arg) => !arg.startsWith("--") && arg !== "host"),
-      hostBuild ? "host" : "linux-x86_64",
-    );
+    const directory = args.find((arg) => !arg.startsWith("--") && arg !== "host");
+    if (args.includes("--standalone")) await buildStandaloneBinary(directory, hostBuild ? "host" : "linux-x86_64");
+    else await build(directory, hostBuild ? "host" : "linux-x86_64");
     break;
   }
   case "login":

package/src/native-fetch-prelude.js

@@ -283,16 +283,10 @@ if (globalThis.crypto.randomUUID == null) {
 // sprout event-loop turn per request, so a blocking roundtrip is acceptable).
 // Wire frame:
 //   [u32 LE len][ <token> "\n" <json> ]   reply: [u32 LE len][ <json> ]
-// SB_BROKER_PORT / SB_BROKER_TOKEN are set by the supervisor next to $PORT.
-// If SB_BROKER_PORT is unset the shims below are never installed (compile.ts
-// only emits the __sbInstallBindings call when the project declares bindings),
-// so a plain sprout is byte-for-byte unchanged.
-// ponytail: text values only; still AF_INET loopback, not AF_UNIX. A failed
-// exchange reconnects and resends once — a broker crash between "request applied"
-// and "reply read" can double-apply a non-idempotent op (queue.send, INSERT);
-// the old fresh-connection-per-call path just failed the call there instead.
-// Binary values + AF_UNIX = v2.
-
+// Shared C preamble: the headers, the two Porffor marshalling helpers every
+// inline-C block uses, and the CSPRNG. Lives here rather than in a transport so
+// both transports — and __sbRandomBytes / __sbEnv below — compile against the
+// same declarations.
 // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
 Porffor.c`
 #include <sys/socket.h>
@@ -330,118 +324,9 @@ static int sb_os_random(unsigned char* buf, size_t n) {
   return 0;
 }
 
-static int sb_io_all(int fd, unsigned char* buf, size_t len, int writing) {
-  size_t done = 0;
-  while (done < len) {
-    long n = writing ? write(fd, buf + done, len - done) : read(fd, buf + done, len - done);
-    if (n <= 0) {
-      if (n < 0 && errno == EINTR) continue;
-      return -1;
-    }
-    done += (size_t)n;
-  }
-  return 0;
-}
-
-// One long-lived loopback connection to the broker, reused across every binding
-// call. The broker frames each request/reply independently and keeps the socket
-// open, so the steady-state per-call cost is just write + read — no socket(),
-// connect() handshake or close() each time. -1 = not connected.
-static int sb_broker_fd = -1;
-
-static int sb_broker_connect(void) {
-  const char* port_s = getenv("SB_BROKER_PORT");
-  if (!port_s) return -10;
-  signal(SIGPIPE, SIG_IGN); // a dead broker must yield EPIPE, not kill the sprout
-  int fd = socket(AF_INET, SOCK_STREAM, 0);
-  if (fd < 0) return -1;
-  int one = 1;
-  setsockopt(fd, IPPROTO_TCP, TCP_NODELAY, &one, sizeof(one));
-  struct sockaddr_in addr;
-  memset(&addr, 0, sizeof(addr));
-  addr.sin_family = AF_INET;
-  addr.sin_port = htons((unsigned short)atoi(port_s));
-  addr.sin_addr.s_addr = htonl(0x7f000001u); // 127.0.0.1
-  if (connect(fd, (struct sockaddr*)&addr, sizeof(addr)) != 0) { close(fd); return -2; }
-  sb_broker_fd = fd;
-  return 0;
-}
-
-// Send one framed request, read one framed reply, on the persistent fd.
-static int sb_broker_exchange(const char* req, size_t req_len, char** resp_out, size_t* resp_len_out) {
-  const char* tok = getenv("SB_BROKER_TOKEN");
-  size_t tok_len = tok ? strlen(tok) : 0;
-
-  // frame body: token "\n" json
-  size_t body_len = tok_len + 1 + req_len;
-  unsigned char* frame = (unsigned char*)malloc(4 + body_len);
-  if (!frame) return -5;
-  frame[0] = (unsigned char)(body_len & 0xff);
-  frame[1] = (unsigned char)((body_len >> 8) & 0xff);
-  frame[2] = (unsigned char)((body_len >> 16) & 0xff);
-  frame[3] = (unsigned char)((body_len >> 24) & 0xff);
-  if (tok_len) memcpy(frame + 4, tok, tok_len);
-  frame[4 + tok_len] = '\n';
-  if (req_len) memcpy(frame + 4 + tok_len + 1, req, req_len);
-  int wr = sb_io_all(sb_broker_fd, frame, 4 + body_len, 1);
-  free(frame);
-  if (wr != 0) return -3;
-
-  unsigned char rhdr[4];
-  if (sb_io_all(sb_broker_fd, rhdr, 4, 0) != 0) return -4;
-  size_t rlen = (size_t)rhdr[0] | ((size_t)rhdr[1] << 8) | ((size_t)rhdr[2] << 16) | ((size_t)rhdr[3] << 24);
-
-  char* buf = (char*)malloc(rlen ? rlen : 1);
-  if (!buf) return -5;
-  if (rlen && sb_io_all(sb_broker_fd, (unsigned char*)buf, rlen, 0) != 0) { free(buf); return -6; }
-
-  *resp_out = buf;
-  *resp_len_out = rlen;
-  return 0;
-}
-
-static int sb_broker_roundtrip(const char* req, size_t req_len, char** resp_out, size_t* resp_len_out) {
-  *resp_out = NULL;
-  *resp_len_out = 0;
-  // Two tries: a broker restart (or an idle-closed socket) invalidates the fd,
-  // so a failed exchange drops the connection and reconnects once before failing.
-  for (int attempt = 0; attempt < 2; attempt++) {
-    if (sb_broker_fd < 0) {
-      int rc = sb_broker_connect();
-      if (rc != 0) return rc;
-    }
-    int rc = sb_broker_exchange(req, req_len, resp_out, resp_len_out);
-    if (rc == 0) return 0;
-    close(sb_broker_fd);
-    sb_broker_fd = -1;
-  }
-  return -3;
-}
 `;
 
-// One request string in, one reply string out. `reqJson` is a parameter, so the
-// generated C names it directly in the RawC block below.
-// oxlint-disable-next-line no-unused-vars -- `reqJson` is read inside the RawC block below, not by JS.
-function __sbCall(reqJson) {
-  let res = "";
-  // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
-  Porffor.c`
-    const char* __req; size_t __reqlen; char* __reqowned = 0;
-    porf_native_fetch_read_value(reqJson, &__req, &__reqlen, &__reqowned);
-    char* __resp = 0; size_t __resplen = 0;
-    int __rc = sb_broker_roundtrip(__req, __reqlen, &__resp, &__resplen);
-    if (__reqowned) free(__reqowned);
-    if (__rc == 0) {
-      res = porf_box((f64)porf_native_fetch_alloc_bytestring(__resp, __resplen), 195);
-      free(__resp);
-    } else {
-      char __e[40];
-      int __n = snprintf(__e, sizeof(__e), "{\"ok\":false,\"error\":\"broker rc %d\"}", __rc);
-      res = porf_box((f64)porf_native_fetch_alloc_bytestring(__e, (size_t)__n), 195);
-    }
-  `;
-  return res;
-}
+// TRANSPORT: wrap.ts splices one of transport-broker.js / transport-embedded.js here.
 
 // `nStr` is the decimal byte count as a string (same string-param pattern as
 // __sbEnv). Returns a bytestring of that many CSPRNG bytes, or '' on failure.
@@ -469,8 +354,14 @@ function __sbRandomBytes(nStr) {
   return out;
 }
 
+// #63 — every request carries the protocol version it was built against and an
+// id unique to this process. The id is what makes a resend safe: the transport
+// retries the *same bytes*, so a broker that already applied the request can
+// recognise it and replay its answer instead of applying it twice.
+var __sbReqId = 0;
+
 function __sbRpc(op, extra) {
-  const req = { op };
+  const req = { v: 1, id: ++__sbReqId, op };
   if (extra) for (const k in extra) req[k] = extra[k];
   const reply = JSON.parse(__sbCall(JSON.stringify(req)));
   if (reply && reply.ok === false) throw new Error(`sproutboat ${op}: ${reply.error || "failed"}`);
@@ -609,16 +500,19 @@ globalThis.__sbInstallBindings = function (target, bindings) {
     target[name] = {
       put(key, value, options) {
         const o = options || {};
-        return __sbRpc("r2.put", {
-          bucket: name,
-          key: String(key),
-          body: value == null ? "" : String(value),
-          httpMetadata: o.httpMetadata || {},
-          customMetadata: o.customMetadata || {},
-        }).object;
+        // #56 — the body goes out of band where the transport allows it.
+        return __sbR2Put(
+          name,
+          String(key),
+          value == null ? "" : String(value),
+          o.httpMetadata || {},
+          o.customMetadata || {},
+        ).object;
       },
       get(key) {
-        const r = __sbRpc("r2.get", { bucket: name, key: String(key) });
+        // #56 — bytes come back out of band on a transport that supports it, so
+        // an object body is never JSON-escaped into a frame.
+        const r = __sbR2Get(name, String(key));
         return r.found ? __sbR2Object(r.object, r.body == null ? "" : r.body) : null;
       },
       head(key) {
@@ -713,6 +607,34 @@ globalThis.__sbInstallBindings = function (target, bindings) {
     };
   }
 
+  // #48 — worker-to-worker. Same wire shape as outbound fetch, but the broker
+  // resolves the target itself and forwards it internally, so this is not
+  // egress and is not subject to the outbound allowlist.
+  for (let i = 0; i < (bindings.services || []).length; i++) {
+    const binding = bindings.services[i].binding;
+    target[binding] = {
+      fetch(input, init) {
+        const url = __sbIsStr(input) ? input : String((input && input.url) || "https://service/");
+        const opts = init || (!__sbIsStr(input) && input) || {};
+        const headers = [];
+        if (opts.headers) {
+          if (__sbIsFn(opts.headers.forEach)) opts.headers.forEach((v, k) => headers.push([k, v]));
+          else for (const k in opts.headers) headers.push([k, opts.headers[k]]);
+        }
+        const r = __sbRpc("service.fetch", {
+          binding,
+          url,
+          method: opts.method || "GET",
+          headers,
+          body: opts.body == null ? null : String(opts.body),
+        });
+        const respHeaders = new Headers();
+        for (let j = 0; j < (r.headers || []).length; j++) respHeaders.set(r.headers[j][0], r.headers[j][1]);
+        return new Response(r.body == null ? "" : r.body, { status: r.status || 502, headers: respHeaders });
+      },
+    };
+  }
+
   if ((bindings.outbound || []).length > 0) {
     globalThis.fetch = function (input, init) {
       const url = __sbIsStr(input) ? input : String(input.url);
@@ -858,6 +780,19 @@ function __sbDOStorage(cls, id) {
     deleteAll() {
       __sbRpc("do.storage.delete_all", { cls, id });
     },
+    // #125 — alarms. Cloudflare takes a Date or epoch ms; at most one is
+    // pending per object, so setting one replaces any earlier alarm.
+    setAlarm(when) {
+      const at = when instanceof Date ? when.getTime() : Number(when);
+      __sbRpc("do.alarm.set", { cls, id, at: at });
+    },
+    getAlarm() {
+      const r = __sbRpc("do.alarm.get", { cls, id });
+      return r.at == null ? null : r.at;
+    },
+    deleteAlarm() {
+      __sbRpc("do.alarm.delete", { cls, id });
+    },
     list(options) {
       const o = options || {};
       const r = __sbRpc("do.storage.list", {
@@ -898,7 +833,14 @@ function __sbEnv(name) {
 
 function __sbTriggerAuthed(request) {
   const want = __sbEnv("SB_BROKER_TOKEN");
-  if (!want) return true; // no token configured (local/dev)
+  // No token configured means no caller can be trusted to send one, so refuse
+  // rather than wave the request through. Every path that legitimately delivers
+  // a trigger over HTTP sets SB_BROKER_TOKEN — the supervisor per deployment,
+  // `sproutboat dev`, the standalone launcher. The one build that has no token
+  // is the embedded binary (#15), which fires its own triggers in-process and
+  // is also the one most likely to be listening on a public interface: exactly
+  // where "anyone may invoke scheduled()" would be a hole.
+  if (!want) return false;
   return request.headers.get("x-sb-token") === want;
 }
 
@@ -931,50 +873,67 @@ globalThis.__sbEntry = function (handlers, request) {
 
   if (trigger === "queue") {
     if (!__sbIsFn(handlers.queue)) return new Response("no queue handler", { status: 404 });
+    const result = __sbRunQueueBatch(handlers, __sbReadJson(request));
+    return new Response(JSON.stringify(result), { headers: { "content-type": "application/json" } });
+  }
+
+  if (trigger === "alarm") {
     const body = __sbReadJson(request);
-    const acked = [];
-    const retried = [];
-    const raw = body.messages || [];
-    const messages = [];
-    for (let i = 0; i < raw.length; i++) {
-      const m = raw[i];
-      const msg = {
-        id: m.id,
-        timestamp: m.timestamp,
-        attempts: m.attempts || 1,
-        body: __sbTryParse(m.body),
-        ack() {
-          if (acked.indexOf(m.id) === -1) acked.push(m.id);
-        },
-        retry() {
-          if (retried.indexOf(m.id) === -1) retried.push(m.id);
-        },
-      };
-      messages.push(msg);
-    }
-    const batch = {
-      queue: body.queue || "",
-      messages,
-      ackAll() {
-        for (let i = 0; i < messages.length; i++) messages[i].ack();
-      },
-      retryAll() {
-        for (let i = 0; i < messages.length; i++) messages[i].retry();
-      },
-    };
-    handlers.queue(batch);
-    // default: any message neither acked nor retried is treated as acked
-    for (let i = 0; i < messages.length; i++) {
-      if (acked.indexOf(messages[i].id) === -1 && retried.indexOf(messages[i].id) === -1) acked.push(messages[i].id);
-    }
-    return new Response(JSON.stringify({ ack: acked, retry: retried }), {
-      headers: { "content-type": "application/json" },
-    });
+    const inst = __sbGetDOInstance(String(body.cls || ""), String(body.id || ""));
+    if (!__sbIsFn(inst.alarm)) return new Response("no alarm handler", { status: 404 });
+    inst.alarm();
+    return new Response("", { status: 204 });
   }
 
   return new Response("unknown trigger", { status: 400 });
 };
 
+/**
+ * Run one queue batch through the handler and report what it acked.
+ *
+ * Shared so the two ways a batch can arrive agree: over HTTP from the broker
+ * (deployed, and the phase-0 standalone launcher), or straight from the local
+ * timer in an embedded binary that has no broker to be delivered from.
+ */
+function __sbRunQueueBatch(handlers, body) {
+  const acked = [];
+  const retried = [];
+  const raw = body.messages || [];
+  const messages = [];
+  for (let i = 0; i < raw.length; i++) {
+    const m = raw[i];
+    const msg = {
+      id: m.id,
+      timestamp: m.timestamp,
+      attempts: m.attempts || 1,
+      body: __sbTryParse(m.body),
+      ack() {
+        if (acked.indexOf(m.id) === -1) acked.push(m.id);
+      },
+      retry() {
+        if (retried.indexOf(m.id) === -1) retried.push(m.id);
+      },
+    };
+    messages.push(msg);
+  }
+  const batch = {
+    queue: body.queue || "",
+    messages,
+    ackAll() {
+      for (let i = 0; i < messages.length; i++) messages[i].ack();
+    },
+    retryAll() {
+      for (let i = 0; i < messages.length; i++) messages[i].retry();
+    },
+  };
+  handlers.queue(batch);
+  // default: any message neither acked nor retried is treated as acked
+  for (let i = 0; i < messages.length; i++) {
+    if (acked.indexOf(messages[i].id) === -1 && retried.indexOf(messages[i].id) === -1) acked.push(messages[i].id);
+  }
+  return { ack: acked, retry: retried };
+}
+
 function __sbReadJson(request) {
   try {
     return JSON.parse(request.body == null ? "{}" : String(request.body));