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

import * as efs from "@distilled.cloud/aws/efs";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
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 { AWSEnvironment } from "../Environment.ts";
import {
  normalizePolicyDocument,
  type PolicyDocument,
  stringifyPolicyDocument,
} from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";

/**
 * A single EFS lifecycle-management rule. EFS requires each rule to carry
 * exactly one transition setting, so a full configuration is expressed as an
 * array of single-setting policies.
 */
export interface FileSystemLifecyclePolicy {
  /**
   * Transition files to the Infrequent Access (IA) storage class after the
   * given period without access, e.g. `"AFTER_30_DAYS"`.
   */
  transitionToIA?: efs.TransitionToIARules;
  /**
   * Transition files back to primary storage on first access, e.g.
   * `"AFTER_1_ACCESS"`.
   */
  transitionToPrimaryStorageClass?: efs.TransitionToPrimaryStorageClassRules;
  /**
   * Transition files to the Archive storage class after the given period
   * without access, e.g. `"AFTER_90_DAYS"`.
   */
  transitionToArchive?: efs.TransitionToArchiveRules;
}

export interface FileSystemProps {
  /**
   * Performance mode of the file system. `generalPurpose` is recommended for
   * all workloads; `maxIO` is a previous-generation mode for highly
   * parallelized workloads. Cannot be changed after creation (replacement).
   * `maxIO` is not supported with `elastic` throughput or One Zone file
   * systems.
   * @default "generalPurpose"
   */
  performanceMode?: "generalPurpose" | "maxIO";
  /**
   * Whether the file system is encrypted at rest. Cannot be changed after
   * creation (replacement).
   * @default true
   */
  encrypted?: boolean;
  /**
   * The KMS key used to encrypt the file system. Only meaningful when
   * `encrypted` is `true`. Cannot be changed after creation (replacement).
   * @default the AWS-managed `/aws/elasticfilesystem` key
   */
  kmsKeyId?: string;
  /**
   * Throughput mode of the file system. `elastic` scales automatically and is
   * recommended for spiky workloads; `provisioned` requires
   * `provisionedThroughputInMibps`. Updatable in place.
   * @default "bursting"
   */
  throughputMode?: "bursting" | "provisioned" | "elastic";
  /**
   * Provisioned throughput in MiB/s. Required when `throughputMode` is
   * `provisioned`.
   */
  provisionedThroughputInMibps?: number;
  /**
   * Create a One Zone file system in this Availability Zone (e.g.
   * `us-west-2a`). Cannot be changed after creation (replacement).
   * @default regional (multi-AZ) file system
   */
  availabilityZoneName?: string;
  /**
   * Lifecycle management rules that transition files between storage
   * classes. Omit (or pass an empty array) to disable lifecycle management.
   */
  lifecyclePolicies?: FileSystemLifecyclePolicy[];
  /**
   * Whether AWS Backup automatic backups are enabled for the file system.
   * Updatable in place. When omitted, the AWS default is left alone
   * (disabled for regional file systems, enabled for One Zone file
   * systems).
   * @default AWS default (regional: disabled; One Zone: enabled)
   */
  backup?: boolean;
  /**
   * Replication overwrite protection. `ENABLED` (the AWS default) makes the
   * file system writable and blocks it from being used as a replication
   * destination; `DISABLED` makes it read-only so an EFS replication
   * configuration can overwrite it. Updatable in place. When omitted, the
   * current protection setting is left alone.
   * @default AWS default ("ENABLED")
   */
  replicationOverwriteProtection?: "ENABLED" | "DISABLED";
  /**
   * The file system policy — an IAM resource-based policy controlling client
   * access to the file system (e.g. enforcing in-transit encryption or
   * restricting mounts to access points). Either a structured
   * {@link PolicyDocument} or a raw JSON string. Omitting the property
   * removes any explicit policy, reverting to the default EFS policy.
   */
  policy?: PolicyDocument | string;
  /**
   * Tags to apply to the file system. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface FileSystem extends Resource<
  "AWS.EFS.FileSystem",
  FileSystemProps,
  {
    /** The ID of the file system (e.g. `fs-0123456789abcdef0`). */
    fileSystemId: string;
    /** The ARN of the file system. */
    fileSystemArn: string;
  },
  {},
  Providers
> {}

