wrangler 0.0.0-e2a26a0 → 0.0.0-e3cab74

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.
+Notably this also contains a property called `env` which is the container for the named environment configuration.
+
+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 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 also includes `DeprecatedConfigFields` and extends and contains 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 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.
+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,265 @@
+import type { Environment, RawEnvironment } from "./environment";
+
+/**
+ * This is the static type definition for the configuration object.
+ *
+ * It reflects 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<Environment> & Environment;
+
+export type RawConfig = Partial<ConfigFields<RawEnvironment>> &
+  RawEnvironment &
+  DeprecatedConfigFields;
+
+export interface ConfigFields<Env extends RawEnvironment> {
+  configPath: string | undefined;
+
+  /**
+   * The entrypoint/path to the JavaScript file that will be executed.
+   */
+  main: 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;
+
+  /**
+   * 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]: Env;
+  };
+
+  /**
+   * Options to configure the development server that your worker will use.
+   *
+   * @default `{}`
+   */
+  dev: {
+    /**
+     * IP address for the local dev server to listen on,
+     *
+     * @default `127.0.0.1`
+     * @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?: string;
+
+    /**
+     * Protocol that wrangler dev forwards requests on
+     *
+     * @default `https`
+     * @todo this needs to be implemented
+     */
+    upstream_protocol?: string;
+  };
+
+  /**
+   * 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;
+
+  /**
+   * Configures a custom build step to be run by Wrangler when building your Worker.
+   *
+   * Refer to the [custom builds documentation](https://developers.cloudflare.com/workers/cli-wrangler/configuration#build)
+   * for more details.
+   *
+   * @default {}
+   */
+  build: {
+    /** The command used to build your Worker. On Linux and macOS, the command is executed in the `sh` shell and the `cmd` shell for Windows. The `&&` and `||` shell operators may be used. */
+    command?: string;
+    /** The directory in which the command is executed. */
+    cwd?: string;
+    /** The directory to watch for changes while using wrangler dev, defaults to the current working directory */
+    watch_dir?: string;
+    /** Deprecated field previously used to configure the build and upload of the script. */
+    upload?: DeprecatedUpload;
+  };
+}
+
+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;
+}
+
+/**
+ * Deprecated upload configuration.
+ */
+export interface DeprecatedUpload {
+  /**
+   * The format of the Worker script.
+   *
+   * @deprecated We infer the format automatically now.
+   */
+  format?: "modules" | "service-worker";
+
+  /**
+   * The directory you wish to upload your worker from,
+   * relative to the wrangler.toml file.
+   *
+   * Defaults to the directory containing the wrangler.toml file.
+   *
+   * @deprecated
+   * @breaking In wrangler 1, this defaults to ./dist, whereas in wrangler 2 it defaults to ./
+   */
+  dir?: string;
+
+  /**
+   * The path to the Worker script, relative to `upload.dir`.
+   *
+   * @deprecated This will be replaced by a command line argument.
+   */
+  main?: string;
+
+  /**
+   * @deprecated This is now defined at the top level `rules` field.
+   */
+  rules?: Environment["rules"];
+}

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");
+}