@depup/wrangler 4.75.0-depup.0

package/templates/pages-template-plugin.ts

@@ -0,0 +1,190 @@
+import { match } from "path-to-regexp";
+
+//note: this explicitly does not include the * character, as pages requires this
+const escapeRegex = /[.+?^${}()|[\]\\]/g;
+
+type HTTPMethod =
+	| "HEAD"
+	| "OPTIONS"
+	| "GET"
+	| "POST"
+	| "PUT"
+	| "PATCH"
+	| "DELETE";
+
+/* TODO: Grab these from @cloudflare/workers-types instead */
+type Params<P extends string = string> = Record<P, string | string[]>;
+
+type EventContext<Env, P extends string, Data> = {
+	request: Request;
+	functionPath: string;
+	waitUntil: (promise: Promise<unknown>) => void;
+	passThroughOnException: () => void;
+	next: (input?: Request | string, init?: RequestInit) => Promise<Response>;
+	env: Env & { ASSETS: { fetch: typeof fetch } };
+	params: Params<P>;
+	data: Data;
+};
+
+type EventPluginContext<Env, P extends string, Data, PluginArgs> = {
+	request: Request;
+	functionPath: string;
+	waitUntil: (promise: Promise<unknown>) => void;
+	passThroughOnException: () => void;
+	next: (input?: Request | string, init?: RequestInit) => Promise<Response>;
+	env: Env & { ASSETS: { fetch: typeof fetch } };
+	params: Params<P>;
+	data: Data;
+	pluginArgs: PluginArgs;
+};
+
+declare type PagesFunction<
+	Env = unknown,
+	P extends string = string,
+	Data extends Record<string, unknown> = Record<string, unknown>,
+> = (context: EventContext<Env, P, Data>) => Response | Promise<Response>;
+
+declare type PagesPluginFunction<
+	Env = unknown,
+	P extends string = string,
+	Data extends Record<string, unknown> = Record<string, unknown>,
+	PluginArgs = unknown,
+> = (
+	context: EventPluginContext<Env, P, Data, PluginArgs>
+) => Response | Promise<Response>;
+/* end @cloudflare/workers-types */
+
+type RouteHandler = {
+	routePath: string;
+	mountPath: string;
+	method?: HTTPMethod;
+	modules: PagesFunction[];
+	middlewares: PagesFunction[];
+};
+
+// inject `routes` via ESBuild
+declare const routes: RouteHandler[];
+
+function* executeRequest(request: Request, relativePathname: string) {
+	// First, iterate through the routes (backwards) and execute "middlewares" on partial route matches
+	for (const route of [...routes].reverse()) {
+		if (route.method && route.method !== request.method) {
+			continue;
+		}
+
+		// replaces with "\\$&", this prepends a backslash to the matched string, e.g. "[" becomes "\["
+		const routeMatcher = match(route.routePath.replace(escapeRegex, "\\$&"), {
+			end: false,
+		});
+		const mountMatcher = match(route.mountPath.replace(escapeRegex, "\\$&"), {
+			end: false,
+		});
+		const matchResult = routeMatcher(relativePathname);
+		const mountMatchResult = mountMatcher(relativePathname);
+		if (matchResult && mountMatchResult) {
+			for (const handler of route.middlewares.flat()) {
+				yield {
+					handler,
+					params: matchResult.params as Params,
+					path: mountMatchResult.path,
+				};
+			}
+		}
+	}
+
+	// Then look for the first exact route match and execute its "modules"
+	for (const route of routes) {
+		if (route.method && route.method !== request.method) {
+			continue;
+		}
+
+		const routeMatcher = match(route.routePath.replace(escapeRegex, "\\$&"), {
+			end: true,
+		});
+		const mountMatcher = match(route.mountPath.replace(escapeRegex, "\\$&"), {
+			end: false,
+		});
+		const matchResult = routeMatcher(relativePathname);
+		const mountMatchResult = mountMatcher(relativePathname);
+		if (matchResult && mountMatchResult && route.modules.length) {
+			for (const handler of route.modules.flat()) {
+				yield {
+					handler,
+					params: matchResult.params as Params,
+					path: matchResult.path,
+				};
+			}
+			break;
+		}
+	}
+}
+
+export default function (pluginArgs: unknown) {
+	const onRequest: PagesPluginFunction = async (workerContext) => {
+		let { request } = workerContext;
+		const { env, next } = workerContext;
+		let { data } = workerContext;
+
+		const url = new URL(request.url);
+		// TODO: Replace this with something actually legible.
+		const relativePathname = `/${
+			url.pathname.replace(workerContext.functionPath, "") || ""
+		}`.replace(/^\/\//, "/");
+
+		const handlerIterator = executeRequest(request, relativePathname);
+		const pluginNext = async (input?: RequestInfo, init?: RequestInit) => {
+			if (input !== undefined) {
+				let url = input;
+				if (typeof input === "string") {
+					url = new URL(input, request.url).toString();
+				}
+				request = new Request(url, init);
+			}
+
+			const result = handlerIterator.next();
+			// Note we can't use `!result.done` because this doesn't narrow to the correct type
+			if (result.done === false) {
+				const { handler, params, path } = result.value;
+				const context = {
+					request: new Request(request.clone()),
+					functionPath: workerContext.functionPath + path,
+					next: pluginNext,
+					params,
+					get data() {
+						return data;
+					},
+					set data(value) {
+						if (typeof value !== "object" || value === null) {
+							throw new Error("context.data must be an object");
+						}
+						// user has overriden context.data, so we need to merge it with the existing data
+						data = value;
+					},
+					pluginArgs,
+					env,
+					waitUntil: workerContext.waitUntil.bind(workerContext),
+					passThroughOnException:
+						workerContext.passThroughOnException.bind(workerContext),
+				};
+
+				const response = await handler(context);
+
+				return cloneResponse(response);
+			} else {
+				return next(request);
+			}
+		};
+
+		return pluginNext();
+	};
+
+	return onRequest;
+}
+
+// This makes a Response mutable
+const cloneResponse = (response: Response) =>
+	// https://fetch.spec.whatwg.org/#null-body-status
+	new Response(
+		[101, 204, 205, 304].includes(response.status) ? null : response.body,
+		response
+	);

package/templates/pages-template-worker.ts

@@ -0,0 +1,198 @@
+import { match } from "path-to-regexp";
+
+//note: this explicitly does not include the * character, as pages requires this
+const escapeRegex = /[.+?^${}()|[\]\\]/g;
+
+type HTTPMethod =
+	| "HEAD"
+	| "OPTIONS"
+	| "GET"
+	| "POST"
+	| "PUT"
+	| "PATCH"
+	| "DELETE";
+
+/* TODO: Grab these from @cloudflare/workers-types instead */
+type Params<P extends string = string> = Record<P, string | string[]>;
+
+type EventContext<Env, P extends string, Data> = {
+	request: Request;
+	functionPath: string;
+	waitUntil: (promise: Promise<unknown>) => void;
+	passThroughOnException: () => void;
+	next: (input?: Request | string, init?: RequestInit) => Promise<Response>;
+	env: Env & { ASSETS: { fetch: typeof fetch } };
+	params: Params<P>;
+	data: Data;
+};
+
+declare type PagesFunction<
+	Env = unknown,
+	P extends string = string,
+	Data extends Record<string, unknown> = Record<string, unknown>,
+> = (context: EventContext<Env, P, Data>) => Response | Promise<Response>;
+/* end @cloudflare/workers-types */
+
+type RouteHandler = {
+	routePath: string;
+	mountPath: string;
+	method?: HTTPMethod;
+	modules: PagesFunction[];
+	middlewares: PagesFunction[];
+};
+
+// inject `routes` via ESBuild
+declare const routes: RouteHandler[];
+// define `__FALLBACK_SERVICE__` via ESBuild
+declare const __FALLBACK_SERVICE__: string;
+
+// expect an ASSETS fetcher binding pointing to the asset-server stage
+type FetchEnv = {
+	[name: string]: { fetch: typeof fetch };
+	ASSETS: { fetch: typeof fetch };
+};
+
+type WorkerContext = {
+	waitUntil: (promise: Promise<unknown>) => void;
+	passThroughOnException: () => void;
+};
+
+function* executeRequest(request: Request) {
+	const requestPath = new URL(request.url).pathname;
+
+	// First, iterate through the routes (backwards) and execute "middlewares" on partial route matches
+	for (const route of [...routes].reverse()) {
+		if (route.method && route.method !== request.method) {
+			continue;
+		}
+
+		// replaces with "\\$&", this prepends a backslash to the matched string, e.g. "[" becomes "\["
+		const routeMatcher = match(route.routePath.replace(escapeRegex, "\\$&"), {
+			end: false,
+		});
+		const mountMatcher = match(route.mountPath.replace(escapeRegex, "\\$&"), {
+			end: false,
+		});
+		const matchResult = routeMatcher(requestPath);
+		const mountMatchResult = mountMatcher(requestPath);
+		if (matchResult && mountMatchResult) {
+			for (const handler of route.middlewares.flat()) {
+				yield {
+					handler,
+					params: matchResult.params as Params,
+					path: mountMatchResult.path,
+				};
+			}
+		}
+	}
+
+	// Then look for the first exact route match and execute its "modules"
+	for (const route of routes) {
+		if (route.method && route.method !== request.method) {
+			continue;
+		}
+		const routeMatcher = match(route.routePath.replace(escapeRegex, "\\$&"), {
+			end: true,
+		});
+		const mountMatcher = match(route.mountPath.replace(escapeRegex, "\\$&"), {
+			end: false,
+		});
+		const matchResult = routeMatcher(requestPath);
+		const mountMatchResult = mountMatcher(requestPath);
+		if (matchResult && mountMatchResult && route.modules.length) {
+			for (const handler of route.modules.flat()) {
+				yield {
+					handler,
+					params: matchResult.params as Params,
+					path: matchResult.path,
+				};
+			}
+			break;
+		}
+	}
+}
+
+export default {
+	async fetch(
+		originalRequest: Request,
+		env: FetchEnv,
+		workerContext: WorkerContext
+	) {
+		let request = originalRequest;
+		const handlerIterator = executeRequest(request);
+		let data = {}; // arbitrary data the user can set between functions
+		let isFailOpen = false;
+
+		const next = async (input?: RequestInfo, init?: RequestInit) => {
+			if (input !== undefined) {
+				let url = input;
+				if (typeof input === "string") {
+					url = new URL(input, request.url).toString();
+				}
+				request = new Request(url, init);
+			}
+
+			const result = handlerIterator.next();
+			// Note we can't use `!result.done` because this doesn't narrow to the correct type
+			if (result.done === false) {
+				const { handler, params, path } = result.value;
+				const context = {
+					request: new Request(request.clone()),
+					functionPath: path,
+					next,
+					params,
+					get data() {
+						return data;
+					},
+					set data(value) {
+						if (typeof value !== "object" || value === null) {
+							throw new Error("context.data must be an object");
+						}
+						// user has overriden context.data, so we need to merge it with the existing data
+						data = value;
+					},
+					env,
+					waitUntil: workerContext.waitUntil.bind(workerContext),
+					passThroughOnException: () => {
+						isFailOpen = true;
+					},
+				};
+
+				const response = await handler(context);
+
+				if (!(response instanceof Response)) {
+					throw new Error("Your Pages function should return a Response");
+				}
+
+				return cloneResponse(response);
+			} else if (__FALLBACK_SERVICE__) {
+				// There are no more handlers so finish with the fallback service (`env.ASSETS.fetch` in Pages' case)
+				const response = await env[__FALLBACK_SERVICE__].fetch(request);
+				return cloneResponse(response);
+			} else {
+				// There was not fallback service so actually make the request to the origin.
+				const response = await fetch(request);
+				return cloneResponse(response);
+			}
+		};
+
+		try {
+			return await next();
+		} catch (error) {
+			if (isFailOpen) {
+				const response = await env[__FALLBACK_SERVICE__].fetch(request);
+				return cloneResponse(response);
+			}
+
+			throw error;
+		}
+	},
+};
+
+// This makes a Response mutable
+const cloneResponse = (response: Response) =>
+	// https://fetch.spec.whatwg.org/#null-body-status
+	new Response(
+		[101, 204, 205, 304].includes(response.status) ? null : response.body,
+		response
+	);

package/templates/remoteBindings/ProxyServerWorker.ts

@@ -0,0 +1,143 @@
+import { newWorkersRpcResponse } from "capnweb";
+import { EmailMessage } from "cloudflare:email";
+
+interface Env extends Record<string, unknown> {}
+
+class BindingNotFoundError extends Error {
+	constructor(name?: string) {
+		super(`Binding ${name ? `"${name}"` : ""} not found`);
+	}
+}
+
+/**
+ * For most bindings, we expose them as
+ *  - RPC stubs directly to capnweb, or
+ *  - HTTP based fetchers
+ * However, there are some special cases:
+ *  - SendEmail bindings need to take EmailMessage as their first parameter,
+ *    which is not serialisable. As such, we reconstruct it before sending it
+ *    on to the binding. See packages/miniflare/src/workers/email/email.worker.ts
+ *  - Dispatch Namespace bindings have a synchronous .get() method. Since we
+ *    can't emulate that over an async boundary, we mock it locally and _actually_
+ *    perform the .get() remotely at the first appropriate async point. See
+ *    packages/miniflare/src/workers/dispatch-namespace/dispatch-namespace.worker.ts
+ *
+ * getExposedJSRPCBinding() and getExposedFetcher() perform the logic for figuring out
+ * which binding is being accessed, dependending on the request. Note: Both have logic
+ * for dispatch namespaces, because dispatch namespaces can use both fetch or RPC depending
+ * on context.
+ */
+
+function getExposedJSRPCBinding(request: Request, env: Env) {
+	const url = new URL(request.url);
+	const bindingName = url.searchParams.get("MF-Binding");
+	if (!bindingName) {
+		throw new BindingNotFoundError();
+	}
+
+	const targetBinding = env[bindingName];
+	if (!targetBinding) {
+		throw new BindingNotFoundError(bindingName);
+	}
+
+	if (targetBinding.constructor.name === "SendEmail") {
+		return {
+			async send(e: any) {
+				// Check if this is an EmailMessage (has EmailMessage::raw property) or MessageBuilder
+				if ("EmailMessage::raw" in e) {
+					// EmailMessage API - reconstruct the EmailMessage object
+					const message = new EmailMessage(
+						e.from,
+						e.to,
+						e["EmailMessage::raw"]
+					);
+					return (targetBinding as SendEmail).send(message);
+				} else {
+					// MessageBuilder API - pass through directly as a plain object
+					return (targetBinding as SendEmail).send(e);
+				}
+			},
+		};
+	}
+
+	if (url.searchParams.has("MF-Dispatch-Namespace-Options")) {
+		const { name, args, options } = JSON.parse(
+			url.searchParams.get("MF-Dispatch-Namespace-Options")!
+		);
+		return (targetBinding as DispatchNamespace).get(name, args, options);
+	}
+
+	return targetBinding;
+}
+
+function getExposedFetcher(request: Request, env: Env) {
+	const bindingName = request.headers.get("MF-Binding");
+	if (!bindingName) {
+		throw new BindingNotFoundError();
+	}
+
+	const targetBinding = env[bindingName];
+	if (!targetBinding) {
+		throw new BindingNotFoundError(bindingName);
+	}
+
+	// Special case the Dispatch Namespace binding because it has a top-level synchronous .get() call
+	const dispatchNamespaceOptions = request.headers.get(
+		"MF-Dispatch-Namespace-Options"
+	);
+	if (dispatchNamespaceOptions) {
+		const { name, args, options } = JSON.parse(dispatchNamespaceOptions);
+		return (targetBinding as DispatchNamespace).get(name, args, options);
+	}
+	return targetBinding as Fetcher;
+}
+
+/**
+ * This Worker can proxy two types of remote binding:
+ *  1. "raw" bindings, where this Worker has been configured to pass through the raw
+ *     fetch from a local workerd instance to the relevant binding
+ *  2. JSRPC bindings, where this Worker uses capnweb to proxy RPC
+ *     communication in userland. This is always over a WebSocket connection
+ */
+function isJSRPCBinding(request: Request): boolean {
+	const url = new URL(request.url);
+	return request.headers.has("Upgrade") && url.searchParams.has("MF-Binding");
+}
+
+export default {
+	async fetch(request, env) {
+		try {
+			if (isJSRPCBinding(request)) {
+				return newWorkersRpcResponse(
+					request,
+					getExposedJSRPCBinding(request, env)
+				);
+			} else {
+				const fetcher = getExposedFetcher(request, env);
+				const originalHeaders = new Headers();
+				for (const [name, value] of request.headers) {
+					if (name.startsWith("mf-header-")) {
+						originalHeaders.set(name.slice("mf-header-".length), value);
+					} else if (name === "upgrade") {
+						// The `Upgrade` header needs to be special-cased to prevent:
+						//   TypeError: Worker tried to return a WebSocket in a response to a request which did not contain the header "Upgrade: websocket"
+						originalHeaders.set(name, value);
+					}
+				}
+
+				return fetcher.fetch(
+					request.headers.get("MF-URL") ?? "http://example.com",
+					new Request(request, {
+						redirect: "manual",
+						headers: originalHeaders,
+					})
+				);
+			}
+		} catch (e) {
+			if (e instanceof BindingNotFoundError) {
+				return new Response(e.message, { status: 400 });
+			}
+			return new Response((e as Error).message, { status: 500 });
+		}
+	},
+} satisfies ExportedHandler<Env>;

package/templates/remoteBindings/wrangler.jsonc

@@ -0,0 +1,4 @@
+{
+	"main": "./ProxyServerWorker.ts",
+	"compatibility_date": "2025-04-28",
+}