sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Kafka/ Connect.ts

import * as Binding from "alchemy/Binding";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import type * as Effect from "effect/Effect";
import { connectEnvPrefix as makeConnectEnvPrefix } from "../Connection/internal.ts";
import type { ServerlessCluster } from "./ServerlessCluster.ts";

/**
 * Connection descriptor for an MSK {@link ServerlessCluster}. Alchemy does
 * not bundle a Kafka client — pass these settings to the Kafka client of
 * your choice (`kafkajs` + `aws-msk-iam-sasl-signer-js`, `@confluentinc/kafka-javascript`, ...),
 * which speaks the Kafka wire protocol against the cluster's SASL/IAM
 * bootstrap endpoint.
 */
export interface ClusterConnectionInfo {
  /**
   * Comma-separated SASL/IAM bootstrap broker string
   * (`boot-….kafka-serverless.….amazonaws.com:9098`).
   */
  bootstrapServers: string;
  /** Bootstrap brokers as individual `host:port` entries (kafkajs `brokers`). */
  brokers: string[];
  /** ARN of the cluster (MSK IAM SASL signers take the cluster's region). */
  clusterArn: string;
  /**
   * SASL mechanism the endpoint requires — always IAM (`AWS_MSK_IAM` over
   * TLS) for MSK Serverless.
   */
  authentication: "iam";
}

/**
 * Environment variable prefix under which the connect bindings publish the
 * cluster endpoint on the host Function, derived from the cluster's logical
 * ID. A cluster with logical ID `Events` yields `MSK_EVENTS` and the
 * variables `MSK_EVENTS_BROKERS` and `MSK_EVENTS_ARN`.
 */
export const connectEnvPrefix = (logicalId: string): string =>
  makeConnectEnvPrefix("MSK", logicalId);

/**
 * Read-only (consumer) runtime access to an MSK {@link ServerlessCluster}'s
 * data plane.
 *
 * Grants the MSK IAM-auth actions a Kafka consumer needs
 * (`kafka-cluster:Connect` on the cluster, `kafka-cluster:ReadData` +
 * `kafka-cluster:DescribeTopic` on the cluster's topics, and
 * `kafka-cluster:DescribeGroup` + `kafka-cluster:AlterGroup` on its consumer
 * groups), publishes the SASL/IAM bootstrap endpoint as environment
 * variables on the host Function, and resolves a typed
 * {@link ClusterConnectionInfo} at runtime.
 *
 * The Kafka data plane is VPC-only — the host Function must be attached to
 * the cluster's VPC and allowed ingress on port 9098 by the cluster's
 * security groups. Provide the implementation with
 * `Effect.provide(AWS.Kafka.ConnectReadHttp)`.
 * ### Connecting to a Cluster
 * **Example:** Resolve Consumer Connection Info inside a Function
 * ```typescript
 * const connect = yield* Kafka.ConnectRead(cluster);
 * // inside a handler:
 * const { brokers, authentication } = yield* connect;
 * ```
 *
 * @binding
 */
export interface ConnectRead extends Binding.Service<
  ConnectRead,
  "AWS.Kafka.ConnectRead",
  (
    cluster: ServerlessCluster,
  ) => Effect.Effect<Effect.Effect<ClusterConnectionInfo, never, RuntimeContext>>
> {}
export const ConnectRead = Binding.Service<ConnectRead>("AWS.Kafka.ConnectRead");

/**
 * Write-only (producer) runtime access to an MSK {@link ServerlessCluster}'s
 * data plane.
 *
 * Grants the MSK IAM-auth actions a Kafka producer needs
 * (`kafka-cluster:Connect` + `kafka-cluster:WriteDataIdempotently` on the
 * cluster, `kafka-cluster:WriteData` + `kafka-cluster:DescribeTopic` on the
 * cluster's topics, and the transactional-id actions for transactional
 * producers), publishes the SASL/IAM bootstrap endpoint as environment
 * variables on the host Function, and resolves a typed
 * {@link ClusterConnectionInfo} at runtime.
 *
 * The Kafka data plane is VPC-only — the host Function must be attached to
 * the cluster's VPC and allowed ingress on port 9098 by the cluster's
 * security groups. Provide the implementation with
 * `Effect.provide(AWS.Kafka.ConnectWriteHttp)`.
 * ### Connecting to a Cluster
 * **Example:** Resolve Producer Connection Info inside a Function
 * ```typescript
 * const connect = yield* Kafka.ConnectWrite(cluster);
 * // inside a handler:
 * const { bootstrapServers } = yield* connect;
 * ```
 *
 * @binding
 */
export interface ConnectWrite extends Binding.Service<
  ConnectWrite,
  "AWS.Kafka.ConnectWrite",
  (
    cluster: ServerlessCluster,
  ) => Effect.Effect<Effect.Effect<ClusterConnectionInfo, never, RuntimeContext>>
> {}
export const ConnectWrite = Binding.Service<ConnectWrite>("AWS.Kafka.ConnectWrite");

/**
 * Full read-write runtime access to an MSK {@link ServerlessCluster}'s data
 * plane.
 *
 * Grants both the consumer- and producer-side MSK IAM-auth actions on the
 * cluster, its topics, its consumer groups, and its transactional ids,
 * publishes the SASL/IAM bootstrap endpoint as environment variables on the
 * host Function, and resolves a typed {@link ClusterConnectionInfo} at
 * runtime.
 *
 * The Kafka data plane is VPC-only — the host Function must be attached to
 * the cluster's VPC and allowed ingress on port 9098 by the cluster's
 * security groups. Provide the implementation with
 * `Effect.provide(AWS.Kafka.ConnectReadWriteHttp)`.
 * ### Connecting to a Cluster
 * **Example:** Resolve Connection Info inside a Function
 * ```typescript
 * const connect = yield* Kafka.ConnectReadWrite(cluster);
 * // inside a handler:
 * const { bootstrapServers, brokers, clusterArn } = yield* connect;
 * ```
 *
 * @binding
 */
export interface ConnectReadWrite extends Binding.Service<
  ConnectReadWrite,
  "AWS.Kafka.ConnectReadWrite",
  (
    cluster: ServerlessCluster,
  ) => Effect.Effect<Effect.Effect<ClusterConnectionInfo, never, RuntimeContext>>
> {}
export const ConnectReadWrite = Binding.Service<ConnectReadWrite>("AWS.Kafka.ConnectReadWrite");