sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ELBv2/ TargetGroupAttachment.ts

import * as elbv2 from "@distilled.cloud/aws/elastic-load-balancing-v2";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { type TargetGroup, type TargetGroupArn } from "./TargetGroup.ts";

export interface TargetGroupAttachmentProps {
  /** The target group to register the target with. Changing it replaces the attachment. */
  targetGroupArn: Input<TargetGroupArn> | TargetGroup;
  /**
   * The target ID: an instance ID (`instance` target type), an IP address
   * (`ip`), a Lambda function ARN (`lambda`), or an ALB ARN (`alb`). Changing
   * it replaces the attachment.
   */
  targetId: string;
  /**
   * The port on which the target receives traffic. Defaults to the target
   * group port. Not applicable to `lambda` targets. Changing it replaces the
   * attachment.
   */
  port?: number;
  /**
   * The Availability Zone of the target. Set to `all` to register an IP
   * target outside the target group's VPC (e.g. an on-prem address). Changing
   * it replaces the attachment.
   */
  availabilityZone?: string;
}

export interface TargetGroupAttachment extends Resource<
  "AWS.ELBv2.TargetGroupAttachment",
  TargetGroupAttachmentProps,
  {
    /** The ARN of the target group the target is registered with. */
    targetGroupArn: TargetGroupArn;
    /** The registered target: an instance ID, IP address, or Lambda/ALB ARN. */
    targetId: string;
    /** The port the target receives traffic on, if applicable. */
    port: number | undefined;
    /** The Availability Zone the target was registered in, if specified. */
    availabilityZone: string | undefined;
  },
  never,
  Providers
> {}

/**
 * Registers a single target (instance, IP address, Lambda function, or ALB)
 * with an ELBv2 target group. ECS services register their own tasks, so this
 * resource matters for Lambda-behind-ALB, EC2 instances, and static IPs.
 *
 * For `lambda` targets, the Lambda function's resource policy must allow
 * `elasticloadbalancing.amazonaws.com` to invoke it, scoped to the target
 * group ARN — create a {@link Permission} first. The provider retries the
 * registration briefly while that permission propagates.
 * ### Registering Targets
 * **Example:** Lambda function target
 * ```typescript
 * const tg = yield* TargetGroup("fn", { targetType: "lambda" });
 * yield* Lambda.Permission("AlbInvoke", {
 *   action: "lambda:InvokeFunction",
 *   functionName: fn.functionArn.as<string>(),
 *   principal: "elasticloadbalancing.amazonaws.com",
 *   sourceArn: tg.targetGroupArn.as<string>(),
 * });
 * yield* TargetGroupAttachment("fn-target", {
 *   targetGroupArn: tg.targetGroupArn,
 *   targetId: fn.functionArn.as<string>(),
 * });
 * ```
 *
 * **Example:** IP address target
 * ```typescript
 * yield* TargetGroupAttachment("ip-target", {
 *   targetGroupArn: tg.targetGroupArn,
 *   targetId: "10.0.1.15",
 *   port: 8080,
 * });
 * ```
 *
 * **Example:** EC2 instance target
 * ```typescript
 * yield* TargetGroupAttachment("instance-target", {
 *   targetGroupArn: tg.targetGroupArn,
 *   targetId: instance.instanceId,
 *   port: 80,
 * });
 * ```
 *
 * @resource
 */
export const TargetGroupAttachment = Resource<TargetGroupAttachment>(
  "AWS.ELBv2.TargetGroupAttachment",
);

// Registering a Lambda target validates that the function's resource policy
// grants elasticloadbalancing.amazonaws.com invoke permission. The Permission
// resource is often created in the same deploy with no data dependency on the
// attachment, so registerTargets can run before the policy lands. ELB surfaces
// the missing-permission case as either `InvalidTargetException` or an
// empty-message `AccessDeniedException` (both members of the registerTargets
// error union — AccessDeniedException via CommonErrors), so retry both briefly
// while IAM propagates. Explicitly typed so `Retry.Return`'s conditional type
// never leaks into declaration emit.
const retryThroughPermissionPropagation = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "InvalidTargetException" || e._tag === "AccessDeniedException",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(15)]),
  });

