sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ AppConfig/ DeploymentEventSource.ts

import * as Binding from "alchemy/Binding";
import type * as Effect from "effect/Effect";
import type * as Stream from "effect/Stream";
import type { Application } from "./Application.ts";
import type { Environment } from "./Environment.ts";

/**
 * The deployment notification action points an AppConfig deployment emits as
 * it progresses. These are the `ON_*` subset of extension action points —
 * fire-and-forget notifications that cannot modify the deployment.
 */
export type DeploymentEventType =
  | "ON_DEPLOYMENT_START"
  | "ON_DEPLOYMENT_STEP"
  | "ON_DEPLOYMENT_BAKING"
  | "ON_DEPLOYMENT_COMPLETE"
  | "ON_DEPLOYMENT_ROLLED_BACK";

/**
 * The payload AppConfig sends when it invokes the host function at a
 * deployment action point (the extension invocation payload, verbatim).
 */
export interface DeploymentEventRecord {
  /** Unique id of this extension invocation. */
  InvocationId: string;
  /** The action point that fired, e.g. `"OnDeploymentStart"`. */
  Type: string;
  /** The application the deployment belongs to. */
  Application?: { Id?: string; Name?: string };
  /** The environment being deployed to. */
  Environment?: { Id?: string; Name?: string };
  /** The configuration profile being deployed. */
  ConfigurationProfile?: { Id?: string; Name?: string };
  /** The deployment's number within the environment. */
  DeploymentNumber?: number;
  /** Description of the deployment. */
  Description?: string;
  /** Parameter values supplied by the extension association. */
  Parameters?: Record<string, string>;
}

export interface DeploymentEventSourceProps {
  /**
   * The deployment action points to subscribe to.
   * @default all five `ON_DEPLOYMENT_*` action points
   */
  events?: DeploymentEventType[];
}

type DeploymentEventsHandler<Req> = (
  events: Stream.Stream<DeploymentEventRecord>,
) => Effect.Effect<void, never, Req>;

/**
 * Subscribe an Effect handler to AppConfig deployment events for an
 * {@link Application} or {@link Environment}.
 *
 * At deploy time this provisions an AppConfig extension targeting the host
 * function (plus the IAM role AppConfig assumes to invoke it) and associates
 * the extension with the target resource. At runtime the handler receives
 * each deployment notification as a {@link DeploymentEventRecord}.
 *
 * @param target The application or environment whose deployments to observe.
 * @param props Optional event-source configuration (which action points).
 * @param process The handler invoked with a stream of deployment events.
 *
 * @example
 * ```typescript
 * yield* AppConfig.consumeDeploymentEvents(env, (events) =>
 *   events.pipe(
 *     Stream.runForEach((event) =>
 *       Effect.log(`${event.Type}: deployment ${event.DeploymentNumber}`),
 *     ),
 *   ),
 * );
 * ```
 *
 * @example Only completed deployments
 * ```typescript
 * yield* AppConfig.consumeDeploymentEvents(
 *   env,
 *   { events: ["ON_DEPLOYMENT_COMPLETE"] },
 *   (events) =>
 *     events.pipe(Stream.runForEach((event) => Effect.log(event.Type))),
 * );
 * ```
 */
export function consumeDeploymentEvents<Req = never>(
  target: Application | Environment,
  process: DeploymentEventsHandler<Req>,
): Effect.Effect<void, never, DeploymentEventSource>;
export function consumeDeploymentEvents<Req = never>(
  target: Application | Environment,
  props: DeploymentEventSourceProps,
  process: DeploymentEventsHandler<Req>,
): Effect.Effect<void, never, DeploymentEventSource>;
export function consumeDeploymentEvents<Req = never>(
  target: Application | Environment,
  propsOrProcess: DeploymentEventSourceProps | DeploymentEventsHandler<Req>,
  maybeProcess?: DeploymentEventsHandler<Req>,
): Effect.Effect<void, never, DeploymentEventSource> {
  const [props, process] =
    typeof propsOrProcess === "function"
      ? [{} as DeploymentEventSourceProps, propsOrProcess]
      : [propsOrProcess, maybeProcess!];
  return DeploymentEventSource.use((source) => source(target, props, process));
}

/**
 * Event source connecting AppConfig deployment notifications to the hosting
 * compute. The contract is a `Binding.Service`; the Lambda implementation
 * layer is `Lambda.AppConfigDeploymentEventSource` (extension + association +
 * invoke role at deploy time, payload dispatch at runtime). Consume it
 * through the {@link consumeDeploymentEvents} helper.
 * ### Consuming Deployment Events
 * **Example:** React to Deployments of an Environment
 * ```typescript
 * export default MyFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const app = yield* AppConfig.Application("App", {});
 *     const env = yield* AppConfig.Environment("Env", {
 *       applicationId: app.applicationId,
 *     });
 *
 *     yield* AppConfig.consumeDeploymentEvents(env, (events) =>
 *       events.pipe(
 *         Stream.runForEach((event) =>
 *           Effect.log(`deployment event: ${event.Type}`),
 *         ),
 *       ),
 *     );
 *   }).pipe(Effect.provide(Lambda.AppConfigDeploymentEventSource)),
 * );
 * ```
 *
 * @binding
 */
export interface DeploymentEventSource extends Binding.Service<
  DeploymentEventSource,
  "AWS.AppConfig.DeploymentEventSource",
  DeploymentEventSourceService
> {}

export const DeploymentEventSource = Binding.Service<DeploymentEventSource>(
  "AWS.AppConfig.DeploymentEventSource",
);

export type DeploymentEventSourceService = <Req = never>(
  target: Application | Environment,
  props: DeploymentEventSourceProps,
  process: (events: Stream.Stream<DeploymentEventRecord>) => Effect.Effect<void, never, Req>,
) => Effect.Effect<void, never, never>;