import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
import * as ecr from "@distilled.cloud/aws/ecr";
import * as ecs from "@distilled.cloud/aws/ecs";
import * as iam from "@distilled.cloud/aws/iam";
import { Region } from "@distilled.cloud/aws/Region";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import { Platform, type Main, type PlatformProps, type PlatformServices } from "alchemy/Platform";
import * as Provider from "alchemy/Provider";
import { Resource, type ResourceBinding } from "alchemy/Resource";
import {
createContainerRuntimeContext,
type HostRuntimeContext,
type ServerHost,
} from "alchemy/Runtime/Process";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import { Stack } from "alchemy/Stack";
import { createInternalTags, createTagsList, diffTags, hasTags } from "alchemy/Tags";
import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import type { Scope } from "effect/Scope";
import * as Stream from "effect/Stream";
import type { Credentials } from "../Credentials.ts";
import {
makeBunBootstrap,
makeImageSource,
type BundledImageSource,
type DockerfileImageSource,
type ImageSourceLike,
type RegistryImageSource,
} from "../ECR/ImageSource.ts";
import { AWSEnvironment } from "../Environment.ts";
import type { PolicyStatement } from "../IAM/Policy.ts";
import { syncLogGroupRetention, type LogRetentionConfig } from "../Logs/LogRetention.ts";
import type { Providers } from "../Providers.ts";
export class TaskConflict extends Data.TaggedError("TaskConflict")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export const isTask = (value: any): value is Task =>
typeof value === "object" && value !== null && "Type" in value && value.Type === "AWS.ECS.Task";
export class TaskEnvironment extends Context.Service<TaskEnvironment, Record<string, any>>()(
"AWS.ECS.TaskEnvironment",
) {}
/**
* The binding contract shared by the ECS container platforms (`Task` and the
* image-owning `Service`): env vars and IAM policy statements land on the
* task role, plus task-level volumes/mount points requested through the
* binding channel (e.g. `EFS.Mount`).
*/
export interface TaskBindingContract {
/** Environment variables injected into the task's containers. */
env?: Record<string, any>;
/** IAM policy statements attached to the task role. */
policyStatements?: PolicyStatement[];
/**
* Task-level volumes requested through the binding channel (e.g.
* `EFS.Mount`). Merged with the resource's own `volumes` prop.
*/
volumes?: ecs.Volume[];
/**
* Container mount points for binding-requested volumes, applied to the
* primary container.
*/
mountPoints?: ecs.MountPoint[];
}
/**
* Task-definition configuration shared by `AWS.ECS.Task` and the
* image-owning form of `AWS.ECS.Service` (which synthesizes its own task
* definition from the same surface).
*/
export interface TaskDefinitionConfig {
/**
* Task-level cpu configuration for Fargate.
* @default 256
*/
cpu?: number;
/**
* Task-level memory configuration for Fargate.
* @default 512
*/
memory?: number;
/**
* HTTP port exposed by the container.
*/
port?: number;
/**
* Additional environment variables for the container.
*/
env?: Record<string, any>;
/**
* Environment files to load into the primary container, e.g. `.env`
* objects stored in S3:
* `[{ value: "arn:aws:s3:::my-bucket/app.env", type: "s3" }]`.
*
* Variables from `env` (and the container's own `environment`) take
* precedence over values loaded from environment files. The execution
* role is automatically granted `s3:GetObject` on the referenced objects
* and `s3:GetBucketLocation` on their buckets.
*/
environmentFiles?: ecs.EnvironmentFile[];
/**
* Command override for the primary container (Docker `CMD`).
*/
command?: string[];
/**
* Container definition overrides applied after Alchemy's defaults for the
* primary container.
*/
container?: Partial<ecs.ContainerDefinition>;
/**
* Retention for the task's CloudWatch log group, e.g.
* `{ retention: "2 weeks" }` or `{ retention: "forever" }`.
*/
logging?: LogRetentionConfig;
/**
* Additional sidecar containers appended to the task definition after the
* primary container. Each entry is a full, typed
* {@link ecs.ContainerDefinition} (image URIs supplied by the user, e.g.
* from an `ECR.Image` or an external registry).
*
* Use this to declare multi-container tasks: log routers (firelens),
* proxies (Envoy/App Mesh), metric agents (otel/cloudwatch), or any
* companion process that shares the task's network namespace.
*/
sidecars?: ecs.ContainerDefinition[];
/**
* Task definition network mode.
* @default "awsvpc"
*/
networkMode?: ecs.NetworkMode;
/**
* Launch-type compatibilities the task definition must support.
* @default ["FARGATE"]
*/
requiresCompatibilities?: ecs.Compatibility[];
/**
* Task-level data volumes (host / docker / EFS / FSx Windows / S3 /
* configured-at-launch). Containers reference these via `mountPoints`.
*/
volumes?: ecs.Volume[];
/**
* Task definition placement constraints (`memberOf` expressions). Only
* applies to EC2/EXTERNAL launch types.
*/
placementConstraints?: ecs.TaskDefinitionPlacementConstraint[];
/**
* CPU architecture and operating-system family the task runs on, e.g.
* `{ cpuArchitecture: "ARM64", operatingSystemFamily: "LINUX" }`.
*/
runtimePlatform?: ecs.RuntimePlatform;
/**
* Amount of ephemeral storage (in GiB) to allocate for the task on Fargate.
*/
ephemeralStorage?: ecs.EphemeralStorage;
/**
* IPC resource namespace to use for the containers in the task.
*/
ipcMode?: ecs.IpcMode;
/**
* Process namespace to use for the containers in the task.
*/
pidMode?: ecs.PidMode;
/**
* App Mesh proxy configuration.
*/
proxyConfiguration?: ecs.ProxyConfiguration;
/**
* Elastic Inference accelerators to attach to the task.
*/
inferenceAccelerators?: ecs.InferenceAccelerator[];
/**
* Whether to enable AWS Fault Injection (FIS) actions on the task.
* @default false
*/
enableFaultInjection?: boolean;
/**
* Additional task definition overrides applied last (escape hatch for
* fields not yet surfaced as first-class props).
*/
taskDefinition?: Partial<
Omit<
ecs.RegisterTaskDefinitionRequest,
"family" | "containerDefinitions" | "executionRoleArn" | "taskRoleArn" | "cpu" | "memory"
>
>;
/**
* Additional managed policy ARNs for the task role.
*/
taskRoleManagedPolicyArns?: string[];
/**
* Additional managed policy ARNs for the execution role.
*/
executionRoleManagedPolicyArns?: string[];
}
export interface TaskPropsBase extends PlatformProps, TaskDefinitionConfig {
/**
* ECS task family. If omitted, a unique family is generated.
*/
taskName?: string;
/**
* User-defined tags to apply to task-owned resources.
*/
tags?: Record<string, string>;
}
/**
* Bundle an inline Effect program (`main`) into a generated image whose
* environment comes from `image`, `dockerfile`, or the default bun base.
*/
export interface BundledTaskProps extends TaskPropsBase, BundledImageSource {}
/**
* Build the user's own Dockerfile (`context` + optional `dockerfile` path)
* into the task image.
*/
export interface DockerfileTaskProps extends TaskPropsBase, DockerfileImageSource {}
/**
* Run a pre-built registry image (`image`), mirrored into ECR.
*/
export interface ImageTaskProps extends TaskPropsBase, RegistryImageSource {}
/**
* Task props — the image comes from exactly one of three sources, flat on
* the props: `main` (bundled Effect program), `context` (user Dockerfile),
* or `image` (registry reference).
*/
export type TaskProps = BundledTaskProps | DockerfileTaskProps | ImageTaskProps;
export interface Task extends Resource<
"AWS.ECS.Task",
TaskProps,
{
/** The ARN of the registered task definition revision. */
taskDefinitionArn: string;
/** The task definition family name. */
taskFamily: string;
/** The name of the main container in the task definition. */
containerName: string;
/** The container port the task listens on. */
port: number;
/** The full URI of the container image the task runs. */
imageUri: string;
/** The name of the ECR repository holding the built image. */
repositoryName: string;
/** The URI of the ECR repository holding the built image. */
repositoryUri: string;
/** The ARN of the task role assumed by the running containers. */
taskRoleArn: string;
/** The name of the task role. */
taskRoleName: string;
/** The ARN of the execution role used to pull images and write logs. */
executionRoleArn: string;
/** The name of the execution role. */
executionRoleName: string;
/** The CloudWatch log group the task writes to. */
logGroupName: string;
/** The ARN of the CloudWatch log group. */
logGroupArn: string;
/** The content hash of the task's container image. */
code: {
/** The content hash of the task's container image. */
hash: string;
};
},
TaskBindingContract,
Providers
> {}
export type TaskServices = Credentials | Region | ServerHost | AWSEnvironment;
/**
* The impl shape for an effectful `Task`: a `run` entry that executes to
* completion when the container starts, and/or a `fetch` HTTP handler for
* tasks deployed as servers (e.g. referenced by an `ECS.Service`).
*/
export type TaskShape =
| void
| (Exclude<Main<TaskServices>, void> & {
/**
* Runs to completion when the container starts, after which the
* container exits.
*/
run?: Effect.Effect<void, never, TaskServices | PlatformServices | RuntimeContext | Scope>;
});
export interface TaskRuntimeContext extends HostRuntimeContext {
readonly Type: "AWS.ECS.Task";
}
// Shared with `Docker.Service`; lives beside the host runtime context.
export { createContainerRuntimeContext } from "alchemy/Runtime/Process";
/**
* A Fargate task definition with a container image from one of three
* sources, declared flat on the props:
*
* - `main` — bundle an inline Effect program into a generated image
* (compose with `image` or an inline `dockerfile` to pick the
* environment; defaults to `oven/bun:1`).
* - `context` — build your own Dockerfile (`dockerfile` is a path relative
* to the cwd, defaulting to `${context}/Dockerfile`).
* - `image` — run a pre-built registry image, mirrored into ECR.
*
* `Task` provisions task + execution IAM roles, a CloudWatch log group, and
* an ECR repository holding the built (or mirrored) image, then registers a
* Fargate task definition. Each reconcile registers a new immutable
* revision. A launched task runs until its process exits — it is the target
* of `AWS.ECS.RunTask` / `StopTask` bindings and `AWS.ECS.Schedule`;
* effectful impls return `{ run }`, executed to completion when the
* container starts.
*
* Beyond the primary container you can declare task-level configuration
* (volumes, runtime platform, ephemeral storage, IPC/PID mode, placement
* constraints) and append additional `sidecars` for multi-container tasks.
* ### Creating a Task
* **Example:** Remote Image
* ```typescript
* const migrate = yield* Task("DbMigrate", {
* image: "public.ecr.aws/docker/library/busybox:stable",
* command: ["sh", "-c", "echo done"],
* cpu: 256,
* memory: 512,
* });
* ```
*
* **Example:** Build Your Own Dockerfile
* ```typescript
* const render = yield* Task("RenderJob", {
* context: "./render", // dockerfile defaults to ./render/Dockerfile
* dockerfile: "./render/Dockerfile.gpu", // always a PATH
* cpu: 1024,
* memory: 4096,
* });
* ```
*
* **Example:** Build args and secrets
* ```typescript
* // Dockerfile:
* // ARG NODE_ENV
* // RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci
* const api = yield* Task("Api", {
* context: "./api",
* build: {
* args: { NODE_ENV: "production" },
* // Mounted only into the RUN step that asks for it; never in the image.
* secrets: { NPM_TOKEN: Config.Redacted("NPM_TOKEN") },
* },
* cpu: 256,
* memory: 512,
* });
* ```
*
* **Example:** Inline Effect Program
* ```typescript
* const drainer = yield* Task(
* "QueueDrainer",
* { main: import.meta.url, image: "oven/bun:1", cpu: 256, memory: 512 },
* Effect.gen(function* () {
* const receive = yield* AWS.SQS.ReceiveMessage(queue);
* return {
* run: Effect.gen(function* () {
* // runs to completion, then the container exits
* const batch = yield* receive({ MaxNumberOfMessages: 10 });
* }),
* };
* }),
* );
* ```
*
* ### Multi-Container Tasks
* **Example:** Task with a Sidecar
* ```typescript
* const task = yield* Task("ApiTask", {
* main: import.meta.url,
* port: 3000,
* sidecars: [
* {
* name: "otel-collector",
* image: "public.ecr.aws/aws-observability/aws-otel-collector:latest",
* essential: false,
* portMappings: [{ containerPort: 4317, protocol: "tcp" }],
* },
* ],
* });
* ```
*
* ### Bundling & Tree-shaking
* `main` is bundled with rolldown at deploy time. Unused code is
* tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
* pure so unused parts prune more aggressively. Your app is not
* marked pure.
*
* **Example:** Mark additional packages as pure
* Only list packages with no top-level side effects.
* ```typescript
* {
* main: import.meta.url,
* build: {
* pure: { packages: ["my-lib", "@my-scope/*"] },
* },
* }
* ```
*
* **Example:** Turn it off
* ```typescript
* {
* main: import.meta.url,
* build: { pure: false },
* }
* ```
*
* ### Task-Level Configuration
* **Example:** ARM64 with EFS Volume and Ephemeral Storage
* ```typescript
* const task = yield* Task("WorkerTask", {
* main: import.meta.url,
* runtimePlatform: { cpuArchitecture: "ARM64", operatingSystemFamily: "LINUX" },
* ephemeralStorage: { sizeInGiB: 40 },
* volumes: [
* {
* name: "data",
* efsVolumeConfiguration: { fileSystemId: fileSystem.fileSystemId },
* },
* ],
* container: {
* mountPoints: [{ sourceVolume: "data", containerPath: "/data" }],
* },
* });
* ```
*
* **Example:** Environment Files from S3
* ```typescript
* const task = yield* Task("ApiTask", {
* main: import.meta.url,
* environmentFiles: [
* { value: "arn:aws:s3:::my-config-bucket/app.env", type: "s3" },
* ],
* });
* ```
*
* @resource
*/
export const Task: Platform<Task, TaskServices, TaskShape, TaskRuntimeContext> = Platform(
"AWS.ECS.Task",
{
createRuntimeContext: createContainerRuntimeContext("AWS.ECS.Task") as (
id: string,
) => TaskRuntimeContext,
},
);
/** Docker build platform matching the task definition's declared runtime. */
export const taskImagePlatform = (runtimePlatform?: ecs.RuntimePlatform) =>
// Build for the architecture the task definition declares (Fargate
// defaults to X86_64 when `runtimePlatform` is unset). Without this, an
// image built on an ARM64 host (e.g. Apple Silicon) is rejected at task
// start with `image Manifest does not contain descriptor matching
// platform 'linux/amd64'`.
runtimePlatform?.cpuArchitecture === "ARM64" ? "linux/arm64" : "linux/amd64";
/** Keep image resolution, drift detection and dev watching on the same inputs. */
export const taskImageInput = (props: TaskProps) => {
const source = props as ImageSourceLike;
return {
source,
platform: taskImagePlatform(props.runtimePlatform),
port: props.port,
isExternal: props.isExternal,
bootstrap: makeBunBootstrap(source.handler ?? "default"),
};
};
/**
* Create the IAM role assumed by ECS tasks if it doesn't already exist.
* Idempotent: an `EntityAlreadyExistsException` adopts the existing role
* only when it carries our internal tags.
*/
export const createTaskRoleIfNotExists = Effect.fn(function* ({
id,
roleName,
}: {
id: string;
roleName: string;
}) {
const tags = yield* createInternalTags(id);
const role = yield* iam
.createRole({
RoleName: roleName,
AssumeRolePolicyDocument: JSON.stringify({
Version: "2012-10-17",
Statement: [
{
Effect: "Allow",
Principal: {
Service: "ecs-tasks.amazonaws.com",
},
Action: "sts:AssumeRole",
},
],
}),
Tags: createTagsList(tags),
})
.pipe(
Effect.catchTag("EntityAlreadyExistsException", () =>
iam.getRole({ RoleName: roleName }).pipe(
Effect.filterOrFail(
(existing) => hasTags(tags, existing.Role?.Tags),
() =>
new TaskConflict({
message: `Role '${roleName}' already exists and is not managed by alchemy`,
}),
),
),
),
);
return role.Role!.Arn!;
});
/**
* Ensure the ECS execution role exists with the standard execution policy
* (plus any additional managed policies) attached.
*/
export const ensureTaskExecutionRole = Effect.fn(function* ({
id,
roleName,
managedPolicyArns,
}: {
id: string;
roleName: string;
managedPolicyArns?: string[];
}) {
const roleArn = yield* createTaskRoleIfNotExists({ id, roleName });
const policies = [
"arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy",
...(managedPolicyArns ?? []),
];
for (const policyArn of policies) {
yield* iam
.attachRolePolicy({
RoleName: roleName,
PolicyArn: policyArn,
})
.pipe(Effect.catchTag("LimitExceededException", () => Effect.void));
}
return roleArn;
});
/** Inline policy granting the execution role read access to `environmentFiles`. */
const ENVIRONMENT_FILES_POLICY_NAME = "alchemy-environment-files";
/**
* Sync the execution role's read access to the S3 `environmentFiles`: put
* an inline policy granting `s3:GetObject` on the referenced objects (and
* `s3:GetBucketLocation` on their buckets), or delete the policy when no
* environment files are configured.
*/
export const syncEnvironmentFilesPolicy = Effect.fn(function* ({
roleName,
environmentFiles,
}: {
roleName: string;
environmentFiles: ecs.EnvironmentFile[] | undefined;
}) {
const objectArns = (environmentFiles ?? [])
.filter((file) => file.type === "s3")
.map((file) => file.value);
if (objectArns.length === 0) {
yield* iam
.deleteRolePolicy({
RoleName: roleName,
PolicyName: ENVIRONMENT_FILES_POLICY_NAME,
})
.pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
return;
}
const bucketArns = [...new Set(objectArns.map((arn) => arn.split("/")[0]))];
yield* iam.putRolePolicy({
RoleName: roleName,
PolicyName: ENVIRONMENT_FILES_POLICY_NAME,
PolicyDocument: JSON.stringify({
Version: "2012-10-17",
Statement: [
{
Effect: "Allow",
Action: ["s3:GetObject"],
Resource: objectArns,
},
{
Effect: "Allow",
Action: ["s3:GetBucketLocation"],
Resource: bucketArns,
},
],
}),
});
});
/** Ensure the CloudWatch log group the task writes to exists. */
export const ensureTaskLogGroup = Effect.fn(function* ({
id,
logGroupName,
}: {
id: string;
logGroupName: string;
}) {
const { accountId, region } = yield* AWSEnvironment.current;
const tags = yield* createInternalTags(id);
yield* logs
.createLogGroup({
logGroupName,
tags,
})
.pipe(Effect.catchTag("ResourceAlreadyExistsException", () => Effect.void));
return `arn:aws:logs:${region}:${accountId}:log-group:${logGroupName}`;
});
/**
* Apply the binding channel to the task role: collect env vars, put (or
* clear) the inline policy from bound policy statements, and dedupe
* binding-requested volumes/mount points.
*/
export const attachTaskBindings = Effect.fn(function* ({
roleName,
policyName,
bindings,
}: {
roleName: string;
policyName: string;
bindings: ResourceBinding<TaskBindingContract>[];
}) {
const activeBindings = bindings.filter(
(binding: ResourceBinding<TaskBindingContract> & { action?: string }) =>
binding.action !== "delete",
);
const env = activeBindings
.map((binding) => binding?.data?.env)
.reduce((acc, value) => ({ ...acc, ...value }), {});
const policyStatements = activeBindings.flatMap(
(binding) =>
binding?.data?.policyStatements?.map((statement) => ({
...statement,
Sid: statement.Sid?.replace(/[^A-Za-z0-9]+/gi, ""),
})) ?? [],
);
// Volumes/mount points requested through the binding channel (e.g.
// `EFS.Mount`) — deduped by volume name / container path; merged
// with the `volumes` prop and primary container in `reconcile`.
const volumes = [
...new Map(
activeBindings
.flatMap((binding) => binding?.data?.volumes ?? [])
.map((volume) => [volume.name, volume] as const),
).values(),
];
const mountPoints = [
...new Map(
activeBindings
.flatMap((binding) => binding?.data?.mountPoints ?? [])
.map((point) => [point.containerPath, point] as const),
).values(),
];
if (policyStatements.length > 0) {
yield* iam.putRolePolicy({
RoleName: roleName,
PolicyName: policyName,
PolicyDocument: JSON.stringify({
Version: "2012-10-17",
Statement: policyStatements,
}),
});
} else {
yield* iam
.deleteRolePolicy({
RoleName: roleName,
PolicyName: policyName,
})
.pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
}
return { env, volumes, mountPoints };
});
/**
* Register a new task definition revision from the shared
* {@link TaskDefinitionConfig} surface.
*/
export const registerTaskDefinitionRevision = Effect.fn(function* ({
props,
family,
imageUri,
taskRoleArn,
executionRoleArn,
logGroupName,
tags,
bindingVolumes = [],
bindingMountPoints = [],
}: {
props: TaskDefinitionConfig;
family: string;
imageUri: string;
taskRoleArn: string;
executionRoleArn: string;
logGroupName: string;
tags: Record<string, string>;
/** Task-level volumes requested through the binding channel. */
bindingVolumes?: ecs.Volume[];
/** Primary-container mount points for binding-requested volumes. */
bindingMountPoints?: ecs.MountPoint[];
}) {
const { region } = yield* AWSEnvironment.current;
const containerName = props.container?.name ?? family;
const primaryContainer: ecs.ContainerDefinition = {
essential: true,
name: containerName,
image: imageUri,
command: props.command,
portMappings:
props.port !== undefined
? [
{
containerPort: props.port,
hostPort: props.port,
protocol: "tcp",
},
]
: undefined,
environment: Object.entries(props.env ?? {}).map(([name, value]) => ({
name,
value: typeof value === "string" ? value : JSON.stringify(value),
})),
environmentFiles: props.environmentFiles,
logConfiguration: {
logDriver: "awslogs",
options: {
"awslogs-group": logGroupName,
"awslogs-region": region,
"awslogs-stream-prefix": family,
},
},
...props.container,
// Merge binding-requested mount points (e.g. `EFS.Mount`) with any
// the user configured on the primary container.
...(bindingMountPoints.length > 0
? {
mountPoints: [...(props.container?.mountPoints ?? []), ...bindingMountPoints],
}
: {}),
};
const response = yield* ecs.registerTaskDefinition({
family,
taskRoleArn,
executionRoleArn,
networkMode: props.networkMode ?? "awsvpc",
requiresCompatibilities: props.requiresCompatibilities ?? ["FARGATE"],
cpu: String(props.cpu ?? 256),
memory: String(props.memory ?? 512),
volumes:
bindingVolumes.length > 0 ? [...(props.volumes ?? []), ...bindingVolumes] : props.volumes,
placementConstraints: props.placementConstraints,
runtimePlatform: props.runtimePlatform,
ephemeralStorage: props.ephemeralStorage,
ipcMode: props.ipcMode,
pidMode: props.pidMode,
proxyConfiguration: props.proxyConfiguration,
inferenceAccelerators: props.inferenceAccelerators,
enableFaultInjection: props.enableFaultInjection,
...props.taskDefinition,
containerDefinitions: [primaryContainer, ...(props.sidecars ?? [])],
tags: Object.entries(tags).map(([key, value]) => ({ key, value })),
});
const taskDefinition = response.taskDefinition;
if (!taskDefinition?.taskDefinitionArn) {
return yield* Effect.die(new Error("registerTaskDefinition returned no task definition"));
}
return taskDefinition;
});
/**
* Sync tags on a task definition revision: diff observed revision tags
* against desired and apply the delta.
*/
export const syncTaskDefinitionTags = Effect.fn(function* ({
revisionArn,
tags,
}: {
revisionArn: string;
tags: Record<string, string>;
}) {
const observedTags = Object.fromEntries(
(
(yield* ecs
.listTagsForResource({ resourceArn: revisionArn })
.pipe(
Effect.catchTag("ClientException", () =>
Effect.succeed({ tags: undefined } as { tags?: ecs.Tag[] }),
),
)).tags ?? []
)
.filter(
(t): t is { key: string; value: string } =>
typeof t.key === "string" && typeof t.value === "string",
)
.map((t) => [t.key, t.value]),
);
const { removed: removedTags, upsert: upsertTags } = diffTags(observedTags, tags);
if (upsertTags.length > 0) {
yield* ecs.tagResource({
resourceArn: revisionArn,
tags: upsertTags.map((t) => ({ key: t.Key, value: t.Value })),
});
}
if (removedTags.length > 0) {
yield* ecs.untagResource({
resourceArn: revisionArn,
tagKeys: removedTags,
});
}
});
/** The family segment of a task definition revision ARN (`…:task-definition/<family>:<revision>`). */
const taskFamilyOfArn = (arn: string) => arn.split("/").pop()?.split(":")[0];
/**
* Reap the task-definition revision superseded by a reconcile: registering
* always produces a NEW revision, so without this every reconcile strands
* the previous revision ACTIVE forever. Deregister + hard-delete the prior
* revision once the new one is registered.
*
* Guarded to the same family — `previousArn` can reference a foreign task
* definition this resource does not own (e.g. an `ECS.Service` switched from
* a BYO `task:` reference to the image-owning form), which must be left
* untouched. Idempotent: both calls tolerate "already gone", and a revision
* still referenced by running tasks parks in `DELETE_IN_PROGRESS` until AWS
* finishes the delete.
*/
export const reapSupersededTaskDefinitionRevision = Effect.fn(function* ({
previousArn,
nextArn,
}: {
/** The revision recorded before this reconcile (`output.taskDefinitionArn`). */
previousArn: string | undefined;
/** The freshly-registered revision ARN. */
nextArn: string;
}) {
if (
previousArn === undefined ||
previousArn === nextArn ||
taskFamilyOfArn(previousArn) !== taskFamilyOfArn(nextArn)
) {
return;
}
yield* ecs
.deregisterTaskDefinition({ taskDefinition: previousArn })
.pipe(Effect.catchTag("ClientException", () => Effect.void));
yield* ecs
.deleteTaskDefinitions({ taskDefinitions: [previousArn] })
.pipe(Effect.catchTag("ClientException", () => Effect.void));
});
/**
* Tear down the infrastructure a task definition owns: every remaining
* revision of the family (deregister + hard delete), the ECR repository, the
* log group, and the task/execution roles. Idempotent — every step tolerates
* "already gone".
*/
export const deleteTaskDefinitionInfrastructure = Effect.fn(function* (output: {
taskDefinitionArn: string;
/**
* The family owned by this resource. When present, EVERY remaining ACTIVE
* revision is swept — state rows written before reconcile-time revision
* reaping can have superseded revisions beyond the recorded one.
*/
taskFamily?: string;
repositoryName: string;
logGroupName: string;
taskRoleName: string;
executionRoleName: string;
}) {
const familyArns = output.taskFamily
? yield* ecs.listTaskDefinitions
.items({
familyPrefix: output.taskFamily,
status: "ACTIVE",
})
.pipe(
// `familyPrefix` is a prefix match — filter to the exact family so
// a family that happens to prefix another resource's is untouched.
// A nonexistent family is an empty list, not an error, so nothing
// is caught here: a real list failure must propagate — swallowing
// it would silently skip the sweep and leak the revisions.
Stream.filter((arn) => taskFamilyOfArn(arn) === output.taskFamily),
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk)),
)
: [];
const revisionArns = [...new Set([output.taskDefinitionArn, ...familyArns])];
for (const arn of revisionArns) {
yield* ecs
.deregisterTaskDefinition({ taskDefinition: arn })
.pipe(Effect.catchTag("ClientException", () => Effect.void));
}
// Deregistering only flips the revisions to INACTIVE — they still
// exist (and show up in `listTaskDefinitions --status INACTIVE`)
// forever. Hard-delete them so destroying a Task leaves zero
// task-definition leftovers. `deleteTaskDefinitions` accepts at most
// 10 ARNs per call.
for (let i = 0; i < revisionArns.length; i += 10) {
yield* ecs
.deleteTaskDefinitions({
taskDefinitions: revisionArns.slice(i, i + 10),
})
.pipe(Effect.catchTag("ClientException", () => Effect.void));
}
yield* ecr
.deleteRepository({
repositoryName: output.repositoryName,
force: true,
})
.pipe(Effect.catchTag("RepositoryNotFoundException", () => Effect.void));
yield* logs
.deleteLogGroup({
logGroupName: output.logGroupName,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
for (const roleName of [output.taskRoleName, output.executionRoleName]) {
// Delete inline policies on BOTH roles — the task role carries the
// bindings policy, and the execution role can carry inline policies too
// (e.g. the Service's secrets-read policy). A role with any inline
// policy left rejects `deleteRole` with `DeleteConflictException`.
yield* iam.listRolePolicies
.items({
RoleName: roleName,
})
.pipe(
Stream.mapEffect((policyName) =>
iam
.deleteRolePolicy({
RoleName: roleName,
PolicyName: policyName,
})
.pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
),
Stream.runDrain,
// The role may already be gone (delete re-run / race) — treat a
// missing role as "no policies to delete" so delete is idempotent.
Effect.catchTag("NoSuchEntityException", () => Effect.void),
);
yield* iam.listAttachedRolePolicies
.items({
RoleName: roleName,
})
.pipe(
Stream.mapEffect((policy) =>
iam
.detachRolePolicy({
RoleName: roleName,
PolicyArn: policy.PolicyArn!,
})
.pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
),
Stream.runDrain,
Effect.catchTag("NoSuchEntityException", () => Effect.void),
);
yield* iam
.deleteRole({
RoleName: roleName,
})
.pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
}
});
export const TaskProvider = () =>
Provider.effect(
Task,
Effect.gen(function* () {
const stack = yield* Stack;
const imageSource = yield* makeImageSource;
const alchemyEnv = {
ALCHEMY_STACK_NAME: stack.name,
ALCHEMY_STAGE: stack.stage,
ALCHEMY_PHASE: "runtime",
};
const toTaskFamily = (id: string, props: { taskName?: string } = {}) =>
props.taskName
? Effect.succeed(props.taskName)
: createPhysicalName({
id,
maxLength: 255,
lowercase: true,
});
const createRoleName = (id: string, suffix: string) =>
createPhysicalName({
id: `${id}-${suffix}`,
maxLength: 64,
});
const createPolicyName = (id: string, suffix: string) =>
createPhysicalName({
id: `${id}-${suffix}`,
maxLength: 128,
});
const createRepositoryName = (id: string) =>
createPhysicalName({
id: `${id}-repo`,
maxLength: 256,
lowercase: true,
});
const createLogGroupName = (id: string) =>
createPhysicalName({
id: `${id}-logs`,
maxLength: 512,
lowercase: true,
});
// Reconstruct the full `Task` Attributes shape from a described task
// definition. Returns `undefined` for task definitions that don't match
// the shape this provider produces (single container whose image is an
// ECR `<repoUri>:<hash>`, task/execution role ARNs, an awslogs log group)
// so foreign task definitions in the account are skipped by `list()`.
const toListAttributes = (
taskDefinition: ecs.TaskDefinition,
region: string,
accountId: string,
): Task["Attributes"] | undefined => {
if (!taskDefinition.taskDefinitionArn || !taskDefinition.family) {
return undefined;
}
const container = taskDefinition.containerDefinitions?.[0];
const image = container?.image;
const taskRoleArn = taskDefinition.taskRoleArn;
const executionRoleArn = taskDefinition.executionRoleArn;
const logGroupName = container?.logConfiguration?.options?.["awslogs-group"];
if (
!container?.name ||
!image ||
!image.includes(":") ||
!taskRoleArn ||
!executionRoleArn ||
!logGroupName
) {
return undefined;
}
const lastColon = image.lastIndexOf(":");
const repositoryUri = image.slice(0, lastColon);
const hash = image.slice(lastColon + 1);
const repositoryName = repositoryUri.split("/").slice(1).join("/");
const taskRoleName = taskRoleArn.split(":role/")[1] ?? taskRoleArn;
const executionRoleName = executionRoleArn.split(":role/")[1] ?? executionRoleArn;
return {
taskDefinitionArn: taskDefinition.taskDefinitionArn,
taskFamily: taskDefinition.family,
containerName: container.name,
port: container.portMappings?.[0]?.containerPort ?? 3000,
imageUri: image,
repositoryName,
repositoryUri,
taskRoleArn,
taskRoleName,
executionRoleArn,
executionRoleName,
logGroupName,
logGroupArn: `arn:aws:logs:${region}:${accountId}:log-group:${logGroupName}`,
code: { hash },
};
};
return {
stables: [
"repositoryName",
"repositoryUri",
"taskRoleArn",
"taskRoleName",
"executionRoleArn",
"executionRoleName",
"logGroupName",
"logGroupArn",
"taskFamily",
],
diff: Effect.fn(function* ({ id, olds, news, output }) {
if (!isResolved(news)) return;
if ((yield* toTaskFamily(id, olds ?? {})) !== (yield* toTaskFamily(id, news ?? {}))) {
return { action: "replace" } as const;
}
// Content drift: the props don't change when files under a
// `context` path (or the mirrored `image` ref's meaning) change —
// nor, for `main` sources, when the user's program or the
// generated bootstrap template changes. Hash the source (running
// the bundler for `main`, so the hash covers the bootstrap entry)
// and surface drift as an update; without this a bootstrap or
// code-only change would silently no-op until `--force`.
if (output) {
const hash = yield* imageSource.hash(taskImageInput(news));
if (hash !== undefined && hash !== output.code.hash) {
return { action: "update" } as const;
}
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const family = output?.taskFamily ?? (yield* toTaskFamily(id, olds ?? {}));
const described = yield* ecs
.describeTaskDefinition({
taskDefinition: output?.taskDefinitionArn ?? family,
})
.pipe(Effect.catchTag("ClientException", () => Effect.undefined));
const taskDefinition = described?.taskDefinition;
if (!taskDefinition?.taskDefinitionArn) {
return undefined;
}
if (!output) {
return undefined;
}
return {
...output,
taskDefinitionArn: taskDefinition.taskDefinitionArn,
taskFamily: taskDefinition.family ?? family,
containerName: taskDefinition.containerDefinitions?.[0]?.name ?? output.containerName,
port:
taskDefinition.containerDefinitions?.[0]?.portMappings?.[0]?.containerPort ??
output.port,
};
}),
reconcile: Effect.fn(function* ({ id, news, bindings, output, session }) {
// Prefer the deployed name: regenerating would target a different
// resource if the generator's output for this id ever drifts. (An
// explicit taskName change arrives here as a fresh replacement
// instance with no output.)
const family = output?.taskFamily ?? (yield* toTaskFamily(id, news));
const taskRoleName = output?.taskRoleName ?? (yield* createRoleName(id, "task-role"));
const executionRoleName =
output?.executionRoleName ?? (yield* createRoleName(id, "execution-role"));
const taskPolicyName = yield* createPolicyName(id, "task-policy");
const repositoryName = output?.repositoryName ?? (yield* createRepositoryName(id));
const logGroupName = output?.logGroupName ?? (yield* createLogGroupName(id));
const tags = {
...(yield* createInternalTags(id)),
...news.tags,
};
// Ensure roles, repository, and log group. Each helper is
// idempotent (creates on miss, adopts on race) so the same
// sequence runs on initial create, adoption, or update.
const taskRoleArn =
output?.taskRoleArn ??
(yield* createTaskRoleIfNotExists({ id, roleName: taskRoleName }));
const executionRoleArn =
output?.executionRoleArn ??
(yield* ensureTaskExecutionRole({
id,
roleName: executionRoleName,
managedPolicyArns: news.executionRoleManagedPolicyArns,
}));
for (const policyArn of news.taskRoleManagedPolicyArns ?? []) {
yield* iam
.attachRolePolicy({
RoleName: taskRoleName,
PolicyArn: policyArn,
})
.pipe(Effect.catchTag("LimitExceededException", () => Effect.void));
}
// Environment files: the execution role reads the referenced S3
// objects at task start.
yield* syncEnvironmentFilesPolicy({
roleName: executionRoleName,
environmentFiles: news.environmentFiles,
});
const {
env: bindingEnv,
volumes: bindingVolumes,
mountPoints: bindingMountPoints,
} = yield* attachTaskBindings({
roleName: taskRoleName,
policyName: taskPolicyName,
bindings,
});
const logGroupArn =
output?.logGroupArn ??
(yield* ensureTaskLogGroup({
id,
logGroupName,
}));
yield* syncLogGroupRetention({
logGroupName,
retention: news.logging?.retention,
});
// Resolve the container image from whichever source the props
// declare (`main` | `context` | `image`), building/mirroring and
// pushing into the task's ECR repository, then register a new
// task definition revision. Task definitions are versioned in
// AWS, so registering a new revision is the unit of "update" —
// the superseded revision is reaped after registration below.
const resolved = yield* imageSource.resolve({
...taskImageInput(news),
id,
repositoryName,
repositoryUri:
output?.repositoryUri && output.repositoryName === repositoryName
? output.repositoryUri
: undefined,
tags,
session,
});
const taskDefinition = yield* registerTaskDefinitionRevision({
props: {
...news,
env: {
...bindingEnv,
...alchemyEnv,
...news.env,
},
},
family,
imageUri: resolved.imageUri,
taskRoleArn,
executionRoleArn,
logGroupName,
tags,
bindingVolumes,
bindingMountPoints,
});
// Sync tags — task definition revisions carry tags at register
// time, but tags are mutable on the revision ARN. Diff the observed
// revision tags against desired so tag-only updates converge.
yield* syncTaskDefinitionTags({
revisionArn: taskDefinition.taskDefinitionArn!,
tags,
});
// The registration above superseded the previously-recorded
// revision — reap it so revisions don't accumulate ACTIVE forever.
yield* reapSupersededTaskDefinitionRevision({
previousArn: output?.taskDefinitionArn,
nextArn: taskDefinition.taskDefinitionArn!,
});
yield* session.note(taskDefinition.taskDefinitionArn!);
return {
taskDefinitionArn: taskDefinition.taskDefinitionArn!,
taskFamily: family,
containerName: taskDefinition.containerDefinitions?.[0]?.name ?? family,
port: news.port ?? output?.port ?? 3000,
imageUri: resolved.imageUri,
repositoryName: resolved.repositoryName,
repositoryUri: resolved.repositoryUri,
taskRoleArn,
taskRoleName,
executionRoleArn,
executionRoleName,
logGroupName,
logGroupArn,
code: {
hash: resolved.codeHash,
},
};
}),
// Enumerate every ACTIVE task definition in the account/region,
// hydrate each via `describeTaskDefinition`, and reconstruct the full
// Attributes shape. Foreign task definitions that don't match the shape
// this provider produces are skipped (see `toListAttributes`).
list: () =>
Effect.gen(function* () {
const { accountId, region } = yield* AWSEnvironment.current;
const arns = yield* ecs.listTaskDefinitions.pages({ status: "ACTIVE" }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) => page.taskDefinitionArns ?? []),
),
);
const rows = yield* Effect.forEach(
arns,
(arn) =>
ecs.describeTaskDefinition({ taskDefinition: arn }).pipe(
Effect.map((described) =>
described.taskDefinition
? toListAttributes(described.taskDefinition, region, accountId)
: undefined,
),
Effect.catchTag("ClientException", () => Effect.undefined),
),
{ concurrency: 10 },
);
return rows.filter((row): row is Task["Attributes"] => row !== undefined);
}),
delete: Effect.fn(function* ({ output }) {
yield* deleteTaskDefinitionInfrastructure(output);
}),
};
}),
);