[wrangler] Add safe telemetry labels for user errors (#13722)

Co-authored-by: Edmund Hung <edmund@cloudflare.com>

Author: MattieTK

.changeset/fix-buffer-devalue.md

@@ -4,10 +4,6 @@
 
 fix: normalise typed array subclasses in devalue serialization
 
-Node.js `Buffer` extends `Uint8Array` but isn't available in all runtimes. When
-a `Buffer` was passed through the proxy serialization bridge (e.g. as a D1 bind
-parameter via `getPlatformProxy()`), the reviver would fail because `"Buffer"`
-isn't in the allowed constructor list and may not exist on `globalThis` in workerd.
+Node.js `Buffer` extends `Uint8Array` but isn't available in all runtimes. When a `Buffer` was passed through the proxy serialization bridge (e.g. as a D1 bind parameter via `getPlatformProxy()`), the reviver would fail because `"Buffer"` isn't in the allowed constructor list and may not exist on `globalThis` in workerd.
 
-The reducer now normalises subclass constructor names to the nearest standard
-typed array parent before serialization, matching structured clone behaviour.
+The reducer now normalises subclass constructor names to the nearest standard typed array parent before serialization, matching structured clone behaviour.

.changeset/quiet-timers-teach.md

@@ -0,0 +1,5 @@
+---
+"wrangler": patch
+---
+
+Improve safe telemetry categorisation for user-facing Wrangler errors.

packages/cli/check-macos-version.ts

@@ -32,7 +32,8 @@ export function checkMacOSVersion(options: { shouldThrow: boolean }): void {
 			throw new UserError(
 				`Unsupported macOS version: The Cloudflare Workers runtime cannot run on the current version of macOS (${macOSVersion}). ` +
 					`The minimum requirement is macOS ${MINIMUM_MACOS_VERSION}+. See https://github.com/cloudflare/workerd?tab=readme-ov-file#running-workerd ` +
-					`If you cannot upgrade your version of macOS, you could try running in a DevContainer setup with a supported version of Linux (glibc 2.35+ required).`
+					`If you cannot upgrade your version of macOS, you could try running in a DevContainer setup with a supported version of Linux (glibc 2.35+ required).`,
+				{ telemetryMessage: false }
 			);
 		} else {
 			/* eslint-disable-next-line no-console -- this package has no logger to use

packages/containers-shared/src/build.ts

@@ -77,7 +77,11 @@ export function dockerBuild(
 			resolve();
 		} else if (!errorHandled) {
 			errorHandled = true;
-			reject(new UserError(`Docker build exited with code: ${code}`));
+			reject(
+				new UserError(`Docker build exited with code: ${code}`, {
+					telemetryMessage: false,
+				})
+			);
 		}
 	});
 	child.on("error", (err) => {

packages/containers-shared/src/images.ts

@@ -112,7 +112,8 @@ export async function prepareContainerImagesForDev(args: {
 	let aborted = false;
 	if (process.platform === "win32") {
 		throw new UserError(
-			"Local development with containers is currently not supported on Windows. You should use WSL instead. You can also set `enable_containers` to false if you do not need to develop the container part of your application."
+			"Local development with containers is currently not supported on Windows. You should use WSL instead. You can also set `enable_containers` to false if you do not need to develop the container part of your application.",
+			{ telemetryMessage: false }
 		);
 	}
 	await verifyDockerInstalled(dockerPath);
@@ -266,7 +267,8 @@ export const getAndValidateRegistryType = (domain: string): RegistryPattern => {
 			.map((r) => r.name)
 			.join(", ");
 		throw new UserError(
-			`${url.hostname} is not a supported image registry.\nCurrently we support the following non-Cloudflare registries: ${supportedRegistries}.\nTo use an existing image from another repository, see https://developers.cloudflare.com/containers/platform-details/image-management/#using-pre-built-container-images`
+			`${url.hostname} is not a supported image registry.\nCurrently we support the following non-Cloudflare registries: ${supportedRegistries}.\nTo use an existing image from another repository, see https://developers.cloudflare.com/containers/platform-details/image-management/#using-pre-built-container-images`,
+			{ telemetryMessage: false }
 		);
 	}
 

packages/containers-shared/src/inspect.ts

@@ -23,7 +23,9 @@ export async function dockerImageInspect(
 		proc.on("close", (code) => {
 			if (code !== 0) {
 				return reject(
-					new UserError(`failed inspecting image locally: ${stderr.trim()}`)
+					new UserError(`failed inspecting image locally: ${stderr.trim()}`, {
+						telemetryMessage: false,
+					})
 				);
 			}
 			resolve(stdout.trim());

packages/containers-shared/src/login.ts

@@ -54,7 +54,11 @@ export async function dockerLoginImageRegistry(
 			if (code === 0) {
 				resolve();
 			} else {
-				reject(new UserError(`Login failed with code: ${code}`));
+				reject(
+					new UserError(`Login failed with code: ${code}`, {
+						telemetryMessage: false,
+					})
+				);
 			}
 		});
 	});

packages/containers-shared/src/utils.ts

@@ -42,13 +42,21 @@ export const runDockerCmd = (
 			resolve({ aborted });
 		} else if (!errorHandled) {
 			errorHandled = true;
-			reject(new UserError(`Docker command exited with code: ${code}`));
+			reject(
+				new UserError(`Docker command exited with code: ${code}`, {
+					telemetryMessage: false,
+				})
+			);
 		}
 	});
 	child.on("error", (err) => {
 		if (!errorHandled) {
 			errorHandled = true;
-			reject(new UserError(`Docker command failed: ${err.message}`));
+			reject(
+				new UserError(`Docker command failed: ${err.message}`, {
+					telemetryMessage: false,
+				})
+			);
 		}
 	});
 	return {
@@ -78,7 +86,8 @@ export const runDockerCmdWithOutput = (dockerPath: string, args: string[]) => {
 		return stdout.trim();
 	} catch (error) {
 		throw new UserError(
-			`Failed running docker command: ${(error as Error).message}. Command: ${dockerPath} ${args.join(" ")}`
+			`Failed running docker command: ${(error as Error).message}. Command: ${dockerPath} ${args.join(" ")}`,
+			{ telemetryMessage: false }
 		);
 	}
 };
@@ -104,7 +113,8 @@ export const verifyDockerInstalled = async (
 		throw new UserError(
 			`The Docker CLI could not be launched. Please ensure that the Docker CLI is installed and the daemon is running.\n` +
 				`Other container tooling that is compatible with the Docker CLI and engine may work, but is not yet guaranteed to do so. You can specify an executable with the environment variable WRANGLER_DOCKER_BIN and a socket with DOCKER_HOST.` +
-				`${isDev ? "\nTo suppress this error if you do not intend on triggering any container instances, set dev.enable_containers to false in your Wrangler config or passing in --enable-containers=false." : ""}`
+				`${isDev ? "\nTo suppress this error if you do not intend on triggering any container instances, set dev.enable_containers to false in your Wrangler config or passing in --enable-containers=false." : ""}`,
+			{ telemetryMessage: false }
 		);
 	}
 };
@@ -190,7 +200,8 @@ export async function checkExposedPorts(
 	if (output === "0") {
 		throw new UserError(
 			`The container "${options.class_name}" does not expose any ports. In your Dockerfile, please expose any ports you intend to connect to.\n` +
-				"For additional information please see: https://developers.cloudflare.com/containers/local-dev/#exposing-ports.\n"
+				"For additional information please see: https://developers.cloudflare.com/containers/local-dev/#exposing-ports.\n",
+			{ telemetryMessage: false }
 		);
 	}
 }

packages/containers-shared/tests/docker-context.test.ts

@@ -48,7 +48,9 @@ describe.skipIf(process.platform !== "linux" && process.env.CI === "true")(
 			expect,
 		}) => {
 			vi.mocked(execFileSync).mockImplementation(() => {
-				throw new UserError("Docker command failed");
+				throw new UserError("Docker command failed", {
+					telemetryMessage: false,
+				});
 			});
 
 			const result = resolveDockerHost("/no/op/docker");

packages/vite-plugin-cloudflare/src/plugins/dev.ts

@@ -250,7 +250,8 @@ export const devPlugin = createPlugin("dev", (ctx) => {
 								"To use images from the Cloudflare-managed registry with the Vite plugin, " +
 									"set the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID environment variables.\n" +
 									"The API token requires Containers:Edit and Workers Scripts:Edit permissions.\n" +
-									"Alternatively, use a Dockerfile that references the image via FROM."
+									"Alternatively, use a Dockerfile that references the image via FROM.",
+								{ telemetryMessage: false }
 							);
 						}