Add support for new placement modes (#10937)

Add wrangler support for targeted placement Worker configurations.
The relevant tests have been added or updated, and type-level
enforcement of the new modes should prevent invalid formats from being
passed through.

Author: ReppCodes

.changeset/placement-targeted-mode.md

@@ -0,0 +1,21 @@
+---
+"wrangler": minor
+"@cloudflare/workers-utils": minor
+---
+
+Add support for "targeted" placement mode with region, host, and hostname fields
+
+This change adds a new mode to `placement` configuration. You can specify one of the following fields to target specific external resources for Worker placement:
+
+- `region`: Specify a region identifier (e.g., "aws:us-east-1") to target a region from another cloud service provider
+- `host`: Specify a host with (required) port (e.g., "example.com:8123") to target a TCP service
+- `hostname`: Specify a hostname (e.g., "example.com") to target an HTTP resource
+
+These fields are mutually exclusive - only one can be specified at a time.
+
+Example configuration:
+
+```toml
+[placement]
+host = "example.com:8123"
+```

packages/workers-utils/src/config/environment.ts

@@ -566,7 +566,12 @@ interface EnvironmentInheritable {
 	 *
 	 * @inheritable
 	 */
-	placement: { mode: "off" | "smart"; hint?: string } | undefined;
+	placement:
+		| { mode: "off" | "smart"; hint?: string }
+		| { mode?: "targeted"; region: string }
+		| { mode?: "targeted"; host: string }
+		| { mode?: "targeted"; hostname: string }
+		| undefined;
 
 	/**
 	 * Specify the directory of static assets to deploy/serve

packages/workers-utils/src/config/validation.ts

@@ -981,24 +981,124 @@ function normalizeAndValidatePlacement(
 	rawEnv: RawEnvironment
 ): Config["placement"] {
 	if (rawEnv.placement) {
-		validateRequiredProperty(
-			diagnostics,
-			"placement",
-			"mode",
-			rawEnv.placement.mode,
-			"string",
-			["off", "smart"]
-		);
-		validateOptionalProperty(
-			diagnostics,
-			"placement",
-			"hint",
-			rawEnv.placement.hint,
-			"string"
-		);
-		if (rawEnv.placement.hint && rawEnv.placement.mode !== "smart") {
+		const placement = rawEnv.placement as Record<string, unknown>;
+
+		// Detect which format is being used
+		const hasHint = "hint" in placement;
+		const hasRegion = "region" in placement;
+		const hasHost = "host" in placement;
+		const hasHostname = "hostname" in placement;
+		const hasTargetedFields = hasRegion || hasHost || hasHostname;
+
+		// Validate that formats aren't mixed
+		if (hasHint && hasTargetedFields) {
 			diagnostics.errors.push(
-				`"placement.hint" cannot be set if "placement.mode" is not "smart"`
+				`"placement" cannot have both "hint" (smart format) and "region"/"host"/"hostname" (targeted format) fields`
+			);
+			return inheritable(
+				diagnostics,
+				topLevelEnv,
+				rawEnv,
+				"placement",
+				() => true,
+				undefined
+			);
+		}
+
+		// Validate old format (with hint)
+		if (hasHint) {
+			validateRequiredProperty(
+				diagnostics,
+				"placement",
+				"mode",
+				placement.mode,
+				"string",
+				["off", "smart"]
+			);
+
+			const mode = placement.mode as string;
+			const hint = placement.hint;
+
+			// Hint must be a string (if provided)
+			if (hint !== undefined && typeof hint !== "string") {
+				diagnostics.errors.push(
+					`"placement.hint" must be a string when "placement.mode" is "${mode}"`
+				);
+			}
+			if (hint && mode !== "smart") {
+				diagnostics.errors.push(
+					`"placement.hint" can only be set when "placement.mode" is "smart"`
+				);
+			}
+		}
+		// Validate new format (with region/host/hostname)
+		else if (hasTargetedFields) {
+			// Mode is optional for new format, but if present must be "off" or "targeted"
+			validateOptionalProperty(
+				diagnostics,
+				"placement",
+				"mode",
+				placement.mode,
+				"string",
+				["off", "targeted"]
+			);
+
+			// Validate that region/host/hostname are strings if present
+			if (hasRegion) {
+				validateOptionalProperty(
+					diagnostics,
+					"placement",
+					"region",
+					placement.region,
+					"string"
+				);
+			}
+			if (hasHost) {
+				validateOptionalProperty(
+					diagnostics,
+					"placement",
+					"host",
+					placement.host,
+					"string"
+				);
+			}
+			if (hasHostname) {
+				validateOptionalProperty(
+					diagnostics,
+					"placement",
+					"hostname",
+					placement.hostname,
+					"string"
+				);
+			}
+
+			// Validate that region/host/hostname are mutually exclusive
+			const fieldsPresent = [hasRegion, hasHost, hasHostname].filter(Boolean);
+			if (fieldsPresent.length > 1) {
+				const presentFields = [];
+				if (hasRegion) {
+					presentFields.push("region");
+				}
+				if (hasHost) {
+					presentFields.push("host");
+				}
+				if (hasHostname) {
+					presentFields.push("hostname");
+				}
+				diagnostics.errors.push(
+					`"placement" fields ${presentFields.map((f) => `"${f}"`).join(", ")} are mutually exclusive. Only one can be specified.`
+				);
+			}
+		}
+		// Just mode, no hint or new format fields
+		else {
+			validateRequiredProperty(
+				diagnostics,
+				"placement",
+				"mode",
+				placement.mode,
+				"string",
+				["off", "smart", "targeted"]
 			);
 		}
 	}

packages/workers-utils/src/worker.ts

@@ -365,10 +365,11 @@ export interface CfDurableObjectMigrations {
 	}[];
 }
 
-export interface CfPlacement {
-	mode: "smart";
-	hint?: string;
-}
+export type CfPlacement =
+	| { mode: "smart"; hint?: string }
+	| { mode?: "targeted"; region: string }
+	| { mode?: "targeted"; host: string }
+	| { mode?: "targeted"; hostname: string };
 
 export interface CfTailConsumer {
 	service: string;

packages/wrangler/src/__tests__/config/configuration.test.ts

@@ -1229,7 +1229,7 @@ describe("normalizeAndValidateConfig()", () => {
 				  - Expected \\"tsconfig\\" to be of type string but got true.
 				  - Expected \\"name\\" to be of type string, alphanumeric and lowercase with dashes only but got 111.
 				  - Expected \\"main\\" to be of type string but got 1333.
-				  - Expected \\"placement.mode\\" field to be one of [\\"off\\",\\"smart\\"] but got \\"INVALID\\".
+				  - Expected \\"placement.mode\\" field to be one of [\\"off\\",\\"smart\\",\\"targeted\\"] but got \\"INVALID\\".
 				  - The field \\"define.DEF1\\" should be a string but got 1777.
 				  - Expected \\"no_bundle\\" to be of type boolean but got \\"INVALID\\".
 				  - Expected \\"minify\\" to be of type boolean but got \\"INVALID\\".
@@ -4835,7 +4835,7 @@ describe("normalizeAndValidateConfig()", () => {
 
 				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
 					"Processing wrangler configuration:
-					  - \\"placement.hint\\" cannot be set if \\"placement.mode\\" is not \\"smart\\""
+					  - \\"placement.hint\\" can only be set when \\"placement.mode\\" is \\"smart\\""
 				`);
 			});
 
@@ -4849,6 +4849,67 @@ describe("normalizeAndValidateConfig()", () => {
 
 				expect(diagnostics.hasErrors()).toBe(false);
 			});
+
+			it(`should error if placement hint object is set with placement mode "targeted"`, () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{
+						placement: { mode: "targeted", hint: "wnam" },
+					} as unknown as RawConfig,
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+					"Processing wrangler configuration:
+					  - Expected \\"placement.mode\\" field to be one of [\\"off\\",\\"smart\\"] but got \\"targeted\\".
+					  - \\"placement.hint\\" can only be set when \\"placement.mode\\" is \\"smart\\""
+				`);
+			});
+
+			it(`should not error if hostname field is set with placement mode "targeted"`, () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ placement: { hostname: "example.com" } },
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasErrors()).toBe(false);
+			});
+
+			it(`should not error if host field is set with placement mode "targeted"`, () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ placement: { host: "example.com:5432" } },
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasErrors()).toBe(false);
+			});
+
+			it(`should not error if host field is set with placement mode "targeted"`, () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ placement: { region: "aws:us-east-1" } },
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasErrors()).toBe(false);
+			});
+
+			it(`should error if placement has an invalid field`, () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ placement: { shoeSize: 13 } } as unknown as RawConfig,
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasErrors()).toBe(true);
+			});
 		});
 
 		describe("route & routes fields", () => {

packages/wrangler/src/api/pages/create-worker-bundle-contents.ts

@@ -4,6 +4,7 @@ import { Response } from "undici";
 import { getBindings } from "../../deployment-bundle/bindings";
 import { createWorkerUploadForm } from "../../deployment-bundle/create-worker-upload-form";
 import { loadSourceMaps } from "../../deployment-bundle/source-maps";
+import { parseConfigPlacement } from "../../utils/placement";
 import type { BundleResult } from "../../deployment-bundle/bundle";
 import type { CfPlacement, Config } from "@cloudflare/workers-utils";
 import type { Blob } from "node:buffer";
@@ -44,11 +45,13 @@ function createWorkerBundleFormData(
 		type: workerBundle.bundleType || "esm",
 	};
 
-	// The upload API only accepts an empty string or no specified placement for the "off" mode.
-	const placement: CfPlacement | undefined =
-		config?.placement?.mode === "smart"
-			? { mode: "smart", hint: config.placement.hint }
-			: undefined;
+	let placement: CfPlacement | undefined;
+
+	if (config !== undefined) {
+		placement = parseConfigPlacement(config);
+	} else {
+		placement = undefined;
+	}
 
 	return createWorkerUploadForm({
 		name: mainModule.name,

packages/wrangler/src/deploy/deploy.ts

@@ -61,6 +61,7 @@ import {
 import triggersDeploy from "../triggers/deploy";
 import { downloadWorkerConfig } from "../utils/download-worker-config";
 import { helpIfErrorIsSizeOrScriptStartup } from "../utils/friendly-validator-errors";
+import { parseConfigPlacement } from "../utils/placement";
 import { printBindings } from "../utils/print-bindings";
 import { retryOnAPIFailure } from "../utils/retry";
 import {
@@ -79,7 +80,6 @@ import type { RetrieveSourceMapFunction } from "../sourcemap";
 import type { ApiVersion, Percentage, VersionId } from "../versions/types";
 import type {
 	CfModule,
-	CfPlacement,
 	CfWorkerInit,
 	ComplianceConfig,
 	Config,
@@ -788,11 +788,7 @@ See https://developers.cloudflare.com/workers/platform/compatibility-dates for m
 			});
 		}
 
-		// The upload API only accepts an empty string or no specified placement for the "off" mode.
-		const placement: CfPlacement | undefined =
-			config.placement?.mode === "smart"
-				? { mode: "smart", hint: config.placement.hint }
-				: undefined;
+		const placement = parseConfigPlacement(config);
 
 		const entryPointName = path.basename(resolvedEntryPointPath);
 		const main: CfModule = {

packages/wrangler/src/utils/placement.ts

@@ -0,0 +1,31 @@
+import type { CfPlacement, Config } from "@cloudflare/workers-utils";
+
+/**
+ * Parse placement out of a Config
+ */
+export function parseConfigPlacement(config: Config): CfPlacement | undefined {
+	if (config.placement) {
+		const configPlacement = config.placement;
+		const hint = "hint" in configPlacement ? configPlacement.hint : undefined;
+
+		if (!hint && configPlacement.mode === "off") {
+			return undefined;
+		} else if (hint || configPlacement.mode === "smart") {
+			return { mode: "smart", hint: hint };
+		} else {
+			// mode is undefined or "targeted", which both map to the targeted variant
+			// TypeScript needs explicit checks to narrow the union type
+			if ("region" in configPlacement && configPlacement.region) {
+				return { mode: "targeted", region: configPlacement.region };
+			} else if ("host" in configPlacement && configPlacement.host) {
+				return { mode: "targeted", host: configPlacement.host };
+			} else if ("hostname" in configPlacement && configPlacement.hostname) {
+				return { mode: "targeted", hostname: configPlacement.hostname };
+			} else {
+				return undefined;
+			}
+		}
+	} else {
+		return undefined;
+	}
+}