@molecule/api-deploy-rollout 0.0.0-stage → 0.0.1-stage

package/dist/provider.js

@@ -0,0 +1,64 @@
+/**
+ * Accessors for the bonded deploy-rollout provider.
+ *
+ * A provider bond (e.g. `@molecule/api-deploy-rollout-default`) calls
+ * `setProvider()` during application startup. Application code uses the
+ * convenience accessors (`runRollout`, `runInPlaceRollout`), which delegate to the
+ * bonded provider, so the hosting-specific algorithm is a wiring decision rather
+ * than an import.
+ *
+ * @module
+ */
+import { bond, isBonded, require as bondRequire } from '@molecule/api-bond';
+const BOND_TYPE = 'deploy-rollout';
+/**
+ * Registers a deploy-rollout provider as the active singleton. Called by a bond
+ * package during application startup.
+ *
+ * @param provider - The provider implementation to bond.
+ */
+export const setProvider = (provider) => {
+    bond(BOND_TYPE, provider);
+};
+/**
+ * Retrieves the bonded deploy-rollout provider, throwing if none is wired.
+ *
+ * @returns The bonded provider.
+ * @throws {Error} If no deploy-rollout provider has been bonded.
+ */
+export const getProvider = () => {
+    try {
+        return bondRequire(BOND_TYPE);
+    }
+    catch (error) {
+        throw new Error('No deploy-rollout provider set. Bond one (e.g. @molecule/api-deploy-rollout-default) at startup.', { cause: error });
+    }
+};
+/**
+ * Checks whether a deploy-rollout provider is currently bonded.
+ *
+ * @returns `true` if a provider is bonded.
+ */
+export const hasProvider = () => {
+    return isBonded(BOND_TYPE);
+};
+/**
+ * Runs a grow-then-shrink rollout through the bonded provider.
+ *
+ * @param options - The set to build, the old set, and the instance provider.
+ * @returns What the rollout did.
+ */
+export const runRollout = (options) => {
+    return getProvider().run(options);
+};
+/**
+ * Runs an in-place rollout (the same instances changed one at a time) through the
+ * bonded provider.
+ *
+ * @param options - The instances to roll and the provider or callbacks.
+ * @returns What the rollout did.
+ */
+export const runInPlaceRollout = (options) => {
+    return getProvider().runInPlace(options);
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAW3E,MAAM,SAAS,GAAG,gBAAgB,CAAA;AAElC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAA+B,EAAQ,EAAE;IACnE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;AAC3B,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAA0B,EAAE;IACrD,IAAI,CAAC;QACH,OAAO,WAAW,CAAwB,SAAS,CAAC,CAAA;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,kGAAkG,EAClG,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAY,EAAE;IACvC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,OAA0B,EACE,EAAE;IAC9B,OAAO,WAAW,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;AACnC,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,OAAiC,EACE,EAAE;IACrC,OAAO,WAAW,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;AAC1C,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Type definitions for the deploy-rollout core interface.
+ *
+ * A rollout replaces the running instances of a deployment with new ones without
+ * taking the deployment down. Two topologies exist and both are first-class here:
+ *
+ * - **grow-then-shrink** — new instances are created beside the current set, each
+ *   gated ready and joined to the routable set; then the old instances leave,
+ *   drain and are destroyed one at a time. This is how a deployment changes its
+ *   instance count and how a stateless app is redeployed with no dropped request.
+ * - **in-place** — the same instances are changed (restarted onto a new build)
+ *   one at a time, with a restore path for every instance already changed. This is
+ *   the only topology an instance provider without a "create a replacement" call
+ *   supports (a Fly Machine patch, for example).
+ *
+ * The types here describe both, plus the policy that bounds either one. The
+ * algorithm lives in a bond (`@molecule/api-deploy-rollout-default`); this
+ * package carries no implementation.
+ *
+ * @module
+ */
+/**
+ * One instance a rollout can act on.
+ *
+ * `id` is the provider's stable handle. `upstreamUrl` is the routable address the
+ * deployment's edge dials, when the provider has one — a rollout that only
+ * restarts instances in place does not need it.
+ */
+export interface RolloutInstance {
+    /** Provider instance id. */
+    id: string;
+    /** The routable upstream URL, when the provider exposes one. */
+    upstreamUrl?: string;
+}
+/**
+ * What a grow-then-shrink rollout needs from whatever hosts the instances.
+ *
+ * The caller implements this over its hosting provider; the `-sandbox` bond does it
+ * over `@molecule/api-code-sandbox`, and tests drive it with a fake that records the
+ * order and can fail any step.
+ */
+export interface InstanceProvider<I extends RolloutInstance = RolloutInstance> {
+    /** A human-readable provider name, for progress lines. */
+    readonly name?: string;
+    /**
+     * Every instance the deployment currently owns, when the provider can enumerate
+     * them. Used to resume an interrupted rollout idempotently: an instance already
+     * ready and joined is not created twice.
+     */
+    list?(): Promise<I[]>;
+    /**
+     * Create the instance at `index` (0-based, above any primary the caller created
+     * itself). It must not be routable until {@link InstanceProvider.join}.
+     *
+     * @param index - Which instance this is.
+     * @returns The created instance.
+     */
+    create(index: number): Promise<I>;
+    /**
+     * Resolve once the instance may take traffic.
+     *
+     * @param instance - The instance to gate.
+     * @param timeoutMs - The policy's readiness budget, for providers whose probe
+     *   accepts one.
+     * @returns `false` when it never became ready (the rollout aborts).
+     */
+    waitReady(instance: I, timeoutMs?: number): Promise<boolean>;
+    /**
+     * A single, fast readiness probe, for the soak window. Optional: a caller that
+     * sets `soakMs` must provide it, because a blocking readiness wait cannot tell a
+     * warm instance from a recovering one.
+     *
+     * @param instance - The instance to probe.
+     * @returns Whether it is serving right now.
+     */
+    isServing?(instance: I): Promise<boolean>;
+    /**
+     * Add the instance to the routable set, so the edge may send it new requests.
+     *
+     * @param instance - A ready instance.
+     */
+    join(instance: I): Promise<void>;
+    /**
+     * Remove the instance from the routable set, so no NEW request is routed to it.
+     * Requests already in flight are untouched.
+     *
+     * @param instance - The instance being retired.
+     */
+    leave(instance: I): Promise<void>;
+    /**
+     * Tell the instance to drain: finish in-flight work and stop accepting new
+     * connections. Resolve when it may be destroyed, and never later than `drainMs`.
+     *
+     * @param instance - The retired instance.
+     * @param drainMs - The bounded wait.
+     */
+    drain(instance: I, drainMs: number): Promise<void>;
+    /**
+     * Destroy the instance, releasing whatever it costs.
+     *
+     * @param instance - The instance to remove.
+     */
+    destroy(instance: I): Promise<void>;
+}
+/**
+ * What an in-place rollout needs from whatever hosts the instances.
+ *
+ * Every instance keeps its identity; `replace` changes it to the new build and
+ * `restore` puts it back on the old one. The caller supplies {@link list} so a
+ * resumed rollout can see what is already there.
+ */
+export interface InPlaceInstanceProvider<I extends RolloutInstance = RolloutInstance> {
+    /** A human-readable provider name, for progress lines. */
+    readonly name?: string;
+    /**
+     * Every instance the rollout may act on, in roll order.
+     *
+     * @returns The instances.
+     */
+    list(): Promise<I[]>;
+    /**
+     * Whether the instance is serving requests right now.
+     *
+     * @param instance - The instance to probe.
+     * @returns `true` while it answers its readiness probe.
+     */
+    isServing(instance: I): Promise<boolean>;
+    /**
+     * Change the instance to the new build and leave it serving.
+     *
+     * @param instance - The instance to change.
+     */
+    replace(instance: I): Promise<void>;
+    /**
+     * Put the instance back on the old build. Called only for instances this run
+     * already replaced.
+     *
+     * @param instance - The instance to restore.
+     */
+    restore(instance: I): Promise<void>;
+}
+/**
+ * How a rollout bounds itself.
+ *
+ * Every field is optional on the caller's side; the bond fills in the defaults
+ * documented here.
+ */
+export interface RolloutPolicy {
+    /**
+     * How many instances the NEW set holds, for a grow-then-shrink rollout. The
+     * caller's own primary instance is not created here, so the bond creates
+     * `replicas - 1`. Defaults to `current.length` (a like-for-like replacement).
+     */
+    replicas?: number;
+    /**
+     * The most instances that may be unavailable at once. When set, the bond derives
+     * `minHealthy = max(1, instances - maxUnavailable)` and refuses a step that would
+     * go below it. Default: `minHealthy` is 1 — never blank the deployment.
+     */
+    maxUnavailable?: number;
+    /**
+     * An absolute floor on healthy instances. Overrides the value derived from
+     * {@link RolloutPolicy.maxUnavailable}. Defaults to 1.
+     */
+    minHealthy?: number;
+    /**
+     * How long a changed instance must keep answering without a gap before the next
+     * step starts. Passing one probe is not proof of a warm instance; a gap restarts
+     * the window. Defaults to 0 (no soak).
+     */
+    soakMs?: number;
+    /** Probe cadence during the soak. Defaults to 2000 ms. */
+    soakProbeMs?: number;
+    /**
+     * How long the soak may keep retrying before the rollout aborts. Defaults to
+     * `soakMs + 60 s`.
+     */
+    soakGraceMs?: number;
+    /** How long a retired instance may take to drain. Defaults to 25 s. */
+    drainMs?: number;
+    /** The readiness budget handed to `waitReady`. Defaults to 120 s. */
+    readinessTimeoutMs?: number;
+    /**
+     * What an abort does to instances this run already changed: `reverse` restores
+     * them newest first (the default), `none` leaves them as they are.
+     */
+    rollback?: 'reverse' | 'none';
+    /**
+     * Whether a rollout reconciles against the provider's current instances instead
+     * of starting from the caller's list. Defaults to true; a provider without
+     * `list()` falls back to the caller's list.
+     */
+    resume?: boolean;
+}
+/** The step of a rollout that produced a result or a failure. */
+export type RolloutStep = 'create' | 'ready' | 'join' | 'leave' | 'drain' | 'destroy' | 'replace' | 'restore' | 'capacity' | 'cancelled';
+/** A step that failed but did not stop the rollout (a retirement or rollback step). */
+export interface RolloutFailure<I extends RolloutInstance = RolloutInstance> {
+    /** The instance the step addressed. */
+    instance: I;
+    /** The step that failed. */
+    step: RolloutStep;
+    /** Whatever was thrown, for the caller's log. */
+    error: unknown;
+}
+/** What a completed or aborted rollout did. */
+export interface RolloutOutcome<I extends RolloutInstance = RolloutInstance> {
+    /** `completed` when the target set is serving; `aborted` otherwise. */
+    status: 'completed' | 'aborted';
+    /** Every instance this run created and joined, in creation order. */
+    created: I[];
+    /** Every new instance that is healthy and joined. */
+    upstreams: I[];
+    /** Old instances this run removed from the set and destroyed. */
+    retired: I[];
+    /** Steps that failed but did not stop the rollout. */
+    failures: RolloutFailure<I>[];
+    /** Instances this run restored, newest first (an in-place abort). */
+    rolledBack: string[];
+    /** Restores that themselves failed. */
+    rollbackFailures: RolloutFailure<I>[];
+}
+/** What an in-place rollout did. */
+export interface InPlaceRolloutOutcome<I extends RolloutInstance = RolloutInstance> {
+    /** The instances changed successfully, in roll order. */
+    applied: string[];
+    /** Every instance that passed its gate. */
+    instances: I[];
+}
+/** What {@link InstanceProvider} needs for one grow-then-shrink rollout. */
+export interface RolloutOptions<I extends RolloutInstance = RolloutInstance> {
+    /** The instance provider. */
+    provider: InstanceProvider<I>;
+    /** The instances serving right now (empty on a first deploy). */
+    current?: readonly I[];
+    /** Rollout bounds; the bond fills the defaults. */
+    policy?: RolloutPolicy;
+    /** Optional progress sink — plain sentences. */
+    log?: (line: string) => Promise<void> | void;
+    /** Consulted between steps; `true` aborts and keeps the old set serving. */
+    isCancelled?: () => Promise<boolean> | boolean;
+    /**
+     * Set when the caller has already created and joined ONE instance of the new
+     * set (the primary), outside this rollout. It counts toward healthy capacity.
+     */
+    primaryServing?: boolean;
+    /** Injectable clock, for tests. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Injectable sleep, for tests. Defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The contract every deploy-rollout bond implements.
+ *
+ * The two methods are the two real deployment topologies; a bond that supports
+ * only one rejects the other with a clear error rather than silently doing
+ * nothing.
+ */
+export interface DeployRolloutProvider {
+    /** A human-readable provider name, for diagnostics. */
+    readonly name: string;
+    /**
+     * Run a grow-then-shrink replacement of a deployment's instances.
+     *
+     * @param options - The set to build, the old set, and the instance provider.
+     * @returns What the rollout did.
+     */
+    run<I extends RolloutInstance>(options: RolloutOptions<I>): Promise<RolloutOutcome<I>>;
+    /**
+     * Run an in-place replacement (the same instances changed one at a time).
+     *
+     * @param options - The instances to roll and the provider or callbacks.
+     * @returns What the rollout did.
+     */
+    runInPlace<I extends RolloutInstance>(options: InPlaceRolloutOptions<I>): Promise<InPlaceRolloutOutcome<I>>;
+}
+/** What an in-place rollout needs. */
+export interface InPlaceRolloutOptions<I extends RolloutInstance = RolloutInstance> {
+    /**
+     * The instances to roll. When absent, the provider's own list is used.
+     */
+    machines?: readonly I[];
+    /**
+     * A provider that owns the operations. Alternatively pass `apply`/`rollback`/
+     * `probeServing` directly; the provider is a convenience for callers that
+     * already model their hosting this way.
+     */
+    provider?: InPlaceInstanceProvider<I>;
+    /** Change one instance and leave it serving on the NEW build. */
+    apply?: (instance: I) => Promise<void>;
+    /** Put one instance back on the OLD build. */
+    rollback?: (instance: I) => Promise<void>;
+    /** Whether an instance is serving right now. */
+    probeServing?: (instanceId: string) => Promise<boolean>;
+    /** Rollout bounds; the bond fills the defaults. */
+    policy?: RolloutPolicy;
+    /** Pause between instances. Defaults to 0. */
+    betweenMs?: number;
+    /** Optional progress sink — plain sentences. */
+    log?: (line: string) => Promise<void> | void;
+    /** Consulted before each instance; `true` aborts and rolls back. */
+    isCancelled?: () => Promise<boolean> | boolean;
+    /** Injectable clock, for tests. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Injectable sleep, for tests. Defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,23 @@
+/**
+ * Type definitions for the deploy-rollout core interface.
+ *
+ * A rollout replaces the running instances of a deployment with new ones without
+ * taking the deployment down. Two topologies exist and both are first-class here:
+ *
+ * - **grow-then-shrink** — new instances are created beside the current set, each
+ *   gated ready and joined to the routable set; then the old instances leave,
+ *   drain and are destroyed one at a time. This is how a deployment changes its
+ *   instance count and how a stateless app is redeployed with no dropped request.
+ * - **in-place** — the same instances are changed (restarted onto a new build)
+ *   one at a time, with a restore path for every instance already changed. This is
+ *   the only topology an instance provider without a "create a replacement" call
+ *   supports (a Fly Machine patch, for example).
+ *
+ * The types here describe both, plus the policy that bounds either one. The
+ * algorithm lives in a bond (`@molecule/api-deploy-rollout-default`); this
+ * package carries no implementation.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@molecule/api-deploy-rollout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-stage",
+  "description": "Deploy-rollout core interface for molecule.dev: replace a deployment's running instances without downtime, grow-then-shrink or in place, with a capacity floor, soak, reverse rollback and idempotent resume.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "molecule",
+    "deploy",
+    "rollout",
+    "rolling deploy",
+    "zero downtime",
+    "replicas"
+  ],
+  "author": "Molecule Dev, Inc. (https://molecule.dev)",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.1"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.2",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/core/deploy-rollout"
+  },
+  "homepage": "https://www.molecule.dev/packages/api-deploy-rollout",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}