Support Images binding in getPlatformProxy() (#9954)

* Support Images binding in getPlatformProxy()

* fix snapshot

* fix snapshot

* Update fixtures/get-platform-proxy/tests/get-platform-proxy.env.test.ts

Co-authored-by: Pete Bacon Darwin <[email protected]>

---------

Co-authored-by: Pete Bacon Darwin <[email protected]>

Author: penalosa

.changeset/red-wombats-chew.md

@@ -0,0 +1,6 @@
+---
+"miniflare": patch
+"wrangler": patch
+---
+
+Support Images binding in `getPlatformProxy()`

fixtures/get-platform-proxy/package.json

@@ -10,6 +10,8 @@
 	"devDependencies": {
 		"@cloudflare/workers-tsconfig": "workspace:*",
 		"@cloudflare/workers-types": "^4.20250712.0",
+		"@types/jest-image-snapshot": "^6.4.0",
+		"jest-image-snapshot": "^6.4.0",
 		"typescript": "catalog:default",
 		"undici": "catalog:default",
 		"vitest": "catalog:default",

fixtures/get-platform-proxy/tests/__image_snapshots__/get-platform-proxy-env-test-ts-get-platform-proxy-env-correctly-obtains-functioning-image-bindings-2-snap.png

@@ -1,5 +1,6 @@
 import path from "path";
 import { D1Database, R2Bucket } from "@cloudflare/workers-types";
+import { toMatchImageSnapshot } from "jest-image-snapshot";
 import {
 	afterEach,
 	beforeEach,
@@ -13,6 +14,7 @@ import { getPlatformProxy } from "./shared";
 import type {
 	Fetcher,
 	Hyperdrive,
+	ImagesBinding,
 	KVNamespace,
 } from "@cloudflare/workers-types";
 import type { Unstable_DevWorker } from "wrangler";
@@ -28,6 +30,7 @@ type Env = {
 	MY_D1: D1Database;
 	MY_HYPERDRIVE: Hyperdrive;
 	ASSETS: Fetcher;
+	IMAGES: ImagesBinding;
 };
 
 const wranglerConfigFilePath = path.join(__dirname, "..", "wrangler.jsonc");
@@ -199,6 +202,43 @@ describe("getPlatformProxy - env", () => {
 		}
 	});
 
+	it("correctly obtains functioning Image bindings", async () => {
+		expect.extend({ toMatchImageSnapshot });
+
+		const { env, dispose } = await getPlatformProxy<Env>({
+			configPath: wranglerConfigFilePath,
+		});
+		try {
+			const { IMAGES } = env;
+			const streams = (
+				await fetch("https://playground.devprod.cloudflare.dev/flares.png")
+			).body!.tee();
+
+			// @ts-expect-error The stream types aren't matching up properly?
+			expect(await IMAGES.info(streams[0])).toMatchInlineSnapshot(`
+				{
+				  "fileSize": 96549,
+				  "format": "image/png",
+				  "height": 1145,
+				  "width": 2048,
+				}
+			`);
+
+			// @ts-expect-error The stream types aren't matching up properly?
+			const response = await env.IMAGES.input(streams[1])
+				.transform({ rotate: 90 })
+				.transform({ width: 128, height: 100 })
+				.transform({ blur: 20 })
+				.output({ format: "image/png" });
+
+			expect(
+				Buffer.from(await response.response().arrayBuffer())
+			).toMatchImageSnapshot();
+		} finally {
+			await dispose();
+		}
+	});
+
 	// Important: the hyperdrive values are passthrough ones since the workerd specific hyperdrive values only make sense inside
 	//            workerd itself and would simply not work in a node.js process
 	it("correctly obtains passthrough Hyperdrive bindings", async () => {

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

@@ -15,6 +15,9 @@
 			"test": true,
 		},
 	},
+	"images": {
+		"binding": "IMAGES",
+	},
 	"kv_namespaces": [
 		{
 			"binding": "MY_KV",

fixtures/get-platform-proxy/wrangler.jsonc

@@ -25,7 +25,15 @@ import {
 } from "../../../workers";
 import { DECODER, SynchronousFetcher, SynchronousResponse } from "./fetch-sync";
 import { NODE_PLATFORM_IMPL } from "./types";
-import type { ServiceWorkerGlobalScope } from "@cloudflare/workers-types/experimental";
+import type {
+	ImageDrawOptions,
+	ImageOutputOptions,
+	ImagesBinding,
+	ImageTransform,
+	ImageTransformationResult,
+	ImageTransformer,
+	ServiceWorkerGlobalScope,
+} from "@cloudflare/workers-types/experimental";
 
 const kAddress = Symbol("kAddress");
 const kName = Symbol("kName");
@@ -282,11 +290,68 @@ class ProxyStubHandler<T extends object>
 				});
 				return this.#parseAsyncResponse(resPromise);
 			} else {
+				// See #createMediaProxy() for why this is special
+				if (name === "ImagesBindingImpl") {
+					return this.#createMediaProxy(target);
+				}
 				// Otherwise, return a `Proxy` for this target
 				return this.bridge.getProxy(target);
 			}
 		},
 	};
