sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ GlobalAccelerator/ EndpointGroup.ts

import * as ga from "@distilled.cloud/aws/global-accelerator";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { toWireSeconds } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { retryGaDeletion, withGaRegion } from "./common.ts";

export interface EndpointConfiguration {
  /**
   * ID of the endpoint: an ALB or NLB ARN, an Elastic IP allocation ID, or
   * an EC2 instance ID.
   */
  endpointId: string;
  /**
   * Relative traffic weight for this endpoint versus the other endpoints in
   * the group (`0` - `255`).
   * @default 128
   */
  weight?: number;
  /**
   * Preserve the client IP address through to the endpoint. Supported for
   * ALB and EC2 instance endpoints.
   * @default true for supported endpoint types
   */
  clientIPPreservationEnabled?: boolean;
  /**
   * ARN of the cross-account attachment authorizing this endpoint when it
   * lives in another AWS account.
   */
  attachmentArn?: string;
}

export interface PortOverride {
  /**
   * The listener port to override.
   */
  listenerPort: number;
  /**
   * The endpoint port that traffic on the overridden listener port is
   * routed to.
   */
  endpointPort: number;
}

export interface EndpointGroupProps {
  /**
   * ARN of the listener the endpoint group attaches to. Changing it
   * replaces the endpoint group.
   */
  listenerArn: string;
  /**
   * The AWS Region where the endpoint group's endpoints live. One endpoint
   * group per region per listener; changing it replaces the group.
   */
  endpointGroupRegion: string;
  /**
   * The endpoints (ALBs, NLBs, EC2 instances, Elastic IPs) traffic is
   * routed to. Omitting it (or `[]`) keeps the group empty.
   */
  endpoints?: EndpointConfiguration[];
  /**
   * The percentage of the listener's traffic to send to this endpoint
   * group (`0` - `100`), applied after location-based routing.
   * @default 100
   */
  trafficDialPercentage?: number;
  /**
   * The port used for health checks.
   * @default the first port of the listener's port ranges
   */
  healthCheckPort?: number;
  /**
   * The protocol used for health checks.
   * @default "TCP"
   */
  healthCheckProtocol?: "TCP" | "HTTP" | "HTTPS";
  /**
   * The path for HTTP/HTTPS health checks.
   * @default "/"
   */
  healthCheckPath?: string;
  /**
   * Time between health checks, e.g. `"10 seconds"` or
   * `Duration.seconds(30)`. Rounded to whole seconds on the wire; the API
   * accepts `10` or `30` seconds.
   * @default "30 seconds"
   */
  healthCheckInterval?: Duration.Input;
  /**
   * Consecutive health-check successes/failures required to flip an
   * endpoint healthy/unhealthy.
   * @default 3
   */
  thresholdCount?: number;
  /**
   * Overrides routing specific listener ports to different endpoint ports.
   */
  portOverrides?: PortOverride[];
}

export interface EndpointGroup extends Resource<
  "AWS.GlobalAccelerator.EndpointGroup",
  EndpointGroupProps,
  {
    /** The ARN of the endpoint group. */
    endpointGroupArn: string;
    /** The ARN of the listener the endpoint group is attached to. */
    listenerArn: string;
    /** The AWS Region the group's endpoints live in. */
    endpointGroupRegion: string;
    /** The percentage of listener traffic dialed to this group. */
    trafficDialPercentage: number;
    /** The health-check protocol: `TCP`, `HTTP`, or `HTTPS`. */
    healthCheckProtocol: string;
    /** The port used for health checks. */
    healthCheckPort: number | undefined;
    /** The path used for HTTP/HTTPS health checks. */
    healthCheckPath: string | undefined;
    /** Seconds between health checks. */
    healthCheckInterval: number;
    /** Consecutive checks required to flip an endpoint's health state. */
    thresholdCount: number;
    /** The endpoints in the group with their observed health. */
    endpoints: {
      /** The endpoint's ID (ALB/NLB ARN, EIP allocation ID, or instance ID). */
      endpointId: string | undefined;
      /** Relative traffic weight of the endpoint. */
      weight: number | undefined;
      /** Observed health: `HEALTHY`, `UNHEALTHY`, or `INITIAL`. */
      healthState: string | undefined;
      /** Whether the client IP is preserved through to the endpoint. */
      clientIPPreservationEnabled: boolean | undefined;
    }[];
  },
  never,
  Providers
> {}

