sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ State/ State.ts

import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { UserFacingError } from "../UserFacingError.ts";
import type { ActionState } from "./ActionState.ts";
import type { ReplacedResourceState, ResourceState } from "./ResourceState.ts";

/**
 * Anything persistable under an FQN. Resources are discriminated by status
 * strings ("creating", "created", …) and Tasks by `kind: "action"`.
 */
export type PersistedState = ResourceState | ActionState;

export const isActionState = (s: PersistedState | undefined): s is ActionState =>
  !!s && (s as any).kind === "action";

export const isResourceState = (s: PersistedState | undefined): s is ResourceState =>
  !!s && (s as any).kind !== "task";

export class StateStoreError extends Data.TaggedError("StateStoreError")<{
  message: string;
  cause?: Error;
  /** HTTP failure metadata without the request, response body, or credentials. */
  http?: {
    /** Undefined when the HTTP client failed before receiving a response. */
    status?: number;
  };
  /** Set when the store must be bootstrapped or upgraded first, as CI never does either. */
  requires?: { readonly action: "bootstrap" | "upgrade"; readonly command: string };
}> {
  readonly [UserFacingError] = true;
}

export class State extends Context.Service<State, Effect.Effect<StateService>>()("alchemy/State") {}

/**
 * State service interface.
 *
 * Resources are keyed by FQN (namespace-qualified key) which includes
 * the full namespace path plus the logical ID. The FQN is used as the
 * storage key while logicalId remains available in the persisted state
 * for provider operations.
 */
export interface StateService {
  /**
   * Stable identifier for the State store implementation, used for
   * telemetry tagging (`alchemy.state_store.id`) so we can answer
   * "which backends are people using" without hard-coding a closed
   * union. Examples: `"local"`, `"inmemory"`, `"http"`,
   * `"cloudflare-http"`. Third-party state stores should pick a short,
   * stable, kebab-case slug.
   */
  readonly id: string;
  /**
   * Wire / behavioural contract version of this state-store
   * implementation. For local / in-process stores this is the
   * `STATE_STORE_VERSION` the CLI was built against; for HTTP-backed
   * stores it is the version reported by the deployed `/version`
   * probe.
   */
  getVersion(): Effect.Effect<number, StateStoreError, never>;
  listStacks(): Effect.Effect<readonly string[], StateStoreError, never>;
  listStages(stack: string): Effect.Effect<readonly string[], StateStoreError, never>;
  /**
   * Get a resource by its FQN (namespace-qualified key).
   */
  get(request: {
    stack: string;
    stage: string;
    fqn: string;
  }): Effect.Effect<PersistedState | undefined, StateStoreError, never>;
  /**
   * List top-level resources that are still in replacement cleanup.
   *
   * Any additional backlog from repeated replacements is stored recursively
   * in the returned state's `old` chain.
   */
  getReplacedResources(request: {
    stack: string;
    stage: string;
  }): Effect.Effect<ReadonlyArray<ReplacedResourceState>, StateStoreError, never>;
  /**
   * Set a resource by its FQN (namespace-qualified key).
   */
  set<V extends PersistedState>(request: {
    stack: string;
    stage: string;
    fqn: string;
    value: V;
  }): Effect.Effect<V, StateStoreError, never>;
  /**
   * Delete a resource by its FQN (namespace-qualified key).
   */
  delete(request: {
    stack: string;
    stage: string;
    fqn: string;
  }): Effect.Effect<void, StateStoreError, never>;
  /**
   * Delete an entire stack, or a single stage when `stage` is provided.
   */
  deleteStack(request: {
    stack: string;
    stage?: string;
  }): Effect.Effect<void, StateStoreError, never>;
  /**
   * List all resource FQNs in a stack/stage.
   */
  list(request: {
    stack: string;
    stage: string;
  }): Effect.Effect<readonly string[], StateStoreError, never>;
  /**
   * Read the persisted stack output for `(stack, stage)`. Returns
   * `undefined` when the stack has not been deployed (or has been
   * destroyed) at this stage.
   *
   * Stack outputs are written by `apply` once the deploy succeeds and
   * read by cross-stack references (`yield* OtherStack` /
   * `OtherStack.stage.<name>` / `Output.stackRef(...)`).
   */
  getOutput(request: {
    stack: string;
    stage: string;
  }): Effect.Effect<unknown, StateStoreError, never>;
  /**
   * Persist the resolved stack output for `(stack, stage)`.
   */
  setOutput(request: {
    stack: string;
    stage: string;
    value: unknown;
  }): Effect.Effect<unknown, StateStoreError, never>;
  /**
   * Move stages into this store from the one it replaces, or back with
   * `rollback`, for stores that replace another. Idempotent: run it again
   * to finish what a failure or a blocked stage left.
   */
  migrate?(
    request: StateMigrationRequest,
  ): Effect.Effect<ReadonlyArray<StateMigration>, StateStoreError, never>;
}

/** Which stages {@link StateService.migrate} moves. */
export interface StateMigrationRequest {
  /** Only this stack's stages. */
  readonly stack?: string;
  /** Only stages of this name. */
  readonly stage?: string;
  /** Move stages back to the store this one replaces. */
  readonly rollback?: boolean;
}

/** What {@link StateService.migrate} did with one stage. */
export interface StateMigration {
  readonly stack: string;
  readonly stage: string;
  /** e.g. `migrated`, `already-migrated`, `rolled-back`, `blocked` or `failed`. */
  readonly status: string;
  /** Records moved. */
  readonly records?: number;
  /** Why a stage was not moved. */
  readonly reason?: string;
}