[wrangler] Add Durable Objects hibernation timeout option (#15658)

Co-authored-by: Christopher Little-Savage <clittle-savage@cloudflare.com>

Author: jqmmes

.changeset/quiet-dodos-hibernate.md

@@ -0,0 +1,9 @@
+---
+"wrangler": minor
+"@cloudflare/deploy-helpers": minor
+"@cloudflare/workers-utils": minor
+---
+
+Add Durable Objects code update strategies to Worker deployments
+
+Use `--durable-objects-code-update-mode immediate` with `wrangler deploy`, `wrangler versions deploy`, and `wrangler rollback` to update code without waiting for active instances to hibernate. Use `--durable-objects-code-update-mode deferred 30s` to set a maximum delay, or configure `durable_objects.code_update_strategy` with `mode` and `max_delay`. When unset, the strategy defaults to deferred with a 5-minute maximum delay; delays cannot exceed 24 hours and must use millisecond precision.

packages/deploy-helpers/src/deploy/deploy.ts

@@ -430,6 +430,9 @@ async function deployWorker(
 		props.containers.source === undefined &&
 		// Rollout skip can recover Container metadata absent from local config.
 		containerMetadata === undefined;
+	if (!canUseNewVersionsDeploymentsApi) {
+		worker.code_update_strategy = props.durableObjectsCodeUpdateStrategy;
+	}
 
 	let workerBundle: FormData;
 	const dockerPath = getDockerPath();
@@ -527,13 +530,20 @@ async function deployWorker(
 				// Deploy new version to 100%
 				const versionMap = new Map<VersionId, Percentage>();
 				versionMap.set(versionResult.id, 100);
+				const unsafeMetadata = config.unsafe?.metadata;
+				const codeUpdateStrategy =
+					unsafeMetadata !== undefined &&
+					"code_update_strategy" in unsafeMetadata
+						? unsafeMetadata.code_update_strategy
+						: props.durableObjectsCodeUpdateStrategy;
 				await createDeployment(
 					config,
 					accountId,
 					scriptName,
 					versionMap,
 					props.message,
-					undefined
+					undefined,
+					codeUpdateStrategy
 				);
 
 				// Update service and environment tags when using environments

packages/deploy-helpers/src/deploy/helpers/create-worker-upload-form.ts

@@ -68,6 +68,7 @@ export function createWorkerUploadForm(
 		main,
 		sourceMaps,
 		migrations,
+		code_update_strategy,
 		exports: configuredExports,
 		compatibility_date,
 		compatibility_flags,
@@ -882,6 +883,7 @@ export function createWorkerUploadForm(
 			compatibility_flags,
 		}),
 		...(migrations && { migrations }),
+		...(code_update_strategy && { code_update_strategy }),
 		...(configuredExports &&
 			Object.keys(configuredExports).length > 0 && {
 				exports: configuredExports,
@@ -911,7 +913,6 @@ export function createWorkerUploadForm(
 			metadata[key] = options.unsafe.metadata[key];
 		}
 	}
-
 	formData.set("metadata", JSON.stringify(metadata));
 
 	if (main.type === "commonjs" && modules && modules.length > 0) {

packages/deploy-helpers/src/deploy/helpers/versions-api.ts

@@ -135,8 +135,11 @@ export async function createDeployment(
 	workerName: string,
 	versionTraffic: Map<VersionId, Percentage>,
 	message: string | undefined,
-	force: boolean | undefined
+	force: boolean | undefined,
+	codeUpdateStrategy?: unknown
 ) {
+	// The generated Cloudflare SDK does not expose code_update_strategy yet.
+	// Keep this request here until the updated deployment schema reaches the SDK.
 	return await fetchResult<{ id: string }>(
 		complianceConfig,
 		`/accounts/${accountId}/workers/scripts/${workerName}/deployments${force ? "?force=true" : ""}`,
@@ -152,6 +155,7 @@ export async function createDeployment(
 				annotations: {
 					"workers/message": message,
 				},
+				code_update_strategy: codeUpdateStrategy,
 			}),
 		}
 	);

packages/deploy-helpers/src/shared/types.ts

@@ -18,6 +18,7 @@ import type {
 	Route,
 	Entry,
 	ContainerApp,
+	DurableObjectCodeUpdateStrategy,
 } from "@cloudflare/workers-utils";
 
 /** API, logging, and prompt implementations supplied by the consumer. */
@@ -154,6 +155,8 @@ export type DeployProps = SharedDeployVersionsProps & {
 	oldAssetTtl: number | undefined;
 	/** From --containers-rollout arg. Deploy-only. */
 	containersRollout: "immediate" | "gradual" | "none" | undefined;
+	/** Controls how Durable Object code updates are applied. */
+	durableObjectsCodeUpdateStrategy?: DurableObjectCodeUpdateStrategy;
 	/**
 	 * When true, an existing Worker with the same name aborts the deploy instead
 	 * of updating it, because this run cannot confirm the local project owns the

packages/workers-utils/src/config/environment.ts

@@ -933,6 +933,29 @@ export type DurableObjectBindings = {
 	environment?: string;
 }[];
 
+export type DurableObjectCodeUpdateStrategy = {
+	/** How Durable Object code updates should be applied. */
+	mode: "immediate" | "deferred";
+	/**
+	 * Maximum time, in seconds, to wait for Durable Objects to hibernate.
+	 * Defaults to 300 (5 minutes) and cannot exceed 86400 (24 hours).
+	 * @minimum 0
+	 * @maximum 86400
+	 * @multipleOf 0.001
+	 * @default 300
+	 */
+	max_delay?: number;
+};
+
+export type DurableObjectsConfig = {
+	bindings: DurableObjectBindings;
+	code_update_strategy?: DurableObjectCodeUpdateStrategy;
+};
+
+export type RawDurableObjectsConfig = Omit<DurableObjectsConfig, "bindings"> & {
+	bindings?: DurableObjectBindings;
+};
+
 export const ARTIFACTS_EVENT_TYPES = [
 	"cf.artifacts.repo.created",
 	"cf.artifacts.repo.deleted",
@@ -1064,7 +1087,7 @@ export interface EnvironmentNonInheritable {
 	};
 
 	/**
-	 * A list of durable objects that your Worker should be bound to.
+	 * Durable Object bindings and code update strategy for your Worker.
 	 *
 	 * For more information about Durable Objects, see the documentation at
 	 * https://developers.cloudflare.com/workers/learning/using-durable-objects
@@ -1077,9 +1100,7 @@ export interface EnvironmentNonInheritable {
 	 * @default {bindings:[]}
 	 * @nonInheritable
 	 */
-	durable_objects: {
-		bindings: DurableObjectBindings;
-	};
+	durable_objects: DurableObjectsConfig;
 
 	/**
 	 * A list of workflows that your Worker should be bound to.
@@ -1862,7 +1883,9 @@ export interface EnvironmentNonInheritable {
  * All the properties are optional, and will be replaced with defaults in the configuration that
  * is used in the rest of the codebase.
  */
-export type RawEnvironment = Partial<Environment>;
+export type RawEnvironment = Partial<Omit<Environment, "durable_objects">> & {
+	durable_objects?: RawDurableObjectsConfig;
+};
 
 /**
  * A bundling resolver rule, defining the modules type for paths that match the specified globs.
@@ -2033,10 +2056,12 @@ export type ContainerEngine =
  */
 export interface PreviewsConfig
 	extends
-		Partial<EnvironmentNonInheritable>,
+		Partial<Omit<EnvironmentNonInheritable, "durable_objects">>,
 		Partial<
 			Pick<
 				EnvironmentInheritable,
 				"logpush" | "observability" | "limits" | "placement" | "cache"
 			>
-		> {}
+		> {
+	durable_objects?: { bindings: DurableObjectBindings };
+}

packages/workers-utils/src/config/index.ts

@@ -33,6 +33,7 @@ export type {
 	CacheOptions,
 	ConfiguredExport,
 	ConfigModuleRuleType,
+	DurableObjectCodeUpdateStrategy,
 	Environment,
 	PreviewsConfig,
 	RawEnvironment,

packages/workers-utils/src/config/validation.ts

@@ -1695,18 +1695,22 @@ function normalizeAndValidateEnvironment(
 			validateDefines(envName),
 			{}
 		),
-		durable_objects: notInheritable(
-			diagnostics,
-			topLevelEnv,
-			rawConfig,
-			rawEnv,
-			envName,
-			"durable_objects",
-			validateBindingsProperty(envName, validateDurableObjectBinding),
-			{
-				bindings: [],
-			}
-		),
+		durable_objects: (() => {
+			const durableObjects = notInheritable(
+				diagnostics,
+				topLevelEnv,
+				rawConfig,
+				rawEnv,
+				envName,
+				"durable_objects",
+				validateDurableObjectsProperty(envName, true),
+				{ bindings: [] }
+			);
+			return {
+				...durableObjects,
+				bindings: durableObjects.bindings ?? [],
+			};
+		})(),
 		workflows: notInheritable(
 			diagnostics,
 			topLevelEnv,
@@ -2719,6 +2723,136 @@ const validateBindingsProperty =
 		return isValid;
 	};
 
+const DURABLE_OBJECTS_CODE_UPDATE_MAX_DELAY_SECONDS = 24 * 60 * 60;
+// Absorbs float64 error in the millisecond precision check. Near the 24-hour
+// maximum the error reaches ~1e-8 ms, so a tighter bound would reject valid
+// values such as 65536.001.
+const MILLISECOND_PRECISION_TOLERANCE = 1e-6;
+
+const validateDurableObjectsProperty =
+	(
+		envName: string,
+		allowMissingBindings = false,
+		allowCodeUpdateStrategy = true
+	): ValidatorFn =>
+	(diagnostics, field, value, config) => {
+		const fieldPath =
+			config === undefined ? `${field}` : `env.${envName}.${field}`;
+
+		if (value === undefined) {
+			return true;
+		}
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			diagnostics.errors.push(
+				`The field "${fieldPath}" should be an object but got ${JSON.stringify(value)}.`
+			);
+			return false;
+		}
+
+		validateAdditionalProperties(
+			diagnostics,
+			fieldPath,
+			Object.keys(value),
+			allowCodeUpdateStrategy
+				? ["bindings", "code_update_strategy"]
+				: ["bindings"]
+		);
+
+		const bindingsContainer =
+			allowMissingBindings && !hasProperty(value, "bindings")
+				? { ...value, bindings: [] }
+				: value;
+		let isValid = validateBindingsProperty(
+			envName,
+			validateDurableObjectBinding
+		)(diagnostics, field, bindingsContainer, config);
+		if (!allowCodeUpdateStrategy) {
+			return isValid;
+		}
+
+		if (
+			!hasProperty(value, "code_update_strategy") ||
+			value.code_update_strategy === undefined
+		) {
+			return isValid;
+		}
+
+		const strategy = value.code_update_strategy;
+		const strategyPath = `${fieldPath}.code_update_strategy`;
+		if (
+			typeof strategy !== "object" ||
+			strategy === null ||
+			Array.isArray(strategy)
+		) {
+			diagnostics.errors.push(
+				`The field "${strategyPath}" should be an object but got ${JSON.stringify(strategy)}.`
+			);
+			return false;
+		}
+
+		validateAdditionalProperties(
+			diagnostics,
+			strategyPath,
+			Object.keys(strategy),
+			["mode", "max_delay"]
+		);
+		isValid =
+			validateRequiredProperty(
+				diagnostics,
+				strategyPath,
+				"mode",
+				hasProperty(strategy, "mode") ? strategy.mode : undefined,
+				"string",
+				["immediate", "deferred"]
+			) && isValid;
+
+		const maxDelay = hasProperty(strategy, "max_delay")
+			? strategy.max_delay
+			: undefined;
+		const maxDelayHasValidType = validateOptionalProperty(
+			diagnostics,
+			strategyPath,
+			"max_delay",
+			maxDelay,
+			"number"
+		);
+		isValid = maxDelayHasValidType && isValid;
+		if (
+			maxDelayHasValidType &&
+			typeof maxDelay === "number" &&
+			(!Number.isFinite(maxDelay) ||
+				maxDelay < 0 ||
+				maxDelay > DURABLE_OBJECTS_CODE_UPDATE_MAX_DELAY_SECONDS)
+		) {
+			diagnostics.errors.push(
+				`Expected "${strategyPath}.max_delay" to be between 0 and ${DURABLE_OBJECTS_CODE_UPDATE_MAX_DELAY_SECONDS} seconds but got ${JSON.stringify(maxDelay)}.`
+			);
+			isValid = false;
+		}
+		if (
+			maxDelayHasValidType &&
+			typeof maxDelay === "number" &&
+			Number.isFinite(maxDelay) &&
+			maxDelay >= 0 &&
+			maxDelay <= DURABLE_OBJECTS_CODE_UPDATE_MAX_DELAY_SECONDS
+		) {
+			const milliseconds = maxDelay * 1000;
+			const roundedMilliseconds = Math.round(milliseconds);
+			if (
+				(maxDelay > 0 && roundedMilliseconds === 0) ||
+				Math.abs(milliseconds - roundedMilliseconds) >
+					MILLISECOND_PRECISION_TOLERANCE
+			) {
+				diagnostics.errors.push(
+					`Expected "${strategyPath}.max_delay" to use millisecond precision but got ${JSON.stringify(maxDelay)}.`
+				);
+				isValid = false;
+			}
+		}
+
+		return isValid;
+	};
+
 const validateUnsafeSettings =
 	(envName: string): ValidatorFn =>
 	(diagnostics, field, value, config) => {
@@ -6415,7 +6549,7 @@ const validatePreviewsConfig =
 		);
 
 		isValid =
-			validateBindingsProperty(envName, validateDurableObjectBinding)(
+			validateDurableObjectsProperty(envName, false, false)(
 				diagnostics,
 				`${field}.durable_objects`,
 				previews.durable_objects,

packages/workers-utils/src/types.ts

@@ -4,6 +4,7 @@ import type {
 	CustomDomainRoute,
 	ContainerApp,
 	ContainerEngine,
+	DurableObjectCodeUpdateStrategy,
 	Exports,
 	DurableObjectMigration,
 	Observability,
@@ -271,6 +272,7 @@ type WorkerMetadataPut = {
 	compatibility_flags?: string[];
 	usage_model?: "bundled" | "unbound";
 	migrations?: CfDurableObjectMigrations;
+	code_update_strategy?: DurableObjectCodeUpdateStrategy;
 	exports?: CfExports;
 	capnp_schema?: string;
 	bindings: WorkerMetadataBinding[];

packages/workers-utils/src/worker.ts

@@ -1,5 +1,6 @@
 import type {
 	CacheOptions,
+	DurableObjectCodeUpdateStrategy,
 	Exports,
 	LocalS3Credentials,
 	Observability,
@@ -504,6 +505,7 @@ export interface CfWorkerInit {
 		| undefined;
 
 	migrations: CfDurableObjectMigrations | undefined;
+	code_update_strategy?: DurableObjectCodeUpdateStrategy;
 	/**
 	 * Declarative exports configuration. Durable Object entries are sent instead
 	 * of `migrations`.