import * as imagebuilder from "@distilled.cloud/aws/imagebuilder";
import { Unowned } from "alchemy/AdoptPolicy";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
imageBuilderArn,
immutableVersionKeysChanged,
retryWhileDependedOn,
syncImageBuilderTags,
toTagRecord,
} from "./internal.ts";
export class ComponentUnexpectedResponse extends Data.TaggedError("ComponentUnexpectedResponse")<{
readonly message: string;
readonly cause?: unknown;
}> {}
/**
* A Component must define its document inline (`data`) or point at an S3
* object (`uri`) — exactly one of the two.
*/
export class ComponentSourceInvalid extends Data.TaggedError(
"AWS::ImageBuilder::ComponentSourceInvalid",
)<{
message: string;
}> {}
/**
* Image Builder component versions are immutable — the deployed document
* differs from the desired one but the semantic version was not bumped, so
* the cloud state cannot be converged.
*/
export class ComponentVersionImmutable extends Data.TaggedError(
"AWS::ImageBuilder::ComponentVersionImmutable",
)<{
message: string;
}> {}
export interface ComponentProps {
/**
* Name of the component. If omitted, a deterministic physical name is
* generated. Changing the name replaces the component.
*/
componentName?: string;
/**
* Semantic version of the component (`major.minor.patch`). Components
* are immutable — bump the version when changing `data`/`uri`. Changing
* the version replaces the component.
* @default "1.0.0"
*/
semanticVersion?: string;
/**
* Operating system platform of the component. Changing the platform
* replaces the component.
*/
platform: "Linux" | "Windows" | "macOS";
/**
* Inline YAML component document (AWSTOMC schema) defining the build /
* validate / test phases. Mutually exclusive with `uri`. Changing the
* data replaces the component.
*/
data?: string;
/**
* S3 URI of a YAML component document. Use for documents larger than
* 64 KB. Mutually exclusive with `data`. Changing the URI replaces the
* component.
*/
uri?: string;
/**
* Description of the component. Changing the description replaces the
* component (component versions are immutable).
*/
description?: string;
/**
* Description of the change in this version compared to the previous
* one. Changing it replaces the component.
*/
changeDescription?: string;
/**
* Operating system versions supported by the component
* (e.g. `["Amazon Linux 2023"]`). Changing them replaces the component.
*/
supportedOsVersions?: string[];
/**
* KMS key used to encrypt the component. Changing it replaces the
* component.
*/
kmsKeyId?: string;
/**
* User-defined tags for the component.
*/
tags?: Record<string, string>;
}
export interface Component extends Resource<
"AWS.ImageBuilder.Component",
ComponentProps,
{
/** The name of the component. */
componentName: string;
/** The ARN of this component build version. */
componentBuildVersionArn: string;
/** The semantic version of the component. */
semanticVersion: string;
/** The OS platform of the component (`Linux` / `Windows`). */
platform: string;
/** Whether the component is a `BUILD` or `TEST` component. */
type: string | undefined;
/** When the component was created. */
dateCreated: string | undefined;
},
never,
Providers
> {}
/**
* An EC2 Image Builder component — a YAML document that defines the build,
* validation, and test steps applied to an instance during image creation.
*
* Components are immutable versions: every property except `tags` replaces
* the component. Bump `semanticVersion` when changing the document.
* ### Creating a Component
* **Example:** Inline Build Component
* ```typescript
* const component = yield* ImageBuilder.Component("Setup", {
* platform: "Linux",
* semanticVersion: "1.0.0",
* data: [
* "name: setup",
* "description: install packages",
* "schemaVersion: 1.2",
* "phases:",
* " - name: build",
* " steps:",
* " - name: install",
* " action: ExecuteBash",
* " inputs:",
* " commands:",
* " - dnf install -y htop",
* ].join("\n"),
* });
* ```
*
* ### Using in an Image Recipe
* **Example:** Reference from a Recipe
* ```typescript
* const recipe = yield* ImageBuilder.ImageRecipe("Recipe", {
* parentImage: "arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x",
* components: [{ componentArn: component.componentBuildVersionArn }],
* });
* ```
*
* @resource
*/
export const Component = Resource<Component>("AWS.ImageBuilder.Component");
export const ComponentProvider = () =>
Provider.effect(
Component,
Effect.gen(function* () {
const toName = (id: string, props: ComponentProps) =>
props.componentName
? Effect.succeed(props.componentName)
: createPhysicalName({ id, maxLength: 126 });
const toVersion = (props: ComponentProps) => props.semanticVersion ?? "1.0.0";
/**
* CreateComponent always mints build version 1 for a fresh
* name/version pair (subsequent creates of the same pair are
* rejected), so the build-version ARN is deterministic.
*/
const toBuildVersionArn = (name: string, version: string) =>
imageBuilderArn("component", `${name}/${version}/1`);
const getComponent = Effect.fn(function* (arn: string) {
const response = yield* imagebuilder
.getComponent({ componentBuildVersionArn: arn })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
return response?.component;
});
const toAttrs = Effect.fn(function* (component: imagebuilder.Component) {
if (!component.arn || !component.name || !component.version) {
return yield* new ComponentUnexpectedResponse({
message: "Image Builder component is missing its ARN, name, or version",
});
}
return {
componentName: component.name,
componentBuildVersionArn: component.arn,
semanticVersion: component.version,
platform: component.platform ?? "",
type: component.type,
dateCreated: component.dateCreated,
};
});
return {
stables: ["componentName", "semanticVersion"],
// Components are immutable — any changed property except tags
// replaces. Individual keys may still hold unresolved Outputs at
// plan time; compare per key so a resolved change still plans a
// replacement, and let the reconcile immutability guard catch
// drift hidden behind an unresolved key.
diff: Effect.fn(function* ({ olds, news }) {
const immutableKeys = [
"componentName",
"semanticVersion",
"platform",
"data",
"uri",
"description",
"changeDescription",
"supportedOsVersions",
"kmsKeyId",
] as const;
if (immutableVersionKeysChanged(olds, news, immutableKeys)) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const arn =
output?.componentBuildVersionArn ??
(yield* toBuildVersionArn(yield* toName(id, olds), toVersion(olds)));
const component = yield* getComponent(arn);
if (component === undefined) return undefined;
const attrs = yield* toAttrs(component);
const tags = toTagRecord(component.tags);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
// One idempotency token per reconcile — retries within this run
// are deduplicated by the API.
const clientToken = yield* Effect.sync(() => crypto.randomUUID());
if ((news.data === undefined) === (news.uri === undefined)) {
return yield* new ComponentSourceInvalid({
message:
"Specify exactly one of `data` (inline YAML) or `uri` (S3 object) for an Image Builder component",
});
}
const name = output?.componentName ?? (yield* toName(id, news));
const version = output?.semanticVersion ?? toVersion(news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news.tags };
// 1. Observe — cloud state is authoritative; output only caches
// the build-version ARN.
const arn = output?.componentBuildVersionArn ?? (yield* toBuildVersionArn(name, version));
let observed = yield* getComponent(arn);
// Immutability guard — the version already exists in the cloud
// with a different document. It cannot be converged in place; the
// user must bump `semanticVersion` (which replaces the component).
if (observed !== undefined && news.data !== undefined && observed.data !== news.data) {
return yield* new ComponentVersionImmutable({
message: `Image Builder component '${name}' version '${version}' already exists with a different document — bump semanticVersion to publish the change`,
});
}
// 2. Ensure — components are immutable, so a missing component is
// the only create path. A same-name/version conflict (race or
// an unbumped document change on a fixed name) surfaces as the
// API's typed error.
if (observed === undefined) {
const created = yield* imagebuilder.createComponent({
name,
semanticVersion: version,
platform: news.platform,
data: news.data,
uri: news.uri,
description: news.description,
changeDescription: news.changeDescription,
supportedOsVersions: news.supportedOsVersions,
kmsKeyId: news.kmsKeyId,
tags: desiredTags,
clientToken,
});
if (!created.componentBuildVersionArn) {
return yield* new ComponentUnexpectedResponse({
message: "CreateComponent returned no componentBuildVersionArn",
});
}
observed = yield* getComponent(created.componentBuildVersionArn);
if (observed === undefined) {
return yield* new ComponentUnexpectedResponse({
message: `created Image Builder component '${name}' is not readable`,
});
}
}
// 3. Sync — tags are the only mutable aspect; diff against
// OBSERVED cloud tags.
if (observed.arn) {
yield* syncImageBuilderTags(observed.arn, desiredTags);
}
// 4. Return fresh attributes.
yield* session.note(name);
return yield* toAttrs(observed);
}),
delete: Effect.fn(function* ({ output }) {
yield* retryWhileDependedOn(
imagebuilder.deleteComponent({
componentBuildVersionArn: output.componentBuildVersionArn,
}),
).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
list: () =>
imagebuilder.listComponents.pages({ owner: "Self" }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.componentVersionList ?? []).filter(
(
version,
): version is imagebuilder.ComponentVersion & {
arn: string;
} => version.arn !== undefined,
),
),
),
Effect.flatMap(
Effect.forEach(
(version) =>
imagebuilder
.listComponentBuildVersions({
componentVersionArn: version.arn,
})
.pipe(
Effect.map((response) =>
(response.componentSummaryList ?? []).filter(
(
summary,
): summary is imagebuilder.ComponentSummary & {
arn: string;
name: string;
version: string;
} =>
summary.arn !== undefined &&
summary.name !== undefined &&
summary.version !== undefined,
),
),
// Tolerate a delete race — drop the version.
Effect.catchTag("ResourceNotFoundException", () => Effect.succeed([])),
),
{ concurrency: 4 },
),
),
Effect.map((groups) =>
groups.flat().map((summary) => ({
componentName: summary.name,
componentBuildVersionArn: summary.arn,
semanticVersion: summary.version,
platform: summary.platform ?? "",
type: summary.type,
dateCreated: summary.dateCreated,
})),
),
),
};
}),
);