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

import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";

/**
 * AdoptPolicy controls whether the engine should "adopt" pre-existing cloud
 * resources that conflict with this stack instead of failing.
 *
 * The engine always calls a provider's `read` lifecycle operation when there
 * is no prior state and `read` is implemented. The provider's job is to
 * report two things:
 *
 *   1. Whether the resource exists (returns attributes vs. `undefined`).
 *   2. Whether *we* own it (plain attributes vs. {@link Unowned}-branded).
 *
 * The engine then routes:
 *
 *   | `read` outcome      | `adopt: false` | `adopt: true`     |
 *   | ------------------- | -------------- | ----------------- |
 *   | undefined           | create         | create            |
 *   | owned (plain attrs) | silent adopt   | silent adopt      |
 *   | {@link Unowned}     | fail           | takeover (adopt)  |
 *
 * "Owned" means a provider has affirmatively determined the resource was
 * created by this stack/stage/logical-id (typically by inspecting tags or
 * naming conventions). Resources without ownership semantics simply always
 * return plain attrs — they are treated as owned by default, so silent
 * adoption is the norm and `--adopt` is unnecessary.
 *
 * The policy can be overridden per-effect via {@link adopt} — most commonly
 * applied at the resource or stack scope.
 */
export class AdoptPolicy extends Context.Service<AdoptPolicy, boolean>()("AdoptPolicy") {}

/**
 * Engine-raised failure produced when `read` reports an existing resource
 * marked as {@link Unowned} and `adopt` is `false`. Surface this to the user
 * to indicate they should either re-tag the cloud resource, pick a different
 * physical name, or re-run with `--adopt` (or `adopt(true)`) to force a
 * takeover.
 */
export class OwnedBySomeoneElse extends Data.TaggedError("OwnedBySomeoneElse")<{
  /** A human-readable description of why the resource cannot be adopted. */
  message: string;
  /** The Resource Type (e.g. `AWS.S3.Bucket`). */
  resourceType?: string;
  /** The logical ID of the conflicting resource. */
  logicalId?: string;
  /** The physical name/identifier of the conflicting resource. */
  physicalName?: string;
}> {}

/**
 * Engine-raised failure produced when a delete-first replacement in a
 * dependency cycle must delete its previous generation before its new
 * identity is known: precreate runs on unresolved props, and a provider
 * without `observe`, or whose `observe` reports {@link Unresolved}, cannot
 * check ownership first. Refusing before the delete keeps the
 * previous generation; re-run with `--adopt` (or `adopt(true)`) to accept
 * whatever the identity resolves to.
 */
export class UnverifiableReplacement extends Data.TaggedError("UnverifiableReplacement")<{
  /** A human-readable description of why the replacement was refused. */
  message: string;
  /** The Resource Type (e.g. `AWS.Lambda.Function`). */
  resourceType?: string;
  /** The logical ID of the refused resource. */
  logicalId?: string;
}> {}

/**
 * Private symbol used to brand attribute objects returned by `read` as
 * "exists in cloud, but not owned by this stack/stage/logical-id".
 *
 * Deliberately *not* registered via `Symbol.for` — the brand is an
 * engine-internal routing hint and must not be observable or
 * forgeable from outside this module. The engine strips it before any
 * state persistence (see {@link stripUnowned}) so it never leaks into
 * the state store, JSON serialization, or downstream `Output`s.
 */
const UnownedTag: unique symbol = Symbol("alchemy/Unowned");

/**
 * Brand a `read` return value as belonging to a different owner.
 *
 * Use this in a provider's `read` implementation when the resource exists in
 * the cloud but a positive ownership check (e.g. tag inspection) shows it
 * was *not* created by this stack/stage/logical-id:
 *
 * ```ts
 * read: Effect.fn(function* ({ id, output, olds }) {
 *   const settings = yield* getScriptSettings({ ... }).pipe(
 *     Effect.catchTag("WorkerNotFound", () => Effect.succeed(undefined)),
 *   );
 *   if (!settings) return undefined;
 *
 *   const attrs = { workerName, ...buildAttrs(settings) };
 *   return hasAlchemyWorkerTags(id, settings.tags) ? attrs : Unowned(attrs);
 * }),
 * ```
 *
 * The returned value is structurally still `T` — there is no wrapper to
 * unwrap. The brand is a non-enumerable symbol that the engine inspects
 * during planning to decide whether to take over (`adopt: true`) or fail
 * loudly (`adopt: false`).
 *
 * Resources without ownership semantics should simply return plain attrs —
 * the engine treats them as owned and silent adoption is the default.
 */
