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

main
ts 440 lines 14.1 KB
Raw
1 import * as kafka from "@distilled.cloud/gcp/managedkafka_v1";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import { tagRecord } from "alchemy/Tags";
7 import * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import { GcpEnvironment } from "../Environment.ts";
10 import { createInternalLabels, diffLabels, hasAlchemyLabels, toLabels } from "../Labels.ts";
11 import type { Providers } from "../Providers.ts";
12 import {
13 asCountString,
14 DEFAULT_MEMORY_BYTES,
15 DEFAULT_VCPU_COUNT,
16 defaultSubnet,
17 fieldMask,
18 fingerprint,
19 getCluster,
20 listAlchemyClusters,
21 locationParent,
22 MAX_CLUSTER_ID_LENGTH,
23 normalizeLocation,
24 parseName,
25 replaceOnIdentity,
26 retryCreateQuota,
27 ResourceNotResolved,
28 rfc1035,
29 toPhysicalId,
30 userLabels,
31 waitForOperation,
32 waitUntilExists,
33 waitUntilGone,
34 waitUntilReady,
35 } from "./internal.ts";
36
37 export type NetworkConfig = {
38 /** VPC subnet `projects/{project}/regions/{region}/subnetworks/{subnet}`. */
39 subnet?: string;
40 };
41
42 export type AccessConfig = {
43 /** VPC networks granted access. At least one subnet is required. */
44 networkConfigs?: NetworkConfig[];
45 };
46
47 export type GcpConfig = {
48 /** Access configuration for the Kafka cluster. */
49 accessConfig?: AccessConfig;
50 /**
51 * Cloud KMS key for encryption. Immutable.
52 * `projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{key}`.
53 */
54 kmsKey?: string;
55 };
56
57 export type CapacityConfig = {
58 /**
59 * vCPUs to provision. Minimum 3.
60 * @default 3
61 */
62 vcpuCount?: number | string;
63 /**
64 * Memory in bytes. Minimum 3221225472 (3 GiB). CPU:memory GiB ratio
65 * must be between 1:1 and 1:8.
66 * @default 3221225472
67 */
68 memoryBytes?: number | string;
69 };
70
71 export type RebalanceConfig = {
72 /**
73 * Rebalance mode (`NO_REBALANCE`, `AUTO_REBALANCE_ON_SCALE_UP`).
74 * @default "NO_REBALANCE"
75 */
76 mode?: kafka.RebalanceConfigModeEnum | (string & {});
77 };
78
79 export type TrustConfig = {
80 /** Certificate Authority Service CA pools. Maximum 10. */
81 casConfigs?: Array<{ caPool?: string }>;
82 };
83
84 export type TlsConfig = {
85 /** Kafka `ssl.principal.mapping.rules`. Empty string clears rules. */
86 sslPrincipalMappingRules?: string;
87 /** Broker truststore. Enables mTLS when set. */
88 trustConfig?: TrustConfig;
89 };
90
91 export type UpdateOptions = {
92 /**
93 * Allow an upscale that shrinks per-broker size below 90% of current.
94 * @default false
95 */
96 allowBrokerDownscaleOnClusterUpscale?: boolean;
97 };
98
99 export type ClusterProps = {
100 /**
101 * Cluster id (the `{cluster}` segment of
102 * `projects/{project}/locations/{location}/clusters/{cluster}`).
103 * Lowercase letters, digits, and hyphens; max 53 characters (longer
104 * values are truncated). If omitted, a unique RFC1035 name of at most
105 * 53 characters is generated. Immutable — changing it replaces the
106 * cluster.
107 */
108 clusterId?: string;
109 /**
110 * Region (`us-central1`, …). Immutable. `US-CENTRAL1` is accepted and
111 * normalized to `us-central1`.
112 * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
113 */
114 location?: string;
115 /**
116 * Subnets for broker PSC endpoints. Each is
117 * `projects/{project}/regions/{region}/subnetworks/{subnet}`. Defaults
118 * to the project's `default` subnet in `location`. Immutable — changing
119 * them replaces the cluster.
120 */
121 subnets?: string[];
122 /**
123 * Full GCP config. `subnets` / `kmsKey` win when both are set.
124 */
125 gcpConfig?: GcpConfig;
126 /**
127 * Customer-managed KMS key. Immutable.
128 */
129 kmsKey?: string;
130 /**
131 * Capacity. Defaults to 3 vCPU / 3 GiB.
132 */
133 capacityConfig?: CapacityConfig;
134 /**
135 * Rebalance behavior.
136 */
137 rebalanceConfig?: RebalanceConfig;
138 /**
139 * TLS / mTLS configuration.
140 */
141 tlsConfig?: TlsConfig;
142 /**
143 * Options that control how updates are applied.
144 */
145 updateOptions?: UpdateOptions;
146 /**
147 * User labels. Alchemy ownership labels are merged in automatically.
148 */
149 labels?: Record<string, string>;
150 };
151
152 export type Cluster = Resource<
153 "GCP.ManagedKafka.Cluster",
154 ClusterProps,
155 {
156 /** Full resource name `projects/{project}/locations/{location}/clusters/{cluster}`. */
157 name: string;
158 /** Cluster id (last path segment). */
159 clusterId: string;
160 /** Project id. */
161 project: string;
162 /** Location id. */
163 location: string;
164 /** User labels (Alchemy ownership labels stripped). */
165 labels: Record<string, string>;
166 /** Server-reported state (`CREATING`, `ACTIVE`, …). */
167 state: string | undefined;
168 /** vCPU count currently provisioned. */
169 vcpuCount: string | undefined;
170 /** Memory in bytes currently provisioned. */
171 memoryBytes: string | undefined;
172 /** Subnets currently attached. */
173 subnets: string[];
174 /** CMEK key, if any. */
175 kmsKey: string | undefined;
176 /** Rebalance mode. */
177 rebalanceMode: string | undefined;
178 /** Kafka software version. */
179 kafkaVersion: string | undefined;
180 /** Broker details when requested with FULL view. */
181 brokerDetails: kafka.BrokerDetails[];
182 /** RFC3339 creation timestamp. */
183 createTime: string | undefined;
184 /** RFC3339 last-update timestamp. */
185 updateTime: string | undefined;
186 },
187 never,
188 Providers
189 >;
190
191 /**
192 * A Managed Service for Apache Kafka cluster.
193 *
194 * Changing `clusterId`, `location`, `subnets`, or `kmsKey` replaces the
195 * cluster. Capacity, rebalance mode, TLS config, and labels update in
196 * place. Provisioning typically takes more than a minute.
197 *
198 * ### Creating a Cluster
199 * **Example:** Generated name, 3 vCPU / 3 GiB
200 * ```typescript
201 * const cluster = yield* GCP.ManagedKafka.Cluster("Brokers", {});
202 * ```
203 *
204 * **Example:** Explicit id, subnet, and labels
205 * ```typescript
206 * const cluster = yield* GCP.ManagedKafka.Cluster("Brokers", {
207 * clusterId: "app-kafka",
208 * location: "us-central1",
209 * subnets: [
210 * "projects/my-project/regions/us-central1/subnetworks/default",
211 * ],
212 * capacityConfig: { vcpuCount: 3, memoryBytes: 3221225472 },
213 * labels: { env: "prod" },
214 * });
215 * ```
216 *
217 * @resource
218 * @category ManagedKafka
219 */
220 export const Cluster = Resource<Cluster>("GCP.ManagedKafka.Cluster");
221
222 export class ClusterNotResolved extends Data.TaggedError("GCP.ManagedKafka.ClusterNotResolved")<{
223 resourceName: string;
224 }> {}
225
226 const resourceName = (project: string, location: string, clusterId: string) =>
227 `projects/${project}/locations/${location}/clusters/${clusterId}`;
228
229 const subnetsOf = (
230 cluster: kafka.Cluster | ClusterProps,
231 project: string,
232 location: string,
233 ): string[] => {
234 const fromConfig = (cluster.gcpConfig?.accessConfig?.networkConfigs ?? [])
235 .map((config) => config.subnet)
236 .filter((subnet): subnet is string => subnet !== undefined);
237 if ("subnets" in cluster && cluster.subnets && cluster.subnets.length > 0) {
238 return cluster.subnets;
239 }
240 if (fromConfig.length > 0) return fromConfig;
241 return [defaultSubnet(project, location)];
242 };
243
244 const kmsOf = (cluster: kafka.Cluster | ClusterProps) =>
245 ("kmsKey" in cluster ? cluster.kmsKey : undefined) ?? cluster.gcpConfig?.kmsKey;
246
247 const toAttrs = (cluster: kafka.Cluster, project: string) => {
248 const name = cluster.name ?? "";
249 const parsed = parseName(name, "clusters");
250 return {
251 name,
252 clusterId: parsed.id,
253 project: parsed.project || project,
254 location: parsed.location,
255 labels: userLabels(cluster.labels),
256 state: cluster.state,
257 vcpuCount: cluster.capacityConfig?.vcpuCount,
258 memoryBytes: cluster.capacityConfig?.memoryBytes,
259 subnets: subnetsOf(cluster, parsed.project || project, parsed.location),
260 kmsKey: cluster.gcpConfig?.kmsKey,
261 rebalanceMode: cluster.rebalanceConfig?.mode,
262 kafkaVersion: cluster.kafkaVersion,
263 brokerDetails: cluster.brokerDetails ?? [],
264 createTime: cluster.createTime,
265 updateTime: cluster.updateTime,
266 };
267 };
268
269 const desiredCapacity = (news: ClusterProps): kafka.CapacityConfig => ({
270 vcpuCount: asCountString(news.capacityConfig?.vcpuCount, DEFAULT_VCPU_COUNT),
271 memoryBytes: asCountString(news.capacityConfig?.memoryBytes, DEFAULT_MEMORY_BYTES),
272 });
273
274 const desiredGcpConfig = (
275 news: ClusterProps,
276 project: string,
277 location: string,
278 ): kafka.GcpConfig => ({
279 accessConfig: {
280 networkConfigs: subnetsOf(news, project, location).map((subnet) => ({
281 subnet,
282 })),
283 },
284 kmsKey: kmsOf(news),
285 });
286
287 export const ClusterProvider = () =>
288 Provider.succeed(Cluster, {
289 stables: ["name", "clusterId", "project", "location", "createTime"],
290
291 diff: Effect.fn(function* ({ news, olds, output }) {
292 if (!isResolved(news)) return undefined;
293 const env = yield* GcpEnvironment.current;
294 const location = normalizeLocation(news.location ?? output?.location, env.region);
295 const previousSubnets = fingerprint([...(olds?.subnets ?? output?.subnets ?? [])].sort());
296 const nextSubnets = fingerprint([...subnetsOf(news, env.project, location)].sort());
297 return replaceOnIdentity({
298 previousId: olds?.clusterId ?? output?.clusterId,
299 nextId: news.clusterId
300 ? rfc1035(news.clusterId, "kafka", MAX_CLUSTER_ID_LENGTH)
301 : (olds?.clusterId ?? output?.clusterId),
302 previousLocation: normalizeLocation(olds?.location ?? output?.location, env.region),
303 nextLocation: location,
304 extra:
305 previousSubnets !== nextSubnets ||
306 (kmsOf(news) ?? "") !== (olds?.kmsKey ?? output?.kmsKey ?? ""),
307 });
308 }),
309
310 read: Effect.fn(function* ({ id, olds, output }) {
311 const env = yield* GcpEnvironment.current;
312 const clusterId = yield* toPhysicalId(
313 id,
314 olds?.clusterId,
315 output?.clusterId,
316 "kafka",
317 MAX_CLUSTER_ID_LENGTH,
318 );
319 const location = normalizeLocation(olds?.location ?? output?.location, env.region);
320 const name = output?.name ?? resourceName(env.project, location, clusterId);
321 const existing = yield* getCluster(name);
322 if (existing === undefined) return undefined;
323 const attrs = toAttrs(existing, env.project);
324 return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
325 }),
326
327 list: () =>
328 Effect.gen(function* () {
329 const env = yield* GcpEnvironment.current;
330 const clusters = yield* listAlchemyClusters(env.project, env.region);
331 return clusters.map((cluster) => toAttrs(cluster, env.project));
332 }),
333
334 reconcile: Effect.fn(function* ({ id, news, output }) {
335 const env = yield* GcpEnvironment.current;
336 const clusterId = yield* toPhysicalId(
337 id,
338 news.clusterId,
339 output?.clusterId,
340 "kafka",
341 MAX_CLUSTER_ID_LENGTH,
342 );
343 const location = normalizeLocation(news.location ?? output?.location, env.region);
344 const name = output?.name ?? resourceName(env.project, location, clusterId);
345 const desiredLabels = {
346 ...toLabels(news.labels),
347 ...(yield* createInternalLabels(id)),
348 };
349 const capacity = desiredCapacity(news);
350 const gcpConfig = desiredGcpConfig(news, env.project, location);
351 const rebalanceConfig = news.rebalanceConfig;
352
353 let current = yield* getCluster(name);
354
355 if (current === undefined) {
356 const created = yield* kafka
357 .createProjectsLocationsClusters({
358 parent: locationParent(env.project, location),
359 clusterId,
360 body: {
361 gcpConfig,
362 capacityConfig: capacity,
363 rebalanceConfig,
364 tlsConfig: news.tlsConfig,
365 updateOptions: news.updateOptions,
366 labels: desiredLabels,
367 },
368 })
369 .pipe(
370 retryCreateQuota,
371 Effect.catchTag("Conflict", () => Effect.undefined),
372 );
373 if (created !== undefined) {
374 yield* waitForOperation(created);
375 }
376 current = yield* waitUntilExists(getCluster(name), name);
377 }
378
379 if (current === undefined) {
380 return yield* new ClusterNotResolved({ resourceName: name });
381 }
382
383 current = yield* waitUntilReady(getCluster(name), name, (cluster) => cluster.state);
384
385 const observedLabels = tagRecord(current.labels);
386 const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
387 const labelsChanged = upsert.length > 0 || removed.length > 0;
388 const capacityChanged =
389 (current.capacityConfig?.vcpuCount ?? "") !== (capacity.vcpuCount ?? "") ||
390 (current.capacityConfig?.memoryBytes ?? "") !== (capacity.memoryBytes ?? "");
391 const rebalanceChanged =
392 (current.rebalanceConfig?.mode ?? "") !== (rebalanceConfig?.mode ?? "");
393 const tlsChanged = fingerprint(current.tlsConfig) !== fingerprint(news.tlsConfig);
394 const updateOptionsChanged =
395 fingerprint(current.updateOptions) !== fingerprint(news.updateOptions);
396
397 if (
398 labelsChanged ||
399 capacityChanged ||
400 rebalanceChanged ||
401 tlsChanged ||
402 updateOptionsChanged
403 ) {
404 const op = yield* kafka.patchProjectsLocationsClusters({
405 name,
406 updateMask: fieldMask([
407 labelsChanged && "labels",
408 capacityChanged && "capacity_config",
409 rebalanceChanged && "rebalance_config",
410 tlsChanged && "tls_config",
411 updateOptionsChanged && "update_options",
412 ]),
413 body: {
414 labels: desiredLabels,
415 capacityConfig: capacity,
416 rebalanceConfig,
417 tlsConfig: news.tlsConfig,
418 updateOptions: news.updateOptions,
419 },
420 });
421 yield* waitForOperation(op);
422 current = yield* waitUntilReady(getCluster(name), name, (cluster) => cluster.state);
423 }
424
425 if (current === undefined) {
426 return yield* new ResourceNotResolved({ resourceName: name });
427 }
428 return toAttrs(current, env.project);
429 }),
430
431 delete: Effect.fn(function* ({ output }) {
432 const op = yield* kafka
433 .deleteProjectsLocationsClusters({ name: output.name })
434 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
435 if (op !== undefined) {
436 yield* waitForOperation(op, { notFoundOk: true });
437 }
438 yield* waitUntilGone(getCluster(output.name), output.name);
439 }),
440 });