import * as imagebuilder from "@distilled.cloud/aws/imagebuilder";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireMinutes } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
deleteImageBuilderLogGroup,
driftedFrom,
imageBuilderArn,
retryWhileDependedOn,
syncImageBuilderTags,
toTagRecord,
} from "./internal.ts";
export class ImagePipelineUnexpectedResponse extends Data.TaggedError(
"ImagePipelineUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
/**
* Image test settings applied to builds of the pipeline. Mirrors the wire
* `ImageTestsConfiguration`, with the timeout expressed as a
* {@link Duration.Input} instead of raw minutes.
*/
export interface ImageTestsConfiguration {
/**
* Whether to run tests on the output image.
* @default true
*/
imageTestsEnabled?: boolean;
/**
* Maximum time tests may run before they are considered failed
* (e.g. `"90 minutes"`). AWS accepts 1 hour to 24 hours, in whole
* minutes on the wire.
* @default "12 hours"
*/
timeout?: Duration.Input;
}
/** Convert the duration-typed test settings to the wire shape. */
const toWireImageTests = (
config: ImageTestsConfiguration | undefined,
): imagebuilder.ImageTestsConfiguration | undefined =>
config === undefined
? undefined
: {
imageTestsEnabled: config.imageTestsEnabled,
timeoutMinutes: toWireMinutes(config.timeout),
};
export interface ImagePipelineProps {
/**
* Name of the image pipeline. If omitted, a deterministic physical name
* is generated. Changing the name replaces the pipeline.
*/
imagePipelineName?: string;
/**
* ARN of the image recipe that the pipeline builds. Exactly one of
* `imageRecipeArn` / `containerRecipeArn` is required.
*/
imageRecipeArn?: string;
/**
* ARN of the container recipe that the pipeline builds.
*/
containerRecipeArn?: string;
/**
* ARN of the infrastructure configuration used to build images.
*/
infrastructureConfigurationArn: string;
/**
* ARN of the distribution configuration applied to output images.
*/
distributionConfigurationArn?: string;
/**
* Description of the pipeline.
*/
description?: string;
/**
* Image test settings (enable/disable tests, timeout).
*/
imageTestsConfiguration?: ImageTestsConfiguration;
/**
* Collect additional information about the image being created,
* including the operating system and packages.
* @default true
*/
enhancedImageMetadataEnabled?: boolean;
/**
* Build schedule (cron expression + start condition). Without a
* schedule the pipeline only builds on manual invocation.
*/
schedule?: imagebuilder.Schedule;
/**
* Whether the pipeline schedule is active.
* @default "ENABLED"
*/
status?: "ENABLED" | "DISABLED";
/**
* Image scanning (Amazon Inspector) settings for output images.
*/
imageScanningConfiguration?: imagebuilder.ImageScanningConfiguration;
/**
* Custom build/test workflows to run.
*/
workflows?: imagebuilder.WorkflowConfiguration[];
/**
* IAM role (name or ARN) that Image Builder assumes to run workflows.
*/
executionRole?: string;
/**
* User-defined tags for the pipeline.
*/
tags?: Record<string, string>;
}
export interface ImagePipeline extends Resource<
"AWS.ImageBuilder.ImagePipeline",
ImagePipelineProps,
{
/** The name of the image pipeline. */
imagePipelineName: string;
/** The ARN of the image pipeline. */
imagePipelineArn: string;
/** The OS platform of the pipeline's recipe (`Linux` / `Windows`). */
platform: string | undefined;
/** Whether the pipeline is `ENABLED` or `DISABLED`. */
status: string | undefined;
/** When the pipeline was created. */
dateCreated: string | undefined;
},
never,
Providers
> {}
/**
* An EC2 Image Builder image pipeline — wires a recipe to an infrastructure
* configuration (and optionally a distribution configuration) and automates
* image builds on a schedule or on demand.
*
* Creating the pipeline does not start a build; builds start on the
* configured schedule or when explicitly invoked.
* ### Creating an Image Pipeline
* **Example:** Manual-Only Pipeline
* ```typescript
* const pipeline = yield* ImageBuilder.ImagePipeline("Pipeline", {
* imageRecipeArn: recipe.imageRecipeArn,
* infrastructureConfigurationArn: infra.infrastructureConfigurationArn,
* status: "DISABLED",
* });
* ```
*
* **Example:** Scheduled Pipeline with Distribution
* ```typescript
* const pipeline = yield* ImageBuilder.ImagePipeline("Nightly", {
* imageRecipeArn: recipe.imageRecipeArn,
* infrastructureConfigurationArn: infra.infrastructureConfigurationArn,
* distributionConfigurationArn: distribution.distributionConfigurationArn,
* schedule: {
* scheduleExpression: "cron(0 9 * * ? *)",
* pipelineExecutionStartCondition:
* "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE",
* },
* });
* ```
*
* @resource
*/
export const ImagePipeline = Resource<ImagePipeline>("AWS.ImageBuilder.ImagePipeline");
export const ImagePipelineProvider = () =>
Provider.effect(
ImagePipeline,
Effect.gen(function* () {
const toName = (id: string, props: ImagePipelineProps) =>
props.imagePipelineName
? Effect.succeed(props.imagePipelineName)
: createPhysicalName({ id, maxLength: 126 });
const toArn = (name: string) => imageBuilderArn("image-pipeline", name);
const getPipeline = Effect.fn(function* (arn: string) {
const response = yield* imagebuilder
.getImagePipeline({ imagePipelineArn: arn })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
return response?.imagePipeline;
});
const toAttrs = Effect.fn(function* (pipeline: imagebuilder.ImagePipeline) {
if (!pipeline.arn || !pipeline.name) {
return yield* new ImagePipelineUnexpectedResponse({
message: "Image Builder image pipeline is missing its ARN or name",
});
}
return {
imagePipelineName: pipeline.name,
imagePipelineArn: pipeline.arn,
platform: pipeline.platform,
status: pipeline.status,
dateCreated: pipeline.dateCreated,
};
});
/** Mutable aspects synced by a full-PUT update. */
const mutableKeys = [
"description",
"imageRecipeArn",
"containerRecipeArn",
"infrastructureConfigurationArn",
"distributionConfigurationArn",
"imageTestsConfiguration",
"enhancedImageMetadataEnabled",
"schedule",
"status",
"imageScanningConfiguration",
"workflows",
"executionRole",
] as const;
return {
stables: ["imagePipelineName", "imagePipelineArn"],
diff: Effect.fn(function* ({ id, olds, news }) {
if (!isResolved(news)) return undefined;
if ((yield* toName(id, olds)) !== (yield* toName(id, news))) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const arn = output?.imagePipelineArn ?? (yield* toArn(yield* toName(id, olds)));
const pipeline = yield* getPipeline(arn);
if (pipeline === undefined) return undefined;
const attrs = yield* toAttrs(pipeline);
const tags = toTagRecord(pipeline.tags);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, olds, output, session }) {
// One idempotency token per reconcile — retries within this run
// are deduplicated by the API.
const clientToken = yield* Effect.sync(() => crypto.randomUUID());
const name = output?.imagePipelineName ?? (yield* toName(id, news));
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news.tags };
// Desired state in wire shape (Duration timeout → whole minutes)
// so create/update/drift all compare like against like.
const desired = {
...news,
imageTestsConfiguration: toWireImageTests(news.imageTestsConfiguration),
};
// 1. Observe.
const arn = output?.imagePipelineArn ?? (yield* toArn(name));
let observed = yield* getPipeline(arn);
// 2. Ensure — create if missing; tolerate an AlreadyExists race.
if (observed === undefined) {
const created = yield* imagebuilder
.createImagePipeline({
name,
description: news.description,
imageRecipeArn: news.imageRecipeArn,
containerRecipeArn: news.containerRecipeArn,
infrastructureConfigurationArn: news.infrastructureConfigurationArn,
distributionConfigurationArn: news.distributionConfigurationArn,
imageTestsConfiguration: desired.imageTestsConfiguration,
enhancedImageMetadataEnabled: news.enhancedImageMetadataEnabled,
schedule: news.schedule,
status: news.status,
imageScanningConfiguration: news.imageScanningConfiguration,
workflows: news.workflows,
executionRole: news.executionRole,
tags: desiredTags,
clientToken,
})
.pipe(Effect.catchTag("ResourceAlreadyExistsException", () => Effect.undefined));
observed = yield* getPipeline(created?.imagePipelineArn ?? arn);
if (observed === undefined) {
return yield* new ImagePipelineUnexpectedResponse({
message: `created Image Builder pipeline '${name}' is not readable`,
});
}
}
// 3. Sync — compare OBSERVED cloud state against the desired
// props; a full-PUT update converges any drift (`olds` is only
// a hint for removed props).
const drifted = mutableKeys.some(
(key) =>
driftedFrom(observed?.[key], desired[key]) ||
(desired[key] === undefined && olds?.[key] !== undefined),
);
if (drifted && observed.arn) {
yield* imagebuilder.updateImagePipeline({
imagePipelineArn: observed.arn,
description: news.description,
imageRecipeArn: news.imageRecipeArn,
containerRecipeArn: news.containerRecipeArn,
infrastructureConfigurationArn: news.infrastructureConfigurationArn,
distributionConfigurationArn: news.distributionConfigurationArn,
imageTestsConfiguration: desired.imageTestsConfiguration,
enhancedImageMetadataEnabled: news.enhancedImageMetadataEnabled,
schedule: news.schedule,
status: news.status,
imageScanningConfiguration: news.imageScanningConfiguration,
workflows: news.workflows,
executionRole: news.executionRole,
clientToken,
});
observed = (yield* getPipeline(observed.arn)) ?? observed;
}
// 3b. Sync tags — 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.deleteImagePipeline({
imagePipelineArn: output.imagePipelineArn,
}),
).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
// Image Builder creates this fixed group outside of the pipeline
// API. Delete only the exact group derived from this owned output,
// and only after the pipeline itself is observed absent.
for (let attempt = 0; attempt < 30; attempt++) {
if ((yield* getPipeline(output.imagePipelineArn)) === undefined) {
yield* deleteImageBuilderLogGroup(
`/aws/imagebuilder/pipeline/${output.imagePipelineName.toLowerCase()}`,
);
return;
}
yield* Effect.sleep("1 second");
}
return yield* Effect.die(
new Error(
`Image Builder pipeline ${output.imagePipelineArn} remained observable 30 seconds after delete`,
),
);
}),
list: () =>
imagebuilder.listImagePipelines.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.imagePipelineList ?? []).filter(
(
pipeline,
): pipeline is imagebuilder.ImagePipeline & {
arn: string;
name: string;
} => pipeline.arn !== undefined && pipeline.name !== undefined,
),
),
),
Effect.map((pipelines) =>
pipelines.map((pipeline) => ({
imagePipelineName: pipeline.name,
imagePipelineArn: pipeline.arn,
platform: pipeline.platform,
status: pipeline.status,
dateCreated: pipeline.dateCreated,
})),
),
),
};
}),
);