The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 137 lines 4.47 KB
Raw
1 ---
2 title: Rate limiting
3 description: Throttle requests inside a Worker with Cloudflare's Rate Limiting binding — declare the limit on the binding, count arbitrary keys at runtime, handle failures as typed errors.
4 sidebar:
5 order: 12
6 ---
7
8 The Rate Limiting binding gives a Worker a counter it can consult on
9 every request. Pass a key, such as an IP, a user id, or an API token,
10 and get back whether that key is within its budget. There is no backing cloud
11 resource to deploy; the limit configuration lives on the binding
12 itself and ships with the Worker.
13
14 ## Bind a rate limit to a Worker
15
16 `yield*` `Cloudflare.RateLimit(name, props)` in the Worker's Construction
17 phase and provide `RateLimitBinding` as a layer:
18
19 ```typescript
20 // src/worker.ts
21 import * as Cloudflare from "@alchemy.run/cloudflare";
22 import * as Effect from "effect/Effect";
23 import { HttpServerRequest } from "effect/http/HttpServerRequest";
24 import * as HttpServerResponse from "effect/http/HttpServerResponse";
25
26 export default Cloudflare.Worker(
27 "ThrottledWorker",
28 { main: import.meta.url },
29 Effect.gen(function* () {
30 const throttle = yield* Cloudflare.RateLimit("THROTTLE", {
31 namespaceId: 1001,
32 simple: { limit: 10, period: 60 },
33 });
34
35 return {
36 fetch: Effect.gen(function* () {
37 const request = yield* HttpServerRequest;
38 const ip = request.headers["cf-connecting-ip"] ?? "unknown";
39
40 const { success } = yield* throttle
41 .limit({ key: ip })
42 .pipe(Effect.orDie);
43
44 return success
45 ? HttpServerResponse.text("ok")
46 : HttpServerResponse.text("rate limited", { status: 429 });
47 }),
48 };
49 }).pipe(Effect.provide(Cloudflare.Workers.RateLimitBinding)),
50 );
51 ```
52
53 `simple.limit` is the number of requests allowed per `simple.period`
54 seconds. The period must be `10` or `60`. `namespaceId` is a number
55 or string that uniquely identifies this limit configuration within
56 the account; reuse the same id to share one budget across Workers,
57 use distinct ids for independent limits.
58
59 ## Count independent keys
60
61 Every key passed to `limit` gets its own budget. With
62 `limit: 2, period: 10`, two calls for `"alice"` succeed and the third
63 is denied, while `"bob"` still has a full budget:
64
65 ```typescript
66 const a1 = yield* throttle.limit({ key: "alice" }); // { success: true }
67 const a2 = yield* throttle.limit({ key: "alice" }); // { success: true }
68 const a3 = yield* throttle.limit({ key: "alice" }); // { success: false }
69 const b1 = yield* throttle.limit({ key: "bob" }); // { success: true }
70 ```
71
72 Counting is approximate and local to the Cloudflare location serving
73 the request. The binding is built for cheap, fast abuse protection,
74 not globally consistent quotas. For exact global counting, put the
75 counter in a [Durable Object](/cloudflare/compute/durable-objects).
76
77 ## Handle failures as typed errors
78
79 `limit` fails with a typed `RateLimitError` if the runtime call
80 itself blows up (as opposed to the key being over budget, which is
81 the `success: false` case). It lives in the Effect error channel like
82 any other tagged error:
83
84 ```typescript
85 const { success } = yield* throttle.limit({ key }).pipe(
86 // fail open: allow the request if the limiter itself errors
87 Effect.catchTag("RateLimitError", () =>
88 Effect.succeed({ success: true }),
89 ),
90 );
91 ```
92
93 ## Declare the binding as env metadata
94
95 Workers whose `main` module exports a plain async `fetch` handler
96 declare the limit on `env` instead. `InferEnv` types it as
97 Cloudflare's native `RateLimit` binding:
98
99 ```typescript
100 // alchemy.run.ts
101 export const Worker = Cloudflare.Worker("Worker", {
102 main: "./src/worker.ts",
103 env: {
104 THROTTLE: Cloudflare.RateLimit("THROTTLE", {
105 namespaceId: 1001,
106 simple: { limit: 10, period: 60 },
107 }),
108 },
109 });
110
111 export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
112 ```
113
114 ```typescript
115 // src/worker.ts
116 import type { WorkerEnv } from "../alchemy.run.ts";
117
118 export default {
119 async fetch(req: Request, env: WorkerEnv) {
120 const { success } = await env.THROTTLE.limit({
121 key: req.headers.get("cf-connecting-ip") ?? "unknown",
122 });
123 return new Response(success ? "ok" : "rate limited", {
124 status: success ? 200 : 429,
125 });
126 },
127 };
128 ```
129
130 ## Where next
131
132 - [Workers](/cloudflare/compute/workers) — the two-phase Worker model
133 the binding lives inside.
134 - [Durable Objects](/cloudflare/compute/durable-objects) — exact,
135 globally consistent counters when approximate isn't enough.
136 - [RateLimit API reference](/providers/cloudflare/workers/ratelimit) —
137 props and client types.