/**
 * An Amazon EFS file system — serverless, elastic, shared POSIX storage.
 *
 * The file system is created encrypted by default with a deterministic
 * creation token derived from the app, stage, and logical ID, so retried
 * creates are idempotent. Mount it into compute with
 * {@link MountTarget} (per-subnet network endpoints) and
 * {@link AccessPoint} (application-specific POSIX entry points — required
 * for Lambda mounts).
 * ### Creating File Systems
 * **Example:** Default file system (encrypted, general purpose)
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const files = yield* AWS.EFS.FileSystem("Files");
 * ```
 *
 * **Example:** Elastic throughput
 * ```typescript
 * const files = yield* AWS.EFS.FileSystem("Files", {
 *   throughputMode: "elastic",
 * });
 * ```
 *
 * ### Lifecycle Management
 * **Example:** Tier cold files to Infrequent Access
 * ```typescript
 * const files = yield* AWS.EFS.FileSystem("Files", {
 *   lifecyclePolicies: [
 *     { transitionToIA: "AFTER_30_DAYS" },
 *     { transitionToPrimaryStorageClass: "AFTER_1_ACCESS" },
 *   ],
 * });
 * ```
 *
 * ### Backup and Protection
 * **Example:** Enable AWS Backup automatic backups
 * ```typescript
 * const files = yield* AWS.EFS.FileSystem("Files", {
 *   backup: true,
 * });
 * ```
 *
 * **Example:** Allow the file system to be a replication destination
 * ```typescript
 * const files = yield* AWS.EFS.FileSystem("Files", {
 *   replicationOverwriteProtection: "DISABLED",
 * });
 * ```
 *
 * ### File System Policy
 * **Example:** Enforce in-transit encryption with a typed PolicyDocument
 * ```typescript
 * const files = yield* AWS.EFS.FileSystem("Files", {
 *   policy: {
 *     Version: "2012-10-17",
 *     Statement: [
 *       {
 *         Sid: "DenyUnencryptedTransport",
 *         Effect: "Deny",
 *         Principal: { AWS: "*" },
 *         Action: ["elasticfilesystem:ClientMount"],
 *         Condition: { Bool: { "aws:SecureTransport": "false" } },
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * ### Mounting into Lambda
 * Lambda mounts EFS through an access point; the function must be attached
 * to a VPC that can reach a mount target.
 *
 * **Example:** File system + mount target + access point + Lambda
 * ```typescript
 * const files = yield* AWS.EFS.FileSystem("Files");
 * const target = yield* AWS.EFS.MountTarget("FilesTarget", {
 *   fileSystemId: files.fileSystemId,
 *   subnetId,
 * });
 * const accessPoint = yield* AWS.EFS.AccessPoint("FilesAccess", {
 *   fileSystemId: files.fileSystemId,
 *   posixUser: { uid: 1000, gid: 1000 },
 *   rootDirectory: {
 *     path: "/lambda",
 *     creationInfo: { ownerUid: 1000, ownerGid: 1000, permissions: "750" },
 *   },
 * });
 * const fn = yield* AWS.Lambda.Function("Api", {
 *   main: "./src/handler.ts",
 *   vpc: { subnetIds: [subnetId], securityGroupIds: [securityGroupId] },
 *   fileSystemConfigs: [
 *     // pass the AccessPoint resource itself (or its ARN)
 *     { accessPoint, localMountPath: "/mnt/files" },
 *   ],
 *   // depend on the mount target so the function is created only after
 *   // the network endpoint is available
 *   env: { EFS_MOUNT_TARGET: target.mountTargetId },
 * });
 * ```
 *
 * **Example:** Host-agnostic mount binding (Lambda or ECS)
 * `EFS.mount` wires the mount config + least-privilege IAM through the
 * host's binding channel — the same code works inside a Lambda Function or
 * an ECS Task body (provide `AWS.EFS.MountLive` on the host Effect).
 * ```typescript
 * export default class Api extends AWS.Lambda.Function<Api>()(
 *   "Api",
 *   { main: import.meta.url, vpc: { subnetIds, securityGroupIds } },
 *   Effect.gen(function* () {
 *     const files = yield* AWS.EFS.mount(accessPoint, { path: "/mnt/files" });
 *     return Effect.fn(function* (event: unknown) {
 *       // read/write under files.path at runtime
 *       return { mountedAt: files.path };
 *     });
 *   }).pipe(Effect.provide(AWS.EFS.MountLive)),
 * ) {}
 * ```
 *
 * @resource
 */
