@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, 06:00 UTC

main
ts 493 lines 18.3 KB
Raw
1 import * as finspace from "@distilled.cloud/aws/finspace";
2 import { isResolved } from "alchemy/Diff";
3 import { createPhysicalName } from "alchemy/PhysicalName";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import { createInternalTags } from "alchemy/Tags";
7 import { toWireSeconds } from "alchemy/Util/Duration";
8 import * as Data from "effect/Data";
9 import type * as Duration from "effect/Duration";
10 import * as Effect from "effect/Effect";
11 import * as Schedule from "effect/Schedule";
12 import type { Providers } from "../Providers.ts";
13
14 export class KxClusterInvalidProps extends Data.TaggedError("KxClusterInvalidProps")<{
15 readonly message: string;
16 readonly cause?: unknown;
17 }> {}
18
19 export class KxClusterUnexpectedResponse extends Data.TaggedError("KxClusterUnexpectedResponse")<{
20 readonly message: string;
21 readonly cause?: unknown;
22 }> {}
23
24 export type KxClusterStatus = finspace.KxClusterStatus;
25 export type KxClusterType = finspace.KxClusterType;
26 export type KxAzMode = finspace.KxAzMode;
27 export type VpcConfiguration = finspace.VpcConfiguration;
28 export type CapacityConfiguration = finspace.CapacityConfiguration;
29 export type CodeConfiguration = finspace.CodeConfiguration;
30 export type KxCommandLineArgument = finspace.KxCommandLineArgument;
31 export type KxDatabaseConfiguration = finspace.KxDatabaseConfiguration;
32 export type KxCacheStorageConfiguration = finspace.KxCacheStorageConfiguration;
33 export type KxSavedownStorageConfiguration = finspace.KxSavedownStorageConfiguration;
34 export type KxScalingGroupConfiguration = finspace.KxScalingGroupConfiguration;
35 export type TickerplantLogConfiguration = finspace.TickerplantLogConfiguration;
36
37 /**
38 * Auto-scaling policy for a dedicated {@link KxCluster}.
39 */
40 export interface AutoScalingConfiguration {
41 /** Lowest number of nodes to scale in to. */
42 minNodeCount?: number;
43 /** Highest number of nodes to scale out to. */
44 maxNodeCount?: number;
45 /** The metric the auto-scaling policy tracks. */
46 autoScalingMetric?: finspace.AutoScalingMetric;
47 /** The desired value of the chosen metric. */
48 metricTarget?: number;
49 /**
50 * The cooldown after a scale-in event before another scaling event —
51 * e.g. `"5 minutes"`. Sent to AWS as whole seconds.
52 */
53 scaleInCooldown?: Duration.Input;
54 /**
55 * The cooldown after a scale-out event before another scaling event —
56 * e.g. `"5 minutes"`. Sent to AWS as whole seconds.
57 */
58 scaleOutCooldown?: Duration.Input;
59 }
60
61 /** Convert the alchemy-facing auto-scaling config to the wire shape (seconds). */
62 const toWireAutoScaling = (
63 config: AutoScalingConfiguration,
64 ): finspace.AutoScalingConfiguration => ({
65 minNodeCount: config.minNodeCount,
66 maxNodeCount: config.maxNodeCount,
67 autoScalingMetric: config.autoScalingMetric,
68 metricTarget: config.metricTarget,
69 scaleInCooldownSeconds: toWireSeconds(config.scaleInCooldown),
70 scaleOutCooldownSeconds: toWireSeconds(config.scaleOutCooldown),
71 });
72
73 export interface KxClusterProps {
74 /**
75 * Identifier of the kdb environment the cluster runs in. Changing it
76 * replaces the cluster.
77 */
78 environmentId: string;
79 /**
80 * Name of the kdb cluster. Changing it replaces the cluster.
81 * @default ${app}-${id}-${stage}-${suffix}
82 */
83 clusterName?: string;
84 /**
85 * The type of cluster — `HDB`, `RDB`, `GATEWAY`, `GP` or `TICKERPLANT`.
86 * Changing it replaces the cluster.
87 */
88 clusterType: KxClusterType;
89 /**
90 * The kdb release the cluster runs (e.g. `"1.0"`). Changing it replaces
91 * the cluster.
92 */
93 releaseLabel: string;
94 /**
95 * VPC the cluster network interfaces are placed in. Changing it replaces
96 * the cluster.
97 */
98 vpcConfiguration: VpcConfiguration;
99 /**
100 * Availability-zone placement mode — `SINGLE` or `MULTI`. Changing it
101 * replaces the cluster.
102 */
103 azMode: KxAzMode;
104 /**
105 * The availability zone id to place the cluster in (required when
106 * `azMode` is `SINGLE`). Changing it replaces the cluster.
107 */
108 availabilityZoneId?: string;
109 /**
110 * Dedicated node capacity for the cluster. Mutually exclusive with
111 * `scalingGroupConfiguration`. Changing it replaces the cluster.
112 */
113 capacityConfiguration?: CapacityConfiguration;
114 /**
115 * Placement on a shared scaling group instead of dedicated capacity.
116 * Changing it replaces the cluster.
117 */
118 scalingGroupConfiguration?: KxScalingGroupConfiguration;
119 /**
120 * Auto-scaling policy for a dedicated cluster. Changing it replaces the
121 * cluster.
122 */
123 autoScalingConfiguration?: AutoScalingConfiguration;
124 /**
125 * Temporary savedown storage for an `RDB` cluster. Changing it replaces
126 * the cluster.
127 */
128 savedownStorageConfiguration?: KxSavedownStorageConfiguration;
129 /**
130 * Databases to mount on the cluster, with optional cache configuration.
131 */
132 databases?: KxDatabaseConfiguration[];
133 /**
134 * Cache storage (e.g. `CACHE_1000`) sized for the mounted databases.
135 * Changing it replaces the cluster.
136 */
137 cacheStorageConfigurations?: KxCacheStorageConfiguration[];
138 /**
139 * Tickerplant log volumes for a `TICKERPLANT` cluster. Changing it
140 * replaces the cluster.
141 */
142 tickerplantLogConfiguration?: TickerplantLogConfiguration;
143 /**
144 * A description of the cluster.
145 */
146 description?: string;
147 /**
148 * The S3 location of the q code to deploy on the cluster.
149 */
150 code?: CodeConfiguration;
151 /**
152 * Path (relative to the code root) of the q script run at cluster start.
153 */
154 initializationScript?: string;
155 /**
156 * Command-line arguments passed to the kdb process.
157 */
158 commandLineArguments?: KxCommandLineArgument[];
159 /**
160 * ARN of the IAM execution role the cluster assumes to access AWS
161 * resources.
162 */
163 executionRole?: string;
164 /**
165 * Tags to associate with the cluster (applied at creation).
166 */
167 tags?: Record<string, string>;
168 }
169
170 export interface KxCluster extends Resource<
171 "AWS.FinSpace.KxCluster",
172 KxClusterProps,
173 {
174 /**
175 * Identifier of the kdb environment the cluster runs in.
176 */
177 environmentId: string;
178 /**
179 * The cluster's name.
180 */
181 clusterName: string;
182 /**
183 * Current lifecycle status of the cluster.
184 */
185 status: KxClusterStatus | undefined;
186 /**
187 * The cluster's type.
188 */
189 clusterType: KxClusterType | undefined;
190 /**
191 * The kdb release the cluster runs.
192 */
193 releaseLabel: string | undefined;
194 /**
195 * Availability-zone placement mode.
196 */
197 azMode: KxAzMode | undefined;
198 },
199 never,
200 Providers
201 > {}
202
203 /**
204 * A kdb cluster inside an Amazon FinSpace Managed kdb environment — the
205 * compute that mounts kdb databases and serves q queries.
206 *
207 * :::caution
208 * Cluster provisioning is slow (tens of minutes) and bills per node-hour
209 * while it exists. Live lifecycle tests are gated behind
210 * `AWS_TEST_FINSPACE=1`.
211 * :::
212 * ### Creating kdb Clusters
213 * **Example:** HDB Cluster on Dedicated Capacity
214 * ```typescript
215 * import * as AWS from "@alchemy.run/aws";
216 *
217 * const cluster = yield* AWS.FinSpace.KxCluster("Hdb", {
218 * environmentId: env.environmentId,
219 * clusterType: "HDB",
220 * releaseLabel: "1.0",
221 * azMode: "SINGLE",
222 * availabilityZoneId: "use1-az1",
223 * capacityConfiguration: { nodeType: "kx.s.large", nodeCount: 1 },
224 * vpcConfiguration: {
225 * vpcId: vpc.vpcId,
226 * securityGroupIds: [sg.securityGroupId],
227 * subnetIds: [subnet.subnetId],
228 * ipAddressType: "IP_V4",
229 * },
230 * databases: [{ databaseName: db.databaseName }],
231 * });
232 * ```
233 *
234 * @resource
235 */
236 export const KxCluster = Resource<KxCluster>("AWS.FinSpace.KxCluster");
237
238 const createClusterName = (id: string, props: { clusterName?: string | undefined }) =>
239 props.clusterName ? Effect.succeed(props.clusterName) : createPhysicalName({ id, maxLength: 63 });
240
241 const isGone = (status: KxClusterStatus | undefined) =>
242 status === "DELETED" || status === "DELETING";
243
244 const readCluster = Effect.fn(function* (environmentId: string, clusterName: string) {
245 const response = yield* finspace
246 .getKxCluster({ environmentId, clusterName })
247 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
248 if (!response || isGone(response.status)) return undefined;
249 return response;
250 });
251
252 const toAttributes = (
253 cluster: finspace.GetKxClusterResponse,
254 environmentId: string,
255 clusterName: string,
256 ): KxCluster["Attributes"] => ({
257 environmentId,
258 clusterName: cluster.clusterName ?? clusterName,
259 status: cluster.status,
260 clusterType: cluster.clusterType,
261 releaseLabel: cluster.releaseLabel,
262 azMode: cluster.azMode,
263 });
264
265 /**
266 * A cluster still transitioning toward the awaited status — retried by the
267 * bounded schedule in {@link waitForClusterStatus}.
268 */
269 class KxClusterNotReady extends Data.TaggedError("KxClusterNotReady")<{
270 readonly clusterName: string;
271 readonly status: string | undefined;
272 }> {}
273
274 /**
275 * A cluster whose asynchronous provisioning converged to a terminal failure
276 * status (`CREATE_FAILED` / `DELETE_FAILED`).
277 */
278 export class KxClusterProvisioningFailed extends Data.TaggedError("KxClusterProvisioningFailed")<{
279 readonly clusterName: string;
280 readonly status: string | undefined;
281 readonly statusReason: string | undefined;
282 }> {}
283
284 // Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
285 // lifecycle code leaks `Retry.Return`'s conditional type into declaration
286 // emit and widens the provider layer to `unknown` for every consumer of
287 // `AWS.providers()`.
288 const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
289 self: Effect.Effect<A, E, R>,
290 ): Effect.Effect<A, E, R> =>
291 Effect.retry(self, {
292 while: (e) => e._tag === "KxClusterNotReady",
293 // Cluster provisioning is slow (tens of minutes); poll every 20s up to
294 // ~40 min.
295 schedule: Schedule.max([Schedule.spaced("20 seconds"), Schedule.recurs(120)]),
296 });
297
298 const waitForClusterStatus = (
299 environmentId: string,
300 clusterName: string,
301 target: "RUNNING" | "DELETED",
302 ) =>
303 retryWhileNotReady(
304 Effect.gen(function* () {
305 const response = yield* finspace
306 .getKxCluster({ environmentId, clusterName })
307 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
308 const status = response?.status;
309 if (target === "DELETED") {
310 if (response === undefined || status === "DELETED") return;
311 if (status === "DELETE_FAILED") {
312 return yield* new KxClusterProvisioningFailed({
313 clusterName,
314 status,
315 statusReason: response.statusReason,
316 });
317 }
318 return yield* new KxClusterNotReady({ clusterName, status });
319 }
320 if (status === "RUNNING") return;
321 if (status === "CREATE_FAILED") {
322 return yield* new KxClusterProvisioningFailed({
323 clusterName,
324 status,
325 statusReason: response?.statusReason,
326 });
327 }
328 // response === undefined right after create is eventual consistency —
329 // keep polling on the bounded schedule.
330 return yield* new KxClusterNotReady({ clusterName, status });
331 }),
332 );
333
334 const sameJson = (a: unknown, b: unknown) =>
335 JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
336
337 export const KxClusterProvider = () =>
338 Provider.effect(
339 KxCluster,
340 Effect.gen(function* () {
341 return {
342 stables: ["environmentId", "clusterName"],
343 // Clusters are keyed by their parent kdb environment — there is no
344 // account-wide enumeration without an environment id.
345 list: () => Effect.succeed([]),
346 read: Effect.fn(function* ({ id, olds, output }) {
347 const environmentId = output?.environmentId ?? olds?.environmentId;
348 if (environmentId === undefined) return undefined;
349 const clusterName = output?.clusterName ?? (yield* createClusterName(id, olds ?? {}));
350 const cluster = yield* readCluster(environmentId, clusterName);
351 if (!cluster) return undefined;
352 // Clusters have no tag-read surface (no ARN in Get/List responses)
353 // — ownership cannot be verified, so a name match is owned.
354 return toAttributes(cluster, environmentId, clusterName);
355 }),
356 diff: Effect.fn(function* ({ id, news, olds }) {
357 if (!isResolved(news)) return;
358 if (olds === undefined) return;
359 const oldName = yield* createClusterName(id, olds);
360 const newName = yield* createClusterName(id, news);
361 // Everything except code/databases/description is fixed at
362 // creation.
363 if (
364 olds.environmentId !== news.environmentId ||
365 oldName !== newName ||
366 olds.clusterType !== news.clusterType ||
367 olds.releaseLabel !== news.releaseLabel ||
368 olds.azMode !== news.azMode ||
369 olds.availabilityZoneId !== news.availabilityZoneId ||
370 !sameJson(olds.vpcConfiguration, news.vpcConfiguration) ||
371 !sameJson(olds.capacityConfiguration, news.capacityConfiguration) ||
372 !sameJson(olds.scalingGroupConfiguration, news.scalingGroupConfiguration) ||
373 !sameJson(
374 olds.autoScalingConfiguration && toWireAutoScaling(olds.autoScalingConfiguration),
375 news.autoScalingConfiguration && toWireAutoScaling(news.autoScalingConfiguration),
376 ) ||
377 !sameJson(olds.savedownStorageConfiguration, news.savedownStorageConfiguration) ||
378 !sameJson(olds.cacheStorageConfigurations, news.cacheStorageConfigurations) ||
379 !sameJson(olds.tickerplantLogConfiguration, news.tickerplantLogConfiguration) ||
380 olds.executionRole !== news.executionRole
381 ) {
382 return { action: "replace" } as const;
383 }
384 }),
385 reconcile: Effect.fn(function* ({ id, news, output, session }) {
386 if (!news) {
387 return yield* new KxClusterInvalidProps({
388 message: "FinSpace KxCluster requires props",
389 });
390 }
391 const environmentId = news.environmentId;
392 const clusterName = output?.clusterName ?? (yield* createClusterName(id, news));
393 const internalTags = yield* createInternalTags(id);
394 // One idempotency token per reconcile.
395 const clientToken = yield* Effect.sync(() => crypto.randomUUID());
396
397 // Observe — cloud state is authoritative.
398 let cluster = yield* readCluster(environmentId, clusterName);
399
400 // Ensure — create if missing (tolerating a Conflict race), then
401 // wait for RUNNING.
402 if (cluster === undefined) {
403 yield* finspace
404 .createKxCluster({
405 clientToken,
406 environmentId,
407 clusterName,
408 clusterType: news.clusterType,
409 releaseLabel: news.releaseLabel,
410 vpcConfiguration: news.vpcConfiguration,
411 azMode: news.azMode,
412 availabilityZoneId: news.availabilityZoneId,
413 capacityConfiguration: news.capacityConfiguration,
414 scalingGroupConfiguration: news.scalingGroupConfiguration,
415 autoScalingConfiguration:
416 news.autoScalingConfiguration && toWireAutoScaling(news.autoScalingConfiguration),
417 savedownStorageConfiguration: news.savedownStorageConfiguration,
418 databases: news.databases,
419 cacheStorageConfigurations: news.cacheStorageConfigurations,
420 tickerplantLogConfiguration: news.tickerplantLogConfiguration,
421 clusterDescription: news.description,
422 code: news.code,
423 initializationScript: news.initializationScript,
424 commandLineArguments: news.commandLineArguments,
425 executionRole: news.executionRole,
426 tags: { ...internalTags, ...news.tags },
427 })
428 .pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
429 yield* session.note(`Creating kdb cluster ${clusterName}...`);
430 yield* waitForClusterStatus(environmentId, clusterName, "RUNNING");
431 cluster = yield* readCluster(environmentId, clusterName);
432 if (cluster === undefined) {
433 return yield* new KxClusterUnexpectedResponse({
434 message: `failed to read created kdb cluster ${clusterName}`,
435 });
436 }
437 }
438
439 // Sync code configuration — only when the caller manages code and
440 // the observed deployment drifted.
441 if (
442 news.code !== undefined &&
443 (!sameJson(news.code, cluster.code) ||
444 (news.initializationScript ?? "") !== (cluster.initializationScript ?? "") ||
445 !sameJson(news.commandLineArguments, cluster.commandLineArguments))
446 ) {
447 yield* finspace.updateKxClusterCodeConfiguration({
448 environmentId,
449 clusterName,
450 clientToken,
451 code: news.code,
452 initializationScript: news.initializationScript,
453 commandLineArguments: news.commandLineArguments,
454 });
455 yield* session.note(`Updated code on kdb cluster ${clusterName}`);
456 yield* waitForClusterStatus(environmentId, clusterName, "RUNNING");
457 }
458
459 // Sync mounted databases — only when the caller manages them and
460 // the observed set drifted.
461 if (news.databases !== undefined && !sameJson(news.databases, cluster.databases)) {
462 yield* finspace.updateKxClusterDatabases({
463 environmentId,
464 clusterName,
465 clientToken,
466 databases: news.databases,
467 });
468 yield* session.note(`Updated databases on kdb cluster ${clusterName}`);
469 yield* waitForClusterStatus(environmentId, clusterName, "RUNNING");
470 }
471
472 yield* session.note(clusterName);
473
474 const final = yield* readCluster(environmentId, clusterName);
475 if (!final) {
476 return yield* new KxClusterUnexpectedResponse({
477 message: `failed to read reconciled kdb cluster ${clusterName}`,
478 });
479 }
480 return toAttributes(final, environmentId, clusterName);
481 }),
482 delete: Effect.fn(function* ({ output }) {
483 yield* finspace
484 .deleteKxCluster({
485 environmentId: output.environmentId,
486 clusterName: output.clusterName,
487 })
488 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
489 yield* waitForClusterStatus(output.environmentId, output.clusterName, "DELETED");
490 }),
491 };
492 }),
493 );