sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EventBridge/ Endpoint.ts

import * as eventbridge from "@distilled.cloud/aws/eventbridge";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";

export type { EndpointState } from "@distilled.cloud/aws/eventbridge";

export type EndpointName = string;
export type EndpointArn = `arn:aws:events:${RegionID}:${AccountID}:endpoint/${EndpointName}`;

export interface EndpointFailoverConfig {
  /**
   * The Route 53 health check that decides when to fail over: while it is
   * unhealthy, events sent to the endpoint go to the secondary region.
   * Accepts the health check ID (`healthCheck.healthCheckId`) or its ARN.
   */
  healthCheck: string;
  /**
   * The region events are routed to while the health check is unhealthy.
   * It must be the region of the second event bus in `eventBuses`.
   */
  secondaryRegion: string;
}

export interface EndpointProps {
  /**
   * Name of the endpoint. Must match [\.\-_A-Za-z0-9]+, 1-64 characters.
   * If omitted, a unique name will be generated. Changing it replaces the
   * endpoint.
   */
  name?: EndpointName;

  /**
   * Description of the endpoint. Max 512 characters.
   */
  description?: string;

  /**
   * ARNs of the two event buses the endpoint routes to: the primary bus in
   * the stack's region and the secondary bus in `failover.secondaryRegion`.
   * Both buses must have the same name.
   */
  eventBuses: [primary: string, secondary: string];

  /**
   * When to fail over, and to which region.
   */
  failover: EndpointFailoverConfig;

  /**
   * Whether events are replicated to the secondary region's bus, so they
   * keep being processed there after a failover.
   * @default true
   */
  replication?: boolean;

  /**
   * ARN of the IAM role EventBridge assumes to replicate events. It must
   * trust `events.amazonaws.com`, allow `events:PutEvents` on both buses, and
   * let EventBridge manage its replication rule on each bus
   * (`rule/<bus>/GlobalEndpointManagedRule-*`) and pass the role to that rule's
   * target (`iam:PassRole` on the role, for `events.amazonaws.com`). See the
   * `Endpoint` examples for a least-privilege policy.
   * Required when `replication` is enabled.
   */
  roleArn?: string;
}

/** The endpoint ended in `CREATE_FAILED` or `UPDATE_FAILED`. */
export class EndpointFailed extends Data.TaggedError("EndpointFailed")<{
  readonly endpointName: string;
  readonly state: string;
  readonly reason: string | undefined;
}> {
  override get message() {
    return `Endpoint ${this.endpointName} is ${this.state}: ${this.reason ?? "no reason given"}`;
  }
}

