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

main
ts 486 lines 18.5 KB
Raw
1 import { hashDockerBuildInputs, resolveDockerBuildPaths } from "@alchemy.run/docker/BuildHash";
2 import { Docker } from "@alchemy.run/docker/Docker";
3 import * as ecr from "@distilled.cloud/aws/ecr";
4 import { isResolved } from "alchemy/Diff";
5 import { createPhysicalName } from "alchemy/PhysicalName";
6 import * as Provider from "alchemy/Provider";
7 import { Resource } from "alchemy/Resource";
8 import { createInternalTags } from "alchemy/Tags";
9 import * as Data from "effect/Data";
10 import * as Effect from "effect/Effect";
11 import * as Redacted from "effect/Redacted";
12 import * as Schedule from "effect/Schedule";
13 import * as Stream from "effect/Stream";
14 import type { Providers } from "../Providers.ts";
15
16 export class ImageUnexpectedResponse extends Data.TaggedError("ImageUnexpectedResponse")<{
17 readonly message: string;
18 readonly cause?: unknown;
19 }> {}
20
21 /**
22 * Docker login credentials for the account's private ECR registry, in the
23 * shape `Docker.image.push` expects. The password is the decoded ECR bearer
24 * token — a credential — so it is carried as `Redacted` and only unwrapped
25 * inside `docker push`'s ephemeral auth config.
26 */
27 export interface EcrRegistryCredentials {
28 username: string;
29 password: Redacted.Redacted<string>;
30 server: string;
31 }
32
33 /**
34 * Resolves Docker login credentials for the account's private ECR registry
35 * by decoding `ecr.getAuthorizationToken`.
36 */
37 export const getEcrRegistryCredentials = Effect.gen(function* () {
38 const auth = yield* ecr.getAuthorizationToken({});
39 const authData = auth.authorizationData?.[0];
40 const token = authData?.authorizationToken;
41 const proxyEndpoint = authData?.proxyEndpoint;
42 if (!token || !proxyEndpoint) {
43 return yield* Effect.die(new Error("Failed to get ECR authorization token"));
44 }
45 const password = yield* Effect.sync(() => {
46 const raw = Redacted.isRedacted(token) ? Redacted.value(token) : token;
47 const decoded = Buffer.from(raw, "base64").toString("utf8");
48 const [, secret] = decoded.split(":", 2);
49 return Redacted.make(secret);
50 });
51 return {
52 username: "AWS",
53 password,
54 server: proxyEndpoint.replace(/^https?:\/\//, ""),
55 } satisfies EcrRegistryCredentials;
56 });
57
58 /**
59 * Builds a Docker image from a local context and pushes it to the account's
60 * private ECR registry. Shared by the `ECR.Image` provider and the
61 * `ECS.Task` runtime resource (which materializes a generated Dockerfile
62 * into its bundle context before delegating here).
63 */
64 export const buildAndPushEcrImage = Effect.fn(function* (
65 docker: Docker["Service"],
66 options: {
67 /** Full image reference to build and push, e.g. `<repositoryUri>:<tag>`. */
68 imageUri: string;
69 /** Docker build context directory. */
70 context: string;
71 /** Absolute path to the Dockerfile. Defaults to `Dockerfile` in `context`. */
72 dockerfile?: string;
73 /** Target platform, e.g. `"linux/amd64"`. */
74 platform?: string;
75 /** Docker build arguments. */
76 buildArgs?: Record<string, string>;
77 /** Additional arguments appended to `docker image build`. */
78 args?: string[];
79 },
80 ) {
81 const credentials = yield* getEcrRegistryCredentials;
82 yield* docker.image.build({
83 tag: options.imageUri,
84 context: options.context,
85 file: options.dockerfile,
86 platform: options.platform,
87 "build-arg": options.buildArgs,
88 args: options.args,
89 });
90 // Pushes are idempotent; transient registry-transport failures (Docker
91 // Desktop's embedded proxy timing out under load, ECR 503s, credential
92 // helper contention) resolve on a bounded re-attempt.
93 yield* docker.image.push(options.imageUri, credentials).pipe(
94 Effect.retry({
95 while: (): boolean => true,
96 schedule: Schedule.exponential("2 seconds"),
97 times: 3,
98 }),
99 );
100 return options.imageUri;
101 });
102
103 export interface ImageProps {
104 /**
105 * URI of the target ECR repository, e.g. `repository.repositoryUri` from an
106 * `ECR.Repository`. When omitted, the Image auto-creates (and owns) a
107 * repository whose name is derived from the logical id; the owned
108 * repository is force-deleted when the Image is destroyed.
109 */
110 repositoryUri?: string;
111 /**
112 * Docker build context directory. The files Docker receives from the
113 * context (after `.dockerignore`), plus the Dockerfile, platform, and build
114 * args, participate in the content hash that identifies the image. Ignored
115 * files are never read and never change the tag. An existing image with the
116 * same hash is reused; missing images are rebuilt and pushed to the desired
117 * repository.
118 */
119 context: string;
120 /**
121 * Path to the Dockerfile, relative to `context` unless absolute.
122 * @default "Dockerfile"
123 */
124 dockerfile?: string;
125 /**
126 * Target platform for the image build. Fargate defaults to X86_64, so the
127 * default pins `linux/amd64` — without it an image built on an ARM64 host
128 * (e.g. Apple Silicon) is rejected at task start.
129 * @default "linux/amd64"
130 */
131 platform?: string;
132 /**
133 * Docker build arguments (`--build-arg`).
134 */
135 buildArgs?: Record<string, string>;
136 }
137
138 export interface Image extends Resource<
139 "AWS.ECR.Image",
140 ImageProps,
141 {
142 /** Full image reference, `<repositoryUri>:<imageTag>`. */
143 imageUri: string;
144 /** Registry manifest digest, e.g. `sha256:...`. */
145 digest: string;
146 /** URI of the repository the image was pushed to. */
147 repositoryUri: string;
148 /** Name of the repository the image was pushed to. */
149 repositoryName: string;
150 /** Content-hash tag the image was pushed under. */
151 imageTag: string;
152 /** Whether this Image auto-created (and owns) the backing repository. */
153 ownsRepository: boolean;
154 },
155 never,
156 Providers
157 > {}
158
159 /**
160 * A Docker image built from a local context and pushed to a private Amazon
161 * ECR repository.
162 *
163 * The image is identified by a content hash over the build context,
164 * Dockerfile, platform, and build args. An existing image with that hash is
165 * reused; a missing image is rebuilt and pushed. A content change produces a
166 * new tag on the same resource, so replacement is never needed.
167 *
168 * ### Building Images
169 * **Example:** Push to an ECR Repository
170 * ```typescript
171 * const repository = yield* AWS.ECR.Repository("AppRepository", {});
172 * const image = yield* AWS.ECR.Image("AppImage", {
173 * repositoryUri: repository.repositoryUri,
174 * context: "./app",
175 * });
176 * ```
177 *
178 * **Example:** Auto-created Repository
179 * ```typescript
180 * const image = yield* AWS.ECR.Image("AppImage", {
181 * context: "./app",
182 * });
183 * ```
184 *
185 * ### Moving an Unchanged Build Context
186 * **Example:** Relocate identical build inputs without rebuilding
187 * ```diff
188 * const image = yield* AWS.ECR.Image("AppImage", {
189 * repositoryUri: repository.repositoryUri,
190 * - context: "./app",
191 * + context: "./relocated-app",
192 * });
193 * ```
194 *
195 * Absolute paths are not part of the image's identity. With identical build
196 * inputs and the same repository setting, this plans a no-op. Content,
197 * Dockerfile, platform, build-argument, and repository changes still update
198 * the image. A deleted image or auto-created repository is recreated on deploy.
199 *
200 * ### Ignoring Files with `.dockerignore`
201 * **Example:** Build from the repository root
202 * ```typescript
203 * // .dockerignore next to the context keeps node_modules/ and target/ out
204 * const image = yield* AWS.ECR.Image("ServiceImage", {
205 * repositoryUri: repository.repositoryUri,
206 * context: "..",
207 * dockerfile: "docker/service.Dockerfile",
208 * });
209 * ```
210 *
211 * The content hash covers only the files Docker receives, so ignored trees
212 * are never read and a local `bun install` or `cargo build` does not change
213 * the tag. A `<Dockerfile>.dockerignore` takes precedence over the context's
214 * `.dockerignore`, as in Docker.
215 *
216 * ### Build Configuration
217 * **Example:** Custom Dockerfile, Platform, and Build Args
218 * ```typescript
219 * const image = yield* AWS.ECR.Image("WorkerImage", {
220 * repositoryUri: repository.repositoryUri,
221 * context: "./worker",
222 * dockerfile: "Dockerfile.worker",
223 * platform: "linux/arm64",
224 * buildArgs: { NODE_ENV: "production" },
225 * });
226 * ```
227 *
228 * ### Consuming the Image
229 * **Example:** Reference from a Task Definition
230 * ```typescript
231 * const task = yield* AWS.ECS.Task("ApiTask", {
232 * main: import.meta.url,
233 * sidecars: [{ name: "proxy", image: image.imageUri, essential: false }],
234 * });
235 * ```
236 *
237 * @resource
238 */
239 export const Image = Resource<Image>("AWS.ECR.Image");
240
241 /** Derives the repository name from a repository URI (`<registry>/<name>`). */
242 const repositoryNameFromUri = (repositoryUri: string) =>
243 repositoryUri.split("/").slice(1).join("/");
244
245 export const ImageProvider = () =>
246 Provider.effect(
247 Image,
248 Effect.gen(function* () {
249 const docker = yield* Docker;
250
251 const toOwnedRepositoryName = (id: string) =>
252 createPhysicalName({
253 id,
254 maxLength: 256,
255 lowercase: true,
256 });
257
258 // Content hash over everything that affects the built image: the
259 // Dockerfile, the context files `.dockerignore` keeps (relative path + bytes),
260 // the target platform, and the build args. Absolute paths deliberately
261 // do NOT participate, so relocating an identical context (e.g. a temp
262 // dir) produces the same tag.
263 const hashBuildInputs = (props: ImageProps) =>
264 hashDockerBuildInputs(
265 {
266 context: props.context,
267 dockerfile: props.dockerfile ?? "Dockerfile",
268 platform: props.platform ?? "linux/amd64",
269 buildArgs: props.buildArgs,
270 },
271 "effective",
272 );
273
274 // Observe the pushed image in ECR. Missing repository or tag → undefined.
275 const describeImage = Effect.fn(function* (repositoryName: string, imageTag: string) {
276 const described = yield* ecr
277 .describeImages({
278 repositoryName,
279 imageIds: [{ imageTag }],
280 })
281 .pipe(
282 Effect.catchTag(
283 ["ImageNotFoundException", "RepositoryNotFoundException"],
284 () => Effect.undefined,
285 ),
286 );
287 return described?.imageDetails?.[0];
288 });
289
290 // Ensure the auto-created repository exists. Idempotent: tolerates
291 // `RepositoryAlreadyExistsException` as a race / re-run and re-describes.
292 const ensureOwnedRepository = Effect.fn(function* (id: string, repositoryName: string) {
293 const internalTags = yield* createInternalTags(id);
294 const created = yield* ecr
295 .createRepository({
296 repositoryName,
297 imageTagMutability: "MUTABLE",
298 tags: Object.entries(internalTags).map(([Key, Value]) => ({
299 Key,
300 Value,
301 })),
302 })
303 .pipe(
304 Effect.catchTag("RepositoryAlreadyExistsException", () =>
305 ecr
306 .describeRepositories({ repositoryNames: [repositoryName] })
307 .pipe(Effect.map((res) => ({ repository: res.repositories?.[0] }))),
308 ),
309 );
310 const repositoryUri = created.repository?.repositoryUri;
311 if (!repositoryUri) {
312 return yield* new ImageUnexpectedResponse({
313 message: `Failed to create or read ECR repository '${repositoryName}'`,
314 });
315 }
316 return repositoryUri;
317 });
318
319 return {
320 read: Effect.fn(function* ({ output }) {
321 // The content hash cannot be recovered without running a build, so
322 // a lost-state read has nothing to look up.
323 if (!output) return undefined;
324 const detail = yield* describeImage(output.repositoryName, output.imageTag);
325 if (!detail?.imageDigest) return undefined;
326 return { ...output, digest: detail.imageDigest };
327 }),
328 // Content changes don't change Props (the context path stays the
329 // same while the files under it change), so surface them here: hash
330 // the build inputs and request an update when the hash drifts from
331 // the pushed tag. Replacement is never needed — a new hash is just a
332 // new tag + digest on the same resource.
333 diff: Effect.fn(function* ({ news, output, olds }) {
334 if (!isResolved(news) || !output) return undefined;
335 const hash = yield* hashBuildInputs(news);
336 if (hash !== output.imageTag || olds.repositoryUri !== news.repositoryUri) {
337 return { action: "update" } as const;
338 }
339 const image = yield* describeImage(output.repositoryName, hash);
340 if (!image?.imageDigest) return { action: "update" } as const;
341 // Build paths may move without changing an existing image.
342 return { action: "noop" } as const;
343 }),
344 reconcile: Effect.fn(function* ({ id, news, output, session }) {
345 // Resolve the target repository: user-supplied URI, or an
346 // auto-created repository owned by this Image.
347 const resolveRepository = Effect.gen(function* () {
348 if (news.repositoryUri) {
349 return {
350 repositoryName: repositoryNameFromUri(news.repositoryUri),
351 repositoryUri: news.repositoryUri,
352 ownsRepository: false,
353 };
354 }
355 const repositoryName = output?.ownsRepository
356 ? output.repositoryName
357 : yield* toOwnedRepositoryName(id);
358 const repositoryUri = yield* ensureOwnedRepository(id, repositoryName);
359 return { repositoryName, repositoryUri, ownsRepository: true };
360 });
361 const { repositoryName, repositoryUri, ownsRepository } = yield* resolveRepository;
362
363 const { context, dockerfile } = yield* resolveDockerBuildPaths({
364 context: news.context,
365 dockerfile: news.dockerfile ?? "Dockerfile",
366 });
367 const imageTag = yield* hashBuildInputs(news);
368 const imageUri = `${repositoryUri}:${imageTag}`;
369
370 // Observe — if this exact content hash is already pushed, there is
371 // nothing to build (crash-safe: a re-run after a mid-reconcile
372 // failure converges without a rebuild).
373 const observed = yield* describeImage(repositoryName, imageTag);
374 if (observed?.imageDigest) {
375 yield* session.note(imageUri);
376 return {
377 imageUri,
378 digest: observed.imageDigest,
379 repositoryUri,
380 repositoryName,
381 imageTag,
382 ownsRepository,
383 };
384 }
385
386 yield* session.note(`building ${imageUri}`);
387 yield* buildAndPushEcrImage(docker, {
388 imageUri,
389 context,
390 dockerfile,
391 platform: news.platform ?? "linux/amd64",
392 buildArgs: news.buildArgs,
393 // Engines using the containerd image store attach provenance
394 // attestations by default, turning the pushed tag into an OCI
395 // image index — which Lambda (a valid consumer of these images)
396 // rejects. Disable: single-manifest pushes work everywhere.
397 args: ["--provenance=false"],
398 });
399
400 const pushed = yield* describeImage(repositoryName, imageTag);
401 if (!pushed?.imageDigest) {
402 return yield* new ImageUnexpectedResponse({
403 message: `Image ${imageUri} not found in ECR after push`,
404 });
405 }
406 yield* session.note(imageUri);
407 return {
408 imageUri,
409 digest: pushed.imageDigest,
410 repositoryUri,
411 repositoryName,
412 imageTag,
413 ownsRepository,
414 };
415 }),
416 // Enumerate every tagged image across every repository in the
417 // account/region. Repository ownership is recorded per-instance in
418 // state and cannot be recovered from enumeration, so listed items are
419 // conservatively marked `ownsRepository: false` — orphan deletion
420 // removes the tag but leaves the repository (ECR.Repository's own
421 // list()/delete() covers repositories).
422 list: () =>
423 Effect.gen(function* () {
424 const repositories = yield* ecr.describeRepositories.pages({}).pipe(
425 Stream.runCollect,
426 Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.repositories ?? [])),
427 );
428 const nested = yield* Effect.forEach(
429 repositories.filter(
430 (
431 r,
432 ): r is ecr.Repository & {
433 repositoryName: string;
434 repositoryUri: string;
435 } => r.repositoryName != null && r.repositoryUri != null,
436 ),
437 (repository) =>
438 ecr.describeImages.pages({ repositoryName: repository.repositoryName }).pipe(
439 Stream.runCollect,
440 Effect.map((chunk) =>
441 Array.from(chunk).flatMap((page) => page.imageDetails ?? []),
442 ),
443 Effect.map((details) =>
444 details.flatMap((detail) =>
445 detail.imageDigest === undefined
446 ? []
447 : (detail.imageTags ?? []).map((imageTag) => ({
448 imageUri: `${repository.repositoryUri}:${imageTag}`,
449 digest: detail.imageDigest!,
450 repositoryUri: repository.repositoryUri,
451 repositoryName: repository.repositoryName,
452 imageTag,
453 ownsRepository: false,
454 })),
455 ),
456 ),
457 // Repository deleted between the list and the describe.
458 Effect.catchTag("RepositoryNotFoundException", () => Effect.succeed([])),
459 ),
460 { concurrency: 10 },
461 );
462 return nested.flat();
463 }),
464 delete: Effect.fn(function* ({ output }) {
465 if (output.ownsRepository) {
466 yield* ecr
467 .deleteRepository({
468 repositoryName: output.repositoryName,
469 force: true,
470 })
471 .pipe(Effect.catchTag("RepositoryNotFoundException", () => Effect.void));
472 return;
473 }
474 // Foreign repository: delete only our tag. `batchDeleteImage`
475 // reports a missing image via its `failures` array (not an error),
476 // so this is naturally idempotent.
477 yield* ecr
478 .batchDeleteImage({
479 repositoryName: output.repositoryName,
480 imageIds: [{ imageTag: output.imageTag }],
481 })
482 .pipe(Effect.catchTag("RepositoryNotFoundException", () => Effect.void));
483 }),
484 };
485 }),
486 );