wrangler: move ratelimit binding to stable

Author: qjex

fixtures/ratelimit-app/src/index.js

@@ -5,6 +5,14 @@ export default {
 		console.log("request log");
 
 		const { pathname } = new URL(request.url);
+
+		if (pathname.startsWith('/unsafe')) {
+			const { success } = await env.UNSAFE_RATE_LIMITER.limit({ key: pathname });
+			if (!success) {
+				return new Response('unsafe: Slow down', { status: 429 });
+			}
+			return new Response("unsafe: Success");
+		}
 		const { success } = await env.RATE_LIMITER.limit({ key: pathname });
 		if (!success) {
 			return new Response(`Slow down`, {

fixtures/ratelimit-app/tests/index.test.ts

@@ -4,7 +4,7 @@ import { unstable_startWorker } from "wrangler";
 
 const basePath = resolve(__dirname, "..");
 
-describe("'wrangler dev' correctly renders pages", () => {
+describe("Rate limiting bindings", () => {
 	let worker: Awaited<ReturnType<typeof unstable_startWorker>>;
 
 	beforeAll(async () => {
@@ -26,8 +26,27 @@ describe("'wrangler dev' correctly renders pages", () => {
 		content = await response.text();
 		expect(content).toEqual("Success");
 
+		response = await worker.fetch(`http://example.com`);
+		content = await response.text();
+		expect(content).toEqual("Success");
+
+
 		response = await worker.fetch(`http://example.com`);
 		content = await response.text();
 		expect(content).toEqual("Slow down");
 	});
+
+	it("ratelimit unsafe binding is defined ", async ({ expect }) => {
+		let response = await worker.fetch(`http://example.com/unsafe`);
+		let content = await response.text();
+		expect(content).toEqual("unsafe: Success");
+
+		response = await worker.fetch(`http://example.com/unsafe`);
+		content = await response.text();
+		expect(content).toEqual("unsafe: Success");
+
+		response = await worker.fetch(`http://example.com/unsafe`);
+		content = await response.text();
+		expect(content).toEqual("unsafe: Slow down");
+	});
 });

fixtures/ratelimit-app/wrangler.jsonc

@@ -2,10 +2,20 @@
 	"name": "ratelimit-app",
 	"compatibility_date": "2024-02-23",
 	"main": "src/index.js",
+	"ratelimits": [
+		{
+			"name": "RATE_LIMITER",
+			"namespace_id": "2001",
+			"simple": {
+				"limit": 3,
+				"period": 60
+			}
+		}
+	],
 	"unsafe": {
 		"bindings": [
 			{
-				"name": "RATE_LIMITER",
+				"name": "UNSAFE_RATE_LIMITER",
 				"type": "ratelimit",
 				"namespace_id": "1001",
 				"simple": {

packages/wrangler/src/__tests__/config/configuration.test.ts

@@ -105,6 +105,7 @@ describe("normalizeAndValidateConfig()", () => {
 			r2_buckets: [],
 			secrets_store_secrets: [],
 			unsafe_hello_world: [],
+			ratelimits: [],
 			services: [],
 			analytics_engine_datasets: [],
 			route: undefined,
@@ -4064,6 +4065,121 @@ describe("normalizeAndValidateConfig()", () => {
 			});
 		});
 
+		describe("[ratelimit]", () => {
+			it("should error if ratelimit is an object", () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					// @ts-expect-error purposely using an invalid value
+					{ ratelimits: {} },
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasWarnings()).toBe(false);
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+					"Processing wrangler configuration:
+					  - The field \\"ratelimits\\" should be an array but got {}."
+				`);
+			});
+
+			it("should error if ratelimit is null", () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					// @ts-expect-error purposely using an invalid value
+					{ ratelimits: null },
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasWarnings()).toBe(false);
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+					"Processing wrangler configuration:
+					  - The field \\"ratelimits\\" should be an array but got null."
+				`);
+			});
+
+			it("should accept valid bindings", () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{
+						ratelimits: [
+							{
+								name: "RATE_LIMITER",
+								namespace_id: "1001",
+								simple: {
+									limit: 5,
+									period: 60,
+								},
+							},
+						],
+					},
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasErrors()).toBe(false);
+			});
+
+			it("should error if ratelimit bindings are not valid", () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{
+						ratelimits: [
+							// @ts-expect-error Test if empty object is caught
+							{},
+							// @ts-expect-error Test if simple is missing
+							{
+								name: "VALID",
+								namespace_id: "1001",
+							},
+							{
+								// @ts-expect-error Test if name is not a string
+								name: null,
+								// @ts-expect-error Test if namespace_id is not a string
+								namespace_id: 123,
+								simple: {
+									// @ts-expect-error Test if limit is not a number
+									limit: "not a number",
+									// @ts-expect-error Test if period is invalid
+									period: 90,
+								},
+								invalid: true,
+							},
+							{
+								name: "MISSING_PERIOD",
+								namespace_id: "1002",
+								// @ts-expect-error Test if period is missing
+								simple: {
+									limit: 10,
+								},
+							},
+						],
+					},
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasWarnings()).toBe(true);
+				expect(diagnostics.renderWarnings()).toMatchInlineSnapshot(`
+					"Processing wrangler configuration:
+					  - Unexpected fields found in ratelimits[2] field: \\"invalid\\""
+				`);
+				expect(diagnostics.hasErrors()).toBe(true);
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+					"Processing wrangler configuration:
+					  - \\"ratelimits[0]\\" bindings must have a string \\"name\\" field but got {}.
+					  - \\"ratelimits[0]\\" bindings must have a string \\"namespace_id\\" field but got {}.
+					  - \\"ratelimits[0]\\" bindings must have a \\"simple\\" configuration object but got {}.
+					  - \\"ratelimits[1]\\" bindings must have a \\"simple\\" configuration object but got {\\"name\\":\\"VALID\\",\\"namespace_id\\":\\"1001\\"}.
+					  - \\"ratelimits[2]\\" bindings must have a string \\"name\\" field but got {\\"name\\":null,\\"namespace_id\\":123,\\"simple\\":{\\"limit\\":\\"not a number\\",\\"period\\":90},\\"invalid\\":true}.
+					  - \\"ratelimits[2]\\" bindings must have a string \\"namespace_id\\" field but got {\\"name\\":null,\\"namespace_id\\":123,\\"simple\\":{\\"limit\\":\\"not a number\\",\\"period\\":90},\\"invalid\\":true}.
+					  - \\"ratelimits[2]\\" bindings \\"simple.limit\\" must be a number but got {\\"limit\\":\\"not a number\\",\\"period\\":90}.
+					  - \\"ratelimits[2]\\" bindings \\"simple.period\\" must be either 10 or 60 but got 90.
+					  - \\"ratelimits[3]\\" bindings \\"simple.period\\" is required and must be a number but got {\\"limit\\":10}."
+				`);
+			});
+		});
+
 		describe("[unsafe.bindings]", () => {
 			it("should error if unsafe is an array", () => {
 				const { diagnostics } = normalizeAndValidateConfig(

packages/wrangler/src/__tests__/type-generation.test.ts

@@ -237,6 +237,16 @@ const bindingsConfigMock: Omit<
 		binding: "ASSETS_BINDING",
 		directory: "/assets",
 	},
+	ratelimits: [
+		{
+			name: "RATE_LIMITER",
+			namespace_id: "1001",
+			simple: {
+				limit: 5,
+				period: 60,
+			},
+		},
+	],
 };
 
 describe("generate types", () => {
@@ -449,6 +459,7 @@ describe("generate types", () => {
 					D1_TESTING_SOMETHING: D1Database;
 					SECRET: SecretsStoreSecret;
 					HELLO_WORLD: HelloWorldBinding;
+					RATE_LIMITER: RateLimit;
 					SERVICE_BINDING: Fetcher /* service_name */;
 					OTHER_SERVICE_BINDING: Service /* entrypoint FakeEntrypoint from service_name_2 */;
 					OTHER_SERVICE_BINDING_ENTRYPOINT: Service /* entrypoint RealEntrypoint from service_name_2 */;
@@ -543,6 +554,7 @@ describe("generate types", () => {
 					D1_TESTING_SOMETHING: D1Database;
 					SECRET: SecretsStoreSecret;
 					HELLO_WORLD: HelloWorldBinding;
+					RATE_LIMITER: RateLimit;
 					SERVICE_BINDING: Fetcher /* service_name */;
 					OTHER_SERVICE_BINDING: Service /* entrypoint FakeEntrypoint from service_name_2 */;
 					OTHER_SERVICE_BINDING_ENTRYPOINT: Service /* entrypoint RealEntrypoint from service_name_2 */;
@@ -701,6 +713,7 @@ describe("generate types", () => {
 					D1_TESTING_SOMETHING: D1Database;
 					SECRET: SecretsStoreSecret;
 					HELLO_WORLD: HelloWorldBinding;
+					RATE_LIMITER: RateLimit;
 					SERVICE_BINDING: Service<typeof import(\\"../b/index\\").default>;
 					OTHER_SERVICE_BINDING: Service /* entrypoint FakeEntrypoint from service_name_2 */;
 					OTHER_SERVICE_BINDING_ENTRYPOINT: Service<typeof import(\\"../c/index\\").RealEntrypoint>;

packages/wrangler/src/api/startDevWorker/types.ts

@@ -24,6 +24,7 @@ import type {
 	CfPipeline,
 	CfQueue,
 	CfR2Bucket,
+	CfRateLimit,
 	CfScriptFormat,
 	CfSecretsStoreSecrets,
 	CfSendEmailBindings,
@@ -302,6 +303,7 @@ export type Binding =
 	| ({ type: "secrets_store_secret" } & BindingOmit<CfSecretsStoreSecrets>)
 	| ({ type: "logfwdr" } & NameOmit<CfLogfwdrBinding>)
 	| ({ type: "unsafe_hello_world" } & BindingOmit<CfHelloWorld>)
+	| ({ type: "ratelimit" } & NameOmit<CfRateLimit>)
 	| { type: `unsafe_${string}` }
 	| { type: "assets" };
 

packages/wrangler/src/api/startDevWorker/utils.ts

@@ -269,6 +269,12 @@ export function convertCfWorkerInitBindingsToBindings(
 				}
 				break;
 			}
+			case "ratelimits": {
+				for (const { name, ...x } of info) {
+					output[name] = { type: "ratelimit", ...x };
+				}
+				break;
+			}
 			default: {
 				assertNever(type);
 			}
@@ -312,6 +318,7 @@ export async function convertBindingsToCfWorkerInitBindings(
 		assets: undefined,
 		pipelines: undefined,
 		unsafe_hello_world: undefined,
+		ratelimits: undefined,
 	};
 
 	const fetchers: Record<string, ServiceFetch> = {};
@@ -401,6 +408,9 @@ export async function convertBindingsToCfWorkerInitBindings(
 		} else if (binding.type === "unsafe_hello_world") {
 			bindings.unsafe_hello_world ??= [];
 			bindings.unsafe_hello_world.push({ ...binding, binding: name });
+		} else if (binding.type === "ratelimit") {
+			bindings.ratelimits ??= [];
+			bindings.ratelimits.push({ ...binding, name: name });
 		} else if (isUnsafeBindingType(binding.type)) {
 			bindings.unsafe ??= {
 				bindings: [],

packages/wrangler/src/config/config.ts

@@ -326,6 +326,7 @@ export const defaultWranglerConfig: Config = {
 	images: undefined,
 	version_metadata: undefined,
 	unsafe_hello_world: [],
+	ratelimits: [],
 
 	/*====================================================*/
 	/*           Fields supported by Workers only         */

packages/wrangler/src/config/environment.ts

@@ -1119,6 +1119,29 @@ export interface EnvironmentNonInheritable {
 		/** Whether the timer is enabled */
 		enable_timer?: boolean;
 	}[];
+
+	/**
+	 * Specifies rate limit bindings that are bound to this Worker environment.
+	 *
+	 * NOTE: This field is not automatically inherited from the top level environment,
+	 * and so must be specified in every named environment.
+	 *
+	 * @default []
+	 * @nonInheritable
+	 */
+	ratelimits: {
+		/** The binding name used to refer to the rate limiter in the Worker. */
+		name: string;
+		/** The namespace ID for this rate limiter. */
+		namespace_id: string;
+		/** Simple rate limiting configuration. */
+		simple: {
+			/** The maximum number of requests allowed in the time period. */
+			limit: number;
+			/** The time period in seconds (10 for ten seconds, 60 for one minute). */
+			period: 10 | 60;
+		};
+	}[];
 }
 
 /**