llm-wiki/raw/official-docs/kafka-message-delivery-semantics-design.md

---
title: official-doc / Kafka Message Delivery Semantics — At-Least-Once, Idempotent Producer, Transactional Delivery Scope
source_type: official-doc
url: https://docs.confluent.io/kafka/design/delivery-semantics.html
archive_url:
related_branches: [feature-kafka-producer-runtime-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, messaging, kafka, idempotency]
created: 2026-07-28
---

# Kafka Message Delivery Semantics — At-Least-Once, Idempotent Producer, Transactional Delivery Scope

> Layer: `raw/` — 외부 자료(공식 문서)의 **원문 발췌·출처 기록**.
> 문서 버전: Confluent Documentation "Kafka Message Delivery Guarantees" (Apache Kafka Design 섹션) — 특정 개정일 미표기.

## source_type

`official-doc` — 이 페이지는 하단에 "This website includes content developed at the Apache Software Foundation under the terms of the Apache License v2" 고지를 명시한다. 즉 Confluent 문서 사이트가 호스팅하지만, 인용 대상 내용 자체는 Apache Kafka 프로젝트의 공식 semantics 설계 서술이다. **원 요청 URL은 접근 불가했다** — 아래 "URL Fetch 실패 기록" 참조.

## URL Fetch 실패 기록 (원 요청 URL)

- 요청된 URL: `https://kafka.apache.org/documentation/#semantics`
- 시도 1 (WebFetch, `#semantics` 앵커 포함): nav/redirect 셸만 반환, "Message Delivery Semantics" 섹션 본문 없음
- 시도 2 (WebFetch, 앵커 제거 `https://kafka.apache.org/documentation/`): 동일 — 네비게이션 메뉴·릴리스 목록·footer만 포함
- 시도 3 (`curl` 직접 fetch, `kafka.apache.org/documentation.html` 및 `/40/`, `/39/`, `/38/`, `/37/`, `/36/documentation.html` 버전별 순회): 전부 `<title>Documentation Redirect Legacy | Apache Kafka</title>` 셸 페이지(19,985 bytes 동일), "Message Delivery" 문자열 0건
- **판정**: 현재 `kafka.apache.org` 문서 사이트는 JS 렌더링 SPA로 전환되어 정적 fetch로는 본문에 도달 불가. 사용자가 사전 승인한 fallback 절차에 따라 `https://docs.confluent.io/kafka/design/delivery-semantics.html` 사용.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-kafka-producer-runtime-contract]] | ca-skeleton 이 producer 측 보증을 "idempotent producer 로 파티션 단위 중복 제거된 at-least-once" 로 표현하고, **DB 와 broker 를 걸친 exactly-once 는 주장하지 않는다**는 상속 결정(`DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1`)의 경계를 공식 문장으로 고정한다 |

## 출처

- 원본 URL (요청됨, 접근 불가): https://kafka.apache.org/documentation/#semantics
- 실제 인용 URL (fallback, 사용됨): https://docs.confluent.io/kafka/design/delivery-semantics.html
- 아카이브 URL: (미제공)
- 저자 / 조직: Confluent, Inc. (문서 콘텐츠는 Apache Software Foundation 개발분 재게시, Apache License v2 고지)
- 발행일: 명시 없음 (footer: "Copyright © Confluent, Inc. 2014-", 개정일 미표기)
- 마지막 확인일: 2026-07-28

## 왜 저장했는지

`feature-kafka-producer-runtime-contract` 브랜치가 상속한 project 결정(`DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1`: "end-to-end 메시징 보증은 at-least-once 전달과 멱등 consumer·inbox로 표현하고 DB와 broker를 걸친 exactly-once를 주장하지 않는다")의 경계를 Kafka 공식 semantics 개념(at-least-once/exactly-once 정의, idempotent producer, transactional producer, exactly-once 적용 범위)으로 뒷받침하기 위함. **단, "그 보장이 파티션 단위"라는 정확한 스코프 표현은 본 페이지 어디에도 없다** — Self-Grep 결과 및 §메모 참조.

## 핵심 인용

> [§Semantic guarantees] "At least once: This means messages are delivered one or more times. If there is a system failure, messages are never lost, but they may be delivered more than once."

> [§Semantic guarantees] "Exactly once: This is the preferred behavior in that each message is delivered once and only once. Messages are never lost or read twice even if some part of the system fails."

> [§Producer delivery — idempotent 옵션] "The idempotent delivery option guarantees that resending a message will not result in duplicate entries in the log, and that log order is maintained. To achieve this, the broker assigns each producer an ID and deduplicates messages using a sequence number that is sent by the producer with every message."

> [§Producer delivery — Exactly once (transactional)] "Exactly once - Starting with version 0.11.0.0, producers can utilize transactional delivery. This means a producer can request acknowledgment that messages were received and successfully replicated, and if it resends a message, it resends with idempotency, meaning existing messages are overwritten rather than duplicated."

