@ddd-ts-kit/kafka 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,398 @@
-# Temporary Holding Version
+# @ddd-ts-kit/kafka
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The integration event provider for Apache Kafka: an `EventBus` of the kernel that publishes
+with an idempotent producer and `acks=all`, so the outbox relay can mark a record published
+safely, and consumes with one consumer group per consuming context, offsets committed after
+the handlers resolved, a bounded number of delayed retries in place and a dead-letter topic.
+It is the "Kafka and other logs" row of the strategy table of `docs/ARCHITECTURE.md`,
+implemented, and it passes `eventBusContract` of `@ddd-ts-kit/testing`.
+
+```
+npm i @ddd-ts-kit/kafka @ddd-ts-kit/events @confluentinc/kafka-javascript
+```
+
+Tested with `@confluentinc/kafka-javascript` 1.11 (librdkafka 2.16) against Apache Kafka 4.3
+in KRaft mode, on Node 24. Other brokers speaking the Kafka protocol should work; only Apache
+Kafka was run.
+
+## The client
+
+`@confluentinc/kafka-javascript` is the client maintained by Confluent: a binding of
+librdkafka with a promise API in the manner of KafkaJS, which is what this package uses.
+
+| Candidate | Looked at on 2026-10-10 | Verdict |
+|---|---|---|
+| `kafkajs` 2.2.4 | last release in February 2023 | not maintained: ruled out |
+| `@platformatic/kafka` 2.14.0 | pure JavaScript, 2.2 MB, released almost weekly, about 500 000 downloads a week, requires Node 22.22 or 24.6 | a serious option without native code; its consumer group protocol is a young reimplementation and its engine range is above the one of this kit (22.12) |
+| `@confluentinc/kafka-javascript` 1.11.0 | released 2026-10-07, about 830 000 downloads a week, librdkafka underneath | chosen: the idempotent producer, the rebalance protocol and the reconnection are those of the reference C client, which is where a provider must not be approximately right |
+
+The price is a native addon. Nothing is compiled when a prebuilt binary exists: the install
+script of the package downloads one (13 MB, 30 MB installed) from the GitHub releases of the
+client. Prebuilt binaries exist for Linux x64 and arm64 on glibc and musl, macOS arm64 and
+Windows x64, for Node 18 to 24. Verified here: Ubuntu with Node 24.21, and the images
+`node:24-alpine` and `node:24-bookworm-slim`, each without a compiler, in about five seconds.
+
+What it asks of CI and of images:
+
+- the install script must run: no `--ignore-scripts`, and with a package manager that asks
+  for install scripts to be approved (npm 11 warns, pnpm blocks), approve this package; the
+  client documents npm as supported and Yarn and pnpm as experimental;
+- the install needs to reach `github.com`; behind a proxy that forbids it, mirror the binary
+  and point `node-pre-gyp` at the mirror, or the install falls back to compiling librdkafka,
+  which needs Python, make and a C++ compiler and takes minutes;
+- build the image on the libc it runs on: a `node_modules` installed on Debian does not load
+  on Alpine;
+- nothing else is needed at run time: the binary links only to libc and libstdc++.
+
+## Composition root
+
+Handlers never see this package. They publish to the outbox; the relay publishes to Kafka;
+each consuming context listens through the bus under its own name. The bus is given to the
+application as two ports of the kernel: `IntegrationEventPublisher` stays the outbox, and
+`EventSubscribers` hands each context the subscriber of its own consumer name.
+
+`init --broker kafka` writes this wiring in the platform of the project: the bus is built by
+`platform/events/create-event-provider.ts`, `platform/platform.module.ts` rebinds
+`EventSubscribers` on it, and `main.ts` gives it, traced, to the outbox relay. By hand, the
+same thing reads:
+
+```ts
+// platform/messaging.module.ts
+import { defineContextModule } from '@ddd-ts-kit/di';
+import { EventSubscribers, IntegrationEventPublisher, type IntegrationEvent } from '@ddd-ts-kit/kernel';
+import { OutboxPublisher, OutboxStore } from '@ddd-ts-kit/events';
+import { KafkaEventBus } from '@ddd-ts-kit/kafka';
+
+// The ordering key, given to the relay and to the bus: the aggregate id an event is about.
+export const aggregateOf = (event: IntegrationEvent): string | undefined =>
+  orderPlaced.is(event) ? event.payload.orderId : undefined;
+
+export const bus = new KafkaEventBus({
+  brokers: config.kafkaBrokers, // 'kafka-1:9092,kafka-2:9092' or a list
+  client: { 'security.protocol': 'sasl_ssl', 'sasl.mechanism': 'SCRAM-SHA-512' /* ... */ },
+  keyOf: aggregateOf, // default: the event id, which orders nothing
+  publishedTypes: ['billing.invoice.issued'], // their topics are created by assertTopology
+  topics: { partitions: 6, replicationFactor: 3 }, // default: those of the broker
+  retry: { maxAttempts: 5, delayMs: 5_000 }, // the defaults
+  onFailure: (failure) => logger.warn('event bus failure', { ...failure }), // codes only, never an error message
+  onDelivery: ({ consumer, topic, outcome }) => deliveries.add(1, { consumer, topic, outcome }),
+});
+
+export const messagingModule = defineContextModule({
+  name: 'messaging',
+  register(builder) {
+    // Publishing side: handlers write to the outbox, in the transaction of the command.
+    builder.rebind(IntegrationEventPublisher).toClass(OutboxPublisher, [OutboxStore]);
+    // Consuming side: one subscriber per consuming context, named after it.
+    builder.rebind(EventSubscribers).toValue({ forContext: (name) => bus.forConsumer(name) });
+  },
+});
+```
+
+```ts
+// contexts/billing/application/integration/handlers/invoice-on-order-placed.integration-handler.ts
+import { CommandBus, systemActor, type IntegrationEvent } from '@ddd-ts-kit/kernel';
+import { IntegrationEventHandler } from '@ddd-ts-kit/kernel/declarations';
+
+@IntegrationEventHandler(orderPlaced, { consumer: 'billing.invoice-on-order-placed' }, [CommandBus])
+export class InvoiceOnOrderPlacedIntegrationHandler {
+  constructor(private readonly commands: CommandBus) {}
+
+  // Nobody is calling: the handler acts as a system actor named after its consumer.
+  readonly actor = systemActor('billing.invoice-on-order-placed');
+
+  async handle(event: IntegrationEvent<OrderPlacedPayload>): Promise<void> {
+    await this.commands.execute(new IssueInvoice(this.actor, event.payload.orderId));
+  }
+}
+```
+
+```ts
+// main.ts
+import { contextModule, createApplication, kernelModule } from '@ddd-ts-kit/di';
+import { Clock } from '@ddd-ts-kit/kernel';
+import { OutboxRelay, OutboxStore } from '@ddd-ts-kit/events';
+import { aggregateOf, bus, messagingModule } from '@/platform/messaging.module.js';
+
+const app = createApplication({
+  modules: [
+    kernelModule(),
+    persistenceModule,
+    messagingModule,
+    contextModule('ordering', orderingDeclarations),
+    contextModule('billing', billingDeclarations),
+  ],
+});
+
+// The relay target is the bus. A record is marked published when every in-sync replica has it.
+const relay = new OutboxRelay({
+  store: app.resolve(OutboxStore),
+  publisher: bus,
+  clock: app.resolve(Clock),
+  ordering: 'per-key', // one running relay: the events of an aggregate leave in order
+  keyOf: aggregateOf,
+});
+
+await app.start(); // subscribes the handler of billing on bus.forConsumer('billing')
+await bus.assertTopology(); // fail at startup, not at the first record
+relay.start({ intervalMs: 500 });
+
+process.on('SIGTERM', async () => {
+  await relay.stop(); // the tick in progress finishes
+  await app.stop(); // the handlers are unsubscribed
+  await bus.close(); // consumers stop, handlers in progress finish and commit
+});
+```
+
+- `persistenceModule` binds `OutboxStore`, and rebinds `UnitOfWork` and `ProcessedEventStore`
+  to the database: see the README of the persistence adapter. A declared integration event
+  handler is subscribed on the subscriber of its own context (`forContext` receives the name
+  of its module), and since `UnitOfWork` and `ProcessedEventStore` are bound, its idempotency
+  mark and its work commit in one unit of work: a redelivery is deduplicated, a failure
+  leaves nothing behind.
+- Without an outbox the bus is the event bus of the kernel module, and handlers publish
+  straight to the broker:
+  `kernelModule({ eventBus: bus, eventSubscribers: () => ({ forContext: (name) => bus.forConsumer(name) }) })`.
+- Without a container the same objects are wired by hand: `bus.forConsumer('billing')` is an
+  `IntegrationEventSubscriber`, to give to `subscribeAll` and `consume` of `@ddd-ts-kit/events`.
+- `publish(events)` resolves only when every in-sync replica acknowledged **every** record of
+  the batch and rejects otherwise (`PUBLISH_NOT_ACKNOWLEDGED` with the code of librdkafka in
+  `reason`, `BROKER_UNAVAILABLE`, `EVENT_BUS_CLOSED`). Nothing is buffered for later: the
+  outbox is the buffer.
+- A consumer name is required to subscribe, and it is the consumer group id, as is:
+  `bus.forConsumer('billing')` gives an `IntegrationEventSubscriber` for one context on the
+  clients of the bus (a modular monolith has several), and the `consumer` option names the
+  one `bus.subscribe` works for. A context extracted to its own service keeps its name, so
+  its group and its offsets: nothing changes on the cluster.
+- Tracing is put around both sides from outside, as with any provider: `tracedPublisher(bus)`
+  as the relay target, and on the consuming side the instrumentation of the kernel module
+  (`kernelModule({ instrumentation: traceApplication() })`), which gives each declared handler
+  one span `process <consumer>` per attempt. `tracedSubscriber(bus.forConsumer(name))` is for
+  a composition without `kernelModule`. The bus carries `traceparent` and `correlationId`
+  untouched, in the envelope and in the record headers.
+- The correlation makes the round trip. Publish through `scopedPublisher(publisher, scope)` of
+  the kernel: a declared handler (or `consume(definition, { ..., scope }, handler)` by hand,
+  or a callback wrapped with `inEventScope`) runs in an execution context whose
+  `correlationId` is the one of the request that published, whose `causationId` is the event,
+  and a retry runs in the same one.
+- Change data capture (the Debezium outbox event router) can replace the relay and the
+  publishing side of this bus; give it the same topics, keys and headers. The consuming side
+  stays.
+
+## Topology
+
+`bus.describeTopology()` returns the topics and the groups as data, for a review or a
+generated document; `bus.assertTopology()` creates the topics that do not exist and resolves
+once the consumers have their partitions. For `forConsumer('billing')` subscribed to
+`ordering.order.placed`:
+
+| Object | Name | Properties |
+|---|---|---|
+| events topic | `ordering.order.placed` | `topicOf(type)`, by default the type; partitions and replication of `topics`, or of the broker |
+| consumer group | `billing` | subscribed to the events topics of its types; starts at the earliest record |
+| dead-letter topic | `billing.ordering.order.placed.dead` | `<consumer>.<topic>.dead`; written by this consumer only |
+| replay group | `billing.replay` | exists once `replayDead` ran; its committed offsets on the dead-letter topics say what was replayed |
+
+One topic per event type is the default. `topicOf: (type) => type.split('.')[0]` gives one
+topic per producing context instead: a consumer then reads every type of that context and
+skips, by committing them, those it did not subscribe to; this is what keeps the order
+between two types of one aggregate.
+
+Topics are created on demand too: the first publication of a type creates its topic, the
+first subscription creates the events topic and the dead-letter topic. Automatic creation by
+the broker is never relied on (it gives one partition and the default replication, silently).
+An existing topic is never altered: `topics` applies at creation only. With
+`topics: { create: false }` the bus creates nothing and a missing topic fails the
+publication.
+
+A record is the envelope as JSON (`id`, `type`, `version`, `occurredAt`, `payload`,
+`traceparent`, `correlationId`), its key is `keyOf(event)`, and its headers are `x-event-id`,
+`x-event-type`, `x-event-version`, `traceparent` and `x-correlation-id`. Any Kafka client can
+consume it.
+
+Two consumers of one type are two groups and both receive every event. Two instances of one
+consumer are two members of its group: each partition, so each key, goes to one of them.
+
+## Ordering
+
+Kafka orders the records of one partition, and the key chooses the partition. So:
+
+1. Give `keyOf` the aggregate id. The default key is the event id: every event is then alone
+   in its order.
+2. Run the relay with `ordering: 'per-key'` and the same `keyOf`, or the order is lost before
+   Kafka sees the events.
+3. The bus does the rest: one publication writes the records of a topic in the order of the
+   batch (idempotent producer, so a retry of the client cannot reorder or duplicate them), a
+   consumer handles the records of a partition one at a time, and a failed record is retried
+   **in place**, see below.
+
+`concurrency` is the number of partitions a consumer handles at once (default 1); the records
+of one partition are never handled concurrently.
+
+## Retry and dead-letter behaviour
+
+1. An offset is committed after every handler subscribed to the type of the record resolved,
+   never before, and never automatically. A declared `@IntegrationEventHandler` (or `consume`
+   of `@ddd-ts-kit/events` by hand) commits its work and its idempotency mark in one unit of
+   work: the commit of the offset then follows that commit, and a redelivery is deduplicated.
+2. When a handler throws, the bus pauses the partition of the record for `retry.delayMs` and
+   reads the same record again: no hot loop, the other partitions keep flowing, and the
+   consumer keeps polling, so the wait neither delays a rebalance nor counts against
+   `max.poll.interval.ms`.
+3. At the `retry.maxAttempts`-th failed delivery the record is copied to the dead-letter
+   topic with `x-dead-reason: max-attempts`, `x-error-code`, `x-attempt` and `x-source`
+   (`<topic>/<partition>/<offset>`), its offset is committed and the partition moves on. A
+   failing record holds its partition for `(maxAttempts - 1) x delayMs` plus the time of its
+   handlers (20 s with the defaults), never for ever.
+4. A record whose value is not an envelope (unparseable, or without `id`, `type`, `version`,
+   `occurredAt`) is poison: it goes straight to the dead-letter topic with
+   `x-dead-reason: poison` and `x-error-code: POISON_MESSAGE`, and no handler sees it.
+5. Only codes travel: `x-error-code` is the `code` of the error or its class name. The message
+   of an error is never logged, reported or attached, because it may quote payload data. The
+   client logs messages and stacks of what it catches: the bus turns its logger off.
+
+**Why retry in place and not through retry topics.** A retry topic lets the partition move on
+at the first failure, and that is exactly the problem: the next event of the same aggregate
+is handled before the one that failed. A database that was down for two seconds would apply
+"order paid" before "order placed". Retrying in place keeps the order of a key through any
+failure that heals within the attempts; the cost is that the other keys of that partition
+wait too, for a bounded time. The order is given up only at the dead-letter step: the events
+that follow a dead one are handled without it, and a replay brings it back late. A consumer
+that cannot tolerate that must stop on the dead letter itself (carry a version in the
+payload, refuse a gap).
+
+Delivery is at least once. The copy-then-commit order means a crash in between delivers the
+record twice, never zero times.
+
+**Rebalances.** Offsets are committed one record at a time, for handled records only, so a
+partition that moves to another member is resumed exactly after the last handled record.
+A handler in progress when its partition is taken away finishes; its commit is then refused,
+and the new owner handles the record again: the processed-event store absorbs it. The count
+of attempts lives in the memory of the member: a record being retried when its partition
+moves, or when the process restarts, starts a fresh budget.
+
+**Lost connections.** librdkafka reconnects by itself, producers and consumers alike, with
+its own backoff. While the cluster is away `publish` rejects after `publishTimeoutMs` (30 s
+by default) with `PUBLISH_NOT_ACKNOWLEDGED`, so the outbox relay keeps the records and
+retries them; a publication that was cut may have been written, and its retry is then a
+second record with the same event id, which consumers deduplicate. A consumer that could not
+start, commit or write a dead letter reports `kind: 'connection'` and tries again after the
+`reconnect` backoff (200 ms doubling up to 30 s), without moving past the record.
+
+**Credentials.** The `client` properties (SASL password, TLS keys) go to the client library when the bus is built and are kept nowhere else. A `KafkaEventBus` that is logged, spread or
+serialised shows `KafkaEventBus [clients concealed]` and nothing else: its fields are not enumerable,
+and `toJSON` and `util.inspect` answer that name. The failures it reports are codes. What the
+client library itself shows when one of its own objects is inspected is not in the hands of
+this package: do not log those.
+
+**What a handler is told.** Next to the event, each handler receives the delivery
+(`EventDelivery` of the kernel): `{ attempt, maxAttempts, system: 'kafka', destination, consumer }`,
+where `destination` is the topic. Handlers of the application ignore it; `@ddd-ts-kit/tracing` reads it
+to make one CONSUMER span per attempt and to mark the redeliveries and the attempt after which
+the event is buried. The bus names itself `messagingSystem: 'kafka'`, and `traceparent` travels in
+the envelope and as a real header, intact across a retry.
+
+## Operations
+
+What to watch:
+
+| Signal | Where | Meaning |
+|---|---|---|
+| outbox `stats()` (`pending`, `failed`, `dead`) | the outbox store | the publishing side: see `@ddd-ts-kit/events` |
+| lag of group `<consumer>` on its events topics | cluster (`kafka-consumer-groups.sh --describe`, an exporter) | the consumer lags, is stopped, or is retrying a record: a lag that does not move is a partition held by a failing record |
+| lag of group `<consumer>.replay` on `<consumer>.<topic>.dead`, or the end offset of that topic before any replay | cluster | the dead-letter depth: must be 0, alert on anything else |
+| `onDelivery` counted by `outcome` | this bus | rate of `retried`, `dead`, `poison` against `acknowledged` |
+| `onFailure` with `kind: 'connection'` | this bus | consumers that could not start, commit or dead-letter, with the code of librdkafka |
+| `bus.deliveriesInFlight` | this bus | handlers running now; stuck above 0 means a handler that hangs |
+| `bus.partitionsAssigned` | this bus | 0 on an instance that subscribed means it consumes nothing (more instances than partitions, or not joined) |
+| under-replicated partitions, `min.insync.replicas` | cluster | below 2 in-sync replicas, `acks=all` protects nothing |
+
+Replaying dead letters, once the cause is fixed:
+
+```ts
+const replayed = await bus.replayDead({ consumer: 'billing', type: 'ordering.order.placed' }, 100);
+```
+
+It copies up to that many records from the dead-letter topic back to the topic they came
+from, with the header `x-replay-for: billing`, and commits its progress on the dead-letter
+topic as the group `billing.replay`. The consumers of this kit other than `billing` skip a
+record marked for someone else; a consumer written without this kit sees the event a second
+time and must deduplicate on `x-event-id`. The replayed record goes to the end of the topic,
+so after the events that followed it. Look at `x-dead-reason` and `x-error-code` first:
+replaying a poison record only kills it again. Dead-letter topics are ordinary topics: give
+them a retention that leaves time to look.
+
+To stop a consumer for good, delete its group, its replay group and its dead-letter topics.
+Unsubscribing a handler does not move the group: a record whose type has no handler left
+holds its partition until a handler comes back or the bus closes.
+
+## Limits
+
+- **A failing record delays its whole partition**, for `(maxAttempts - 1) x delayMs` plus the
+  time of its handlers. Keep that well under the latency the other aggregates can accept.
+- **One delay.** The wait is the same for every attempt, no exponential backoff.
+- **One commit per record**, synchronous: the throughput of a partition is bounded by the
+  handler plus a commit round trip. It is the price of never committing an unhandled record.
+- **A handler must finish within `maxHandlingMs`** (`max.poll.interval.ms`, 5 minutes by
+  default). Beyond it the member is taken for dead, its partitions move, and the record is
+  handled twice, concurrently.
+- **A new group starts at the earliest record** of its topics (`startFrom: 'earliest'`): a
+  consumer deployed after the producers misses nothing, and a consumer added a year later
+  reads a year of retained events. Choose `latest` deliberately, knowing that what is
+  published between the creation of the group and its first assignment is then skipped.
+- **A retry runs every handler of the type again**, those that succeeded included, when
+  several handlers of one consumer subscribe to the same type. Each must be idempotent.
+- **A batch is not atomic.** When `publish` rejects, some records may have been written. The
+  relay publishes one by one and retries, consumers deduplicate. Transactions are not used.
+- **The idempotent producer deduplicates the retries of the client, not those of the relay.**
+  A record published again by the relay is a second record: the processed-event store is not
+  optional.
+- **Durability is a cluster setting.** `acks=all` waits for the in-sync replicas, whatever
+  their number: use a replication factor of 3 with `min.insync.replicas=2`. The defaults of a
+  single-node broker acknowledge with one copy.
+- **`publish` does not fail fast while the cluster is away**: it waits `publishTimeoutMs`.
+  Lower it for a relay that must notice quickly; it is also the bound of a healthy but slow
+  acknowledgement.
+- **Topic and group names** are the event type and the consumer name as given: they must fit
+  the 249 characters and the `[a-zA-Z0-9._-]` alphabet of Kafka, dead-letter suffix included.
+- **Partitions of an existing topic are not changed** by the bus, and adding partitions by
+  hand moves keys to other partitions: the order of a key is lost across that change.
+- The native client is loaded in the process: a crash of librdkafka is a crash of the
+  process, and `client` is passed to it unchecked.
+
+Not verified by the test suite: a cluster of several brokers (leader election, an in-sync
+replica set that shrinks, `min.insync.replicas`), TLS and SASL, the cooperative assignor and
+the next-generation group protocol (`group.protocol=consumer`), a consumer process killed
+mid-handler, a fatal producer error (the bus then opens a new producer; the path is not
+exercised), brokers older than 4.3, and Debezium in place of the relay.
+
+## Other providers
+
+`@ddd-ts-kit/rabbitmq` and `@ddd-ts-kit/nats` implement the same two ports and pass the same
+contract suite. The three share the envelope, the header names (`traceparent`,
+`x-correlation-id`, `x-event-version`, `x-attempt`, `x-error-code`, `x-dead-reason`), the
+option names (`consumer`, `retry`, `reconnect`, `onFailure`, `onDelivery`) and the methods
+(`forConsumer`, `assertTopology`, `describeTopology`, `replayDead`, `close`). Kafka is the one
+to choose when the order of the events of an aggregate matters.
+
+## Testing
+
+The suites need a real broker and are skipped without `DDD_TS_KIT_TEST_KAFKA_BROKERS`:
+
+```
+docker run -d --rm --name ddd-ts-kit-test-kafka -p 127.0.0.1:9092:9092 -p 127.0.0.1:9094:9094 -e KAFKA_NODE_ID=1 -e KAFKA_PROCESS_ROLES=broker,controller -e KAFKA_LISTENERS=PLAINTEXT://:9092,RELAYED://:9094,CONTROLLER://:9093 -e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://127.0.0.1:9092,RELAYED://127.0.0.1:9095 -e KAFKA_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,RELAYED:PLAINTEXT -e KAFKA_CONTROLLER_QUORUM_VOTERS=1@localhost:9093 -e KAFKA_CONTROLLER_LISTENER_NAMES=CONTROLLER -e KAFKA_INTER_BROKER_LISTENER_NAME=PLAINTEXT -e KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1 -e KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=1 -e KAFKA_TRANSACTION_STATE_LOG_MIN_ISR=1 -e KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS=0 apache/kafka:4.3.1
+DDD_TS_KIT_TEST_KAFKA_BROKERS=127.0.0.1:9092 DDD_TS_KIT_TEST_KAFKA_RELAY=127.0.0.1:9095=127.0.0.1:9094 npx vitest run packages/kafka
+docker rm -f ddd-ts-kit-test-kafka
+```
+
+A Kafka client connects to the addresses the broker advertises, so a network failure cannot
+be produced by pointing the bus at a relay: the broker has a second listener, `RELAYED`,
+that advertises `127.0.0.1:9095`, where the tests listen and relay to the port behind it
+(9094). `DDD_TS_KIT_TEST_KAFKA_RELAY` gives both addresses; without it the three network
+failure tests are skipped and the rest runs.
+
+They run the contract suite on topics of one and of three partitions, then the behaviours of
+this provider, one suite per behaviour (`publishing`, `consuming`, `correlation`, `retries`
+in place, `dead-letters`, `partitions` for the order per key through a retry and a second
+instance joining, `topology`, `connection-loss` with the acknowledged publication cut
+mid-flight, `closing`) and the whole chain from the outbox to an idempotent consumer. Every test works on topics and groups of its own and deletes them.

