alchemy 2.0.0-beta.59 → 2.0.0-beta.60

package/lib/AWS/Lambda/MicrovmImage.js

@@ -0,0 +1,381 @@
+import * as Effect from "effect/Effect";
+import { Platform } from "../../Platform.js";
+import { makeMicrovmRuntimeContext, MicrovmImageTypeId, } from "./MicrovmRuntimeContext.js";
+/**
+ * The IAM permissions a build role needs: read the code artifact from the
+ * Assets bucket(s) and write build logs to CloudWatch. Used to auto-grant a
+ * {@link Role} passed as `buildRole`.
+ */
+const buildRolePolicyStatements = [
+    {
+        Effect: "Allow",
+        Action: ["s3:GetObject"],
+        Resource: ["arn:aws:s3:::alchemy-assets-*-an/*"],
+    },
+    {
+        Effect: "Allow",
+        Action: [
+            "logs:CreateLogGroup",
+            "logs:CreateLogStream",
+            "logs:PutLogEvents",
+        ],
+        Resource: ["arn:aws:logs:*:*:log-group:/aws/lambda/microvms/*"],
+    },
+];
+export { MicrovmImageTypeId } from "./MicrovmRuntimeContext.js";
+/**
+ * A Lambda **MicroVM image** — a Firecracker snapshot that boots a fully
+ * initialized application in milliseconds. The model is *image-then-launch*:
+ * you create an image once (this resource), then launch isolated, stateful
+ * MicroVM instances from it at runtime (one per end-user/session) with the
+ * {@link RunMicrovm} binding from a Lambda Function.
+ *
+ * ### How the build works
+ *
+ * The build runs **server-side on AWS** — there is no local Docker. You supply
+ * a *code artifact* (a zip of a Dockerfile + your code) and a *base image*
+ * (`baseImage`); AWS runs your Dockerfile on top of the base, initializes
+ * the app, and takes a Firecracker snapshot. The build is asynchronous: the
+ * provider uploads the artifact, calls `CreateMicrovmImage`/`UpdateMicrovmImage`,
+ * and polls until the image reaches `CREATED`/`UPDATED` (or surfaces the build
+ * failure). Build logs stream to CloudWatch at `/aws/lambda/microvms/<name>`.
+ *
+ * Alchemy produces the code artifact for you in three ways, selected by which
+ * prop you set (`main` → `context` → `codeArtifact.uri`):
+ *
+ * - **Effectful** (`main`): write the in-VM HTTP server in TypeScript as an
+ *   Effect. Alchemy bundles it (with its capability bindings), generates a
+ *   Dockerfile on the MicroVM base, zips both, and uploads to the Assets bucket.
+ * - **External** (`context`/`dockerfile`): bring your own Dockerfile + build
+ *   context (any language). Alchemy zips the directory and uploads it.
+ * - **Prebuilt** (`codeArtifact.uri`): point at an existing S3 zip or ECR image
+ *   URI; nothing is built or uploaded.
+ *
+ * Re-deploys only trigger a new build when the artifact's content hash or a
+ * build-affecting prop changes; otherwise the image is left untouched.
+ *
+ * ### Prerequisites
+ *
+ * - A **build role** (`buildRole`) Lambda assumes to read the code artifact and
+ *   write build logs. Pass a {@link Role} instance and the required permissions
+ *   are granted automatically — see the example below.
+ * - A **bootstrapped Assets bucket** (`alchemy aws bootstrap`) for effectful /
+ *   external modes, which upload the artifact to S3.
+ * - The account must be **onboarded to the Lambda MicroVM preview**.
+ *
+ * @resource
+ *
+ * @section Creating the Build Role
+ * Pass a bare {@link Role} as `buildRole` and the MicroVM image grants
+ * everything it needs via a binding: the trust policy (so Lambda can assume it)
+ * plus the S3 (Assets bucket) and CloudWatch-logs permissions (folded into an
+ * `alchemy-bindings` inline policy). You don't write any policy yourself.
+ * @example Bare build role
+ * ```typescript
+ * const buildRole = yield* AWS.IAM.Role("MicrovmBuildRole", {});
+ *
+ * // Pass the role instance; trust + permissions are attached for you.
+ * const image = yield* AWS.Lambda.MicrovmImage("Sandbox", {
+ *   main: import.meta.filename,
+ *   buildRole,
+ * });
+ * ```
+ *
+ * @section Effectful MicroVMs
+ * Write the in-VM server in TypeScript. Alchemy bundles `main` and bakes it into
+ * the image; the server listens on `port` (default 8080), which becomes the
+ * MicroVM `endpoint`.
+ * @example In-VM HTTP server (single file)
+ * ```typescript
+ * export default class Sandbox extends AWS.Lambda.MicrovmImage<Sandbox>()(
+ *   "Sandbox",
+ *   { main: import.meta.filename, buildRole },
+ *   Effect.gen(function* () {
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         return HttpServerResponse.text(`hello from ${request.url}`);
+ *       }),
+ *     };
+ *   }),
+ * ) {}
+ * ```
+ *
+ * @example With capability bindings and env vars
+ * ```typescript
+ * export default class Sandbox extends AWS.Lambda.MicrovmImage<Sandbox>()(
+ *   "Sandbox",
+ *   {
+ *     main: import.meta.filename,
+ *     buildRole,
+ *     runtime: "bun",
+ *     env: { LOG_LEVEL: "info" },
+ *   },
+ *   Effect.gen(function* () {
+ *     // bindings are bundled into the image and resolved at runtime
+ *     const getObject = yield* AWS.S3.GetObject(bucket);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const obj = yield* getObject({ key: "data.json" });
+ *         return HttpServerResponse.json(yield* obj.json);
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(AWS.S3.GetObjectHttp)),
+ * ) {}
+ * ```
+ *
+ * @example Class + `.make()` (two files, for a Lambda orchestrator)
+ * When a Lambda Function imports the image to bind its instance operations, keep
+ * the class (a typed handle) and the `.make()` runtime in separate files so the
+ * orchestrator's bundle doesn't pull in the VM's runtime deps.
+ * ```typescript
+ * // sandbox.ts — imported by the orchestrator
+ * export class Sandbox extends AWS.Lambda.MicrovmImage<Sandbox>()("Sandbox") {}
+ *
+ * // sandbox.live.ts — provided on the Stack; bundled into the image.
+ * // Must be the `default` export: the bundler resolves the image entrypoint
+ * // from the code artifact's default export.
+ * export default Sandbox.make(
+ *   { main: import.meta.filename, buildRole },
+ *   Effect.gen(function* () {
+ *     return { fetch: Effect.gen(function* () {
+ *       return HttpServerResponse.text("ok");
+ *     }) };
+ *   }),
+ * );
+ * ```
+ *
+ * @section Tagged RPC
+ * Beyond (or instead of) a raw `fetch` handler, an image can expose a typed
+ * **RPC `Shape`** as the second type parameter. The in-VM runtime serves those
+ * methods over an `/__rpc__/*` protocol and falls through to `fetch` for every
+ * other request, so an image can offer BOTH a typed RPC surface and ordinary
+ * HTTP routes. A caller gets a fully-typed client with {@link connectMicrovm}:
+ * value methods `yield*` as `Effect`s, streaming methods pipe as `Stream`s.
+ * @example Define a tagged-RPC image (RPC + fetch)
+ * ```typescript
+ * // sandbox.ts — the typed handle imported by the orchestrator Lambda
+ * export class Sandbox extends AWS.Lambda.MicrovmImage<
+ *   Sandbox,
+ *   { hello: (message: string) => Effect.Effect<string> }
+ * >()("Sandbox") {}
+ *
+ * // sandbox.live.ts — provided on the Stack; bundled into the image (default export)
+ * export default Sandbox.make(
+ *   { main: import.meta.filename, buildRole },
+ *   Effect.gen(function* () {
+ *     return {
+ *       // RPC method — reached with `connectMicrovm` below
+ *       hello: (message: string) => Effect.succeed(`hello, ${message}!`),
+ *       // raw HTTP route — reached with a plain HTTPS request to the endpoint
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         const url = new URL(request.url, "http://microvm");
+ *         return HttpServerResponse.json({ path: url.pathname });
+ *       }),
+ *     };
+ *   }),
+ * );
+ * ```
+ *
+ * @example Call the RPC method from a Lambda
+ * `connectMicrovm` builds the typed stub over an `HttpClient` (provide
+ * `FetchHttpClient.layer` for the request scope), pointing at the running
+ * MicroVM's `endpoint` and authenticating with the `authToken` headers.
+ * ```typescript
+ * const vm = yield* runMicrovm({});
+ * // ...wait until `vm.state` is RUNNING (poll `getMicrovm`)...
+ * const { authToken } = yield* createAuthToken({
+ *   microvmIdentifier: vm.microvmId,
+ *   expirationInMinutes: 5,
+ *   allowedPorts: [{ port: 8080 }], // the in-VM server's port
+ * });
+ *
+ * const sandbox = yield* AWS.Lambda.connectMicrovm(Sandbox, {
+ *   endpoint: vm.endpoint,
+ *   authToken,
+ * });
+ * const reply = yield* sandbox.hello("world"); // "hello, world!"
+ * ```
+ *
+ * @example Call the same MicroVM's `fetch` route directly
+ * For the raw HTTP path, send the auth token as request headers via
+ * {@link microvmAuthHeaders}.
+ * ```typescript
+ * const client = yield* HttpClient.HttpClient;
+ * const res = yield* client.get(`https://${vm.endpoint}/echo?message=hi`, {
+ *   headers: AWS.Lambda.microvmAuthHeaders(authToken),
+ * });
+ * const body = yield* res.json;
+ * ```
+ *
+ * @section External Images (your own Dockerfile)
+ * Bring a build context directory containing a Dockerfile (any language).
+ * Alchemy zips and uploads it; AWS runs your Dockerfile. Your Dockerfile should
+ * build on a MicroVM-compatible base (e.g.
+ * `FROM public.ecr.aws/lambda/microvms:al2023-minimal`).
+ * @example Flask app from a Dockerfile
+ * ```typescript
+ * const image = yield* AWS.Lambda.MicrovmImage("Flask", {
+ *   context: `${import.meta.dirname}/app`, // dir with Dockerfile + app.py
+ *   buildRole,
+ * });
+ * ```
+ * @example Custom Dockerfile path within the context
+ * ```typescript
+ * const image = yield* AWS.Lambda.MicrovmImage("Worker", {
+ *   context: `${import.meta.dirname}/app`,
+ *   dockerfile: "docker/worker.Dockerfile", // relative to `context`
+ *   buildRole,
+ * });
+ * ```
+ *
+ * @section Prebuilt Artifacts
+ * Skip the build entirely and point at an artifact you already produced.
+ * @example From an existing S3 zip
+ * ```typescript
+ * const image = yield* AWS.Lambda.MicrovmImage("Prebuilt", {
+ *   codeArtifact: { uri: "s3://my-bucket/app.zip" }, // or an ECR image URI
+ *   buildRole,
+ * });
+ * ```
+ *
+ * @section Sizing and Base Image
+ * `baseImage` defaults to the latest AWS-managed `al2023` base (discovered
+ * via `listManagedMicrovmImages`). Override it, and tune CPU/memory, explicitly.
+ * @example Pin the base image and resources
+ * ```typescript
+ * const image = yield* AWS.Lambda.MicrovmImage("Sized", {
+ *   main: import.meta.filename,
+ *   buildRole,
+ *   baseImage: "arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1",
+ *   cpuConfigurations: [{ architecture: "ARM_64" }],
+ *   resources: [{ minimumMemoryInMiB: 2048 }],
+ * });
+ * ```
+ *
+ * @section Logging
+ * @example Stream runtime + build logs to a custom CloudWatch group
+ * ```typescript
+ * const image = yield* AWS.Lambda.MicrovmImage("Logged", {
+ *   main: import.meta.filename,
+ *   buildRole,
+ *   logging: { cloudWatch: { logGroup: "/aws/microvm/my-app" } },
+ *   // or disable: logging: { disabled: {} }
+ * });
+ * ```
+ *
+ * @section VPC Egress
+ * Give the MicroVM a managed egress path into your VPC with a
+ * {@link NetworkConnector} (reference it by ARN).
+ * @example Image-level egress connector
+ * ```typescript
+ * const egress = yield* AWS.Lambda.NetworkConnector("Egress", {
+ *   subnetIds: [subnet.subnetId],
+ *   securityGroupIds: [sg.groupId],
+ *   operatorRole: operatorRole.roleArn,
+ * });
+ *
+ * const image = yield* AWS.Lambda.MicrovmImage("Connected", {
+ *   main: import.meta.filename,
+ *   buildRole,
+ *   egressNetworkConnectors: [egress.networkConnectorArn],
+ * });
+ * ```
+ *
+ * @section Launching MicroVMs
+ * The image is just the template. Launch and drive instances from a Lambda
+ * Function using the per-operation bindings ({@link RunMicrovm},
+ * {@link GetMicrovm}, {@link CreateAuthToken}, {@link TerminateMicrovm}, …).
+ * Each binding's IAM policy is scoped to this image automatically.
+ * @example Run a MicroVM, call its RPC, and tear it down
+ * Always terminate the MicroVM you launched — wrap the work in
+ * `Effect.ensuring` so a failure (or a client retry) never leaks a running
+ * MicroVM against your account's memory quota. Give the Function a generous
+ * `timeout` since it waits for the MicroVM to reach RUNNING in-line.
+ * ```typescript
+ * export default class Api extends AWS.Lambda.Function<Api>()(
+ *   "Api",
+ *   { main: import.meta.filename, url: true, timeout: Duration.seconds(120) },
+ *   Effect.gen(function* () {
+ *     const runMicrovm = yield* AWS.Lambda.RunMicrovm(Sandbox);
+ *     const getMicrovm = yield* AWS.Lambda.GetMicrovm(Sandbox);
+ *     const createAuthToken = yield* AWS.Lambda.CreateAuthToken(Sandbox);
+ *     const terminateMicrovm = yield* AWS.Lambda.TerminateMicrovm(Sandbox);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const vm = yield* runMicrovm({
+ *           idlePolicy: {
+ *             maxIdleDurationSeconds: 900,
+ *             suspendedDurationSeconds: 300,
+ *             autoResumeEnabled: true,
+ *           },
+ *         });
+ *         return yield* Effect.gen(function* () {
+ *           // wait until the MicroVM is RUNNING before connecting
+ *           yield* getMicrovm({ microvmIdentifier: vm.microvmId }).pipe(
+ *             Effect.flatMap((m) =>
+ *               m.state === "RUNNING"
+ *                 ? Effect.void
+ *                 : Effect.fail(new Error(`microvm ${m.state}`)),
+ *             ),
+ *             Effect.retry({ schedule: Schedule.spaced("2 seconds"), times: 30 }),
+ *           );
+ *           const { authToken } = yield* createAuthToken({
+ *             microvmIdentifier: vm.microvmId,
+ *             expirationInMinutes: 5,
+ *             allowedPorts: [{ port: 8080 }],
+ *           });
+ *           const sandbox = yield* AWS.Lambda.connectMicrovm(Sandbox, {
+ *             endpoint: vm.endpoint,
+ *             authToken,
+ *           });
+ *           const reply = yield* sandbox.hello("world");
+ *           return yield* HttpServerResponse.json({ reply });
+ *         }).pipe(
+ *           // terminate on success OR failure — never leak a running MicroVM
+ *           Effect.ensuring(
+ *             terminateMicrovm({ microvmIdentifier: vm.microvmId }).pipe(
+ *               Effect.ignore,
+ *             ),
+ *           ),
+ *           // the in-VM endpoint calls need an HttpClient for this scope
+ *           Effect.provide(FetchHttpClient.layer),
+ *         );
+ *       }),
+ *     };
+ *   }).pipe(
+ *     Effect.provide(
+ *       Layer.mergeAll(
+ *         AWS.Lambda.RunMicrovmHttp,
+ *         AWS.Lambda.GetMicrovmHttp,
+ *         AWS.Lambda.CreateAuthTokenHttp,
+ *         AWS.Lambda.TerminateMicrovmHttp,
+ *       ),
+ *     ),
+ *   ),
+ * ) {}
+ * ```
+ */
+export const MicrovmImage = Platform(MicrovmImageTypeId, {
+    createRuntimeContext: makeMicrovmRuntimeContext,
+    // When `buildRole` is a Role instance, grant it the build permissions via a
+    // binding so the user doesn't have to author the inline policy.
+    onCreate: (_resource, props) => props.buildRole && typeof props.buildRole !== "string"
+        ? props.buildRole
+            .bind `Allow(${_resource}, AWS.Lambda.MicrovmImage.build)`({
+            // Grant the build permissions...
+            policyStatements: buildRolePolicyStatements,
+            // ...and the trust statement, so a build role passed as a bare
+            // `Role` (no `assumeRolePolicyDocument`) can be assumed by Lambda.
+            assumeRolePolicyStatements: [
+                {
+                    Effect: "Allow",
+                    Principal: { Service: "lambda.amazonaws.com" },
+                    Action: ["sts:AssumeRole"],
+                },
+            ],
+        })
+        : Effect.void,
+});
+//# sourceMappingURL=MicrovmImage.js.map