> [§Exactly once support] "Kafka supports exactly-once delivery in Kafka Streams and uses transactional producers and consumers to provide exactly-once delivery when transferring and processing data between Kafka topics." [...] "Otherwise, by default Kafka guarantees at-least-once delivery."

## Claims Extracted

| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KAFKA-SEM-C1 | at-least-once 는 "메시지가 1회 이상 전달됨: 실패 시 유실되지 않지만 중복 전달될 수 있음" 으로 정의된다 | "At least once: This means messages are delivered one or more times. If there is a system failure, messages are never lost, but they may be delivered more than once." | `official-vendor-doc` | Kafka broker/producer/consumer 간 semantic guarantee 용어 정의 일반 | ca-skeleton 이 실제로 at-least-once 를 달성한다는 것(설정·구현 사실)은 증명하지 않는다 — 이는 용어 정의일 뿐 프로젝트 구현 증거가 아니다 |
| KAFKA-SEM-C2 | exactly-once 는 "각 메시지가 정확히 한 번만 전달됨: 시스템 일부가 실패해도 유실되거나 두 번 읽히지 않음" 으로 정의되며 "선호되는(preferred) 동작" 으로 서술된다 | "Exactly once: This is the preferred behavior in that each message is delivered once and only once. Messages are never lost or read twice even if some part of the system fails." | `official-vendor-doc` | exactly-once 라는 용어 자체의 정의 | Kafka 가 **모든** 상황에서 exactly-once 를 실제로 제공한다는 것은 증명하지 않는다 — 페이지 자체가 바로 다음 문장에서 "many systems claim to provide exactly once ... but this might not always what you think it is" 라고 경고하며, 적용 범위는 KAFKA-SEM-C5 로 별도 한정된다 |
| KAFKA-SEM-C3 | idempotent producer 옵션은 "메시지 재전송이 로그에 중복 항목을 만들지 않고, 로그 순서가 유지됨"을 보장하며, 이는 broker가 producer마다 ID를 부여하고 매 메시지에 동봉되는 sequence number로 중복 제거하는 방식으로 달성된다 | "The idempotent delivery option guarantees that resending a message will not result in duplicate entries in the log, and that log order is maintained. To achieve this, the broker assigns each producer an ID and deduplicates messages using a sequence number that is sent by the producer with every message." | `official-vendor-doc` | Kafka producer의 idempotent delivery(0.11.0.0+) 재시도 시 broker측 중복 제거 메커니즘 | **"파티션 단위(per-partition)" 라는 단어를 이 페이지는 전혀 쓰지 않는다.** "log" 라는 표현만 사용하며, Kafka의 로그가 topic-partition 단위로 존재한다는 사실은 이 문서 밖의 일반 지식으로 추론될 뿐 본문이 명시적으로 진술하지 않는다 — Self-Grep 실패 항목으로 아래 보고. 또한 producer 재시작(새 PID 발급) 시 이전 세션의 중복 제거 상태가 유지되는지도 이 문서는 언급하지 않는다 |
| KAFKA-SEM-C4 | 0.11.0.0부터 producer는 transactional delivery를 쓸 수 있으며, 메시지 수신·복제 완료 ack를 요청할 수 있고, 재전송 시 idempotency로 기존 메시지를 덮어써 중복시키지 않는다(더 높은 지연 대신 더 높은 내구성) | "Exactly once - Starting with version 0.11.0.0, producers can utilize transactional delivery. This means a producer can request acknowledgment that messages were received and successfully replicated, and if it resends a message, it resends with idempotency, meaning existing messages are overwritten rather than duplicated." | `official-vendor-doc` | Kafka 내부(브로커/토픽/파티션)에 대한 transactional producer 동작 | **DB 트랜잭션과의 원자성은 증명하지 않는다.** 이 인용은 Kafka 브로커에 대한 producer의 ack/재전송 동작만 서술하며, 외부 데이터베이스 write 와 Kafka publish 를 하나의 원자적 단위로 묶는다는 진술은 어디에도 없다 |
| KAFKA-SEM-C5 | Kafka Streams는 transactional producer/consumer를 이용해 "Kafka 토픽 간(between Kafka topics) 데이터를 옮기고 처리할 때" exactly-once를 제공하며, 그 외 consumer/producer 시스템은 Kafka Connect API의 자동 offset 관리를 써야 하고, 그렇지 않으면 Kafka는 기본적으로 at-least-once를 보장한다 | "Kafka supports exactly-once delivery in Kafka Streams and uses transactional producers and consumers to provide exactly-once delivery when transferring and processing data between Kafka topics." [...] "Otherwise, by default Kafka guarantees at-least-once delivery." | `official-vendor-doc` | Kafka 내장 exactly-once의 적용 범위(intra-Kafka topic-to-topic) vs 그 밖의 시스템 | **이 문장은 "DB와 broker를 걸친 exactly-once가 불가능하다"를 명시적으로 부정하지 않는다.** "between Kafka topics" 로 범위를 한정하고, 외부 시스템은 Connect API의 offset 관리에 위임한다고만 말할 뿐이며, 임의의 DB write 가 Kafka publish 와 원자적으로 결합될 수 있는지/없는지에 대한 직접 진술은 이 페이지에 없다 |

