wrangler 0.0.0-e978986 → 0.0.0-e98613f8

package/src/logger.ts

@@ -1,59 +1,74 @@
 import { format } from "node:util";
 import { formatMessagesSync } from "esbuild";
+import { getEnvironmentVariableFactory } from "./environment-variables";
+import type { BuildFailure } from "esbuild";
 
-const LOGGER_LEVELS = {
-  error: 0,
-  warn: 1,
-  log: 2,
-  debug: 3,
+export const LOGGER_LEVELS = {
+	none: -1,
+	error: 0,
+	warn: 1,
+	info: 2,
+	log: 3,
+	debug: 4,
 } as const;
 
-type LoggerLevel = keyof typeof LOGGER_LEVELS;
+export type LoggerLevel = keyof typeof LOGGER_LEVELS;
 
 /** A map from LOGGER_LEVEL to the error `kind` needed by `formatMessagesSync()`. */
 const LOGGER_LEVEL_FORMAT_TYPE_MAP = {
-  error: "error",
-  warn: "warning",
-  log: undefined,
-  debug: undefined,
+	error: "error",
+	warn: "warning",
+	info: undefined,
+	log: undefined,
+	debug: undefined,
 } as const;
 
+const getLogLevelFromEnv = getEnvironmentVariableFactory({
+	variableName: "WRANGLER_LOG",
+	defaultValue: "log",
+});
+
 class Logger {
-  constructor(public loggerLevel: LoggerLevel = "log") {}
+	constructor() {}
 
-  columns = process.stdout.columns;
+	loggerLevel: LoggerLevel = (getLogLevelFromEnv() as LoggerLevel) ?? "log";
+	columns = process.stdout.columns;
 
-  debug = (...args: unknown[]) => this.doLog("debug", args);
-  log = (...args: unknown[]) => this.doLog("log", args);
-  warn = (...args: unknown[]) => this.doLog("warn", args);
-  error = (...args: unknown[]) => this.doLog("error", args);
+	debug = (...args: unknown[]) => this.doLog("debug", args);
+	info = (...args: unknown[]) => this.doLog("info", args);
+	log = (...args: unknown[]) => this.doLog("log", args);
+	warn = (...args: unknown[]) => this.doLog("warn", args);
+	error = (...args: unknown[]) => this.doLog("error", args);
 
-  private doLog(messageLevel: LoggerLevel, args: unknown[]) {
-    if (LOGGER_LEVELS[this.loggerLevel] >= LOGGER_LEVELS[messageLevel]) {
-      console[messageLevel](this.formatMessage(messageLevel, format(...args)));
-    }
-  }
+	private doLog(messageLevel: Exclude<LoggerLevel, "none">, args: unknown[]) {
+		if (LOGGER_LEVELS[this.loggerLevel] >= LOGGER_LEVELS[messageLevel]) {
+			console[messageLevel](this.formatMessage(messageLevel, format(...args)));
+		}
+	}
 
-  private formatMessage(level: LoggerLevel, message: string): string {
-    const kind = LOGGER_LEVEL_FORMAT_TYPE_MAP[level];
-    if (kind) {
-      // Format the message using the esbuild formatter.
-      // The first line of the message is the main `text`,
-      // subsequent lines are put into the `notes`.
-      const [firstLine, ...otherLines] = message.split("\n");
-      const notes =
-        otherLines.length > 0
-          ? otherLines.map((text) => ({ text }))
-          : undefined;
-      return formatMessagesSync([{ text: firstLine, notes }], {
-        color: true,
-        kind,
-        terminalWidth: this.columns,
-      })[0];
-    } else {
-      return message;
-    }
-  }
+	private formatMessage(
+		level: Exclude<LoggerLevel, "none">,
+		message: string
+	): string {
+		const kind = LOGGER_LEVEL_FORMAT_TYPE_MAP[level];
+		if (kind) {
+			// Format the message using the esbuild formatter.
+			// The first line of the message is the main `text`,
+			// subsequent lines are put into the `notes`.
+			const [firstLine, ...otherLines] = message.split("\n");
+			const notes =
+				otherLines.length > 0
+					? otherLines.map((text) => ({ text }))
+					: undefined;
+			return formatMessagesSync([{ text: firstLine, notes }], {
+				color: true,
+				kind,
+				terminalWidth: this.columns,
+			})[0];
+		} else {
+			return message;
+		}
+	}
 }
 
 /**
@@ -64,3 +79,14 @@ class Logger {
  * to filter out logging messages.
  */
 export const logger = new Logger();
+
+/**
+ * Logs all errors/warnings associated with an esbuild BuildFailure in the same
+ * style esbuild would.
+ */
+export function logBuildFailure(failure: BuildFailure) {
+	let logs = formatMessagesSync(failure.errors, { kind: "error", color: true });
+	for (const log of logs) console.error(log);
+	logs = formatMessagesSync(failure.warnings, { kind: "warning", color: true });
+	for (const log of logs) console.warn(log);
+}

package/src/metrics/index.ts

@@ -0,0 +1,5 @@
+export { getMetricsDispatcher } from "./metrics-dispatcher";
+export type { Properties } from "./metrics-dispatcher";
+export { getMetricsConfig } from "./metrics-config";
+export * from "./send-event";
+export { getMetricsUsageHeaders } from "./metrics-usage-headers";

package/src/metrics/metrics-config.ts

@@ -0,0 +1,239 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fetchResult } from "../cfetch";
+import { getConfigCache, saveToConfigCache } from "../config-cache";
+import { confirm } from "../dialogs";
+import { getEnvironmentVariableFactory } from "../environment-variables";
+import { getGlobalWranglerConfigPath } from "../global-wrangler-config-path";
+import { CI } from "../is-ci";
+import isInteractive from "../is-interactive";
+import { logger } from "../logger";
+import { getAPIToken } from "../user";
+
+/**
+ * The date that the metrics being gathered was last updated in a way that would require
+ * the user to give their permission again.
+ *
+ * When reading from a config file, we check the recorded date in the config file against
+ * this one here. We ignore the permissions set in the the file if the recorded date is older.
+ * This allows us to prompt the user to re-opt-in when we make substantive changes to our metrics
+ * gathering.
+ */
+export const CURRENT_METRICS_DATE = new Date(2022, 6, 4);
+export const USER_ID_CACHE_PATH = "user-id.json";
+
+export const getWranglerSendMetricsFromEnv = getEnvironmentVariableFactory({
+	variableName: "WRANGLER_SEND_METRICS",
+});
+
+export interface MetricsConfigOptions {
+	/**
+	 * Defines whether to send metrics to Cloudflare:
+	 * If defined, then use this value for whether the dispatch is enabled.
+	 * Otherwise, infer the enabled value from the user configuration.
+	 */
+	sendMetrics?: boolean;
+	/**
+	 * When true, do not make any CF API requests.
+	 */
+	offline?: boolean;
+}
+
+/**
+ * The information needed to set up the MetricsDispatcher.
+ */
+export interface MetricsConfig {
+	/** True if usage tracking is enabled. */
+	enabled: boolean;
+	/** A UID that identifies this user and machine pair for Wrangler. */
+	deviceId: string;
+	/** The currently logged in user - undefined if not logged in. */
+	userId: string | undefined;
+}
+
+/**
+ * Get hold of the permissions and device-id for metrics dispatch.
+ *
+ * The device-id is just a unique identifier sent along with events to help
+ * to collate metrics. Once generated, this id is cached in the metrics config file.
+ *
+ * The permissions define whether we can send metrics or not. They can come from a variety of places:
+ * - the `send_metrics` setting in `wrangler.toml`
+ * - a cached response from the current user
+ * - prompting the user to opt-in to metrics
+ *
+ * If the user was prompted to opt-in, then their response is cached in the metrics config file.
+ *
+ * If the current process is not interactive then we will cannot prompt the user and just assume
+ * we cannot send metrics if there is no cached or project-level preference available.
+ */
+export async function getMetricsConfig({
+	sendMetrics,
+	offline = false,
+}: MetricsConfigOptions): Promise<MetricsConfig> {
+	const config = readMetricsConfig();
+	const deviceId = getDeviceId(config);
+	const userId = await getUserId(offline);
+
+	// If the WRANGLER_SEND_METRICS environment variable has been set use that
+	// and ignore everything else.
+	const sendMetricsEnv = getWranglerSendMetricsFromEnv();
+	if (sendMetricsEnv !== undefined) {
+		return {
+			enabled: sendMetricsEnv.toLowerCase() === "true",
+			deviceId,
+			userId,
+		};
+	}
+
+	// If the project is explicitly set the `send_metrics` options in `wrangler.toml`
+	// then use that and ignore any user preference.
+	if (sendMetrics !== undefined) {
+		return { enabled: sendMetrics, deviceId, userId };
+	}
+
+	// Get the user preference from the metrics config.
+	const permission = config.permission;
+	if (permission !== undefined) {
+		if (new Date(permission.date) >= CURRENT_METRICS_DATE) {
+			return { enabled: permission.enabled, deviceId, userId };
+		} else if (permission.enabled) {
+			logger.log(
+				"Usage metrics tracking has changed since you last granted permission."
+			);
+		}
+	}
+
+	// We couldn't get the metrics permission from the project-level nor the user-level config.
+	// If we are not interactive or in a CI build then just bail out.
+	if (!isInteractive() || CI.isCI()) {
+		return { enabled: false, deviceId, userId };
+	}
+
+	// Otherwise, let's ask the user and store the result in the metrics config.
+	const enabled = await confirm(
+		"Would you like to help improve Wrangler by sending usage metrics to Cloudflare?"
+	);
+	logger.log(
+		`Your choice has been saved in the following file: ${path.relative(
+			process.cwd(),
+			getMetricsConfigPath()
+		)}.\n\n` +
+			"  You can override the user level setting for a project in `wrangler.toml`:\n\n" +
+			"   - to disable sending metrics for a project: `send_metrics = false`\n" +
+			"   - to enable sending metrics for a project: `send_metrics = true`"
+	);
+	writeMetricsConfig({
+		permission: {
+			enabled,
+			date: CURRENT_METRICS_DATE,
+		},
+		deviceId,
+	});
+	return { enabled, deviceId, userId };
+}
+
+/**
+ * Stringify and write the given info to the metrics config file.
+ */
+export function writeMetricsConfig(config: MetricsConfigFile) {
+	mkdirSync(path.dirname(getMetricsConfigPath()), { recursive: true });
+	writeFileSync(
+		getMetricsConfigPath(),
+		JSON.stringify(
+			config,
+			(_key, value) => (value instanceof Date ? value.toISOString() : value),
+			"\t"
+		)
+	);
+}
+
+/**
+ * Read and parse the metrics config file.
+ */
+export function readMetricsConfig(): MetricsConfigFile {
+	try {
+		const config = readFileSync(getMetricsConfigPath(), "utf8");
+		return JSON.parse(config, (key, value) =>
+			key === "date" ? new Date(value) : value
+		);
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Get the path to the metrics config file.
+ */
+function getMetricsConfigPath(): string {
+	return path.resolve(getGlobalWranglerConfigPath(), "metrics.json");
+}
+
+/**
+ * The format of the metrics config file.
+ */
+export interface MetricsConfigFile {
+	permission?: {
+		/** True if Wrangler should send metrics to Cloudflare. */
+		enabled: boolean;
+		/** The date that this permission was set. */
+		date: Date;
+	};
+	/** A unique UUID that identifies this device for metrics purposes. */
+	deviceId?: string;
+}
+
+/**
+ * Returns an ID that uniquely identifies Wrangler on this device to help collate events.
+ *
+ * Once created this ID is stored in the metrics config file.
+ */
+function getDeviceId(config: MetricsConfigFile) {
+	// Get or create the deviceId.
+	const deviceId = config.deviceId ?? randomUUID();
+	if (config.deviceId === undefined) {
+		// We had to create a new deviceID so store it now.
+		writeMetricsConfig({ ...config, deviceId });
+	}
+	return deviceId;
+}
+
+/**
+ * Returns the ID of the current user, which will be sent with each event.
+ *
+ * The ID is retrieved from the CF API `/user` endpoint if the user is authenticated and then
+ * stored in the `node_modules/.cache`.
+ *
+ * If it is not possible to retrieve the ID (perhaps the user is not logged in) then we just use
+ * `undefined`.
+ */
+async function getUserId(offline: boolean) {
+	// Get the userId from the cache.
+	// If it has not been found in the cache and we are not offline then make an API call to get it.
+	// If we can't work in out then just use `anonymous`.
+	let userId = getConfigCache<{ userId: string }>(USER_ID_CACHE_PATH).userId;
+	if (userId === undefined && !offline) {
+		userId = await fetchUserId();
+		if (userId !== undefined) {
+			saveToConfigCache(USER_ID_CACHE_PATH, { userId });
+		}
+	}
+	return userId;
+}
+
+/**
+ * Ask the Cloudflare API for the User ID of the current user.
+ *
+ * We will only do this if we are not "offline", e.g. not running `wrangler dev --local`.
+ * Quietly return undefined if anything goes wrong.
+ */
+async function fetchUserId(): Promise<string | undefined> {
+	try {
+		return getAPIToken()
+			? (await fetchResult<{ id: string }>("/user")).id
+			: undefined;
+	} catch (e) {
+		return undefined;
+	}
+}

package/src/metrics/metrics-dispatcher.ts

@@ -0,0 +1,96 @@
+import { fetch } from "undici";
+import { version as wranglerVersion } from "../../package.json";
+import { logger } from "../logger";
+import { getMetricsConfig } from "./metrics-config";
+import type { MetricsConfigOptions } from "./metrics-config";
+
+// The SPARROW_SOURCE_KEY is provided at esbuild time as a `define` for production and beta
+// releases. Otherwise it is left undefined, which automatically disables metrics requests.
+declare const SPARROW_SOURCE_KEY: string;
+const SPARROW_URL = "https://sparrow.cloudflare.com";
+
+export async function getMetricsDispatcher(options: MetricsConfigOptions) {
+	return {
+		/**
+		 * Dispatch a event to the analytics target.
+		 *
+		 * The event should follow these conventions
+		 *  - name is of the form `[action] [object]` (lower case)
+		 *  - additional properties are camelCased
+		 */
+		async sendEvent(name: string, properties: Properties = {}): Promise<void> {
+			await dispatch({ type: "event", name, properties });
+		},
+
+		/**
+		 * Dispatch a user profile information to the analytics target.
+		 *
+		 * This call can be used to inform the analytics target of relevant properties associated
+		 * with the current user.
+		 */
+		async identify(properties: Properties): Promise<void> {
+			await dispatch({ type: "identify", name: "identify", properties });
+		},
+	};
+
+	async function dispatch(event: {
+		type: "identify" | "event";
+		name: string;
+		properties: Properties;
+	}): Promise<void> {
+		if (!SPARROW_SOURCE_KEY) {
+			logger.debug(
+				"Metrics dispatcher: Source Key not provided. Be sure to initialize before sending events.",
+				event
+			);
+			return;
+		}
+
+		// Lazily get the config for this dispatcher only when an event is being dispatched.
+		// We must await this since it might trigger user interaction that would break other UI
+		// in Wrangler if it was allowed to run in parallel.
+		const metricsConfig = await getMetricsConfig(options);
+		if (!metricsConfig.enabled) {
+			logger.debug(
+				`Metrics dispatcher: Dispatching disabled - would have sent ${JSON.stringify(
+					event
+				)}.`
+			);
+			return;
+		}
+
+		logger.debug(`Metrics dispatcher: Posting data ${JSON.stringify(event)}`);
+		const body = JSON.stringify({
+			deviceId: metricsConfig.deviceId,
+			userId: metricsConfig.userId,
+			event: event.name,
+			properties: {
+				category: "Workers",
+				wranglerVersion,
+				os: process.platform + ":" + process.arch,
+				...event.properties,
+			},
+		});
+
+		// Do not await this fetch call.
+		// Just fire-and-forget, otherwise we might slow down the rest of Wrangler.
+		fetch(`${SPARROW_URL}/api/v1/${event.type}`, {
+			method: "POST",
+			headers: {
+				Accept: "*/*",
+				"Content-Type": "application/json",
+				"Sparrow-Source-Key": SPARROW_SOURCE_KEY,
+			},
+			mode: "cors",
+			keepalive: true,
+			body,
+		}).catch((e) => {
+			logger.debug(
+				"Metrics dispatcher: Failed to send request:",
+				(e as Error).message
+			);
+		});
+	}
+}
+
+export type Properties = Record<string, unknown>;

package/src/metrics/metrics-usage-headers.ts

@@ -0,0 +1,24 @@
+import { getMetricsConfig } from "./metrics-config";
+
+/**
+ * Add an additional header to publish requests if the user has opted into sending usage metrics.
+ *
+ * This allows us to estimate the number of instances of Wrangler that have opted-in
+ * without breaking our agreement not to send stuff if you have not opted-in.
+ */
+export async function getMetricsUsageHeaders(
+	sendMetrics: boolean | undefined
+): Promise<Record<string, string> | undefined> {
+	const metricsEnabled = (
+		await getMetricsConfig({
+			sendMetrics,
+		})
+	).enabled;
+	if (metricsEnabled) {
+		return {
+			metricsEnabled: "true",
+		};
+	} else {
+		return undefined;
+	}
+}

package/src/metrics/send-event.ts

@@ -0,0 +1,96 @@
+import { logger } from "../logger";
+import { getMetricsDispatcher } from "./metrics-dispatcher";
+import type { MetricsConfigOptions } from "./metrics-config";
+import type { Properties } from "./metrics-dispatcher";
+
+/** These are event names used by this wrangler client. */
+export type EventNames =
+	| "view accounts"
+	| "deploy worker script"
+	| "delete worker script"
+	| "begin log stream"
+	| "end log stream"
+	| "begin pages log stream"
+	| "end pages log stream"
+	| "create encrypted variable"
+	| "delete encrypted variable"
+	| "list encrypted variables"
+	| "create kv namespace"
+	| "list kv namespaces"
+	| "delete kv namespace"
+	| "write kv key-value"
+	| "list kv keys"
+	| "read kv value"
+	| "delete kv key-value"
+	| "write kv key-values (bulk)"
+	| "delete kv key-values (bulk)"
+	| "create r2 bucket"
+	| "list r2 buckets"
+	| "delete r2 bucket"
+	| "login user"
+	| "logout user"
+	| "create pubsub namespace"
+	| "list pubsub namespaces"
+	| "delete pubsub namespace"
+	| "view pubsub namespace"
+	| "create pubsub broker"
+	| "update pubsub broker"
+	| "list pubsub brokers"
+	| "delete pubsub broker"
+	| "view pubsub broker"
+	| "issue pubsub broker credentials"
+	| "revoke pubsub broker credentials"
+	| "unrevoke pubsub broker credentials"
+	| "list pubsub broker revoked credentials"
+	| "list pubsub broker public-keys"
+	| "list dispatch namespaces"
+	| "view dispatch namespace"
+	| "create dispatch namespace"
+	| "delete dispatch namespace"
+	| "rename dispatch namespace"
+	| "create pages project"
+	| "list pages projects"
+	| "create pages deployment"
+	| "list pages deployments"
+	| "build pages functions"
+	| "run dev"
+	| "run dev (api)"
+	| "run pages dev";
+
+/**
+ * Send a metrics event, with no extra properties, to Cloudflare, if usage tracking is enabled.
+ *
+ * This overload assumes that you do not want to configure analytics with options.
+ */
+export function sendMetricsEvent(event: EventNames): Promise<void>;
+/**
+ * Send a metrics event, with no extra properties, to Cloudflare, if usage tracking is enabled.
+ */
+export function sendMetricsEvent(
+	event: EventNames,
+	options: MetricsConfigOptions
+): Promise<void>;
+/**
+ * Send a metrics event to Cloudflare, if usage tracking is enabled.
+ *
+ * Generally you should pass the `send_metrics` property from the wrangler.toml config here,
+ * which would override any user permissions.
+ */
+export function sendMetricsEvent(
+	event: EventNames,
+	properties: Properties,
+	options: MetricsConfigOptions
+): Promise<void>;
+export async function sendMetricsEvent(
+	event: EventNames,
+	...args: [] | [MetricsConfigOptions] | [Properties, MetricsConfigOptions]
+): Promise<void> {
+	try {
+		const options = args.pop() ?? {};
+		const properties = (args.pop() ?? {}) as Properties;
+		const metricsDispatcher = await getMetricsDispatcher(options);
+		await metricsDispatcher.sendEvent(event, properties);
+	} catch (err) {
+		logger.debug("Error sending metrics event", err);
+	}
+}