Rate Limiting

End-to-end rate limiting: L1 global-IP + L2 auth + L3 handler opt-in.

What it shows

• Handler rateLimit: { per, limit, windowSeconds }
• How L1/L2 from buildServer stack with L3

Source

Feature entry point: src/feature.ts.

Tests

cd samples/recipes/rate-limiting
bun test

---

Source code

The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):

// Rate-Limiting Showcase — minimal feature
//
// Declares one query handler with an L3 rateLimit option so the
// dispatcher gates calls before the handler body runs. The integration
// test pairs this with L1+L2 middleware wired via buildServer's
// `rateLimit` option to prove all three layers stack.

import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
import { z } from "zod";

export function createRateLimitShowcaseFeature(): FeatureDefinition {
  return defineFeature("rl-showcase", (r) => {
    // Per-user budget. Real apps tune `limit` to actual handler cost — a
    // search call against a sharded index might warrant 5/min, a full
    // export 1/min. The bucket is `user:<userId>` (see rate-limit/bucket.ts).
    r.queryHandler(
      "expensive-search",
      z.object({ q: z.string().min(1) }),
      async ({ payload }) => ({ q: payload.q, hits: 0 }),
      {
        access: { roles: ["Admin", "User"] },
        rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
      },
    );
  });
}

📄 On GitHub: samples/recipes/rate-limiting/src/feature.ts