wrangler 0.0.0-ece06ea → 0.0.0-ecfbb0c

package/src/cfetch/index.ts

@@ -0,0 +1,121 @@
+import { URLSearchParams } from "node:url";
+import { ParseError } from "../parse";
+import { fetchInternal } from "./internal";
+import type { RequestInit } from "undici";
+
+// Check out https://api.cloudflare.com/ for API docs.
+
+export { getCloudflareAPIBaseURL as getCloudflareApiBaseUrl } from "./internal";
+
+export interface FetchError {
+	code: number;
+	message: string;
+	error_chain?: FetchError[];
+}
+export interface FetchResult<ResponseType = unknown> {
+	success: boolean;
+	result: ResponseType;
+	errors: FetchError[];
+	messages: string[];
+	result_info?: unknown;
+}
+
+export { fetchKVGetValue } from "./internal";
+
+/**
+ * Make a fetch request, and extract the `result` from the JSON response.
+ */
+export async function fetchResult<ResponseType>(
+	resource: string,
+	init: RequestInit = {},
+	queryParams?: URLSearchParams,
+	abortSignal?: AbortSignal
+): Promise<ResponseType> {
+	const json = await fetchInternal<FetchResult<ResponseType>>(
+		resource,
+		init,
+		queryParams,
+		abortSignal
+	);
+	if (json.success) {
+		return json.result;
+	} else {
+		throwFetchError(resource, json);
+	}
+}
+
+/**
+ * Make a fetch request for a list of values,
+ * extracting the `result` from the JSON response,
+ * and repeating the request if the results are paginated.
+ */
+export async function fetchListResult<ResponseType>(
+	resource: string,
+	init: RequestInit = {},
+	queryParams?: URLSearchParams
+): Promise<ResponseType[]> {
+	const results: ResponseType[] = [];
+	let getMoreResults = true;
+	let cursor: string | undefined;
+	while (getMoreResults) {
+		if (cursor) {
+			queryParams = new URLSearchParams(queryParams);
+			queryParams.set("cursor", cursor);
+		}
+		const json = await fetchInternal<FetchResult<ResponseType[]>>(
+			resource,
+			init,
+			queryParams
+		);
+		if (json.success) {
+			results.push(...json.result);
+			if (hasCursor(json.result_info)) {
+				cursor = json.result_info?.cursor;
+			} else {
+				getMoreResults = false;
+			}
+		} else {
+			throwFetchError(resource, json);
+		}
+	}
+	return results;
+}
+
+function throwFetchError(
+	resource: string,
+	response: FetchResult<unknown>
+): never {
+	const error = new ParseError({
+		text: `A request to the Cloudflare API (${resource}) failed.`,
+		notes: response.errors.map((err) => ({
+			text: renderError(err),
+		})),
+	});
+	// add the first error code directly to this error
+	// so consumers can use it for specific behaviour
+	const code = response.errors[0]?.code;
+	if (code) {
+		//@ts-expect-error non-standard property on Error
+		error.code = code;
+	}
+	throw error;
+}
+
+function hasCursor(result_info: unknown): result_info is { cursor: string } {
+	const cursor = (result_info as { cursor: string } | undefined)?.cursor;
+	return cursor !== undefined && cursor !== null && cursor !== "";
+}
+
+function renderError(err: FetchError, level = 0): string {
+	const chainedMessages =
+		err.error_chain
+			?.map(
+				(chainedError) =>
+					`\n${"  ".repeat(level)}- ${renderError(chainedError, level + 1)}`
+			)
+			.join("\n") ?? "";
+	return (
+		(err.code ? `${err.message} [code: ${err.code}]` : err.message) +
+		chainedMessages
+	);
+}

package/src/cfetch/internal.ts

