sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EFS/ MountTarget.ts

import * as efs from "@distilled.cloud/aws/efs";
import { isResolved } from "alchemy/Diff";
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 * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

export interface MountTargetProps {
  /**
   * ID of the EFS file system to expose through this mount target
   * (e.g. `fileSystem.fileSystemId`). Cannot be changed after creation
   * (replacement).
   */
  fileSystemId: string;
  /**
   * ID of the subnet to create the mount target in. Determines the VPC and
   * Availability Zone; one mount target is allowed per AZ. Cannot be changed
   * after creation (replacement).
   */
  subnetId: string;
  /**
   * Static private IPv4 address for the mount target within the subnet's
   * range. Cannot be changed after creation (replacement).
   * @default an address assigned by EFS
   */
  ipAddress?: string;
  /**
   * Security groups attached to the mount target's network interface (up to
   * five). NFS clients must be allowed to reach TCP port 2049 through these
   * groups. Updatable in place.
   * @default the VPC's default security group
   */
  securityGroups?: string[];
}

export interface MountTarget extends Resource<
  "AWS.EFS.MountTarget",
  MountTargetProps,
  {
    /** The ID of the mount target (e.g. `fsmt-0123456789abcdef0`). */
    mountTargetId: string;
    /** The ID of the EFS file system the mount target belongs to. */
    fileSystemId: string;
    /** The ID of the subnet the mount target was created in. */
    subnetId: string;
    /** The IPv4 address at which the file system is reachable in the subnet. */
    ipAddress: string | undefined;
    /** The ID of the network interface created for the mount target. */
    networkInterfaceId: string | undefined;
    /** The name of the Availability Zone the mount target resides in. */
    availabilityZoneName: string | undefined;
  },
  {},
  Providers
> {}

/**
 * An Amazon EFS mount target — the per-subnet network endpoint (an ENI
 * serving NFS on TCP 2049) that compute in a VPC uses to reach a file
 * system.
 *
 * Create one mount target per Availability Zone you run compute in. The
 * reconciler waits for the mount target to reach the `available` state
 * (typically 1–2 minutes), so downstream resources that depend on its
 * attributes deploy only once the endpoint is usable. Deletion likewise
 * waits until the mount target is fully gone, because its ENI must be
 * released before the subnet, security groups, or file system can be
 * deleted.
 * ### Creating Mount Targets
 * **Example:** Mount target in a subnet
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const files = yield* AWS.EFS.FileSystem("Files");
 * const target = yield* AWS.EFS.MountTarget("FilesTarget", {
 *   fileSystemId: files.fileSystemId,
 *   subnetId,
 * });
 * ```
 *
 * **Example:** Mount target with explicit security groups
 * ```typescript
 * const target = yield* AWS.EFS.MountTarget("FilesTarget", {
 *   fileSystemId: files.fileSystemId,
 *   subnetId,
 *   securityGroups: [nfsSecurityGroupId],
 * });
 * ```
 *
 * @resource
 */
export const MountTarget = Resource<MountTarget>("AWS.EFS.MountTarget");

/**
 * Internal marker error used to drive the bounded wait for a mount target to
 * reach the `available` lifecycle state.
 */
export class MountTargetNotAvailable extends Data.TaggedError("MountTargetNotAvailable")<{
  mountTargetId: string;
  state: string;
}> {}

/**
 * Internal marker error used to drive the bounded wait for a mount target to
 * disappear after deletion (its ENI releases asynchronously).
 */
export class MountTargetStillDeleting extends Data.TaggedError("MountTargetStillDeleting")<{
  mountTargetId: string;
  state: string;
}> {}

/**
 * Mount-target provisioning takes 1–3 minutes. Bounded poll (5s × 36 ≈
 * 180s), explicitly typed so declaration emit never widens the provider
 * layer (see PATTERNS §7).
 */