package/dist/codec/decode.d.ts

@@ -0,0 +1,4 @@
+import type { IntegrationEvent } from '@ddd-ts-kit/kernel';
+/** The envelope exactly as published, or `undefined` for a value that is not one (poison). */
+export declare function decode(value: Buffer | null): IntegrationEvent | undefined;
+//# sourceMappingURL=decode.d.ts.map

package/dist/codec/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/codec/decode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,8FAA8F;AAC9F,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,gBAAgB,GAAG,SAAS,CAgBzE"}

package/dist/codec/decode.js

@@ -0,0 +1,39 @@
+/** The envelope exactly as published, or `undefined` for a value that is not one (poison). */
+export function decode(value) {
+    const body = value === null ? undefined : parsed(value);
+    if (!isEnvelope(body)) {
+        return undefined;
+    }
+    return {
+        id: body.id,
+        type: body.type,
+        version: body.version,
+        occurredAt: body.occurredAt,
+        payload: body.payload,
+        ...(typeof body.traceparent === 'string' ? { traceparent: body.traceparent } : {}),
+        ...(typeof body.correlationId === 'string' ? { correlationId: body.correlationId } : {}),
+    };
+}
+function parsed(content) {
+    try {
+        return JSON.parse(content.toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isEnvelope(body) {
+    if (typeof body !== 'object' || body === null) {
+        return false;
+    }
+    return (hasText(body, 'id') &&
+        hasText(body, 'type') &&
+        hasText(body, 'occurredAt') &&
+        'version' in body &&
+        typeof body.version === 'number');
+}
+function hasText(body, field) {
+    const value = Reflect.get(body, field);
+    return typeof value === 'string' && value.length > 0;
+}
+//# sourceMappingURL=decode.js.map

package/dist/codec/decode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.js","sourceRoot":"","sources":["../../src/codec/decode.ts"],"names":[],"mappings":"AAEA,8FAA8F;AAC9F,MAAM,UAAU,MAAM,CAAC,KAAoB;IACzC,MAAM,IAAI,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAExD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,GAAG,CAAC,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,GAAG,CAAC,OAAO,IAAI,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzF,CAAC;AACJ,CAAC;AAYD,SAAS,MAAM,CAAC,OAAe;IAC7B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,IAAa;IAC/B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CACL,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC;QACnB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC;QAC3B,SAAS,IAAI,IAAI;QACjB,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CACjC,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,KAAa;IAC1C,MAAM,KAAK,GAAY,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAEhD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC"}

package/dist/codec/encode.d.ts

@@ -0,0 +1,9 @@
+import type { IntegrationEvent } from '@ddd-ts-kit/kernel';
+import type { OutgoingRecord } from './outgoing-record.js';
+import type { Routing } from './routing.js';
+/**
+ * The value is the whole envelope as JSON, so any Kafka client can consume it. The headers
+ * repeat what a router, a tracer or an operator needs without opening the value.
+ */
+export declare function encode(event: IntegrationEvent, routing: Routing): OutgoingRecord;
+//# sourceMappingURL=encode.d.ts.map

package/dist/codec/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/codec/encode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAQ3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAehF"}

package/dist/codec/encode.js

@@ -0,0 +1,22 @@
+import { CORRELATION_HEADER, EVENT_ID_HEADER, EVENT_TYPE_HEADER, EVENT_VERSION_HEADER, TRACEPARENT_HEADER, } from './headers.js';
+/**
+ * The value is the whole envelope as JSON, so any Kafka client can consume it. The headers
+ * repeat what a router, a tracer or an operator needs without opening the value.
+ */
+export function encode(event, routing) {
+    return {
+        topic: routing.topicOf(event.type),
+        message: {
+            key: routing.keyOf(event) ?? null,
+            value: JSON.stringify(event),
+            headers: {
+                [EVENT_ID_HEADER]: event.id,
+                [EVENT_TYPE_HEADER]: event.type,
+                [EVENT_VERSION_HEADER]: String(event.version),
+                ...(event.traceparent === undefined ? {} : { [TRACEPARENT_HEADER]: event.traceparent }),
+                ...(event.correlationId === undefined ? {} : { [CORRELATION_HEADER]: event.correlationId }),
+            },
+        },
+    };
+}
+//# sourceMappingURL=encode.js.map

package/dist/codec/encode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.js","sourceRoot":"","sources":["../../src/codec/encode.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAItB;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,KAAuB,EAAE,OAAgB;IAC9D,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;QAClC,OAAO,EAAE;YACP,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI;YACjC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAC5B,OAAO,EAAE;gBACP,CAAC,eAAe,CAAC,EAAE,KAAK,CAAC,EAAE;gBAC3B,CAAC,iBAAiB,CAAC,EAAE,KAAK,CAAC,IAAI;gBAC/B,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;gBAC7C,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;gBACvF,GAAG,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC;aAC5F;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/codec/headers.d.ts

@@ -0,0 +1,13 @@
+export declare const EVENT_ID_HEADER = "x-event-id";
+export declare const EVENT_TYPE_HEADER = "x-event-type";
+export declare const EVENT_VERSION_HEADER = "x-event-version";
+export declare const TRACEPARENT_HEADER = "traceparent";
+export declare const CORRELATION_HEADER = "x-correlation-id";
+export declare const ATTEMPT_HEADER = "x-attempt";
+export declare const ERROR_CODE_HEADER = "x-error-code";
+export declare const DEAD_REASON_HEADER = "x-dead-reason";
+/** Where a dead record came from: `<topic>/<partition>/<offset>`. */
+export declare const SOURCE_HEADER = "x-source";
+/** Set on a replayed record: the one consumer it is meant for. The others skip it. */
+export declare const REPLAY_FOR_HEADER = "x-replay-for";
+//# sourceMappingURL=headers.d.ts.map

package/dist/codec/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../src/codec/headers.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,eAAe,CAAC;AAC5C,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAChD,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AACtD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAChD,eAAO,MAAM,kBAAkB,qBAAqB,CAAC;AACrD,eAAO,MAAM,cAAc,cAAc,CAAC;AAC1C,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAChD,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAClD,qEAAqE;AACrE,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,iBAAiB,CAAC"}

package/dist/codec/headers.js

@@ -0,0 +1,13 @@
+export const EVENT_ID_HEADER = 'x-event-id';
+export const EVENT_TYPE_HEADER = 'x-event-type';
+export const EVENT_VERSION_HEADER = 'x-event-version';
+export const TRACEPARENT_HEADER = 'traceparent';
+export const CORRELATION_HEADER = 'x-correlation-id';
+export const ATTEMPT_HEADER = 'x-attempt';
+export const ERROR_CODE_HEADER = 'x-error-code';
+export const DEAD_REASON_HEADER = 'x-dead-reason';
+/** Where a dead record came from: `<topic>/<partition>/<offset>`. */
+export const SOURCE_HEADER = 'x-source';
+/** Set on a replayed record: the one consumer it is meant for. The others skip it. */
+export const REPLAY_FOR_HEADER = 'x-replay-for';
+//# sourceMappingURL=headers.js.map

package/dist/codec/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../../src/codec/headers.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AACtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAChD,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AACrD,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC;AAC1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAChD,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAClD,qEAAqE;AACrE,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AACxC,sFAAsF;AACtF,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC"}

package/dist/codec/incoming-record.d.ts

@@ -0,0 +1,8 @@
+import type { KafkaJS } from '@confluentinc/kafka-javascript';
+/** A record as a consumer receives it. */
+export interface IncomingRecord {
+    readonly topic: string;
+    readonly partition: number;
+    readonly message: KafkaJS.KafkaMessage;
+}
+//# sourceMappingURL=incoming-record.d.ts.map

package/dist/codec/incoming-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incoming-record.d.ts","sourceRoot":"","sources":["../../src/codec/incoming-record.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAE9D,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC;CACxC"}

package/dist/codec/incoming-record.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=incoming-record.js.map

package/dist/codec/incoming-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incoming-record.js","sourceRoot":"","sources":["../../src/codec/incoming-record.ts"],"names":[],"mappings":""}

package/dist/codec/outgoing-record.d.ts

@@ -0,0 +1,7 @@
+import type { KafkaJS } from '@confluentinc/kafka-javascript';
+/** A record ready to be sent to its topic. */
+export interface OutgoingRecord {
+    readonly topic: string;
+    readonly message: KafkaJS.Message;
+}
+//# sourceMappingURL=outgoing-record.d.ts.map

package/dist/codec/outgoing-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outgoing-record.d.ts","sourceRoot":"","sources":["../../src/codec/outgoing-record.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAE9D,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC;CACnC"}

package/dist/codec/outgoing-record.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=outgoing-record.js.map

package/dist/codec/outgoing-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outgoing-record.js","sourceRoot":"","sources":["../../src/codec/outgoing-record.ts"],"names":[],"mappings":""}

package/dist/codec/republication.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingRecord } from './incoming-record.js';
+import type { OutgoingRecord } from './outgoing-record.js';
+/** The same record, key and value untouched, for another topic with `headers` added or replaced. */
+export declare function republication({ message }: IncomingRecord, topic: string, headers: Record<string, string>): OutgoingRecord;
+//# sourceMappingURL=republication.d.ts.map

package/dist/codec/republication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"republication.d.ts","sourceRoot":"","sources":["../../src/codec/republication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,oGAAoG;AACpG,wBAAgB,aAAa,CAC3B,EAAE,OAAO,EAAE,EAAE,cAAc,EAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,cAAc,CAKhB"}

package/dist/codec/republication.js

@@ -0,0 +1,8 @@
+/** The same record, key and value untouched, for another topic with `headers` added or replaced. */
+export function republication({ message }, topic, headers) {
+    return {
+        topic,
+        message: { key: message.key, value: message.value, headers: { ...message.headers, ...headers } },
+    };
+}
+//# sourceMappingURL=republication.js.map

package/dist/codec/republication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"republication.js","sourceRoot":"","sources":["../../src/codec/republication.ts"],"names":[],"mappings":"AAGA,oGAAoG;AACpG,MAAM,UAAU,aAAa,CAC3B,EAAE,OAAO,EAAkB,EAC3B,KAAa,EACb,OAA+B;IAE/B,OAAO;QACL,KAAK;QACL,OAAO,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE;KACjG,CAAC;AACJ,CAAC"}

package/dist/codec/routing.d.ts

@@ -0,0 +1,7 @@
+import type { IntegrationEvent } from '@ddd-ts-kit/kernel';
+/** Where an event goes and under which key. */
+export interface Routing {
+    readonly topicOf: (type: string) => string;
+    readonly keyOf: (event: IntegrationEvent) => string | undefined;
+}
+//# sourceMappingURL=routing.d.ts.map

package/dist/codec/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/codec/routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,CAAC;CACjE"}

package/dist/codec/routing.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=routing.js.map

package/dist/codec/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../src/codec/routing.ts"],"names":[],"mappings":""}

package/dist/codec/source-of.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingRecord } from './incoming-record.js';
+/** Where a record sits in the log: `<topic>/<partition>/<offset>`. */
+export declare function sourceOf({ topic, partition, message }: IncomingRecord): string;
+//# sourceMappingURL=source-of.d.ts.map

package/dist/codec/source-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-of.d.ts","sourceRoot":"","sources":["../../src/codec/source-of.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,cAAc,GAAG,MAAM,CAE9E"}