wrangler 4.31.0 → 4.33.0

package/wrangler-dist/cli.d.ts

@@ -1,11 +1,11 @@
-import { Json, Request, Response as Response$1, DispatchFetch, NodeJSCompatMode, Miniflare, MiniflareOptions, Mutex, WorkerOptions, ModuleRule, RemoteProxyConnectionString } from 'miniflare';
+import { Json, Request, Response as Response$1, DispatchFetch, NodeJSCompatMode, Miniflare, WorkerRegistry, MiniflareOptions, Mutex, WorkerOptions, ModuleRule, RemoteProxyConnectionString } from 'miniflare';
 import * as undici from 'undici';
 import { RequestInfo, RequestInit, Response, FormData } from 'undici';
-import { CamelCaseKey, ArgumentsCamelCase, InferredOptionTypes, Alias, PositionalOptions, Options } from 'yargs';
+import { CamelCaseKey, Argv, PositionalOptions, Options, ArgumentsCamelCase, InferredOptionTypes, Alias } from 'yargs';
 import { RouterConfig, AssetConfig } from '@cloudflare/workers-shared';
+import { Metafile } from 'esbuild';
 import { EventEmitter } from 'node:events';
 import Protocol from 'devtools-protocol/types/protocol-mapping';
-import { Metafile } from 'esbuild';
 import { ContainerNormalizedConfig } from '@cloudflare/containers-shared';
 import { IncomingRequestCfProperties } from '@cloudflare/workers-types/experimental';
 import { URLSearchParams } from 'node:url';
@@ -150,11 +150,22 @@ type ContainerApp = {
         namespace_id: string;
     };
     /**
-     * How a rollout should be done, defining the size of it
+     * Configures what percentage of instances should be updated at each step of a rollout.
+     * You can specify this as a single number, or an array of numbers.
+     *
+     * If this is a single number, each step will progress by that percentage.
+     * The options are 5, 10, 20, 25, 50 or 100.
+     *
+     * If this is an array, each step specifies the cumulative rollout progress.
+     * The final step must be 100.
+     *
+     * This can be overridden adhoc by deploying with the `--containers-rollout=immediate` flag,
+     * which will roll out to 100% of instances in one step.
+     *
      * @optional
-     * @default 25
+     * @default [10,100]
      * */
-    rollout_step_percentage?: number;
+    rollout_step_percentage?: number | number[];
     /**
      * How a rollout should be created. It supports the following modes:
      *  - full_auto: The container application will be rolled out fully automatically.
@@ -162,6 +173,7 @@ type ContainerApp = {
      *  - manual: The container application will be rollout fully by manually actioning progress steps.
      * @optional
      * @default "full_auto"
+     * @hidden
      */
     rollout_kind?: "full_auto" | "none" | "full_manual";
     /**
@@ -770,9 +782,18 @@ interface EnvironmentNonInheritable {
     services: {
         /** The binding name used to refer to the bound service. */
         binding: string;
-        /** The name of the service. */
+        /**
+         * The name of the service.
+         * To bind to a worker in a specific environment,
+         * you should use the format `<worker_name>-<environment_name>`.
+         */
         service: string;
-        /** The environment of the service (e.g. production, staging, etc). */
+        /**
+         * @hidden
+         * @deprecated you should use `service: <worker_name>-<environment_name>` instead.
+         * This refers to the deprecated concept of 'service environments'.
+         * The environment of the service (e.g. production, staging, etc).
+         */
         environment?: string;
         /** Optionally, the entrypoint (named export) of the service to bind to. */
         entrypoint?: string;
@@ -1065,6 +1086,239 @@ type ContainerEngine = {
     localDocker: DockerConfiguration;
 } | string;
 