export const FileSystem = Resource<FileSystem>("AWS.EFS.FileSystem");

const isMutableEfsTagKey = (key: string): boolean => !key.toLowerCase().startsWith("aws:");

const mutableEfsTags = (tags: Record<string, string>): Record<string, string> =>
  Object.fromEntries(Object.entries(tags).filter(([key]) => isMutableEfsTagKey(key)));

const efsTagsToRecord = (tags: readonly efs.Tag[] | undefined): Record<string, string> =>
  Object.fromEntries(
    (tags ?? []).filter((tag) => isMutableEfsTagKey(tag.Key)).map((tag) => [tag.Key, tag.Value]),
  );

/**
 * A file system briefly reports `creating`/`updating` before settling in
 * `available`. Bounded poll (~60s), explicitly typed so declaration emit
 * never widens the provider layer (see PATTERNS §7).
 */
const retryUntilFileSystemAvailable = <E extends { _tag: string }, R>(
  self: Effect.Effect<efs.FileSystemDescription, E, R>,
): Effect.Effect<efs.FileSystemDescription, E | FileSystemNotAvailable, R> =>
  Effect.retry(
    Effect.flatMap(self, (fs) =>
      fs.LifeCycleState === "available"
        ? Effect.succeed(fs)
        : Effect.fail(
            new FileSystemNotAvailable({
              fileSystemId: fs.FileSystemId,
              state: fs.LifeCycleState,
            }),
          ),
    ),
    {
      while: (e) => e._tag === "FileSystemNotAvailable",
      schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(30)]),
    },
  );

/**
 * Deleting a file system whose mount targets are still tearing down (their
 * ENIs release asynchronously) transiently fails with `FileSystemInUse`.
 * Bounded retry (~60s), explicitly typed (PATTERNS §7).
 */
const retryWhileFileSystemInUse = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "FileSystemInUse",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
  });

/**
 * Throughput updates are rejected with `IncorrectFileSystemLifeCycleState`
 * while a previous modification is still applying. Bounded retry (~60s),
 * explicitly typed (PATTERNS §7).
 */
const retryWhileFileSystemUpdating = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "IncorrectFileSystemLifeCycleState",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
  });

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

const toWireLifecyclePolicies = (
  policies: FileSystemLifecyclePolicy[] | undefined,
): efs.LifecyclePolicy[] =>
  (policies ?? []).map((p) => ({
    ...(p.transitionToIA !== undefined ? { TransitionToIA: p.transitionToIA } : {}),
    ...(p.transitionToPrimaryStorageClass !== undefined
      ? { TransitionToPrimaryStorageClass: p.transitionToPrimaryStorageClass }
      : {}),
    ...(p.transitionToArchive !== undefined ? { TransitionToArchive: p.transitionToArchive } : {}),
  }));

const canonicalPolicies = (policies: readonly efs.LifecyclePolicy[]): string =>
  JSON.stringify(
    policies
      .map((p) => ({
        TransitionToIA: p.TransitionToIA ?? null,
        TransitionToPrimaryStorageClass: p.TransitionToPrimaryStorageClass ?? null,
        TransitionToArchive: p.TransitionToArchive ?? null,
      }))
      .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
  );

