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

main
ts 1,085 lines 39.6 KB
Raw
1 import type { Credentials } from "@distilled.cloud/aws/Credentials";
2 import * as ec2 from "@distilled.cloud/aws/ec2";
3 import { Region } from "@distilled.cloud/aws/Region";
4 import * as Bundle from "alchemy/Bundle/Bundle";
5 import { deepEqual, isResolved } from "alchemy/Diff";
6 import type { Input } from "alchemy/Input";
7 import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
8 import * as Provider from "alchemy/Provider";
9 import type { ScopedPlanStatusSession } from "alchemy/Report";
10 import { Resource } from "alchemy/Resource";
11 import type { ServerHost } from "alchemy/Runtime/Process";
12 import { Stack } from "alchemy/Stack";
13 import { Stage } from "alchemy/Stage";
14 import { createAlchemyTagFilters, createInternalTags, diffTags } from "alchemy/Tags";
15 import * as Data from "effect/Data";
16 import * as Effect from "effect/Effect";
17 import * as FileSystem from "effect/FileSystem";
18 import * as Redacted from "effect/Redacted";
19 import * as Schedule from "effect/Schedule";
20 import * as Stream from "effect/Stream";
21 import type { AccountID } from "../Environment.ts";
22 import { AWSEnvironment } from "../Environment.ts";
23 import type { PolicyStatement } from "../IAM/Policy.ts";
24 import type { Providers } from "../Providers.ts";
25 import type { RegionID } from "../Region.ts";
26 import {
27 type Ec2HostedProps,
28 type InstanceMetadataOptions,
29 createEc2HostRuntimeContext,
30 createEc2HostedSupport,
31 type Ec2HostRuntimeContext,
32 } from "./hosted.ts";
33 import type { SecurityGroupId } from "./SecurityGroup.ts";
34 import type { SubnetId } from "./Subnet.ts";
35 import type { VpcId } from "./Vpc.ts";
36
37 export type { InstanceMetadataOptions };
38
39 export type InstanceId<ID extends string = string> = `i-${ID}`;
40 export const InstanceId = <ID extends string>(id: ID): ID & InstanceId<ID> =>
41 `i-${id}` as ID & InstanceId<ID>;
42
43 export type InstanceArn<ID extends InstanceId = InstanceId> =
44 `arn:aws:ec2:${RegionID}:${AccountID}:instance/${ID}`;
45
46 export const isInstance = (value: any): value is Instance =>
47 typeof value === "object" &&
48 value !== null &&
49 "Type" in value &&
50 value.Type === "AWS.EC2.Instance";
51
52 export interface InstanceProps extends PlatformProps {
53 /**
54 * AMI ID to launch.
55 */
56 imageId: string;
57 /**
58 * EC2 instance type, such as `t3.micro`.
59 */
60 instanceType: string;
61 /**
62 * Optional subnet to launch into.
63 */
64 subnetId?: Input<SubnetId>;
65 /**
66 * Security groups to attach to the primary network interface.
67 */
68 securityGroupIds?: Input<SecurityGroupId>[];
69 /**
70 * Optional EC2 key pair name for SSH access. Accepts a reference such as
71 * `AWS.EC2.KeyPair(...).keyName`.
72 */
73 keyName?: Input<string>;
74 /**
75 * Optional IAM instance profile name to attach at launch.
76 */
77 instanceProfileName?: string;
78 /**
79 * User data script to provide at launch time.
80 * Changes force replacement — EC2 does not re-run user data on an
81 * in-place update.
82 *
83 * Pass a `Redacted` when the script carries credentials: it is revealed
84 * only when building the `RunInstances` request and compared by value,
85 * so it never appears in plan output.
86 */
87 userData?: string | Redacted.Redacted<string>;
88 /**
89 * Whether to associate a public IPv4 address on launch.
90 */
91 associatePublicIpAddress?: boolean;
92 /**
93 * Optional private IPv4 address for the primary interface.
94 */
95 privateIpAddress?: string;
96 /**
97 * Optional availability zone override.
98 */
99 availabilityZone?: string;
100 /**
101 * Whether source/destination checking is enabled.
102 * @default true
103 */
104 sourceDestCheck?: boolean;
105 /**
106 * Instance Metadata Service (IMDS) options, e.g. requiring IMDSv2 and
107 * limiting the hop count. Applied at launch and updated in place. Unset
108 * fields keep the AMI / account defaults.
109 */
110 metadataOptions?: InstanceMetadataOptions;
111 /**
112 * User-defined tags to apply to the instance.
113 */
114 tags?: Record<string, string>;
115 /**
116 * Module entrypoint for the bundled instance program.
117 * When omitted, the instance behaves as a low-level EC2 resource.
118 */
119 main?: string;
120 /**
121 * Named export to load from `main`.
122 * @default "default"
123 */
124 handler?: string;
125 /**
126 * Port exposed by the process, if any.
127 * @default 3000
128 */
129 port?: number;
130 /**
131 * Additional environment variables for the hosted process.
132 */
133 env?: Record<string, any>;
134 /**
135 * Bundler configuration for the hosted process entrypoint. Unused
136 * code is tree-shaken. `effect`, alchemy, and `@distilled.cloud` are
137 * marked pure so unused parts prune more aggressively. List extra
138 * packages with `pure.packages`, or disable with `pure: false`.
139 */
140 build?: Bundle.BundleConfig;
141 /**
142 * Additional managed policy ARNs for the managed instance role.
143 * This can only be used when Alchemy manages the instance profile.
144 */
145 roleManagedPolicyArns?: string[];
146 }
147
148 export interface Instance extends Resource<
149 "AWS.EC2.Instance",
150 InstanceProps,
151 {
152 /**
153 * The ID of the instance.
154 */
155 instanceId: InstanceId;
156 /**
157 * The Amazon Resource Name (ARN) of the instance.
158 */
159 instanceArn: InstanceArn;
160 /**
161 * The AMI ID the instance launched from.
162 */
163 imageId: string;
164 /**
165 * The instance type.
166 */
167 instanceType: string;
168 /**
169 * The current instance state.
170 */
171 state: string;
172 /**
173 * The VPC the instance belongs to, if any.
174 */
175 vpcId?: VpcId;
176 /**
177 * The subnet the instance belongs to, if any.
178 */
179 subnetId?: SubnetId;
180 /**
181 * The availability zone of the instance.
182 */
183 availabilityZone?: string;
184 /**
185 * The attached security group IDs.
186 */
187 securityGroupIds: string[];
188 /**
189 * The primary private IPv4 address.
190 */
191 privateIpAddress?: string;
192 /**
193 * The public IPv4 address, if assigned.
194 */
195 publicIpAddress?: string;
196 /**
197 * The private DNS name.
198 */
199 privateDnsName?: string;
200 /**
201 * The public DNS name, if assigned.
202 */
203 publicDnsName?: string;
204 /**
205 * HTTP URL of the hosted process
206 * (`http://{publicDnsName|publicIpAddress}:{port}`).
207 *
208 * Set when the instance is hosted (`main` / `port`). Under
209 * `alchemy dev` the emulator's public address is
210 * `{instanceId}.localhost.floci.io`, which resolves to 127.0.0.1
211 * and is served by a per-port host-routing mux — reading `url`
212 * instead of interpolating `publicIpAddress` is what makes the
213 * instance reachable from the host. On AWS this is the public
214 * IP/DNS and the process port.
215 */
216 url?: string;
217 /**
218 * The key pair name used for SSH access.
219 */
220 keyName?: string;
221 /**
222 * The IAM instance profile ARN attached to the instance, if any.
223 */
224 instanceProfileArn?: string;
225 /**
226 * The IAM instance profile ID attached to the instance, if any.
227 */
228 instanceProfileId?: string;
229 /**
230 * The IAM instance profile name attached to the instance, if known.
231 */
232 instanceProfileName?: string;
233 /**
234 * Whether source/destination checking is enabled.
235 */
236 sourceDestCheck?: boolean;
237 /**
238 * The Instance Metadata Service options in effect on the instance.
239 */
240 metadataOptions?: InstanceMetadataOptions;
241 /**
242 * When the instance was launched.
243 */
244 launchTime?: string;
245 /**
246 * Current tags on the instance.
247 */
248 tags: Record<string, string>;
249 /**
250 * Role attached by the hosted runtime, if any.
251 */
252 roleArn?: string;
253 /**
254 * Role name attached by the hosted runtime, if any.
255 */
256 roleName?: string;
257 /**
258 * Inline policy name used for bindings/runtime sync, if any.
259 */
260 policyName?: string;
261 /**
262 * Whether the role/profile were created and owned by Alchemy.
263 */
264 managedIam?: boolean;
265 /**
266 * Deterministic runtime unit name for hosted instances.
267 */
268 runtimeUnitName?: string;
269 /**
270 * Asset prefix for hosted bundles and env files.
271 */
272 assetPrefix?: string;
273 /**
274 * Bundle hash for hosted instances.
275 */
276 code?: {
277 hash: string;
278 };
279 },
280 {
281 /** Environment variables injected into the hosted instance runtime. */
282 env?: Record<string, any>;
283 /** IAM policy statements attached to the instance profile role. */
284 policyStatements?: PolicyStatement[];
285 },
286 Providers
287 > {}
288
289 export type InstanceServices = ServerHost | Credentials | Region | AWSEnvironment;
290
291 export type InstanceShape = Main<InstanceServices>;
292
293 export type InstanceRuntimeContext = Ec2HostRuntimeContext;
294
295 /**
296 * An EC2 instance that can either act as a low-level compute primitive or run
297 * a bundled long-lived Effect program directly on the machine.
298 * ### Launching Instances
299 * **Example:** Basic Instance
300 * ```typescript
301 * const instance = yield* AWS.EC2.Instance("AppInstance", {
302 * imageId: AWS.EC2.amazonLinux2023(),
303 * instanceType: "t3.micro",
304 * subnetId: subnet.subnetId,
305 * });
306 * ```
307 *
308 * **Example:** Require IMDSv2
309 * A hop limit of 1 keeps containers on the host from reaching the
310 * instance role's credentials. Changes apply in place.
311 * ```typescript
312 * const instance = yield* AWS.EC2.Instance("AppInstance", {
313 * imageId: AWS.EC2.amazonLinux2023(),
314 * instanceType: "t3.micro",
315 * metadataOptions: {
316 * httpTokens: "required",
317 * httpPutResponseHopLimit: 1,
318 * },
319 * });
320 * ```
321 *
322 * ### Hosting Processes
323 * **Example:** HTTP Server on an Instance
324 * ```typescript
325 * const api = yield* Effect.gen(function* () {
326 * yield* Http.serve(
327 * HttpServerResponse.json({ ok: true }),
328 * );
329 *
330 * return {
331 * main: import.meta.url,
332 * imageId: AWS.EC2.amazonLinux2023(),
333 * instanceType: "t3.small",
334 * subnetId: subnet.subnetId,
335 * securityGroupIds: [securityGroup.groupId],
336 * associatePublicIpAddress: true,
337 * port: 3000,
338 * };
339 * }).pipe(
340 * Effect.provide(AWS.EC2.HttpServer),
341 * AWS.EC2.Instance("ApiInstance"),
342 * );
343 * ```
344 *
345 * ### Bundling & Tree-shaking
346 * `main` is bundled with rolldown at deploy time. Unused code is
347 * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
348 * pure so unused parts prune more aggressively. Your app is not
349 * marked pure.
350 *
351 * **Example:** Mark additional packages as pure
352 * Only list packages with no top-level side effects.
353 * ```typescript
354 * {
355 * main: import.meta.url,
356 * build: {
357 * pure: { packages: ["my-lib", "@my-scope/*"] },
358 * },
359 * }
360 * ```
361 *
362 * **Example:** Turn it off
363 * ```typescript
364 * {
365 * main: import.meta.url,
366 * build: { pure: false },
367 * }
368 * ```
369 *
370 * @resource
371 */
372 export const Instance: Platform<Instance, InstanceServices, InstanceShape, InstanceRuntimeContext> =
373 Platform("AWS.EC2.Instance", {
374 createRuntimeContext: createEc2HostRuntimeContext("AWS.EC2.Instance"),
375 });
376
377 export const InstanceProvider = () =>
378 Provider.effect(
379 Instance,
380 Effect.gen(function* () {
381 const stack = yield* Stack;
382 const stage = yield* Stage;
383 const fs = yield* FileSystem.FileSystem;
384 const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
385
386 const toInstanceArn = (instanceId: InstanceId) =>
387 AWSEnvironment.current.pipe(
388 Effect.map(
389 (env) =>
390 `arn:aws:ec2:${env.region}:${env.accountId}:instance/${instanceId}` as InstanceArn,
391 ),
392 );
393
394 const hosted = createEc2HostedSupport({
395 stackName: stack.name,
396 stage,
397 fs,
398 virtualEntryPlugin,
399 resourceType: "EC2.Instance",
400 });
401
402 const isPendingInstanceProfileError = (error: unknown) => {
403 const tag = (error as { _tag?: string })?._tag;
404 if (tag === "InvalidIAMInstanceProfile.NotFound" || tag === "InvalidParameterValue") {
405 return true;
406 }
407 if (tag !== "UnknownAwsError") {
408 return false;
409 }
410 const unknown = error as {
411 errorTag?: string;
412 message?: string;
413 errorData?: {
414 message?: string;
415 Message?: string;
416 };
417 };
418 const message =
419 unknown.message ?? unknown.errorData?.message ?? unknown.errorData?.Message ?? "";
420 return (
421 unknown.errorTag === "InvalidParameterValue" &&
422 message.includes("iamInstanceProfile.name") &&
423 message.includes("Invalid IAM Instance Profile name")
424 );
425 };
426
427 const isPendingInstanceLookupError = (error: unknown) => {
428 const tag = (error as { _tag?: string })?._tag;
429 return error instanceof InstanceNotFound || tag === "InvalidInstanceID.NotFound";
430 };
431
432 const toTagRecord = (tags?: Array<{ Key?: string; Value?: string }>) =>
433 Object.fromEntries(
434 (tags ?? [])
435 .filter((tag): tag is { Key: string; Value: string } =>
436 Boolean(tag.Key && tag.Value !== undefined),
437 )
438 .map((tag) => [tag.Key, tag.Value]),
439 );
440
441 const publicHost = (instance: ec2.Instance) =>
442 instance.PublicDnsName || instance.PublicIpAddress;
443
444 const hostedListenPort = (props: { main?: unknown; port?: number }) =>
445 props.main !== undefined || props.port !== undefined ? (props.port ?? 3000) : undefined;
446
447 const instanceUrl = (instance: ec2.Instance, port?: number) => {
448 const host = publicHost(instance);
449 if (!host || port === undefined) return undefined;
450 return `http://${host}:${port}`;
451 };
452
453 const portFromUrl = (url?: string) => {
454 if (!url) return undefined;
455 try {
456 const parsed = new URL(url);
457 return parsed.port ? Number(parsed.port) : undefined;
458 } catch {
459 return undefined;
460 }
461 };
462
463 const toAttributes = Effect.fn(function* (instance: ec2.Instance, port?: number) {
464 return {
465 instanceId: instance.InstanceId as InstanceId,
466 instanceArn: yield* toInstanceArn(instance.InstanceId as InstanceId),
467 imageId: instance.ImageId!,
468 instanceType: String(instance.InstanceType ?? ""),
469 state: instance.State?.Name ?? "unknown",
470 vpcId: instance.VpcId as VpcId | undefined,
471 subnetId: instance.SubnetId as SubnetId | undefined,
472 availabilityZone: instance.Placement?.AvailabilityZone,
473 securityGroupIds: (instance.SecurityGroups ?? [])
474 .map((group) => group.GroupId)
475 .filter((value): value is string => Boolean(value)),
476 privateIpAddress: instance.PrivateIpAddress,
477 publicIpAddress: instance.PublicIpAddress,
478 privateDnsName: instance.PrivateDnsName,
479 publicDnsName: instance.PublicDnsName,
480 url: instanceUrl(instance, port),
481 keyName: instance.KeyName,
482 instanceProfileArn: instance.IamInstanceProfile?.Arn,
483 instanceProfileId: instance.IamInstanceProfile?.Id,
484 instanceProfileName: undefined,
485 sourceDestCheck: instance.SourceDestCheck,
486 metadataOptions: instance.MetadataOptions
487 ? {
488 httpTokens: instance.MetadataOptions.HttpTokens as
489 | InstanceMetadataOptions["httpTokens"]
490 | undefined,
491 httpPutResponseHopLimit: instance.MetadataOptions.HttpPutResponseHopLimit,
492 httpEndpoint: instance.MetadataOptions.HttpEndpoint as
493 | InstanceMetadataOptions["httpEndpoint"]
494 | undefined,
495 httpProtocolIpv6: instance.MetadataOptions.HttpProtocolIpv6 as
496 | InstanceMetadataOptions["httpProtocolIpv6"]
497 | undefined,
498 instanceMetadataTags: instance.MetadataOptions.InstanceMetadataTags as
499 | InstanceMetadataOptions["instanceMetadataTags"]
500 | undefined,
501 }
502 : undefined,
503 launchTime:
504 instance.LaunchTime instanceof Date
505 ? instance.LaunchTime.toISOString()
506 : (instance.LaunchTime as string | undefined),
507 tags: toTagRecord(instance.Tags),
508 } satisfies Instance["Attributes"];
509 });
510
511 const describeInstance = (instanceId: string) =>
512 ec2
513 .describeInstances({
514 InstanceIds: [instanceId],
515 })
516 .pipe(
517 Effect.map(
518 (result) =>
519 (result.Reservations ?? []).flatMap(
520 (reservation) => reservation.Instances ?? [],
521 )[0],
522 ),
523 Effect.flatMap((instance) =>
524 instance
525 ? Effect.succeed(instance)
526 : Effect.fail(new InstanceNotFound({ instanceId })),
527 ),
528 );
529
530 // Generation-scoped recovery lookup: instances are branded with the
531 // engine's per-generation instance id (`alchemy::instance`) on top of
532 // the stack/stage/id ownership tags. An interrupted create resumes with
533 // the same generation id, so it still recovers its own orphan — while a
534 // replacement's create phase runs under a freshly minted generation id
535 // and can never re-adopt the old generation's live instance that the
536 // cleanup phase is about to terminate.
537 const findInstanceByTags = Effect.fn(function* (id: string, generation: string) {
538 const filters = [
539 ...(yield* createAlchemyTagFilters(id)),
540 { Name: "tag:alchemy::instance", Values: [generation] },
541 ];
542 return yield* ec2.describeInstances
543 .items({
544 Filters: filters,
545 })
546 .pipe(
547 Stream.flatMap((reservation) => Stream.fromArray(reservation.Instances ?? [])),
548 Stream.filter((instance) => {
549 const state = instance.State?.Name;
550 return (
551 state === "pending" ||
552 state === "running" ||
553 state === "stopping" ||
554 state === "stopped"
555 );
556 }),
557 Stream.runCollect,
558 Effect.map(
559 (instances) =>
560 [...instances].sort((a, b) => {
561 const aTime =
562 a.LaunchTime instanceof Date
563 ? a.LaunchTime.getTime()
564 : Date.parse(String(a.LaunchTime ?? 0));
565 const bTime =
566 b.LaunchTime instanceof Date
567 ? b.LaunchTime.getTime()
568 : Date.parse(String(b.LaunchTime ?? 0));
569 return bTime - aTime;
570 })[0],
571 ),
572 );
573 });
574
575 const waitForState = Effect.fn(function* ({
576 instanceId,
577 states,
578 session,
579 }: {
580 instanceId: string;
581 states: string[];
582 session: Pick<ScopedPlanStatusSession, "note">;
583 }) {
584 return yield* describeInstance(instanceId).pipe(
585 Effect.tap((instance) =>
586 session.note(
587 `Waiting for instance ${instanceId}: ${instance.State?.Name ?? "unknown"}`,
588 ),
589 ),
590 Effect.filterOrFail(
591 (instance) => states.includes(instance.State?.Name ?? ""),
592 (instance) =>
593 new InstanceStateMismatch({
594 instanceId,
595 actual: instance.State?.Name ?? "unknown",
596 expected: states,
597 }),
598 ),
599 Effect.retry({
600 while: (error) =>
601 error instanceof InstanceStateMismatch || isPendingInstanceLookupError(error),
602 schedule: Schedule.max([Schedule.exponential("250 millis"), Schedule.recurs(8)]),
603 }),
604 );
605 });
606
607 const waitForDeleted = Effect.fn(function* ({
608 instanceId,
609 session,
610 }: {
611 instanceId: string;
612 session: Pick<ScopedPlanStatusSession, "note">;
613 }) {
614 yield* describeInstance(instanceId).pipe(
615 Effect.tap((instance) =>
616 session.note(
617 `Waiting for instance deletion ${instanceId}: ${instance.State?.Name ?? "unknown"}`,
618 ),
619 ),
620 Effect.flatMap((instance) =>
621 instance.State?.Name === "terminated"
622 ? Effect.undefined
623 : Effect.fail(new InstanceStillExists({ instanceId })),
624 ),
625 Effect.retry({
626 while: (error) => error instanceof InstanceStillExists,
627 // Termination (shutting-down -> terminated) can take a couple of
628 // minutes; the prior ~64s budget timed out intermittently.
629 schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(48)]),
630 }),
631 Effect.catchTags({
632 "InvalidInstanceID.NotFound": () => Effect.void,
633 InstanceNotFound: () => Effect.void,
634 }),
635 );
636 });
637
638 const resolvedSecurityGroups = (groups?: InstanceProps["securityGroupIds"]) =>
639 hosted.normalizeSecurityGroups(groups as string[] | undefined);
640
641 const buildRunInstancesRequest = (
642 news: InstanceProps,
643 runtime: {
644 userData?: string;
645 instanceProfileName?: string;
646 },
647 tags: Record<string, string>,
648 clientToken: string,
649 ): ec2.RunInstancesRequest => ({
650 ...hosted.buildLaunchTemplateData(
651 {
652 imageId: news.imageId,
653 instanceType: news.instanceType,
654 keyName: news.keyName as string | undefined,
655 subnetId: news.subnetId as string | undefined,
656 securityGroupIds: news.securityGroupIds as string[] | undefined,
657 associatePublicIpAddress: news.associatePublicIpAddress,
658 privateIpAddress: news.privateIpAddress,
659 availabilityZone: news.availabilityZone,
660 metadataOptions: news.metadataOptions,
661 tags,
662 },
663 runtime,
664 ),
665 MinCount: 1,
666 MaxCount: 1,
667 ClientToken: clientToken,
668 });
669
670 return {
671 stables: ["instanceId", "instanceArn", "vpcId", "subnetId"],
672 list: () =>
673 Effect.gen(function* () {
674 // describeInstances paginates; each page nests instances under
675 // Reservations[].Instances[]. Enumerate every non-terminated
676 // instance in the ambient account/region.
677 const instances = yield* ec2.describeInstances.pages({}).pipe(
678 Stream.runCollect,
679 Effect.map((chunk) =>
680 Array.from(chunk).flatMap((page) =>
681 (page.Reservations ?? []).flatMap((reservation) => reservation.Instances ?? []),
682 ),
683 ),
684 );
685 return yield* Effect.forEach(
686 instances.filter((instance) => instance.State?.Name !== "terminated"),
687 (instance) => toAttributes(instance),
688 );
689 }),
690 diff: Effect.fn(function* ({ id, news, olds, output }) {
691 const raw = news as unknown as Record<string, unknown>;
692 // Launch-time properties cannot be mutated in place. Check them
693 // even when OTHER props are still unresolved Outputs (e.g.
694 // `userData` interpolating an ECR Image URI that's being rebuilt):
695 // bailing on `isResolved(news)` lets the engine default the change
696 // to `update`, which keeps the same instance ID and never re-runs
697 // user data. An unresolved replace-trigger is itself a replacement
698 // — the upstream's new value is unknown at plan time, so we can't
699 // prove the launch config didn't change.
700 const launchConfigChanged = (next: unknown, prev: unknown) =>
701 !isResolved(next) || prev !== next;
702 // `Redacted` userData decoded from state is a fresh object, so it
703 // must be compared by value rather than by reference.
704 const userDataChanged =
705 !isResolved(raw.userData) || !deepEqual(raw.userData, olds.userData);
706 const hostModeChanged = Boolean(olds.main) !== Boolean(raw.main);
707 if (
708 hostModeChanged ||
709 launchConfigChanged(raw.imageId, olds.imageId) ||
710 launchConfigChanged(raw.subnetId, olds.subnetId) ||
711 launchConfigChanged(raw.keyName, olds.keyName) ||
712 launchConfigChanged(raw.instanceProfileName, olds.instanceProfileName) ||
713 userDataChanged ||
714 launchConfigChanged(raw.associatePublicIpAddress, olds.associatePublicIpAddress) ||
715 launchConfigChanged(raw.privateIpAddress, olds.privateIpAddress) ||
716 launchConfigChanged(raw.availabilityZone, olds.availabilityZone)
717 ) {
718 // A primary private IP cannot belong to two instances in the
719 // same subnet. An omitted subnet may still resolve to that subnet.
720 const reusesFixedPrivateIp =
721 raw.privateIpAddress !== undefined &&
722 (output?.privateIpAddress ?? olds.privateIpAddress) === raw.privateIpAddress &&
723 (raw.subnetId === undefined || (output?.subnetId ?? olds.subnetId) === raw.subnetId);
724 return reusesFixedPrivateIp
725 ? ({ action: "replace", deleteFirst: true } as const)
726 : ({ action: "replace" } as const);
727 }
728 // The hosted bundle hash must participate in planning even while
729 // OTHER props are unresolved Outputs (an `imageId` AMI lookup, a
730 // subnet reference): a content-only edit changes no prop at all,
731 // so bailing on full resolution silently no-ops the update. The
732 // content inputs are plain — gate on THEM, not on the whole bag
733 // (the same isResolved-defeats-content-diff bug the MicroVM image
734 // diff had).
735 const contentInputs = {
736 main: raw.main,
737 handler: raw.handler,
738 build: raw.build,
739 port: raw.port,
740 // `isExternal` chooses the bundler entry (raw file vs virtual
741 // `export default` wrapper). Omitting it here re-bundles an
742 // external program as an Effect entrypoint and fails the plan
743 // with MISSING_EXPORT when the source has no default export.
744 isExternal: raw.isExternal,
745 };
746 if (isResolved(contentInputs) && contentInputs.main !== undefined && output?.code?.hash) {
747 const { hash } = yield* hosted.bundleProgram(
748 id,
749 contentInputs as unknown as Ec2HostedProps,
750 );
751 if (hash !== output.code.hash) {
752 return {
753 action: "update",
754 stables: ["instanceId", "instanceArn", "vpcId", "subnetId"],
755 } as const;
756 }
757 }
758 if (!isResolved(news)) return;
759
760 if (
761 olds.instanceType !== news.instanceType ||
762 olds.sourceDestCheck !== news.sourceDestCheck ||
763 !deepEqual(olds.metadataOptions ?? {}, news.metadataOptions ?? {}) ||
764 olds.main !== news.main ||
765 olds.handler !== news.handler ||
766 olds.port !== news.port ||
767 !deepEqual(olds.env ?? {}, news.env ?? {}) ||
768 !deepEqual(olds.build ?? {}, news.build ?? {}) ||
769 !deepEqual(olds.roleManagedPolicyArns ?? [], news.roleManagedPolicyArns ?? []) ||
770 !deepEqual(
771 resolvedSecurityGroups(olds.securityGroupIds),
772 resolvedSecurityGroups(news.securityGroupIds),
773 ) ||
774 !deepEqual(olds.tags ?? {}, news.tags ?? {})
775 ) {
776 return {
777 action: "update",
778 stables: ["instanceId", "instanceArn", "vpcId", "subnetId"],
779 } as const;
780 }
781
782 // Content-only changes were already handled by the resolved-subset
783 // bundle-hash check above.
784 }),
785 read: Effect.fn(function* ({ id, instanceId, output }) {
786 const instance = output?.instanceId
787 ? yield* describeInstance(output.instanceId).pipe(
788 Effect.catchTags({
789 "InvalidInstanceID.NotFound": () => Effect.undefined,
790 InstanceNotFound: () => Effect.undefined,
791 }),
792 )
793 : yield* findInstanceByTags(id, instanceId);
794 // A terminated instance is a tombstone EC2 keeps listing for a
795 // while; report it as missing, as reconcile does.
796 return instance && instance.State?.Name !== "terminated"
797 ? {
798 ...(yield* toAttributes(instance, portFromUrl(output?.url))),
799 instanceProfileName: output?.instanceProfileName,
800 roleArn: output?.roleArn,
801 roleName: output?.roleName,
802 policyName: output?.policyName,
803 managedIam: output?.managedIam,
804 runtimeUnitName: output?.runtimeUnitName,
805 assetPrefix: output?.assetPrefix,
806 code: output?.code,
807 }
808 : undefined;
809 }),
810 reconcile: Effect.fn(function* ({
811 id,
812 instanceId: generation,
813 news,
814 output,
815 bindings,
816 session,
817 }) {
818 const desiredTags = {
819 ...(yield* createInternalTags(id)),
820 // Generation brand consumed by the recovery lookup above.
821 "alchemy::instance": generation,
822 ...news.tags,
823 };
824 const runtime = yield* hosted.resolveHostedRuntime({
825 id,
826 news: {
827 ...news,
828 userData:
829 news.userData === undefined || typeof news.userData === "string"
830 ? news.userData
831 : Redacted.value(news.userData),
832 },
833 bindings,
834 output,
835 });
836
837 // Observe — try the cached instanceId first, then fall back to the
838 // alchemy-tag search for recovery from interrupted creates. EC2
839 // assigns instance IDs server-side so we always read the live
840 // record before deciding whether to launch a new one.
841 let instance: ec2.Instance | undefined = output?.instanceId
842 ? yield* describeInstance(output.instanceId).pipe(
843 Effect.catchTags({
844 "InvalidInstanceID.NotFound": () => Effect.undefined,
845 InstanceNotFound: () => Effect.undefined,
846 }),
847 )
848 : yield* findInstanceByTags(id, generation);
849
850 // A terminated instance is a tombstone; treat as missing so we
851 // launch a fresh one.
852 if (instance && instance.State?.Name === "terminated") {
853 instance = undefined;
854 }
855
856 // Ensure — RunInstances when no live instance was observed. The
857 // initial sourceDestCheck is set here because RunInstances itself
858 // doesn't accept it. The ClientToken is this generation plus the
859 // last instance it launched, so a launch retried after a lost reply
860 // returns the first instance, and a relaunch after the instance was
861 // terminated sends a new token.
862 if (instance === undefined) {
863 const launch = (previous: string) =>
864 ec2
865 .runInstances(
866 buildRunInstancesRequest(news, runtime, desiredTags, `${generation}-${previous}`),
867 )
868 .pipe(
869 Effect.retry({
870 while: isPendingInstanceProfileError,
871 schedule: Schedule.max([
872 Schedule.exponential("500 millis"),
873 Schedule.recurs(8),
874 ]),
875 }),
876 );
877 let launched = (yield* launch(output?.instanceId ?? "initial")).Instances?.[0];
878 // A used token returns the instance it first launched, even once
879 // that instance is terminated (its reply was lost and it was then
880 // terminated outside the stack). Launch again under a token keyed
881 // on that instance.
882 if (launched?.InstanceId && isTerminating(launched)) {
883 launched = (yield* launch(launched.InstanceId)).Instances?.[0];
884 }
885 const newInstanceId = launched?.InstanceId as InstanceId | undefined;
886 if (!newInstanceId || isTerminating(launched!)) {
887 return yield* new InstanceLaunchFailed({
888 id,
889 message: newInstanceId
890 ? `RunInstances returned ${launched?.State?.Name} instance ${newInstanceId}`
891 : "RunInstances returned no instance ID",
892 });
893 }
894 yield* session.note(newInstanceId);
895 instance = yield* waitForState({
896 instanceId: newInstanceId,
897 states: ["running"],
898 session,
899 });
900 if (news.sourceDestCheck !== undefined) {
901 yield* ec2.modifyInstanceAttribute({
902 InstanceId: newInstanceId,
903 SourceDestCheck: { Value: news.sourceDestCheck },
904 });
905 }
906 }
907
908 const instanceId = instance.InstanceId as InstanceId;
909 let restarted = false;
910
911 // Sync security groups — observed primary-ENI groups vs desired.
912 const observedSecurityGroups = (instance.SecurityGroups ?? [])
913 .map((g) => g.GroupId)
914 .filter((g): g is string => Boolean(g));
915 const desiredSecurityGroups = resolvedSecurityGroups(news.securityGroupIds);
916 if (
917 desiredSecurityGroups &&
918 desiredSecurityGroups.length > 0 &&
919 JSON.stringify([...observedSecurityGroups].sort()) !==
920 JSON.stringify([...desiredSecurityGroups].sort())
921 ) {
922 yield* ec2.modifyInstanceAttribute({
923 InstanceId: instanceId,
924 Groups: desiredSecurityGroups,
925 });
926 }
927
928 // Sync source/dest check — observed flag vs desired (default true).
929 const desiredSourceDestCheck = news.sourceDestCheck ?? true;
930 if ((instance.SourceDestCheck ?? true) !== desiredSourceDestCheck) {
931 yield* ec2.modifyInstanceAttribute({
932 InstanceId: instanceId,
933 SourceDestCheck: { Value: desiredSourceDestCheck },
934 });
935 }
936
937 // Sync metadata options — only the fields the user set, against
938 // the observed IMDS config. Unset fields keep whatever is live.
939 const desiredMetadata = news.metadataOptions ?? {};
940 const metadataMatches = (observed: ec2.InstanceMetadataOptionsResponse = {}) =>
941 (desiredMetadata.httpTokens ?? observed.HttpTokens) === observed.HttpTokens &&
942 (desiredMetadata.httpPutResponseHopLimit ?? observed.HttpPutResponseHopLimit) ===
943 observed.HttpPutResponseHopLimit &&
944 (desiredMetadata.httpEndpoint ?? observed.HttpEndpoint) === observed.HttpEndpoint &&
945 (desiredMetadata.httpProtocolIpv6 ?? observed.HttpProtocolIpv6) ===
946 observed.HttpProtocolIpv6 &&
947 (desiredMetadata.instanceMetadataTags ?? observed.InstanceMetadataTags) ===
948 observed.InstanceMetadataTags;
949 if (!metadataMatches(instance.MetadataOptions)) {
950 yield* ec2.modifyInstanceMetadataOptions({
951 InstanceId: instanceId,
952 HttpTokens: desiredMetadata.httpTokens,
953 HttpPutResponseHopLimit: desiredMetadata.httpPutResponseHopLimit,
954 HttpEndpoint: desiredMetadata.httpEndpoint,
955 HttpProtocolIpv6: desiredMetadata.httpProtocolIpv6,
956 InstanceMetadataTags: desiredMetadata.instanceMetadataTags,
957 });
958 // DescribeInstances lags the modify; wait for the new options so
959 // the returned attributes reflect them.
960 yield* describeInstance(instanceId).pipe(
961 Effect.repeat({
962 until: (observed) =>
963 observed.MetadataOptions?.State === "applied" &&
964 metadataMatches(observed.MetadataOptions),
965 schedule: Schedule.spaced("2 seconds"),
966 times: 15,
967 }),
968 );
969 }
970
971 // Sync instance type — observed type vs desired. Type changes need
972 // the instance stopped, then we restart it if it was running.
973 if (news.instanceType && String(instance.InstanceType ?? "") !== news.instanceType) {
974 const wasRunning = instance.State?.Name === "running";
975 if (wasRunning) {
976 yield* ec2.stopInstances({ InstanceIds: [instanceId] });
977 yield* waitForState({
978 instanceId,
979 states: ["stopped"],
980 session,
981 });
982 }
983 yield* ec2.modifyInstanceAttribute({
984 InstanceId: instanceId,
985 InstanceType: {
986 Value: news.instanceType as ec2.InstanceType,
987 },
988 });
989 if (wasRunning) {
990 yield* ec2.startInstances({ InstanceIds: [instanceId] });
991 yield* waitForState({
992 instanceId,
993 states: ["running"],
994 session,
995 });
996 restarted = true;
997 }
998 }
999
1000 // Sync tags — observed cloud tags vs desired.
1001 const currentTags = Object.fromEntries(
1002 (instance.Tags ?? [])
1003 .filter((t): t is { Key: string; Value: string } =>
1004 Boolean(t.Key && t.Value !== undefined),
1005 )
1006 .map((t) => [t.Key, t.Value]),
1007 ) as Record<string, string>;
1008 const { removed, upsert } = diffTags(currentTags, desiredTags);
1009 if (removed.length > 0) {
1010 yield* ec2.deleteTags({
1011 Resources: [instanceId],
1012 Tags: removed.map((key) => ({ Key: key })),
1013 });
1014 }
1015 if (upsert.length > 0) {
1016 yield* ec2.createTags({
1017 Resources: [instanceId],
1018 Tags: upsert,
1019 });
1020 }
1021
1022 // Hosted-runtime reboot — picks up new bundle/env without an
1023 // explicit instance-type cycle. Skip if the type-change path
1024 // already restarted us.
1025 if (news.main && !restarted) {
1026 yield* ec2.rebootInstances({ InstanceIds: [instanceId] });
1027 yield* waitForState({
1028 instanceId,
1029 states: ["running"],
1030 session,
1031 });
1032 }
1033
1034 // Re-read final state so attributes reflect the post-sync cloud.
1035 const final = yield* describeInstance(instanceId);
1036 return {
1037 ...(yield* toAttributes(final, hostedListenPort(news))),
1038 instanceProfileName: runtime.instanceProfileName ?? output?.instanceProfileName,
1039 roleArn: runtime.roleArn ?? output?.roleArn,
1040 roleName: runtime.roleName ?? output?.roleName,
1041 policyName: runtime.policyName ?? output?.policyName,
1042 managedIam: runtime.managedIam ?? output?.managedIam,
1043 runtimeUnitName: runtime.runtimeUnitName ?? output?.runtimeUnitName,
1044 assetPrefix: runtime.assetPrefix ?? output?.assetPrefix,
1045 code: runtime.code ?? output?.code,
1046 };
1047 }),
1048 delete: Effect.fn(function* ({ output, session }) {
1049 yield* ec2
1050 .terminateInstances({
1051 InstanceIds: [output.instanceId],
1052 })
1053 .pipe(Effect.catchTag("InvalidInstanceID.NotFound", () => Effect.void));
1054 yield* waitForDeleted({
1055 instanceId: output.instanceId,
1056 session,
1057 });
1058
1059 yield* hosted.cleanupHostedRuntime({ output });
1060 }),
1061 };
1062 }),
1063 );
1064
1065 const isTerminating = (instance: ec2.Instance) =>
1066 instance.State?.Name === "shutting-down" || instance.State?.Name === "terminated";
1067
1068 class InstanceLaunchFailed extends Data.TaggedError("InstanceLaunchFailed")<{
1069 id: string;
1070 message: string;
1071 }> {}
1072
1073 class InstanceNotFound extends Data.TaggedError("InstanceNotFound")<{
1074 instanceId: string;
1075 }> {}
1076
1077 class InstanceStillExists extends Data.TaggedError("InstanceStillExists")<{
1078 instanceId: string;
1079 }> {}
1080
1081 class InstanceStateMismatch extends Data.TaggedError("InstanceStateMismatch")<{
1082 instanceId: string;
1083 actual: string;
1084 expected: string[];
1085 }> {}