sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EC2/ NetworkInterfaceAttachment.ts

import * as ec2 from "@distilled.cloud/aws/ec2";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import type { ScopedPlanStatusSession } from "alchemy/Report";
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 { Providers } from "../Providers.ts";
import type { InstanceId } from "./Instance.ts";
import type { NetworkInterfaceId } from "./NetworkInterface.ts";

export type NetworkInterfaceAttachmentId<ID extends string = string> = `eni-attach-${ID}`;

export interface NetworkInterfaceAttachmentProps {
  /**
   * The ID of the network interface to attach. Required. Changing it replaces
   * the attachment.
   */
  networkInterfaceId: NetworkInterfaceId;

  /**
   * The ID of the instance to attach the interface to. Required. Changing it
   * replaces the attachment.
   */
  instanceId: InstanceId;

  /**
   * The device index for the interface on the instance (0 is the primary
   * interface). Required. Changing it replaces the attachment.
   */
  deviceIndex: number;

  /**
   * Whether to force-detach the interface on delete if a normal detach does
   * not complete.
   * @default true
   */
  forceDetach?: boolean;
}

export interface NetworkInterfaceAttachment extends Resource<
  "AWS.EC2.NetworkInterfaceAttachment",
  NetworkInterfaceAttachmentProps,
  {
    /**
     * The ID of the attachment.
     */
    attachmentId: NetworkInterfaceAttachmentId;

    /**
     * The ID of the attached network interface.
     */
    networkInterfaceId: NetworkInterfaceId;

    /**
     * The ID of the instance the interface is attached to.
     */
    instanceId: InstanceId;

    /**
     * The device index of the interface on the instance.
     */
    deviceIndex: number;

    /**
     * The attachment status.
     */
    status: ec2.AttachmentStatus;
  },
  never,
  Providers
> {}
/**
 * Attaches an {@link NetworkInterface} (ENI) to an EC2 {@link Instance} at a
 * device index. The interface and instance must be in the same Availability
 * Zone. On delete the interface is detached (force-detached as a fallback)
 * before the resource is removed.
 *
 * This is an existence-style resource — its identity is the
 * `networkInterfaceId`/`instanceId`/`deviceIndex` triple. Changing any of them
 * replaces the attachment.
 *
 * ### Attaching a Network Interface
 * **Example:** Attach a Secondary ENI to an Instance
 * ```typescript
 * const attachment = yield* AWS.EC2.NetworkInterfaceAttachment("SecondaryEni", {
 *   networkInterfaceId: eni.networkInterfaceId,
 *   instanceId: instance.instanceId,
 *   deviceIndex: 1,
 * });
 * ```
 *
 * Device index 0 is the instance's primary interface, so secondary interfaces
 * use index 1 and up. The ENI's IPs and security groups now apply to the
 * instance on that interface.
 *
 * @resource
 */
export const NetworkInterfaceAttachment = Resource<NetworkInterfaceAttachment>(
  "AWS.EC2.NetworkInterfaceAttachment",
);

