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

import * as s3files from "@distilled.cloud/aws/s3files";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { PolicyDocument } from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";
import {
  retryWhileConflict,
  S3FilesNotConverged,
  toTagList,
  toTagRecord,
  untilSettled,
} from "./internal.ts";

export interface FileSystemProps {
  /**
   * ARN of the S3 general purpose bucket the file system exposes as POSIX
   * storage (`arn:aws:s3:::my-bucket`). The bucket must have versioning
   * enabled. Changing it replaces the file system.
   */
  bucket: string;
  /**
   * Optional key prefix that scopes the file system to a portion of the
   * bucket. Changing it replaces the file system.
   */
  prefix?: string;
  /**
   * ARN of the IAM role that grants the S3 Files service permission to read
   * and write the bucket on the file system's behalf. S3 Files runs on EFS
   * infrastructure, so the role must trust the
   * `elasticfilesystem.amazonaws.com` service principal. Changing it
   * replaces the file system.
   */
  roleArn: string;
  /**
   * KMS key used to encrypt file system data. Changing it replaces the file
   * system.
   * @default AWS-managed encryption
   */
  kmsKeyId?: string;
  /**
   * Acknowledge the service warning that applies when creating a file system
   * over a bucket that already contains data.
   * @default false
   */
  acceptBucketWarning?: boolean;
  /**
   * IAM resource policy controlling access to the file system. Omitting it
   * removes any existing policy.
   */
  policy?: PolicyDocument;
  /**
   * When true, deletion force-deletes the file system even if it still has
   * pending export data.
   * @default false
   */
  forceDestroy?: boolean;
  /**
   * Tags to apply to the file system. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface FileSystem extends Resource<
  "AWS.S3Files.FileSystem",
  FileSystemProps,
  {
    /**
     * Unique ID of the file system.
     */
    fileSystemId: string;
    /**
     * ARN of the file system.
     */
    fileSystemArn: string;
    /**
     * Name of the S3 general purpose bucket backing the file system.
     */
    bucket: string;
    /**
     * ARN of the IAM role the file system uses to access the backing bucket.
     */
    roleArn: string;
    /**
     * Current lifecycle status of the file system (e.g. `AVAILABLE`).
     */
    status: string;
    /**
     * Key prefix within the backing bucket that scopes the file system, if
     * one was configured.
     */
    prefix?: string;
  },
  never,
  Providers
> {}

/**
 * An Amazon S3 File System — POSIX-style file system access over an S3
 * general purpose bucket (mountable from EC2/ECS via mount targets, with
 * application-scoped access via {@link AccessPoint}s).
 *
 * S3 Files is a newer service; availability varies by region and account.
 *
 * ### Creating a File System
 * **Example:** Basic File System
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * // S3 Files requires versioning on the source bucket.
 * const bucket = yield* AWS.S3.Bucket("Data", { versioning: "Enabled" });
 * const role = yield* AWS.IAM.Role("FilesRole", {
 *   assumeRolePolicyDocument: {
 *     Version: "2012-10-17",
 *     Statement: [
 *       {
 *         Effect: "Allow",
 *         // S3 Files runs on EFS infrastructure and assumes the role as
 *         // the elasticfilesystem service principal.
 *         Principal: { Service: "elasticfilesystem.amazonaws.com" },
 *         Action: ["sts:AssumeRole"],
 *       },
 *     ],
 *   },
 *   inlinePolicies: {
 *     bucket: {
 *       Version: "2012-10-17",
 *       Statement: [
 *         {
 *           Effect: "Allow",
 *           Action: ["s3:ListBucket", "s3:ListBucketVersions"],
 *           Resource: [bucket.bucketArn],
 *         },
 *         {
 *           Effect: "Allow",
 *           Action: ["s3:GetObject*", "s3:PutObject*", "s3:DeleteObject*", "s3:List*", "s3:AbortMultipartUpload"],
 *           Resource: [AWS.Output.interpolate`${bucket.bucketArn}/*`],
 *         },
 *       ],
 *     },
 *   },
 * });
 *
 * const fs = yield* AWS.S3Files.FileSystem("Files", {
 *   bucket: bucket.bucketArn,
 *   roleArn: role.roleArn,
 * });
 * ```
 *
 * **Example:** Prefix-Scoped File System
 * ```typescript
 * const fs = yield* AWS.S3Files.FileSystem("Files", {
 *   bucket: bucket.bucketArn,
 *   prefix: "shared/",
 *   roleArn: role.roleArn,
 * });
 * ```
 *
 * @resource
 */