@@ -0,0 +1,149 @@
+import assert from "node:assert";
+import { fetch, Headers } from "undici";
+import { version as wranglerVersion } from "../../package.json";
+import { getEnvironmentVariableFactory } from "../environment-variables";
+import { ParseError, parseJSON } from "../parse";
+import { loginOrRefreshIfRequired, requireApiToken } from "../user";
+import type { ApiCredentials } from "../user";
+import type { URLSearchParams } from "node:url";
+import type { RequestInit, HeadersInit } from "undici";
+
+/**
+ * Get the URL to use to access the Cloudflare API.
+ */
+export const getCloudflareAPIBaseURL = getEnvironmentVariableFactory({
+	variableName: "CLOUDFLARE_API_BASE_URL",
+	deprecatedName: "CF_API_BASE_URL",
+	defaultValue: "https://api.cloudflare.com/client/v4",
+});
+
+/**
+ * Make a fetch request to the Cloudflare API.
+ *
+ * This function handles acquiring the API token and logging the caller in, as necessary.
+ *
+ * Check out https://api.cloudflare.com/ for API docs.
+ *
+ * This function should not be used directly, instead use the functions in `cfetch/index.ts`.
+ */
+export async function fetchInternal<ResponseType>(
+	resource: string,
+	init: RequestInit = {},
+	queryParams?: URLSearchParams,
+	abortSignal?: AbortSignal
+): Promise<ResponseType> {
+	assert(
+		resource.startsWith("/"),
+		`CF API fetch - resource path must start with a "/" but got "${resource}"`
+	);
+	await requireLoggedIn();
+	const apiToken = requireApiToken();
+	const headers = cloneHeaders(init.headers);
+	addAuthorizationHeaderIfUnspecified(headers, apiToken);
+	addUserAgent(headers);
+
+	const queryString = queryParams ? `?${queryParams.toString()}` : "";
+	const method = init.method ?? "GET";
+	const response = await fetch(
+		`${getCloudflareAPIBaseURL()}${resource}${queryString}`,
+		{
+			method,
+			...init,
+			headers,
+			signal: abortSignal,
+		}
+	);
+	const jsonText = await response.text();
+	try {
+		return parseJSON<ResponseType>(jsonText);
+	} catch (err) {
+		throw new ParseError({
+			text: "Received a malformed response from the API",
+			notes: [
+				{
+					text: truncate(jsonText, 100),
+				},
+				{
+					text: `${method} ${resource} -> ${response.status} ${response.statusText}`,
+				},
+			],
+		});
+	}
+}
+
+function truncate(text: string, maxLength: number): string {
+	const { length } = text;
+	if (length <= maxLength) {
+		return text;
+	}
+	return `${text.substring(0, maxLength)}... (length = ${length})`;
+}
+
+function cloneHeaders(
+	headers: HeadersInit | undefined
+): Record<string, string> {
+	return headers instanceof Headers
+		? Object.fromEntries(headers.entries())
+		: Array.isArray(headers)
+		? Object.fromEntries(headers)
+		: { ...headers };
+}
+
+async function requireLoggedIn(): Promise<void> {
+	const loggedIn = await loginOrRefreshIfRequired();
+	if (!loggedIn) {
+		throw new Error("Not logged in.");
+	}
+}
+
+function addAuthorizationHeaderIfUnspecified(
+	headers: Record<string, string>,
+	auth: ApiCredentials
+): void {
+	if (!("Authorization" in headers)) {
+		if ("apiToken" in auth) {
+			headers["Authorization"] = `Bearer ${auth.apiToken}`;
+		} else {
+			headers["X-Auth-Key"] = auth.authKey;
+			headers["X-Auth-Email"] = auth.authEmail;
+		}
+	}
+}
+
+function addUserAgent(headers: Record<string, string>): void {
+	headers["User-Agent"] = `wrangler/${wranglerVersion}`;
+}
+
+/**
+ * The implementation for fetching a kv value from the cloudflare API.
+ * We special-case this one call, because it's the only API call that
+ * doesn't return json. We inline the implementation and try not to share
+ * any code with the other calls. We should push back on any new APIs that
+ * try to introduce non-"standard" response structures.
+ *
+ * Note: any calls to fetchKVGetValue must call encodeURIComponent on key
+ * before passing it
+ */
+
+export async function fetchKVGetValue(
+	accountId: string,
+	namespaceId: string,
+	key: string
+): Promise<ArrayBuffer> {
+	await requireLoggedIn();
+	const auth = requireApiToken();
+	const headers: Record<string, string> = {};
+	addAuthorizationHeaderIfUnspecified(headers, auth);
+	const resource = `${getCloudflareAPIBaseURL()}/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${key}`;
+	const response = await fetch(resource, {
+		method: "GET",
+		headers,
+	});
+	if (response.ok) {
+		return await response.arrayBuffer();
+	} else {
+		throw new Error(
+			`Failed to fetch ${resource} - ${response.status}: ${response.statusText});`
+		);
+	}
+}

