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

main
ts 141 lines 5.49 KB
Raw
1 import * as Binding from "alchemy/Binding";
2 import type { RuntimeContext } from "alchemy/RuntimeContext";
3 import type * as Effect from "effect/Effect";
4 import { connectEnvPrefix as makeConnectEnvPrefix } from "../Connection/internal.ts";
5 import type { ServerlessCluster } from "./ServerlessCluster.ts";
6
7 /**
8 * Connection descriptor for an MSK {@link ServerlessCluster}. Alchemy does
9 * not bundle a Kafka client — pass these settings to the Kafka client of
10 * your choice (`kafkajs` + `aws-msk-iam-sasl-signer-js`, `@confluentinc/kafka-javascript`, ...),
11 * which speaks the Kafka wire protocol against the cluster's SASL/IAM
12 * bootstrap endpoint.
13 */
14 export interface ClusterConnectionInfo {
15 /**
16 * Comma-separated SASL/IAM bootstrap broker string
17 * (`boot-….kafka-serverless.….amazonaws.com:9098`).
18 */
19 bootstrapServers: string;
20 /** Bootstrap brokers as individual `host:port` entries (kafkajs `brokers`). */
21 brokers: string[];
22 /** ARN of the cluster (MSK IAM SASL signers take the cluster's region). */
23 clusterArn: string;
24 /**
25 * SASL mechanism the endpoint requires — always IAM (`AWS_MSK_IAM` over
26 * TLS) for MSK Serverless.
27 */
28 authentication: "iam";
29 }
30
31 /**
32 * Environment variable prefix under which the connect bindings publish the
33 * cluster endpoint on the host Function, derived from the cluster's logical
34 * ID. A cluster with logical ID `Events` yields `MSK_EVENTS` and the
35 * variables `MSK_EVENTS_BROKERS` and `MSK_EVENTS_ARN`.
36 */
37 export const connectEnvPrefix = (logicalId: string): string =>
38 makeConnectEnvPrefix("MSK", logicalId);
39
40 /**
41 * Read-only (consumer) runtime access to an MSK {@link ServerlessCluster}'s
42 * data plane.
43 *
44 * Grants the MSK IAM-auth actions a Kafka consumer needs
45 * (`kafka-cluster:Connect` on the cluster, `kafka-cluster:ReadData` +
46 * `kafka-cluster:DescribeTopic` on the cluster's topics, and
47 * `kafka-cluster:DescribeGroup` + `kafka-cluster:AlterGroup` on its consumer
48 * groups), publishes the SASL/IAM bootstrap endpoint as environment
49 * variables on the host Function, and resolves a typed
50 * {@link ClusterConnectionInfo} at runtime.
51 *
52 * The Kafka data plane is VPC-only — the host Function must be attached to
53 * the cluster's VPC and allowed ingress on port 9098 by the cluster's
54 * security groups. Provide the implementation with
55 * `Effect.provide(AWS.Kafka.ConnectReadHttp)`.
56 * ### Connecting to a Cluster
57 * **Example:** Resolve Consumer Connection Info inside a Function
58 * ```typescript
59 * const connect = yield* Kafka.ConnectRead(cluster);
60 * // inside a handler:
61 * const { brokers, authentication } = yield* connect;
62 * ```
63 *
64 * @binding
65 */
66 export interface ConnectRead extends Binding.Service<
67 ConnectRead,
68 "AWS.Kafka.ConnectRead",
69 (
70 cluster: ServerlessCluster,
71 ) => Effect.Effect<Effect.Effect<ClusterConnectionInfo, never, RuntimeContext>>
72 > {}
73 export const ConnectRead = Binding.Service<ConnectRead>("AWS.Kafka.ConnectRead");
74
75 /**
76 * Write-only (producer) runtime access to an MSK {@link ServerlessCluster}'s
77 * data plane.
78 *
79 * Grants the MSK IAM-auth actions a Kafka producer needs
80 * (`kafka-cluster:Connect` + `kafka-cluster:WriteDataIdempotently` on the
81 * cluster, `kafka-cluster:WriteData` + `kafka-cluster:DescribeTopic` on the
82 * cluster's topics, and the transactional-id actions for transactional
83 * producers), publishes the SASL/IAM bootstrap endpoint as environment
84 * variables on the host Function, and resolves a typed
85 * {@link ClusterConnectionInfo} at runtime.
86 *
87 * The Kafka data plane is VPC-only — the host Function must be attached to
88 * the cluster's VPC and allowed ingress on port 9098 by the cluster's
89 * security groups. Provide the implementation with
90 * `Effect.provide(AWS.Kafka.ConnectWriteHttp)`.
91 * ### Connecting to a Cluster
92 * **Example:** Resolve Producer Connection Info inside a Function
93 * ```typescript
94 * const connect = yield* Kafka.ConnectWrite(cluster);
95 * // inside a handler:
96 * const { bootstrapServers } = yield* connect;
97 * ```
98 *
99 * @binding
100 */
101 export interface ConnectWrite extends Binding.Service<
102 ConnectWrite,
103 "AWS.Kafka.ConnectWrite",
104 (
105 cluster: ServerlessCluster,
106 ) => Effect.Effect<Effect.Effect<ClusterConnectionInfo, never, RuntimeContext>>
107 > {}
108 export const ConnectWrite = Binding.Service<ConnectWrite>("AWS.Kafka.ConnectWrite");
109
110 /**
111 * Full read-write runtime access to an MSK {@link ServerlessCluster}'s data
112 * plane.
113 *
114 * Grants both the consumer- and producer-side MSK IAM-auth actions on the
115 * cluster, its topics, its consumer groups, and its transactional ids,
116 * publishes the SASL/IAM bootstrap endpoint as environment variables on the
117 * host Function, and resolves a typed {@link ClusterConnectionInfo} at
118 * runtime.
119 *
120 * The Kafka data plane is VPC-only — the host Function must be attached to
121 * the cluster's VPC and allowed ingress on port 9098 by the cluster's
122 * security groups. Provide the implementation with
123 * `Effect.provide(AWS.Kafka.ConnectReadWriteHttp)`.
124 * ### Connecting to a Cluster
125 * **Example:** Resolve Connection Info inside a Function
126 * ```typescript
127 * const connect = yield* Kafka.ConnectReadWrite(cluster);
128 * // inside a handler:
129 * const { bootstrapServers, brokers, clusterArn } = yield* connect;
130 * ```
131 *
132 * @binding
133 */
134 export interface ConnectReadWrite extends Binding.Service<
135 ConnectReadWrite,
136 "AWS.Kafka.ConnectReadWrite",
137 (
138 cluster: ServerlessCluster,
139 ) => Effect.Effect<Effect.Effect<ClusterConnectionInfo, never, RuntimeContext>>
140 > {}
141 export const ConnectReadWrite = Binding.Service<ConnectReadWrite>("AWS.Kafka.ConnectReadWrite");