sproutboat 0.50.0 → 0.51.0

package/CHANGELOG.md

@@ -10,6 +10,15 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.51.0] - 2026-11-03
+
+Built on `@sproutboat/runtime` 0.42.0, `@sproutboat/toolchain` 0.23.0 and `@sproutboat/wire` 0.22.0. The change below starts at a new compatibility date; earlier dates answer as before.
+
+### Added
+
+- **`connect()` from `cloudflare:sockets` from `2026-11-17`**: TCP sockets with `readable`, `writable`, `opened`, `closed`, `close()` and `startTls()`, on a standalone binary, under `sproutboat dev` and on a platform deploy. The same unmodified Postgres (`pg`, `postgres`) and Redis driver code that runs on workerd runs here, with no differences from workerd in the driver suites. Outbound policy is the one `fetch()` uses. Before the date, importing `cloudflare:sockets` fails the build with `cloudflare:sockets needs compatibility_date 2026-11-17 or later`.
+- **From the same date a driver bundles as it does for workerd**: the `workerd` export condition (`pg-cloudflare`, `postgres/cf`), a bundled `Buffer`, `process` and `global`, and shims for `net`, `tls`, `dns`, `fs` and `crypto` so the Node branch of a driver names `cloudflare:sockets` instead of failing the build. A named function expression that shadows a global builtin function is renamed, which sproutd admission needs.
+
 ## [0.50.0] - 2026-11-02
 
 Built on `@sproutboat/runtime` 0.41.0, `@sproutboat/toolchain` 0.22.0 and `@sproutboat/wire` 0.21.4. Each change below that an existing app could observe starts at a new compatibility date; earlier dates answer as before.

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.50.0
+**Package:** `sproutboat` 0.51.0
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -64,9 +64,9 @@
     "@sproutboat/artifact": "^0.3.0",
     "@sproutboat/assets": "^0.3.0",
     "@sproutboat/config": "^0.6.0",
