@molecule/api-deploy-rollout-default 0.0.0-stage → 1.1.0

package/dist/index.js

@@ -0,0 +1,39 @@
+/**
+ * Default deploy-rollout provider for molecule.dev.
+ *
+ * Implements the two real deployment topologies over any instance provider:
+ * grow-then-shrink (create the new set, gate it ready, join it, then retire the old
+ * one at a time) and in-place (change the same instances one at a time, with a
+ * reverse restore on failure). No I/O of its own, no clock other than an injected
+ * one, no knowledge of where the instances live.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider, runRollout } from '@molecule/api-deploy-rollout'
+ * import { provider } from '@molecule/api-deploy-rollout-default'
+ *
+ * setProvider(provider)
+ *
+ * const outcome = await runRollout({
+ *   provider: myInstanceProvider,
+ *   current: oldInstances,
+ *   policy: { replicas: 2, soakMs: 30_000 },
+ * })
+ * ```
+ *
+ * @remarks
+ * - **Capacity floor first.** `policy.minHealthy` (default 1) is checked before
+ *   every retirement; a step that would go below it aborts instead of running.
+ * - **Soak is continuous.** With `soakMs > 0` the instance must keep answering
+ *   `isServing`; a gap restarts the window (a fresh process can pass one probe while
+ *   its event loop is still warming).
+ * - **Rollback is reverse.** Instances this run changed are restored newest first; a
+ *   restore failure does not stop the remaining restores.
+ * - **Resume is a no-op when complete.** A re-run reconciles against the provider's
+ *   own `list()` where it has one, so an interrupted rollout does not create a
+ *   duplicate set.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';

package/dist/provider.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The default deploy-rollout provider: the state machine itself.
+ *
+ * Provider-agnostic on purpose. The deploy path wires it to Fly Machines or to a
+ * sandbox provider; the tests wire it to a fake that records every call. What it
+ * guarantees is the part that is hard to get right:
+ *
+ * 1. **A new instance joins only after it is READY.** `waitReady` is the provider's
+ *    readiness gate (`/health/ready` when the app has the lifecycle bond,
+ *    `/health` otherwise — the caller decides).
+ * 2. **Healthy capacity never drops below the policy floor.** Before any instance
+ *    leaves the routable set, the run counts what is still serving and refuses a
+ *    step that would go below `minHealthy`.
+ * 3. **One at a time, with a soak.** The next step starts only after the previous
+ *    instance passed its gate and kept answering for the soak window.
+ * 4. **A failure aborts and rolls back in reverse.** Grow-then-shrink destroys every
+ *    instance it created and leaves the old set untouched (nothing was cut over);
+ *    in-place restores every instance it changed, newest first.
+ * 5. **A retirement failure never strands the set.** The step is reported and the
+ *    rollout continues; an unreachable instance is the orphan sweep's to reclaim.
+ *
+ * @module
+ */
+import type { DeployRolloutProvider, InPlaceRolloutOptions, InPlaceRolloutOutcome, InstanceProvider, RolloutFailure, RolloutInstance, RolloutOptions, RolloutOutcome, RolloutPolicy, RolloutStep } from '@molecule/api-deploy-rollout';
+/** The default bounded drain wait — matches the lifecycle bond's own budget. */
+export declare const DEFAULT_ROLLOUT_DRAIN_MS = 25000;
+/** The default readiness budget handed to a provider. */
+export declare const DEFAULT_ROLLOUT_READINESS_TIMEOUT_MS = 120000;
+/** The default cadence of the soak probe. */
+export declare const DEFAULT_SOAK_PROBE_MS = 2000;
+/** The default floor of healthy instances: never blank the deployment. */
+export declare const DEFAULT_MIN_HEALTHY = 1;
+/** A cancellation probe: `true` means stop. */
+export type RolloutCancelProbe = () => Promise<boolean> | boolean;
+/** The resolved policy the state machine runs with. */
+export interface ResolvedRolloutPolicy {
+    /** Target size of the new set (grow-then-shrink only). */
+    replicas: number;
+    /** Floor of healthy instances. */
+    minHealthy: number;
+    /** Continuous healthy time required after a change. */
+    soakMs: number;
+    /** Probe cadence during the soak. */
+    soakProbeMs: number;
+    /** Give-up bound for the soak. */
+    soakGraceMs: number;
+    /** Bounded wait for a retiring instance. */
+    drainMs: number;
+    /** Readiness budget handed to the provider. */
+    readinessTimeoutMs: number;
+    /** What an abort does to instances already changed. */
+    rollback: 'reverse' | 'none';
+    /** Whether to reconcile against the provider's current instances. */
+    resume: boolean;
+}
+/**
+ * A rollout that could not finish, carrying what it did so the caller can report
+ * it (and, where the topology allows, undo the rest itself).
+ *
+ * The same class serves both topologies: grow-then-shrink fills `role`, `created`
+ * and `outcome`; in-place fills `failed`, `rolledBack` and `rollbackFailures`.
+ */
+export declare class RolloutAbortedError extends Error {
+    /** The API layer's key for this abort. */
+    readonly errorKey = "deploy-rollout.error.aborted";
+    /** The step that failed. */
+    readonly role: RolloutStep | null;
+    /** The instance whose step failed, when one did. */
+    readonly failed: string | null;
+    /** Instances restored to the old build, newest first. */
+    readonly rolledBack: string[];
+    /** Restores that themselves failed. */
+    readonly rollbackFailures: RolloutFailure[];
+    /** The grow-then-shrink outcome, when the abort happened there. */
+    readonly outcome: RolloutOutcome | null;
+    /**
+     * Build the abort with what the caller must report.
+     *
+     * @param message - What happened, in plain words.
+     * @param details - The role, the failed instance, what was undone and the outcome.
+     * @param cause - The underlying error, when there was one.
+     */
+    constructor(message: string, details?: {
+        role?: RolloutStep | null;
+        failed?: string | null;
+        rolledBack?: string[];
+        rollbackFailures?: RolloutFailure[];
+        outcome?: RolloutOutcome | null;
+    }, cause?: unknown);
+}
+/**
+ * Fill the policy defaults.
+ *
+ * `maxUnavailable` derives `minHealthy` only when it is set; without it the floor
+ * is one healthy instance, which is exactly the rule every existing rolling path
+ * has today.
+ *
+ * @param policy - The caller's policy, if any.
+ * @param instanceCount - How many instances the topology has, for `maxUnavailable`.
+ * @returns The resolved policy.
+ */
+export declare const resolveRolloutPolicy: (policy: RolloutPolicy | undefined, instanceCount: number) => ResolvedRolloutPolicy;
+/**
+ * Run a grow-then-shrink replacement.
+ *
+ * The caller has already created, gated and joined the PRIMARY instance of the new
+ * version when `primaryServing` is set; `replicas` is the size of the new set
+ * including that one, and this function creates the remaining `replicas - 1`.
+ *
+ * @param options - The set to build, the old set, and the provider.
+ * @returns The new set, the retired instances and non-fatal failures.
+ * @throws {RolloutAbortedError} When an instance cannot be created, become ready or
+ *   join — after undoing everything this run created and leaving the old set serving.
+ */
+export declare const runGrowThenShrink: <I extends RolloutInstance>(options: RolloutOptions<I>) => Promise<RolloutOutcome<I>>;
+/**
+ * Run an in-place replacement: the same instances changed one at a time.
+ *
+ * The instance list comes from `machines`, or from the provider's own `list()`.
+ * The operations come from `apply`/`rollback`/`probeServing`, or from the provider's
+ * `replace`/`restore`/`isServing`. Before an instance is taken out of rotation,
+ * every OTHER instance must answer its probe, and the resulting healthy count must
+ * stay at or above the policy floor.
+ *
+ * @param options - The instances to roll and the provider or callbacks.
+ * @returns The instances changed, in roll order.
+ * @throws {RolloutAbortedError} On the first failed step, after the reverse rollback.
+ */
+export declare const runInPlace: <I extends RolloutInstance>(options: InPlaceRolloutOptions<I>) => Promise<InPlaceRolloutOutcome<I>>;
+/**
+ * The provider implementation registered under `deploy-rollout`.
+ */
+export declare const provider: DeployRolloutProvider;
+/**
+ * Create a fresh provider object (the same algorithm; a distinct identity for
+ * tests and for apps that register more than one).
+ *
+ * @returns A deploy-rollout provider.
+ */
+export declare const createProvider: () => DeployRolloutProvider;
+/**
+ * One plain sentence about what a finished rollout did.
+ *
+ * @param outcome - What the rollout returned.
+ * @param replicas - The set size, for the sentence.
+ * @returns The line, or `null` when there was nothing to retire or the set is one.
+ */
+export declare const describeRolloutResult: <I extends RolloutInstance>(outcome: Pick<RolloutOutcome<I>, "retired">, replicas: number) => string | null;
+/** Re-exported so a caller can type its own instance provider without a second import. */
+export type { InstanceProvider };
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}