Exactly-Once Semantics

Exactly-Once Semantics Overview

Exactly-Once Semantics is a building block you will reach for often in Apache Kafka. It keeps related logic together and makes your intent obvious to reviewers and future maintainers.

When you learn exactly-once semantics properly, you avoid the guesswork that leads to bugs and rework. The example below shows the shape you will use in most real Apache Kafka projects.

import { Kafka } from 'kafkajs';

const kafka = new Kafka({ clientId: 'orders', brokers: ['localhost:9092'] });
const consumer = kafka.consumer({ groupId: 'order-processors' });

await consumer.connect();
await consumer.subscribe({ topic: 'orders', fromBeginning: false });

await consumer.run({
  eachMessage: async ({ topic, partition, message }) => {
    const order = JSON.parse(message.value.toString());
    console.log({ partition, key: message.key?.toString(), order });
  },
});

A consumer joins a group and processes messages from the partitions it is assigned.

Exactly-Once Semantics Example

import { Kafka } from 'kafkajs';

const kafka = new Kafka({ clientId: 'app', brokers: ['localhost:9092'] });
const producer = kafka.producer();
const consumer = kafka.consumer({ groupId: 'group' });

• Start from a minimal Exactly-Once Semantics example and grow it only as needed.
• Keep configuration explicit so Exactly-Once Semantics behaves the same in every environment.
• Name things clearly so teammates understand your Exactly-Once Semantics at a glance.
• Add tests around Exactly-Once Semantics early to lock in expected behaviour.

Apache Kafka Cheatsheet

Handy KafkaJS reference related to exactly-once semantics.

How Exactly-Once Semantics Works in Apache Kafka

Exactly-Once Semantics builds on Kafka's log-based design, where producers append events to partitioned topics and consumer groups read them independently, tracking their own offsets.

A consumer joins a group and processes messages from the partitions it is assigned.

• Topics are split into partitions for parallelism and ordering per key.
• Producers choose a partition, usually by message key.
• Consumer groups share partitions so work scales horizontally.
• Offsets record how far each group has read.

Practical Guidance for Exactly-Once Semantics

In production, exactly-once semantics needs attention to delivery guarantees, retries, and observability. Make handlers idempotent and monitor consumer lag closely.

Common Mistakes

• Skipping error handling and edge cases when wiring up exactly-once semantics.
• Leaving exactly-once semantics untested, so regressions slip into production.
• Over-engineering exactly-once semantics before you actually need the extra flexibility.
• Ignoring documentation, which makes exactly-once semantics hard for the next developer to change.

Key Takeaways

• Exactly-Once Semantics is a core part of working effectively with Apache Kafka.
• Start small and keep exactly-once semantics focused on a single responsibility.
• Apply consistent patterns so exactly-once semantics scales across your project.
• Test and document exactly-once semantics to keep it maintainable over time.