package/lib/AWS/Lambda/MicrovmImage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicrovmImage.js","sourceRoot":"","sources":["../../../src/AWS/Lambda/MicrovmImage.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAO7C,OAAO,EACL,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAEpC;;;;GAIG;AACH,MAAM,yBAAyB,GAAsB;IACnD;QACE,MAAM,EAAE,OAAO;QACf,MAAM,EAAE,CAAC,cAAc,CAAC;QACxB,QAAQ,EAAE,CAAC,oCAAoC,CAAC;KACjD;IACD;QACE,MAAM,EAAE,OAAO;QACf,MAAM,EAAE;YACN,qBAAqB;YACrB,sBAAsB;YACtB,mBAAmB;SACpB;QACD,QAAQ,EAAE,CAAC,mDAAmD,CAAC;KAChE;CACF,CAAC;AAEF,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAyKhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6UG;AACH,MAAM,CAAC,MAAM,YAAY,GAKrB,QAAQ,CAAC,kBAAkB,EAAE;IAC/B,oBAAoB,EAAE,yBAAyB;IAC/C,4EAA4E;IAC5E,gEAAgE;IAChE,QAAQ,EAAE,CAAC,SAAS,EAAE,KAAwB,EAAE,EAAE,CAChD,KAAK,CAAC,SAAS,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ;QACpD,CAAC,CAAC,KAAK,CAAC,SAAS;aACZ,IAAI,CAAA,SAAS,SAAS,kCAAkC,CAAC;YAC1D,iCAAiC;YACjC,gBAAgB,EAAE,yBAAyB;YAC3C,+DAA+D;YAC/D,mEAAmE;YACnE,0BAA0B,EAAE;gBAC1B;oBACE,MAAM,EAAE,OAAO;oBACf,SAAS,EAAE,EAAE,OAAO,EAAE,sBAAsB,EAAE;oBAC9C,MAAM,EAAE,CAAC,gBAAgB,CAAC;iBAC3B;aACF;SACF,CAAC;QACJ,CAAC,CAAC,MAAM,CAAC,IAAI;CAClB,CAAC,CAAC"}

package/lib/AWS/Lambda/MicrovmProvider.d.ts

@@ -0,0 +1,7 @@
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Provider from "../../Provider.ts";
+import { Assets } from "../Assets.ts";
+import { MicrovmImage } from "./MicrovmImage.ts";
+export declare const MicrovmImageProvider: () => import("effect/Layer").Layer<Provider.Provider<MicrovmImage>, never, Assets | FileSystem.FileSystem | Path.Path | import("../../Stack.ts").Stack | import("../../Stage.ts").Stage | import("../Assets.ts").AssetsRequirements>;
+//# sourceMappingURL=MicrovmProvider.d.ts.map

package/lib/AWS/Lambda/MicrovmProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicrovmProvider.d.ts","sourceRoot":"","sources":["../../../src/AWS/Lambda/MicrovmProvider.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AASpC,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAC;AAG9C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAQtC,OAAO,EAAE,YAAY,EAA0B,MAAM,mBAAmB,CAAC;AAiSzE,eAAO,MAAM,oBAAoB,sOA6G7B,CAAC"}