sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Lambda/ LayerVersion.ts

import type * as lambda from "@distilled.cloud/aws/lambda";
import * as Lambda from "@distilled.cloud/aws/lambda";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { sha256, sha256Object } from "alchemy/Util/sha256";
import { zipFiles, type ZipFile } from "alchemy/Util/zip";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Path from "effect/Path";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

/**
 * Reference to an S3 bucket: a raw bucket name or anything exposing a
 * `bucketName` attribute (e.g. an `AWS.S3.Bucket` resource).
 */
export type BucketRef = string | { bucketName: string };

/** Resolve a {@link BucketRef} to its bucket name. */
const bucketNameOf = (bucket: BucketRef): string =>
  typeof bucket === "string" ? bucket : bucket.bucketName;

/**
 * Layer content stored in S3. Use this instead of {@link LayerVersionProps.path}
 * for archives larger than the 50 MB direct-upload limit.
 */
export interface LayerVersionS3Content {
  /**
   * S3 bucket holding the layer archive — an `AWS.S3.Bucket` resource or a
   * raw bucket name.
   */
  bucket: BucketRef;
  /** Key of the layer archive object. */
  key: string;
  /** Version id of the object, for versioned buckets. */
  objectVersion?: string;
}

export interface LayerVersionProps {
  /**
   * Name of the layer. If omitted, a unique name is generated.
   */
  layerName?: string;
  /**
   * Local path to the layer content — either a directory whose contents are
   * packaged into a zip archive, or an existing `.zip` file uploaded as-is.
   *
   * Layer archives are extracted into `/opt` at runtime, so the directory's
   * layout must match the runtime's convention (e.g. `nodejs/node_modules`
   * for Node.js dependencies, `bin/` for executables). File modes are
   * preserved, so executables keep their `+x` bit.
   *
   * Exactly one of `path` or {@link s3} is required.
   */
  path?: string;
  /**
   * Layer content already uploaded to S3. Required for archives above the
   * 50 MB direct-upload limit.
   *
   * Exactly one of {@link path} or `s3` is required.
   */
  s3?: LayerVersionS3Content;
  /**
   * Description of this version of the layer.
   */
  description?: string;
  /**
   * Runtimes the layer is compatible with. Used to filter the layer in the
   * console; Lambda does not enforce it.
   */
  compatibleRuntimes?: lambda.Runtime[];
  /**
   * Instruction set architectures the layer is compatible with.
   */
  compatibleArchitectures?: lambda.Architecture[];
  /**
   * The layer's software license — an SPDX identifier, a URL, or the full
   * license text.
   */
  licenseInfo?: string;
}

export interface LayerVersion extends Resource<
  "AWS.Lambda.LayerVersion",
  LayerVersionProps,
  {
    /**
     * Name of the layer.
     */
    layerName: string;
    /**
     * ARN of the layer (without a version suffix).
     */
    layerArn: string;
    /**
     * ARN of this specific layer version. This is what
     * {@link FunctionProps.layers} takes.
     */
    layerVersionArn: string;
    /**
     * Version number assigned by Lambda.
     */
    version: number;
    /**
     * Hash of the packaged content and publish configuration. Any change to
     * it publishes a new version, since layer versions are immutable.
     */
    sourceHash: string;
    /**
     * Base64-encoded SHA-256 of the layer archive, as reported by Lambda.
     */
    codeSha256?: string;
    /**
     * Size of the layer archive in bytes.
     */
    codeSize?: number;
    /**
     * Date the version was created, in ISO-8601 format.
     */
    createdDate?: string;
    /**
     * Description of the version.
     */
    description?: string;
    /**
     * Runtimes the layer is compatible with.
     */
    compatibleRuntimes?: lambda.Runtime[];
    /**
     * Architectures the layer is compatible with.
     */
    compatibleArchitectures?: lambda.Architecture[];
    /**
     * The layer's software license.
     */
    licenseInfo?: string;
  },
  never,
  Providers
> {}

/**
 * A version of a Lambda layer — a zip archive of libraries, a custom runtime,
 * or other dependencies that Lambda extracts into `/opt` alongside your
 * function code.
 *
 * Layer versions are immutable, so changing the content or any publish
 * setting publishes a new version under the same layer and retires the one
 * it supersedes. `layerVersionArn` and `version` therefore change on update;
 * `layerName` and `layerArn` stay put.
 *
 * ### Publishing a Layer
 * **Example:** Package a Local Directory
 * ```typescript
 * // ./layers/deps contains nodejs/node_modules/...
 * const deps = yield* LayerVersion("Deps", {
 *   path: "./layers/deps",
 *   compatibleRuntimes: ["nodejs22.x"],
 * });
 * ```
 *
 * **Example:** Publish an Existing Archive
 * ```typescript
 * const layer = yield* LayerVersion("Ffmpeg", {
 *   path: "./dist/ffmpeg-layer.zip",
 *   description: "static ffmpeg build",
 *   compatibleArchitectures: ["arm64"],
 * });
 * ```
 *
 * **Example:** Publish From S3
 * ```typescript
 * const layer = yield* LayerVersion("BigLayer", {
 *   s3: {
 *     bucket,
 *     key: "layers/big-layer.zip",
 *   },
 * });
 * ```
 *
 * ### Attaching to a Function
 * **Example:** Use a Layer in a Function
 * ```typescript
 * const fn = yield* Function("Handler", {
 *   main: import.meta.resolve("./handler.ts"),
 *   layers: [deps],
 * });
 * ```
 *
 * @resource
 */
