@sproutboat/wire 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @sproutboat/wire
 
+## 0.5.0
+
+### Minor Changes
+
+- Rate limiter (baronunread/sproutboat#69): `env.<NAME>.limit({ key })` now
+  returns `{ success, resetAt }`. `resetAt` is epoch milliseconds for when the
+  fixed window rolls and the counter clears, returned on every call (hit or
+  miss), so a rejection can carry an accurate `Retry-After`:
+  `Math.ceil((resetAt - Date.now()) / 1000)`. The `ratelimit.check` op already
+  had `windowStart` and `period` in hand; it just stopped discarding them.
+  Additive: existing callers reading only `success` are unaffected.
+
+## 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

package/package.json

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

package/src/broker.test.ts

@@ -737,3 +737,22 @@ 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
+  const over = await hit("a"); // 4 — over
+  expect(over.success).toBe(false);
+  // resetAt is epoch ms at the window edge, so it drives a Retry-After.
+  expect(over.resetAt).toBeGreaterThan(Date.now());
+  expect(over.resetAt).toBeLessThanOrEqual(Date.now() + 60_000);
+  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

@@ -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);
@@ -586,6 +597,24 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         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, resetAt: (windowStart + period) * 1000 };
+      }
+
       case "r2.put": {
         const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
         const body = str(msg.body);
@@ -897,6 +926,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     "d1.exec",
     "d1.batch",
     "d1.backup",
+    "ratelimit.check",
     "r2.put",
     "r2.delete",
     "do.storage.put",