Add support for built-in workerd services (#435)

Specifically, this allows custom `network`, `external` and `disk`
services to be specified as service bindings. Requests to `network`
services are dispatched according to URL. Requests to `external`
services are dispatched to the specified remote server. Requests to
`disk` services are dispatched to an HTTP service backed by an
on-disk directory.

This PR also fixes a bug where custom function service bindings with
the same name in different Workers would dispatch all requests to the
first Workers' function.

packages/miniflare/README.md

@@ -275,7 +275,7 @@ parameter in module format Workers.
   Record mapping binding name to paths containing arbitrary binary data to
   inject as `ArrayBuffer` bindings into this Worker.
 
-- `serviceBindings?: Record<string, string | (request: Request) => Awaitable<Response>>`
+- `serviceBindings?: Record<string, string | { network: Network } | { external: ExternalServer } | { disk: DiskDirectory } | (request: Request) => Awaitable<Response>>`
 
   Record mapping binding name to service designators to inject as
   `{ fetch: typeof fetch }`
@@ -284,10 +284,22 @@ parameter in module format Workers.
 
   - If the designator is a `string`, requests will be dispatched to the Worker
     with that `name`.
+  - If the designator is an object of the form `{ network: { ... } }`, where
+    `network` is a
+    [`workerd` `Network` struct](https://github.com/cloudflare/workerd/blob/bdbd6075c7c53948050c52d22f2dfa37bf376253/src/workerd/server/workerd.capnp#L555-L598),
+    requests will be dispatched according to the `fetch`ed URL.
+  - If the designator is an object of the form `{ external: { ... } }` where
+    `external` is a
+    [`workerd` `ExternalServer` struct](https://github.com/cloudflare/workerd/blob/bdbd6075c7c53948050c52d22f2dfa37bf376253/src/workerd/server/workerd.capnp#L504-L553),
+    requests will be dispatched to the specified remote server.
+  - If the designator is an object of the form `{ disk: { ... } }` where `disk`
+    is a
+    [`workerd` `DiskDirectory` struct](https://github.com/cloudflare/workerd/blob/bdbd6075c7c53948050c52d22f2dfa37bf376253/src/workerd/server/workerd.capnp#L600-L643),
+    requests will be dispatched to an HTTP service backed by an on-disk
+    directory.
   - If the designator is a function, requests will be dispatched to your custom
     handler. This allows you to access data and functions defined in Node.js
     from your Worker.
-    <!--TODO: other service types, disk, network, external, etc-->
 
 #### Cache
 

packages/miniflare/src/index.ts

@@ -478,7 +478,7 @@ export class Miniflare {
 			const workerBindings: Worker_Binding[] = [];
 			const additionalModules: Worker_Module[] = [];
 			for (const [key, plugin] of PLUGIN_ENTRIES) {
-				const pluginBindings = await plugin.getBindings(workerOpts[key]);
+				const pluginBindings = await plugin.getBindings(workerOpts[key], i);
 				if (pluginBindings !== undefined) {
 					workerBindings.push(...pluginBindings);
 

packages/miniflare/src/plugins/core/index.ts

@@ -2,7 +2,6 @@ import { readFileSync } from "fs";
 import fs from "fs/promises";
 import { TextEncoder } from "util";
 import { bold } from "kleur/colors";
-import { Request, Response } from "undici";
 import { z } from "zod";
 import {
 	Service,
@@ -11,13 +10,7 @@ import {
 	kVoid,
 	supportedCompatibilityDate,
 } from "../../runtime";
-import {
-	Awaitable,
-	JsonSchema,
-	Log,
-	MiniflareCoreError,
-	zAwaitable,
-} from "../../shared";
+import { Awaitable, JsonSchema, Log, MiniflareCoreError } from "../../shared";
 import { getCacheServiceName } from "../cache";
 import {
 	BINDING_SERVICE_LOOPBACK,
@@ -31,15 +24,11 @@ import {
 	STRING_SCRIPT_PATH,
 	convertModuleDefinition,
 } from "./modules";
+import { ServiceDesignatorSchema } from "./services";
 
 const encoder = new TextEncoder();
 const numericCompare = new Intl.Collator(undefined, { numeric: true }).compare;
 
-// (request: Request) => Awaitable<Response>
-export const ServiceFetchSchema = z
-	.function()
-	.args(z.instanceof(Request))
-	.returns(zAwaitable(z.instanceof(Response)));
 export const CoreOptionsSchema = z.object({
 	name: z.string().optional(),
 	script: z.string().optional(),
@@ -62,10 +51,7 @@ export const CoreOptionsSchema = z.object({
 	wasmBindings: z.record(z.string()).optional(),
 	textBlobBindings: z.record(z.string()).optional(),
 	dataBlobBindings: z.record(z.string()).optional(),
-	// TODO: add support for workerd network/external/disk services here
-	serviceBindings: z
-		.record(z.union([z.string(), ServiceFetchSchema]))
-		.optional(),
+	serviceBindings: z.record(ServiceDesignatorSchema).optional(),
 });
 
 export const CoreSharedOptionsSchema = z.object({
@@ -92,11 +78,19 @@ export const SERVICE_LOOPBACK = `${CORE_PLUGIN_NAME}:loopback`;
 export const SERVICE_ENTRY = `${CORE_PLUGIN_NAME}:entry`;
 // Service prefix for all regular user workers
 const SERVICE_USER_PREFIX = `${CORE_PLUGIN_NAME}:user`;
+// Service prefix for `workerd`'s builtin services (network, external, disk)
+const SERVICE_BUILTIN_PREFIX = `${CORE_PLUGIN_NAME}:builtin`;
 // Service prefix for custom fetch functions defined in `serviceBindings` option
 const SERVICE_CUSTOM_PREFIX = `${CORE_PLUGIN_NAME}:custom`;
 
-export function getUserServiceName(name = "") {
-	return `${SERVICE_USER_PREFIX}:${name}`;
+export function getUserServiceName(workerName = "") {
+	return `${SERVICE_USER_PREFIX}:${workerName}`;
+}
+function getBuiltinServiceName(workerIndex: number, bindingName: string) {
+	return `${SERVICE_BUILTIN_PREFIX}:${workerIndex}:${bindingName}`;
+}
+function getCustomServiceName(workerIndex: number, bindingName: string) {
+	return `${SERVICE_CUSTOM_PREFIX}:${workerIndex}:${bindingName}`;
 }
 
 export const HEADER_PROBE = "MF-Probe";
@@ -235,7 +229,7 @@ export const CORE_PLUGIN: Plugin<
 > = {
 	options: CoreOptionsSchema,
 	sharedOptions: CoreSharedOptionsSchema,
-	getBindings(options) {
+	getBindings(options, workerIndex) {
 		const bindings: Awaitable<Worker_Binding>[] = [];
 
 		if (options.bindings !== undefined) {
@@ -269,15 +263,23 @@ export const CORE_PLUGIN: Plugin<
 		}
 		if (options.serviceBindings !== undefined) {
 			bindings.push(
-				...Object.entries(options.serviceBindings).map(([name, service]) => ({
-					name,
-					service: {
-						name:
-							typeof service === "function"
-								? `${SERVICE_CUSTOM_PREFIX}:${name}` // Custom `fetch` function
-								: `${SERVICE_USER_PREFIX}:${service}`, // Regular user worker
-					},
-				}))
+				...Object.entries(options.serviceBindings).map(([name, service]) => {
+					let serviceName: string;
+					if (typeof service === "function") {
+						// Custom `fetch` function
+						serviceName = getCustomServiceName(workerIndex, name);
+					} else if (typeof service === "object") {
+						// Builtin workerd service: network, external, disk
+						serviceName = getBuiltinServiceName(workerIndex, name);
+					} else {
+						// Regular user worker
+						serviceName = getUserServiceName(service);
+					}
+					return {
+						name: name,
+						service: { name: serviceName },
+					};
+				})
 			);
 		}
 
@@ -372,8 +374,9 @@ export const CORE_PLUGIN: Plugin<
 		if (options.serviceBindings !== undefined) {
 			for (const [name, service] of Object.entries(options.serviceBindings)) {
 				if (typeof service === "function") {
+					// Custom `fetch` function
 					services.push({
-						name: `${SERVICE_CUSTOM_PREFIX}:${name}`,
+						name: getCustomServiceName(workerIndex, name),
 						worker: {
 							serviceWorkerScript: SCRIPT_CUSTOM_SERVICE,
 							compatibilityDate: "2022-09-01",
@@ -389,6 +392,12 @@ export const CORE_PLUGIN: Plugin<
 							],
 						},
 					});
+				} else if (typeof service === "object") {
+					// Builtin workerd service: network, external, disk
+					services.push({
+						name: getBuiltinServiceName(workerIndex, name),
+						...service,
+					});
 				}
 			}
 		}
@@ -430,3 +439,5 @@ function getWorkerScript(
 		return { serviceWorkerScript: code };
 	}
 }
+
+export * from "./services";

packages/miniflare/src/plugins/core/services.ts

@@ -0,0 +1,83 @@
+import { Request, Response } from "undici";
+import { z } from "zod";
+import {
+	ExternalServer,
+	HttpOptions_Style,
+	TlsOptions_Version,
+} from "../../runtime";
+import { zAwaitable } from "../../shared";
+
+// Zod validators for types in runtime/config/workerd.ts.
+// All options should be optional except where specifically stated.
+// TODO: autogenerate these with runtime/config/workerd.ts from capnp
+
+export const HttpOptionsHeaderSchema = z.object({
+	name: z.string(), // name should be required
+	value: z.ostring(), // If omitted, the header will be removed
+});
+const HttpOptionsSchema = z.object({
+	style: z.nativeEnum(HttpOptions_Style).optional(),
+	forwardedProtoHeader: z.ostring(),
+	cfBlobHeader: z.ostring(),
+	injectRequestHeaders: HttpOptionsHeaderSchema.array().optional(),
+	injectResponseHeaders: HttpOptionsHeaderSchema.array().optional(),
+});
+
+const TlsOptionsKeypairSchema = z.object({
+	privateKey: z.ostring(),
+	certificateChain: z.ostring(),
+});
+
+const TlsOptionsSchema = z.object({
+	keypair: TlsOptionsKeypairSchema.optional(),
+	requireClientCerts: z.oboolean(),
+	trustBrowserCas: z.oboolean(),
+	trustedCertificates: z.string().array().optional(),
+	minVersion: z.nativeEnum(TlsOptions_Version).optional(),
+	cipherList: z.ostring(),
+});
+
+const NetworkSchema = z.object({
+	allow: z.string().array().optional(),
+	deny: z.string().array().optional(),
+	tlsOptions: TlsOptionsSchema.optional(),
+});
+
+export const ExternalServerSchema = z.intersection(
+	z.object({ address: z.string() }), // address should be required
+	z.union([
+		z.object({ http: z.optional(HttpOptionsSchema) }),
+		z.object({
+			https: z.optional(
+				z.object({
+					options: HttpOptionsSchema.optional(),
+					tlsOptions: TlsOptionsSchema.optional(),
+					certificateHost: z.ostring(),
+				})
+			),
+		}),
+	])
+) as z.ZodType<ExternalServer>;
+// This type cast is required for `api-extractor` to produce a `.d.ts` rollup.
+// Rather than outputting a `z.ZodIntersection<...>` for this type, it will
+// just use `z.ZodType<ExternalServer>`. Without this, the extractor process
+// just ends up pinned at 100% CPU. Probably unbounded recursion? I guess this
+// type is too complex? Something to investigate... :thinking_face:
+
+const DiskDirectorySchema = z.object({
+	path: z.string(), // path should be required
+	writable: z.oboolean(),
+});
+
+export const ServiceFetchSchema = z
+	.function()
+	.args(z.instanceof(Request))
+	.returns(zAwaitable(z.instanceof(Response)));
+
+export const ServiceDesignatorSchema = z.union([
+	z.string(),
+	z.object({ network: NetworkSchema }),
+	z.object({ external: ExternalServerSchema }),
+	z.object({ disk: DiskDirectorySchema }),
+	ServiceFetchSchema,
+]);

packages/miniflare/src/plugins/shared/index.ts

@@ -26,7 +26,10 @@ export interface PluginBase<
 	SharedOptions extends z.ZodType | undefined,
 > {
 	options: Options;
-	getBindings(options: z.infer<Options>): Awaitable<Worker_Binding[] | void>;
+	getBindings(
+		options: z.infer<Options>,
+		workerIndex: number
+	): Awaitable<Worker_Binding[] | void>;
 	getServices(
 		options: PluginServicesOptions<Options, SharedOptions>
 	): Awaitable<Service[] | void>;

packages/miniflare/src/runtime/config/workerd.ts

@@ -132,9 +132,10 @@ export type Worker_DurableObjectNamespace = { className?: string } & (
 	| { ephemeralLocal?: Void }
 );
 
-export type ExternalServer =
+export type ExternalServer = { address?: string } & (
 	| { http: HttpOptions }
-	| { https: ExternalServer_Https };
+	| { https: ExternalServer_Https }
+);
 
 export interface ExternalServer_Https {
 	options?: HttpOptions;