wrangler 0.0.0-ece06ea → 0.0.0-ed4f2ef

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,229 @@
+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;
+
+  /**
+   * 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`
+   * @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;
+  };
+}

package/src/config/diagnostics.ts

@@ -0,0 +1,80 @@
+/**
+ * Diagnostic errors and warnings.
+ *
+ * The structure is a tree, where each node can contain zero or more errors, warnings and child diagnostics objects.
+ * You can check whether the overall tree has errors or warnings, and you can render a string representation of the errors or warnings.
+ */
+export class Diagnostics {
+  errors: string[] = [];
+  warnings: string[] = [];
+  children: Diagnostics[] = [];
+
+  /**
+   * Create a new Diagnostics object.
+   * @param description A general description of this collection of messages.
+   */
+  constructor(public description: string) {}
+
+  /**
+   * Merge the given `diagnostics` into this as a child.
+   */
+  addChild(diagnostics: Diagnostics): void {
+    if (diagnostics.hasErrors() || diagnostics.hasWarnings()) {
+      this.children.push(diagnostics);
+    }
+  }
+
+  /** Does this or any of its children have errors. */
+  hasErrors(): boolean {
+    if (this.errors.length > 0) {
+      return true;
+    } else {
+      return this.children.some((child) => child.hasErrors());
+    }
+  }
+
+  /** Render the errors of this and all its children. */
+  renderErrors(): string {
+    return this.render("errors");
+  }
+
+  /** Does this or any of its children have warnings. */
+  hasWarnings(): boolean {
+    if (this.warnings.length > 0) {
+      return true;
+    } else {
+      return this.children.some((child) => child.hasWarnings());
+    }
+  }
+
+  /** Render the warnings of this and all its children. */
+  renderWarnings(): string {
+    return this.render("warnings");
+  }
+
+  private render(field: "errors" | "warnings"): string {
+    const hasMethod = field === "errors" ? "hasErrors" : "hasWarnings";
+    return indentText(
+      `${this.description}\n` +
+        // Output all the fields (errors or warnings) at this level
+        this[field].map((message) => `- ${indentText(message)}`).join("\n") +
+        // Output all the child diagnostics at the next level
+        this.children
+          .map((child) =>
+            child[hasMethod]() ? "\n- " + child.render(field) : ""
+          )
+          .filter((output) => output !== "")
+          .join("\n")
+    );
+  }
+}
+
+/** Indent all the but the first line by two spaces. */
+function indentText(str: string): string {
+  return str
+    .split("\n")
+    .map((line, index) =>
+      (index === 0 ? line : `  ${line}`).replace(/^\s*$/, "")
+    )
+    .join("\n");
+}