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

import * as elbv2 from "@distilled.cloud/aws/elastic-load-balancing-v2";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import { toSeconds } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { AccountID } from "../Environment.ts";
import { plainJson } from "../internal/Observe.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import { attributeDelta, observedAttributes } from "./common.ts";
import { readElbTags } from "./internal.ts";

export type TargetGroupName = string;
export type TargetGroupArn =
  `arn:aws:elasticloadbalancing:${RegionID}:${AccountID}:targetgroup/${string}`;

export interface TargetGroupProps {
  /** The target group name. If omitted, a unique name is generated. Changing it replaces the target group. */
  name?: string;
  /** The VPC the targets live in. Not required for `lambda` targets. Changing it replaces the target group. */
  vpcId?: string;
  /** The port on which targets receive traffic. Changing it replaces the target group. */
  port?: number;
  /**
   * The protocol for routing traffic to targets. Changing it replaces the
   * target group.
   * @default "HTTP"
   */
  protocol?: "HTTP" | "HTTPS" | "TCP" | "UDP" | "TCP_UDP" | "TLS" | "GENEVE";
  /**
   * The application protocol version. Use `GRPC` for gRPC, `HTTP2` for HTTP/2.
   * Changing it replaces the target group.
   */
  protocolVersion?: "HTTP1" | "HTTP2" | "GRPC";
  /**
   * The target type. Changing it replaces the target group.
   * @default "ip"
   */
  targetType?: "ip" | "instance" | "lambda" | "alb";
  /** The IP address type (`ipv4`/`ipv6`). Changing it replaces the target group. */
  ipAddressType?: "ipv4" | "ipv6";
  /** The health-check path (HTTP/HTTPS). Updated in place. */
  healthCheckPath?: string;
  /** The health-check port. Updated in place. */
  healthCheckPort?: string;
  /** The health-check protocol. Updated in place. */
  healthCheckProtocol?: string;
  /** Whether health checks are enabled. Updated in place. */
  healthCheckEnabled?: boolean;
  /** The approximate interval between health checks — e.g. `"15 seconds"`. Sent to AWS as whole seconds. Updated in place. */
  healthCheckInterval?: Duration.Input;
  /** The amount of time to wait for a health-check response — e.g. `"5 seconds"`. Sent to AWS as whole seconds. Updated in place. */
  healthCheckTimeout?: Duration.Input;
  /** The number of consecutive successes before a target is healthy. Updated in place. */
  healthyThresholdCount?: number;
  /** The number of consecutive failures before a target is unhealthy. Updated in place. */
  unhealthyThresholdCount?: number;
  /** The HTTP/gRPC codes used to determine a healthy response. Updated in place. */
  matcher?: { HttpCode?: string; GrpcCode?: string };
  /** Raw target-group attributes (deregistration delay, stickiness, slow start, ...). */
  attributes?: Record<string, string>;
  /** Tags to apply to the target group. */
  tags?: Record<string, string>;
}

export interface TargetGroup extends Resource<
  "AWS.ELBv2.TargetGroup",
  TargetGroupProps,
  {
    /** The ARN of the target group. */
    targetGroupArn: TargetGroupArn;
    /** The name of the target group. */
    targetGroupName: TargetGroupName;
    /** Undefined for `lambda` target groups (they have no port). */
    port: number | undefined;
    /** Undefined for `lambda` target groups (they have no protocol). */
    protocol: string | undefined;
    /** The target type (`instance`, `ip`, `lambda`, or `alb`). */
    targetType: string;
    /** Undefined for `lambda` target groups (they are not VPC-scoped). */
    vpcId: string | undefined;
    /** The tags applied to the target group. */
    tags: Record<string, string>;
    /**
     * The live values of the keys declared in `attributes`. Undeclared
     * attributes are left out so AWS defaults never register as drift.
     */
    attributes?: Record<string, string>;
    /**
     * The health-check settings the props declare, as observed. Lets
     * `alchemy drift` detect out-of-band changes.
     */
    healthCheck?: Partial<HealthCheckSettings>;
  },
  never,
  Providers
> {}

