feat(wrangler): Add support for placement hints (#6625)

- Add hint field to smart placement configuration Co-authored-by: Max Peterson <mpeterson@cloudflare.com>
cloudflare · Sep 11, 2024 · 8dcd456 · 8dcd456
1 parent 6523db2
commit 8dcd456
Show file tree

Hide file tree

Showing 8 changed files with 55 additions and 4 deletions.
diff --git a/.changeset/three-nails-bake.md b/.changeset/three-nails-bake.md
@@ -0,0 +1,7 @@
+---
+"wrangler": minor
+---
+
+feature: Add support for placement hints
+
+Adds the `hint` field to smart placement configuration. When set, placement hints will be used to decide where smart-placement-enabled Workers are run.
diff --git a/packages/wrangler/src/__tests__/configuration.test.ts b/packages/wrangler/src/__tests__/configuration.test.ts
@@ -3485,6 +3485,31 @@ describe("normalizeAndValidateConfig()", () => {
 			});
 		});
 
+		describe("[placement]", () => {
+			it(`should error if placement hint is set with placement mode "off"`, () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ placement: { mode: "off", hint: "wnam" } },
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+					"Processing wrangler configuration:
+					  - \\"placement.hint\\" cannot be set if \\"placement.mode\\" is not \\"smart\\""
+				`);
+			});
+
+			it(`should not error if placement hint is set with placement mode "smart"`, () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ placement: { mode: "smart", hint: "wnam" } },
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasErrors()).toBe(false);
+			});
+		});
+
 		describe("(deprecated)", () => {
 			it("should remove and warn about deprecated properties", () => {
 				const rawConfig: RawConfig = {

diff --git a/packages/wrangler/src/api/pages/create-worker-bundle-contents.ts b/packages/wrangler/src/api/pages/create-worker-bundle-contents.ts
@@ -73,7 +73,9 @@ function createWorkerBundleFormData(
 
 	// 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" } : undefined;
+		config?.placement?.mode === "smart"
+			? { mode: "smart", hint: config.placement.hint }
+			: undefined;
 
 	const worker: CfWorkerInit = {
 		name: mainModule.name,

diff --git a/packages/wrangler/src/config/environment.ts b/packages/wrangler/src/config/environment.ts
@@ -337,7 +337,7 @@ interface EnvironmentInheritable {
 	 *
 	 * @inheritable
 	 */
-	placement: { mode: "off" | "smart" } | undefined;
+	placement: { mode: "off" | "smart"; hint?: string } | undefined;
 
 	/**
 	 * Specify the directory of static assets to deploy/serve

diff --git a/packages/wrangler/src/config/validation.ts b/packages/wrangler/src/config/validation.ts
@@ -945,6 +945,18 @@ function normalizeAndValidatePlacement(
 			"string",
 			["off", "smart"]
 		);
+		validateOptionalProperty(
+			diagnostics,
+			"placement",
+			"hint",
+			rawEnv.placement.hint,
+			"string"
+		);
+		if (rawEnv.placement.hint && rawEnv.placement.mode !== "smart") {
+			diagnostics.errors.push(
+				`"placement.hint" cannot be set if "placement.mode" is not "smart"`
+			);
+		}
 	}
 
 	return inheritable(

diff --git a/packages/wrangler/src/deploy/deploy.ts b/packages/wrangler/src/deploy/deploy.ts
@@ -714,7 +714,9 @@ 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" } : undefined;
+			config.placement?.mode === "smart"
+				? { mode: "smart", hint: config.placement.hint }
+				: undefined;
 
 		const entryPointName = path.basename(resolvedEntryPointPath);
 		const main: CfModule = {

diff --git a/packages/wrangler/src/deployment-bundle/worker.ts b/packages/wrangler/src/deployment-bundle/worker.ts
@@ -267,6 +267,7 @@ export interface CfDurableObjectMigrations {
 
 export interface CfPlacement {
 	mode: "smart";
+	hint?: string;
 }
 
 export interface CfTailConsumer {

diff --git a/packages/wrangler/src/versions/upload.ts b/packages/wrangler/src/versions/upload.ts
@@ -401,7 +401,9 @@ 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" } : undefined;
+			config.placement?.mode === "smart"
+				? { mode: "smart", hint: config.placement.hint }
+				: undefined;
 
 		const entryPointName = path.basename(resolvedEntryPointPath);
 		const main = {