wrangler 0.0.0-e2a26a0 → 0.0.0-e2b7352

package/src/bundle.ts

@@ -0,0 +1,155 @@
+import assert from "node:assert";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as esbuild from "esbuild";
+import createModuleCollector from "./module-collection";
+import type { Config } from "./config";
+import type { Entry } from "./entry";
+import type { CfModule } from "./worker";
+
+type BundleResult = {
+  modules: CfModule[];
+  resolvedEntryPointPath: string;
+  bundleType: "esm" | "commonjs";
+  stop: (() => void) | undefined;
+};
+
+/**
+ * Generate a bundle for the worker identified by the arguments passed in.
+ */
+export async function bundleWorker(
+  entry: Entry,
+  destination: string,
+  options: {
+    serveAssetsFromWorker: boolean;
+    jsxFactory: string | undefined;
+    jsxFragment: string | undefined;
+    rules: Config["rules"];
+    watch?: esbuild.WatchMode;
+    tsconfig: string | undefined;
+  }
+): Promise<BundleResult> {
+  const {
+    serveAssetsFromWorker,
+    jsxFactory,
+    jsxFragment,
+    rules,
+    watch,
+    tsconfig,
+  } = options;
+  const entryDirectory = path.dirname(entry.file);
+  const moduleCollector = createModuleCollector({
+    wrangler1xlegacyModuleReferences: {
+      rootDirectory: entryDirectory,
+      fileNames: new Set(
+        fs
+          .readdirSync(entryDirectory, { withFileTypes: true })
+          .filter(
+            (dirEntry) =>
+              dirEntry.isFile() && dirEntry.name !== path.basename(entry.file)
+          )
+          .map((dirEnt) => dirEnt.name)
+      ),
+    },
+    format: entry.format,
+    rules,
+  });
+  const result = await esbuild.build({
+    ...getEntryPoint(entry.file, serveAssetsFromWorker),
+    bundle: true,
+    absWorkingDir: entry.directory,
+    outdir: destination,
+    external: ["__STATIC_CONTENT_MANIFEST"],
+    format: "esm",
+    sourcemap: true,
+    metafile: true,
+    conditions: ["worker", "browser"],
+    ...(process.env.NODE_ENV && {
+      define: {
+        "process.env.NODE_ENV": `"${process.env.NODE_ENV}"`,
+      },
+    }),
+    loader: {
+      ".js": "jsx",
+      ".mjs": "jsx",
+      ".cjs": "jsx",
+    },
+    plugins: [moduleCollector.plugin],
+    ...(jsxFactory && { jsxFactory }),
+    ...(jsxFragment && { jsxFragment }),
+    ...(tsconfig && { tsconfig }),
+    watch,
+  });
+
+  const entryPointOutputs = Object.entries(result.metafile.outputs).filter(
+    ([_path, output]) => output.entryPoint !== undefined
+  );
+  assert(
+    entryPointOutputs.length > 0,
+    `Cannot find entry-point "${entry.file}" in generated bundle.` +
+      listEntryPoints(entryPointOutputs)
+  );
+  assert(
+    entryPointOutputs.length < 2,
+    "More than one entry-point found for generated bundle." +
+      listEntryPoints(entryPointOutputs)
+  );
+
+  const entryPointExports = entryPointOutputs[0][1].exports;
+  const bundleType = entryPointExports.length > 0 ? "esm" : "commonjs";
+
+  return {
+    modules: moduleCollector.modules,
+    resolvedEntryPointPath: path.resolve(
+      entry.directory,
+      entryPointOutputs[0][0]
+    ),
+    bundleType,
+    stop: result.stop,
+  };
+}
+
+type EntryPoint =
+  | { stdin: esbuild.StdinOptions; nodePaths: string[] }
+  | { entryPoints: string[] };
+
+/**
+ * Create an object that describes the entry point for esbuild.
+ *
+ * If we are using the experimental asset handling, then the entry point is
+ * actually a shim worker that will either return an asset from a KV store,
+ * or delegate to the actual worker.
+ */
+function getEntryPoint(
+  entryFile: string,
+  serveAssetsFromWorker: boolean
+): EntryPoint {
+  if (serveAssetsFromWorker) {
+    return {
+      stdin: {
+        contents: fs
+          .readFileSync(
+            path.join(__dirname, "../templates/static-asset-facade.js"),
+            "utf8"
+          )
+          .replace("__ENTRY_POINT__", entryFile),
+        sourcefile: "static-asset-facade.js",
+        resolveDir: path.dirname(entryFile),
+      },
+      nodePaths: [path.join(__dirname, "../vendor")],
+    };
+  } else {
+    return { entryPoints: [entryFile] };
+  }
+}
+
+/**
+ * Generate a string that describes the entry-points that were identified by esbuild.
+ */
+function listEntryPoints(
+  outputs: [string, ValueOf<esbuild.Metafile["outputs"]>][]
+): string {
+  return outputs.map(([_input, output]) => output.entryPoint).join("\n");
+}
+
+type ValueOf<T> = T[keyof T];

package/src/cfetch/index.ts

