@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 351 lines 13.4 KB
Raw
1 import * as efs from "@distilled.cloud/aws/efs";
2 import { isResolved } from "alchemy/Diff";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import * as Data from "effect/Data";
6 import * as Effect from "effect/Effect";
7 import * as Schedule from "effect/Schedule";
8 import * as Stream from "effect/Stream";
9 import type { Providers } from "../Providers.ts";
10
11 export interface MountTargetProps {
12 /**
13 * ID of the EFS file system to expose through this mount target
14 * (e.g. `fileSystem.fileSystemId`). Cannot be changed after creation
15 * (replacement).
16 */
17 fileSystemId: string;
18 /**
19 * ID of the subnet to create the mount target in. Determines the VPC and
20 * Availability Zone; one mount target is allowed per AZ. Cannot be changed
21 * after creation (replacement).
22 */
23 subnetId: string;
24 /**
25 * Static private IPv4 address for the mount target within the subnet's
26 * range. Cannot be changed after creation (replacement).
27 * @default an address assigned by EFS
28 */
29 ipAddress?: string;
30 /**
31 * Security groups attached to the mount target's network interface (up to
32 * five). NFS clients must be allowed to reach TCP port 2049 through these
33 * groups. Updatable in place.
34 * @default the VPC's default security group
35 */
36 securityGroups?: string[];
37 }
38
39 export interface MountTarget extends Resource<
40 "AWS.EFS.MountTarget",
41 MountTargetProps,
42 {
43 /** The ID of the mount target (e.g. `fsmt-0123456789abcdef0`). */
44 mountTargetId: string;
45 /** The ID of the EFS file system the mount target belongs to. */
46 fileSystemId: string;
47 /** The ID of the subnet the mount target was created in. */
48 subnetId: string;
49 /** The IPv4 address at which the file system is reachable in the subnet. */
50 ipAddress: string | undefined;
51 /** The ID of the network interface created for the mount target. */
52 networkInterfaceId: string | undefined;
53 /** The name of the Availability Zone the mount target resides in. */
54 availabilityZoneName: string | undefined;
55 },
56 {},
57 Providers
58 > {}
59
60 /**
61 * An Amazon EFS mount target — the per-subnet network endpoint (an ENI
62 * serving NFS on TCP 2049) that compute in a VPC uses to reach a file
63 * system.
64 *
65 * Create one mount target per Availability Zone you run compute in. The
66 * reconciler waits for the mount target to reach the `available` state
67 * (typically 1–2 minutes), so downstream resources that depend on its
68 * attributes deploy only once the endpoint is usable. Deletion likewise
69 * waits until the mount target is fully gone, because its ENI must be
70 * released before the subnet, security groups, or file system can be
71 * deleted.
72 * ### Creating Mount Targets
73 * **Example:** Mount target in a subnet
74 * ```typescript
75 * import * as AWS from "@alchemy.run/aws";
76 *
77 * const files = yield* AWS.EFS.FileSystem("Files");
78 * const target = yield* AWS.EFS.MountTarget("FilesTarget", {
79 * fileSystemId: files.fileSystemId,
80 * subnetId,
81 * });
82 * ```
83 *
84 * **Example:** Mount target with explicit security groups
85 * ```typescript
86 * const target = yield* AWS.EFS.MountTarget("FilesTarget", {
87 * fileSystemId: files.fileSystemId,
88 * subnetId,
89 * securityGroups: [nfsSecurityGroupId],
90 * });
91 * ```
92 *
93 * @resource
94 */
95 export const MountTarget = Resource<MountTarget>("AWS.EFS.MountTarget");
96
97 /**
98 * Internal marker error used to drive the bounded wait for a mount target to
99 * reach the `available` lifecycle state.
100 */
101 export class MountTargetNotAvailable extends Data.TaggedError("MountTargetNotAvailable")<{
102 mountTargetId: string;
103 state: string;
104 }> {}
105
106 /**
107 * Internal marker error used to drive the bounded wait for a mount target to
108 * disappear after deletion (its ENI releases asynchronously).
109 */
110 export class MountTargetStillDeleting extends Data.TaggedError("MountTargetStillDeleting")<{
111 mountTargetId: string;
112 state: string;
113 }> {}
114
115 /**
116 * Mount-target provisioning takes 1–3 minutes. Bounded poll (5s × 36 ≈
117 * 180s), explicitly typed so declaration emit never widens the provider
118 * layer (see PATTERNS §7).
119 */
120 const retryUntilMountTargetAvailable = <E extends { _tag: string }, R>(
121 self: Effect.Effect<efs.MountTargetDescription, E, R>,
122 ): Effect.Effect<efs.MountTargetDescription, E | MountTargetNotAvailable, R> =>
123 Effect.retry(
124 Effect.flatMap(self, (mt) =>
125 mt.LifeCycleState === "available"
126 ? Effect.succeed(mt)
127 : Effect.fail(
128 new MountTargetNotAvailable({
129 mountTargetId: mt.MountTargetId,
130 state: mt.LifeCycleState,
131 }),
132 ),
133 ),
134 {
135 while: (e) => e._tag === "MountTargetNotAvailable",
136 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]),
137 },
138 );
139
140 /**
141 * Deletion releases the mount target's ENI asynchronously (1–3 minutes).
142 * Bounded poll (5s × 36 ≈ 180s) until the mount target is observed gone,
143 * explicitly typed (PATTERNS §7).
144 */
145 const retryUntilMountTargetGone = <A, E extends { _tag: string }, R>(
146 self: Effect.Effect<A, E, R>,
147 ): Effect.Effect<A, E, R> =>
148 Effect.retry(self, {
149 while: (e) => e._tag === "MountTargetStillDeleting",
150 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]),
151 });
152
153 /**
154 * Security-group modifications race the mount target's own state machine;
155 * `IncorrectMountTargetState` while it is still creating is transient.
156 * Bounded retry (~60s), explicitly typed (PATTERNS §7).
157 */
158 const retryWhileMountTargetSettling = <A, E extends { _tag: string }, R>(
159 self: Effect.Effect<A, E, R>,
160 ): Effect.Effect<A, E, R> =>
161 Effect.retry(self, {
162 while: (e) => e._tag === "IncorrectMountTargetState" || e._tag === "DependencyTimeout",
163 schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
164 });
165
166 export const MountTargetProvider = () =>
167 Provider.effect(
168 MountTarget,
169 Effect.gen(function* () {
170 const findById = Effect.fn(function* (mountTargetId: string) {
171 return yield* efs.describeMountTargets({ MountTargetId: mountTargetId }).pipe(
172 Effect.map((r) => r.MountTargets?.[0]),
173 Effect.catchTag("MountTargetNotFound", () => Effect.undefined),
174 );
175 });
176
177 const findBySubnet = Effect.fn(function* (fileSystemId: string, subnetId: string) {
178 return yield* efs.describeMountTargets({ FileSystemId: fileSystemId }).pipe(
179 Effect.map((r) => r.MountTargets?.find((mt) => mt.SubnetId === subnetId)),
180 Effect.catchTag("FileSystemNotFound", () => Effect.undefined),
181 );
182 });
183
184 const toAttributes = (mt: efs.MountTargetDescription) => ({
185 mountTargetId: mt.MountTargetId,
186 fileSystemId: mt.FileSystemId,
187 subnetId: mt.SubnetId,
188 ipAddress: mt.IpAddress,
189 networkInterfaceId: mt.NetworkInterfaceId,
190 availabilityZoneName: mt.AvailabilityZoneName,
191 });
192
193 return MountTarget.Provider.of({
194 stables: ["mountTargetId", "fileSystemId", "subnetId", "ipAddress", "availabilityZoneName"],
195
196 // Mount targets are only enumerable per file system, so walk every
197 // file system in the account/region. A file system can vanish between
198 // the enumeration and the per-FS describe — drop it.
199 list: () =>
200 Effect.gen(function* () {
201 const systems = yield* efs.describeFileSystems.items({}).pipe(
202 Stream.runCollect,
203 Effect.map((chunk) => Array.from(chunk)),
204 );
205 const perSystem = yield* Effect.forEach(
206 systems,
207 (fs) =>
208 efs.describeMountTargets({ FileSystemId: fs.FileSystemId }).pipe(
209 Effect.map((r) =>
210 (r.MountTargets ?? [])
211 .filter((mt) => mt.LifeCycleState !== "deleted")
212 .map(toAttributes),
213 ),
214 Effect.catchTag("FileSystemNotFound", () => Effect.succeed([])),
215 ),
216 { concurrency: 5 },
217 );
218 return perSystem.flat();
219 }),
220
221 // Mount targets are untaggable, so there is no ownership marker to
222 // check: identity is the (fileSystemId, subnetId) pair, matching the
223 // one-mount-target-per-AZ constraint.
224 read: Effect.fn(function* ({ olds, output }) {
225 const mt = output?.mountTargetId
226 ? yield* findById(output.mountTargetId)
227 : olds?.fileSystemId && olds.subnetId
228 ? yield* findBySubnet(olds.fileSystemId, olds.subnetId)
229 : undefined;
230 if (mt === undefined || mt.LifeCycleState === "deleted") {
231 return undefined;
232 }
233 return toAttributes(mt);
234 }),
235
236 diff: Effect.fn(function* ({ news, olds }) {
237 if (!isResolved(news) || olds === undefined) return undefined;
238 if (
239 news.fileSystemId !== olds.fileSystemId ||
240 news.subnetId !== olds.subnetId ||
241 news.ipAddress !== olds.ipAddress
242 ) {
243 return { action: "replace" } as const;
244 }
245 // undefined → default update path (security-group sync)
246 }),
247
248 reconcile: Effect.fn(function* ({ news, output, session }) {
249 // 1. OBSERVE — output.mountTargetId is only a cache; fall through
250 // to the (fileSystemId, subnetId) identity if it is stale.
251 let mt = output?.mountTargetId ? yield* findById(output.mountTargetId) : undefined;
252 if (mt === undefined || mt.LifeCycleState === "deleted") {
253 mt = yield* findBySubnet(news.fileSystemId, news.subnetId);
254 }
255 if (mt?.LifeCycleState === "deleted") {
256 mt = undefined;
257 }
258
259 // 2. ENSURE — create if missing. `MountTargetConflict` means a peer
260 // created it in the same subnet/AZ concurrently — re-observe.
261 if (mt === undefined) {
262 mt = yield* efs
263 .createMountTarget({
264 FileSystemId: news.fileSystemId,
265 SubnetId: news.subnetId,
266 IpAddress: news.ipAddress,
267 SecurityGroups: news.securityGroups,
268 })
269 .pipe(
270 Effect.catchTag("MountTargetConflict", () =>
271 findBySubnet(news.fileSystemId, news.subnetId).pipe(
272 Effect.flatMap((existing) =>
273 existing !== undefined
274 ? Effect.succeed(existing)
275 : efs.createMountTarget({
276 FileSystemId: news.fileSystemId,
277 SubnetId: news.subnetId,
278 IpAddress: news.ipAddress,
279 SecurityGroups: news.securityGroups,
280 }),
281 ),
282 ),
283 ),
284 );
285 }
286
287 const mountTargetId = mt.MountTargetId;
288
289 // Wait for the network endpoint to become usable — dependents
290 // (e.g. a Lambda with fileSystemConfigs) fail to create against a
291 // mount target that is still `creating`.
292 yield* session.note(`waiting for ${mountTargetId} to be available`);
293 mt = yield* retryUntilMountTargetAvailable(
294 efs
295 .describeMountTargets({ MountTargetId: mountTargetId })
296 .pipe(Effect.map((r) => r.MountTargets![0])),
297 );
298
299 // 3. SYNC security groups — diff the OBSERVED set against the
300 // desired one; only call the API on a real delta. When the prop
301 // is omitted the observed groups (VPC default) are left alone.
302 if (news.securityGroups !== undefined) {
303 const observed = yield* efs
304 .describeMountTargetSecurityGroups({
305 MountTargetId: mountTargetId,
306 })
307 .pipe(Effect.map((r) => [...r.SecurityGroups].sort()));
308 const desired = [...news.securityGroups].sort();
309 if (JSON.stringify(observed) !== JSON.stringify(desired)) {
310 yield* retryWhileMountTargetSettling(
311 efs.modifyMountTargetSecurityGroups({
312 MountTargetId: mountTargetId,
313 SecurityGroups: news.securityGroups,
314 }),
315 );
316 }
317 }
318
319 yield* session.note(mountTargetId);
320 return toAttributes(mt);
321 }),
322
323 // Deletion must observe the mount target actually GONE before
324 // returning: its ENI is released asynchronously and the subnet,
325 // security groups, and file system cannot be deleted until then.
326 delete: Effect.fn(function* ({ output, session }) {
327 yield* efs
328 .deleteMountTarget({ MountTargetId: output.mountTargetId })
329 .pipe(Effect.catchTag("MountTargetNotFound", () => Effect.void));
330
331 yield* session.note(`waiting for ${output.mountTargetId} to be deleted`);
332 yield* retryUntilMountTargetGone(
333 efs.describeMountTargets({ MountTargetId: output.mountTargetId }).pipe(
334 Effect.flatMap((r) => {
335 const state = r.MountTargets?.[0]?.LifeCycleState;
336 return state === undefined || state === "deleted"
337 ? Effect.void
338 : Effect.fail(
339 new MountTargetStillDeleting({
340 mountTargetId: output.mountTargetId,
341 state,
342 }),
343 );
344 }),
345 Effect.catchTag("MountTargetNotFound", () => Effect.void),
346 ),
347 );
348 }),
349 });
350 }),
351 );