/**
 * An Amazon EventBridge global endpoint: one URL for publishing events that
 * EventBridge routes to an event bus in the primary region, or to the
 * same-named bus in a secondary region when a Route 53 health check fails.
 *
 * Create the same-named bus in both regions, a health check that reflects
 * the primary region's health, and (for replication) a role EventBridge can
 * use to forward events to the secondary bus. Publish through the endpoint by
 * passing it to the `PutEvents` binding.
 *
 * Endpoints do not support tags, so ownership is tracked by the
 * deterministic physical name.
 * ### Creating a Global Endpoint
 * **Example:** Fail Over Between Two Regions
 * ```typescript
 * const primary = yield* AWS.EventBridge.EventBus("Primary", { name: "orders" });
 * const secondary = yield* AWS.EventBridge.EventBus("Secondary", {
 *   name: "orders",
 *   region: "us-east-2",
 * });
 *
 * // Healthy while the primary region's API answers its health route.
 * const health = yield* AWS.Route53.HealthCheck("PrimaryHealth", {
 *   type: "HTTPS",
 *   fullyQualifiedDomainName: "api.us-east-1.example.com",
 *   resourcePath: "/health",
 *   port: 443,
 * });
 *
 * const replication = yield* AWS.IAM.Role("ReplicationRole", {
 *   // `iam:PassRole` below is scoped to roles on this path.
 *   path: "/eventbridge-replication/",
 *   assumeRolePolicyDocument: {
 *     Version: "2012-10-17",
 *     Statement: [
 *       {
 *         Effect: "Allow",
 *         Principal: { Service: "events.amazonaws.com" },
 *         Action: "sts:AssumeRole",
 *       },
 *     ],
 *   },
 *   inlinePolicies: {
 *     Replicate: {
 *       Version: "2012-10-17",
 *       Statement: [
 *         {
 *           Effect: "Allow",
 *           Action: "events:PutEvents",
 *           Resource: [primary.eventBusArn, secondary.eventBusArn],
 *         },
 *         // EventBridge manages a replication rule on each bus.
 *         {
 *           Effect: "Allow",
 *           Action: [
 *             "events:PutRule",
 *             "events:PutTargets",
 *             "events:DeleteRule",
 *             "events:RemoveTargets",
 *           ],
 *           Resource: [
 *             "arn:aws:events:us-east-1:123456789012:rule/orders/GlobalEndpointManagedRule-*",
 *             "arn:aws:events:us-east-2:123456789012:rule/orders/GlobalEndpointManagedRule-*",
 *           ],
 *         },
 *         // ...and passes this role to those rules' targets.
 *         {
 *           Effect: "Allow",
 *           Action: "iam:PassRole",
 *           Resource: "arn:aws:iam::123456789012:role/eventbridge-replication/*",
 *           Condition: { StringEquals: { "iam:PassedToService": "events.amazonaws.com" } },
 *         },
 *       ],
 *     },
 *   },
 * });
 *
 * const endpoint = yield* AWS.EventBridge.Endpoint("Orders", {
 *   eventBuses: [primary.eventBusArn, secondary.eventBusArn],
 *   failover: {
 *     healthCheck: health.healthCheckId,
 *     secondaryRegion: "us-east-2",
 *   },
 *   roleArn: replication.roleArn,
 * });
 * ```
 *
 * **Example:** Fail Over Without Replication
 * ```typescript
 * const endpoint = yield* AWS.EventBridge.Endpoint("Orders", {
 *   eventBuses: [primary.eventBusArn, secondary.eventBusArn],
 *   failover: {
 *     healthCheck: health.healthCheckId,
 *     secondaryRegion: "us-east-2",
 *   },
 *   replication: false,
 * });
 * ```
 *
 * ### Publishing Through the Endpoint
 * **Example:** Publish from a Function
 * ```typescript
 * // init — bind the endpoint (provide AWS.EventBridge.PutEventsHttp)
 * const putEvents = yield* AWS.EventBridge.PutEvents(endpoint);
 *
 * // runtime — EventBridge routes the event to the healthy region
 * yield* putEvents({
 *   Entries: [
 *     {
 *       Source: "my.app",
 *       DetailType: "OrderCreated",
 *       Detail: JSON.stringify({ orderId: "123" }),
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export interface Endpoint extends Resource<
  "AWS.EventBridge.Endpoint",
  EndpointProps,
  {
    /** The name of the endpoint. */
    endpointName: EndpointName;
    /** The ARN of the endpoint. */
    endpointArn: EndpointArn;
    /** The ID of the endpoint, used as `EndpointId` when calling `PutEvents`. */
    endpointId: string;
    /** The URL events are published to. */
    endpointUrl: string;
    /** The ARNs of the primary and secondary event buses. */
    eventBusArns: string[];
  },
  never,
  Providers
> {}
export const Endpoint = Resource<Endpoint>("AWS.EventBridge.Endpoint");

type EndpointAttrs = Endpoint["Attributes"];

/** The ARN EventBridge expects for a Route 53 health check, from its ID or ARN. */
const toHealthCheckArn = (healthCheck: string) =>
  healthCheck.startsWith("arn:") ? healthCheck : `arn:aws:route53:::healthcheck/${healthCheck}`;

const toAttrs = (endpoint: eventbridge.DescribeEndpointResponse): EndpointAttrs => ({
  endpointName: endpoint.Name!,
  endpointArn: endpoint.Arn as EndpointArn,
  endpointId: endpoint.EndpointId ?? "",
  endpointUrl: endpoint.EndpointUrl ?? "",
  eventBusArns: (endpoint.EventBuses ?? []).map((bus) => bus.EventBusArn),
});