const wireTarget = (props: {
  targetId: string;
  port?: number;
  availabilityZone?: string;
}): elbv2.TargetDescription => ({
  Id: props.targetId,
  Port: props.port,
  AvailabilityZone: props.availabilityZone,
});

export const TargetGroupAttachmentProvider = () =>
  Provider.succeed(TargetGroupAttachment, {
    stables: ["targetGroupArn", "targetId", "port", "availabilityZone"],
    diff: Effect.fn(function* ({ olds, news }) {
      if (!isResolved(news)) return;
      // Registration has no mutable aspect — every change is a replacement.
      if (
        olds.targetGroupArn !== news.targetGroupArn ||
        olds.targetId !== news.targetId ||
        olds.port !== news.port ||
        olds.availabilityZone !== news.availabilityZone
      ) {
        return { action: "replace" } as const;
      }
    }),
    read: Effect.fn(function* ({ output }) {
      if (!output) {
        return undefined;
      }
      // describeTargetHealth without an explicit Targets filter lists only
      // registered targets, so presence in the response means registered.
      const health = yield* elbv2
        .describeTargetHealth({ TargetGroupArn: output.targetGroupArn })
        .pipe(Effect.catchTag(["TargetGroupNotFoundException"], () => Effect.undefined));
      const registered = health?.TargetHealthDescriptions?.some(
        (d) =>
          d.Target?.Id === output.targetId &&
          (output.port === undefined || d.Target?.Port === output.port),
      );
      return registered ? output : undefined;
    }),
    // Attachments belong to a target group. Enumerate every target group,
    // then every registered target.
    list: Effect.fn(function* () {
      const targetGroupArns = yield* elbv2.describeTargetGroups.pages({}).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.TargetGroups ?? []).flatMap((tg) =>
              tg.TargetGroupArn ? [tg.TargetGroupArn as TargetGroupArn] : [],
            ),
          ),
        ),
      );
      const rows = yield* Effect.forEach(
        targetGroupArns,
        (targetGroupArn) =>
          elbv2.describeTargetHealth({ TargetGroupArn: targetGroupArn }).pipe(
            Effect.map((health) =>
              (health.TargetHealthDescriptions ?? []).flatMap((d) =>
                d.Target?.Id
                  ? [
                      {
                        targetGroupArn,
                        targetId: d.Target.Id,
                        port: d.Target.Port,
                        availabilityZone: d.Target.AvailabilityZone,
                      },
                    ]
                  : [],
              ),
            ),
            // The group may vanish between enumeration and health lookup.
            Effect.catchTag(["TargetGroupNotFoundException"], () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      const result: TargetGroupAttachment["Attributes"][] = rows.flat();
      return result;
    }),
    reconcile: Effect.fn(function* ({ news, session }) {
      const targetGroupArn = news.targetGroupArn as TargetGroupArn;
      const target = wireTarget(news);

      // Observe — is the target already registered?
      const health = yield* elbv2
        .describeTargetHealth({ TargetGroupArn: targetGroupArn })
        .pipe(Effect.catchTag(["InvalidTargetException"], () => Effect.undefined));
      const registered = health?.TargetHealthDescriptions?.some(
        (d) =>
          d.Target?.Id === news.targetId &&
          (news.port === undefined || d.Target?.Port === news.port),
      );

      // Ensure — registerTargets is an idempotent put, but skip the call
      // (and its permission-propagation retry) when already registered.
      if (!registered) {
        yield* retryThroughPermissionPropagation(
          elbv2.registerTargets({
            TargetGroupArn: targetGroupArn,
            Targets: [target],
          }),
        );
      }

      yield* session.note(`${news.targetId} -> ${targetGroupArn}`);
      return {
        targetGroupArn,
        targetId: news.targetId,
        port: news.port,
        availabilityZone: news.availabilityZone,
      };
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* elbv2
        .deregisterTargets({
          TargetGroupArn: output.targetGroupArn,
          Targets: [
            wireTarget({
              targetId: output.targetId,
              port: output.port,
              availabilityZone: output.availabilityZone,
            }),
          ],
        })
        .pipe(
          // Already deregistered / group already deleted.
          Effect.catchTag(
            ["InvalidTargetException", "TargetGroupNotFoundException"],
            () => Effect.void,
          ),
        );
    }),
  });