Exactly-Once Delivery
debt(d9/e7/b7/t7)
Closest to 'silent in production until users hit it' (d9). The detection_hints field explicitly states automated: no, and the code_pattern hint (initTransactions|beginTransaction) only tells you the feature is being used, not whether it's correctly configured end-to-end. A missing transactional consumer or network partition will silently produce at-least-once or at-most-once semantics in production — duplicate or lost messages only manifest under failure conditions that are invisible during normal operation.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix mentions Kafka transactions, outbox pattern, and idempotent consumers as alternatives. Switching from a broken exactly-once assumption to a correct architecture (either true transactional Kafka or outbox + idempotent consumer) requires changes to producers, consumers, and often the persistence layer across multiple services. This is not a single-file fix and typically spans the entire messaging pipeline.
Closest to 'strong gravitational pull' (e7 → b7). The applies_to covers cli and queue-worker contexts broadly. Once a system is architected around exactly-once semantics (or incorrectly assumes them), every downstream consumer, producer, retry strategy, and failure-handling path is shaped by that choice. Changing the delivery guarantee affects every component that reads or writes to the message broker.
Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception is explicit: developers commonly believe enabling Kafka idempotence achieves exactly-once end-to-end, but without a transactional consumer it is still at-least-once. Additionally, network failures make true exactly-once impossible across distributed systems. This contradicts the intuitive reading of the feature name and Kafka's own idempotent producer documentation, making it a serious trap that experienced developers commonly fall into.
TL;DR
Explanation
True exactly-once requires: idempotent producer (Kafka enable.idempotence=true), transactional producer (write + offset commit in one DB transaction), and transactional consumer. Kafka: exactly-once via transactions — producer writes and commits consumer offsets atomically. Cost: lower throughput, higher latency. Alternatives: at-least-once + idempotent consumer (practically equivalent, more portable). Exactly-once semantics (EOS) in Kafka: enable.idempotence=true + transactional.id + isolation.level=read_committed. RabbitMQ: no native exactly-once — use outbox pattern + deduplication. Most real-world systems use at-least-once + idempotency.
Common Misconception
Why It Matters
Common Mistakes
- Enabling Kafka idempotence without transactional consumer — still at-least-once end-to-end.
- Using exactly-once where at-least-once + idempotency is simpler and sufficient.
- Not understanding that network failures make true exactly-once impossible across systems.
Code Examples
// Claimed exactly-once but not transactional end-to-end:
$producer->send($topic, $message); // Idempotent producer
$consumer->process($message); // Not transactional — can fail after produce// Kafka transactional exactly-once:
$producer->initTransactions();
$producer->beginTransaction();
try {
$producer->send($outputTopic, $result);
$producer->sendOffsetsToTransaction($offsets, $consumerGroupId);
$producer->commitTransaction();
} catch (Exception $e) {
$producer->abortTransaction();
}