export const NetworkInterfaceAttachmentProvider = () =>
  Provider.effect(
    NetworkInterfaceAttachment,
    Effect.gen(function* () {
      return {
        stables: ["attachmentId", "networkInterfaceId", "instanceId", "deviceIndex"],

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          if (
            olds.networkInterfaceId !== news.networkInterfaceId ||
            olds.instanceId !== news.instanceId ||
            olds.deviceIndex !== news.deviceIndex
          ) {
            return { action: "replace" };
          }
        }),

        reconcile: Effect.fn(function* ({ news, output, session }) {
          // 1. OBSERVE — the attachment lives on the interface.
          const lookup = yield* ec2
            .describeNetworkInterfaces({
              NetworkInterfaceIds: [news.networkInterfaceId],
            })
            .pipe(
              Effect.catchTag("InvalidNetworkInterfaceID.NotFound", () =>
                Effect.succeed({ NetworkInterfaces: [] }),
              ),
            );
          const eni = lookup.NetworkInterfaces?.[0];
          const existing = eni?.Attachment;
          const attachedToInstance =
            existing?.InstanceId === news.instanceId &&
            existing?.Status !== "detaching" &&
            existing?.Status !== "detached";

          // 2. ENSURE — attach when not already attached to this instance.
          let attachmentId =
            attachedToInstance && existing?.AttachmentId
              ? (existing.AttachmentId as NetworkInterfaceAttachmentId)
              : output?.attachmentId;
          if (!attachedToInstance) {
            const result = yield* ec2.attachNetworkInterface({
              NetworkInterfaceId: news.networkInterfaceId,
              InstanceId: news.instanceId,
              DeviceIndex: news.deviceIndex,
              DryRun: false,
            });
            attachmentId = result.AttachmentId! as NetworkInterfaceAttachmentId;
            yield* session.note(
              `Network interface ${news.networkInterfaceId} attaching to ${news.instanceId}`,
            );
          }

          // 3. WAIT — until attached.
          const status = yield* waitForEniAttachmentState(
            news.networkInterfaceId,
            "attached",
            session,
          );

          return {
            attachmentId: attachmentId!,
            networkInterfaceId: news.networkInterfaceId,
            instanceId: news.instanceId,
            deviceIndex: news.deviceIndex,
            status,
          };
        }),

        // Attachments are embedded in interfaces; there is no standalone
        // enumeration keyed to this resource's identity.
        list: () => Effect.succeed([]),

        delete: Effect.fn(function* ({ output, olds, session }) {
          const { attachmentId, networkInterfaceId } = output;
          const force = olds?.forceDetach ?? true;
          yield* session.note(
            `Detaching network interface ${networkInterfaceId} (${attachmentId})`,
          );

          yield* ec2
            .detachNetworkInterface({
              AttachmentId: attachmentId,
              Force: force,
              DryRun: false,
            })
            .pipe(
              Effect.catchTag("InvalidAttachmentID.NotFound", () => Effect.void),
              // The interface can still be in-use momentarily — retry.
              Effect.retry({
                while: (e) => e._tag === "DependencyViolation",
                schedule: Schedule.max([Schedule.fixed(3000), Schedule.recurs(15)]),
              }),
            );

          // Wait for the interface to return to 'available'.
          yield* waitForEniDetached(networkInterfaceId, session);
          yield* session.note(`Network interface ${networkInterfaceId} detached`);
        }),
      };
    }),
  );

class EniAttachmentPending extends Data.TaggedError("EniAttachmentPending")<{
  networkInterfaceId: string;
  status: string;
}> {}

class EniStillAttached extends Data.TaggedError("EniStillAttached")<{
  networkInterfaceId: string;
  status: string;
}> {}

/**
 * Wait for the interface's attachment to reach a target status.
 */
const waitForEniAttachmentState = (
  networkInterfaceId: string,
  target: ec2.AttachmentStatus,
  session?: ScopedPlanStatusSession,
) =>
  Effect.gen(function* () {
    const result = yield* ec2.describeNetworkInterfaces({
      NetworkInterfaceIds: [networkInterfaceId],
    });
    const status = result.NetworkInterfaces?.[0]?.Attachment?.Status;
    if (status === target) {
      return status;
    }
    return yield* new EniAttachmentPending({
      networkInterfaceId,
      status: status ?? "unknown",
    });
  }).pipe(
    Effect.retry({
      while: (e) => e instanceof EniAttachmentPending,
      schedule: Schedule.max([
        Schedule.fixed(2000),
        Schedule.recurs(20), // max ~40s
      ]).pipe(
        Schedule.tap(({ attempt }) =>
          session
            ? session.note(`Waiting for interface attachment... (${(attempt + 1) * 2}s)`)
            : Effect.void,
        ),
      ),
    }),
  );

/**
 * Wait for the interface to return to `available` after a detach.
 */
const waitForEniDetached = (networkInterfaceId: string, session?: ScopedPlanStatusSession) =>
  Effect.gen(function* () {
    const result = yield* ec2
      .describeNetworkInterfaces({
        NetworkInterfaceIds: [networkInterfaceId],
      })
      .pipe(
        Effect.catchTag("InvalidNetworkInterfaceID.NotFound", () =>
          Effect.succeed({ NetworkInterfaces: [] }),
        ),
      );
    const eni = result.NetworkInterfaces?.[0];
    if (!eni || eni.Status === "available" || eni.Attachment === undefined) {
      return;
    }
    return yield* new EniStillAttached({
      networkInterfaceId,
      status: eni.Status ?? "unknown",
    });
  }).pipe(
    Effect.retry({
      while: (e) => e instanceof EniStillAttached,
      schedule: Schedule.max([
        Schedule.fixed(2000),
        Schedule.recurs(20), // max ~40s
      ]).pipe(
        Schedule.tap(({ attempt }) =>
          session
            ? session.note(`Waiting for interface to detach... (${(attempt + 1) * 2}s)`)
            : Effect.void,
        ),
      ),
    }),
  );