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

main
ts 549 lines 21.4 KB
Raw
1 import * as dax from "@distilled.cloud/aws/dax";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Schedule from "effect/Schedule";
11 import type { Providers } from "../Providers.ts";
12 import { readDaxTags, sameStringSet } from "./internal.ts";
13
14 export class DAXClusterNotReady extends Data.TaggedError("DAXClusterNotReady")<{
15 readonly message: string;
16 readonly cause?: unknown;
17 }> {}
18
19 export class DAXClusterUnexpectedResponse extends Data.TaggedError("DAXClusterUnexpectedResponse")<{
20 readonly message: string;
21 readonly cause?: unknown;
22 }> {}
23
24 export interface ClusterProps {
25 /**
26 * Name of the cluster. Must be 1-20 alphanumeric characters or hyphens.
27 * If omitted, a deterministic physical name is generated. Changing the
28 * name replaces the cluster.
29 */
30 clusterName?: string;
31 /**
32 * Compute and memory capacity of the nodes, e.g. `"dax.t3.small"` (the
33 * cheapest supported node type) or `"dax.r5.large"`. Changing the node
34 * type replaces the cluster.
35 * @default "dax.t3.small"
36 */
37 nodeType?: string;
38 /**
39 * Number of nodes in the cluster (1 = a single node; 2+ = one primary
40 * plus read replicas). AWS recommends at least 3 nodes (spanning multiple
41 * Availability Zones) for production. Updated in place via
42 * IncreaseReplicationFactor / DecreaseReplicationFactor.
43 * @default 1
44 */
45 replicationFactor?: number;
46 /**
47 * ARN of the IAM role that DAX assumes to access DynamoDB tables on your
48 * behalf. The role's trust policy must allow `dax.amazonaws.com` to assume
49 * it. Changing the role replaces the cluster.
50 */
51 iamRoleArn: string;
52 /**
53 * Human-readable description of the cluster.
54 */
55 description?: string;
56 /**
57 * Availability Zones the nodes are placed into. Must be a subset of the
58 * AZs covered by the subnet group and match `replicationFactor` in length
59 * when provided. Changing the AZs replaces the cluster.
60 * @default DAX spreads nodes across the subnet group's AZs
61 */
62 availabilityZones?: string[];
63 /**
64 * Name of the {@link SubnetGroup} the cluster's nodes are placed into.
65 * Changing the subnet group replaces the cluster.
66 * @default the default DAX subnet group
67 */
68 subnetGroupName?: string;
69 /**
70 * VPC security groups that control network access to the cluster
71 * endpoint.
72 * @default the VPC's default security group
73 */
74 securityGroupIds?: string[];
75 /**
76 * Weekly maintenance window, e.g. `"sun:23:00-mon:01:30"` (UTC).
77 */
78 preferredMaintenanceWindow?: string;
79 /**
80 * SNS topic ARN to publish cluster events to.
81 */
82 notificationTopicArn?: string;
83 /**
84 * Name of the {@link ParameterGroup} applied to the cluster.
85 * @default the default DAX parameter group
86 */
87 parameterGroupName?: string;
88 /**
89 * Whether server-side encryption (encryption at rest) is enabled.
90 * Changing this replaces the cluster.
91 * @default false
92 */
93 sseEnabled?: boolean;
94 /**
95 * Encryption in transit for the cluster endpoint — `"NONE"` or `"TLS"`.
96 * Changing this replaces the cluster.
97 * @default "NONE"
98 */
99 clusterEndpointEncryptionType?: dax.ClusterEndpointEncryptionType;
100 /**
101 * IP address type — `"ipv4"`, `"ipv6"` or `"dual_stack"`. Changing this
102 * replaces the cluster.
103 * @default "ipv4"
104 */
105 networkType?: dax.NetworkType;
106 /**
107 * User-defined tags for the cluster.
108 */
109 tags?: Record<string, string>;
110 }
111
112 export interface Cluster extends Resource<
113 "AWS.DAX.Cluster",
114 ClusterProps,
115 {
116 /** Name of the DAX cluster. */
117 clusterName: string;
118 /** ARN of the DAX cluster. */
119 clusterArn: string;
120 /** Current cluster status (e.g. `available`, `creating`). */
121 status: string;
122 /** Compute/memory node type of the cluster's nodes. */
123 nodeType: string;
124 /** Total number of nodes in the cluster. */
125 totalNodes: number | undefined;
126 /** Number of nodes currently in `available` status. */
127 activeNodes: number | undefined;
128 /** Hostname of the cluster discovery endpoint. */
129 discoveryEndpointAddress: string | undefined;
130 /** Port of the cluster discovery endpoint. */
131 discoveryEndpointPort: number | undefined;
132 /** Full `dax://` (or `daxs://` for TLS) discovery endpoint URL clients connect to. */
133 discoveryEndpointUrl: string | undefined;
134 /** Name of the subnet group the cluster's nodes are placed into. */
135 subnetGroupName: string | undefined;
136 /** ARN of the IAM role DAX assumes to reach DynamoDB. */
137 iamRoleArn: string | undefined;
138 /** Name of the parameter group attached to the cluster. */
139 parameterGroupName: string | undefined;
140 /** Security group IDs attached to the cluster's nodes. */
141 securityGroupIds: string[];
142 /** Endpoint encryption in transit (`NONE` or `TLS`). */
143 clusterEndpointEncryptionType: string | undefined;
144 /** Current tags on the cluster. */
145 tags: Record<string, string>;
146 },
147 never,
148 Providers
149 > {}
150
151 /**
152 * An Amazon DAX cluster — a fully managed, in-memory write-through cache for
153 * DynamoDB.
154 *
155 * Clusters are VPC-only and take roughly 5-10 minutes to provision; they are
156 * billed per node-hour while they exist. Place them in a {@link SubnetGroup}
157 * and give them an IAM role that DAX assumes to reach DynamoDB. Destroy
158 * clusters you are not using.
159 * ### Creating a Cluster
160 * **Example:** Single-Node Development Cluster
161 * ```typescript
162 * const role = yield* IAM.Role("DaxRole", {
163 * assumeRolePolicyDocument: {
164 * Version: "2012-10-17",
165 * Statement: [{
166 * Effect: "Allow",
167 * Principal: { Service: "dax.amazonaws.com" },
168 * Action: ["sts:AssumeRole"],
169 * }],
170 * },
171 * managedPolicyArns: ["arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess"],
172 * });
173 * const subnetGroup = yield* SubnetGroup("DaxSubnets", {
174 * subnetIds: [subnetA.subnetId, subnetB.subnetId],
175 * });
176 * const cluster = yield* Cluster("Cache", {
177 * nodeType: "dax.t3.small",
178 * replicationFactor: 1,
179 * iamRoleArn: role.roleArn,
180 * subnetGroupName: subnetGroup.subnetGroupName,
181 * });
182 * ```
183 *
184 * ### Encryption
185 * **Example:** Cluster with Encryption At Rest and In Transit
186 * ```typescript
187 * const cluster = yield* Cluster("SecureCache", {
188 * nodeType: "dax.t3.small",
189 * replicationFactor: 3,
190 * iamRoleArn: role.roleArn,
191 * subnetGroupName: subnetGroup.subnetGroupName,
192 * sseEnabled: true,
193 * clusterEndpointEncryptionType: "TLS",
194 * });
195 * ```
196 *
197 * @resource
198 */
199 export const Cluster = Resource<Cluster>("AWS.DAX.Cluster");
200
201 const DEFAULT_NODE_TYPE = "dax.t3.small";
202 const DEFAULT_REPLICATION_FACTOR = 1;
203
204 // A freshly created IAM role is not immediately assumable by dax.amazonaws.com
205 // — CreateCluster rejects with "No permission to assume role" until IAM
206 // propagates (typically a few seconds). Bounded retry through that window.
207 const retryIamRolePropagation = <A, E extends { _tag: string }, R>(
208 self: Effect.Effect<A, E, R>,
209 ): Effect.Effect<A, E, R> =>
210 Effect.retry(self, {
211 while: (e) =>
212 e._tag === "InvalidParameterValueException" &&
213 ((e as { message?: string }).message?.includes("No permission to assume role") ?? false),
214 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(10)]),
215 });
216
217 export const ClusterProvider = () =>
218 Provider.effect(
219 Cluster,
220 Effect.gen(function* () {
221 // DAX cluster names must start with a letter. At its 20-character limit
222 // a generated name is all hash and instance suffix, which can start
223 // with a digit, so lead with a letter then.
224 const toName = (id: string, props: Partial<ClusterProps>) =>
225 props.clusterName
226 ? Effect.succeed(props.clusterName)
227 : createPhysicalName({ id, maxLength: 20, lowercase: true }).pipe(
228 Effect.map((name) => (/^[a-z]/.test(name) ? name : `d${name.slice(0, 19)}`)),
229 );
230
231 const readCluster = Effect.fn(function* (name: string) {
232 const response = yield* dax
233 .describeClusters({ ClusterNames: [name] })
234 .pipe(Effect.catchTag("ClusterNotFoundFault", () => Effect.undefined));
235 return response?.Clusters?.[0];
236 });
237
238 // Bounded readiness wait. DAX cluster provisioning/modification
239 // typically completes in 5-10 minutes; budget ~15 min (60 * 15s).
240 const waitForAvailable = Effect.fn(function* (name: string) {
241 const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]);
242 return yield* readCluster(name).pipe(
243 Effect.flatMap((cluster) => {
244 if (!cluster?.ClusterArn) {
245 return Effect.fail(
246 new DAXClusterNotReady({ message: `DAX cluster '${name}' not found` }),
247 );
248 }
249 if (cluster.Status !== "available") {
250 return Effect.fail(
251 new DAXClusterNotReady({
252 message: `DAX cluster '${name}' not available (status: ${cluster.Status})`,
253 }),
254 );
255 }
256 return Effect.succeed(cluster);
257 }),
258 Effect.retry({ schedule: policy }),
259 );
260 });
261
262 // Wait for a cluster to leave a transitional state before delete. Ends
263 // when the cluster is available, deleting, or gone.
264 const waitUntilSettled = Effect.fn(function* (name: string) {
265 const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]);
266 return yield* readCluster(name).pipe(
267 Effect.flatMap((cluster) => {
268 if (
269 cluster !== undefined &&
270 cluster.Status !== "available" &&
271 cluster.Status !== "deleting"
272 ) {
273 return Effect.fail(
274 new DAXClusterNotReady({
275 message: `DAX cluster '${name}' still settling (status: ${cluster.Status})`,
276 }),
277 );
278 }
279 return Effect.succeed(cluster);
280 }),
281 Effect.retry({ schedule: policy }),
282 );
283 });
284
285 const toAttrs = Effect.fn(function* (cluster: dax.Cluster) {
286 if (!cluster.ClusterName || !cluster.ClusterArn) {
287 return yield* new DAXClusterUnexpectedResponse({
288 message: `DAX cluster '${cluster.ClusterName}' is missing its ARN`,
289 });
290 }
291 return {
292 clusterName: cluster.ClusterName,
293 clusterArn: cluster.ClusterArn,
294 status: cluster.Status ?? "available",
295 nodeType: cluster.NodeType ?? DEFAULT_NODE_TYPE,
296 totalNodes: cluster.TotalNodes,
297 activeNodes: cluster.ActiveNodes,
298 discoveryEndpointAddress: cluster.ClusterDiscoveryEndpoint?.Address,
299 discoveryEndpointPort: cluster.ClusterDiscoveryEndpoint?.Port,
300 discoveryEndpointUrl: cluster.ClusterDiscoveryEndpoint?.URL,
301 subnetGroupName: cluster.SubnetGroup,
302 iamRoleArn: cluster.IamRoleArn,
303 parameterGroupName: cluster.ParameterGroup?.ParameterGroupName,
304 securityGroupIds: (cluster.SecurityGroups ?? [])
305 .map((g) => g.SecurityGroupIdentifier)
306 .filter((g): g is string => g !== undefined),
307 clusterEndpointEncryptionType: cluster.ClusterEndpointEncryptionType,
308 tags: yield* readDaxTags(cluster.ClusterArn),
309 };
310 });
311
312 return {
313 stables: ["clusterName", "clusterArn"],
314
315 diff: Effect.fn(function* ({ id, olds, news }) {
316 if (!isResolved(news)) return undefined;
317 const n = news ?? { iamRoleArn: "" };
318 const o = olds ?? { iamRoleArn: "" };
319 if ((yield* toName(id, o)) !== (yield* toName(id, n))) {
320 return { action: "replace" } as const;
321 }
322 // Create-only properties force a replacement.
323 if ((n.nodeType ?? DEFAULT_NODE_TYPE) !== (o.nodeType ?? DEFAULT_NODE_TYPE)) {
324 return { action: "replace" } as const;
325 }
326 if (n.iamRoleArn !== o.iamRoleArn) {
327 return { action: "replace" } as const;
328 }
329 if (
330 n.subnetGroupName !== undefined &&
331 o.subnetGroupName !== undefined &&
332 n.subnetGroupName !== o.subnetGroupName
333 ) {
334 return { action: "replace" } as const;
335 }
336 if ((n.sseEnabled ?? false) !== (o.sseEnabled ?? false)) {
337 return { action: "replace" } as const;
338 }
339 if (
340 (n.clusterEndpointEncryptionType ?? "NONE") !==
341 (o.clusterEndpointEncryptionType ?? "NONE")
342 ) {
343 return { action: "replace" } as const;
344 }
345 if ((n.networkType ?? undefined) !== (o.networkType ?? undefined)) {
346 return { action: "replace" } as const;
347 }
348 if (!sameStringSet(n.availabilityZones, o.availabilityZones)) {
349 return { action: "replace" } as const;
350 }
351 }),
352
353 read: Effect.fn(function* ({ id, olds, output }) {
354 const name = output?.clusterName ?? (yield* toName(id, olds ?? { iamRoleArn: "" }));
355 const cluster = yield* readCluster(name);
356 if (!cluster?.ClusterArn) return undefined;
357 const attrs = yield* toAttrs(cluster);
358 return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
359 }),
360
361 reconcile: Effect.fn(function* ({ id, news, output, session }) {
362 const props = news!;
363 const name = output?.clusterName ?? (yield* toName(id, props));
364 const internalTags = yield* createInternalTags(id);
365 const desiredTags = { ...internalTags, ...props.tags };
366 const desiredReplicationFactor = props.replicationFactor ?? DEFAULT_REPLICATION_FACTOR;
367
368 // 1. Observe — cloud state is authoritative.
369 let observed = yield* readCluster(name);
370
371 // 2. Ensure — create if missing; tolerate AlreadyExists as a race.
372 if (observed === undefined) {
373 yield* dax
374 .createCluster({
375 ClusterName: name,
376 NodeType: props.nodeType ?? DEFAULT_NODE_TYPE,
377 ReplicationFactor: desiredReplicationFactor,
378 IamRoleArn: props.iamRoleArn,
379 Description: props.description,
380 AvailabilityZones: props.availabilityZones,
381 SubnetGroupName: props.subnetGroupName,
382 SecurityGroupIds: props.securityGroupIds,
383 PreferredMaintenanceWindow: props.preferredMaintenanceWindow,
384 NotificationTopicArn: props.notificationTopicArn,
385 ParameterGroupName: props.parameterGroupName,
386 SSESpecification:
387 props.sseEnabled !== undefined ? { Enabled: props.sseEnabled } : undefined,
388 ClusterEndpointEncryptionType: props.clusterEndpointEncryptionType,
389 NetworkType: props.networkType,
390 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
391 Key,
392 Value,
393 })),
394 })
395 .pipe(
396 retryIamRolePropagation,
397 Effect.catchTag("ClusterAlreadyExistsFault", () => Effect.void),
398 );
399 }
400
401 // Provisioning and in-flight modifications both surface as a
402 // non-available status; wait for availability (bounded) so update
403 // calls do not hit InvalidClusterStateFault.
404 observed = yield* waitForAvailable(name);
405
406 // 3. Sync — compute the update delta from OBSERVED state.
407 const update: dax.UpdateClusterRequest = { ClusterName: name };
408 let mutated = false;
409 if (props.description !== undefined && props.description !== observed.Description) {
410 update.Description = props.description;
411 mutated = true;
412 }
413 if (
414 props.preferredMaintenanceWindow !== undefined &&
415 props.preferredMaintenanceWindow !== observed.PreferredMaintenanceWindow
416 ) {
417 update.PreferredMaintenanceWindow = props.preferredMaintenanceWindow;
418 mutated = true;
419 }
420 if (
421 props.notificationTopicArn !== undefined &&
422 props.notificationTopicArn !== observed.NotificationConfiguration?.TopicArn
423 ) {
424 update.NotificationTopicArn = props.notificationTopicArn;
425 mutated = true;
426 }
427 if (
428 props.parameterGroupName !== undefined &&
429 props.parameterGroupName !== observed.ParameterGroup?.ParameterGroupName
430 ) {
431 update.ParameterGroupName = props.parameterGroupName;
432 mutated = true;
433 }
434 const observedSg = (observed.SecurityGroups ?? [])
435 .map((g) => g.SecurityGroupIdentifier)
436 .filter((g): g is string => g !== undefined);
437 if (
438 props.securityGroupIds !== undefined &&
439 !sameStringSet(props.securityGroupIds, observedSg)
440 ) {
441 update.SecurityGroupIds = props.securityGroupIds;
442 mutated = true;
443 }
444 if (mutated) {
445 yield* dax.updateCluster(update);
446 observed = yield* waitForAvailable(name);
447 }
448
449 // 3b. Sync replication factor — DAX has dedicated add/remove-node
450 // APIs instead of a general update.
451 const observedFactor = observed.TotalNodes;
452 if (observedFactor !== undefined && observedFactor !== desiredReplicationFactor) {
453 if (desiredReplicationFactor > observedFactor) {
454 yield* dax.increaseReplicationFactor({
455 ClusterName: name,
456 NewReplicationFactor: desiredReplicationFactor,
457 });
458 } else {
459 yield* dax.decreaseReplicationFactor({
460 ClusterName: name,
461 NewReplicationFactor: desiredReplicationFactor,
462 });
463 }
464 observed = yield* waitForAvailable(name);
465 }
466
467 // 3c. Sync tags — diff against OBSERVED cloud tags.
468 const arn = observed.ClusterArn;
469 if (arn) {
470 const observedTags = yield* readDaxTags(arn);
471 const { removed, upsert } = diffTags(observedTags, desiredTags);
472 if (upsert.length > 0) {
473 yield* dax.tagResource({ ResourceName: arn, Tags: upsert });
474 }
475 if (removed.length > 0) {
476 yield* dax.untagResource({ ResourceName: arn, TagKeys: removed });
477 }
478 }
479
480 yield* session.note(name);
481 return yield* toAttrs(observed);
482 }),
483
484 delete: Effect.fn(function* ({ output }) {
485 const name = output.clusterName;
486 // A cluster mid-create/modify rejects deletion with
487 // InvalidClusterStateFault — wait (bounded) for it to settle
488 // first. A cluster already deleting (or gone) is success.
489 const settled = yield* waitUntilSettled(name).pipe(Effect.orElseSucceed(() => undefined));
490 if (settled === undefined) {
491 return;
492 }
493 if (settled.Status !== "deleting") {
494 yield* dax.deleteCluster({ ClusterName: name }).pipe(
495 Effect.catchTag("ClusterNotFoundFault", () => Effect.void),
496 Effect.retry({
497 while: (e) => e._tag === "InvalidClusterStateFault",
498 schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(20)]),
499 }),
500 // Exhausted retries: the cluster is in a state (e.g. an
501 // out-of-band delete already in flight) where deletion is
502 // already converging — treat as success like the NotFound case.
503 Effect.catchTag("InvalidClusterStateFault", () => Effect.void),
504 );
505 }
506 // Wait until the cluster is actually gone: a `deleting` cluster
507 // still holds its subnet/parameter groups, so dependents deleted
508 // right after would fail with SubnetGroupInUseFault. DAX cluster
509 // deletion typically takes 5-10 minutes; budget ~15 min (60 * 15s).
510 yield* readCluster(name).pipe(
511 Effect.flatMap((cluster) =>
512 cluster === undefined
513 ? Effect.void
514 : Effect.fail(
515 new DAXClusterNotReady({
516 message: `DAX cluster '${name}' still deleting (status: ${cluster.Status})`,
517 }),
518 ),
519 ),
520 Effect.retry({
521 schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]),
522 }),
523 );
524 }),
525
526 list: () =>
527 Effect.gen(function* () {
528 // Bounded hand-rolled pagination (no distilled paginator).
529 const clusters: dax.Cluster[] = [];
530 let nextToken: string | undefined;
531 for (let page = 0; page < 20; page++) {
532 const response = yield* dax.describeClusters({
533 NextToken: nextToken,
534 });
535 clusters.push(...(response.Clusters ?? []));
536 nextToken = response.NextToken;
537 if (!nextToken) break;
538 }
539 return yield* Effect.forEach(
540 clusters.filter(
541 (cluster) => cluster.ClusterName !== undefined && cluster.ClusterArn !== undefined,
542 ),
543 (cluster) => toAttrs(cluster),
544 { concurrency: 4 },
545 );
546 }),
547 };
548 }),
549 );