@@ -1,10 +1,11 @@
 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 { CF_API_BASE_URL } from "./internal";
+export { getCloudflareAPIBaseURL as getCloudflareApiBaseUrl } from "./internal";
 
 export interface FetchError {
   code: number;
@@ -81,11 +82,12 @@ function throwFetchError(
   resource: string,
   response: FetchResult<unknown>
 ): never {
-  response.messages.forEach((message) => console.warn(message));
-  const errors = response.errors
-    .map((error) => `${error.code}: ${error.message}`)
-    .join("\n");
-  const error = new Error(`Failed to fetch ${resource} - \n${errors}`);
+  const error = new ParseError({
+    text: "Received a bad response from the API",
+    notes: response.errors.map((err) => ({
+      text: err.code ? `${err.message} [code: ${err.code}]` : err.message,
+    })),
+  });
   // add the first error code directly to this error
   // so consumers can use it for specific behaviour
   const code = response.errors[0]?.code;

package/src/cfetch/internal.ts

@@ -1,10 +1,19 @@
-import { fetch } from "undici";
+import { fetch, Headers } from "undici";
+import { getEnvironmentVariableFactory } from "../environment-variables";
+import { ParseError, parseJSON } from "../parse";
+import { reportError } from "../reporting";
 import { getAPIToken, loginOrRefreshIfRequired } from "../user";
 import type { URLSearchParams } from "node:url";
 import type { RequestInit, HeadersInit } from "undici";
 
-export const CF_API_BASE_URL =
-  process.env.CF_API_BASE_URL || "https://api.cloudflare.com/client/v4";
+/**
+ * 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.
@@ -26,24 +35,50 @@ export async function fetchInternal<ResponseType>(
   addAuthorizationHeader(headers, apiToken);
 
   const queryString = queryParams ? `?${queryParams.toString()}` : "";
-  const response = await fetch(`${CF_API_BASE_URL}${resource}${queryString}`, {
-    method: "GET",
-    ...init,
-    headers,
-  });
+  const method = init.method ?? "GET";
+  const response = await fetch(
+    `${getCloudflareAPIBaseURL()}${resource}${queryString}`,
+    {
+      method,
+      ...init,
+      headers,
+    }
+  );
   const jsonText = await response.text();
   try {
-    const json = JSON.parse(jsonText);
-    return json as ResponseType;
-  } catch (e) {
-    throw new Error(
-      `Failed to fetch ${resource} - ${response.status}: ${response.statusText}\nInvalid JSON response:\n${jsonText}`
-    );
+    return parseJSON(jsonText) as ResponseType;
+  } catch (err) {
+    await reportError(err as Error);
+    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): HeadersInit {
-  return { ...headers };
+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> {
@@ -54,15 +89,18 @@ async function requireLoggedIn(): Promise<void> {
 }
 
 function requireApiToken(): string {
-  const apiToken = getAPIToken();
-  if (!apiToken) {
+  const authToken = getAPIToken();
+  if (!authToken) {
     throw new Error("No API token found.");
   }
-  return apiToken;
+  return authToken;
 }
 
-function addAuthorizationHeader(headers: HeadersInit, apiToken: string): void {
-  if (headers["Authorization"]) {
+function addAuthorizationHeader(
+  headers: Record<string, string>,
+  apiToken: string
+): void {
+  if ("Authorization" in headers) {
     throw new Error(
       "The request already specifies an authorisation header - cannot add a new one."
     );
@@ -86,7 +124,7 @@ export async function fetchKVGetValue(
   await requireLoggedIn();
   const apiToken = requireApiToken();
   const headers = { Authorization: `Bearer ${apiToken}` };
-  const resource = `${CF_API_BASE_URL}/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${key}`;
+  const resource = `${getCloudflareAPIBaseURL()}/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${key}`;
   const response = await fetch(resource, {
     method: "GET",
     headers,

package/src/cli.ts

@@ -1,6 +1,16 @@
+import process from "process";
 import { hideBin } from "yargs/helpers";
+import { reportError, initReporting } from "./reporting";
 import { main } from ".";
 
+try {
+  initReporting();
+} catch (error) {}
+
+process.on("uncaughtExceptionMonitor", async (err, origin) => {
+  await reportError(err, origin);
+});
+
 main(hideBin(process.argv)).catch(() => {
   // 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.

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 `console.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,218 @@
+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;
+
+  /**
+   * 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;
+}
+
+export interface DevConfig {
+  /**
+   * IP address for the local dev server to listen on,
+   *
+   * @default `localhost`
+   * @todo this needs to be implemented
+   */
+  ip: string;
+
+  /**
+   * Port for the local dev server to listen on
+   *
+   * @default `8787`
+   */
+  port: number;
+
+  /**
+   * Protocol that local wrangler dev server listens to requests on.
+   *
+   * @default `http`
+   * @todo this needs to be implemented
+   */
+  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`
+   */
+  upstream_protocol: "https" | "http";
+
+  /**
+   * Host to forward requests to, defaults to the zone 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;
+}
+
+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;
+  };
+}