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
| 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 | ); |