package/src/cli.ts

@@ -1,10 +1,27 @@
+import "dotenv/config"; // Grab locally specified env params from a `.env` file.
+import process from "process";
+import { hideBin } from "yargs/helpers";
+import { unstable_dev } from "./api";
+import { FatalError } from "./errors";
 import { main } from ".";
 
-main(process.argv.slice(2)).catch((cause) => {
-  const { name, message } = cause;
-  if (name === "CloudflareError") {
-    console.error("\x1b[31m", message);
-    return;
-  }
-  throw cause;
-});
+/**
+ * The main entrypoint for the CLI.
+ * main only gets called when the script is run directly, not when it's imported as a module.
+ */
+if (require.main) {
+	main(hideBin(process.argv)).catch((e) => {
+		// The logging of any error that was thrown from `main()` is handled in the `yargs.fail()` handler.
+		// Here we just want to ensure that the process exits with a non-zero code.
+		// We don't want to do this inside the `main()` function, since that would kill the process when running our tests.
+		const exitCode = (e instanceof FatalError && e.code) || 1;
+		process.exit(exitCode);
+	});
+}
+
+/**
+ * This is how we're exporting the API.
+ * It makes it possible to import wrangler from 'wrangler',
+ * and call wrangler.unstable_dev().
+ */
+module.exports = { unstable_dev };

package/src/config/README.md