### Strength 참고

모두 `official-vendor-doc` — RFC/표준(`official-standard`)이 아니라 Kafka 프로젝트(Apache Software Foundation 개발분, Confluent 재게시)의 공식 설계 문서 서술이다.

## Usage Boundaries

- 이 자료가 직접 증명하는 것:
  - `KAFKA-SEM-C1`: at-least-once 의 정의(1회 이상 전달, 실패 시 무손실이나 중복 가능)
  - `KAFKA-SEM-C2`: exactly-once 의 정의(정확히 1회, 무손실·무중복) 및 이 페이지가 이를 "선호되는 동작"으로 규정한다는 것
  - `KAFKA-SEM-C3`: idempotent producer 가 broker-assigned ID + per-message sequence number 로 재전송 시 로그 중복을 막는다는 메커니즘
  - `KAFKA-SEM-C4`: 0.11.0.0+ transactional producer 가 ack 요청 + idempotent 재전송(overwrite, not duplicate)을 제공한다는 것
  - `KAFKA-SEM-C5`: Kafka 내장 exactly-once 의 명시적 적용 범위가 "Kafka 토픽 간"이며, 그 밖의 시스템은 Connect API offset 관리에 의존한다는 것, 기본값은 at-least-once 라는 것
- 이 자료가 증명하지 **않는** 것:
  - **idempotent producer 보장이 "파티션 단위"라는 정확한 스코프 문구.** 이 페이지는 그 단어를 쓰지 않는다(`KAFKA-SEM-C3` 참조) — branch-note 나 project 결정문에서 "파티션 단위"라는 표현을 쓰려면 이 문서만으로는 근거가 부족하고, Kafka producer configs 공식 문서(`enable.idempotence` 항목, Javadoc)로 별도 보강이 필요하다
  - Kafka transactional producer 가 DB write 와 원자적으로 결합된다는 것(`KAFKA-SEM-C4`, `KAFKA-SEM-C5`) — 이 문서 범위 안에서는 Kafka 내부(토픽/파티션) transactional write만 다루며, DB-broker 이중 쓰기(dual-write) 원자성에 대한 진술은 전혀 없다
  - Kafka 가 모든 상황에서 exactly-once 를 보장한다는 일반 주장 — 페이지 스스로 "many systems claim to provide exactly once delivery semantics, but this might not always be what you think it is" 라고 경고하며 범위를 한정한다
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - "파티션 단위 중복 제거"의 정확한 공식 문구 — Kafka producer configs 문서(`enable.idempotence`) 또는 Javadoc 별도 인용 필요
  - `acks=all` + idempotent producer 조합이 실제로 ca-skeleton 설정에 반영되는지 — 별도 구현 증거(코드/설정) 필요
  - Kafka Connect API 의 offset 관리가 실제로 임의 외부 DB(비-Connect 커스텀 consumer)에도 원자성을 제공하는지 — 이 페이지는 Connect 커넥터 예시(HDFS)만 들며 일반화하지 않는다

## 메모

- Self-Grep 실패 보고: "파티션 단위" 관련 원문 문구를 이 페이지(Confluent fallback)에서 찾지 못했다. 추측으로 채우지 않고 `KAFKA-SEM-C3`의 "Does not prove"에 명시했다. 필요 시 Apache Kafka producer configs 공식 문서(`enable.idempotence`)를 별도 raw 문서로 수집해 이 gap 을 메워야 한다.
- 원 요청 URL(`kafka.apache.org/documentation/#semantics`)은 현재 정적 fetch로 접근 불가한 JS 렌더링 nav 셸이다 — 향후 재시도 시 브라우저 렌더링 기반 도구가 필요할 수 있다.
- 같은 branch 의 다른 raw 문서(`raw/official-docs/spring-kafka-sending-messages-kafkatemplate.md`)가 이미 "acks=all + enable.idempotence 설정 자체"를 다루는 Kafka producer configs 공식 문서 보강이 필요하다고 지적한 바 있다 — 동일 gap.

## 관련

- 같은 branch 의 다른 official-doc: [[raw/official-docs/spring-kafka-sending-messages-kafkatemplate.md]] — `KafkaTemplate.send()` 반환 타입/동기 대기 메커니즘 (같은 branch, 인접 관심사)
- 이 자료를 인용한 wiki 요약: (생성 시 링크)