import type * as Binding from "alchemy/Binding";
import type { Input } from "alchemy/Input";
import * as Output from "alchemy/Output";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as AWSBindings from "../AWSBindings.ts";
import type { PolicyStatement } from "../IAM/Policy.ts";
import { regionFromArn } from "./BindingHttp.ts";
import type { MicrovmImage } from "./MicrovmImage.ts";
// Shared scaffolding for the MicroVM runtime bindings. Every `*Http` impl is
// identical except for the distilled operation, the IAM action(s), the policy
// scope, and whether the bound image's identifier is injected into the request.
// NOT exported from `index.ts` — it only backs the per-operation `*Http` files.
/** The distilled operation method, yielded to its request callable. */
type Operation<Res, Err> = Effect.Effect<(req: any) => Effect.Effect<Res, Err, any>, never, any>;
export interface ImageBindingOptions<Req, Res, Err, Self> {
/** The `Binding.Service` contract this layer implements. */
binding: Binding.Service<
Self,
string,
(image: MicrovmImage) => Effect.Effect<(req: Req) => Effect.Effect<Res, Err>>
>;
/** Operation name, used for the SID label and tracing, e.g. `"RunMicrovm"`. */
name: string;
/** IAM action(s) the host Function needs, e.g. `["lambda:RunMicrovm"]`. */
actions: string[];
/** The distilled operation, e.g. `microvms.runMicrovm`. */
operation: Operation<Res, Err>;
/**
* Policy scope (always limited to the bound image's identity — never `["*"]`):
* - `"image"` (default) scopes to the exact image ARN (e.g. `RunMicrovm`,
* image-read ops).
* - `"microvm"` scopes to the MicroVM instances launched from this image via
* a `microvm:*` glob derived from the image ARN (same partition, region,
* and account). MicroVM instance ARNs are minted at runtime, so an exact
* ARN can't be known at deploy time, but the action stays bounded to this
* account/region's MicroVMs rather than `["*"]`.
* - `"account"` uses `["*"]`. Reserved for collection-level list actions
* (e.g. `ListMicrovms`) that AWS only authorizes against `*` and cannot be
* resource-scoped, analogous to `ec2:DescribeInstances`.
*/
scope?: "image" | "microvm" | "account";
/** Inject `imageIdentifier: <imageArn>` into each request. */
injectImageIdentifier?: boolean;
/**
* Also grant `lambda:PassNetworkConnector` on network connectors in the
* image's region — both the account's own connectors and the AWS-managed
* ones (e.g. `INTERNET_EGRESS`). Required by `RunMicrovm`, which passes a
* network connector (defaulting to the managed `INTERNET_EGRESS`) to the
* launched MicroVM.
*/
passNetworkConnector?: boolean;
}
/**
* Derive the `microvm:*` instance-ARN glob from an image ARN by swapping the
* `microvm-image:<name>` resource segment for `microvm:*`, keeping the same
* `arn:<partition>:lambda:<region>:<account>:` prefix.
*/
const microvmGlob = (imageArn: string): string =>
`${imageArn.replace(/:microvm-image[:/].*$/, "")}:microvm:*`;
/**
* Derive the network-connector ARN globs from an image ARN: the account's own
* connectors (`arn:<partition>:lambda:<region>:<account>:network-connector:*`)
* and the AWS-managed connectors (same prefix but account `aws`).
*/
const networkConnectorGlobs = (imageArn: string): string[] => {
// arn:<partition>:lambda:<region>:<account>
const prefix = imageArn.replace(/:microvm-image[:/].*$/, "");
// arn:<partition>:lambda:<region>
const regionPrefix = prefix.replace(/:[^:]*$/, "");
return [`${prefix}:network-connector:*`, `${regionPrefix}:aws:network-connector:*`];
};
/** The IAM policy statements an image-scoped MicroVM operation requires. */
const imagePolicyStatements = <Req, Res, Err, Self>(
image: MicrovmImage,
options: ImageBindingOptions<Req, Res, Err, Self>,
): Input<PolicyStatement>[] => [
{
Effect: "Allow",
Action: options.actions,
Resource:
options.scope === "account"
? // Collection-level list actions only authorize on `*`.
["*"]
: options.scope === "microvm"
? [
// Instance ops (GetMicrovm, TerminateMicrovm, CreateAuthToken,
// …) are authorized by AWS against the image ARN as well as the
// instance ARN, so grant both: the exact image and the
// `microvm:*` instance glob derived from it.
Output.interpolate`${image.imageArn}`,
image.imageArn.pipe(Output.map(microvmGlob)),
]
: [Output.interpolate`${image.imageArn}`],
},
...(options.passNetworkConnector
? [
{
Effect: "Allow" as const,
Action: ["lambda:PassNetworkConnector"],
Resource: [
image.imageArn.pipe(Output.map((a) => networkConnectorGlobs(a)[0]!)),
image.imageArn.pipe(Output.map((a) => networkConnectorGlobs(a)[1]!)),
],
},
]
: []),
];
/**
* Build a MicroVM runtime binding bound to a {@link MicrovmImage}. At deploy it
* grants the IAM statements to the host via `AWSBindings.Bind`: the host's
* own role, or the Role Alchemy creates for it. At runtime it calls the
* distilled operation resolved with `AWSBindings.withCredentials`, signing in
* the image's region on a host with a created key.
*/
export const makeImageBinding = <Req, Res, Err, Self>(
options: ImageBindingOptions<Req, Res, Err, Self>,
): Layer.Layer<Self> =>
Layer.effect(
options.binding as any,
Effect.gen(function* () {
const bind = yield* AWSBindings.Bind;
return Effect.fn(function* (image: MicrovmImage) {
// Accessors (registered on the host at deploy, resolved at runtime).
const imageArn = yield* image.imageArn;
// Region is derived from the resolved image ARN — via `Effect.map` of
// the accessor, NOT a second Output binding (whose env key would embed
// the mapper's source text and is brittle).
// resolved per bind because a host with a created key signs in the image's own region
const run = yield* AWSBindings.withCredentials(
options.operation,
Effect.succeed(Effect.map(imageArn, regionFromArn)),
);
if (!globalThis.__ALCHEMY_RUNTIME__) {
yield* bind`AWS.Lambda.${options.name}(${image})`({
policyStatements: imagePolicyStatements(image, options),
});
}
return Effect.fn(`AWS.Lambda.${options.name}(${image.LogicalId})`)(function* (
request: Req,
) {
return yield* run(
options.injectImageIdentifier
? { ...(request as object), imageIdentifier: yield* imageArn }
: request,
);
});
});
}),
) as unknown as Layer.Layer<Self>;
export interface AccountBindingOptions<Req, Res, Err, Self> {
binding: Binding.Service<
Self,
string,
() => Effect.Effect<(req: Req) => Effect.Effect<Res, Err>>
>;
name: string;
actions: string[];
operation: Operation<Res, Err>;
}
/**
* Build an account-scoped MicroVM binding (no resource argument), e.g. for
* listing AWS-managed base images. IAM `Resource` is `["*"]`.
*/
export const makeAccountBinding = <Req, Res, Err, Self>(
options: AccountBindingOptions<Req, Res, Err, Self>,
): Layer.Layer<Self> =>
Layer.effect(
options.binding as any,
Effect.gen(function* () {
const bind = yield* AWSBindings.Bind;
const run = yield* AWSBindings.withCredentials(options.operation);
return Effect.fn(function* () {
if (!globalThis.__ALCHEMY_RUNTIME__) {
yield* bind`AWS.Lambda.${options.name}()`({
policyStatements: [{ Effect: "Allow", Action: options.actions, Resource: ["*"] }],
});
}
return Effect.fn(`AWS.Lambda.${options.name}()`)(function* (request: Req) {
return yield* run(request);
});
});
}),
) as unknown as Layer.Layer<Self>;