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

import * as efs from "@distilled.cloud/aws/efs";
import { Unowned } from "alchemy/AdoptPolicy";
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, 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 type { Providers } from "../Providers.ts";

export interface AccessPointPosixUser {
  /** POSIX user ID applied to all file-system requests through this access point. */
  uid: number;
  /** POSIX group ID applied to all file-system requests through this access point. */
  gid: number;
  /** Secondary POSIX group IDs. */
  secondaryGids?: number[];
}

export interface AccessPointRootDirectory {
  /**
   * Path on the file system to expose as the access point's root.
   * @default "/"
   */
  path?: string;
  /**
   * Ownership and permissions EFS applies when it creates the root directory
   * on first mount. Required if `path` does not already exist on the file
   * system (which is always the case for a freshly created file system).
   */
  creationInfo?: {
    /** POSIX user ID that owns the created root directory. */
    ownerUid: number;
    /** POSIX group ID that owns the created root directory. */
    ownerGid: number;
    /** Octal permissions of the created root directory, e.g. `"750"`. */
    permissions: string;
  };
}

export interface AccessPointProps {
  /**
   * ID of the EFS file system the access point exposes
   * (e.g. `fileSystem.fileSystemId`). Cannot be changed after creation
   * (replacement).
   */
  fileSystemId: string;
  /**
   * POSIX identity enforced for all requests through this access point.
   * Cannot be changed after creation (replacement).
   */
  posixUser?: AccessPointPosixUser;
  /**
   * Directory on the file system exposed as the access point's root,
   * optionally created on first mount with the given ownership/permissions.
   * Cannot be changed after creation (replacement).
   */
  rootDirectory?: AccessPointRootDirectory;
  /**
   * Tags to apply to the access point. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface AccessPoint extends Resource<
  "AWS.EFS.AccessPoint",
  AccessPointProps,
  {
    /** The ID of the access point (e.g. `fsap-0123456789abcdef0`). */
    accessPointId: string;
    /** The ARN of the access point. */
    accessPointArn: string;
    /** The ID of the EFS file system the access point belongs to. */
    fileSystemId: string;
  },
  {},
  Providers
> {}

/**
 * An Amazon EFS access point — an application-specific entry point into a
 * file system that enforces a POSIX identity and a root directory.
 *
 * Access points are how Lambda (and other serverless compute) mounts EFS:
 * pass `accessPoint.accessPointArn` to a Lambda Function's
 * `fileSystemConfigs`. The POSIX user and root directory are immutable —
 * changing them replaces the access point.
 * ### Creating Access Points
 * **Example:** Access point with a POSIX identity and auto-created root
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const files = yield* AWS.EFS.FileSystem("Files");
 * const accessPoint = yield* AWS.EFS.AccessPoint("FilesAccess", {
 *   fileSystemId: files.fileSystemId,
 *   posixUser: { uid: 1000, gid: 1000 },
 *   rootDirectory: {
 *     path: "/app",
 *     creationInfo: { ownerUid: 1000, ownerGid: 1000, permissions: "750" },
 *   },
 * });
 * ```
 *
 * ### Mounting into Lambda
 * **Example:** Mount at /mnt/files
 * ```typescript
 * const fn = yield* AWS.Lambda.Function("Api", {
 *   main: "./src/handler.ts",
 *   vpc: { subnetIds: [subnetId], securityGroupIds: [securityGroupId] },
 *   fileSystemConfigs: [
 *     { arn: accessPoint.accessPointArn, localMountPath: "/mnt/files" },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const AccessPoint = Resource<AccessPoint>("AWS.EFS.AccessPoint");

/**
 * Internal marker error used to drive the bounded wait for an access point
 * to reach the `available` lifecycle state.
 */
export class AccessPointNotAvailable extends Data.TaggedError("AccessPointNotAvailable")<{
  accessPointId: string;
  state: string;
}> {}

/**
 * Access points settle to `available` in seconds. Bounded poll (~60s),
 * explicitly typed so declaration emit never widens the provider layer
 * (see PATTERNS §7).
 */
const retryUntilAccessPointAvailable = <E extends { _tag: string }, R>(
  self: Effect.Effect<efs.AccessPointDescription, E, R>,
): Effect.Effect<efs.AccessPointDescription, E | AccessPointNotAvailable, R> =>
  Effect.retry(
    Effect.flatMap(self, (ap) =>
      ap.LifeCycleState === "available"
        ? Effect.succeed(ap)
        : Effect.fail(
            new AccessPointNotAvailable({
              accessPointId: ap.AccessPointId ?? "",
              state: ap.LifeCycleState ?? "unknown",
            }),
          ),
    ),
    {
      while: (e) => e._tag === "AccessPointNotAvailable",
      schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(30)]),
    },
  );

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

const toWirePosixUser = (posixUser: AccessPointPosixUser | undefined): efs.PosixUser | undefined =>
  posixUser === undefined
    ? undefined
    : {
        Uid: posixUser.uid,
        Gid: posixUser.gid,
        ...(posixUser.secondaryGids !== undefined
          ? { SecondaryGids: posixUser.secondaryGids }
          : {}),
      };