@@ -0,0 +1,107 @@
+# Configuration validation
+
+The files in this directory define and validate the configuration that is read from a `wrangler.toml` file.
+
+The configuration for a Worker is complicated since we can define different "environments", and each environment can have its own configuration.
+There is a default ("top-level") environment and then named environments that provide environment specific configuration.
+
+This is further complicated by the fact that there are three kinds of environment configuration:
+
+- **non-overridable**: these values are defined once in the top-level configuration, apply to all environments and cannot be overridden by an environment.
+- **inheritable**: these values can be defined at the top-level but can also be overridden by environment specific values.
+  Named environments do not need to provide their own values, in which case they inherit the value from the top-level.
+- **non-inheritable**: these values must be explicitly defined in each environment if they are defined at the top-level.
+  Named environments do not inherit such configuration and must provide their own values.
+
+All configuration values in `wrangler.toml` are optional and will receive a default value if not defined.
+
+## Types
+
+### Environment
+
+The fields that can be defined within the `env` containers are defined in the [`Environment`](./environment.ts) type.
+This includes the `EnvironmentInheritable` and `EnvironmentNonInheritable` fields.
+
+### Config
+
+The "non-overridable" types are defined in the [`ConfigFields`](./config.ts) type.
+The `Config` type is the overall configuration, which consists of the `ConfigFields` and also an `Environment`.
+In this case the `Environment`, here, corresponds to the "currently active" environment. This is specified by the `--env` command line argument.
+If there is no argument passed then the currently active environment is the "top-level" environment.
+The fields in `Config` and `Environment` are not generally optional and so you can expect they have been filled with suitable inherited or default values.
+These types should be used when you are working with fields that should be passed to commands.
+
+### RawConfig
+
+The `RawConfig` type is a version of `Config`, where all the fields are optional.
+The `RawConfig` type includes `DeprecatedConfigFields` and `EnvironmentMap`.
+It also extends the `RawEnvironment` type, which is a version of `Environment` where all the fields are optional.
+These optional fields map to the actual fields found in the `wrangler.toml`.
+These types should be used when you are working with raw configuration that is read or will be written to a `wrangler.toml`.
+
+## Validation
+
+Validation is triggered by passing a `RawConfig` object, and the active environment name, to the `normalizeAndValidateConfig()` function.
+This function will return:
+
+- a `Config` object, where all the fields have suitable valid values
+- a `Diagnostics` object, which contains any errors or warnings from the validation process
+
+The field values may have been parsed directly from the `RawConfig`, inherited into a named environment from the top-level environment, or given a default value.
+Generally, if there are any warnings they should be presented to the user via `logger.warn()` messages,
+and if there are any errors then an `Error` should be thrown describing these errors.
+
+The `Diagnostics` object is hierarchical: each `Diagnostics` instance can contain a collection of child `Diagnostics` instance.
+When checking for or rendering warnings and errors, the `Diagnostics` class will automatically traverse down to all its children.
+
+## Usage
+
+The [high level API](./index.ts) for configuration processing consists of the `findWranglerToml()` and `readConfig()` functions.
+
+### readConfig()
+
+The `readConfig()` function will find the nearest `wrangler.toml` file, load and parse it, then validate and normalize the values into a `Config` object.
+Note that you should pass the current active environment name in as a parameter. The resulting `Config` object will contain only the fields appropriate to that environment.
+If there are validation errors then it will throw a suitable error.
+
+## Changing configuration
+
+### Add a new configuration field
+
+When a new field needs to be added to the `wrangler.toml` configuration you will need to add to the types and validation code in this directory.
+
+Here are some steps that you should consider when doing this:
+
+- add the new field to one of the interface:
+  - if the field is not overridable in an environment then add it to the `ConfigFields` interface.
+  - if the field can be inherited and overridden in a named environment then add it to the `EnvironmentInheritable` interface.
+  - if the field cannot be inherited and must be specified in each named environment then add it to the `EnvironmentNonInheritable` interface.
+- if the field is experimental then add a call to the `experimental()` function:
+  - if the field is now in the `ConfigDeprecated` interface then add the call to the `normalizeAndValidateConfig()` function.
+  - if the field is now in the `EnvironmentDeprecated` interface then add the call to the `normalizeAndValidateEnvironment()` function.
+- add validation and normalization to the interface
+  - if the field is in `ConfigFields` then add validation calls to `normalizeAndValidateConfig()` and assign the normalized value to the appropriate property in the `config` object.
+  - if the field is in `EnvironmentInheritable` then call `inheritable()` in `normalizeAndValidateEnvironment()` and assign the normalized value to the appropriate property in the `environment` object.
+  - if the field is in `EnvironmentNonInheritable` then call `notInheritable()` in `normalizeAndValidateEnvironment()` and assign the normalized value to the appropriate property in the `environment` object.
+- update the tests in `configuration.test.ts`
+  - add to the `"should use defaults for empty configuration"` test to prove the correct default value is assigned
+  - if the field is in `ConfigFields` add tests to the `"top-level non-environment configuration"` block to check the validation and normalization of values
+  - if the field is in `EnvironmentInheritable` or `EnvironmentNonInheritable`
+    - add tests to the `"top-level environment configuration"` block to check the validation and normalization of values
+    - add tests to the `"named environment configuration"` block to check the inheritance of values
+
+### Remove a configuration field
+
+We should not just remove a field from use, since users would not know that this field is no longer needed, nor how to migrate to any new usage.
+Instead we should first deprecate it, and then then remove it in a future major release.
+
+- move the field to a deprecation interface:
+  - if the field was originally in `ConfigFields` then move it to the `ConfigDeprecated` interface.
+  - if the field was originally in either `EnvironmentInheritable` or `EnvironmentNonInheritable` then move it to the `EnvironmentDeprecatedInterface`.
+- remove the validation for the field
+  - the TypeScript compiler should indicate where there is now an unknown field, so that you can remove its validation and normalization from the code base.
+- add a deprecation warning by calling `deprecated()`
+  - if the field is now in the `ConfigDeprecated` interface then add the call to the `normalizeAndValidateConfig()` function.
+  - if the field is now in the `EnvironmentDeprecated` interface then add the call to the `normalizeAndValidateEnvironment()` function.
+- update the tests in `configuration.test.ts`
+  - Find tests where the field is mentioned and either remove them (e.g. validation) or update to show the deprecation message.

