@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 547 lines 19.9 KB
Raw
1 import * as memorydb from "@distilled.cloud/aws/memorydb";
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 { toWireDays } from "alchemy/Util/Duration";
9 import * as Data from "effect/Data";
10 import type * as Duration from "effect/Duration";
11 import * as Effect from "effect/Effect";
12 import * as Schedule from "effect/Schedule";
13 import * as Stream from "effect/Stream";
14 import type { Providers } from "../Providers.ts";
15 import { readMemoryDbTags, sameStringSet } from "./internal.ts";
16
17 export class MemoryDBClusterNotReady extends Data.TaggedError("MemoryDBClusterNotReady")<{
18 readonly message: string;
19 readonly cause?: unknown;
20 }> {}
21
22 export class MemoryDBClusterUnexpectedResponse extends Data.TaggedError(
23 "MemoryDBClusterUnexpectedResponse",
24 )<{
25 readonly message: string;
26 readonly cause?: unknown;
27 }> {}
28
29 export interface ClusterProps {
30 /**
31 * Name of the cluster. Must be 1-40 alphanumeric characters. If omitted, a
32 * deterministic physical name is generated. Changing the name replaces the
33 * cluster.
34 */
35 clusterName?: string;
36 /**
37 * Compute and memory capacity of the nodes, e.g. `"db.t4g.small"` (the
38 * cheapest supported node type) or `"db.r7g.large"`.
39 * @default "db.t4g.small"
40 */
41 nodeType?: string;
42 /**
43 * Name of the {@link ACL} that authenticates connections to the cluster.
44 * Required by MemoryDB. The ACL must include a user named `default`.
45 */
46 aclName: string;
47 /**
48 * Name of the {@link SubnetGroup} the cluster's nodes are placed into.
49 * Changing the subnet group replaces the cluster.
50 * @default the default subnet group
51 */
52 subnetGroupName?: string;
53 /**
54 * VPC security groups that control network access to the cluster endpoint.
55 * @default the VPC's default security group
56 */
57 securityGroupIds?: string[];
58 /**
59 * Number of shards (partitions) in the cluster.
60 * @default 1
61 */
62 numShards?: number;
63 /**
64 * Number of read replicas per shard (0-5).
65 * @default 1
66 */
67 numReplicasPerShard?: number;
68 /**
69 * Name of the parameter group applied to the cluster.
70 * @default the engine's default parameter group
71 */
72 parameterGroupName?: string;
73 /**
74 * Human-readable description of the cluster.
75 */
76 description?: string;
77 /**
78 * Engine — `"redis"` or `"valkey"`.
79 * @default "valkey"
80 */
81 engine?: string;
82 /**
83 * Engine version, e.g. `"7.1"` (redis) or `"7.2"` (valkey).
84 * @default latest for the engine
85 */
86 engineVersion?: string;
87 /**
88 * Port the cluster accepts connections on. Changing the port replaces the
89 * cluster.
90 * @default 6379
91 */
92 port?: number;
93 /**
94 * Whether in-transit encryption (TLS) is enabled. Changing this replaces the
95 * cluster.
96 * @default true
97 */
98 tlsEnabled?: boolean;
99 /**
100 * Customer-managed KMS key for encryption at rest. Changing the key replaces
101 * the cluster.
102 * @default AWS-owned key
103 */
104 kmsKeyId?: string;
105 /**
106 * Weekly maintenance window, e.g. `"sun:23:00-mon:01:30"` (UTC).
107 */
108 maintenanceWindow?: string;
109 /**
110 * How long automatic snapshots are retained (e.g. `"7 days"` or
111 * `Duration.days(7)`). Sent to the API in whole days; `Duration.zero`
112 * disables automatic snapshots.
113 */
114 snapshotRetentionLimit?: Duration.Input;
115 /**
116 * Daily window (UTC, `HH:MM-HH:MM`) when automatic snapshots are taken.
117 */
118 snapshotWindow?: string;
119 /**
120 * SNS topic ARN to publish cluster events to.
121 */
122 snsTopicArn?: string;
123 /**
124 * Whether minor engine version upgrades are applied automatically.
125 * @default true
126 */
127 autoMinorVersionUpgrade?: boolean;
128 /**
129 * Whether data tiering (SSD) is enabled. Only supported on r6gd node types.
130 * Changing this replaces the cluster.
131 */
132 dataTiering?: boolean;
133 /**
134 * IP address type. Changing this replaces the cluster.
135 * @default "ipv4"
136 */
137 networkType?: memorydb.NetworkType;
138 /**
139 * IP discovery protocol.
140 */
141 ipDiscovery?: memorydb.IpDiscovery;
142 /**
143 * User-defined tags for the cluster.
144 */
145 tags?: Record<string, string>;
146 }
147
148 export interface Cluster extends Resource<
149 "AWS.MemoryDB.Cluster",
150 ClusterProps,
151 {
152 /** Name of the cluster. */
153 clusterName: string;
154 /** ARN of the cluster. */
155 clusterArn: string;
156 /** Current lifecycle status (e.g. `creating`, `available`). */
157 status: string;
158 /** Node instance type (e.g. `db.t4g.small`). */
159 nodeType: string;
160 /** Engine (`redis` or `valkey`). */
161 engine: string;
162 /** Running engine version. */
163 engineVersion: string | undefined;
164 /** DNS address of the cluster endpoint. */
165 endpointAddress: string | undefined;
166 /** Port of the cluster endpoint. */
167 endpointPort: number | undefined;
168 /** Name of the ACL attached to the cluster. */
169 aclName: string | undefined;
170 /** Name of the parameter group in use. */
171 parameterGroupName: string | undefined;
172 /** Name of the subnet group the cluster's nodes are placed in. */
173 subnetGroupName: string | undefined;
174 /** Whether in-transit encryption (TLS) is enabled. */
175 tlsEnabled: boolean | undefined;
176 /** Number of shards in the cluster. */
177 numberOfShards: number | undefined;
178 /** Tags on the cluster (user + internal Alchemy tags). */
179 tags: Record<string, string>;
180 },
181 never,
182 Providers
183 > {}
184
185 /**
186 * An Amazon MemoryDB cluster — a durable, Redis/Valkey-compatible in-memory
187 * database.
188 *
189 * Clusters take roughly 10-15 minutes to provision and are billed per node
190 * while they exist. They are reachable only from inside a VPC and require an
191 * {@link ACL}; place them in a {@link SubnetGroup} spanning multiple AZs for
192 * high availability. Destroy clusters you are not using.
193 * ### Creating a Cluster
194 * **Example:** Single-Shard Cluster
195 * ```typescript
196 * const user = yield* User("CacheUser", {
197 * authenticationMode: { type: "password", passwords: [cachePassword] },
198 * accessString: "on ~* +@all",
199 * });
200 * const acl = yield* ACL("CacheAcl", { userNames: [user.userName] });
201 * const subnetGroup = yield* SubnetGroup("CacheSubnets", {
202 * subnetIds: [subnetA.subnetId, subnetB.subnetId],
203 * });
204 * const cluster = yield* Cluster("Cache", {
205 * nodeType: "db.t4g.small",
206 * aclName: acl.aclName,
207 * subnetGroupName: subnetGroup.subnetGroupName,
208 * numShards: 1,
209 * numReplicasPerShard: 1,
210 * });
211 * ```
212 *
213 * @resource
214 */
215 export const Cluster = Resource<Cluster>("AWS.MemoryDB.Cluster");
216
217 const DEFAULT_NODE_TYPE = "db.t4g.small";
218
219 export const ClusterProvider = () =>
220 Provider.effect(
221 Cluster,
222 Effect.gen(function* () {
223 const toName = (id: string, props: Partial<ClusterProps>) =>
224 props.clusterName
225 ? Effect.succeed(props.clusterName)
226 : createPhysicalName({ id, maxLength: 40, lowercase: true });
227
228 const readCluster = Effect.fn(function* (name: string) {
229 const response = yield* memorydb
230 .describeClusters({ ClusterName: name })
231 .pipe(Effect.catchTag("ClusterNotFoundFault", () => Effect.undefined));
232 return response?.Clusters?.[0];
233 });
234
235 // Bounded readiness wait. MemoryDB cluster provisioning/modification
236 // typically completes in 10-15 minutes; budget ~20 min (80 * 15s).
237 const waitForAvailable = Effect.fn(function* (name: string) {
238 const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(80)]);
239 return yield* readCluster(name).pipe(
240 Effect.flatMap((cluster) => {
241 if (!cluster?.ARN) {
242 return Effect.fail(
243 new MemoryDBClusterNotReady({ message: `Cluster '${name}' not found` }),
244 );
245 }
246 if (cluster.Status !== "available") {
247 return Effect.fail(
248 new MemoryDBClusterNotReady({
249 message: `Cluster '${name}' not available (status: ${cluster.Status})`,
250 }),
251 );
252 }
253 return Effect.succeed(cluster);
254 }),
255 Effect.retry({ schedule: policy }),
256 );
257 });
258
259 // Wait for a cluster to leave a transitional state before delete. Ends
260 // when the cluster is available, deleting, or gone.
261 const waitUntilSettled = Effect.fn(function* (name: string) {
262 const policy = Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(80)]);
263 return yield* readCluster(name).pipe(
264 Effect.flatMap((cluster) => {
265 if (
266 cluster !== undefined &&
267 cluster.Status !== "available" &&
268 cluster.Status !== "deleting"
269 ) {
270 return Effect.fail(
271 new MemoryDBClusterNotReady({
272 message: `Cluster '${name}' still settling (status: ${cluster.Status})`,
273 }),
274 );
275 }
276 return Effect.succeed(cluster);
277 }),
278 Effect.retry({ schedule: policy }),
279 );
280 });
281
282 const toAttrs = Effect.fn(function* (cluster: memorydb.Cluster) {
283 if (!cluster.Name || !cluster.ARN) {
284 return yield* new MemoryDBClusterUnexpectedResponse({
285 message: `Cluster '${cluster.Name}' is missing its ARN`,
286 });
287 }
288 return {
289 clusterName: cluster.Name,
290 clusterArn: cluster.ARN,
291 status: cluster.Status ?? "available",
292 nodeType: cluster.NodeType ?? DEFAULT_NODE_TYPE,
293 engine: cluster.Engine ?? "valkey",
294 engineVersion: cluster.EngineVersion,
295 endpointAddress: cluster.ClusterEndpoint?.Address,
296 endpointPort: cluster.ClusterEndpoint?.Port,
297 aclName: cluster.ACLName,
298 parameterGroupName: cluster.ParameterGroupName,
299 subnetGroupName: cluster.SubnetGroupName,
300 tlsEnabled: cluster.TLSEnabled,
301 numberOfShards: cluster.NumberOfShards,
302 tags: yield* readMemoryDbTags(cluster.ARN),
303 };
304 });
305
306 return {
307 stables: ["clusterName", "clusterArn"],
308
309 diff: Effect.fn(function* ({ id, olds, news }) {
310 if (!isResolved(news)) return undefined;
311 const n = news ?? { aclName: "" };
312 const o = olds ?? { aclName: "" };
313 if ((yield* toName(id, o)) !== (yield* toName(id, n))) {
314 return { action: "replace" } as const;
315 }
316 // Create-only properties force a replacement.
317 if (
318 n.subnetGroupName !== undefined &&
319 o.subnetGroupName !== undefined &&
320 n.subnetGroupName !== o.subnetGroupName
321 ) {
322 return { action: "replace" } as const;
323 }
324 if ((n.port ?? undefined) !== (o.port ?? undefined)) {
325 return { action: "replace" } as const;
326 }
327 if ((n.tlsEnabled ?? undefined) !== (o.tlsEnabled ?? undefined)) {
328 return { action: "replace" } as const;
329 }
330 if ((n.kmsKeyId ?? undefined) !== (o.kmsKeyId ?? undefined)) {
331 return { action: "replace" } as const;
332 }
333 if ((n.networkType ?? undefined) !== (o.networkType ?? undefined)) {
334 return { action: "replace" } as const;
335 }
336 if ((n.dataTiering ?? undefined) !== (o.dataTiering ?? undefined)) {
337 return { action: "replace" } as const;
338 }
339 if ((n.engine ?? undefined) !== (o.engine ?? undefined)) {
340 return { action: "replace" } as const;
341 }
342 }),
343
344 read: Effect.fn(function* ({ id, olds, output }) {
345 const name = output?.clusterName ?? (yield* toName(id, olds ?? { aclName: "" }));
346 const cluster = yield* readCluster(name);
347 if (!cluster?.ARN) return undefined;
348 const attrs = yield* toAttrs(cluster);
349 return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
350 }),
351
352 reconcile: Effect.fn(function* ({ id, news, output, session }) {
353 const props = news!;
354 const name = output?.clusterName ?? (yield* toName(id, props));
355 const internalTags = yield* createInternalTags(id);
356 const desiredTags = { ...internalTags, ...props.tags };
357 // The wire field is whole days.
358 const snapshotRetentionDays = toWireDays(props.snapshotRetentionLimit);
359
360 // 1. Observe — cloud state is authoritative.
361 let observed = yield* readCluster(name);
362
363 // 2. Ensure — create if missing; tolerate AlreadyExists as a race.
364 if (observed === undefined) {
365 yield* memorydb
366 .createCluster({
367 ClusterName: name,
368 NodeType: props.nodeType ?? DEFAULT_NODE_TYPE,
369 ACLName: props.aclName,
370 SubnetGroupName: props.subnetGroupName,
371 SecurityGroupIds: props.securityGroupIds,
372 NumShards: props.numShards,
373 NumReplicasPerShard: props.numReplicasPerShard,
374 ParameterGroupName: props.parameterGroupName,
375 Description: props.description,
376 Engine: props.engine,
377 EngineVersion: props.engineVersion,
378 Port: props.port,
379 TLSEnabled: props.tlsEnabled,
380 KmsKeyId: props.kmsKeyId,
381 MaintenanceWindow: props.maintenanceWindow,
382 SnapshotRetentionLimit: snapshotRetentionDays,
383 SnapshotWindow: props.snapshotWindow,
384 SnsTopicArn: props.snsTopicArn,
385 AutoMinorVersionUpgrade: props.autoMinorVersionUpgrade,
386 DataTiering: props.dataTiering,
387 NetworkType: props.networkType,
388 IpDiscovery: props.ipDiscovery,
389 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
390 Key,
391 Value,
392 })),
393 })
394 .pipe(Effect.catchTag("ClusterAlreadyExistsFault", () => Effect.void));
395 }
396
397 // Provisioning and in-flight modifications both surface as a
398 // non-available status; wait for availability (bounded) so modify
399 // calls do not hit InvalidClusterStateFault.
400 observed = yield* waitForAvailable(name);
401
402 // 3. Sync — compute the update delta from OBSERVED state.
403 const update: memorydb.UpdateClusterRequest = { ClusterName: name };
404 let mutated = false;
405 if (props.description !== undefined && props.description !== observed.Description) {
406 update.Description = props.description;
407 mutated = true;
408 }
409 const observedSg = (observed.SecurityGroups ?? [])
410 .map((g) => g.SecurityGroupId)
411 .filter((g): g is string => g !== undefined);
412 if (
413 props.securityGroupIds !== undefined &&
414 !sameStringSet(props.securityGroupIds, observedSg)
415 ) {
416 update.SecurityGroupIds = props.securityGroupIds;
417 mutated = true;
418 }
419 if (
420 props.maintenanceWindow !== undefined &&
421 props.maintenanceWindow !== observed.MaintenanceWindow
422 ) {
423 update.MaintenanceWindow = props.maintenanceWindow;
424 mutated = true;
425 }
426 if (
427 snapshotRetentionDays !== undefined &&
428 snapshotRetentionDays !== (observed.SnapshotRetentionLimit ?? 0)
429 ) {
430 update.SnapshotRetentionLimit = snapshotRetentionDays;
431 mutated = true;
432 }
433 if (
434 props.snapshotWindow !== undefined &&
435 props.snapshotWindow !== observed.SnapshotWindow
436 ) {
437 update.SnapshotWindow = props.snapshotWindow;
438 mutated = true;
439 }
440 if (props.nodeType !== undefined && props.nodeType !== observed.NodeType) {
441 update.NodeType = props.nodeType;
442 mutated = true;
443 }
444 if (props.engineVersion !== undefined && props.engineVersion !== observed.EngineVersion) {
445 update.EngineVersion = props.engineVersion;
446 mutated = true;
447 }
448 if (
449 props.parameterGroupName !== undefined &&
450 props.parameterGroupName !== observed.ParameterGroupName
451 ) {
452 update.ParameterGroupName = props.parameterGroupName;
453 mutated = true;
454 }
455 if (props.aclName !== undefined && props.aclName !== observed.ACLName) {
456 update.ACLName = props.aclName;
457 mutated = true;
458 }
459 if (props.ipDiscovery !== undefined && props.ipDiscovery !== observed.IpDiscovery) {
460 update.IpDiscovery = props.ipDiscovery;
461 mutated = true;
462 }
463 if (props.numShards !== undefined && props.numShards !== observed.NumberOfShards) {
464 update.ShardConfiguration = { ShardCount: props.numShards };
465 mutated = true;
466 }
467
468 if (mutated) {
469 yield* memorydb.updateCluster(update);
470 observed = yield* waitForAvailable(name);
471 }
472
473 // 3b. Sync tags — diff against OBSERVED cloud tags.
474 const arn = observed.ARN;
475 if (arn) {
476 const observedTags = yield* readMemoryDbTags(arn);
477 const { removed, upsert } = diffTags(observedTags, desiredTags);
478 if (upsert.length > 0) {
479 yield* memorydb.tagResource({ ResourceArn: arn, Tags: upsert });
480 }
481 if (removed.length > 0) {
482 yield* memorydb.untagResource({
483 ResourceArn: arn,
484 TagKeys: removed,
485 });
486 }
487 }
488
489 yield* session.note(name);
490 return yield* toAttrs(observed);
491 }),
492
493 delete: Effect.fn(function* ({ output }) {
494 const name = output.clusterName;
495 // A cluster mid-create/modify rejects deletion with
496 // InvalidClusterStateFault — wait (bounded) for it to settle first.
497 // A cluster already deleting (or gone) is success.
498 const settled = yield* waitUntilSettled(name).pipe(Effect.orElseSucceed(() => undefined));
499 if (settled === undefined) {
500 return;
501 }
502 if (settled.Status !== "deleting") {
503 yield* memorydb.deleteCluster({ ClusterName: name }).pipe(
504 Effect.catchTag("ClusterNotFoundFault", () => Effect.void),
505 Effect.retry({
506 while: (e) => e._tag === "InvalidClusterStateFault",
507 schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(20)]),
508 }),
509 Effect.catchTag("InvalidClusterStateFault", () => Effect.void),
510 );
511 }
512 // Wait until the cluster is actually gone: a `deleting` cluster
513 // still holds its subnet group and ACL, so dependents deleted right
514 // after fail with SubnetGroupInUseFault / InvalidACLStateFault.
515 // MemoryDB cluster deletion typically takes 5-10 minutes; budget
516 // ~15 min (60 * 15s).
517 yield* readCluster(name).pipe(
518 Effect.flatMap((cluster) =>
519 cluster === undefined
520 ? Effect.void
521 : Effect.fail(
522 new MemoryDBClusterNotReady({
523 message: `MemoryDB cluster '${name}' still deleting (status: ${cluster.Status})`,
524 }),
525 ),
526 ),
527 Effect.retry({
528 schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]),
529 }),
530 );
531 }),
532
533 list: () =>
534 memorydb.describeClusters.pages({}).pipe(
535 Stream.runCollect,
536 Effect.map((chunk) =>
537 Array.from(chunk).flatMap((page) =>
538 (page.Clusters ?? []).filter(
539 (cluster) => cluster.Name !== undefined && cluster.ARN !== undefined,
540 ),
541 ),
542 ),
543 Effect.flatMap(Effect.forEach((cluster) => toAttrs(cluster), { concurrency: 4 })),
544 ),
545 };
546 }),
547 );