export const FileSystemProvider = () =>
  Provider.effect(
    FileSystem,
    Effect.gen(function* () {
      const createToken = Effect.fn(function* (id: string) {
        return yield* createPhysicalName({ id, maxLength: 64 });
      });

      const fileSystemArnOf = Effect.fn(function* (fileSystemId: string) {
        const { accountId, region } = yield* AWSEnvironment.current;
        return `arn:aws:elasticfilesystem:${region}:${accountId}:file-system/${fileSystemId}`;
      });

      const findByToken = Effect.fn(function* (token: string) {
        return yield* efs.describeFileSystems({ CreationToken: token }).pipe(
          Effect.map((r) => r.FileSystems?.[0]),
          Effect.catchTag("FileSystemNotFound", () => Effect.undefined),
        );
      });

      const findById = Effect.fn(function* (fileSystemId: string) {
        return yield* efs.describeFileSystems({ FileSystemId: fileSystemId }).pipe(
          Effect.map((r) => r.FileSystems?.[0]),
          Effect.catchTag("FileSystemNotFound", () => Effect.undefined),
        );
      });

      return FileSystem.Provider.of({
        stables: ["fileSystemId", "fileSystemArn"],

        list: () =>
          Effect.gen(function* () {
            const systems = yield* efs.describeFileSystems.items({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk)),
            );
            return yield* Effect.forEach(systems, (fs) =>
              Effect.gen(function* () {
                return {
                  fileSystemId: fs.FileSystemId,
                  fileSystemArn: fs.FileSystemArn ?? (yield* fileSystemArnOf(fs.FileSystemId)),
                };
              }),
            );
          }),

        read: Effect.fn(function* ({ id, output }) {
          const fs = output?.fileSystemId
            ? yield* findById(output.fileSystemId)
            : yield* findByToken(yield* createToken(id));
          if (fs === undefined || fs.LifeCycleState === "deleted") {
            return undefined;
          }
          const attrs = {
            fileSystemId: fs.FileSystemId,
            fileSystemArn: fs.FileSystemArn ?? (yield* fileSystemArnOf(fs.FileSystemId)),
          };
          return (yield* hasAlchemyTags(id, efsTagsToRecord(fs.Tags))) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ news = {}, olds = {} }) {
          if (!isResolved(news)) return undefined;
          const replaced =
            (news.performanceMode ?? "generalPurpose") !==
              (olds.performanceMode ?? "generalPurpose") ||
            (news.encrypted ?? true) !== (olds.encrypted ?? true) ||
            news.kmsKeyId !== olds.kmsKeyId ||
            news.availabilityZoneName !== olds.availabilityZoneName;
          if (replaced) {
            return { action: "replace" } as const;
          }
          // undefined → default update path (throughput/lifecycle/tags sync)
        }),

        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
          const token = yield* createToken(id);
          const internalTags = yield* createInternalTags(id);

          // 1. OBSERVE — the creation token is the deterministic identity;
          //    output.fileSystemId is only a cache and may be stale.
          let fs = output?.fileSystemId
            ? yield* findById(output.fileSystemId)
            : yield* findByToken(token);
          if (fs?.LifeCycleState === "deleted") {
            fs = undefined;
          }

          // 2. ENSURE — create if missing. CreateFileSystem is idempotent on
          //    the creation token; a concurrent create surfaces the typed
          //    FileSystemAlreadyExists which we resolve by re-observing.
          if (fs === undefined) {
            fs = yield* efs
              .createFileSystem({
                CreationToken: token,
                PerformanceMode: news.performanceMode,
                Encrypted: news.encrypted ?? true,
                KmsKeyId: news.kmsKeyId,
                Backup: news.backup,
                ThroughputMode: news.throughputMode,
                ProvisionedThroughputInMibps: news.provisionedThroughputInMibps,
                AvailabilityZoneName: news.availabilityZoneName,
                Tags: Object.entries(mutableEfsTags({ ...news.tags, ...internalTags })).map(
                  ([Key, Value]) => ({ Key, Value }),
                ),
              })
              .pipe(
                Effect.catchTag("FileSystemAlreadyExists", (e) =>
                  efs
                    .describeFileSystems({ FileSystemId: e.FileSystemId })
                    .pipe(Effect.map((r) => r.FileSystems![0])),
                ),
              );
          }

          const fileSystemId = fs.FileSystemId;

          // File-system mutations (throughput, lifecycle) require the
          // `available` state; creation settles in seconds.
          fs = yield* retryUntilFileSystemAvailable(
            efs
              .describeFileSystems({ FileSystemId: fileSystemId })
              .pipe(Effect.map((r) => r.FileSystems![0])),
          );

          // 3a. SYNC throughput — observed vs desired; only call the API on a
          //     real delta.
          if (news.throughputMode !== undefined) {
            const modeChanged = fs.ThroughputMode !== news.throughputMode;
            const provisionedChanged =
              news.throughputMode === "provisioned" &&
              fs.ProvisionedThroughputInMibps !== news.provisionedThroughputInMibps;
            if (modeChanged || provisionedChanged) {
              yield* retryWhileFileSystemUpdating(
                efs.updateFileSystem({
                  FileSystemId: fileSystemId,
                  ThroughputMode: news.throughputMode,
                  ProvisionedThroughputInMibps:
                    news.throughputMode === "provisioned"
                      ? news.provisionedThroughputInMibps
                      : undefined,
                }),
              );
            }
          }

          // 3b. SYNC lifecycle policies — a PUT with the full desired list;
          //     an empty list clears lifecycle management.
          const observedPolicies = yield* efs
            .describeLifecycleConfiguration({ FileSystemId: fileSystemId })
            .pipe(Effect.map((r) => r.LifecyclePolicies ?? []));
          const desiredPolicies = toWireLifecyclePolicies(news.lifecyclePolicies);
          if (canonicalPolicies(observedPolicies) !== canonicalPolicies(desiredPolicies)) {
            yield* retryWhileFileSystemUpdating(
              efs.putLifecycleConfiguration({
                FileSystemId: fileSystemId,
                LifecyclePolicies: desiredPolicies,
              }),
            );
          }

          // 3c. SYNC backup policy — observed vs desired; only call the API
          //     on a real delta. An in-flight transition (ENABLING/
          //     DISABLING) counts as its target state. When the prop is
          //     omitted the AWS default is left alone.
          if (news.backup !== undefined) {
            const observedBackupStatus = yield* efs
              .describeBackupPolicy({ FileSystemId: fileSystemId })
              .pipe(
                Effect.map((r) => r.BackupPolicy?.Status),
                Effect.catchTag("PolicyNotFound", () => Effect.undefined),
              );
            const observedBackup =
              observedBackupStatus === "ENABLED" || observedBackupStatus === "ENABLING";
            if (observedBackup !== news.backup) {
              yield* retryWhileFileSystemUpdating(
                efs.putBackupPolicy({
                  FileSystemId: fileSystemId,
                  BackupPolicy: {
                    Status: news.backup ? "ENABLED" : "DISABLED",
                  },
                }),
              );
            }
          }

          // 3d. SYNC replication overwrite protection — observed vs desired
          //     from the file system description. When the prop is omitted
          //     the current protection setting is left alone.
          if (news.replicationOverwriteProtection !== undefined) {
            const observedProtection =
              fs.FileSystemProtection?.ReplicationOverwriteProtection ?? "ENABLED";
            if (observedProtection !== news.replicationOverwriteProtection) {
              yield* retryWhileFileSystemUpdating(
                efs.updateFileSystemProtection({
                  FileSystemId: fileSystemId,
                  ReplicationOverwriteProtection: news.replicationOverwriteProtection,
                }),
              );
            }
          }

          // 3e. SYNC file system policy — compare the observed policy with
          //     the desired one after canonicalization (sorted keys, no
          //     whitespace) so a re-deploy of an equivalent document is a
          //     no-op API-wise.
          const observedPolicy = yield* efs
            .describeFileSystemPolicy({ FileSystemId: fileSystemId })
            .pipe(
              Effect.map((r) => r.Policy),
              Effect.catchTag("PolicyNotFound", () => Effect.undefined),
            );
          const desiredPolicy =
            news.policy === undefined
              ? undefined
              : typeof news.policy === "string"
                ? news.policy
                : stringifyPolicyDocument(news.policy);
          if (desiredPolicy === undefined) {
            if (observedPolicy !== undefined) {
              yield* retryWhileFileSystemUpdating(
                efs.deleteFileSystemPolicy({ FileSystemId: fileSystemId }),
              );
            }
          } else if (
            observedPolicy === undefined ||
            normalizePolicyDocument(observedPolicy) !== normalizePolicyDocument(desiredPolicy)
          ) {
            yield* retryWhileFileSystemUpdating(
              efs.putFileSystemPolicy({
                FileSystemId: fileSystemId,
                Policy: desiredPolicy,
              }),
            );
          }

          // 3f. SYNC tags — diff against OBSERVED cloud tags so adoption
          //     converges.
          const observedTags = efsTagsToRecord(fs.Tags);
          const desiredTags = mutableEfsTags({
            ...news.tags,
            ...internalTags,
          });
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* efs.tagResource({
              ResourceId: fileSystemId,
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* efs.untagResource({
              ResourceId: fileSystemId,
              TagKeys: removed,
            });
          }

          yield* session.note(fileSystemId);
          return {
            fileSystemId,
            fileSystemArn: fs.FileSystemArn ?? (yield* fileSystemArnOf(fileSystemId)),
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* retryWhileFileSystemInUse(
            efs.deleteFileSystem({ FileSystemId: output.fileSystemId }),
          ).pipe(Effect.catchTag("FileSystemNotFound", () => Effect.void));
        }),
      });
    }),
  );