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

main
ts 569 lines 18.9 KB
Raw
1 import * as ec2 from "@distilled.cloud/aws/ec2";
2 import { isResolved, somePropsAreDifferent } from "alchemy/Diff";
3 import * as Provider from "alchemy/Provider";
4 import type { ScopedPlanStatusSession } from "alchemy/Report";
5 import { Resource } from "alchemy/Resource";
6 import {
7 createAlchemyTagFilters,
8 createInternalTags,
9 createTagsList,
10 diffTags,
11 } from "alchemy/Tags";
12 import * as Data from "effect/Data";
13 import * as Effect from "effect/Effect";
14 import * as Schedule from "effect/Schedule";
15 import * as Stream from "effect/Stream";
16 import type { AccountID } from "../Environment.ts";
17 import { AWSEnvironment } from "../Environment.ts";
18 import type { Providers } from "../Providers.ts";
19 import type { RegionID } from "../Region.ts";
20
21 export type VolumeId<ID extends string = string> = `vol-${ID}`;
22 export const VolumeId = <ID extends string>(id: ID): ID & VolumeId<ID> =>
23 `vol-${id}` as ID & VolumeId<ID>;
24
25 export type VolumeArn = `arn:aws:ec2:${RegionID}:${AccountID}:volume/${VolumeId}`;
26
27 export interface VolumeProps {
28 /**
29 * The Availability Zone in which to create the volume, e.g. `us-east-1a`.
30 * Required. An EBS volume is bound to a single AZ; changing it replaces the
31 * volume.
32 */
33 availabilityZone: string;
34
35 /**
36 * The size of the volume, in GiB. Required unless you create the volume from
37 * a `snapshotId` (in which case it defaults to the snapshot size). The size
38 * can be increased in place via `modifyVolume`; decreasing it replaces the
39 * volume.
40 */
41 size?: number;
42
43 /**
44 * The volume type.
45 * @default "gp3"
46 */
47 volumeType?: ec2.VolumeType;
48
49 /**
50 * The number of I/O operations per second (IOPS). Only valid for `io1`,
51 * `io2`, and `gp3` volumes. Mutable in place via `modifyVolume`.
52 */
53 iops?: number;
54
55 /**
56 * The throughput to provision, in MiB/s. Only valid for `gp3` volumes.
57 * Mutable in place via `modifyVolume`.
58 */
59 throughput?: number;
60
61 /**
62 * Whether the volume is encrypted. Changing this replaces the volume.
63 * @default false
64 */
65 encrypted?: boolean;
66
67 /**
68 * The identifier of the KMS key to use for encryption. Can be a key ID, key
69 * ARN, alias name (`alias/my-key`), or alias ARN. Implies `encrypted: true`.
70 * Changing this replaces the volume.
71 */
72 kmsKeyId?: string;
73
74 /**
75 * The snapshot from which to create the volume. Changing this replaces the
76 * volume.
77 */
78 snapshotId?: string;
79
80 /**
81 * Whether the volume can be attached to multiple instances (Multi-Attach).
82 * Only valid for `io1`/`io2` volumes.
83 * @default false
84 */
85 multiAttachEnabled?: boolean;
86
87 /**
88 * Tags to assign to the volume. Merged with alchemy auto-tags
89 * (alchemy::stack, alchemy::stage, alchemy::id).
90 */
91 tags?: Record<string, string>;
92 }
93
94 export interface Volume extends Resource<
95 "AWS.EC2.Volume",
96 VolumeProps,
97 {
98 /**
99 * The ID of the volume.
100 */
101 volumeId: VolumeId;
102
103 /**
104 * The Amazon Resource Name (ARN) of the volume.
105 */
106 volumeArn: VolumeArn;
107
108 /**
109 * The Availability Zone of the volume.
110 */
111 availabilityZone: string;
112
113 /**
114 * The size of the volume, in GiB.
115 */
116 size: number;
117
118 /**
119 * The volume type.
120 */
121 volumeType: ec2.VolumeType;
122
123 /**
124 * The number of IOPS provisioned for the volume.
125 */
126 iops?: number;
127
128 /**
129 * The throughput provisioned for the volume, in MiB/s.
130 */
131 throughput?: number;
132
133 /**
134 * Whether the volume is encrypted.
135 */
136 encrypted: boolean;
137
138 /**
139 * The KMS key used for encryption, if any.
140 */
141 kmsKeyId?: string;
142
143 /**
144 * The snapshot the volume was created from, if any.
145 */
146 snapshotId?: string;
147
148 /**
149 * Whether Multi-Attach is enabled.
150 */
151 multiAttachEnabled: boolean;
152
153 /**
154 * The current state of the volume.
155 */
156 state: ec2.VolumeState;
157 },
158 never,
159 Providers
160 > {}
161 /**
162 * An Elastic Block Store (EBS) volume — durable block storage you attach to an
163 * EC2 instance via a {@link VolumeAttachment}. Volumes live in a single
164 * Availability Zone and persist independently of any instance.
165 *
166 * Changing `availabilityZone`, `encrypted`, `kmsKeyId`, `snapshotId`, or
167 * shrinking `size` replaces the volume. Growing `size` and changing `iops`,
168 * `throughput`, or `volumeType` are applied in place via `modifyVolume` (note
169 * AWS enforces a 6-hour cooldown between volume modifications).
170 *
171 * ### Creating a Volume
172 * **Example:** Basic gp3 Volume
173 * ```typescript
174 * const volume = yield* AWS.EC2.Volume("DataVolume", {
175 * availabilityZone: "us-east-1a",
176 * size: 20,
177 * volumeType: "gp3",
178 * });
179 * ```
180 *
181 * The minimal volume: a 20 GiB general-purpose `gp3` volume in one AZ. It must
182 * be in the same AZ as the instance you attach it to.
183 *
184 * ### Provisioned Performance
185 * **Example:** gp3 with Provisioned IOPS and Throughput
186 * ```typescript
187 * const fast = yield* AWS.EC2.Volume("FastVolume", {
188 * availabilityZone: "us-east-1a",
189 * size: 100,
190 * volumeType: "gp3",
191 * iops: 6000,
192 * throughput: 250,
193 * });
194 * ```
195 *
196 * `gp3` decouples IOPS and throughput from size, so you can provision up to
197 * 16,000 IOPS and 1,000 MiB/s independently. Use `io2` for the highest
198 * durability and IOPS ceilings.
199 *
200 * ### Encryption
201 * **Example:** Encrypted Volume with a KMS Key
202 * ```typescript
203 * const secure = yield* AWS.EC2.Volume("SecureVolume", {
204 * availabilityZone: "us-east-1a",
205 * size: 20,
206 * encrypted: true,
207 * kmsKeyId: "alias/my-app-key",
208 * });
209 * ```
210 *
211 * Setting `kmsKeyId` implies encryption. Omit it while setting `encrypted:
212 * true` to use the account's default EBS KMS key.
213 *
214 * ### Creating from a Snapshot
215 * **Example:** Restore a Volume from a Snapshot
216 * ```typescript
217 * const restored = yield* AWS.EC2.Volume("RestoredVolume", {
218 * availabilityZone: "us-east-1a",
219 * snapshotId: snapshot.snapshotId,
220 * });
221 * ```
222 *
223 * When you create a volume from a snapshot, `size` defaults to the snapshot's
224 * size and can only be grown, never shrunk.
225 *
226 * @resource
227 */
228 export const Volume = Resource<Volume>("AWS.EC2.Volume");
229
230 export const VolumeProvider = () =>
231 Provider.effect(
232 Volume,
233 Effect.gen(function* () {
234 // EBS volume IDs are server-assigned. Recover a successfully created
235 // volume after state persistence failure via the resource instance tag;
236 // logical-id-only tags are insufficient during replacement because the
237 // old and new volume instances can coexist.
238 const findVolumeByInstanceTags = Effect.fn(function* (id: string, instanceId: string) {
239 const filters = yield* createAlchemyTagFilters(id);
240 const pages = yield* ec2.describeVolumes
241 .pages({
242 Filters: [...filters, { Name: "tag:alchemy::instance", Values: [instanceId] }],
243 })
244 .pipe(Stream.runCollect);
245 return Array.from(pages)
246 .flatMap((page) => page.Volumes ?? [])
247 .find((volume) => volume.State !== "deleting" && volume.State !== "deleted");
248 });
249
250 // Try the cached volume id first, then the ownership-tag lookup. A
251 // volume that is deleting or deleted counts as missing.
252 const observeVolume = Effect.fn(function* (
253 id: string,
254 instanceId: string,
255 volumeId: string | undefined,
256 ) {
257 if (volumeId) {
258 const lookup = yield* ec2
259 .describeVolumes({ VolumeIds: [volumeId] })
260 .pipe(Effect.catchTag("InvalidVolume.NotFound", () => Effect.succeed({ Volumes: [] })));
261 const found = lookup.Volumes?.[0];
262 if (found && found.State !== "deleting" && found.State !== "deleted") {
263 return found;
264 }
265 }
266 return yield* findVolumeByInstanceTags(id, instanceId);
267 });
268
269 return {
270 stables: [
271 "volumeId",
272 "volumeArn",
273 "availabilityZone",
274 "encrypted",
275 "kmsKeyId",
276 "snapshotId",
277 ],
278
279 diff: Effect.fn(function* ({ news, olds }) {
280 if (!isResolved(news)) return;
281 if (
282 somePropsAreDifferent(olds, news, [
283 "availabilityZone",
284 "encrypted",
285 "kmsKeyId",
286 "snapshotId",
287 ])
288 ) {
289 return { action: "replace" };
290 }
291 // Shrinking a volume is not supported in place — replace.
292 if (olds.size !== undefined && news.size !== undefined && news.size < olds.size) {
293 return { action: "replace" };
294 }
295 }),
296
297 read: Effect.fn(function* ({ id, instanceId, output }) {
298 const { accountId, region } = yield* AWSEnvironment.current;
299 const volume = yield* observeVolume(id, instanceId, output?.volumeId);
300 return volume ? toVolumeAttributes(volume, region, accountId) : undefined;
301 }),
302
303 reconcile: Effect.fn(function* ({ id, instanceId, news, output, session }) {
304 const { accountId, region } = yield* AWSEnvironment.current;
305 const alchemyTags = yield* createInternalTags(id);
306 const desiredTags = {
307 ...news.tags,
308 ...alchemyTags,
309 "alchemy::instance": instanceId,
310 };
311
312 // 1. OBSERVE — cloud state is authoritative; output is only an id
313 // cache. A volume in a terminal state is treated as missing.
314 let volume = yield* observeVolume(id, instanceId, output?.volumeId);
315
316 // 2. ENSURE — create the volume when missing, then wait until it is
317 // available. The ClientToken is this generation plus the last
318 // volume it created, so a create retried after a lost reply
319 // returns the first volume, and a recreate after the volume was
320 // deleted sends a new token.
321 if (volume === undefined) {
322 const create = (clientToken: string | undefined) =>
323 ec2.createVolume({
324 AvailabilityZone: news.availabilityZone,
325 Size: news.size,
326 VolumeType: news.volumeType ?? "gp3",
327 Iops: news.iops,
328 Throughput: news.throughput,
329 Encrypted: news.encrypted ?? (news.kmsKeyId !== undefined ? true : undefined),
330 KmsKeyId: news.kmsKeyId,
331 SnapshotId: news.snapshotId,
332 MultiAttachEnabled: news.multiAttachEnabled,
333 ClientToken: clientToken,
334 TagSpecifications: [
335 {
336 ResourceType: "volume",
337 Tags: createTagsList(desiredTags),
338 },
339 ],
340 DryRun: false,
341 });
342 // EC2 refuses a token whose volume was deleted, which a recreate
343 // with no saved volume id (Drift.repair) runs into. Step to the
344 // next token in a fixed sequence, so a retry after a lost reply
345 // walks the same sequence and returns the same volume.
346 const token = `${instanceId}-${output?.volumeId ?? "initial"}`;
347 const createFrom = (
348 attempt: number,
349 ): Effect.Effect<
350 ec2.Volume,
351 Effect.Error<ReturnType<typeof create>>,
352 Effect.Services<ReturnType<typeof create>>
353 > =>
354 create(attempt === 0 ? token : `${token}-${attempt}`).pipe(
355 Effect.catchTag("IdempotentVolumeDeleted", (e) =>
356 attempt < 8 ? createFrom(attempt + 1) : Effect.fail(e),
357 ),
358 );
359 const created = yield* createFrom(0);
360 const volumeId = created.VolumeId! as VolumeId;
361 yield* session.note(`Volume created: ${volumeId}`);
362 volume = yield* waitForVolumeAvailable(volumeId, session);
363 }
364
365 const volumeId = volume.VolumeId! as VolumeId;
366
367 // 3. SYNC — grow size / adjust performance in place. Only include a
368 // field when the user specified it AND it drifts from observed
369 // cloud state, so a no-op reconcile never triggers the 6h
370 // modification cooldown.
371 const modify: ec2.ModifyVolumeRequest = { VolumeId: volumeId };
372 let needsModify = false;
373 if (news.size !== undefined && news.size > (volume.Size ?? 0)) {
374 modify.Size = news.size;
375 needsModify = true;
376 }
377 if (news.volumeType !== undefined && news.volumeType !== volume.VolumeType) {
378 modify.VolumeType = news.volumeType;
379 needsModify = true;
380 }
381 if (news.iops !== undefined && news.iops !== volume.Iops) {
382 modify.Iops = news.iops;
383 needsModify = true;
384 }
385 if (news.throughput !== undefined && news.throughput !== volume.Throughput) {
386 modify.Throughput = news.throughput;
387 needsModify = true;
388 }
389 if (needsModify) {
390 yield* ec2.modifyVolume(modify);
391 yield* session.note(`Volume modified: ${volumeId}`);
392 }
393
394 // 3b. SYNC TAGS — diff against observed cloud tags.
395 const currentTags = Object.fromEntries(
396 (volume.Tags ?? []).map((t) => [t.Key!, t.Value!]),
397 ) as Record<string, string>;
398 const { removed, upsert } = diffTags(currentTags, desiredTags);
399 if (removed.length > 0) {
400 yield* ec2.deleteTags({
401 Resources: [volumeId],
402 Tags: removed.map((key) => ({ Key: key })),
403 DryRun: false,
404 });
405 }
406 if (upsert.length > 0) {
407 yield* ec2.createTags({
408 Resources: [volumeId],
409 Tags: upsert,
410 DryRun: false,
411 });
412 }
413
414 // 4. RETURN fresh attributes.
415 const finalLookup = yield* ec2.describeVolumes({
416 VolumeIds: [volumeId],
417 });
418 const final = finalLookup.Volumes?.[0] ?? volume;
419 return toVolumeAttributes(final, region, accountId);
420 }),
421
422 // Enumerate every volume in the ambient account/region.
423 list: () =>
424 Effect.gen(function* () {
425 const { accountId, region } = yield* AWSEnvironment.current;
426 const chunk = yield* ec2.describeVolumes.pages({}).pipe(Stream.runCollect);
427 return Array.from(chunk).flatMap((page) =>
428 (page.Volumes ?? []).map((v) => toVolumeAttributes(v, region, accountId)),
429 );
430 }),
431
432 delete: Effect.fn(function* ({ output, session }) {
433 const volumeId = output.volumeId;
434 yield* session.note(`Deleting volume: ${volumeId}`);
435
436 yield* ec2.deleteVolume({ VolumeId: volumeId, DryRun: false }).pipe(
437 Effect.tapError(Effect.logDebug),
438 Effect.catchTag("InvalidVolume.NotFound", () => Effect.void),
439 // A volume that is still detaching reports VolumeInUse — retry
440 // until the detach completes.
441 Effect.retry({
442 while: (e) => e._tag === "VolumeInUse",
443 schedule: Schedule.max([Schedule.fixed(3000), Schedule.recurs(20)]).pipe(
444 Schedule.tap(({ attempt }) =>
445 session.note(`Waiting for volume to detach... (attempt ${attempt + 1})`),
446 ),
447 ),
448 }),
449 );
450
451 yield* waitForVolumeDeleted(volumeId, session);
452 yield* session.note(`Volume ${volumeId} deleted successfully`);
453 }),
454 };
455 }),
456 );
457
458 const toVolumeAttributes = (
459 volume: ec2.Volume,
460 region: RegionID,
461 accountId: AccountID,
462 ): Volume["Attributes"] => {
463 const volumeId = volume.VolumeId! as VolumeId;
464 return {
465 volumeId,
466 volumeArn: `arn:aws:ec2:${region}:${accountId}:volume/${volumeId}` as VolumeArn,
467 availabilityZone: volume.AvailabilityZone!,
468 size: volume.Size ?? 0,
469 volumeType: volume.VolumeType ?? "gp3",
470 iops: volume.Iops,
471 throughput: volume.Throughput,
472 encrypted: volume.Encrypted ?? false,
473 kmsKeyId: volume.KmsKeyId,
474 snapshotId: volume.SnapshotId && volume.SnapshotId.length > 0 ? volume.SnapshotId : undefined,
475 multiAttachEnabled: volume.MultiAttachEnabled ?? false,
476 state: volume.State ?? "creating",
477 };
478 };
479
480 class VolumeNotFound extends Data.TaggedError("VolumeNotFound")<{
481 volumeId: string;
482 }> {}
483
484 class VolumeFailed extends Data.TaggedError("VolumeFailed")<{
485 volumeId: string;
486 }> {}
487
488 class VolumeNotReady extends Data.TaggedError("VolumeNotReady")<{
489 volumeId: string;
490 state: string;
491 }> {}
492
493 class VolumeStillExists extends Data.TaggedError("VolumeStillExists")<{
494 volumeId: string;
495 state: string;
496 message: string;
497 }> {}
498
499 /**
500 * Wait for the volume to reach the `available` state.
501 */
502 const waitForVolumeAvailable = (volumeId: string, session?: ScopedPlanStatusSession) =>
503 Effect.gen(function* () {
504 const result = yield* ec2.describeVolumes({ VolumeIds: [volumeId] });
505 const volume = result.Volumes?.[0];
506 if (!volume) {
507 return yield* new VolumeNotFound({ volumeId });
508 }
509 if (volume.State === "available" || volume.State === "in-use") {
510 return volume;
511 }
512 if (volume.State === "error") {
513 return yield* new VolumeFailed({ volumeId });
514 }
515 return yield* new VolumeNotReady({ volumeId, state: volume.State! });
516 }).pipe(
517 Effect.retry({
518 while: (e) => e._tag === "VolumeNotReady",
519 schedule: Schedule.max([
520 Schedule.fixed(2000),
521 Schedule.recurs(30), // max ~60s
522 ]).pipe(
523 Schedule.tap(({ attempt }) =>
524 session
525 ? session.note(`Waiting for volume to be available... (${(attempt + 1) * 2}s)`)
526 : Effect.void,
527 ),
528 ),
529 }),
530 );
531
532 /**
533 * Wait for the volume to be fully deleted.
534 */
535 const waitForVolumeDeleted = (volumeId: string, session: ScopedPlanStatusSession) =>
536 Effect.gen(function* () {
537 const result = yield* ec2
538 .describeVolumes({ VolumeIds: [volumeId] })
539 .pipe(Effect.catchTag("InvalidVolume.NotFound", () => Effect.succeed({ Volumes: [] })));
540 const volume = result.Volumes?.[0];
541 // Do not treat `deleting` as deleted. The provider's delete contract is
542 // complete only after EC2 stops returning the volume; otherwise nuke can
543 // report success while the resource remains in its inventory.
544 if (!volume || volume.State === "deleted") {
545 return;
546 }
547 return yield* new VolumeStillExists({
548 volumeId,
549 state: volume.State ?? "unknown",
550 message:
551 `Volume ${volumeId} remains ${volume.State ?? "visible"} after the bounded delete wait; ` +
552 "AWS accepted DeleteVolume but has not removed it",
553 });
554 }).pipe(
555 Effect.retry({
556 while: (e) => e._tag === "VolumeStillExists",
557 schedule: Schedule.max([
558 Schedule.fixed(2000),
559 // DeleteVolume is accepted immediately but describe can keep
560 // returning `deleting` well past a minute after a snapshot (the
561 // suite log hit the old 60s cap with the volume still present).
562 Schedule.recurs(45),
563 ]).pipe(
564 Schedule.tap(({ attempt }) =>
565 session.note(`Waiting for volume deletion... (${(attempt + 1) * 2}s)`),
566 ),
567 ),
568 }),
569 );