Zum Inhalt springen
Deutsch

Kafka

KafkaActor integriert mit Apache Kafka. Umschließt intern kafkajs; du importierst es nicht direkt.

import { ActorSystem } from 'actor-ts';
import { KafkaActor, KafkaOptions } from 'actor-ts/io';
const system = ActorSystem.create('my-app');
const kafkaOptions = KafkaOptions.create()
.withBrokers(['kafka-1:9092', 'kafka-2:9092'])
.withClientId('my-app')
// Consumer-Actor-Target wird einmalig hier konfiguriert.
.withConsumer({ groupId: 'my-app-orders' })
.withTopics(['orders', 'payments'])
.withTarget(orderHandler);
const kafka = system.spawn(
() => new KafkaActor(
kafkaOptions,
),
'kafka',
);
// Ein weiteres Topic zur Laufzeit hinzufügen (das `topics` aus dem
// Konstruktor deckt den Normalfall ab; `subscribe` ist für späte
// Ergänzungen).
kafka.tell({ kind: 'subscribe', topic: 'audit' });
// Publishen:
kafka.tell({ kind: 'publish', publish: { topic: 'audit', value: 'something' } });
interface KafkaOptionsType extends BrokerCommonOptionsType {
brokers: string[] | string; // Bootstrap-Server
clientId?: string;
sasl?: {
mechanism: 'plain' | 'scram-sha-256' | 'scram-sha-512';
username: string;
password: string;
};
ssl?: boolean | TlsTransportOptionsType; // true, or cert material
producer?: {
idempotent?: boolean;
allowAutoTopicCreation?: boolean;
};
consumer?: {
groupId?: string;
fromBeginning?: boolean;
commitMode?: 'auto' | 'manual';
commitTimeoutMs?: number;
};
target?: ActorRef<KafkaRecord>; // Consumer-Actor für eingehende Records
topics?: ReadonlyArray<string>;
}

Der Parent BrokerCommonOptionsType gibt dir Reconnect, Buffer, Breaker — siehe BrokerActor-Basis.

Dieselben Einstellungen kommen aus HOCON, unter actor-ts.io.broker.kafka, unterhalb expliziter Optionen und oberhalb der eingebauten Defaults:

actor-ts.io.broker.kafka {
brokers = ["kafka-1:9092", "kafka-2:9092"] # a list, even for one broker
client-id = "my-app"
ssl = false # the default; certificate material is code-only
sasl { # all three leaves, once the block is there
mechanism = "scram-sha-256" # "plain", "scram-sha-256" or "scram-sha-512"
username = "my-app"
password = ${?ACTOR_TS_KAFKA_PASSWORD}
}
consumer {
group-id = "my-app-orders" # no consumer without one
from-beginning = false # the default
commit-mode = "auto" # the default; or "manual"
commit-timeout = 30s # the default; manual mode only
}
topics = ["orders", "payments"]
}

brokers und topics sind Listen, und commit-timeout ist eine Dauer, 30s und 30000 meinen also dasselbe. Bleibt group-id ungesetzt, ist der Actor nur Producer.

Idempotenz und automatische Topic-Erzeugung sind eher Cluster-Policy als Anwendungscode, deshalb sind beide unter actor-ts.io.broker.kafka lesbar:

actor-ts.io.broker.kafka {
producer {
idempotent = true
allow-auto-topic-creation = false
}
}

Nennst du nur eines von beiden, behält das andere seinen eingebauten Default — der Reader baut den Block neu auf, statt einen partiellen zurückzugeben, ein HOCON-producer { idempotent = true } kann allowAutoTopicCreation also nicht ausleeren.

withProducer({ … }) im Code ersetzt den konfigurierten Block weiterhin vollständig: gewohnte Präzedenz (Konstruktor > HOCON > Defaults), angewendet auf das Feld, das dieses Objekt ist.

target hat keinen Config-Key — es ist eine ActorRef, die einen lebenden Actor in diesem Prozess benennt, und dafür hat eine Config-Datei keine Schreibweise. Ebenso wenig die Zertifikatsform von ssl: das HOCON-Blatt ist nur boolesch, denn eine Config-Datei ist der falsche Ort für einen Private Key.

kafka.tell({
kind: 'publish',
publish: {
topic: 'orders',
key: orderId, // optional — partitioniert nach Key
value: JSON.stringify(order),
headers: { 'x-trace': traceId },
},
});

Bei getrennter Verbindung gepuffert; beim Reconnect in Reihenfolge geflusht.

Für strikte Reihenfolge innerhalb einer Partition setze producer.idempotent: true und gib einen konsistenten key für zusammengehörige Records — kafkajs dedupliziert Retries innerhalb der Producer-Session.