/**
 * A Global Accelerator endpoint group — the set of regional endpoints
 * (ALBs, NLBs, EC2 instances, or Elastic IPs) that a listener routes
 * traffic to in one AWS Region, with traffic-dial and health-check
 * configuration.
 *
 * One endpoint group per region per listener. Everything except the
 * listener and region is updatable in place.
 * ### Creating Endpoint Groups
 * **Example:** Route to an Application Load Balancer
 * ```typescript
 * const group = yield* GlobalAccelerator.EndpointGroup("UsWest2", {
 *   listenerArn: listener.listenerArn,
 *   endpointGroupRegion: "us-west-2",
 *   endpoints: [{ endpointId: alb.loadBalancerArn }],
 * });
 * ```
 *
 * **Example:** Weighted Endpoints with HTTP Health Checks
 * ```typescript
 * const group = yield* GlobalAccelerator.EndpointGroup("UsEast1", {
 *   listenerArn: listener.listenerArn,
 *   endpointGroupRegion: "us-east-1",
 *   endpoints: [
 *     { endpointId: blueAlb.loadBalancerArn, weight: 200 },
 *     { endpointId: greenAlb.loadBalancerArn, weight: 55 },
 *   ],
 *   healthCheckProtocol: "HTTP",
 *   healthCheckPath: "/health",
 *   healthCheckInterval: "10 seconds",
 * });
 * ```
 *
 * ### Traffic Management
 * **Example:** Canary a Region with the Traffic Dial
 * ```typescript
 * const group = yield* GlobalAccelerator.EndpointGroup("Canary", {
 *   listenerArn: listener.listenerArn,
 *   endpointGroupRegion: "eu-west-1",
 *   trafficDialPercentage: 10,
 * });
 * ```
 *
 * @resource
 */
export const EndpointGroup = Resource<EndpointGroup>("AWS.GlobalAccelerator.EndpointGroup");

// Endpoint-group ARNs embed the parent listener ARN:
// arn:...:accelerator/{id}/listener/{id}/endpoint-group/{id}
const listenerArnOf = (endpointGroupArn: string) => endpointGroupArn.split("/endpoint-group/")[0]!;

const toAttributes = (g: ga.EndpointGroup, endpointGroupArn: string) => ({
  endpointGroupArn,
  listenerArn: listenerArnOf(endpointGroupArn),
  endpointGroupRegion: g.EndpointGroupRegion ?? "",
  trafficDialPercentage: g.TrafficDialPercentage ?? 100,
  healthCheckProtocol: g.HealthCheckProtocol ?? "TCP",
  healthCheckPort: g.HealthCheckPort,
  healthCheckPath: g.HealthCheckPath,
  healthCheckInterval: g.HealthCheckIntervalSeconds ?? 30,
  thresholdCount: g.ThresholdCount ?? 3,
  endpoints: (g.EndpointDescriptions ?? []).map((d) => ({
    endpointId: d.EndpointId,
    weight: d.Weight,
    healthState: d.HealthState,
    clientIPPreservationEnabled: d.ClientIPPreservationEnabled,
  })),
});

// The desired mutable configuration, shared by create and update. Defaults
// are applied explicitly so removing a prop converges back to the default.
const desiredConfig = (news: EndpointGroupProps) => ({
  EndpointConfigurations: (news.endpoints ?? []).map((e) => ({
    EndpointId: e.endpointId,
    Weight: e.weight,
    ClientIPPreservationEnabled: e.clientIPPreservationEnabled,
    AttachmentArn: e.attachmentArn,
  })),
  TrafficDialPercentage: news.trafficDialPercentage ?? 100,
  HealthCheckPort: news.healthCheckPort,
  HealthCheckProtocol: news.healthCheckProtocol ?? "TCP",
  HealthCheckPath: news.healthCheckPath,
  HealthCheckIntervalSeconds: toWireSeconds(news.healthCheckInterval) ?? 30,
  ThresholdCount: news.thresholdCount ?? 3,
  PortOverrides: (news.portOverrides ?? []).map((o) => ({
    ListenerPort: o.listenerPort,
    EndpointPort: o.endpointPort,
  })),
});

const normalizeOverrides = (overrides: ga.PortOverride[] | undefined) =>
  JSON.stringify(
    (overrides ?? [])
      .map((o) => [o.ListenerPort ?? 0, o.EndpointPort ?? 0])
      .sort((a, b) => a[0]! - b[0]!),
  );

// Compare observed cloud state against the desired props for every aspect we
// manage. Fields the user never specified (healthCheckPort/path) fall back to
// service-computed defaults and are only compared when explicitly desired.
const hasDrift = (live: ga.EndpointGroup, news: EndpointGroupProps): boolean => {
  if ((live.TrafficDialPercentage ?? 100) !== (news.trafficDialPercentage ?? 100)) {
    return true;
  }
  if ((live.HealthCheckProtocol ?? "TCP") !== (news.healthCheckProtocol ?? "TCP")) {
    return true;
  }
  if ((live.HealthCheckIntervalSeconds ?? 30) !== (toWireSeconds(news.healthCheckInterval) ?? 30)) {
    return true;
  }
  if ((live.ThresholdCount ?? 3) !== (news.thresholdCount ?? 3)) return true;
  if (news.healthCheckPort !== undefined && live.HealthCheckPort !== news.healthCheckPort) {
    return true;
  }
  if (news.healthCheckPath !== undefined && live.HealthCheckPath !== news.healthCheckPath) {
    return true;
  }
  if (
    normalizeOverrides(live.PortOverrides) !== normalizeOverrides(desiredConfig(news).PortOverrides)
  ) {
    return true;
  }
  const observed = new Map((live.EndpointDescriptions ?? []).map((d) => [d.EndpointId ?? "", d]));
  const desired = news.endpoints ?? [];
  if (observed.size !== desired.length) return true;
  for (const e of desired) {
    const d = observed.get(e.endpointId);
    if (!d) return true;
    if (e.weight !== undefined && d.Weight !== e.weight) return true;
    if (
      e.clientIPPreservationEnabled !== undefined &&
      d.ClientIPPreservationEnabled !== e.clientIPPreservationEnabled
    ) {
      return true;
    }
  }
  return false;
};

