alchemy 2.0.0-beta.65 → 2.0.0-beta.67

package/src/AWS/Lambda/LayerVersion.ts

@@ -0,0 +1,490 @@
+import type * as lambda from "@distilled.cloud/aws/lambda";
+import * as Lambda from "@distilled.cloud/aws/lambda";
+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 { deepEqual, isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import { sha256, sha256Object } from "../../Util/sha256.ts";
+import { zipFiles, type ZipFile } from "../../Util/zip.ts";
+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.
+ *
+ * @resource
+ * @section 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",
+ *   },
+ * });
+ * ```
+ *
+ * @section 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],
+ * });
+ * ```
+ */
+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.succeed(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),
+          );
+        }),
+      };
+    }),
+  );

package/src/AWS/Lambda/MicrovmBundle.ts

@@ -136,6 +136,7 @@ const HttpServer = NodeHttpServer;`
 }
 import { Stack } from "alchemy/Stack";
 import { makeEntrypointLayer } from "alchemy/Runtime";
+import { provideProcessTelemetry } from "alchemy/Telemetry";
 import * as Effect from "effect/Effect";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 import * as Layer from "effect/Layer";
@@ -162,8 +163,15 @@ const stack = Layer.succeed(Stack, {
 });
 
 const serverEffect = tag.pipe(
-  Effect.flatMap(func => func.RuntimeContext.exports),
-  Effect.flatMap(exports => exports.default),
+  // Process-lifetime telemetry: built once into the root scope; exporters
+  // batch on their intervals and flush when the scope closes on graceful
+  // shutdown.
+  Effect.flatMap((func) =>
+    func.RuntimeContext.exports.pipe(
+      Effect.flatMap((exports) => exports.default),
+      provideProcessTelemetry(func.RuntimeContext),
+    ),
+  ),
   Effect.provide(
     layer.pipe(
       Layer.provideMerge(stack),

package/src/AWS/Lambda/index.ts

@@ -33,6 +33,7 @@ export * from "./InvokeFunctionHttp.ts";
 export * from "./InvokeWithResponseStream.ts";
 export * from "./InvokeWithResponseStreamHttp.ts";
 export * from "./KafkaEventSource.ts";
+export * from "./LayerVersion.ts";
 export * from "./ListFunctions.ts";
 export * from "./ListFunctionsHttp.ts";
 export * from "./ListManagedMicrovmImages.ts";

package/src/AWS/Providers.ts

@@ -663,6 +663,7 @@ export const providers = () =>
       Lambda.Alias,
       Lambda.EventSourceMapping,
       Lambda.Function,
+      Lambda.LayerVersion,
       Lambda.MicrovmImage,
       Lambda.NetworkConnector,
       Lambda.Permission,
@@ -872,10 +873,14 @@ export const providers = () =>
       ServiceCatalog.PrincipalPortfolioAssociation,
       ServiceCatalog.Product,
       ServiceQuotas.ServiceQuotaIncreaseRequest,
+      SES.ActiveReceiptRuleSet,
       SES.ConfigurationSet,
       SES.ConfigurationSetEventDestination,
       SES.EmailIdentity,
       SES.EmailTemplate,
+      SES.ReceiptFilter,
+      SES.ReceiptRule,
+      SES.ReceiptRuleSet,
       Shield.Protection,
       Shield.ProtectionGroup,
       Shield.Subscription,
@@ -1249,6 +1254,7 @@ export const providers = () =>
           Lambda.AliasProvider(),
           Lambda.EventSourceMappingProvider(),
           Lambda.FunctionProvider(),
+          Lambda.LayerVersionProvider(),
           Lambda.MicrovmImageProvider(),
           Lambda.NetworkConnectorProvider(),
           Lambda.PermissionProvider(),
@@ -1354,10 +1360,14 @@ export const providers = () =>
           Scheduler.ScheduleProvider(),
           SecretsManager.RotationScheduleProvider(),
           SecretsManager.SecretProvider(),
+          SES.ActiveReceiptRuleSetProvider(),
           SES.ConfigurationSetEventDestinationProvider(),
           SES.ConfigurationSetProvider(),
           SES.EmailIdentityProvider(),
           SES.EmailTemplateProvider(),
+          SES.ReceiptFilterProvider(),
+          SES.ReceiptRuleProvider(),
+          SES.ReceiptRuleSetProvider(),
           SNS.PlatformApplicationProvider(),
           SNS.SubscriptionProvider(),
           SNS.TopicProvider(),

package/src/AWS/SES/ActiveReceiptRuleSet.ts

@@ -0,0 +1,88 @@
+import * as ses from "@distilled.cloud/aws/ses";
+import * as Effect from "effect/Effect";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+
+export interface ActiveReceiptRuleSetProps {
+  /**
+   * Name of the receipt rule set to make active for the account in the current
+   * region. Typically the `ruleSetName` output of a `SES.ReceiptRuleSet`.
+   * Re-pointing to a different rule set updates the active pointer in place.
+   */
+  ruleSetName: string;
+}
+
+export interface ActiveReceiptRuleSet extends Resource<
+  "AWS.SES.ActiveReceiptRuleSet",
+  ActiveReceiptRuleSetProps,
+  {
+    /** Name of the rule set that is active for the account. */
+    ruleSetName: string;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * The account's active Amazon SES receipt rule set — the single rule set (per
+ * account, per region) that SES actually evaluates against inbound mail.
+ *
+ * This is an account-level singleton pointer, not a container: only one rule
+ * set can be active at a time. Deleting this resource deactivates email
+ * receiving (clears the pointer) only when the account is still pointed at the
+ * rule set this resource set; if something else has since become active, the
+ * delete is a no-op.
+ * @resource
+ * @section Activating a Rule Set
+ * @example Make a Rule Set Active
+ * ```typescript
+ * import * as SES from "alchemy/AWS/SES";
+ *
+ * const ruleSet = yield* SES.ReceiptRuleSet("Inbound", {});
+ * const active = yield* SES.ActiveReceiptRuleSet("Active", {
+ *   ruleSetName: ruleSet.ruleSetName,
+ * });
+ * ```
+ */
+export const ActiveReceiptRuleSet = Resource<ActiveReceiptRuleSet>(
+  "AWS.SES.ActiveReceiptRuleSet",
+);
+
+const activeRuleSetName = Effect.fn(function* () {
+  const response = yield* ses.describeActiveReceiptRuleSet({});
+  return response.Metadata?.Name;
+});
+
+export const ActiveReceiptRuleSetProvider = () =>
+  Provider.succeed(ActiveReceiptRuleSet, {
+    // Account/region singleton setting: "deleting" it only clears the active
+    // pointer, so nuke skips it (and would otherwise disable email receiving
+    // account-wide).
+    nuke: { singleton: true },
+
+    list: () => Effect.succeed([]),
+
+    read: Effect.fn(function* () {
+      const name = yield* activeRuleSetName();
+      return name ? { ruleSetName: name } : undefined;
+    }),
+
+    reconcile: Effect.fn(function* ({ news }) {
+      // OBSERVE the current active pointer; only re-point on a mismatch.
+      const observed = yield* activeRuleSetName();
+      if (observed !== news.ruleSetName) {
+        yield* ses.setActiveReceiptRuleSet({ RuleSetName: news.ruleSetName });
+      }
+      return { ruleSetName: news.ruleSetName };
+    }),
+
+    delete: Effect.fn(function* ({ output }) {
+      // Only deactivate if the account is still pointed at the rule set we
+      // activated; otherwise another owner has taken over and we leave it be.
+      const observed = yield* activeRuleSetName();
+      if (observed === output.ruleSetName) {
+        yield* ses.setActiveReceiptRuleSet({});
+      }
+    }),
+  });