add a cf field to the getBindingsProxy result

.changeset/strong-otters-hope.md

@@ -0,0 +1,16 @@
+---
+"wrangler": minor
+---
+
+feature: add a `cf` field to the `getBindingsProxy` result
+
+Add a new `cf` field to the `getBindingsProxy` result that people can use to mock the production
+`cf` (`IncomingRequestCfProperties`) object.
+
+Example:
+
+```ts
+const { cf } = await getBindingsProxy();
+
+console.log(`country = ${cf.country}; colo = ${cf.colo}`); // logs 'country = GB ; colo = LHR'
+```

fixtures/get-bindings-proxy/tests/get-bindings-proxy.cf.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { getBindingsProxy } from "./shared";
+
+describe("getBindingsProxy - cf", () => {
+	it("should provide mock data", async () => {
+		const { cf, dispose } = await getBindingsProxy();
+		try {
+			expect(cf).toMatchObject({
+				colo: "DFW",
+				city: "Austin",
+				regionCode: "TX",
+			});
+		} finally {
+			await dispose();
+		}
+	});
+
+	it("should match the production runtime cf object", async () => {
+		const { cf, dispose } = await getBindingsProxy();
+		try {
+			expect(cf.constructor.name).toBe("Object");
+
+			expect(() => {
+				cf.city = "test city";
+			}).toThrowError(
+				"Cannot assign to read only property 'city' of object '#<Object>'"
+			);
+			expect(cf.city).not.toBe("test city");
+
+			expect(() => {
+				cf.newField = "test new field";
+			}).toThrowError("Cannot add property newField, object is not extensible");
+			expect("newField" in cf).toBe(false);
+
+			expect(cf.botManagement).toMatchObject({
+				score: 99,
+			});
+			expect(Object.isFrozen(cf.botManagement)).toBe(true);
+		} finally {
+			await dispose();
+		}
+	});
+});

packages/wrangler/src/api/integrations/bindings/index.ts

@@ -41,6 +41,11 @@ export type BindingsProxy<Bindings = Record<string, unknown>> = {
 	 * Object containing the various proxies
 	 */
 	bindings: Bindings;
+	/**
+	 * Mock of the context object that Workers received in their request handler, all the object's methods are no-op
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	cf: Record<string, any>;
 	/**
 	 * Mock of the context object that Workers received in their request handler, all the object's methods are no-op
 	 */
@@ -88,11 +93,15 @@ export async function getBindingsProxy<Bindings = Record<string, unknown>>(
 
 	const vars = getVarsForDev(rawConfig, env);
 
+	const cf = await mf.getCf();
+	deepFreeze(cf);
+
 	return {
 		bindings: {
 			...vars,
 			...bindings,
 		},
+		cf,
 		ctx: new ExecutionContext(),
 		caches: new CacheStorage(),
 		dispose: () => mf.dispose(),
@@ -177,3 +186,14 @@ function getMiniflarePersistOptions(
 		d1Persist: `${persistPath}/d1`,
 	};
 }
+
+function deepFreeze<T extends Record<string | number | symbol, unknown>>(
+	obj: T
+): void {
+	Object.freeze(obj);
+	Object.entries(obj).forEach(([, prop]) => {
+		if (prop !== null && typeof prop === "object" && !Object.isFrozen(prop)) {
+			deepFreeze(prop as Record<string | number | symbol, unknown>);
+		}
+	});
+}