sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ GreengrassV2/ GreengrassEventSource.ts

import type * as Effect from "effect/Effect";
import type * as Stream from "effect/Stream";
import {
  consumeBusEvents,
  type EventRecord,
  type EventRouteProps,
} from "../EventBridge/EventSource.ts";

/**
 * The `detail` payload IoT Greengrass V2 delivers to EventBridge.
 * Deployment-status events describe a deployment landing on a core device
 * (`deploymentId`, `coreDeviceExecutionStatus`); component-status events
 * describe an installed component's lifecycle state (`componentName`,
 * `componentLifecycleState`, e.g. `BROKEN`). Fields not shared by every
 * event kind are optional (the schema grows over time).
 */
export interface GreengrassEventDetail {
  /** The core device thing name the event is about. */
  coreDeviceThingName?: string;
  /** Deployment-status events: the id of the deployment. */
  deploymentId?: string;
  /**
   * Deployment-status events: the per-device execution status, e.g.
   * `SUCCEEDED`, `FAILED`, `REJECTED`, `TIMED_OUT`.
   */
  coreDeviceExecutionStatus?: string;
  /** Component-status events: the name of the installed component. */
  componentName?: string;
  /** Component-status events: the version of the installed component. */
  componentVersion?: string;
  /**
   * Component-status events: the component's lifecycle state, e.g.
   * `RUNNING`, `ERRORED`, `BROKEN`.
   */
  componentLifecycleState?: string;
  /** Additional event fields (the schema grows over time). */
  [key: string]: unknown;
}

/** An IoT Greengrass V2 EventBridge event delivered to the handler. */
export type GreengrassEvent = EventRecord<GreengrassEventDetail>;

/** Which IoT Greengrass V2 notifications to subscribe to. */
export type GreengrassEventKind = "deployment-status" | "component-status";

const DETAIL_TYPES: Record<GreengrassEventKind, string> = {
  "deployment-status": "Greengrass V2 Effective Deployment Status Change",
  "component-status": "Greengrass V2 Installed Component Status Change",
};

export interface GreengrassEventSourceProps extends EventRouteProps {
  /**
   * Logical id for the backing EventBridge rule.
   * @default "GreengrassEvents"
   */
  id?: string;
  /**
   * Which notifications to subscribe to: per-device deployment status
   * changes (a deployment succeeding/failing on a core device) and/or
   * installed component status changes (a component entering `BROKEN`).
   * @default ["deployment-status"]
   */
  kinds?: readonly GreengrassEventKind[];
}

/**
 * Event source connecting IoT Greengrass V2 notifications to the hosting
 * compute. Greengrass publishes per-core-device deployment execution status
 * (`SUCCEEDED`, `FAILED`, …) and installed-component lifecycle changes (most
 * importantly a component dropping into `BROKEN`) to the account's default
 * EventBridge bus (source `aws.greengrass`); this subscribes the host
 * Function to those events so it can alert on failed rollouts or broken
 * edge software.
 *
 * Greengrass publishes to EventBridge automatically — no additional resource
 * is created besides the EventBridge rule targeting the host. Provide the
 * host-specific implementation layer (e.g. `AWS.Lambda.EventSource`) on the
 * Function effect.
 *
 * ### Consuming Greengrass Events
 * **Example:** Alert When A Rollout Fails On A Device
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * export default AlertFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     yield* AWS.GreengrassV2.consumeGreengrassEvents(
 *       { kinds: ["deployment-status"] },
 *       (events) =>
 *         Stream.runForEach(events, (event) =>
 *           event.detail.coreDeviceExecutionStatus === "FAILED"
 *             ? Effect.logError(
 *                 `deployment ${event.detail.deploymentId} failed on ${event.detail.coreDeviceThingName}`,
 *               )
 *             : Effect.void,
 *         ),
 *     );
 *     return {};
 *   }).pipe(Effect.provide(AWS.Lambda.EventSource)),
 * );
 * ```
 */
export const consumeGreengrassEvents = <StreamReq = never, Req = never>(
  props: GreengrassEventSourceProps,
  process: (
    events: Stream.Stream<GreengrassEvent, never, StreamReq>,
  ) => Effect.Effect<void, never, Req>,
) =>
  consumeBusEvents(
    props.id ?? "GreengrassEvents",
    {
      source: ["aws.greengrass"],
      "detail-type": (props.kinds ?? (["deployment-status"] as const)).map(
        (kind) => DETAIL_TYPES[kind],
      ),
    },
    { description: props.description, state: props.state },
    process,
  );