chore: rename getBindingsProxy to getPlatformProxy

.changeset/strange-geckos-shave.md

@@ -0,0 +1,13 @@
+---
+"wrangler": patch
+---
+
+chore: rename `getBindingsProxy` to `getPlatformProxy`
+
+initially `getBindingsProxy` was supposed to only provide proxies for bindings,
+the utility has however grown, including now `cf`, `ctx` and `caches`, to
+clarify the increased scope the utility is getting renamed to `getPlatformProxy`
+and its `bindings` field is getting renamed `env`
+
+_note_: `getBindingProxy` with its signature is still kept available, making this
+a non breaking change

fixtures/get-bindings-proxy/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "get-bindings-proxy-fixture",
 	"private": true,
-	"description": "A test for the getBindingsProxy utility",
+	"description": "A test for the getBindingsProxy (deprecated) utility",
 	"scripts": {
 		"test": "vitest run",
 		"test:watch": "vitest",

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

@@ -7,12 +7,10 @@ import {
 	R2Bucket,
 } from "@cloudflare/workers-types";
 import { describe, expect, it } from "vitest";
-import {
-	getBindingsProxy as originalGetBindingsProxy,
-	unstable_dev,
-} from "wrangler";
+import { unstable_dev } from "wrangler";
+import { getBindingsProxy } from "./shared";
 import type { KVNamespace } from "@cloudflare/workers-types";
-import type { GetBindingsProxyOptions, UnstableDevWorker } from "wrangler";
+import type { UnstableDevWorker } from "wrangler";
 
 type Bindings = {
 	MY_VAR: string;
@@ -30,17 +28,6 @@ type Bindings = {
 
 const wranglerTomlFilePath = path.join(__dirname, "..", "wrangler.toml");
 
-// Here we wrap the actual original getBindingsProxy function and disable its persistance, this is to make sure
-// that we don't implement any persistance during these tests (which would add unnecessary extra complexity)
-function getBindingsProxy<T>(
-	options: Omit<GetBindingsProxyOptions, "persist">
-): ReturnType<typeof originalGetBindingsProxy<T>> {
-	return originalGetBindingsProxy({
-		...options,
-		persist: false,
-	});
-}
-
 describe("getBindingsProxy - bindings", () => {
 	let devWorkers: UnstableDevWorker[];
 

fixtures/get-platform-proxy/.dev.vars

@@ -0,0 +1,3 @@
+MY_DEV_VAR = "my-dev-var-value"
+MY_VAR_A = "my-dev-var-a"
+MY_KV = "my-dev-kv"

fixtures/get-platform-proxy/custom-toml/path/.dev.vars

@@ -0,0 +1 @@
+MY_DEV_VAR = "my-dev-var-value-from-a-custom-location"

fixtures/get-platform-proxy/custom-toml/path/test-toml

@@ -0,0 +1,7 @@
+name = "get-bindings-proxy-fixture"
+main = "src/index.ts"
+compatibility_date = "2023-11-21"
+
+[vars]
+MY_VAR = "my-var-value-from-a-custom-toml"
+MY_JSON_VAR = { test = true, customToml = true }

fixtures/get-platform-proxy/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "get-platform-proxy-fixture",
+	"private": true,
+	"description": "A test for the getPlatformProxy utility",
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"type:tests": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-tsconfig": "workspace:*",
+		"@cloudflare/workers-types": "^4.20221111.1",
+		"wrangler": "workspace:*",
+		"undici": "^5.28.2"
+	}
+}

fixtures/get-platform-proxy/tests/get-platform-proxy.caches.test.ts

@@ -0,0 +1,34 @@
+import { Request, Response } from "undici";
+import { describe, expect, it } from "vitest";
+import { getPlatformProxy } from "./shared";
+
+describe("getPlatformProxy - caches", () => {
+	(["default", "named"] as const).forEach((cacheType) =>
+		it(`correctly obtains a no-op ${cacheType} cache`, async () => {
+			const { caches, dispose } = await getPlatformProxy();
+			try {
+				const cache =
+					cacheType === "default"
+						? caches.default
+						: await caches.open("my-cache");
+				testNoOpCache(cache);
+			} finally {
+				await dispose();
+			}
+		})
+	);
+});
+
+async function testNoOpCache(
+	cache: Awaited<ReturnType<typeof getPlatformProxy>>["caches"]["default"]
+) {
+	let match = await cache.match("http://0.0.0.0/test");
+	expect(match).toBeUndefined();
+
+	const req = new Request("http://0.0.0.0/test");
+	await cache.put(req, new Response("test"));
+	const resp = await cache.match(req);
+	expect(resp).toBeUndefined();
+	const deleted = await cache.delete(req);
+	expect(deleted).toBe(false);
+}

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { getPlatformProxy } from "./shared";
+
+describe("getPlatformProxy - cf", () => {
+	it("should provide mock data", async () => {
+		const { cf, dispose } = await getPlatformProxy();
+		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 getPlatformProxy();
+		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();
+		}
+	});
+});

fixtures/get-platform-proxy/tests/get-platform-proxy.ctx.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { getPlatformProxy } from "./shared";
+
+describe("getPlatformProxy - ctx", () => {
+	it("should provide a no-op waitUntil method", async () => {
+		const { ctx, dispose } = await getPlatformProxy();
+		try {
+			let value = 4;
+			ctx.waitUntil(
+				new Promise((resolve) => {
+					value++;
+					resolve(value);
+				})
+			);
+			expect(value).toBe(5);
+		} finally {
+			await dispose();
+		}
+	});
+
+	it("should provide a no-op passThroughOnException method", async () => {
+		const { ctx, dispose } = await getPlatformProxy();
+		try {
+			expect(ctx.passThroughOnException()).toBe(undefined);
+		} finally {
+			await dispose();
+		}
+	});
+
+	it("should match the production runtime ctx object", async () => {
+		const { ctx, dispose } = await getPlatformProxy();
+		try {
+			expect(ctx.constructor.name).toBe("ExecutionContext");
+			expect(typeof ctx.waitUntil).toBe("function");
+			expect(typeof ctx.passThroughOnException).toBe("function");
+
+			ctx.waitUntil = ((str: string) => `- ${str} -`) as any;
+			expect(ctx.waitUntil("waitUntil can be overridden" as any)).toBe(
+				"- waitUntil can be overridden -"
+			);
+
+			ctx.passThroughOnException = ((str: string) => `_ ${str} _`) as any;
+			expect(
+				(ctx.passThroughOnException as any)(
+					"passThroughOnException can be overridden"
+				)
+			).toBe("_ passThroughOnException can be overridden _");
+
+			(ctx as any).text = "the ExecutionContext can be extended";
+			expect((ctx as any).text).toBe("the ExecutionContext can be extended");
+		} finally {
+			await dispose();
+		}
+	});
+});