const toWireRootDirectory = (
  rootDirectory: AccessPointRootDirectory | undefined,
): efs.RootDirectory | undefined =>
  rootDirectory === undefined
    ? undefined
    : {
        ...(rootDirectory.path !== undefined ? { Path: rootDirectory.path } : {}),
        ...(rootDirectory.creationInfo !== undefined
          ? {
              CreationInfo: {
                OwnerUid: rootDirectory.creationInfo.ownerUid,
                OwnerGid: rootDirectory.creationInfo.ownerGid,
                Permissions: rootDirectory.creationInfo.permissions,
              },
            }
          : {}),
      };

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

      const findById = Effect.fn(function* (accessPointId: string) {
        return yield* efs.describeAccessPoints({ AccessPointId: accessPointId }).pipe(
          Effect.map((r) => r.AccessPoints?.[0]),
          Effect.catchTag("AccessPointNotFound", () => Effect.undefined),
        );
      });

      const findByToken = Effect.fn(function* (fileSystemId: string, token: string) {
        return yield* efs.describeAccessPoints({ FileSystemId: fileSystemId }).pipe(
          Effect.map((r) => r.AccessPoints?.find((ap) => ap.ClientToken === token)),
          Effect.catchTag("FileSystemNotFound", () => Effect.undefined),
        );
      });

      return AccessPoint.Provider.of({
        stables: ["accessPointId", "accessPointArn", "fileSystemId"],

        // Access points are only enumerable per file system, so walk every
        // file system in the account/region.
        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.describeAccessPoints({ FileSystemId: fs.FileSystemId }).pipe(
                  Effect.map((r) =>
                    (r.AccessPoints ?? [])
                      .filter(
                        (ap) => ap.AccessPointId !== undefined && ap.LifeCycleState !== "deleted",
                      )
                      .map((ap) => ({
                        accessPointId: ap.AccessPointId!,
                        accessPointArn: ap.AccessPointArn!,
                        fileSystemId: ap.FileSystemId!,
                      })),
                  ),
                  Effect.catchTag("FileSystemNotFound", () => Effect.succeed([])),
                ),
              { concurrency: 5 },
            );
            return perSystem.flat();
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const ap = output?.accessPointId
            ? yield* findById(output.accessPointId)
            : olds?.fileSystemId
              ? yield* findByToken(olds.fileSystemId, yield* createToken(id))
              : undefined;
          if (ap?.AccessPointId === undefined || ap.LifeCycleState === "deleted") {
            return undefined;
          }
          const attrs = {
            accessPointId: ap.AccessPointId,
            accessPointArn: ap.AccessPointArn!,
            fileSystemId: ap.FileSystemId!,
          };
          return (yield* hasAlchemyTags(id, efsTagsToRecord(ap.Tags))) ? attrs : Unowned(attrs);
        }),

        // posixUser, rootDirectory, and the file system are all immutable on
        // an access point — any change replaces it. Only tags update in
        // place.
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news) || olds === undefined) return undefined;
          if (
            news.fileSystemId !== olds.fileSystemId ||
            !deepEqual(news.posixUser, olds.posixUser) ||
            !deepEqual(news.rootDirectory, olds.rootDirectory)
          ) {
            return { action: "replace" } as const;
          }
          // undefined → default update path (tag sync)
        }),

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

          // 1. OBSERVE — output.accessPointId is only a cache; the client
          //    token is the deterministic identity within the file system.
          let ap = output?.accessPointId
            ? yield* findById(output.accessPointId)
            : yield* findByToken(news.fileSystemId, token);
          if (ap?.LifeCycleState === "deleted") {
            ap = undefined;
          }

          // 2. ENSURE — create if missing. CreateAccessPoint is idempotent
          //    on the client token; a concurrent identical create surfaces
          //    the typed AccessPointAlreadyExists which we resolve by
          //    describing the winner.
          if (ap === undefined) {
            ap = yield* efs
              .createAccessPoint({
                ClientToken: token,
                FileSystemId: news.fileSystemId,
                PosixUser: toWirePosixUser(news.posixUser),
                RootDirectory: toWireRootDirectory(news.rootDirectory),
                Tags: Object.entries({ ...news.tags, ...internalTags }).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(
                Effect.catchTag("AccessPointAlreadyExists", (e) =>
                  efs
                    .describeAccessPoints({ AccessPointId: e.AccessPointId })
                    .pipe(Effect.map((r) => r.AccessPoints![0])),
                ),
              );
          }

          const accessPointId = ap.AccessPointId!;

          ap = yield* retryUntilAccessPointAvailable(
            efs
              .describeAccessPoints({ AccessPointId: accessPointId })
              .pipe(Effect.map((r) => r.AccessPoints![0])),
          );

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

          yield* session.note(accessPointId);
          return {
            accessPointId,
            accessPointArn: ap.AccessPointArn!,
            fileSystemId: ap.FileSystemId!,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* efs
            .deleteAccessPoint({ AccessPointId: output.accessPointId })
            .pipe(Effect.catchTag("AccessPointNotFound", () => Effect.void));
        }),
      });
    }),
  );