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

main
ts 427 lines 16.5 KB
Raw
1 import * as athena from "@distilled.cloud/aws/athena";
2 import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
3 import * as datazone from "@distilled.cloud/aws/datazone";
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 * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Schedule from "effect/Schedule";
11 import { deleteGlueDatabase } from "../Glue/internal.ts";
12 import { unredact } from "./internal.ts";
13
14 /**
15 * A name/value provisioning parameter passed to the environment's blueprint.
16 */
17 export interface EnvironmentUserParameter {
18 /** The parameter name. */
19 name?: string;
20 /** The parameter value. */
21 value?: string;
22 }
23
24 export interface EnvironmentProps {
25 /**
26 * The identifier of the {@link Domain} the environment lives in. Accepts a
27 * domain's `domainId` output. Changing it triggers a replacement.
28 */
29 domainId: string;
30 /**
31 * The identifier of the {@link Project} that owns the environment. Accepts
32 * a project's `projectId` output. Changing it triggers a replacement.
33 */
34 projectId: string;
35 /**
36 * Name of the environment. If omitted, a deterministic physical name is
37 * generated from the app, stage, and logical ID. The name is mutable — it
38 * converges via `UpdateEnvironment` without replacement.
39 */
40 name?: string;
41 /**
42 * A description of the environment.
43 */
44 description?: string;
45 /**
46 * The identifier of the environment profile to create the environment
47 * from (V1 domains). Changing it triggers a replacement.
48 */
49 environmentProfileId?: string;
50 /**
51 * The identifier of the environment blueprint to create the environment
52 * from directly (profile-less flows). Changing it triggers a replacement.
53 */
54 environmentBlueprintId?: string;
55 /**
56 * The AWS account to provision the environment in. Defaults to the
57 * domain's account. Changing it triggers a replacement.
58 */
59 environmentAccountId?: string;
60 /**
61 * The region to provision the environment in. Changing it triggers a
62 * replacement.
63 */
64 environmentAccountRegion?: string;
65 /**
66 * Blueprint provisioning parameters (e.g. the Glue database name for
67 * `DefaultDataLake`).
68 */
69 userParameters?: EnvironmentUserParameter[];
70 /**
71 * Glossary term identifiers to attach to the environment.
72 */
73 glossaryTerms?: string[];
74 }
75
76 export interface Environment extends Resource<
77 "AWS.DataZone.Environment",
78 EnvironmentProps,
79 {
80 /** The unique identifier of the environment. */
81 environmentId: string;
82 /** The identifier of the domain the environment lives in. */
83 domainId: string;
84 /** The identifier of the owning project. */
85 projectId: string;
86 /** The name of the environment. */
87 name: string;
88 /** The status of the environment (`ACTIVE` once deployed). */
89 status: string | undefined;
90 /** The provider of the environment (e.g. `Amazon DataZone`). */
91 provider: string;
92 /** The AWS account the environment is provisioned in. */
93 awsAccountId: string | undefined;
94 /** The region the environment is provisioned in. */
95 awsAccountRegion: string | undefined;
96 /** The identifier of the environment profile the environment came from. */
97 environmentProfileId: string | undefined;
98 /** The identifier of the blueprint the environment came from. */
99 environmentBlueprintId: string | undefined;
100 }
101 > {}
102
103 /**
104 * An Amazon DataZone environment — the provisioned collection of AWS
105 * resources (Glue databases, IAM roles, Athena workgroups, ...) a project
106 * works with, deployed from an environment blueprint via CloudFormation.
107 *
108 * Environment deployment is asynchronous (minutes — DataZone drives a
109 * CloudFormation stack) and is polled to `ACTIVE` with a bounded wait. The
110 * environment's blueprint must be configured in the domain first (see
111 * {@link EnvironmentBlueprintConfiguration}).
112 *
113 * ### Creating Environments
114 * **Example:** Environment from a Profile (V1 Domains)
115 * ```typescript
116 * import * as DataZone from "@alchemy.run/aws/DataZone";
117 *
118 * const env = yield* DataZone.Environment("datalake-env", {
119 * domainId: domain.domainId,
120 * projectId: project.projectId,
121 * environmentProfileId: profileId,
122 * });
123 * ```
124 *
125 * **Example:** Environment with Provisioning Parameters
126 * ```typescript
127 * const env = yield* DataZone.Environment("datalake-env", {
128 * domainId: domain.domainId,
129 * projectId: project.projectId,
130 * environmentProfileId: profileId,
131 * description: "Analytics data lake environment",
132 * userParameters: [
133 * { name: "glueDbName", value: "analytics_db" },
134 * ],
135 * });
136 * ```
137 *
138 * @resource
139 */
140 export const Environment = Resource<Environment>("AWS.DataZone.Environment");
141
142 /** The environment deployment settled in a failed state. */
143 export class EnvironmentDeploymentFailed extends Data.TaggedError(
144 "AWS.DataZone.EnvironmentDeploymentFailed",
145 )<{
146 readonly environmentId: string;
147 readonly status: string;
148 readonly reason: string | undefined;
149 }> {
150 override get message() {
151 return `DataZone environment ${this.environmentId} ${this.status}${this.reason ? `: ${this.reason}` : ""}`;
152 }
153 }
154
155 /** Environment status values indicating an in-flight transition to wait out. */
156 const ENVIRONMENT_TRANSIENT = new Set(["CREATING", "UPDATING", "DELETING"]);
157
158 /** Environment status values indicating a failed deployment. */
159 const ENVIRONMENT_FAILED = new Set(["CREATE_FAILED", "UPDATE_FAILED", "VALIDATION_FAILED"]);
160
161 export const EnvironmentProvider = () =>
162 Provider.effect(
163 Environment,
164 Effect.gen(function* () {
165 const createName = Effect.fn(function* (id: string, props: Pick<EnvironmentProps, "name">) {
166 return props.name ?? (yield* createPhysicalName({ id, maxLength: 64 }));
167 });
168
169 // A deleted environment — or one inside a deleted domain — is reported
170 // as AccessDeniedException, NOT ResourceNotFoundException: DataZone
171 // evaluates domain-scoped authorization before existence. Both mean
172 // "absent".
173 const getEnvironmentOrUndefined = Effect.fn(function* (
174 domainId: string,
175 environmentId: string,
176 ) {
177 return yield* datazone
178 .getEnvironment({
179 domainIdentifier: domainId,
180 identifier: environmentId,
181 })
182 .pipe(
183 Effect.catchTags({
184 ResourceNotFoundException: () => Effect.undefined,
185 AccessDeniedException: () => Effect.undefined,
186 }),
187 );
188 });
189
190 const findByName = Effect.fn(function* (domainId: string, projectId: string, name: string) {
191 const found = yield* datazone
192 .listEnvironments({
193 domainIdentifier: domainId,
194 projectIdentifier: projectId,
195 name,
196 })
197 .pipe(
198 Effect.catchTags({
199 ResourceNotFoundException: () => Effect.undefined,
200 AccessDeniedException: () => Effect.undefined,
201 }),
202 );
203 const summary = (found?.items ?? []).find(
204 (s) => unredact(s.name) === name && s.status !== "DELETING",
205 );
206 return summary?.id;
207 });
208
209 // Poll the environment to a settled (non-transient) status. Deployment
210 // drives a CloudFormation stack — bounded at ~5 minutes.
211 const waitForSettled = Effect.fn(function* (domainId: string, environmentId: string) {
212 return yield* getEnvironmentOrUndefined(domainId, environmentId).pipe(
213 Effect.repeat({
214 schedule: Schedule.fixed("5 seconds"),
215 until: (env) =>
216 env === undefined ||
217 env.status === undefined ||
218 !ENVIRONMENT_TRANSIENT.has(env.status),
219 times: 60,
220 }),
221 );
222 });
223
224 // Poll the environment until it no longer exists — teardown drives a
225 // CloudFormation stack delete, bounded at ~5 minutes.
226 const waitForGone = Effect.fn(function* (domainId: string, environmentId: string) {
227 yield* getEnvironmentOrUndefined(domainId, environmentId).pipe(
228 Effect.repeat({
229 schedule: Schedule.fixed("5 seconds"),
230 until: (env) => env === undefined || env.status === "DELETED",
231 times: 60,
232 }),
233 );
234 });
235
236 // DataZone's data-lake blueprint stack retains its Glue databases,
237 // Athena workgroup, and log group (CloudFormation DELETE_SKIPPED), so
238 // deleting the environment leaks them. Read their names from the
239 // environment's provisioned resources and delete them once it is gone.
240 const deleteRetainedResources = Effect.fn(function* (
241 resources: ReadonlyArray<datazone.Resource>,
242 ) {
243 const valueOf = (name: string) => resources.find((r) => r.name === name)?.value;
244 for (const name of ["glueProducerDBName", "glueConsumerDBName"]) {
245 const database = valueOf(name);
246 if (database) yield* deleteGlueDatabase(database, undefined);
247 }
248 const workGroup = valueOf("athenaWorkGroupName");
249 if (workGroup) {
250 yield* athena.deleteWorkGroup({ WorkGroup: workGroup, RecursiveDeleteOption: true });
251 }
252 // arn:aws:logs:{region}:{account}:log-group:{name}:*
253 const logGroup = valueOf("logGroupArn")?.split(":")[6];
254 if (logGroup) {
255 yield* logs
256 .deleteLogGroup({ logGroupName: logGroup })
257 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
258 }
259 });
260
261 const failIfDeploymentFailed = Effect.fn(function* (
262 env: datazone.GetEnvironmentOutput,
263 environmentId: string,
264 ) {
265 if (env.status !== undefined && ENVIRONMENT_FAILED.has(env.status)) {
266 return yield* new EnvironmentDeploymentFailed({
267 environmentId,
268 status: env.status,
269 reason: env.lastDeployment?.failureReason?.message,
270 });
271 }
272 return env;
273 });
274
275 const toAttributes = (env: datazone.GetEnvironmentOutput, environmentId: string) => ({
276 environmentId,
277 domainId: env.domainId,
278 projectId: env.projectId,
279 name: unredact(env.name),
280 status: env.status,
281 provider: env.provider,
282 awsAccountId: env.awsAccountId,
283 awsAccountRegion: env.awsAccountRegion,
284 environmentProfileId: env.environmentProfileId,
285 environmentBlueprintId: env.environmentBlueprintId,
286 });
287
288 return Environment.Provider.of({
289 stables: ["environmentId", "domainId", "projectId", "awsAccountId", "awsAccountRegion"],
290
291 // Environments are keyed by their parent domain + project — there is
292 // no account-level enumeration without those identifiers.
293 list: () => Effect.succeed([]),
294
295 read: Effect.fn(function* ({ id, olds, output }) {
296 const domainId = output?.domainId ?? olds?.domainId;
297 const projectId = output?.projectId ?? olds?.projectId;
298 if (domainId === undefined || projectId === undefined) {
299 return undefined;
300 }
301 const environmentId =
302 output?.environmentId ??
303 (yield* findByName(domainId, projectId, yield* createName(id, olds ?? {})));
304 if (environmentId === undefined) return undefined;
305 const env = yield* getEnvironmentOrUndefined(domainId, environmentId);
306 if (env === undefined || env.status === "DELETING" || env.status === "DELETED") {
307 return undefined;
308 }
309 // Environments have no tags — ownership is tracked purely by
310 // identity.
311 return toAttributes(env, environmentId);
312 }),
313
314 diff: Effect.fn(function* ({ news, olds }) {
315 if (!isResolved(news)) return undefined;
316 if (olds === undefined) return undefined;
317 if (
318 olds.domainId !== news.domainId ||
319 olds.projectId !== news.projectId ||
320 olds.environmentProfileId !== news.environmentProfileId ||
321 olds.environmentBlueprintId !== news.environmentBlueprintId ||
322 olds.environmentAccountId !== news.environmentAccountId ||
323 olds.environmentAccountRegion !== news.environmentAccountRegion
324 ) {
325 return { action: "replace" } as const;
326 }
327 // name, description, and glossaryTerms converge via
328 // updateEnvironment.
329 }),
330
331 reconcile: Effect.fn(function* ({ id, news, output, session }) {
332 const domainId = news.domainId;
333 const projectId = news.projectId;
334 const name = yield* createName(id, news);
335
336 // 1. OBSERVE — cloud state is authoritative; output is only an id
337 // cache. Fall back to a name lookup after state loss.
338 let environmentId = output?.environmentId;
339 let env = environmentId
340 ? yield* getEnvironmentOrUndefined(domainId, environmentId)
341 : undefined;
342 if (env === undefined) {
343 environmentId = yield* findByName(domainId, projectId, name);
344 if (environmentId !== undefined) {
345 env = yield* getEnvironmentOrUndefined(domainId, environmentId);
346 }
347 }
348
349 if (env === undefined) {
350 // 2. ENSURE — create and wait out the CloudFormation deployment.
351 const created = yield* datazone.createEnvironment({
352 domainIdentifier: domainId,
353 projectIdentifier: projectId,
354 name,
355 description: news.description,
356 environmentProfileIdentifier: news.environmentProfileId,
357 environmentBlueprintIdentifier: news.environmentBlueprintId,
358 environmentAccountIdentifier: news.environmentAccountId,
359 environmentAccountRegion: news.environmentAccountRegion,
360 userParameters: news.userParameters,
361 glossaryTerms: news.glossaryTerms,
362 });
363 environmentId = created.id ?? (yield* findByName(domainId, projectId, name));
364 if (environmentId === undefined) {
365 return yield* new EnvironmentDeploymentFailed({
366 environmentId: "",
367 status: "UNKNOWN",
368 reason: `createEnvironment for ${name} returned no id`,
369 });
370 }
371 env = yield* waitForSettled(domainId, environmentId);
372 if (env === undefined) {
373 return yield* new EnvironmentDeploymentFailed({
374 environmentId,
375 status: "DELETED",
376 reason: "environment disappeared during deployment",
377 });
378 }
379 env = yield* failIfDeploymentFailed(env, environmentId);
380 } else {
381 // 3. SYNC — wait out any in-flight transition, then converge the
382 // mutable aspects by diffing OBSERVED state against desired.
383 env = (yield* waitForSettled(domainId, environmentId!)) ?? env;
384 const drifted =
385 unredact(env.name) !== name ||
386 (env.description === undefined ? undefined : unredact(env.description)) !==
387 (news.description ?? undefined);
388 if (drifted) {
389 yield* datazone.updateEnvironment({
390 domainIdentifier: domainId,
391 identifier: environmentId!,
392 name,
393 description: news.description,
394 glossaryTerms: news.glossaryTerms,
395 });
396 env = (yield* waitForSettled(domainId, environmentId!)) ?? env;
397 env = yield* failIfDeploymentFailed(env, environmentId!);
398 }
399 }
400
401 yield* session.note(environmentId!);
402 return toAttributes(env, environmentId!);
403 }),
404
405 delete: Effect.fn(function* ({ output }) {
406 // wait out any in-flight transition first — deleting a CREATING
407 // environment is rejected with a conflict.
408 const env = yield* waitForSettled(output.domainId, output.environmentId);
409 yield* datazone
410 .deleteEnvironment({
411 domainIdentifier: output.domainId,
412 identifier: output.environmentId,
413 })
414 .pipe(
415 Effect.catchTags({
416 ResourceNotFoundException: () => Effect.void,
417 // deleting an environment whose domain is already gone surfaces
418 // as AccessDenied — auth is checked before existence.
419 AccessDeniedException: () => Effect.void,
420 }),
421 );
422 yield* waitForGone(output.domainId, output.environmentId);
423 yield* deleteRetainedResources(env?.provisionedResources ?? []);
424 }),
425 });
426 }),
427 );