const retryUntilMountTargetAvailable = <E extends { _tag: string }, R>(
  self: Effect.Effect<efs.MountTargetDescription, E, R>,
): Effect.Effect<efs.MountTargetDescription, E | MountTargetNotAvailable, R> =>
  Effect.retry(
    Effect.flatMap(self, (mt) =>
      mt.LifeCycleState === "available"
        ? Effect.succeed(mt)
        : Effect.fail(
            new MountTargetNotAvailable({
              mountTargetId: mt.MountTargetId,
              state: mt.LifeCycleState,
            }),
          ),
    ),
    {
      while: (e) => e._tag === "MountTargetNotAvailable",
      schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]),
    },
  );

/**
 * Deletion releases the mount target's ENI asynchronously (1–3 minutes).
 * Bounded poll (5s × 36 ≈ 180s) until the mount target is observed gone,
 * explicitly typed (PATTERNS §7).
 */
const retryUntilMountTargetGone = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "MountTargetStillDeleting",
    schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]),
  });

/**
 * Security-group modifications race the mount target's own state machine;
 * `IncorrectMountTargetState` while it is still creating is transient.
 * Bounded retry (~60s), explicitly typed (PATTERNS §7).
 */
const retryWhileMountTargetSettling = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "IncorrectMountTargetState" || e._tag === "DependencyTimeout",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
  });