package/src/config/config.ts

@@ -0,0 +1,243 @@
+import type { Environment, RawEnvironment } from "./environment";
+
+/**
+ * This is the static type definition for the configuration object.
+ *
+ * It reflects a normalized and validated version of the configuration that you can write in wrangler.toml,
+ * and optionally augment with arguments passed directly to wrangler.
+ *
+ * For more information about the configuration object, see the
+ * documentation at https://developers.cloudflare.com/workers/cli-wrangler/configuration
+ *
+ * Notes:
+ *
+ * - Fields that are only specified in `ConfigFields` and not `Environment` can only appear
+ * in the top level config and should not appear in any environments.
+ * - All top level fields in config and environments are optional in the wrangler.toml file.
+ *
+ * Legend for the annotations:
+ *
+ * - `@breaking`: the deprecation/optionality is a breaking change from wrangler 1.
+ * - `@todo`: there's more work to be done (with details attached).
+ */
+export type Config = ConfigFields<DevConfig> & Environment;
+
+export type RawConfig = Partial<ConfigFields<RawDevConfig>> &
+	RawEnvironment &
+	DeprecatedConfigFields &
+	EnvironmentMap;
+
+export interface ConfigFields<Dev extends RawDevConfig> {
+	configPath: string | undefined;
+
+	/**
+	 * A boolean to enable "legacy" style wrangler environments (from wrangler 1).
+	 * These have been superseded by Services, but there may be projects that won't
+	 * (or can't) use them. If you're using a legacy environment, you can set this
+	 * to `true` to enable it.
+	 */
+	legacy_env: boolean;
+
+	/**
+	 * Options to configure the development server that your worker will use.
+	 */
+	dev: Dev;
+
+	/**
+	 * A list of migrations that should be uploaded with your Worker.
+	 *
+	 * These define changes in your Durable Object declarations.
+	 *
+	 * More details at https://developers.cloudflare.com/workers/learning/using-durable-objects#configuring-durable-object-classes-with-migrations
+	 *
+	 * @default `[]`
+	 */
+	migrations: {
+		/** A unique identifier for this migration. */
+		tag: string;
+		/** The new Durable Objects being defined. */
+		new_classes?: string[];
+		/** The Durable Objects being renamed. */
+		renamed_classes?: {
+			from: string;
+			to: string;
+		}[];
+		/** The Durable Objects being removed. */
+		deleted_classes?: string[];
+	}[];
+
+	/**
+	 * The definition of a Worker Site, a feature that lets you upload
+	 * static assets with your Worker.
+	 *
+	 * More details at https://developers.cloudflare.com/workers/platform/sites
+	 */
+	site:
+		| {
+				/**
+				 * The directory containing your static assets.
+				 *
+				 * It must be a path relative to your wrangler.toml file.
+				 * Example: bucket = "./public"
+				 *
+				 * If there is a `site` field then it must contain this `bucket` field.
+				 */
+				bucket: string;
+
+				/**
+				 * The location of your Worker script.
+				 *
+				 * @deprecated DO NOT use this (it's a holdover from wrangler 1.x). Either use the top level `main` field, or pass the path to your entry file as a command line argument.
+				 * @breaking
+				 */
+				"entry-point"?: string;
+
+				/**
+				 * An exclusive list of .gitignore-style patterns that match file
+				 * or directory names from your bucket location. Only matched
+				 * items will be uploaded. Example: include = ["upload_dir"]
+				 *
+				 * @optional
+				 * @default `[]`
+				 */
+				include?: string[];
+
+				/**
+				 * A list of .gitignore-style patterns that match files or
+				 * directories in your bucket that should be excluded from
+				 * uploads. Example: exclude = ["ignore_dir"]
+				 *
+				 * @optional
+				 * @default `[]`
+				 */
+				exclude?: string[];
+		  }
+		| undefined;
+
+	/**
+	 * Serve a folder of static assets with your Worker, without any additional code.
+	 * This can either be a string, or an object with additional config fields.
+	 */
+	assets:
+		| string
+		| { bucket: string; include: string[]; exclude: string[] }
+		| undefined;
+
+	/**
+	 * A list of wasm modules that your worker should be bound to. This is
+	 * the "legacy" way of binding to a wasm module. ES module workers should
+	 * do proper module imports.
+	 */
+	wasm_modules:
+		| {
+				[key: string]: string;
+		  }
+		| undefined;
+
+	/**
+	 * A list of text files that your worker should be bound to. This is
+	 * the "legacy" way of binding to a text file. ES module workers should
+	 * do proper module imports.
+	 */
+	text_blobs:
+		| {
+				[key: string]: string;
+		  }
+		| undefined;
+
+	/**
+	 * A list of data files that your worker should be bound to. This is
+	 * the "legacy" way of binding to a data file. ES module workers should
+	 * do proper module imports.
+	 */
+	data_blobs:
+		| {
+				[key: string]: string;
+		  }
+		| undefined;
+}
+
+export interface DevConfig {
+	/**
+	 * IP address for the local dev server to listen on,
+	 *
+	 * @default `localhost`
+	 */
+	ip: string;
+
+	/**
+	 * Port for the local dev server to listen on
+	 *
+	 * @default `8787`
+	 */
+	port: number | undefined;
+
+	/**
+	 * Protocol that local wrangler dev server listens to requests on.
+	 *
+	 * @default `http`
+	 */
+	local_protocol: "http" | "https";
+
+	/**
+	 * Protocol that wrangler dev forwards requests on
+	 *
+	 * Setting this to `http` is not currently implemented.
+	 * See https://github.com/cloudflare/wrangler2/issues/583
+	 *
+	 * @default `https`
+	 * @todo this needs to be implemented https://github.com/cloudflare/wrangler2/issues/583
+	 */
+	upstream_protocol: "https" | "http";
+
+	/**
+	 * Host to forward requests to, defaults to the host of the first route of project
+	 */
+	host: string | undefined;
+}
+
+export type RawDevConfig = Partial<DevConfig>;
+
+export interface DeprecatedConfigFields {
+	/**
+	 * The project "type". A holdover from wrangler 1.x.
+	 * Valid values were "webpack", "javascript", and "rust".
+	 *
+	 * @deprecated DO NOT USE THIS. Most common features now work out of the box with wrangler, including modules, jsx, typescript, etc. If you need anything more, use a custom build.
+	 * @breaking
+	 */
+	type?: "webpack" | "javascript" | "rust";
+
+	/**
+	 * Path to the webpack config to use when building your worker.
+	 * A holdover from wrangler 1.x, used with `type: "webpack"`.
+	 *
+	 * @deprecated DO NOT USE THIS. Most common features now work out of the box with wrangler, including modules, jsx, typescript, etc. If you need anything more, use a custom build.
+	 * @breaking
+	 */
+	webpack_config?: string;
+
+	/**
+	 * Configuration only used by a standalone use of the miniflare binary.
+	 * @deprecated
+	 */
+	miniflare?: unknown;
+}
+
+interface EnvironmentMap {
+	/**
+	 * The `env` section defines overrides for the configuration for different environments.
+	 *
+	 * All environment fields can be specified at the top level of the config indicating the default environment settings.
+	 *
+	 * - Some fields are inherited and overridable in each environment.
+	 * - But some are not inherited and must be explicitly specified in every environment, if they are specified at the top level.
+	 *
+	 * For more information, see the documentation at https://developers.cloudflare.com/workers/cli-wrangler/configuration#environments
+	 *
+	 * @default `{}`
+	 */
+	env?: {
+		[envName: string]: RawEnvironment;
+	};
+}