kafka

Apache Kafka (TypeScript)

TypeScript／Node から Kafka の生成・消費・管理を行う場合に、このスキルを使用します。@platformatic/kafka を優先し、ブローカーのセマンティクス、トピック設計、配信保証、およびアプリケーションコードを変更する運用作業も扱います。

ワークフロー

1. ローカルの状況を確認します。
   • パッケージ：@platformatic/kafka（スナップショット 2.13.0）。エンジン：Node >=22.22 または >=24.6。Kafka ブローカー 3.5–4.2 で CI テスト済み（上流の Apache Kafka は 4.3.x で、4.0+ は KRaft のみです）。
   • クライアント：bootstrapBrokers を使用する Producer／Consumer／Admin（KafkaJS の brokers ではありません）。
   • トピック：パーティション、キー、RF／min.insync.replicas、クリーンアップポリシー。
   • セマンティクス：at-least-once と EOS、自動コミットと手動コミット、ProduceAcks。
2. 日常的な使用方法については、まず usage-guide.md に従います。
3. バージョンにずれがある場合はドキュメントを更新します。source-map.md から始めてください。
4. 詳細については、以下を参照します。
   • 概念（パーティション、グループ、保持、EOS）：fundamentals.md。
   • @platformatic/kafka API、シリアライザー、ストリーム、トランザクション、SASL：platformatic-kafka.md。
   • 設計、DLQ、アウトボックス、モニタリング：patterns-ops.md。
   • クライアントの選択肢とブローカー：clients-ecosystem.md。
5. kafkajs（メンテナンスされていません）や、librdkafka が必要な場合を除くネイティブの node-rdkafka よりも、@platformatic/kafka を優先します。Platformatic で KafkaJS の connect／subscribe／run API を使えるかのように説明しないでください。
6. 絞り込んだ生成・消費のスモークテスト、必要に応じた Admin によるトピック作成、ラグの把握を行い、シャットダウン時に close() を呼び出して検証します。

基本的な判断基準

• Kafka は追記専用のパーティション分割ログです。順序が保証されるのはパーティションごとであり、グループの並列度の上限はパーティション数です。
• アプリケーションのデフォルトのセマンティクスは、at-least-once と冪等なハンドラーです。Kafka 間の EOS が必要な場合にのみ、トランザクション／READ_COMMITTED を使用します。
• 耐久性の三要素：RF=3、min.insync.replicas=2、プロデューサーの ProduceAcks.ALL（利用可能な場合は冪等プロデューサーも使用）。
• キー：順序とパーティション分割のために、安定したエンティティ ID を使用します。コンパクションには、キーとトゥームストーン（null 値）が必要です。
• デュアルライト（1 つのリクエストで DB と Kafka の両方に書き込む）よりも、アウトボックス／CDC を優先します。
• 不正なメッセージ：リトライ／DLQ の後にコミットします。パーティションを永久にブロックしないでください。
• Platformatic：クライアントは長期間使用し、接続は遅延させ、close() を呼び出します。consume() → ストリーム（for await／data／並行 forEach）で消費します。オフセットは bigint であり、消費時のヘッダーは Map です。
• serializers／deserializers（例：stringSerializers）を渡します。デフォルトでは Buffer が想定されています。
• 従来型のグループでは、デフォルトで全処理を停止してリバランスします。KIP-429 cooperative-sticky（protocols: [{ name: COOPERATIVE_STICKY_ASSIGNOR, version: 3 }]。全メンバーを一緒に切り替えます）を有効にするか、Kafka 4.0+ では KIP-848（groupProtocol: "consumer"）を使用します。メンバーの停止を検知するため、consumer:heartbeat:stalled に注意してください。
• Kafka の共有グループ（KIP-932 のキュー。Kafka 4.2 以降で本番環境に対応）は @platformatic/kafka では実装されていません。キューのセマンティクスを保証しないでください。
• Kafka 4.0+ は KRaft のみに対応しています（ZooKeeper はありません）。ローカル／開発環境では advertised.listeners を修正してください。
• コマンド例では bun／bunx を優先してください。ただし、実行環境は引き続き @platformatic/kafka の Node エンジン要件を満たす必要があります。

検証

リポジトリで定義されたコマンドを優先してください。Kafka に関する重要な作業では、該当する項目を以下から選んで実施してください。

• bun pm ls @platformatic/kafka と Node ≥22.22（または ≥24.6）。
• スモークテスト：Admin の createTopics（または既存のトピック）、Producer.send、Consumer.consume ＋ 処理 ＋ close()。
• 耐久性：ProduceAcks.ALL。EOS を謳う場合は、冪等性／transactionalId も確認してください。
• コンシューマー：正しい groupId とモード（EARLIEST／LATEST／COMMITTED）、および autocommit: false の場合は処理後にコミットしてください。
• セキュリティ：TLS ＋ SASL（または mTLS）。パブリックネットワークでは PLAINTEXT を使用しないでください。
• 運用：コンシューマーのラグ、レプリカ不足のパーティション、ホットキーの偏り、リバランスの頻発（max.poll／処理時間）。

実施したチェックと実施しなかったチェック、および残っているブローカー／バージョンに関する前提を報告してください。