const describeEndpointGroup = Effect.fn(function* (endpointGroupArn: string) {
  return yield* withGaRegion(ga.describeEndpointGroup({ EndpointGroupArn: endpointGroupArn })).pipe(
    Effect.map((r) => r.EndpointGroup),
    Effect.catchTag("EndpointGroupNotFoundException", () => Effect.undefined),
  );
});

// An endpoint group's natural identity is (listener, region) — GA allows at
// most one per region per listener, so this lookup is exact.
const findEndpointGroup = Effect.fn(function* (
  listenerArn: string | undefined,
  region: string | undefined,
) {
  if (!listenerArn || !region) return undefined;
  const groups = yield* withGaRegion(
    ga.listEndpointGroups.items({ ListenerArn: listenerArn }).pipe(Stream.runCollect),
  ).pipe(
    Effect.map((chunk) => Array.from(chunk)),
    Effect.catchTag("ListenerNotFoundException", () => Effect.succeed([] as ga.EndpointGroup[])),
  );
  return groups.find((g) => g.EndpointGroupRegion === region);
});

export const EndpointGroupProvider = () =>
  Provider.succeed(EndpointGroup, {
    stables: ["endpointGroupArn", "listenerArn", "endpointGroupRegion"],
    // Sub-resource keyed entirely by its parent listener (and untagged) —
    // account-wide enumeration happens via the Accelerator resource.
    list: () => Effect.succeed([]),
    read: Effect.fn(function* ({ olds, output }) {
      if (output?.endpointGroupArn) {
        const live = yield* describeEndpointGroup(output.endpointGroupArn);
        if (live) return toAttributes(live, output.endpointGroupArn);
      }
      const found = yield* findEndpointGroup(olds?.listenerArn, olds?.endpointGroupRegion);
      if (!found?.EndpointGroupArn) return undefined;
      return toAttributes(found, found.EndpointGroupArn);
    }),
    diff: Effect.fn(function* ({ news, olds }) {
      if (!isResolved(news)) return undefined;
      if (news.listenerArn !== olds.listenerArn) {
        return { action: "replace" } as const;
      }
      if (news.endpointGroupRegion !== olds.endpointGroupRegion) {
        return { action: "replace" } as const;
      }
      // everything else updates in place.
    }),
    reconcile: Effect.fn(function* ({ news, output, instanceId, session }) {
      // Observe — cached ARN first, then the exact (listener, region) key.
      let live = output?.endpointGroupArn
        ? yield* describeEndpointGroup(output.endpointGroupArn)
        : undefined;
      if (!live?.EndpointGroupArn) {
        live = yield* findEndpointGroup(news.listenerArn, news.endpointGroupRegion);
      }

      // Ensure — create if missing; a concurrent create for the same
      // (listener, region) surfaces as AlreadyExists and we converge on it.
      if (!live?.EndpointGroupArn) {
        live = yield* withGaRegion(
          ga.createEndpointGroup({
            ListenerArn: news.listenerArn,
            EndpointGroupRegion: news.endpointGroupRegion,
            ...desiredConfig(news),
            IdempotencyToken: instanceId,
          }),
        ).pipe(
          Effect.map((r) => r.EndpointGroup),
          Effect.catchTag("EndpointGroupAlreadyExistsException", () =>
            findEndpointGroup(news.listenerArn, news.endpointGroupRegion),
          ),
        );
      }
      if (!live?.EndpointGroupArn) {
        return yield* Effect.die(new Error("CreateEndpointGroup returned no endpoint group"));
      }
      const endpointGroupArn = live.EndpointGroupArn;

      // Sync — one update with the full desired config when anything drifts.
      if (hasDrift(live, news)) {
        const updated = yield* withGaRegion(
          ga.updateEndpointGroup({
            EndpointGroupArn: endpointGroupArn,
            ...desiredConfig(news),
          }),
        ).pipe(Effect.map((r) => r.EndpointGroup));
        if (updated) live = updated;
      }

      yield* session.note(endpointGroupArn);
      return toAttributes(live, endpointGroupArn);
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* ga
        .deleteEndpointGroup({
          EndpointGroupArn: output.endpointGroupArn,
        })
        .pipe(
          withGaRegion,
          retryGaDeletion,
          Effect.catchTag("EndpointGroupNotFoundException", () => Effect.void),
        );
    }),
  });