-    "@sproutboat/runtime": "^0.41.0",
-    "@sproutboat/toolchain": "^0.22.0",
-    "@sproutboat/wire": "^0.21.4"
+    "@sproutboat/runtime": "^0.42.0",
+    "@sproutboat/toolchain": "^0.23.0",
+    "@sproutboat/wire": "^0.22.0"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.85.0",
@@ -78,10 +78,10 @@
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.50.0",
-    "@sproutboat/cli-darwin-x64": "0.50.0",
-    "@sproutboat/cli-linux-arm64": "0.50.0",
-    "@sproutboat/cli-linux-x64": "0.50.0"
+    "@sproutboat/cli-darwin-arm64": "0.51.0",
+    "@sproutboat/cli-darwin-x64": "0.51.0",
+    "@sproutboat/cli-linux-arm64": "0.51.0",
+    "@sproutboat/cli-linux-x64": "0.51.0"
   },
   "engines": {
     "node": ">=18"

package/src/bundle.ts

@@ -12,7 +12,8 @@
  * reaching for a Node API fails exactly as user code would.
  */
 import { relative } from "node:path";
-import { NODE_SHIMS } from "./node-shims";
+import { SOCKETS_DATE } from "@sproutboat/runtime";
+import { NODE_SHIMS, SOCKET_NODE_SHIMS } from "./node-shims";
 
 export type BundleResult = {
   /** One self-contained ESM module: what gets validated, hashed, and compiled. */
@@ -54,6 +55,86 @@ const nodeShimsPlugin: import("bun").BunPlugin = {
   },
 };
 
+/**
+ * Porffor lists the global builtin functions on the global object of every unit, and a function
+ * named like one of them (postgres: `export const escapeIdentifier = function escape(str) {}`)
+ * drops the entry from that unit alone, so a sproutd app that does it no longer matches the
+ * runtime's common code and is rejected at admission. A named function expression's name is only
+ * visible inside itself, so renaming it is safe unless the body calls itself by that name.
+ */
+const SHADOWED_BUILTIN_FUNCTIONS =
+  /([=(:,?&|]\s*|\breturn\s+)function\s+(escape|unescape|eval|isNaN|isFinite|parseInt|parseFloat|encodeURI|encodeURIComponent|decodeURI|decodeURIComponent)\s*\(/g;
+
+/** What a driver reads off `process`: an empty environment and a microtask for nextTick. */
+const PROCESS_STUB = `
+const env = {};
+function nextTick(fn, ...args) { Promise.resolve().then(() => fn(...args)); }
+const process = { env, platform: "linux", arch: "wasm32", version: "v20.0.0", versions: {}, argv: [], browser: true, nextTick, emitWarning() {}, cwd() { return "/"; }, stderr: { write() {} }, stdout: { write() {} }, on() {}, off() {}, once() {}, emit() {} };
+export default process;
+`;
+
+/**
+ * Node libraries use `Buffer` and `process` as free globals. Bun's browser target does not
+ * inject them for a CommonJS file, so a dependency that never imports Buffer would throw a
+ * ReferenceError at runtime. This gives every dependency file that uses one a local binding to the
+ * bundled implementation (the `buffer` package, which Porffor compiles; see the toolchain notes on
+ * typed array method dispatch). Applied only to node_modules, never to the handler's own code.
+ */
+const nodeGlobalsPlugin: import("bun").BunPlugin = {
+  name: "sproutboat-node-globals",
+  setup(build) {
+    build.onResolve({ filter: /^sb-node-process$/ }, () => ({ path: "sb-node-process", namespace: "sb-node-global" }));
+    build.onLoad({ filter: /.*/, namespace: "sb-node-global" }, () => ({ contents: PROCESS_STUB, loader: "js" }));
+    build.onLoad({ filter: /node_modules\/.*\.(?:c?js|mjs)$/ }, async (args) => {
+      const original = await Bun.file(args.path).text();
+      const text = original.replace(
+        SHADOWED_BUILTIN_FUNCTIONS,
+        (_m, lead: string, name: string) => `${lead}function ${name}_sb(`,
+      );
+      const usesBuffer =
+        /(?:^|[^.\w$])Buffer\s*[.(]/m.test(text) &&
+        !/\b(?:import|require)\b[^;\n]*\bBuffer\b/.test(text) &&
+        !/(?:const|let|var)\s+\{?\s*Buffer\b/.test(text);
+      const usesProcess =
+        /(?:^|[^.\w$])process\s*\./m.test(text) &&
+        !/\b(?:import|require)\b[^;\n]*\bprocess\b/.test(text) &&
+        !/(?:const|let|var|function)\s+\{?\s*process\b/.test(text);
+      const usesGlobal =
+        /(?:^|[^.\w$])global\s*\./m.test(text) && !/(?:const|let|var|function)\s+\{?\s*global\b/.test(text);
+      if (!usesBuffer && !usesProcess && !usesGlobal)
+        return text === original ? undefined : { contents: text, loader: "js" };
+      const esm = /^\s*(?:import|export)\s/m.test(text);
+      let prefix = "";
+      if (usesBuffer) prefix += esm ? `import { Buffer } from "buffer";\n` : `var { Buffer } = require("buffer");\n`;
+      if (usesProcess)
+        prefix += esm
+          ? `import process from "sb-node-process";\n`
+          : `var process = require("sb-node-process").default;\n`;
+      if (usesGlobal) prefix += "var global = globalThis;\n";
+      return { contents: prefix + text, loader: "js" };
+    });
+  },
+};
+
+const socketShimSpecifiers = new RegExp(
+  `^(${Object.keys(SOCKET_NODE_SHIMS)
+    .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|")})$`,
+);
+
+/** The Node built-ins a driver names, replaced from the sockets date: see SOCKET_NODE_SHIMS. */
+const socketShimsPlugin: import("bun").BunPlugin = {
+  name: "sproutboat-socket-shims",
+  setup(build) {
+    build.onResolve({ filter: socketShimSpecifiers }, (args) => ({ path: args.path, namespace: "sb-socket-shim" }));
+    build.onLoad({ filter: /.*/, namespace: "sb-socket-shim" }, (args) => ({
+      // SAFETY: onResolve above only routes specifiers built from SOCKET_NODE_SHIMS's own keys here.
+      contents: (SOCKET_NODE_SHIMS as Record<string, string>)[args.path],
+      loader: "js",
+    }));
+  },
+};
+
 /** Bun reports resolution failures on `AggregateError.errors`; its own message is just "Bundle failed". */
 function bundleDetail(cause: unknown): string {
   const errors = cause instanceof AggregateError ? cause.errors : [];
@@ -63,7 +144,15 @@ function bundleDetail(cause: unknown): string {
 }
 
 /** Bundle `entryPath` into a single module, resolving imports from `projectDir`. */
-export async function bundleHandler(entryPath: string, projectDir: string): Promise<BundleResult> {
+export async function bundleHandler(
+  entryPath: string,
+  projectDir: string,
+  options: { compatibilityDate?: string } = {},
+): Promise<BundleResult> {
+  // From the sockets date a driver bundles as it does for workerd: its "workerd" export condition,
+  // Node's free `Buffer`/`process`/`global` bound to bundled code, and net/tls/dns/fs/crypto shims
+  // that name cloudflare:sockets when the driver takes its Node path.
+  const sockets = options.compatibilityDate !== undefined && options.compatibilityDate >= SOCKETS_DATE;
   let built: Awaited<ReturnType<typeof Bun.build>>;
   try {
     built = await Bun.build({
@@ -78,10 +167,11 @@ export async function bundleHandler(entryPath: string, projectDir: string): Prom
       minify: false,
       splitting: false,
       sourcemap: "none",
-      plugins: [nodeShimsPlugin],
+      conditions: sockets ? ["workerd", "worker"] : undefined,
+      plugins: sockets ? [nodeShimsPlugin, socketShimsPlugin, nodeGlobalsPlugin] : [nodeShimsPlugin],
       // WorkerEntrypoint, DurableObject, RpcTarget and env are runtime globals; the
       // compiler turns this import into them, so it stays in the bundle as written.
-      external: ["cloudflare:workers"],
+      external: ["cloudflare:workers", "cloudflare:sockets"],
     });
   } catch (cause) {
     // An unresolvable specifier arrives as an AggregateError whose `errors`

package/src/main.ts

@@ -234,7 +234,9 @@ async function readProject(directory = process.cwd()) {
   // smuggle in a Node API the handler is not allowed to touch.
   let bundle: BundleResult;
   try {
-    bundle = await bundleHandler(sourcePath, project.directory);
+    bundle = await bundleHandler(sourcePath, project.directory, {
+      compatibilityDate: project.config.compatibility_date,
+    });
   } catch (cause) {
     fail(cause instanceof BundleError ? cause.message : String(cause));
   }

package/src/node-shims.ts

@@ -386,3 +386,85 @@ export const NODE_SHIMS = {
   "node:querystring": NODE_QUERYSTRING_SHIM,
   "node:url": NODE_URL_SHIM,
 } satisfies Record<string, string>;
+
+// From the sockets date (2026-11-17), for drivers that carry a Node code path next to their Workers one.
+/**
+ * node:net, node:tls, node:dns, node:fs and node:util/types for drivers that carry a Node code path
+ * next to their Workers one (pg, mysql2). The Workers path never calls them: every function throws
+ * a message that names cloudflare:sockets, so a driver that does take the Node path says why.
+ */
+const unavailable = (what: string) =>
+  `function unavailable() { throw new Error("${what} is not available in a compiled handler; use cloudflare:sockets (connect())"); }\n`;
+const NODE_NET_SHIM =
+  unavailable("the net module") +
+  `class Socket { constructor() { unavailable(); } }
+const ipv4 = /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])$/;
+function isIP(x) { return ipv4.test(String(x)) ? 4 : String(x).indexOf(":") >= 0 && /^[0-9a-fA-F:.]+$/.test(String(x)) ? 6 : 0; }
+function connect() { unavailable(); }
+export { Socket, isIP, connect };
+export default { Socket, isIP, connect, createConnection: connect };
+`;
+const NODE_TLS_SHIM =
+  unavailable("the tls module") +
+  `function connect() { unavailable(); }
+export { connect };
+export default { connect };
+`;
+const NODE_DNS_SHIM =
+  unavailable("the dns module") +
+  `function lookup() { unavailable(); }
+export { lookup };
+export default { lookup, promises: { lookup } };
+`;
+const NODE_FS_SHIM =
+  unavailable("the fs module") +
+  `function readFileSync() { unavailable(); }
+function existsSync() { return false; }
+function statSync() { unavailable(); }
+function createReadStream() { unavailable(); }
+export { readFileSync, existsSync, statSync, createReadStream };
+export default { readFileSync, existsSync, statSync, createReadStream };
+`;
+const NODE_UTIL_TYPES_SHIM = `
+const isDate = (v) => v instanceof Date;
+const isTypedArray = (v) => ArrayBuffer.isView(v) && !(v instanceof DataView);
+const isUint8Array = (v) => v instanceof Uint8Array;
+const isArrayBuffer = (v) => v instanceof ArrayBuffer;
+const isPromise = (v) => v instanceof Promise;
+const isRegExp = (v) => v instanceof RegExp;
+export { isDate, isTypedArray, isUint8Array, isArrayBuffer, isPromise, isRegExp };
+export default { isDate, isTypedArray, isUint8Array, isArrayBuffer, isPromise, isRegExp };
+`;
+
+/**
+ * node:crypto as a Workers handler has it: the Web Crypto global, not the Node API. pg asks for
+ * `crypto.webcrypto || globalThis.crypto` and for createHash("md5") inside a try, so a createHash
+ * that throws sends it to crypto.subtle. Bun's default polyfill (crypto-browserify) is 20k lines,
+ * and its elliptic-curve code does not compile under Porffor.
+ */
+const NODE_CRYPTO_SHIM = `
+function unavailable() { throw new Error("this crypto function is not available; use crypto.subtle"); }
+const webcrypto = globalThis.crypto;
+function randomBytes(n) { return webcrypto.getRandomValues(new Uint8Array(n)); }
+function randomUUID() { return webcrypto.randomUUID(); }
+function createHash() { unavailable(); }
+function createHmac() { unavailable(); }
+export { webcrypto, randomBytes, randomUUID, createHash, createHmac };
+export default { webcrypto, randomBytes, randomUUID, createHash, createHmac, getRandomValues: (a) => webcrypto.getRandomValues(a), subtle: webcrypto.subtle };
+`;
+
+/** Replaces Bun's browser polyfills, in a bundle at the sockets date or later (see bundle.ts). */
+export const SOCKET_NODE_SHIMS = {
+  "node:crypto": NODE_CRYPTO_SHIM,
+  crypto: NODE_CRYPTO_SHIM,
+  "node:net": NODE_NET_SHIM,
+  net: NODE_NET_SHIM,
+  "node:tls": NODE_TLS_SHIM,
+  tls: NODE_TLS_SHIM,
+  "node:dns": NODE_DNS_SHIM,
+  dns: NODE_DNS_SHIM,
+  "node:fs": NODE_FS_SHIM,
+  fs: NODE_FS_SHIM,
+  "node:util/types": NODE_UTIL_TYPES_SHIM,
+  "util/types": NODE_UTIL_TYPES_SHIM,
+} satisfies Record<string, string>;