@sproutboat/wire 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @sproutboat/wire
 
+## 0.3.0
+
+### Minor Changes
+
+- Standalone runtime: client IP, D1 online backup, and a prepared-statement cache.
+  
+  - `request.cf.clientIp` is populated from the connection's remote address
+    (`x-sb-remote-addr`, appended by the server and stripped from client input),
+    with `SB_TRUSTED_PROXIES` resolving `X-Forwarded-For` behind a reverse proxy.
+    IPv4-mapped IPv6 peers are folded to dotted form. (baronunread/sproutboat#163)
+  - `env.<D1>.backup(name?)` — a Sproutboat extension: an online, integrity-checked
+    single-file snapshot via `VACUUM INTO`, on both the embedded and broker
+    transports. New `d1.backup` op. (baronunread/sproutboat#164)
+  - The embedded transport caches prepared statements per database (FIFO, 32/db)
+    instead of recompiling the SQL on every binding op. (baronunread/sproutboat#155)
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,15 +1,30 @@
 # `@sproutboat/wire`
 
-Single source of truth for the broker frame protocol: op dispatch, storage
-tables, queue and alarm delivery, plus the JSON validation utilities the
-protocol is built on.
-
-Current sources, moved verbatim: `sproutboat-cli/src/broker.ts`,
-`broker.test.ts`, `json.ts`. Contract tests move with the code; the CLI's
-`CONTRACTS.md` broker-wire and storage sections keep generating from here.
-
-Note: `broker.ts` imports `@sproutboat/assets`, deliberately declared
-nowhere here. Bun resolves transitive `file:` links from the consumer root,
-not the declaring package, so every consumer links all `@sproutboat/*`
-packages it needs at its own root. Add a real version range here at first
-npm publish.
+Broker frame protocol and the JSON validation utilities it is built on.
+Single source of truth shared by the CLI dev broker and the platform's
+edge and supervisor.
+
+```sh
+bun add @sproutboat/wire
+```
+
+```ts
+import { createBroker } from "@sproutboat/wire";
+import { parseJsonValue } from "@sproutboat/wire";
+```
+
+## API
+
+- `createBroker(options)` opens a binding broker over a resource file:
+  KV, D1, R2, queues, Durable Object storage and alarms, Analytics Engine
+  points, secrets, outbound fetch. Frame envelope, both directions:
+  `[u32 LE length][payload]`.
+- Frame helpers: `frameOf`, `encodeFrame`, `encodeV1`, `FRAME_V1`,
+  `cronMatches`, plus the `Broker`, `BrokerOptions`, `BrokerServer`,
+  `FetchLike` and `Frame` types.
+- JSON boundary parsing: `parseJsonValue`, `jsonObject`, guards
+  (`isString`, `isBoolean`, `isSafeInteger`), `JsonValue` and `JsonObject`
+  types. Parse at the I/O boundary, then narrow; nothing downstream takes
+  an unparsed value.
+
+See `src/broker.test.ts` for the protocol contract in executable form.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/wire",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.ts",

package/src/broker.test.ts

@@ -105,6 +105,30 @@ test("D1: query / run / batch on a bound database, isolated per name", async ()
   await expect(b.dispatch({ op: "d1.query", db: "NOPE", sql: "SELECT 1", params: [] })).rejects.toThrow("not bound");
 });
 
+test("D1: backup writes an integrity-checked snapshot, replayed from cache", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "sb-broker-backup-"));
+  try {
+    const b = make({ db: join(dir, "store.sqlite"), bindings: { d1: ["DB"] } });
+    await b.dispatch({ op: "d1.exec", db: "DB", sql: "CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)" });
+    await b.dispatch({ op: "d1.query", db: "DB", sql: "INSERT INTO t (name) VALUES (?)", params: ["ada"] });
+
+    const bk = await b.dispatch({ op: "d1.backup", db: "DB", name: "snap.sqlite" });
+    expect(bk.ok).toBe(true);
+    expect(String(bk.path).endsWith(join("backups", "snap.sqlite"))).toBe(true);
+    expect(Number(bk.bytes)).toBeGreaterThan(0);
+    expect(existsSync(String(bk.path))).toBe(true);
+
+    // the snapshot is a real, readable database with the row in it
+    const snap = new Database(String(bk.path), { readonly: true });
+    expect(snap.query("SELECT name FROM t").all()).toEqual([{ name: "ada" }]);
+    snap.close();
+
+    await expect(b.dispatch({ op: "d1.backup", db: "NOPE" })).rejects.toThrow("not bound");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("R2: put / get / head / list / delete on a bound bucket", async () => {
   const b = make({ bindings: { r2: ["ASSETS"] } });
   const put = await b.dispatch({

package/src/broker.ts

@@ -19,7 +19,7 @@
  */
 import { Database, type Statement } from "bun:sqlite";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { dirname, join, normalize, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { resolveAssetKey, type AssetManifest } from "@sproutboat/assets";
@@ -375,6 +375,34 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     };
   };
 
+  // #164 — an online, integrity-checked snapshot of a D1 database via
+  // VACUUM INTO. Standalone (transport-embedded) is the primary target; the
+  // broker carries it too so one conformance suite covers both backends.
+  const d1Backup = (conn: Database, dbName: string, name: string) => {
+    const source = conn.filename;
+    if (!source || source === ":memory:") throw new Error("d1 backup needs a file-backed database");
+    // A caller-supplied name must be a plain basename; else use the default.
+    const file = /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)
+      ? name
+      : `${dbName}-${new Date().toISOString().replace(/[:.]/g, "-")}.sqlite`;
+    const dir = join(dirname(dirname(resolve(source))), "backups");
+    mkdirSync(dir, { recursive: true });
+    const dest = join(dir, file);
+    if (existsSync(dest)) rmSync(dest); // VACUUM INTO refuses an existing target
+    conn.run("VACUUM INTO ?", [dest]);
+    const copy = new Database(dest, { readonly: true });
+    try {
+      const row = copy.query<{ integrity_check: string }, []>("PRAGMA integrity_check").get();
+      if (row?.integrity_check !== "ok") {
+        rmSync(dest, { force: true });
+        throw new Error("integrity check failed on the backup");
+      }
+    } finally {
+      copy.close();
+    }
+    return { path: dest, bytes: statSync(dest).size };
+  };
+
   /** An object body as bytes, whichever storage class it came back in. */
   const r2Bytes = (body: string | Uint8Array): Uint8Array =>
     body instanceof Uint8Array ? body : new TextEncoder().encode(body);
@@ -553,6 +581,10 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         conn.exec(str(msg.sql));
         return { ok: true };
       }
+      case "d1.backup": {
+        const name = requireD1(msg.db);
+        return { ok: true, ...d1Backup(d1(name), name, msg.name == null ? "" : str(msg.name)) };
+      }
 
       case "r2.put": {
         const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
@@ -864,6 +896,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     "d1.query",
     "d1.exec",
     "d1.batch",
+    "d1.backup",
     "r2.put",
     "r2.delete",
     "do.storage.put",