+/**
+ * A symbol to inherit a binding from the deployed worker.
+ */
+declare const INHERIT_SYMBOL: unique symbol;
+
+/**
+ * The type of Worker
+ */
+type CfScriptFormat = "modules" | "service-worker";
+/**
+ * A module type.
+ */
+type CfModuleType = "esm" | "commonjs" | "compiled-wasm" | "text" | "buffer" | "python" | "python-requirement";
+/**
+ * An imported module.
+ */
+interface CfModule {
+    /**
+     * The module name.
+     *
+     * @example
+     * './src/index.js'
+     */
+    name: string;
+    /**
+     * The absolute path of the module on disk, or `undefined` if this is a
+     * virtual module. Used as the source URL for this module, so source maps are
+     * correctly resolved.
+     *
+     * @example
+     * '/path/to/src/index.js'
+     */
+    filePath: string | undefined;
+    /**
+     * The module content, usually JavaScript or WASM code.
+     *
+     * @example
+     * export default {
+     *   async fetch(request) {
+     *     return new Response('Ok')
+     *   }
+     * }
+     */
+    content: string | Buffer<ArrayBuffer>;
+    /**
+     * An optional sourcemap for this module if it's of a ESM or CJS type, this will only be present
+     * if we're deploying with sourcemaps enabled. Since we copy extra modules that aren't bundled
+     * we need to also copy the relevant sourcemaps into the final out directory.
+     */
+    sourceMap?: CfWorkerSourceMap;
+    /**
+     * The module type.
+     *
+     * If absent, will default to the main module's type.
+     */
+    type?: CfModuleType;
+}
+/**
+ * A KV namespace.
+ */
+interface CfKvNamespace {
+    binding: string;
+    id?: string | typeof INHERIT_SYMBOL;
+    experimental_remote?: boolean;
+    raw?: boolean;
+}
+/**
+ * A binding to send email.
+ */
+type CfSendEmailBindings = {
+    name: string;
+    experimental_remote?: boolean;
+} & ({
+    destination_address?: string;
+} | {
+    allowed_destination_addresses?: string[];
+});
+/**
+ * A binding to the AI project
+ */
+interface CfAIBinding {
+    binding: string;
+    staging?: boolean;
+    experimental_remote?: boolean;
+    raw?: boolean;
+}
+/**
+ * A Durable Object.
+ */
+interface CfDurableObject {
+    name: string;
+    class_name: string;
+    script_name?: string;
+    environment?: string;
+}
+interface CfWorkflow {
+    name: string;
+    class_name: string;
+    binding: string;
+    script_name?: string;
+    experimental_remote?: boolean;
+    raw?: boolean;
+}
+interface CfQueue {
+    binding: string;
+    queue_name: string;
+    delivery_delay?: number;
+    experimental_remote?: boolean;
+    raw?: boolean;
+}
+interface CfR2Bucket {
+    binding: string;
+    bucket_name?: string | typeof INHERIT_SYMBOL;
+    jurisdiction?: string;
+    experimental_remote?: boolean;
+    raw?: boolean;
+}
+interface CfD1Database {
+    binding: string;
+    database_id?: string | typeof INHERIT_SYMBOL;
+    database_name?: string;
+    preview_database_id?: string;
+    database_internal_env?: string;
+    migrations_table?: string;
+    migrations_dir?: string;
+    experimental_remote?: boolean;
+    raw?: boolean;
+}
+interface CfVectorize {
+    binding: string;
+    index_name: string;
+    raw?: boolean;
+    experimental_remote?: boolean;
+}
+interface CfSecretsStoreSecrets {
+    binding: string;
+    store_id: string;
+    secret_name: string;
+}
+interface CfHelloWorld {
+    binding: string;
+    enable_timer?: boolean;
+}
+interface CfHyperdrive {
+    binding: string;
+    id: string;
+    localConnectionString?: string;
+}
+interface CfService {
+    binding: string;
+    service: string;
+    environment?: string;
+    entrypoint?: string;
+    props?: Record<string, unknown>;
+    experimental_remote?: boolean;
+}
+interface CfAnalyticsEngineDataset {
+    binding: string;
+    dataset?: string;
+}
+interface CfDispatchNamespace {
+    binding: string;
+    namespace: string;
+    outbound?: {
+        service: string;
+        environment?: string;
+        parameters?: string[];
+    };
+    experimental_remote?: boolean;
+}
+interface CfMTlsCertificate {
+    binding: string;
+    certificate_id: string;
+    experimental_remote?: boolean;
+}
+interface CfLogfwdrBinding {
+    name: string;
+    destination: string;
+}
+interface CfPipeline {
+    binding: string;
+    pipeline: string;
+    experimental_remote?: boolean;
+}
+interface CfUnsafeBinding {
+    name: string;
+    type: string;
+}
+type CfUnsafeMetadata = Record<string, unknown>;
+type CfCapnp = {
+    base_path?: never;
+    source_schemas?: never;
+    compiled_schema: string;
+} | {
+    base_path: string;
+    source_schemas: string[];
+    compiled_schema?: never;
+};
+interface CfUnsafe {
+    bindings: CfUnsafeBinding[] | undefined;
+    metadata: CfUnsafeMetadata | undefined;
+    capnp: CfCapnp | undefined;
+}
+interface CfTailConsumer {
+    service: string;
+    environment?: string;
+}
+interface CfWorkerSourceMap {
+    /**
+     * The name of the source map.
+     *
+     * @example
+     * 'out.js.map'
+     */
+    name: string;
+    /**
+     * The content of the source map, which is a JSON object described by the v3
+     * spec.
+     *
+     * @example
+     * {
+     *   "version" : 3,
+     *   "file": "out.js",
+     *   "sourceRoot": "",
+     *   "sources": ["foo.js", "bar.js"],
+     *   "sourcesContent": [null, null],
+     *   "names": ["src", "maps", "are", "fun"],
+     *   "mappings": "A,AAAB;;ABCDE;"
+     * }
+     */
+    content: string | Buffer;
+}
+
 /**
  * This is the static type definition for the configuration object.
  *
@@ -1308,6 +1562,7 @@ interface CommonYargsOptions {
     "experimental-provision": boolean | undefined;
     "experimental-remote-bindings": boolean | undefined;
 }
+type CommonYargsArgv = Argv<CommonYargsOptions>;
 type RemoveIndex<T> = {
     [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
 };
@@ -1346,243 +1601,10 @@ declare const experimental_readRawConfig: (args: ReadConfigCommandArgs, options?
     userConfigPath: string | undefined;
 };
 
-/**
- * A symbol to inherit a binding from the deployed worker.
- */
-declare const INHERIT_SYMBOL: unique symbol;
-
-/**
- * The type of Worker
- */
-type CfScriptFormat = "modules" | "service-worker";
-/**
- * A module type.
- */
-type CfModuleType = "esm" | "commonjs" | "compiled-wasm" | "text" | "buffer" | "python" | "python-requirement";
-/**
- * An imported module.
- */
-interface CfModule {
-    /**
-     * The module name.
-     *
-     * @example
-     * './src/index.js'
-     */
-    name: string;
-    /**
-     * The absolute path of the module on disk, or `undefined` if this is a
-     * virtual module. Used as the source URL for this module, so source maps are
-     * correctly resolved.
-     *
-     * @example
-     * '/path/to/src/index.js'
-     */
-    filePath: string | undefined;
-    /**
-     * The module content, usually JavaScript or WASM code.
-     *
-     * @example
-     * export default {
-     *   async fetch(request) {
-     *     return new Response('Ok')
-     *   }
-     * }
-     */
-    content: string | Buffer<ArrayBuffer>;
-    /**
-     * An optional sourcemap for this module if it's of a ESM or CJS type, this will only be present
-     * if we're deploying with sourcemaps enabled. Since we copy extra modules that aren't bundled
-     * we need to also copy the relevant sourcemaps into the final out directory.
-     */
-    sourceMap?: CfWorkerSourceMap;
-    /**
-     * The module type.
-     *
-     * If absent, will default to the main module's type.
-     */
-    type?: CfModuleType;
-}
-/**
- * A KV namespace.
- */
-interface CfKvNamespace {
-    binding: string;
-    id?: string | typeof INHERIT_SYMBOL;
-    experimental_remote?: boolean;
-    raw?: boolean;
-}
-/**
- * A binding to send email.
- */
-type CfSendEmailBindings = {
-    name: string;
-    experimental_remote?: boolean;
-} & ({
-    destination_address?: string;
-} | {
-    allowed_destination_addresses?: string[];
-});
-/**
- * A binding to the AI project
- */
-interface CfAIBinding {
-    binding: string;
-    staging?: boolean;
-    experimental_remote?: boolean;
-    raw?: boolean;
-}
-/**
- * A Durable Object.
- */
-interface CfDurableObject {
-    name: string;
-    class_name: string;
-    script_name?: string;
-    environment?: string;
-}
-interface CfWorkflow {
-    name: string;
-    class_name: string;
-    binding: string;
-    script_name?: string;
-    experimental_remote?: boolean;
-    raw?: boolean;
-}
-interface CfQueue {
-    binding: string;
-    queue_name: string;
-    delivery_delay?: number;
-    experimental_remote?: boolean;
-    raw?: boolean;
-}
-interface CfR2Bucket {
-    binding: string;
-    bucket_name?: string | typeof INHERIT_SYMBOL;
-    jurisdiction?: string;
-    experimental_remote?: boolean;
-    raw?: boolean;
-}
-interface CfD1Database {
-    binding: string;
-    database_id?: string | typeof INHERIT_SYMBOL;
-    database_name?: string;
-    preview_database_id?: string;
-    database_internal_env?: string;
-    migrations_table?: string;
-    migrations_dir?: string;
-    experimental_remote?: boolean;
-    raw?: boolean;
-}
-interface CfVectorize {
-    binding: string;
-    index_name: string;
-    raw?: boolean;
-    experimental_remote?: boolean;
-}
-interface CfSecretsStoreSecrets {
-    binding: string;
-    store_id: string;
-    secret_name: string;
-}
-interface CfHelloWorld {
-    binding: string;
-    enable_timer?: boolean;
-}
-interface CfHyperdrive {
-    binding: string;
-    id: string;
-    localConnectionString?: string;
-}
-interface CfService {
-    binding: string;
-    service: string;
-    environment?: string;
-    entrypoint?: string;
-    props?: Record<string, unknown>;
-    experimental_remote?: boolean;
-}
-interface CfAnalyticsEngineDataset {
-    binding: string;
-    dataset?: string;
-}
-interface CfDispatchNamespace {
-    binding: string;
-    namespace: string;
-    outbound?: {
-        service: string;
-        environment?: string;
-        parameters?: string[];
-    };
-    experimental_remote?: boolean;
-}
-interface CfMTlsCertificate {
-    binding: string;
-    certificate_id: string;
-    experimental_remote?: boolean;
-}
-interface CfLogfwdrBinding {
-    name: string;
-    destination: string;
-}
-interface CfPipeline {
-    binding: string;
-    pipeline: string;
-    experimental_remote?: boolean;
-}
-interface CfUnsafeBinding {
-    name: string;
-    type: string;
-}
-type CfUnsafeMetadata = Record<string, unknown>;
-type CfCapnp = {
-    base_path?: never;
-    source_schemas?: never;
-    compiled_schema: string;
-} | {
-    base_path: string;
-    source_schemas: string[];
-    compiled_schema?: never;
-};
-interface CfUnsafe {
-    bindings: CfUnsafeBinding[] | undefined;
-    metadata: CfUnsafeMetadata | undefined;
-    capnp: CfCapnp | undefined;
-}
-interface CfTailConsumer {
-    service: string;
-    environment?: string;
-}
-interface CfWorkerSourceMap {
-    /**
-     * The name of the source map.
-     *
-     * @example
-     * 'out.js.map'
-     */
-    name: string;
-    /**
-     * The content of the source map, which is a JSON object described by the v3
-     * spec.
-     *
-     * @example
-     * {
-     *   "version" : 3,
-     *   "file": "out.js",
-     *   "sourceRoot": "",
-     *   "sources": ["foo.js", "bar.js"],
-     *   "sourcesContent": [null, null],
-     *   "names": ["src", "maps", "are", "fun"],
-     *   "mappings": "A,AAAB;;ABCDE;"
-     * }
-     */
-    content: string | Buffer;
-}
-
-interface EnablePagesAssetsServiceBindingOptions {
-    proxyPort?: number;
-    directory?: string;
-}
+interface EnablePagesAssetsServiceBindingOptions {
+    proxyPort?: number;
+    directory?: string;
+}
 
 interface Unstable_DevOptions {
     config?: string;
@@ -1777,6 +1799,7 @@ declare function deploy({ directory, accountId, projectName, branch, skipCaching
         modified_on: string;
         short_id: string;
         build_image_major_version: number;
+        kv_namespaces?: any;
         source?: {
             type: "github" | "gitlab";
             config: {
@@ -1791,7 +1814,6 @@ declare function deploy({ directory, accountId, projectName, branch, skipCaching
                 preview_branch_excludes?: string[] | undefined;
             };
         } | undefined;
-        kv_namespaces?: any;
         env_vars?: any;
         durable_object_namespaces?: any;
         is_skipped?: boolean | undefined;
@@ -1811,26 +1833,6 @@ declare const unstable_pages: {
  */
 type ComplianceConfig = Partial<Pick<Config, "compliance_region">>;
 
-type WorkerRegistry = Record<string, WorkerDefinition>;
-type WorkerEntrypointsDefinition = Record<"default" | string, {
-    host: string;
-    port: number;
-} | undefined>;
-type WorkerDefinition = {
-    port: number | undefined;
-    protocol: "http" | "https" | undefined;
-    host: string | undefined;
-    mode: "local" | "remote";
-    headers?: Record<string, string>;
-    entrypointAddresses?: WorkerEntrypointsDefinition;
-    durableObjects: {
-        name: string;
-        className: string;
-    }[];
-    durableObjectsHost?: string;
-    durableObjectsPort?: number;
-};
-
 type _Params<ParamsArray extends [unknown?]> = ParamsArray extends [infer P] ? P : undefined;
 type _EventMethods = keyof Protocol.Events;
 type DevToolsEvent<Method extends _EventMethods> = Method extends unknown ? {
@@ -1948,6 +1950,7 @@ declare class ConfigController extends Controller<ConfigControllerEventMap> {
     latestConfig?: StartDevWorkerOptions;
     set(input: StartDevWorkerInput, throwErrors?: boolean): Promise<StartDevWorkerOptions | undefined>;
     patch(input: Partial<StartDevWorkerInput>): Promise<StartDevWorkerOptions | undefined>;
+    onDevRegistryUpdate(event: DevRegistryUpdateEvent): void;
     teardown(): Promise<void>;
     emitConfigUpdateEvent(config: StartDevWorkerOptions): void;
 }
@@ -2073,8 +2076,6 @@ interface StartDevWorkerInput {
         outboundService?: ServiceFetch;
         /** An undici MockAgent to declaratively mock fetch calls to particular resources. */
         mockFetch?: undici.MockAgent;
-        /** Describes the registry of other Workers running locally */
-        registry?: WorkerRegistry | null;
         testScheduled?: boolean;
         /** Whether to use Vectorize as a remote binding -- the worker is run locally but accesses to Vectorize are made remotely */
         bindVectorizeToProd?: boolean;
@@ -2087,6 +2088,8 @@ interface StartDevWorkerInput {
         containerBuildId?: string;
         /** Whether to build and connect to containers during local dev. Requires Docker daemon to be running. Defaults to true. */
         enableContainers?: boolean;
+        /** Path to the dev registry directory */
+        registry?: string;
         /** Path to the docker executable. Defaults to 'docker' */
         dockerPath?: string;
         /** Options for the container engine */
@@ -2262,6 +2265,10 @@ type ReloadCompleteEvent = {
     bundle: Bundle;
     proxyData: ProxyData;
 };
+type DevRegistryUpdateEvent = {
+    type: "devRegistryUpdate";
+    registry: WorkerRegistry;
+};
 type PreviewTokenExpiredEvent = {
     type: "previewTokenExpired";
     proxyData: ProxyData;
@@ -2324,8 +2331,6 @@ type ProxyData = {
     headers: Record<string, string>;
     liveReload?: boolean;
     proxyLogsToController?: boolean;
-    internalDurableObjects?: CfDurableObject[];
-    entrypointAddresses: WorkerEntrypointsDefinition | undefined;
 };
 
 interface TypedEventEmitter<EventMap extends Record<string | symbol, unknown[]>> extends EventEmitter {
@@ -2354,6 +2359,7 @@ declare abstract class Controller<EventMap extends ControllerEventMap = Controll
 type RuntimeControllerEventMap = ControllerEventMap & {
     reloadStart: [ReloadStartEvent];
     reloadComplete: [ReloadCompleteEvent];
+    devRegistryUpdate: [DevRegistryUpdateEvent];
 };
 declare abstract class RuntimeController extends Controller<RuntimeControllerEventMap> {
     abstract onBundleStart(_: BundleStartEvent): void;
@@ -2908,13 +2914,100 @@ type DefinitionTreeNode = {
 };
 type DefinitionTree = Map<string, DefinitionTreeNode>;
 
+type CreateCommandResult<NamedArgDefs extends NamedArgDefinitions> = DeepFlatten<{
+    args: HandlerArgs<NamedArgDefs>;
+}>;
+
+/**
+ * Class responsible for registering and managing commands within a command registry.
+ */
+declare class CommandRegistry {
+    #private;
+    /**
+     * Initializes the command registry with the given command registration function.
+     */
+    constructor(registerCommand: RegisterCommand);
+    /**
+     * Defines multiple commands and their corresponding definitions.
+     */
+    define(defs: {
+        command: Command;
+        definition: AliasDefinition | CreateCommandResult<NamedArgDefinitions> | NamespaceDefinition;
+    }[]): void;
+    getDefinitionTreeRoot(): DefinitionTreeNode;
+    /**
+     * Registers all commands in the command registry, walking through the definition tree.
+     */
+    registerAll(): void;
+    /**
+     * Registers a specific namespace if not already registered.
+     * TODO: Remove this once all commands use the command registry.
+     * See https://github.com/cloudflare/workers-sdk/pull/7357#discussion_r1862138470 for more details.
+     */
+    registerNamespace(namespace: string): void;
+}
+/**
+ * Type for the function used to register commands.
+ */
+type RegisterCommand = (segment: string, def: InternalDefinition, registerSubTreeCallback: () => void) => void;
+
+declare function createCLIParser(argv: string[]): {
+    wrangler: CommonYargsArgv;
+    registry: CommandRegistry;
+    globalFlags: {
+        readonly v: {
+            readonly describe: "Show version number";
+            readonly alias: "version";
+            readonly type: "boolean";
+        };
+        readonly cwd: {
+            readonly describe: "Run as if Wrangler was started in the specified directory instead of the current working directory";
+            readonly type: "string";
+            readonly requiresArg: true;
+        };
+        readonly config: {
+            readonly alias: "c";
+            readonly describe: "Path to Wrangler configuration file";
+            readonly type: "string";
+            readonly requiresArg: true;
+        };
+        readonly env: {
+            readonly alias: "e";
+            readonly describe: "Environment to use for operations, and for selecting .env and .dev.vars files";
+            readonly type: "string";
+            readonly requiresArg: true;
+        };
+        readonly "env-file": {
+            readonly describe: "Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files";
+            readonly type: "string";
+            readonly array: true;
+            readonly requiresArg: true;
+        };
+        readonly "experimental-remote-bindings": {
+            readonly describe: "Experimental: Enable Remote Bindings";
+            readonly type: "boolean";
+            readonly hidden: true;
+            readonly alias: readonly ["x-remote-bindings"];
+        };
+        readonly "experimental-provision": {
+            readonly describe: "Experimental: Enable automatic resource provisioning";
+            readonly type: "boolean";
+            readonly hidden: true;
+            readonly alias: readonly ["x-provision"];
+        };
+    };
+};
+
 /**
  * EXPERIMENTAL: Get all registered Wrangler commands for documentation generation.
  * This API is experimental and may change without notice.
  *
- * @returns The complete command tree structure with all metadata
+ * @returns An object containing the command tree structure and global flags
  */
-declare function experimental_getWranglerCommands(): DefinitionTreeNode;
+declare function experimental_getWranglerCommands(): {
+    registry: DefinitionTreeNode;
+    globalFlags: ReturnType<typeof createCLIParser>["globalFlags"];
+};
 
 interface Unstable_ASSETSBindingsOptions {
     log: Logger;