export const LayerVersion = Resource<LayerVersion>("AWS.Lambda.LayerVersion");

/**
 * Lambda rejects a `PublishLayerVersion` request whose inline archive exceeds
 * 50 MB — larger archives must go through S3.
 */
const MAX_INLINE_ARCHIVE_SIZE = 50 * 1024 * 1024;

export const LayerVersionProvider = () =>
  Provider.effect(
    LayerVersion,
    Effect.gen(function* () {
      const createLayerName = (id: string, layerName?: string) =>
        layerName
          ? Effect.succeed(layerName)
          : createPhysicalName({
              id,
              // Layer names are limited to 140 characters.
              maxLength: 140,
              delimiter: "-",
            });

      /**
       * Read `directory` recursively into deterministic zip entries, keeping
       * each file's unix mode so executables stay executable under `/opt`.
       */
      const readDirectoryEntries = Effect.fn(function* (directory: string) {
        const fs = yield* FileSystem.FileSystem;
        const path = yield* Path.Path;
        const names = yield* fs.readDirectory(directory, { recursive: true });
        const entries = yield* Effect.forEach(
          names,
          Effect.fn(function* (name) {
            const file = path.join(directory, name);
            const info = yield* fs.stat(file);
            if (info.type !== "File") return [];
            return [
              {
                // Zip archives always use forward slashes.
                path: name.replaceAll("\\", "/"),
                content: yield* fs.readFile(file),
                mode: info.mode,
              } satisfies ZipFile,
            ];
          }),
          { concurrency: 16 },
        );
        return entries.flat();
      });

      /**
       * Resolve the props' content into a `PublishLayerVersion` payload plus
       * a hash of everything that would force a new version.
       */
      const packageContent = Effect.fn(function* (props: LayerVersionProps) {
        const config = {
          description: props.description,
          compatibleRuntimes: props.compatibleRuntimes,
          compatibleArchitectures: props.compatibleArchitectures,
          licenseInfo: props.licenseInfo,
        };
        if (props.s3 && props.path) {
          return yield* Effect.die(
            "AWS.Lambda.LayerVersion accepts either `path` or `s3`, not both.",
          );
        }
        if (props.s3) {
          // Hash the resolved coordinates, not the props, so a bucket passed
          // as a resource and the same bucket passed by name agree.
          const s3 = {
            S3Bucket: bucketNameOf(props.s3.bucket),
            S3Key: props.s3.key,
            S3ObjectVersion: props.s3.objectVersion,
          } satisfies lambda.LayerVersionContentInput;
          return {
            content: s3,
            sourceHash: yield* sha256Object({ s3, config }),
          };
        }
        if (!props.path) {
          return yield* Effect.die("AWS.Lambda.LayerVersion requires either `path` or `s3`.");
        }
        const fs = yield* FileSystem.FileSystem;
        const path = yield* Path.Path;
        const resolved = path.resolve(props.path);
        const info = yield* fs.stat(resolved);
        if (info.type !== "Directory" && path.extname(resolved) !== ".zip") {
          return yield* Effect.die(
            `AWS.Lambda.LayerVersion \`path\` must be a directory or a .zip archive: ${resolved}`,
          );
        }
        const archive =
          info.type === "Directory"
            ? yield* zipFiles(yield* readDirectoryEntries(resolved))
            : yield* fs.readFile(resolved);
        if (archive.byteLength > MAX_INLINE_ARCHIVE_SIZE) {
          return yield* Effect.die(
            `AWS.Lambda.LayerVersion archive is ${archive.byteLength} bytes, above Lambda's ${MAX_INLINE_ARCHIVE_SIZE} byte direct-upload limit. Upload it to S3 and use \`s3\` instead.`,
          );
        }
        return {
          content: {
            ZipFile: new Uint8Array(archive),
          } satisfies lambda.LayerVersionContentInput,
          // Hash the archive bytes rather than the source path so the same
          // content checked out at a different path does not republish.
          sourceHash: yield* sha256Object({
            archive: yield* sha256(archive),
            config,
          }),
        };
      });

      const snapshot = (
        layerName: string,
        sourceHash: string,
        // `listLayerVersions` items carry the same fields as a
        // `getLayerVersion` response minus `LayerArn`/`Content`, so both
        // shapes snapshot through here.
        version: lambda.GetLayerVersionResponse | lambda.LayerVersionsListItem,
      ): LayerVersion["Attributes"] | undefined => {
        if (!version.LayerVersionArn || !version.Version) {
          return undefined;
        }
        const layerArn =
          ("LayerArn" in version ? version.LayerArn : undefined) ??
          // `arn:…:layer:{name}:{version}` — the layer ARN is the version ARN
          // without its trailing version segment.
          version.LayerVersionArn.slice(0, version.LayerVersionArn.lastIndexOf(":"));
        const content = "Content" in version ? version.Content : undefined;
        return {
          layerName,
          layerArn,
          layerVersionArn: version.LayerVersionArn,
          version: version.Version,
          sourceHash,
          codeSha256: content?.CodeSha256,
          codeSize: content?.CodeSize,
          createdDate: version.CreatedDate,
          description: version.Description || undefined,
          compatibleRuntimes: version.CompatibleRuntimes,
          compatibleArchitectures: version.CompatibleArchitectures,
          licenseInfo: version.LicenseInfo,
        };
      };

      const getVersion = (layerName: string, version: number) =>
        Lambda.getLayerVersion({
          LayerName: layerName,
          VersionNumber: version,
        }).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));

      return {
        // `layerVersionArn`/`version` deliberately are NOT stable: an update
        // publishes a new version under the same layer.
        stables: ["layerName", "layerArn"],
        // A layer version is immutable, but the *layer* is not: publishing
        // re-uses the layer name and mints version N+1. So a content or
        // config change is an UPDATE, not a replacement — a replacement would
        // mint a fresh instance id, hence a fresh layer name, and every
        // change would strand a new layer stuck at version 1.
        diff: Effect.fn(function* ({ olds, news, output }) {
          if (!isResolved(news)) return;
          if (!output) return undefined;
          // Auto-generated names are engine-owned: the published layer's name
          // stays authoritative even if the generator would name this id
          // differently today. Only an explicit `layerName` forces a replace.
          if ((news.layerName ?? output.layerName) !== output.layerName) {
            return { action: "replace" } as const;
          }
          const { sourceHash } = yield* packageContent(news);
          if (
            sourceHash !== output.sourceHash ||
            olds.description !== news.description ||
            olds.licenseInfo !== news.licenseInfo ||
            !deepEqual(olds.compatibleRuntimes, news.compatibleRuntimes) ||
            !deepEqual(olds.compatibleArchitectures, news.compatibleArchitectures)
          ) {
            return { action: "update" } as const;
          }
          return { action: "noop" } as const;
        }),
        read: Effect.fn(function* ({ output }) {
          if (!output) return undefined;
          const version = yield* getVersion(output.layerName, output.version);
          return version ? snapshot(output.layerName, output.sourceHash, version) : undefined;
        }),
        list: () =>
          Effect.gen(function* () {
            // Layers carry no tags, so there is nothing to filter ownership
            // on — enumerate every version of every layer in the ambient
            // account/region.
            const layerNames = yield* Lambda.listLayers.items({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk)
                  .map((layer) => layer.LayerName)
                  .filter((name): name is string => name !== undefined),
              ),
            );
            const versions = yield* Effect.forEach(
              layerNames,
              (layerName) =>
                Lambda.listLayerVersions.items({ LayerName: layerName }).pipe(
                  Stream.runCollect,
                  Effect.map((chunk) =>
                    Array.from(chunk).flatMap((version) => {
                      const attrs = snapshot(layerName, "", version);
                      return attrs ? [attrs] : [];
                    }),
                  ),
                  Effect.catchTag("ResourceNotFoundException", () =>
                    Effect.succeed([] as LayerVersion["Attributes"][]),
                  ),
                ),
              { concurrency: 10 },
            );
            return versions.flat();
          }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const layerName = output?.layerName ?? (yield* createLayerName(id, news.layerName));
          const { content, sourceHash } = yield* packageContent(news);

          // Observe: an interrupted apply may have already published the
          // version recorded in state. Republishing would leak a version, so
          // reuse it when it still exists and still matches the desired
          // content.
          if (output?.version !== undefined && output.sourceHash === sourceHash) {
            const existing = yield* getVersion(layerName, output.version);
            const attrs = existing && snapshot(layerName, sourceHash, existing);
            if (attrs) return attrs;
          }

          const published = yield* Lambda.publishLayerVersion({
            LayerName: layerName,
            Content: content,
            Description: news.description,
            CompatibleRuntimes: news.compatibleRuntimes,
            CompatibleArchitectures: news.compatibleArchitectures,
            LicenseInfo: news.licenseInfo,
          });

          const attrs = snapshot(layerName, sourceHash, published);
          if (!attrs) {
            return yield* Effect.die(
              `Lambda layer ${layerName} did not return complete attributes.`,
            );
          }

          // Retire the version this one supersedes, so an update doesn't
          // leak a version per deploy. Functions already referencing the old
          // version keep working — Lambda retains a copy until nothing
          // refers to it.
          if (output?.version !== undefined && output.version !== attrs.version) {
            yield* Lambda.deleteLayerVersion({
              LayerName: layerName,
              VersionNumber: output.version,
            }).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
          }

          yield* session.note(`Layer ${attrs.layerName}:${attrs.version}`);

          return attrs;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* Lambda.deleteLayerVersion({
            LayerName: output.layerName,
            VersionNumber: output.version,
          }).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      };
    }),
  );