export const Unowned: {
  <T extends object>(attrs: T): T;
  is: (value: unknown) => boolean;
} = Object.assign(
  <T extends object>(attrs: T): T => {
    const cloned = { ...attrs } as T;
    Object.defineProperty(cloned, UnownedTag, {
      value: true,
      enumerable: false,
      writable: false,
      configurable: false,
    });
    return cloned;
  },
  {
    is: (value: unknown): boolean =>
      typeof value === "object" && value !== null && (value as any)[UnownedTag] === true,
  },
);

/**
 * {@link Unowned} unless `attrs` is the generation a replacement is replacing:
 * during a replacement `read` and `observe` receive that generation's
 * attributes as `previous`, and a delete-first replacement that reuses its
 * identity finds it under that same identity. `key` must identify the
 * resource uniquely (a full resource name or an API id, not a display name).
 *
 * ```ts
 * read: Effect.fn(function* ({ output, olds, previous }) {
 *   // ...
 *   return output ? attrs : unownedUnlessPrevious(attrs, previous, "name");
 * }),
 * ```
 */
export const unownedUnlessPrevious = <T extends object, K extends keyof T>(
  attrs: T,
  previous: Partial<Record<K, unknown>> | undefined,
  key: K,
): T =>
  previous !== undefined && previous[key] !== undefined && previous[key] === attrs[key]
    ? attrs
    : Unowned(attrs);

/**
 * A provider's `observe` answer when the identity `precreate` would claim
 * depends on props that have not resolved yet, so nothing can be checked.
 * Unlike `undefined`, it does not report the identity as absent: the engine
 * checks the resolved identity before `reconcile` claims it, and refuses a
 * delete-first replacement that would delete its previous generation first.
 *
 * ```ts
 * observe: Effect.fn(function* ({ id, news }) {
 *   if (!isResolved(news.namespace)) return Unresolved;
 *   // ...
 * }),
 * ```
 *
 * `precreate` must not write to an identity it cannot resolve.
 */
export const Unresolved: unique symbol = Symbol("alchemy/Unresolved");
export type Unresolved = typeof Unresolved;

/**
 * Raised by a provider's `precreate` when the identity it must claim is still
 * {@link Unresolved}. The engine resolves every prop that comes from outside
 * a dependency cycle before precreate, so the identity depends on a peer in
 * the resource's own cycle. Name the resource with a literal, or a value from
 * outside the cycle.
 */
export class UnresolvedIdentity extends Data.TaggedError("UnresolvedIdentity")<{
  /** A human-readable description of the unresolved identity. */
  message: string;
  /** The Resource Type (e.g. `AWS.Lambda.Function`). */
  resourceType?: string;
  /** The logical ID of the resource. */
  logicalId?: string;
}> {}

/**
 * Strip the {@link Unowned} brand from an attributes object before persisting
 * it — state should not carry per-deploy ownership-routing metadata.
 *
 * The brand is intentionally non-enumerable, so a plain spread already
 * drops it; the additional `delete` is defense-in-depth in case a future
 * change makes the descriptor enumerable. Always returns a fresh object
 * (never mutates the input).
 */
export const stripUnowned = <T extends object>(attrs: T): T => {
  const out: any = { ...attrs };
  if (UnownedTag in out) delete out[UnownedTag];
  return out;
};

export const adopt: {
  (enabled?: boolean): <A, E, R = never>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
  <R1 = never>(
    enabled: Effect.Effect<boolean, never, R1>,
  ): <A, E, R2 = never>(effect: Effect.Effect<A, E, R2>) => Effect.Effect<A, E, R1 | R2>;
} = ((enabled: boolean | Effect.Effect<boolean, never, any> = true) =>
  (eff: Effect.Effect<any, any, any>) =>
    eff.pipe(
      typeof enabled === "boolean"
        ? Effect.provideService(AdoptPolicy, enabled ?? true)
        : Effect.provideServiceEffect(AdoptPolicy, enabled),
    )) as any;