The best way to control Claude Code, Codex and more from any computer or phone

main
ts 1,317 lines 44.1 KB
Raw
1 import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
2 import * as ecr from "@distilled.cloud/aws/ecr";
3 import * as ecs from "@distilled.cloud/aws/ecs";
4 import * as iam from "@distilled.cloud/aws/iam";
5 import { Region } from "@distilled.cloud/aws/Region";
6 import { isResolved } from "alchemy/Diff";
7 import { createPhysicalName } from "alchemy/PhysicalName";
8 import { Platform, type Main, type PlatformProps, type PlatformServices } from "alchemy/Platform";
9 import * as Provider from "alchemy/Provider";
10 import { Resource, type ResourceBinding } from "alchemy/Resource";
11 import {
12 createContainerRuntimeContext,
13 type HostRuntimeContext,
14 type ServerHost,
15 } from "alchemy/Runtime/Process";
16 import type { RuntimeContext } from "alchemy/RuntimeContext";
17 import { Stack } from "alchemy/Stack";
18 import { createInternalTags, createTagsList, diffTags, hasTags } from "alchemy/Tags";
19 import * as Context from "effect/Context";
20 import * as Data from "effect/Data";
21 import * as Effect from "effect/Effect";
22 import type { Scope } from "effect/Scope";
23 import * as Stream from "effect/Stream";
24 import type { Credentials } from "../Credentials.ts";
25 import {
26 makeBunBootstrap,
27 makeImageSource,
28 type BundledImageSource,
29 type DockerfileImageSource,
30 type ImageSourceLike,
31 type RegistryImageSource,
32 } from "../ECR/ImageSource.ts";
33 import { AWSEnvironment } from "../Environment.ts";
34 import type { PolicyStatement } from "../IAM/Policy.ts";
35 import { syncLogGroupRetention, type LogRetentionConfig } from "../Logs/LogRetention.ts";
36 import type { Providers } from "../Providers.ts";
37
38 export class TaskConflict extends Data.TaggedError("TaskConflict")<{
39 readonly message: string;
40 readonly cause?: unknown;
41 }> {}
42
43 export const isTask = (value: any): value is Task =>
44 typeof value === "object" && value !== null && "Type" in value && value.Type === "AWS.ECS.Task";
45
46 export class TaskEnvironment extends Context.Service<TaskEnvironment, Record<string, any>>()(
47 "AWS.ECS.TaskEnvironment",
48 ) {}
49
50 /**
51 * The binding contract shared by the ECS container platforms (`Task` and the
52 * image-owning `Service`): env vars and IAM policy statements land on the
53 * task role, plus task-level volumes/mount points requested through the
54 * binding channel (e.g. `EFS.Mount`).
55 */
56 export interface TaskBindingContract {
57 /** Environment variables injected into the task's containers. */
58 env?: Record<string, any>;
59 /** IAM policy statements attached to the task role. */
60 policyStatements?: PolicyStatement[];
61 /**
62 * Task-level volumes requested through the binding channel (e.g.
63 * `EFS.Mount`). Merged with the resource's own `volumes` prop.
64 */
65 volumes?: ecs.Volume[];
66 /**
67 * Container mount points for binding-requested volumes, applied to the
68 * primary container.
69 */
70 mountPoints?: ecs.MountPoint[];
71 }
72
73 /**
74 * Task-definition configuration shared by `AWS.ECS.Task` and the
75 * image-owning form of `AWS.ECS.Service` (which synthesizes its own task
76 * definition from the same surface).
77 */
78 export interface TaskDefinitionConfig {
79 /**
80 * Task-level cpu configuration for Fargate.
81 * @default 256
82 */
83 cpu?: number;
84 /**
85 * Task-level memory configuration for Fargate.
86 * @default 512
87 */
88 memory?: number;
89 /**
90 * HTTP port exposed by the container.
91 */
92 port?: number;
93 /**
94 * Additional environment variables for the container.
95 */
96 env?: Record<string, any>;
97 /**
98 * Environment files to load into the primary container, e.g. `.env`
99 * objects stored in S3:
100 * `[{ value: "arn:aws:s3:::my-bucket/app.env", type: "s3" }]`.
101 *
102 * Variables from `env` (and the container's own `environment`) take
103 * precedence over values loaded from environment files. The execution
104 * role is automatically granted `s3:GetObject` on the referenced objects
105 * and `s3:GetBucketLocation` on their buckets.
106 */
107 environmentFiles?: ecs.EnvironmentFile[];
108 /**
109 * Command override for the primary container (Docker `CMD`).
110 */
111 command?: string[];
112 /**
113 * Container definition overrides applied after Alchemy's defaults for the
114 * primary container.
115 */
116 container?: Partial<ecs.ContainerDefinition>;
117 /**
118 * Retention for the task's CloudWatch log group, e.g.
119 * `{ retention: "2 weeks" }` or `{ retention: "forever" }`.
120 */
121 logging?: LogRetentionConfig;
122 /**
123 * Additional sidecar containers appended to the task definition after the
124 * primary container. Each entry is a full, typed
125 * {@link ecs.ContainerDefinition} (image URIs supplied by the user, e.g.
126 * from an `ECR.Image` or an external registry).
127 *
128 * Use this to declare multi-container tasks: log routers (firelens),
129 * proxies (Envoy/App Mesh), metric agents (otel/cloudwatch), or any
130 * companion process that shares the task's network namespace.
131 */
132 sidecars?: ecs.ContainerDefinition[];
133 /**
134 * Task definition network mode.
135 * @default "awsvpc"
136 */
137 networkMode?: ecs.NetworkMode;
138 /**
139 * Launch-type compatibilities the task definition must support.
140 * @default ["FARGATE"]
141 */
142 requiresCompatibilities?: ecs.Compatibility[];
143 /**
144 * Task-level data volumes (host / docker / EFS / FSx Windows / S3 /
145 * configured-at-launch). Containers reference these via `mountPoints`.
146 */
147 volumes?: ecs.Volume[];
148 /**
149 * Task definition placement constraints (`memberOf` expressions). Only
150 * applies to EC2/EXTERNAL launch types.
151 */
152 placementConstraints?: ecs.TaskDefinitionPlacementConstraint[];
153 /**
154 * CPU architecture and operating-system family the task runs on, e.g.
155 * `{ cpuArchitecture: "ARM64", operatingSystemFamily: "LINUX" }`.
156 */
157 runtimePlatform?: ecs.RuntimePlatform;
158 /**
159 * Amount of ephemeral storage (in GiB) to allocate for the task on Fargate.
160 */
161 ephemeralStorage?: ecs.EphemeralStorage;
162 /**
163 * IPC resource namespace to use for the containers in the task.
164 */
165 ipcMode?: ecs.IpcMode;
166 /**
167 * Process namespace to use for the containers in the task.
168 */
169 pidMode?: ecs.PidMode;
170 /**
171 * App Mesh proxy configuration.
172 */
173 proxyConfiguration?: ecs.ProxyConfiguration;
174 /**
175 * Elastic Inference accelerators to attach to the task.
176 */
177 inferenceAccelerators?: ecs.InferenceAccelerator[];
178 /**
179 * Whether to enable AWS Fault Injection (FIS) actions on the task.
180 * @default false
181 */
182 enableFaultInjection?: boolean;
183 /**
184 * Additional task definition overrides applied last (escape hatch for
185 * fields not yet surfaced as first-class props).
186 */
187 taskDefinition?: Partial<
188 Omit<
189 ecs.RegisterTaskDefinitionRequest,
190 "family" | "containerDefinitions" | "executionRoleArn" | "taskRoleArn" | "cpu" | "memory"
191 >
192 >;
193 /**
194 * Additional managed policy ARNs for the task role.
195 */
196 taskRoleManagedPolicyArns?: string[];
197 /**
198 * Additional managed policy ARNs for the execution role.
199 */
200 executionRoleManagedPolicyArns?: string[];
201 }
202
203 export interface TaskPropsBase extends PlatformProps, TaskDefinitionConfig {
204 /**
205 * ECS task family. If omitted, a unique family is generated.
206 */
207 taskName?: string;
208 /**
209 * User-defined tags to apply to task-owned resources.
210 */
211 tags?: Record<string, string>;
212 }
213
214 /**
215 * Bundle an inline Effect program (`main`) into a generated image whose
216 * environment comes from `image`, `dockerfile`, or the default bun base.
217 */
218 export interface BundledTaskProps extends TaskPropsBase, BundledImageSource {}
219 /**
220 * Build the user's own Dockerfile (`context` + optional `dockerfile` path)
221 * into the task image.
222 */
223 export interface DockerfileTaskProps extends TaskPropsBase, DockerfileImageSource {}
224 /**
225 * Run a pre-built registry image (`image`), mirrored into ECR.
226 */
227 export interface ImageTaskProps extends TaskPropsBase, RegistryImageSource {}
228
229 /**
230 * Task props — the image comes from exactly one of three sources, flat on
231 * the props: `main` (bundled Effect program), `context` (user Dockerfile),
232 * or `image` (registry reference).
233 */
234 export type TaskProps = BundledTaskProps | DockerfileTaskProps | ImageTaskProps;
235
236 export interface Task extends Resource<
237 "AWS.ECS.Task",
238 TaskProps,
239 {
240 /** The ARN of the registered task definition revision. */
241 taskDefinitionArn: string;
242 /** The task definition family name. */
243 taskFamily: string;
244 /** The name of the main container in the task definition. */
245 containerName: string;
246 /** The container port the task listens on. */
247 port: number;
248 /** The full URI of the container image the task runs. */
249 imageUri: string;
250 /** The name of the ECR repository holding the built image. */
251 repositoryName: string;
252 /** The URI of the ECR repository holding the built image. */
253 repositoryUri: string;
254 /** The ARN of the task role assumed by the running containers. */
255 taskRoleArn: string;
256 /** The name of the task role. */
257 taskRoleName: string;
258 /** The ARN of the execution role used to pull images and write logs. */
259 executionRoleArn: string;
260 /** The name of the execution role. */
261 executionRoleName: string;
262 /** The CloudWatch log group the task writes to. */
263 logGroupName: string;
264 /** The ARN of the CloudWatch log group. */
265 logGroupArn: string;
266 /** The content hash of the task's container image. */
267 code: {
268 /** The content hash of the task's container image. */
269 hash: string;
270 };
271 },
272 TaskBindingContract,
273 Providers
274 > {}
275
276 export type TaskServices = Credentials | Region | ServerHost | AWSEnvironment;
277
278 /**
279 * The impl shape for an effectful `Task`: a `run` entry that executes to
280 * completion when the container starts, and/or a `fetch` HTTP handler for
281 * tasks deployed as servers (e.g. referenced by an `ECS.Service`).
282 */
283 export type TaskShape =
284 | void
285 | (Exclude<Main<TaskServices>, void> & {
286 /**
287 * Runs to completion when the container starts, after which the
288 * container exits.
289 */
290 run?: Effect.Effect<void, never, TaskServices | PlatformServices | RuntimeContext | Scope>;
291 });
292
293 export interface TaskRuntimeContext extends HostRuntimeContext {
294 readonly Type: "AWS.ECS.Task";
295 }
296
297 // Shared with `Docker.Service`; lives beside the host runtime context.
298 export { createContainerRuntimeContext } from "alchemy/Runtime/Process";
299
300 /**
301 * A Fargate task definition with a container image from one of three
302 * sources, declared flat on the props:
303 *
304 * - `main` — bundle an inline Effect program into a generated image
305 * (compose with `image` or an inline `dockerfile` to pick the
306 * environment; defaults to `oven/bun:1`).
307 * - `context` — build your own Dockerfile (`dockerfile` is a path relative
308 * to the cwd, defaulting to `${context}/Dockerfile`).
309 * - `image` — run a pre-built registry image, mirrored into ECR.
310 *
311 * `Task` provisions task + execution IAM roles, a CloudWatch log group, and
312 * an ECR repository holding the built (or mirrored) image, then registers a
313 * Fargate task definition. Each reconcile registers a new immutable
314 * revision. A launched task runs until its process exits — it is the target
315 * of `AWS.ECS.RunTask` / `StopTask` bindings and `AWS.ECS.Schedule`;
316 * effectful impls return `{ run }`, executed to completion when the
317 * container starts.
318 *
319 * Beyond the primary container you can declare task-level configuration
320 * (volumes, runtime platform, ephemeral storage, IPC/PID mode, placement
321 * constraints) and append additional `sidecars` for multi-container tasks.
322 * ### Creating a Task
323 * **Example:** Remote Image
324 * ```typescript
325 * const migrate = yield* Task("DbMigrate", {
326 * image: "public.ecr.aws/docker/library/busybox:stable",
327 * command: ["sh", "-c", "echo done"],
328 * cpu: 256,
329 * memory: 512,
330 * });
331 * ```
332 *
333 * **Example:** Build Your Own Dockerfile
334 * ```typescript
335 * const render = yield* Task("RenderJob", {
336 * context: "./render", // dockerfile defaults to ./render/Dockerfile
337 * dockerfile: "./render/Dockerfile.gpu", // always a PATH
338 * cpu: 1024,
339 * memory: 4096,
340 * });
341 * ```
342 *
343 * **Example:** Build args and secrets
344 * ```typescript
345 * // Dockerfile:
346 * // ARG NODE_ENV
347 * // RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci
348 * const api = yield* Task("Api", {
349 * context: "./api",
350 * build: {
351 * args: { NODE_ENV: "production" },
352 * // Mounted only into the RUN step that asks for it; never in the image.
353 * secrets: { NPM_TOKEN: Config.Redacted("NPM_TOKEN") },
354 * },
355 * cpu: 256,
356 * memory: 512,
357 * });
358 * ```
359 *
360 * **Example:** Inline Effect Program
361 * ```typescript
362 * const drainer = yield* Task(
363 * "QueueDrainer",
364 * { main: import.meta.url, image: "oven/bun:1", cpu: 256, memory: 512 },
365 * Effect.gen(function* () {
366 * const receive = yield* AWS.SQS.ReceiveMessage(queue);
367 * return {
368 * run: Effect.gen(function* () {
369 * // runs to completion, then the container exits
370 * const batch = yield* receive({ MaxNumberOfMessages: 10 });
371 * }),
372 * };
373 * }),
374 * );
375 * ```
376 *
377 * ### Multi-Container Tasks
378 * **Example:** Task with a Sidecar
379 * ```typescript
380 * const task = yield* Task("ApiTask", {
381 * main: import.meta.url,
382 * port: 3000,
383 * sidecars: [
384 * {
385 * name: "otel-collector",
386 * image: "public.ecr.aws/aws-observability/aws-otel-collector:latest",
387 * essential: false,
388 * portMappings: [{ containerPort: 4317, protocol: "tcp" }],
389 * },
390 * ],
391 * });
392 * ```
393 *
394 * ### Bundling & Tree-shaking
395 * `main` is bundled with rolldown at deploy time. Unused code is
396 * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
397 * pure so unused parts prune more aggressively. Your app is not
398 * marked pure.
399 *
400 * **Example:** Mark additional packages as pure
401 * Only list packages with no top-level side effects.
402 * ```typescript
403 * {
404 * main: import.meta.url,
405 * build: {
406 * pure: { packages: ["my-lib", "@my-scope/*"] },
407 * },
408 * }
409 * ```
410 *
411 * **Example:** Turn it off
412 * ```typescript
413 * {
414 * main: import.meta.url,
415 * build: { pure: false },
416 * }
417 * ```
418 *
419 * ### Task-Level Configuration
420 * **Example:** ARM64 with EFS Volume and Ephemeral Storage
421 * ```typescript
422 * const task = yield* Task("WorkerTask", {
423 * main: import.meta.url,
424 * runtimePlatform: { cpuArchitecture: "ARM64", operatingSystemFamily: "LINUX" },
425 * ephemeralStorage: { sizeInGiB: 40 },
426 * volumes: [
427 * {
428 * name: "data",
429 * efsVolumeConfiguration: { fileSystemId: fileSystem.fileSystemId },
430 * },
431 * ],
432 * container: {
433 * mountPoints: [{ sourceVolume: "data", containerPath: "/data" }],
434 * },
435 * });
436 * ```
437 *
438 * **Example:** Environment Files from S3
439 * ```typescript
440 * const task = yield* Task("ApiTask", {
441 * main: import.meta.url,
442 * environmentFiles: [
443 * { value: "arn:aws:s3:::my-config-bucket/app.env", type: "s3" },
444 * ],
445 * });
446 * ```
447 *
448 * @resource
449 */
450 export const Task: Platform<Task, TaskServices, TaskShape, TaskRuntimeContext> = Platform(
451 "AWS.ECS.Task",
452 {
453 createRuntimeContext: createContainerRuntimeContext("AWS.ECS.Task") as (
454 id: string,
455 ) => TaskRuntimeContext,
456 },
457 );
458
459 /** Docker build platform matching the task definition's declared runtime. */
460 export const taskImagePlatform = (runtimePlatform?: ecs.RuntimePlatform) =>
461 // Build for the architecture the task definition declares (Fargate
462 // defaults to X86_64 when `runtimePlatform` is unset). Without this, an
463 // image built on an ARM64 host (e.g. Apple Silicon) is rejected at task
464 // start with `image Manifest does not contain descriptor matching
465 // platform 'linux/amd64'`.
466 runtimePlatform?.cpuArchitecture === "ARM64" ? "linux/arm64" : "linux/amd64";
467
468 /** Keep image resolution, drift detection and dev watching on the same inputs. */
469 export const taskImageInput = (props: TaskProps) => {
470 const source = props as ImageSourceLike;
471 return {
472 source,
473 platform: taskImagePlatform(props.runtimePlatform),
474 port: props.port,
475 isExternal: props.isExternal,
476 bootstrap: makeBunBootstrap(source.handler ?? "default"),
477 };
478 };
479
480 /**
481 * Create the IAM role assumed by ECS tasks if it doesn't already exist.
482 * Idempotent: an `EntityAlreadyExistsException` adopts the existing role
483 * only when it carries our internal tags.
484 */
485 export const createTaskRoleIfNotExists = Effect.fn(function* ({
486 id,
487 roleName,
488 }: {
489 id: string;
490 roleName: string;
491 }) {
492 const tags = yield* createInternalTags(id);
493 const role = yield* iam
494 .createRole({
495 RoleName: roleName,
496 AssumeRolePolicyDocument: JSON.stringify({
497 Version: "2012-10-17",
498 Statement: [
499 {
500 Effect: "Allow",
501 Principal: {
502 Service: "ecs-tasks.amazonaws.com",
503 },
504 Action: "sts:AssumeRole",
505 },
506 ],
507 }),
508 Tags: createTagsList(tags),
509 })
510 .pipe(
511 Effect.catchTag("EntityAlreadyExistsException", () =>
512 iam.getRole({ RoleName: roleName }).pipe(
513 Effect.filterOrFail(
514 (existing) => hasTags(tags, existing.Role?.Tags),
515 () =>
516 new TaskConflict({
517 message: `Role '${roleName}' already exists and is not managed by alchemy`,
518 }),
519 ),
520 ),
521 ),
522 );
523 return role.Role!.Arn!;
524 });
525
526 /**
527 * Ensure the ECS execution role exists with the standard execution policy
528 * (plus any additional managed policies) attached.
529 */
530 export const ensureTaskExecutionRole = Effect.fn(function* ({
531 id,
532 roleName,
533 managedPolicyArns,
534 }: {
535 id: string;
536 roleName: string;
537 managedPolicyArns?: string[];
538 }) {
539 const roleArn = yield* createTaskRoleIfNotExists({ id, roleName });
540 const policies = [
541 "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy",
542 ...(managedPolicyArns ?? []),
543 ];
544 for (const policyArn of policies) {
545 yield* iam
546 .attachRolePolicy({
547 RoleName: roleName,
548 PolicyArn: policyArn,
549 })
550 .pipe(Effect.catchTag("LimitExceededException", () => Effect.void));
551 }
552 return roleArn;
553 });
554
555 /** Inline policy granting the execution role read access to `environmentFiles`. */
556 const ENVIRONMENT_FILES_POLICY_NAME = "alchemy-environment-files";
557
558 /**
559 * Sync the execution role's read access to the S3 `environmentFiles`: put
560 * an inline policy granting `s3:GetObject` on the referenced objects (and
561 * `s3:GetBucketLocation` on their buckets), or delete the policy when no
562 * environment files are configured.
563 */
564 export const syncEnvironmentFilesPolicy = Effect.fn(function* ({
565 roleName,
566 environmentFiles,
567 }: {
568 roleName: string;
569 environmentFiles: ecs.EnvironmentFile[] | undefined;
570 }) {
571 const objectArns = (environmentFiles ?? [])
572 .filter((file) => file.type === "s3")
573 .map((file) => file.value);
574 if (objectArns.length === 0) {
575 yield* iam
576 .deleteRolePolicy({
577 RoleName: roleName,
578 PolicyName: ENVIRONMENT_FILES_POLICY_NAME,
579 })
580 .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
581 return;
582 }
583 const bucketArns = [...new Set(objectArns.map((arn) => arn.split("/")[0]))];
584 yield* iam.putRolePolicy({
585 RoleName: roleName,
586 PolicyName: ENVIRONMENT_FILES_POLICY_NAME,
587 PolicyDocument: JSON.stringify({
588 Version: "2012-10-17",
589 Statement: [
590 {
591 Effect: "Allow",
592 Action: ["s3:GetObject"],
593 Resource: objectArns,
594 },
595 {
596 Effect: "Allow",
597 Action: ["s3:GetBucketLocation"],
598 Resource: bucketArns,
599 },
600 ],
601 }),
602 });
603 });
604
605 /** Ensure the CloudWatch log group the task writes to exists. */
606 export const ensureTaskLogGroup = Effect.fn(function* ({
607 id,
608 logGroupName,
609 }: {
610 id: string;
611 logGroupName: string;
612 }) {
613 const { accountId, region } = yield* AWSEnvironment.current;
614 const tags = yield* createInternalTags(id);
615 yield* logs
616 .createLogGroup({
617 logGroupName,
618 tags,
619 })
620 .pipe(Effect.catchTag("ResourceAlreadyExistsException", () => Effect.void));
621 return `arn:aws:logs:${region}:${accountId}:log-group:${logGroupName}`;
622 });
623
624 /**
625 * Apply the binding channel to the task role: collect env vars, put (or
626 * clear) the inline policy from bound policy statements, and dedupe
627 * binding-requested volumes/mount points.
628 */
629 export const attachTaskBindings = Effect.fn(function* ({
630 roleName,
631 policyName,
632 bindings,
633 }: {
634 roleName: string;
635 policyName: string;
636 bindings: ResourceBinding<TaskBindingContract>[];
637 }) {
638 const activeBindings = bindings.filter(
639 (binding: ResourceBinding<TaskBindingContract> & { action?: string }) =>
640 binding.action !== "delete",
641 );
642
643 const env = activeBindings
644 .map((binding) => binding?.data?.env)
645 .reduce((acc, value) => ({ ...acc, ...value }), {});
646
647 const policyStatements = activeBindings.flatMap(
648 (binding) =>
649 binding?.data?.policyStatements?.map((statement) => ({
650 ...statement,
651 Sid: statement.Sid?.replace(/[^A-Za-z0-9]+/gi, ""),
652 })) ?? [],
653 );
654
655 // Volumes/mount points requested through the binding channel (e.g.
656 // `EFS.Mount`) — deduped by volume name / container path; merged
657 // with the `volumes` prop and primary container in `reconcile`.
658 const volumes = [
659 ...new Map(
660 activeBindings
661 .flatMap((binding) => binding?.data?.volumes ?? [])
662 .map((volume) => [volume.name, volume] as const),
663 ).values(),
664 ];
665 const mountPoints = [
666 ...new Map(
667 activeBindings
668 .flatMap((binding) => binding?.data?.mountPoints ?? [])
669 .map((point) => [point.containerPath, point] as const),
670 ).values(),
671 ];
672
673 if (policyStatements.length > 0) {
674 yield* iam.putRolePolicy({
675 RoleName: roleName,
676 PolicyName: policyName,
677 PolicyDocument: JSON.stringify({
678 Version: "2012-10-17",
679 Statement: policyStatements,
680 }),
681 });
682 } else {
683 yield* iam
684 .deleteRolePolicy({
685 RoleName: roleName,
686 PolicyName: policyName,
687 })
688 .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
689 }
690
691 return { env, volumes, mountPoints };
692 });
693
694 /**
695 * Register a new task definition revision from the shared
696 * {@link TaskDefinitionConfig} surface.
697 */
698 export const registerTaskDefinitionRevision = Effect.fn(function* ({
699 props,
700 family,
701 imageUri,
702 taskRoleArn,
703 executionRoleArn,
704 logGroupName,
705 tags,
706 bindingVolumes = [],
707 bindingMountPoints = [],
708 }: {
709 props: TaskDefinitionConfig;
710 family: string;
711 imageUri: string;
712 taskRoleArn: string;
713 executionRoleArn: string;
714 logGroupName: string;
715 tags: Record<string, string>;
716 /** Task-level volumes requested through the binding channel. */
717 bindingVolumes?: ecs.Volume[];
718 /** Primary-container mount points for binding-requested volumes. */
719 bindingMountPoints?: ecs.MountPoint[];
720 }) {
721 const { region } = yield* AWSEnvironment.current;
722 const containerName = props.container?.name ?? family;
723 const primaryContainer: ecs.ContainerDefinition = {
724 essential: true,
725 name: containerName,
726 image: imageUri,
727 command: props.command,
728 portMappings:
729 props.port !== undefined
730 ? [
731 {
732 containerPort: props.port,
733 hostPort: props.port,
734 protocol: "tcp",
735 },
736 ]
737 : undefined,
738 environment: Object.entries(props.env ?? {}).map(([name, value]) => ({
739 name,
740 value: typeof value === "string" ? value : JSON.stringify(value),
741 })),
742 environmentFiles: props.environmentFiles,
743 logConfiguration: {
744 logDriver: "awslogs",
745 options: {
746 "awslogs-group": logGroupName,
747 "awslogs-region": region,
748 "awslogs-stream-prefix": family,
749 },
750 },
751 ...props.container,
752 // Merge binding-requested mount points (e.g. `EFS.Mount`) with any
753 // the user configured on the primary container.
754 ...(bindingMountPoints.length > 0
755 ? {
756 mountPoints: [...(props.container?.mountPoints ?? []), ...bindingMountPoints],
757 }
758 : {}),
759 };
760 const response = yield* ecs.registerTaskDefinition({
761 family,
762 taskRoleArn,
763 executionRoleArn,
764 networkMode: props.networkMode ?? "awsvpc",
765 requiresCompatibilities: props.requiresCompatibilities ?? ["FARGATE"],
766 cpu: String(props.cpu ?? 256),
767 memory: String(props.memory ?? 512),
768 volumes:
769 bindingVolumes.length > 0 ? [...(props.volumes ?? []), ...bindingVolumes] : props.volumes,
770 placementConstraints: props.placementConstraints,
771 runtimePlatform: props.runtimePlatform,
772 ephemeralStorage: props.ephemeralStorage,
773 ipcMode: props.ipcMode,
774 pidMode: props.pidMode,
775 proxyConfiguration: props.proxyConfiguration,
776 inferenceAccelerators: props.inferenceAccelerators,
777 enableFaultInjection: props.enableFaultInjection,
778 ...props.taskDefinition,
779 containerDefinitions: [primaryContainer, ...(props.sidecars ?? [])],
780 tags: Object.entries(tags).map(([key, value]) => ({ key, value })),
781 });
782 const taskDefinition = response.taskDefinition;
783 if (!taskDefinition?.taskDefinitionArn) {
784 return yield* Effect.die(new Error("registerTaskDefinition returned no task definition"));
785 }
786 return taskDefinition;
787 });
788
789 /**
790 * Sync tags on a task definition revision: diff observed revision tags
791 * against desired and apply the delta.
792 */
793 export const syncTaskDefinitionTags = Effect.fn(function* ({
794 revisionArn,
795 tags,
796 }: {
797 revisionArn: string;
798 tags: Record<string, string>;
799 }) {
800 const observedTags = Object.fromEntries(
801 (
802 (yield* ecs
803 .listTagsForResource({ resourceArn: revisionArn })
804 .pipe(
805 Effect.catchTag("ClientException", () =>
806 Effect.succeed({ tags: undefined } as { tags?: ecs.Tag[] }),
807 ),
808 )).tags ?? []
809 )
810 .filter(
811 (t): t is { key: string; value: string } =>
812 typeof t.key === "string" && typeof t.value === "string",
813 )
814 .map((t) => [t.key, t.value]),
815 );
816 const { removed: removedTags, upsert: upsertTags } = diffTags(observedTags, tags);
817 if (upsertTags.length > 0) {
818 yield* ecs.tagResource({
819 resourceArn: revisionArn,
820 tags: upsertTags.map((t) => ({ key: t.Key, value: t.Value })),
821 });
822 }
823 if (removedTags.length > 0) {
824 yield* ecs.untagResource({
825 resourceArn: revisionArn,
826 tagKeys: removedTags,
827 });
828 }
829 });
830
831 /** The family segment of a task definition revision ARN (`…:task-definition/<family>:<revision>`). */
832 const taskFamilyOfArn = (arn: string) => arn.split("/").pop()?.split(":")[0];
833
834 /**
835 * Reap the task-definition revision superseded by a reconcile: registering
836 * always produces a NEW revision, so without this every reconcile strands
837 * the previous revision ACTIVE forever. Deregister + hard-delete the prior
838 * revision once the new one is registered.
839 *
840 * Guarded to the same family — `previousArn` can reference a foreign task
841 * definition this resource does not own (e.g. an `ECS.Service` switched from
842 * a BYO `task:` reference to the image-owning form), which must be left
843 * untouched. Idempotent: both calls tolerate "already gone", and a revision
844 * still referenced by running tasks parks in `DELETE_IN_PROGRESS` until AWS
845 * finishes the delete.
846 */
847 export const reapSupersededTaskDefinitionRevision = Effect.fn(function* ({
848 previousArn,
849 nextArn,
850 }: {
851 /** The revision recorded before this reconcile (`output.taskDefinitionArn`). */
852 previousArn: string | undefined;
853 /** The freshly-registered revision ARN. */
854 nextArn: string;
855 }) {
856 if (
857 previousArn === undefined ||
858 previousArn === nextArn ||
859 taskFamilyOfArn(previousArn) !== taskFamilyOfArn(nextArn)
860 ) {
861 return;
862 }
863 yield* ecs
864 .deregisterTaskDefinition({ taskDefinition: previousArn })
865 .pipe(Effect.catchTag("ClientException", () => Effect.void));
866 yield* ecs
867 .deleteTaskDefinitions({ taskDefinitions: [previousArn] })
868 .pipe(Effect.catchTag("ClientException", () => Effect.void));
869 });
870
871 /**
872 * Tear down the infrastructure a task definition owns: every remaining
873 * revision of the family (deregister + hard delete), the ECR repository, the
874 * log group, and the task/execution roles. Idempotent — every step tolerates
875 * "already gone".
876 */
877 export const deleteTaskDefinitionInfrastructure = Effect.fn(function* (output: {
878 taskDefinitionArn: string;
879 /**
880 * The family owned by this resource. When present, EVERY remaining ACTIVE
881 * revision is swept — state rows written before reconcile-time revision
882 * reaping can have superseded revisions beyond the recorded one.
883 */
884 taskFamily?: string;
885 repositoryName: string;
886 logGroupName: string;
887 taskRoleName: string;
888 executionRoleName: string;
889 }) {
890 const familyArns = output.taskFamily
891 ? yield* ecs.listTaskDefinitions
892 .items({
893 familyPrefix: output.taskFamily,
894 status: "ACTIVE",
895 })
896 .pipe(
897 // `familyPrefix` is a prefix match — filter to the exact family so
898 // a family that happens to prefix another resource's is untouched.
899 // A nonexistent family is an empty list, not an error, so nothing
900 // is caught here: a real list failure must propagate — swallowing
901 // it would silently skip the sweep and leak the revisions.
902 Stream.filter((arn) => taskFamilyOfArn(arn) === output.taskFamily),
903 Stream.runCollect,
904 Effect.map((chunk) => Array.from(chunk)),
905 )
906 : [];
907 const revisionArns = [...new Set([output.taskDefinitionArn, ...familyArns])];
908
909 for (const arn of revisionArns) {
910 yield* ecs
911 .deregisterTaskDefinition({ taskDefinition: arn })
912 .pipe(Effect.catchTag("ClientException", () => Effect.void));
913 }
914
915 // Deregistering only flips the revisions to INACTIVE — they still
916 // exist (and show up in `listTaskDefinitions --status INACTIVE`)
917 // forever. Hard-delete them so destroying a Task leaves zero
918 // task-definition leftovers. `deleteTaskDefinitions` accepts at most
919 // 10 ARNs per call.
920 for (let i = 0; i < revisionArns.length; i += 10) {
921 yield* ecs
922 .deleteTaskDefinitions({
923 taskDefinitions: revisionArns.slice(i, i + 10),
924 })
925 .pipe(Effect.catchTag("ClientException", () => Effect.void));
926 }
927
928 yield* ecr
929 .deleteRepository({
930 repositoryName: output.repositoryName,
931 force: true,
932 })
933 .pipe(Effect.catchTag("RepositoryNotFoundException", () => Effect.void));
934
935 yield* logs
936 .deleteLogGroup({
937 logGroupName: output.logGroupName,
938 })
939 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
940
941 for (const roleName of [output.taskRoleName, output.executionRoleName]) {
942 // Delete inline policies on BOTH roles — the task role carries the
943 // bindings policy, and the execution role can carry inline policies too
944 // (e.g. the Service's secrets-read policy). A role with any inline
945 // policy left rejects `deleteRole` with `DeleteConflictException`.
946 yield* iam.listRolePolicies
947 .items({
948 RoleName: roleName,
949 })
950 .pipe(
951 Stream.mapEffect((policyName) =>
952 iam
953 .deleteRolePolicy({
954 RoleName: roleName,
955 PolicyName: policyName,
956 })
957 .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
958 ),
959 Stream.runDrain,
960 // The role may already be gone (delete re-run / race) — treat a
961 // missing role as "no policies to delete" so delete is idempotent.
962 Effect.catchTag("NoSuchEntityException", () => Effect.void),
963 );
964
965 yield* iam.listAttachedRolePolicies
966 .items({
967 RoleName: roleName,
968 })
969 .pipe(
970 Stream.mapEffect((policy) =>
971 iam
972 .detachRolePolicy({
973 RoleName: roleName,
974 PolicyArn: policy.PolicyArn!,
975 })
976 .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
977 ),
978 Stream.runDrain,
979 Effect.catchTag("NoSuchEntityException", () => Effect.void),
980 );
981 yield* iam
982 .deleteRole({
983 RoleName: roleName,
984 })
985 .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
986 }
987 });
988
989 export const TaskProvider = () =>
990 Provider.effect(
991 Task,
992 Effect.gen(function* () {
993 const stack = yield* Stack;
994 const imageSource = yield* makeImageSource;
995
996 const alchemyEnv = {
997 ALCHEMY_STACK_NAME: stack.name,
998 ALCHEMY_STAGE: stack.stage,
999 ALCHEMY_PHASE: "runtime",
1000 };
1001
1002 const toTaskFamily = (id: string, props: { taskName?: string } = {}) =>
1003 props.taskName
1004 ? Effect.succeed(props.taskName)
1005 : createPhysicalName({
1006 id,
1007 maxLength: 255,
1008 lowercase: true,
1009 });
1010
1011 const createRoleName = (id: string, suffix: string) =>
1012 createPhysicalName({
1013 id: `${id}-${suffix}`,
1014 maxLength: 64,
1015 });
1016
1017 const createPolicyName = (id: string, suffix: string) =>
1018 createPhysicalName({
1019 id: `${id}-${suffix}`,
1020 maxLength: 128,
1021 });
1022
1023 const createRepositoryName = (id: string) =>
1024 createPhysicalName({
1025 id: `${id}-repo`,
1026 maxLength: 256,
1027 lowercase: true,
1028 });
1029
1030 const createLogGroupName = (id: string) =>
1031 createPhysicalName({
1032 id: `${id}-logs`,
1033 maxLength: 512,
1034 lowercase: true,
1035 });
1036
1037 // Reconstruct the full `Task` Attributes shape from a described task
1038 // definition. Returns `undefined` for task definitions that don't match
1039 // the shape this provider produces (single container whose image is an
1040 // ECR `<repoUri>:<hash>`, task/execution role ARNs, an awslogs log group)
1041 // so foreign task definitions in the account are skipped by `list()`.
1042 const toListAttributes = (
1043 taskDefinition: ecs.TaskDefinition,
1044 region: string,
1045 accountId: string,
1046 ): Task["Attributes"] | undefined => {
1047 if (!taskDefinition.taskDefinitionArn || !taskDefinition.family) {
1048 return undefined;
1049 }
1050 const container = taskDefinition.containerDefinitions?.[0];
1051 const image = container?.image;
1052 const taskRoleArn = taskDefinition.taskRoleArn;
1053 const executionRoleArn = taskDefinition.executionRoleArn;
1054 const logGroupName = container?.logConfiguration?.options?.["awslogs-group"];
1055 if (
1056 !container?.name ||
1057 !image ||
1058 !image.includes(":") ||
1059 !taskRoleArn ||
1060 !executionRoleArn ||
1061 !logGroupName
1062 ) {
1063 return undefined;
1064 }
1065 const lastColon = image.lastIndexOf(":");
1066 const repositoryUri = image.slice(0, lastColon);
1067 const hash = image.slice(lastColon + 1);
1068 const repositoryName = repositoryUri.split("/").slice(1).join("/");
1069 const taskRoleName = taskRoleArn.split(":role/")[1] ?? taskRoleArn;
1070 const executionRoleName = executionRoleArn.split(":role/")[1] ?? executionRoleArn;
1071 return {
1072 taskDefinitionArn: taskDefinition.taskDefinitionArn,
1073 taskFamily: taskDefinition.family,
1074 containerName: container.name,
1075 port: container.portMappings?.[0]?.containerPort ?? 3000,
1076 imageUri: image,
1077 repositoryName,
1078 repositoryUri,
1079 taskRoleArn,
1080 taskRoleName,
1081 executionRoleArn,
1082 executionRoleName,
1083 logGroupName,
1084 logGroupArn: `arn:aws:logs:${region}:${accountId}:log-group:${logGroupName}`,
1085 code: { hash },
1086 };
1087 };
1088
1089 return {
1090 stables: [
1091 "repositoryName",
1092 "repositoryUri",
1093 "taskRoleArn",
1094 "taskRoleName",
1095 "executionRoleArn",
1096 "executionRoleName",
1097 "logGroupName",
1098 "logGroupArn",
1099 "taskFamily",
1100 ],
1101 diff: Effect.fn(function* ({ id, olds, news, output }) {
1102 if (!isResolved(news)) return;
1103 if ((yield* toTaskFamily(id, olds ?? {})) !== (yield* toTaskFamily(id, news ?? {}))) {
1104 return { action: "replace" } as const;
1105 }
1106 // Content drift: the props don't change when files under a
1107 // `context` path (or the mirrored `image` ref's meaning) change —
1108 // nor, for `main` sources, when the user's program or the
1109 // generated bootstrap template changes. Hash the source (running
1110 // the bundler for `main`, so the hash covers the bootstrap entry)
1111 // and surface drift as an update; without this a bootstrap or
1112 // code-only change would silently no-op until `--force`.
1113 if (output) {
1114 const hash = yield* imageSource.hash(taskImageInput(news));
1115 if (hash !== undefined && hash !== output.code.hash) {
1116 return { action: "update" } as const;
1117 }
1118 }
1119 }),
1120 read: Effect.fn(function* ({ id, olds, output }) {
1121 const family = output?.taskFamily ?? (yield* toTaskFamily(id, olds ?? {}));
1122 const described = yield* ecs
1123 .describeTaskDefinition({
1124 taskDefinition: output?.taskDefinitionArn ?? family,
1125 })
1126 .pipe(Effect.catchTag("ClientException", () => Effect.undefined));
1127 const taskDefinition = described?.taskDefinition;
1128 if (!taskDefinition?.taskDefinitionArn) {
1129 return undefined;
1130 }
1131 if (!output) {
1132 return undefined;
1133 }
1134 return {
1135 ...output,
1136 taskDefinitionArn: taskDefinition.taskDefinitionArn,
1137 taskFamily: taskDefinition.family ?? family,
1138 containerName: taskDefinition.containerDefinitions?.[0]?.name ?? output.containerName,
1139 port:
1140 taskDefinition.containerDefinitions?.[0]?.portMappings?.[0]?.containerPort ??
1141 output.port,
1142 };
1143 }),
1144 reconcile: Effect.fn(function* ({ id, news, bindings, output, session }) {
1145 // Prefer the deployed name: regenerating would target a different
1146 // resource if the generator's output for this id ever drifts. (An
1147 // explicit taskName change arrives here as a fresh replacement
1148 // instance with no output.)
1149 const family = output?.taskFamily ?? (yield* toTaskFamily(id, news));
1150 const taskRoleName = output?.taskRoleName ?? (yield* createRoleName(id, "task-role"));
1151 const executionRoleName =
1152 output?.executionRoleName ?? (yield* createRoleName(id, "execution-role"));
1153 const taskPolicyName = yield* createPolicyName(id, "task-policy");
1154 const repositoryName = output?.repositoryName ?? (yield* createRepositoryName(id));
1155 const logGroupName = output?.logGroupName ?? (yield* createLogGroupName(id));
1156 const tags = {
1157 ...(yield* createInternalTags(id)),
1158 ...news.tags,
1159 };
1160
1161 // Ensure roles, repository, and log group. Each helper is
1162 // idempotent (creates on miss, adopts on race) so the same
1163 // sequence runs on initial create, adoption, or update.
1164 const taskRoleArn =
1165 output?.taskRoleArn ??
1166 (yield* createTaskRoleIfNotExists({ id, roleName: taskRoleName }));
1167 const executionRoleArn =
1168 output?.executionRoleArn ??
1169 (yield* ensureTaskExecutionRole({
1170 id,
1171 roleName: executionRoleName,
1172 managedPolicyArns: news.executionRoleManagedPolicyArns,
1173 }));
1174
1175 for (const policyArn of news.taskRoleManagedPolicyArns ?? []) {
1176 yield* iam
1177 .attachRolePolicy({
1178 RoleName: taskRoleName,
1179 PolicyArn: policyArn,
1180 })
1181 .pipe(Effect.catchTag("LimitExceededException", () => Effect.void));
1182 }
1183
1184 // Environment files: the execution role reads the referenced S3
1185 // objects at task start.
1186 yield* syncEnvironmentFilesPolicy({
1187 roleName: executionRoleName,
1188 environmentFiles: news.environmentFiles,
1189 });
1190
1191 const {
1192 env: bindingEnv,
1193 volumes: bindingVolumes,
1194 mountPoints: bindingMountPoints,
1195 } = yield* attachTaskBindings({
1196 roleName: taskRoleName,
1197 policyName: taskPolicyName,
1198 bindings,
1199 });
1200
1201 const logGroupArn =
1202 output?.logGroupArn ??
1203 (yield* ensureTaskLogGroup({
1204 id,
1205 logGroupName,
1206 }));
1207 yield* syncLogGroupRetention({
1208 logGroupName,
1209 retention: news.logging?.retention,
1210 });
1211
1212 // Resolve the container image from whichever source the props
1213 // declare (`main` | `context` | `image`), building/mirroring and
1214 // pushing into the task's ECR repository, then register a new
1215 // task definition revision. Task definitions are versioned in
1216 // AWS, so registering a new revision is the unit of "update" —
1217 // the superseded revision is reaped after registration below.
1218 const resolved = yield* imageSource.resolve({
1219 ...taskImageInput(news),
1220 id,
1221 repositoryName,
1222 repositoryUri:
1223 output?.repositoryUri && output.repositoryName === repositoryName
1224 ? output.repositoryUri
1225 : undefined,
1226 tags,
1227 session,
1228 });
1229
1230 const taskDefinition = yield* registerTaskDefinitionRevision({
1231 props: {
1232 ...news,
1233 env: {
1234 ...bindingEnv,
1235 ...alchemyEnv,
1236 ...news.env,
1237 },
1238 },
1239 family,
1240 imageUri: resolved.imageUri,
1241 taskRoleArn,
1242 executionRoleArn,
1243 logGroupName,
1244 tags,
1245 bindingVolumes,
1246 bindingMountPoints,
1247 });
1248
1249 // Sync tags — task definition revisions carry tags at register
1250 // time, but tags are mutable on the revision ARN. Diff the observed
1251 // revision tags against desired so tag-only updates converge.
1252 yield* syncTaskDefinitionTags({
1253 revisionArn: taskDefinition.taskDefinitionArn!,
1254 tags,
1255 });
1256
1257 // The registration above superseded the previously-recorded
1258 // revision — reap it so revisions don't accumulate ACTIVE forever.
1259 yield* reapSupersededTaskDefinitionRevision({
1260 previousArn: output?.taskDefinitionArn,
1261 nextArn: taskDefinition.taskDefinitionArn!,
1262 });
1263
1264 yield* session.note(taskDefinition.taskDefinitionArn!);
1265 return {
1266 taskDefinitionArn: taskDefinition.taskDefinitionArn!,
1267 taskFamily: family,
1268 containerName: taskDefinition.containerDefinitions?.[0]?.name ?? family,
1269 port: news.port ?? output?.port ?? 3000,
1270 imageUri: resolved.imageUri,
1271 repositoryName: resolved.repositoryName,
1272 repositoryUri: resolved.repositoryUri,
1273 taskRoleArn,
1274 taskRoleName,
1275 executionRoleArn,
1276 executionRoleName,
1277 logGroupName,
1278 logGroupArn,
1279 code: {
1280 hash: resolved.codeHash,
1281 },
1282 };
1283 }),
1284 // Enumerate every ACTIVE task definition in the account/region,
1285 // hydrate each via `describeTaskDefinition`, and reconstruct the full
1286 // Attributes shape. Foreign task definitions that don't match the shape
1287 // this provider produces are skipped (see `toListAttributes`).
1288 list: () =>
1289 Effect.gen(function* () {
1290 const { accountId, region } = yield* AWSEnvironment.current;
1291 const arns = yield* ecs.listTaskDefinitions.pages({ status: "ACTIVE" }).pipe(
1292 Stream.runCollect,
1293 Effect.map((chunk) =>
1294 Array.from(chunk).flatMap((page) => page.taskDefinitionArns ?? []),
1295 ),
1296 );
1297 const rows = yield* Effect.forEach(
1298 arns,
1299 (arn) =>
1300 ecs.describeTaskDefinition({ taskDefinition: arn }).pipe(
1301 Effect.map((described) =>
1302 described.taskDefinition
1303 ? toListAttributes(described.taskDefinition, region, accountId)
1304 : undefined,
1305 ),
1306 Effect.catchTag("ClientException", () => Effect.undefined),
1307 ),
1308 { concurrency: 10 },
1309 );
1310 return rows.filter((row): row is Task["Attributes"] => row !== undefined);
1311 }),
1312 delete: Effect.fn(function* ({ output }) {
1313 yield* deleteTaskDefinitionInfrastructure(output);
1314 }),
1315 };
1316 }),
1317 );