export const FileSystem = Resource<FileSystem>("AWS.S3Files.FileSystem");

const replacementKey = (props: Partial<FileSystemProps>) =>
  JSON.stringify({
    bucket: props.bucket,
    prefix: props.prefix,
    roleArn: props.roleArn,
    kmsKeyId: props.kmsKeyId,
  });

const normalizePolicy = (policy: string | undefined) => {
  if (policy === undefined) return undefined;
  try {
    return JSON.stringify(JSON.parse(policy));
  } catch {
    return policy;
  }
};

export const FileSystemProvider = () =>
  Provider.effect(
    FileSystem,
    Effect.gen(function* () {
      const observe = (fileSystemId: string) =>
        s3files
          .getFileSystem({ fileSystemId })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));

      const observedTags = (fileSystemId: string) =>
        s3files.listTagsForResource.items({ resourceId: fileSystemId }).pipe(
          Stream.runCollect,
          Effect.map((tags) => toTagRecord(Array.from(tags))),
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed({} as Record<string, string>),
          ),
        );

      const toAttributes = Effect.fn(function* (fs: s3files.GetFileSystemResponse) {
        if (
          fs.fileSystemId === undefined ||
          fs.fileSystemArn === undefined ||
          fs.bucket === undefined ||
          fs.roleArn === undefined ||
          fs.status === undefined
        ) {
          return yield* new S3FilesNotConverged({
            resource: fs.fileSystemId ?? "unknown file system",
            status: fs.status,
          });
        }
        return {
          fileSystemId: fs.fileSystemId,
          fileSystemArn: fs.fileSystemArn,
          bucket: fs.bucket,
          roleArn: fs.roleArn,
          status: fs.status,
          ...(fs.prefix !== undefined ? { prefix: fs.prefix } : {}),
        };
      });

      // State-loss / conflict fallback: find the file system carrying this
      // logical id's Alchemy tags (optionally narrowed to a bucket).
      const findByAlchemyTags = Effect.fn(function* (id: string, bucket: string | undefined) {
        const fileSystems = yield* s3files.listFileSystems
          .items(bucket !== undefined ? { bucket } : {})
          .pipe(
            Stream.runCollect,
            Effect.map((c) => Array.from(c)),
          );
        for (const fs of fileSystems) {
          const tags = yield* observedTags(fs.fileSystemId);
          if (yield* hasAlchemyTags(id, tags)) {
            return yield* observe(fs.fileSystemId);
          }
        }
        return undefined;
      });

      const syncTags = Effect.fn(function* (fileSystemId: string, desired: Record<string, string>) {
        const current = yield* observedTags(fileSystemId);
        const { upsert, removed } = diffTags(current, desired);
        if (upsert.length > 0) {
          yield* s3files.tagResource({
            resourceId: fileSystemId,
            tags: upsert.map((t) => ({ key: t.Key, value: t.Value })),
          });
        }
        if (removed.length > 0) {
          yield* s3files.untagResource({
            resourceId: fileSystemId,
            tagKeys: removed,
          });
        }
      });

      const syncPolicy = Effect.fn(function* (
        fileSystemId: string,
        desired: PolicyDocument | undefined,
      ) {
        const current = yield* s3files.getFileSystemPolicy({ fileSystemId }).pipe(
          Effect.map((r) => r.policy),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );
        const desiredJson = desired !== undefined ? JSON.stringify(desired) : undefined;
        if (desiredJson !== undefined) {
          if (normalizePolicy(current) !== normalizePolicy(desiredJson)) {
            yield* s3files.putFileSystemPolicy({
              fileSystemId,
              policy: desiredJson,
            });
          }
        } else if (current !== undefined) {
          yield* s3files
            .deleteFileSystemPolicy({ fileSystemId })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }
      });

      return FileSystem.Provider.of({
        stables: ["fileSystemId", "fileSystemArn", "bucket"],
        list: () =>
          Effect.gen(function* () {
            const fileSystems = yield* s3files.listFileSystems.items({}).pipe(
              Stream.runCollect,
              Effect.map((c) => Array.from(c)),
            );
            return fileSystems.map((fs) => ({
              fileSystemId: fs.fileSystemId,
              fileSystemArn: fs.fileSystemArn,
              bucket: fs.bucket,
              roleArn: fs.roleArn,
              status: fs.status,
            }));
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const found =
            output?.fileSystemId !== undefined
              ? yield* observe(output.fileSystemId)
              : yield* findByAlchemyTags(id, olds?.bucket);
          if (found === undefined) return undefined;
          const attrs = yield* toAttributes(found);
          const tags = toTagRecord(found.tags);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          // There is no UpdateFileSystem API — bucket, prefix, role, and
          // encryption are all fixed at create time. Only tags and the
          // resource policy are mutable in place.
          if (replacementKey(olds ?? {}) !== replacementKey(news ?? {})) {
            return { action: "replace" } as const;
          }
          // fall through: engine default update (tags + policy sync)
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const clientToken = yield* Effect.sync(() => crypto.randomUUID());
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — cloud state is authoritative; output only caches
          //    the server-assigned file system id.
          let live =
            output?.fileSystemId !== undefined
              ? yield* observe(output.fileSystemId)
              : yield* findByAlchemyTags(id, news.bucket);

          // 2. ENSURE — create when missing. A ConflictException means a
          //    file system already exists for this bucket/prefix (possibly a
          //    concurrent create) — re-find it by our tags and only fail if
          //    it is not ours.
          if (live === undefined) {
            const created = yield* s3files
              .createFileSystem({
                bucket: news.bucket,
                prefix: news.prefix,
                roleArn: news.roleArn,
                kmsKeyId: news.kmsKeyId,
                acceptBucketWarning: news.acceptBucketWarning,
                clientToken,
                tags: toTagList(desiredTags),
              })
              .pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
            live =
              created?.fileSystemId !== undefined
                ? yield* observe(created.fileSystemId)
                : yield* findByAlchemyTags(id, news.bucket);
          }
          if (live?.fileSystemId === undefined) {
            return yield* new S3FilesNotConverged({
              resource: `file system for bucket ${news.bucket}`,
              status: live?.status,
            });
          }
          const fileSystemId = live.fileSystemId;

          // Wait (bounded) for the file system to leave `creating`.
          const settled = yield* untilSettled(
            observe(fileSystemId),
            (fs) => fs === undefined || fs.status !== "creating",
          );
          if (settled === undefined || settled.status !== "available") {
            return yield* new S3FilesNotConverged({
              resource: fileSystemId,
              status: settled?.status,
            });
          }

          // 3. SYNC — tags against observed cloud tags; policy against the
          //    observed resource policy.
          yield* syncTags(fileSystemId, desiredTags);
          yield* syncPolicy(fileSystemId, news.policy);

          // 4. RETURN fresh attributes.
          yield* session.note(fileSystemId);
          return yield* toAttributes(settled);
        }),
        delete: Effect.fn(function* ({ olds, output }) {
          // Idempotent: initiate deletion unless it is already underway.
          const live = yield* observe(output.fileSystemId);
          if (live === undefined) return;
          if (live.status !== "deleting" && live.status !== "deleted") {
            yield* retryWhileConflict(
              s3files.deleteFileSystem({
                fileSystemId: output.fileSystemId,
                forceDelete: olds.forceDestroy,
              }),
            ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
          }
          // Wait until the file system is fully gone: the source bucket
          // rejects DeleteBucket with BucketHasS3FileSystemAttached while
          // the file system still exists, and the engine deletes the bucket
          // immediately after this resource.
          const remaining = yield* untilSettled(
            observe(output.fileSystemId),
            (fs) => fs === undefined,
          );
          if (remaining !== undefined) {
            return yield* new S3FilesNotConverged({
              resource: output.fileSystemId,
              status: remaining.status,
            });
          }
        }),
      });
    }),
  );