@sproutboat/wire 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @sproutboat/wire
 
+## 0.4.0
+
+### Minor Changes
+
+- Rate Limiting binding (baronunread/sproutboat#69): `env.<NAME>.limit({ key }) ->
+  { success }`.
+  
+  - Config: `ratelimiters: [{ binding, limit, period }]` in `sproutboat.jsonc` —
+    at most `limit` calls per `period` seconds, per key.
+  - A fixed-window counter (`ratelimit` table) on **both** transports: the
+    embedded one for standalone binaries, and the broker (`ratelimit.check` op,
+    in the replay-dedup set) for deployed sprouts. `limit` / `period` travel in
+    the message so the op stays stateless.
+  - `ponytail`: fixed window, so a burst across the boundary can briefly reach
+    ~2x; swap for a two-window weighted count if that matters.
+
+## 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.4.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({
@@ -713,3 +737,18 @@ test("replaying a read is allowed, since it changes nothing", async () => {
   const c = await read();
   expect(a.subarray(4).toString()).toBe(c.subarray(4).toString());
 });
+
+test("ratelimit: fixed window per key, limit/period from the message (#69)", async () => {
+  const b = make({ bindings: { ratelimiters: [{ binding: "API", limit: 3, period: 60 }] } });
+  const hit = (key: string) => b.dispatch({ op: "ratelimit.check", name: "API", key, limit: 3, period: 60 });
+
+  expect((await hit("a")).success).toBe(true); // 1
+  expect((await hit("a")).success).toBe(true); // 2
+  expect((await hit("a")).success).toBe(true); // 3
+  expect((await hit("a")).success).toBe(false); // 4 — over
+  expect((await hit("b")).success).toBe(true); // a different key has its own count
+
+  await expect(b.dispatch({ op: "ratelimit.check", name: "NOPE", key: "x", limit: 1, period: 60 })).rejects.toThrow(
+    "not bound",
+  );
+});

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";
@@ -38,6 +38,9 @@ export type Bindings = {
   /** #48 — worker-to-worker: binding name -> the project it calls. */
   services: Array<{ binding: string; service: string }>;
   crons: string[];
+  /** #69 — rate limiters. Only the names are used here; the message carries
+   *  `limit` / `period` (both come from the same baked config as the handler). */
+  ratelimiters: Array<{ binding: string; limit: number; period: number }>;
   /** Static-asset binding name, or `""` when assets are edge-only. */
   assets: string;
   /**
@@ -181,6 +184,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     do: [],
     services: [],
     crons: [],
+    ratelimiters: [],
     assets: "",
     resources: {},
     ...opts.bindings,
@@ -264,6 +268,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   );
   // Alarm polling reads the earliest due objects across classes.
   db.exec("CREATE INDEX IF NOT EXISTS do_alarm_due ON do_alarm (at)");
+  // #69 — fixed-window rate-limiter counters, per binding name + key.
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS ratelimit (name TEXT NOT NULL, key TEXT NOT NULL, window_start INTEGER NOT NULL, " +
+      "count INTEGER NOT NULL, PRIMARY KEY (name, key))",
+  );
 
   // #74 — one SQLite file per account-level resource id, opened on first use.
   const resourceDbs = new Map<string, Database>();
@@ -326,6 +335,8 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   const requireR2 = bound(bindings.r2, "R2 bucket");
   const requireQueue = bound(bindings.queues, "queue");
   const requireAe = bound(bindings.analytics, "analytics dataset");
+  const rateLimiterNames = bindings.ratelimiters.map((r) => r.binding);
+  const requireRateLimiter = bound(rateLimiterNames, "rate limiter");
   const doClasses = new Set(bindings.do.map((d) => d.className));
   const requireDoClass = (cls: JsonValue | undefined): string => {
     const n = str(cls);
@@ -375,6 +386,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 +592,28 @@ 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 "ratelimit.check": {
+        // #69 — fixed window; limit/period arrive in the message. Same upsert as
+        // the embedded transport so one conformance suite covers both.
+        const name = requireRateLimiter(msg.name);
+        const limit = Math.max(Number(msg.limit) || 1, 1);
+        const period = Math.max(Number(msg.period) || 60, 1);
+        const now = Math.floor(Date.now() / 1000);
+        const windowStart = now - (now % period);
+        const row = db
+          .query<{ count: number }, [string, string, number]>(
+            "INSERT INTO ratelimit (name, key, window_start, count) VALUES (?1, ?2, ?3, 1) " +
+              "ON CONFLICT (name, key) DO UPDATE SET count = CASE WHEN window_start = ?3 THEN count + 1 ELSE 1 END, " +
+              "window_start = ?3 RETURNING count",
+          )
+          .get(name, msg.key == null ? "" : str(msg.key), windowStart);
+        return { ok: true, success: (row?.count ?? 1) <= limit };
+      }
 
       case "r2.put": {
         const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
@@ -864,6 +925,8 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     "d1.query",
     "d1.exec",
     "d1.batch",
+    "d1.backup",
+    "ratelimit.check",
     "r2.put",
     "r2.delete",
     "do.storage.put",