+	/**
+	 * Images bindings are some of the most complex bindings from an API perspective, other than RPC. In particular, they expose a _synchronous_ API that accepts ReadableStream arguments.
+	 * Multiple synchronous APIs are chained together in a builder pattern (e.g. `await env.IMAGES.input(stream).transform(...).output(...)`) before the final `.output()` call is awaited.
+	 * This breaks our assumptions around functions that accept ReadableStream arguments always being async, and so doesn't work without some special casing.
+	 *
+	 * Ref: https://developers.cloudflare.com/images/transform-images/bindings/
+	 */
+	#createMediaProxy(target: NativeTarget) {
+		type Operation = {
+			type: "transform" | "draw";
+			arguments: unknown[];
+		};
+		const transformer = (
+			target: {
+				input: (
+					stream: ReadableStream,
+					operations: Operation[],
+					options: ImageOutputOptions
+				) => ImageTransformationResult;
+			},
+			stream: ReadableStream,
+			operations: Operation[]
+		): ImageTransformer => {
+			return {
+				transform: (transform: ImageTransform): ImageTransformer => {
+					return transformer(target, stream, [
+						...operations,
+						{ type: "transform", arguments: [transform] },
+					]);
+				},
+				draw: (image: ImageTransformer, options?: ImageDrawOptions) => {
+					return transformer(target, stream, [
+						...operations,
+						{ type: "draw", arguments: [image, options] },
+					]);
+				},
+				output: async (options: ImageOutputOptions) => {
+					// This signature doesn't exist on the production binding, but will be intercepted in the proxy server
+					return await target.input(stream, operations, options);
+				},
+			};
+		};
+		const binding = {
+			info: (stream: ReadableStream<Uint8Array>) => {
+				// @ts-expect-error The stream types are mismatched
+				return (this.bridge.getProxy(target) as ImagesBinding)["info"](stream);
+			},
+			input: (stream: ReadableStream<Uint8Array>) => {
+				return transformer(this.bridge.getProxy(target), stream, []);
+			},
+		};
+		return binding;
+	}
 
 	constructor(
 		readonly bridge: ProxyClientBridge,
@@ -552,7 +617,7 @@ class ProxyStubHandler<T extends object>
 		this.#assertSafe();
 
 		const targetName = this.target[kName];
-		// See `isFetcherFetch()` comment for why this special
+		// See `isFetcherFetch()` comment for why this is special
 		if (isFetcherFetch(targetName, key)) return this.#fetcherFetchCall(args);
 
 		const stringified = stringifyWithStreams(

packages/miniflare/src/plugins/core/proxy/client.ts

@@ -87,3 +87,10 @@ export function isR2ObjectWriteHttpMetadata(targetName: string, key: string) {
 		key === "writeHttpMetadata"
 	);
 }
+
+/**
+ * See #createMediaProxy() comment for why this is special
+ */
+export function isImagesInput(targetName: string, key: string) {
+	return targetName === "ImagesBindingImpl" && key === "input";
+}

packages/miniflare/src/workers/core/constants.ts

@@ -6,6 +6,7 @@ import {
 	CoreBindings,
 	CoreHeaders,
 	isFetcherFetch,
+	isImagesInput,
 	isR2ObjectWriteHttpMetadata,
 	ProxyAddresses,
 	ProxyOps,
@@ -305,7 +306,15 @@ export class ProxyServer implements DurableObject {
 			}
 			assert(Array.isArray(args));
 			try {
-				if (["RpcProperty", "RpcStub"].includes(func.constructor.name)) {
+				// See #createMediaProxy() for why this is special
+				if (isImagesInput(targetName, keyHeader)) {
+					let transform = func.apply(target, [args[0]]);
+					for (const operation of args[1]) {
+						transform = transform[operation.type](...operation.arguments);
+					}
+					// We intentionally don't await this `output()` call so that it's treated as a regular promise
+					result = transform.output(args[2]);
+				} else if (["RpcProperty", "RpcStub"].includes(func.constructor.name)) {
 					// let's resolve RpcPromise instances right away (to support serialization)
 					result = await func(...args);
 				} else {

packages/miniflare/src/workers/core/proxy.worker.ts

@@ -215,7 +215,7 @@ async function getMiniflareOptionsFromConfig(args: {
 			services: bindings.services,
 			serviceBindings: {},
 			migrations: config.migrations,
-			imagesLocalMode: false,
+			imagesLocalMode: true,
 			tails: [],
 			containers: undefined,
 			containerBuildId: undefined,