/**
 * An ELBv2 target group. A target group routes requests to one or more
 * registered targets (instances, IPs, Lambda functions, or another ALB) using
 * the configured protocol and port, and runs health checks against them.
 * ### Creating a Target Group
 * **Example:** HTTP target group
 * ```typescript
 * const tg = yield* TargetGroup("web", {
 *   vpcId: vpc.vpcId,
 *   port: 80,
 *   protocol: "HTTP",
 *   targetType: "ip",
 * });
 * ```
 *
 * **Example:** Lambda target group
 * ```typescript
 * // No vpc/port/protocol — the target is a Lambda function.
 * const tg = yield* TargetGroup("fn", {
 *   targetType: "lambda",
 * });
 * ```
 *
 * **Example:** gRPC target group
 * ```typescript
 * const tg = yield* TargetGroup("grpc", {
 *   vpcId: vpc.vpcId,
 *   port: 50051,
 *   protocol: "HTTP",
 *   protocolVersion: "GRPC",
 *   matcher: { GrpcCode: "0" },
 * });
 * ```
 *
 * ### Health Checks
 * **Example:** Custom health-check thresholds
 * ```typescript
 * const tg = yield* TargetGroup("api", {
 *   vpcId: vpc.vpcId,
 *   port: 8080,
 *   protocol: "HTTP",
 *   healthCheckPath: "/healthz",
 *   healthCheckInterval: "15 seconds",
 *   healthyThresholdCount: 3,
 *   unhealthyThresholdCount: 3,
 * });
 * ```
 *
 * @resource
 */
export const TargetGroup = Resource<TargetGroup>("AWS.ELBv2.TargetGroup");

type HealthCheckSettings = Pick<
  elbv2.TargetGroup,
  | "HealthCheckPath"
  | "HealthCheckPort"
  | "HealthCheckProtocol"
  | "HealthCheckEnabled"
  | "HealthCheckIntervalSeconds"
  | "HealthCheckTimeoutSeconds"
  | "HealthyThresholdCount"
  | "UnhealthyThresholdCount"
  | "Matcher"
>;

/**
 * The health-check settings reconcile converges (those the props declare),
 * taken from `settings`. `read` and `reconcile` share it so a converged
 * target group reads unchanged.
 */
const observeHealthCheck = (
  settings: HealthCheckSettings,
  props: TargetGroupProps | undefined,
): Partial<HealthCheckSettings> =>
  plainJson({
    HealthCheckPath: props?.healthCheckPath === undefined ? undefined : settings.HealthCheckPath,
    HealthCheckPort: props?.healthCheckPort === undefined ? undefined : settings.HealthCheckPort,
    HealthCheckProtocol:
      props?.healthCheckProtocol === undefined ? undefined : settings.HealthCheckProtocol,
    HealthCheckEnabled:
      props?.healthCheckEnabled === undefined ? undefined : settings.HealthCheckEnabled,
    HealthCheckIntervalSeconds:
      props?.healthCheckInterval === undefined ? undefined : settings.HealthCheckIntervalSeconds,
    HealthCheckTimeoutSeconds:
      props?.healthCheckTimeout === undefined ? undefined : settings.HealthCheckTimeoutSeconds,
    HealthyThresholdCount:
      props?.healthyThresholdCount === undefined ? undefined : settings.HealthyThresholdCount,
    UnhealthyThresholdCount:
      props?.unhealthyThresholdCount === undefined ? undefined : settings.UnhealthyThresholdCount,
    Matcher: props?.matcher === undefined ? undefined : settings.Matcher,
  });