export const EndpointProvider = () =>
  Provider.effect(
    Endpoint,
    Effect.gen(function* () {
      const createEndpointName = (id: string, props: { name?: string } = {}) =>
        props.name
          ? Effect.succeed(props.name)
          : createPhysicalName({
              id,
              maxLength: 64,
            });

      const describe = (name: string) =>
        eventbridge
          .describeEndpoint({ Name: name })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));

      /**
       * Poll until the endpoint leaves CREATING/UPDATING. Endpoints settle in
       * well under a minute; the wait is bounded so a stuck endpoint surfaces
       * instead of hanging, and a failed one surfaces its reason.
       */
      const awaitSettled = (name: string) =>
        eventbridge.describeEndpoint({ Name: name }).pipe(
          // A describe fired immediately after create can be eventually
          // consistent — absorb NotFound briefly before polling the state.
          Effect.retry({
            while: (e): boolean => e._tag === "ResourceNotFoundException",
            schedule: Schedule.spaced("1 second"),
            times: 5,
          }),
          Effect.repeat({
            schedule: Schedule.spaced("3 seconds"),
            until: (r): boolean => r.State !== "CREATING" && r.State !== "UPDATING",
            times: 30,
          }),
        );

      const failed = (name: string, r: eventbridge.DescribeEndpointResponse) =>
        new EndpointFailed({ endpointName: name, state: r.State ?? "", reason: r.StateReason });

      /** Delete the endpoint and wait until it is gone. */
      const removeEndpoint = Effect.fn(function* (name: string) {
        yield* eventbridge.deleteEndpoint({ Name: name }).pipe(
          // An endpoint that is still CREATING/UPDATING rejects the delete.
          Effect.retry({
            while: (e): boolean => e._tag === "ConcurrentModificationException",
            schedule: Schedule.spaced("3 seconds"),
            times: 10,
          }),
          Effect.catchTag("ResourceNotFoundException", () => Effect.void),
        );
        // Wait out DELETING so the same name can be recreated right away and
        // the buses it routes to can be deleted.
        yield* describe(name).pipe(
          Effect.repeat({
            schedule: Schedule.spaced("3 seconds"),
            until: (r): boolean => r === undefined,
            times: 30,
          }),
        );
      });

      const createEndpoint = Effect.fn(function* (
        name: string,
        desired: Omit<eventbridge.CreateEndpointRequest, "Name">,
      ) {
        // Tolerate an AlreadyExists race with a peer reconciler; the settled
        // state is observed below either way.
        yield* eventbridge.createEndpoint({ Name: name, ...desired }).pipe(
          Effect.retry({
            // A freshly created replication role takes a few seconds to
            // become assumable by EventBridge (IAM propagation).
            while: (e): boolean => e._tag === "EndpointRoleNotAssumable",
            schedule: Schedule.spaced("3 seconds"),
            times: 15,
          }),
          Effect.catchTag("ResourceAlreadyExistsException", () => Effect.void),
        );
        const settled = yield* awaitSettled(name);
        if (settled.State === "CREATE_FAILED") {
          yield* removeEndpoint(name);
          return yield* failed(name, settled);
        }
        return settled;
      });

      const updateEndpoint = Effect.fn(function* (
        name: string,
        desired: Omit<eventbridge.UpdateEndpointRequest, "Name">,
      ) {
        yield* eventbridge.updateEndpoint({ Name: name, ...desired }).pipe(
          Effect.retry({
            while: (e): boolean => e._tag === "EndpointRoleNotAssumable",
            schedule: Schedule.spaced("3 seconds"),
            times: 15,
          }),
          Effect.retry({
            while: (e): boolean => e._tag === "ConcurrentModificationException",
            schedule: Schedule.spaced("3 seconds"),
            times: 10,
          }),
        );
        const settled = yield* awaitSettled(name);
        if (settled.State === "UPDATE_FAILED") return yield* failed(name, settled);
        return settled;
      });

      return {
        stables: ["endpointName", "endpointArn", "endpointId", "endpointUrl"],
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return;
          const oldName = yield* createEndpointName(id, olds);
          const newName = yield* createEndpointName(id, news);
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          // Endpoints don't support tags; the deterministic physical name is
          // the ownership signal (it embeds app/stage/logical id).
          const name = output?.endpointName ?? (yield* createEndpointName(id, olds ?? {}));
          const described = yield* describe(name);
          if (!described?.Name || !described.Arn) {
            return undefined;
          }
          return toAttrs(described);
        }),
        list: () =>
          Effect.gen(function* () {
            const attrs: EndpointAttrs[] = [];
            let nextToken: string | undefined;
            do {
              const page = yield* eventbridge.listEndpoints({ NextToken: nextToken });
              for (const endpoint of page.Endpoints ?? []) {
                if (!endpoint.Name || !endpoint.Arn) continue;
                attrs.push(toAttrs(endpoint));
              }
              nextToken = page.NextToken;
            } while (nextToken);
            return attrs;
          }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.endpointName ?? (yield* createEndpointName(id, news));
          const desired = {
            Description: news.description,
            RoutingConfig: {
              FailoverConfig: {
                Primary: { HealthCheck: toHealthCheckArn(news.failover.healthCheck) },
                Secondary: { Route: news.failover.secondaryRegion },
              },
            },
            ReplicationConfig: {
              State: news.replication === false ? "DISABLED" : "ENABLED",
            },
            EventBuses: news.eventBuses.map((arn) => ({ EventBusArn: arn })),
            RoleArn: news.roleArn,
          } satisfies Omit<eventbridge.UpdateEndpointRequest, "Name">;

          // Observe — live cloud state is authoritative. A vanished endpoint
          // falls through to create, and so does one a previous run left in
          // CREATE_FAILED (it can never become ACTIVE).
          let observed = yield* describe(name);
          if (observed?.Arn) {
            observed = yield* awaitSettled(name);
            if (observed.State === "CREATE_FAILED") {
              yield* removeEndpoint(name);
              observed = undefined;
            }
          }

          // Ensure — create the endpoint and wait for it to settle. The
          // replication role is checked again after the endpoint is accepted:
          // while its policy is still propagating, the endpoint ends in
          // CREATE_FAILED ("does not grant EventBridge the PutRule
          // permission"), so a failed create is removed and retried.
          if (!observed?.Arn) {
            observed = yield* createEndpoint(name, desired).pipe(
              Effect.retry({
                while: (e): boolean => e._tag === "EndpointFailed",
                schedule: Schedule.spaced("10 seconds"),
                times: 3,
              }),
            );
          }

          // Sync — diff the observed configuration against the desired one
          // and update only when something differs (or the last update
          // failed).
          const drifted =
            observed.State === "UPDATE_FAILED" ||
            (observed.Description ?? "") !== (desired.Description ?? "") ||
            observed.RoutingConfig?.FailoverConfig?.Primary?.HealthCheck !==
              desired.RoutingConfig.FailoverConfig.Primary.HealthCheck ||
            observed.RoutingConfig?.FailoverConfig?.Secondary?.Route !==
              desired.RoutingConfig.FailoverConfig.Secondary.Route ||
            (observed.ReplicationConfig?.State ?? "ENABLED") !== desired.ReplicationConfig.State ||
            (observed.RoleArn ?? "") !== (desired.RoleArn ?? "") ||
            (observed.EventBuses ?? [])
              .map((bus) => bus.EventBusArn)
              .sort()
              .join(",") !== [...news.eventBuses].sort().join(",");
          if (drifted) {
            // Same propagation race as create, ending in UPDATE_FAILED.
            observed = yield* updateEndpoint(name, desired).pipe(
              Effect.retry({
                while: (e): boolean => e._tag === "EndpointFailed",
                schedule: Schedule.spaced("10 seconds"),
                times: 3,
              }),
            );
          }

          const attrs = toAttrs(observed);
          yield* session.note(attrs.endpointUrl);
          return attrs;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* removeEndpoint(output.endpointName);
        }),
      };
    }),
  );