// Das Consumer-Actor-Target wird über die Settings verdrahtet
// (siehe oben); `subscribe` ergänzt zur Laufzeit nur weitere
// Topics, wenn nötig.
kafka.tell({ kind: 'subscribe', topic: 'orders' });
class OrderHandler extends Actor<KafkaRecord> {
override onReceive(record: KafkaRecord): void {
// record.topic / partition / offset / key / value / timestamp / headers
const order = JSON.parse(new TextDecoder().decode(record.value!));
this.process(order);
}
}

Der Actor liefert jeden konsumierten Record an target. Für Kafkas Consumer-Group-Work-Sharing nimm mehrere Actor-Instanzen mit derselben groupId — jede Instanz übernimmt eine Teilmenge der Partitionen.

topics und das subscribe-Kommando zur Laufzeit speisen dieselbe gewünschte Menge, die von der BrokerActor-Basisklasse gehalten wird und nicht vom Consumer: ein zur Laufzeit hinzugefügtes Topic wird nach einem Reconnect neu subscribed, und ein subscribe, das gesendet wird während der Actor getrennt ist, wird beim nächsten Connect angewandt statt verworfen. Konfigurierte Topics erben consumer.fromBeginning; eine Ergänzung zur Laufzeit startet beim aktuellen Offset.

Ein unsubscribe gibt es nicht — kafkajs kann einem laufenden Consumer kein einzelnes Topic entziehen. Stoppe den Actor (oder starte einen zweiten mit einer anderen groupId), wenn ein Consumer wirklich eine andere Topic-Menge braucht.

consumer: { commitMode: 'auto' } // at-least-once
consumer: { commitMode: 'manual' } // exactly-once-with-processing

auto (Default): kafkajs committed, nachdem der Handler zurückkehrt. Crash zwischen Handler und Commit → erneute Auslieferung beim nächsten Start. At-least-once. Handler müssen idempotent sein.

manual: der Consumer pausiert bei jedem Record und wartet auf eine explizite Commit-Nachricht:

override async onReceive(record: KafkaRecord): Promise<void> {
await processIdempotently(record);
this.kafka.tell({
kind: 'commit',
topic: record.topic,
partition: record.partition,
offset: record.offset,
});
}

Liefert Exactly-once-with-processing-Semantik, wenn deine Verarbeitung selbst transaktional ist. commitTimeoutMs (Default 30 s) deckelt, wie lange die Pumpe wartet, bevor sie aufgibt und einen Rebalance auslöst.

const kafkaOptions = KafkaOptions.create()
.withBrokers(['kafka-1:9093'])
.withSsl(true)
.withSasl({
mechanism: 'scram-sha-512',
username: process.env.KAFKA_USER!,
password: process.env.KAFKA_PASS!,
});
new KafkaActor(
kafkaOptions,
);

Sowohl TLS als auch SASL-Credentials werden an kafkajs durchgereicht. Nimm Env-Variablen für Secrets; hardcode sie nicht in application.conf.

withSsl(true) verifiziert den Broker gegen den System-Trust-Store. Hinter einer privaten CA — oder wenn der Broker ein Client-Zertifikat verlangt — übergibst du das Material statt des Booleans:

const kafkaOptions = KafkaOptions.create()
.withBrokers(['kafka-1:9093'])
.withSsl({
ca: fs.readFileSync('./tls/ca.crt', 'utf8'),
cert: fs.readFileSync('./tls/client.crt', 'utf8'),
key: fs.readFileSync('./tls/client.key', 'utf8'),
});
new KafkaActor(kafkaOptions);

Jedes Feld trägt das Material selbst, nie einen Pfad darauf — deshalb liest das Beispiel die Dateien. cert und key ergeben nur gemeinsam Sinn; eines ohne das andere wird beim Start des Actors abgelehnt.

Der ssl-Config-Key bleibt bewusst boolean-only: Ein Private Key gehört nicht in die application.conf, die Material-Form ist also nur aus dem Code erreichbar.

Terminal-Fenster
npm install kafkajs
# oder: bun add kafkajs

kafkajs ist eine Peer-Dependency — das Framework bundelt es nicht. Du installierst es, wenn du KafkaActor nutzt.

Drei primäre Anwendungsfälle:

  1. Durables Event-Streaming — mehrere Consumer lesen denselben Stream mit verschiedenen Offsets; wiederabspielbare Historie.
  2. Producer und Consumer entkoppeln — High-Volume-Downstreams, die nicht das Tempo des Producers vorgeben sollten.
  3. Brücken zu bestehender Kafka-Infrastruktur — actor-ts an ein bereits Kafka nutzendes System anbinden.

Für clusterinternes Pub/Sub bevorzuge DistributedPubSub — keine Broker- Abhängigkeit.