export const MountTargetProvider = () =>
  Provider.effect(
    MountTarget,
    Effect.gen(function* () {
      const findById = Effect.fn(function* (mountTargetId: string) {
        return yield* efs.describeMountTargets({ MountTargetId: mountTargetId }).pipe(
          Effect.map((r) => r.MountTargets?.[0]),
          Effect.catchTag("MountTargetNotFound", () => Effect.undefined),
        );
      });

      const findBySubnet = Effect.fn(function* (fileSystemId: string, subnetId: string) {
        return yield* efs.describeMountTargets({ FileSystemId: fileSystemId }).pipe(
          Effect.map((r) => r.MountTargets?.find((mt) => mt.SubnetId === subnetId)),
          Effect.catchTag("FileSystemNotFound", () => Effect.undefined),
        );
      });

      const toAttributes = (mt: efs.MountTargetDescription) => ({
        mountTargetId: mt.MountTargetId,
        fileSystemId: mt.FileSystemId,
        subnetId: mt.SubnetId,
        ipAddress: mt.IpAddress,
        networkInterfaceId: mt.NetworkInterfaceId,
        availabilityZoneName: mt.AvailabilityZoneName,
      });

      return MountTarget.Provider.of({
        stables: ["mountTargetId", "fileSystemId", "subnetId", "ipAddress", "availabilityZoneName"],

        // Mount targets are only enumerable per file system, so walk every
        // file system in the account/region. A file system can vanish between
        // the enumeration and the per-FS describe — drop it.
        list: () =>
          Effect.gen(function* () {
            const systems = yield* efs.describeFileSystems.items({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk)),
            );
            const perSystem = yield* Effect.forEach(
              systems,
              (fs) =>
                efs.describeMountTargets({ FileSystemId: fs.FileSystemId }).pipe(
                  Effect.map((r) =>
                    (r.MountTargets ?? [])
                      .filter((mt) => mt.LifeCycleState !== "deleted")
                      .map(toAttributes),
                  ),
                  Effect.catchTag("FileSystemNotFound", () => Effect.succeed([])),
                ),
              { concurrency: 5 },
            );
            return perSystem.flat();
          }),

        // Mount targets are untaggable, so there is no ownership marker to
        // check: identity is the (fileSystemId, subnetId) pair, matching the
        // one-mount-target-per-AZ constraint.
        read: Effect.fn(function* ({ olds, output }) {
          const mt = output?.mountTargetId
            ? yield* findById(output.mountTargetId)
            : olds?.fileSystemId && olds.subnetId
              ? yield* findBySubnet(olds.fileSystemId, olds.subnetId)
              : undefined;
          if (mt === undefined || mt.LifeCycleState === "deleted") {
            return undefined;
          }
          return toAttributes(mt);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news) || olds === undefined) return undefined;
          if (
            news.fileSystemId !== olds.fileSystemId ||
            news.subnetId !== olds.subnetId ||
            news.ipAddress !== olds.ipAddress
          ) {
            return { action: "replace" } as const;
          }
          // undefined → default update path (security-group sync)
        }),

        reconcile: Effect.fn(function* ({ news, output, session }) {
          // 1. OBSERVE — output.mountTargetId is only a cache; fall through
          //    to the (fileSystemId, subnetId) identity if it is stale.
          let mt = output?.mountTargetId ? yield* findById(output.mountTargetId) : undefined;
          if (mt === undefined || mt.LifeCycleState === "deleted") {
            mt = yield* findBySubnet(news.fileSystemId, news.subnetId);
          }
          if (mt?.LifeCycleState === "deleted") {
            mt = undefined;
          }

          // 2. ENSURE — create if missing. `MountTargetConflict` means a peer
          //    created it in the same subnet/AZ concurrently — re-observe.
          if (mt === undefined) {
            mt = yield* efs
              .createMountTarget({
                FileSystemId: news.fileSystemId,
                SubnetId: news.subnetId,
                IpAddress: news.ipAddress,
                SecurityGroups: news.securityGroups,
              })
              .pipe(
                Effect.catchTag("MountTargetConflict", () =>
                  findBySubnet(news.fileSystemId, news.subnetId).pipe(
                    Effect.flatMap((existing) =>
                      existing !== undefined
                        ? Effect.succeed(existing)
                        : efs.createMountTarget({
                            FileSystemId: news.fileSystemId,
                            SubnetId: news.subnetId,
                            IpAddress: news.ipAddress,
                            SecurityGroups: news.securityGroups,
                          }),
                    ),
                  ),
                ),
              );
          }

          const mountTargetId = mt.MountTargetId;

          // Wait for the network endpoint to become usable — dependents
          // (e.g. a Lambda with fileSystemConfigs) fail to create against a
          // mount target that is still `creating`.
          yield* session.note(`waiting for ${mountTargetId} to be available`);
          mt = yield* retryUntilMountTargetAvailable(
            efs
              .describeMountTargets({ MountTargetId: mountTargetId })
              .pipe(Effect.map((r) => r.MountTargets![0])),
          );

          // 3. SYNC security groups — diff the OBSERVED set against the
          //    desired one; only call the API on a real delta. When the prop
          //    is omitted the observed groups (VPC default) are left alone.
          if (news.securityGroups !== undefined) {
            const observed = yield* efs
              .describeMountTargetSecurityGroups({
                MountTargetId: mountTargetId,
              })
              .pipe(Effect.map((r) => [...r.SecurityGroups].sort()));
            const desired = [...news.securityGroups].sort();
            if (JSON.stringify(observed) !== JSON.stringify(desired)) {
              yield* retryWhileMountTargetSettling(
                efs.modifyMountTargetSecurityGroups({
                  MountTargetId: mountTargetId,
                  SecurityGroups: news.securityGroups,
                }),
              );
            }
          }

          yield* session.note(mountTargetId);
          return toAttributes(mt);
        }),

        // Deletion must observe the mount target actually GONE before
        // returning: its ENI is released asynchronously and the subnet,
        // security groups, and file system cannot be deleted until then.
        delete: Effect.fn(function* ({ output, session }) {
          yield* efs
            .deleteMountTarget({ MountTargetId: output.mountTargetId })
            .pipe(Effect.catchTag("MountTargetNotFound", () => Effect.void));

          yield* session.note(`waiting for ${output.mountTargetId} to be deleted`);
          yield* retryUntilMountTargetGone(
            efs.describeMountTargets({ MountTargetId: output.mountTargetId }).pipe(
              Effect.flatMap((r) => {
                const state = r.MountTargets?.[0]?.LifeCycleState;
                return state === undefined || state === "deleted"
                  ? Effect.void
                  : Effect.fail(
                      new MountTargetStillDeleting({
                        mountTargetId: output.mountTargetId,
                        state,
                      }),
                    );
              }),
              Effect.catchTag("MountTargetNotFound", () => Effect.void),
            ),
          );
        }),
      });
    }),
  );