export const TargetGroupProvider = () =>
  Provider.effect(
    TargetGroup,
    Effect.gen(function* () {
      const toName = (id: string, props: { name?: string } = {}) =>
        props.name
          ? Effect.succeed(props.name)
          : createPhysicalName({ id, maxLength: 32, lowercase: true });

      // The observed values of the declared attribute keys; skips the call
      // when nothing is declared.
      const readAttributes = Effect.fn(function* (
        targetGroupArn: string,
        declared: Record<string, string> | undefined,
      ) {
        if (!declared || Object.keys(declared).length === 0) return undefined;
        const observed = yield* elbv2.describeTargetGroupAttributes({
          TargetGroupArn: targetGroupArn,
        });
        return observedAttributes(declared, observed.Attributes);
      });

      return {
        stables: ["targetGroupArn", "targetGroupName", "vpcId"],
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          if ((yield* toName(id, olds ?? {})) !== (yield* toName(id, news ?? {}))) {
            return { action: "replace" } as const;
          }
          if (
            !deepEqual(
              {
                vpcId: olds.vpcId,
                protocol: olds.protocol ?? "HTTP",
                protocolVersion: olds.protocolVersion,
                port: olds.port,
                targetType: olds.targetType ?? "ip",
                ipAddressType: olds.ipAddressType,
              },
              {
                vpcId: news.vpcId,
                protocol: news.protocol ?? "HTTP",
                protocolVersion: news.protocolVersion,
                port: news.port,
                targetType: news.targetType ?? "ip",
                ipAddressType: news.ipAddressType,
              },
            )
          ) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ olds, output }) {
          if (!output) {
            return undefined;
          }
          const described = yield* elbv2
            .describeTargetGroups({
              TargetGroupArns: [output.targetGroupArn],
            })
            .pipe(Effect.catchTag("TargetGroupNotFoundException", () => Effect.undefined));
          const targetGroup = described?.TargetGroups?.[0];
          if (!targetGroup?.TargetGroupArn) {
            return undefined;
          }
          const attributes = yield* readAttributes(output.targetGroupArn, olds?.attributes).pipe(
            Effect.catchTag("TargetGroupNotFoundException", () => Effect.succeed(null)),
          );
          if (attributes === null) {
            return undefined;
          }
          const tags = yield* readElbTags(output.targetGroupArn).pipe(
            Effect.catchTag("TargetGroupNotFoundException", () => Effect.undefined),
          );
          if (tags === undefined) {
            return undefined;
          }
          return {
            ...output,
            port: targetGroup.Port,
            protocol: targetGroup.Protocol,
            targetType: targetGroup.TargetType!,
            vpcId: targetGroup.VpcId,
            tags,
            attributes,
            healthCheck: observeHealthCheck(targetGroup, olds),
          };
        }),
        // Target groups are account/region-scoped. Exhaustively paginate
        // describeTargetGroups, then fetch tags per group (Attributes carry
        // them) to produce the same shape `read` returns.
        list: () =>
          Effect.gen(function* () {
            const targetGroups = yield* elbv2.describeTargetGroups.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) =>
                  (page.TargetGroups ?? []).filter(
                    (tg): tg is elbv2.TargetGroup & { TargetGroupArn: string } =>
                      tg.TargetGroupArn != null,
                  ),
                ),
              ),
            );
            return yield* Effect.forEach(
              targetGroups,
              (tg) =>
                Effect.gen(function* () {
                  const tagDescriptions = yield* elbv2
                    .describeTags({ ResourceArns: [tg.TargetGroupArn] })
                    .pipe(Effect.catchTag("TargetGroupNotFoundException", () => Effect.undefined));
                  const tags = Object.fromEntries(
                    (tagDescriptions?.TagDescriptions?.[0]?.Tags ?? [])
                      .filter(
                        (t): t is { Key: string; Value: string } =>
                          typeof t.Key === "string" && typeof t.Value === "string",
                      )
                      .map((t) => [t.Key, t.Value]),
                  );
                  return {
                    targetGroupArn: tg.TargetGroupArn as TargetGroupArn,
                    targetGroupName: tg.TargetGroupName!,
                    port: tg.Port,
                    protocol: tg.Protocol,
                    targetType: tg.TargetType!,
                    vpcId: tg.VpcId,
                    tags,
                  };
                }),
              { concurrency: 10 },
            );
          }),
        reconcile: Effect.fn(function* ({ id, news, session }) {
          const name = yield* toName(id, news);
          const desiredTags = {
            ...(yield* createInternalTags(id)),
            ...news.tags,
          };

          // Observe — look up by deterministic name.
          let described = yield* elbv2
            .describeTargetGroups({
              Names: [name],
            })
            .pipe(Effect.catchTag("TargetGroupNotFoundException", () => Effect.undefined));
          let targetGroup = described?.TargetGroups?.[0];

          // Ensure — create if missing. Stable axes (vpcId, port, protocol,
          // targetType) are handled by diff so we don't deal with mismatch.
          // Lambda target groups have no port/protocol/VPC — the API rejects
          // those members, so omit them entirely.
          const isLambdaTarget = news.targetType === "lambda";
          if (!targetGroup?.TargetGroupArn) {
            const created = yield* elbv2.createTargetGroup({
              Name: name,
              Port: isLambdaTarget ? undefined : news.port,
              Protocol: isLambdaTarget ? undefined : (news.protocol ?? "HTTP"),
              ProtocolVersion: isLambdaTarget ? undefined : news.protocolVersion,
              VpcId: isLambdaTarget ? undefined : news.vpcId,
              TargetType: news.targetType ?? "ip",
              IpAddressType: isLambdaTarget ? undefined : news.ipAddressType,
              HealthCheckPath: news.healthCheckPath,
              HealthCheckPort: news.healthCheckPort,
              HealthCheckProtocol: news.healthCheckProtocol,
              HealthCheckEnabled: news.healthCheckEnabled,
              HealthCheckIntervalSeconds: toSeconds(news.healthCheckInterval),
              HealthCheckTimeoutSeconds: toSeconds(news.healthCheckTimeout),
              HealthyThresholdCount: news.healthyThresholdCount,
              UnhealthyThresholdCount: news.unhealthyThresholdCount,
              Matcher: news.matcher,
              Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                Key,
                Value,
              })),
            });
            targetGroup = created.TargetGroups?.[0];
            if (!targetGroup?.TargetGroupArn) {
              return yield* Effect.die(new Error("createTargetGroup returned no target group"));
            }
          }

          const targetGroupArn = targetGroup.TargetGroupArn as TargetGroupArn;

          // Sync health check — diff observed against desired; only call
          // modifyTargetGroup when a health-check field actually changed.
          const observedHc = {
            HealthCheckPath: targetGroup.HealthCheckPath,
            HealthCheckPort: targetGroup.HealthCheckPort,
            HealthCheckProtocol: targetGroup.HealthCheckProtocol,
            HealthCheckEnabled: targetGroup.HealthCheckEnabled,
            HealthCheckIntervalSeconds: targetGroup.HealthCheckIntervalSeconds,
            HealthCheckTimeoutSeconds: targetGroup.HealthCheckTimeoutSeconds,
            HealthyThresholdCount: targetGroup.HealthyThresholdCount,
            UnhealthyThresholdCount: targetGroup.UnhealthyThresholdCount,
            Matcher: targetGroup.Matcher,
          };
          const desiredHc = {
            HealthCheckPath: news.healthCheckPath ?? observedHc.HealthCheckPath,
            HealthCheckPort: news.healthCheckPort ?? observedHc.HealthCheckPort,
            HealthCheckProtocol: news.healthCheckProtocol ?? observedHc.HealthCheckProtocol,
            HealthCheckEnabled: news.healthCheckEnabled ?? observedHc.HealthCheckEnabled,
            HealthCheckIntervalSeconds:
              toSeconds(news.healthCheckInterval) ?? observedHc.HealthCheckIntervalSeconds,
            HealthCheckTimeoutSeconds:
              toSeconds(news.healthCheckTimeout) ?? observedHc.HealthCheckTimeoutSeconds,
            HealthyThresholdCount: news.healthyThresholdCount ?? observedHc.HealthyThresholdCount,
            UnhealthyThresholdCount:
              news.unhealthyThresholdCount ?? observedHc.UnhealthyThresholdCount,
            Matcher: news.matcher ?? observedHc.Matcher,
          };
          if (!deepEqual(observedHc, desiredHc)) {
            yield* elbv2.modifyTargetGroup({
              TargetGroupArn: targetGroupArn,
              ...desiredHc,
            });
          }

          // Sync attributes — diff the observed values of the declared keys
          // against desired and apply only the delta.
          let attributes = yield* readAttributes(targetGroupArn, news.attributes);
          const attributeChanges = attributeDelta(news.attributes, attributes);
          if (attributeChanges.length > 0) {
            const modified = yield* elbv2.modifyTargetGroupAttributes({
              TargetGroupArn: targetGroupArn,
              Attributes: attributeChanges,
            });
            attributes = {
              ...attributes,
              ...observedAttributes(news.attributes, modified.Attributes),
            };
          }

          // Sync tags — diff observed cloud tags against desired.
          const tagDescriptions = yield* elbv2.describeTags({
            ResourceArns: [targetGroupArn],
          });
          const observedTags = Object.fromEntries(
            (tagDescriptions.TagDescriptions?.[0]?.Tags ?? [])
              .filter(
                (t): t is { Key: string; Value: string } =>
                  typeof t.Key === "string" && typeof t.Value === "string",
              )
              .map((t) => [t.Key, t.Value]),
          );
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* elbv2.addTags({
              ResourceArns: [targetGroupArn],
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* elbv2.removeTags({
              ResourceArns: [targetGroupArn],
              TagKeys: removed,
            });
          }

          yield* session.note(targetGroupArn);
          return {
            targetGroupArn,
            targetGroupName: targetGroup.TargetGroupName!,
            port: targetGroup.Port,
            protocol: targetGroup.Protocol,
            targetType: targetGroup.TargetType!,
            vpcId: targetGroup.VpcId,
            tags: desiredTags,
            attributes,
            healthCheck: observeHealthCheck(desiredHc, news),
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          // deleteTargetGroup is idempotent on a missing target group (returns
          // success). It only fails with ResourceInUseException while a
          // listener/rule still references it — retry briefly for the
          // eventual-consistency window after the dependents are removed.
          yield* elbv2
            .deleteTargetGroup({
              TargetGroupArn: output.targetGroupArn,
            })
            .pipe(
              Effect.retry({
                while: (e) => e._tag === "ResourceInUseException",
                schedule: Schedule.max([Schedule.spaced("3 seconds"), Schedule.recurs(8)]),
              }),
              Effect.catchTag("ResourceInUseException", () => Effect.void),
            );
        }),
      };
    }),
  );