문제: 2026-11-01 성숙도 리뷰에서 High 21건·P1 25건이 나왔다. 결과를 모르는 일을 "확실함"으로 기록했다(발송 중 죽은 알림 재발송, 커밋 중 끊긴 쓰기를 재시도 가능으로 응답, 재시도 가능한 거부를 DEAD로). 중복을 DB가 아니라 코드 순서로 막았다(정산 job, 포스터 제목). 짝 프론트와 wire 계약이 달랐고(처리 중 409, Envelope null), JWT audience 검증이 기본으로 꺼져 있었고, 트레이스가 나가지 않았고, CI가 strict lane 14개를 한 번도 돌리지 않았다. 방법: 발견마다 실패하는 테스트를 먼저 쓰고 고쳤다. 주요 선택: - 알림 attempt는 처음부터 "시작 여부 모름"으로 쓴다(호출 직전 갱신은 쓰기가 하나 늘어 버림). - 정산 job claim은 lease·fence를 갱신하는 UPDATE 한 문장(처리 전체를 트랜잭션으로 감싸는 안은 외부 호출 동안 잠금을 잡아 버림). - 커밋 단계 연결 끊김은 DB_COMPLETION_UNKNOWN(재시도 불가). - 처리 중 409는 retryable=true + Retry-After: 2, Envelope null 필드는 web Jackson mixin으로 생략(shared-contract는 stdlib only). - 트레이싱은 자체 Tracer를 지우고 Boot 4 tracing·OTLP로. - strict lane을 단계에 연결하고 verifyStrictLaneStages가 고아를 막는다. 발견별 RED·GREEN·버린 대안은 리뷰 README 13절 표에 있다. 위험·한계: JWT 모드는 APP_SECURITY_JWT_AUDIENCE가 없으면 기동하지 않는다. 짝 프론트는 409 retryable과 Envelope 키 규칙을 맞춰야 한다. 이 커밋 시점에는 MinIO 공식 이미지가 사라져 MinIO 2 lane이 실패한다 (다음 커밋에서 대체 이미지로 해결). 검증: ci 통과. mainCheck·integrationCheck는 MinIO 2 lane만 실패(이미지 pull 거부). -p optional-platforms ci integrationCheck, performanceCheck, releaseCheck(-PgitRevision) 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 2·13절 BREAKING CHANGE: JWT 모드에서 APP_SECURITY_JWT_AUDIENCE가 필수가 되고 role은 audience client와 realm 것만 읽는다. IDEMPOTENT_IN_FLIGHT가 retryable=true, Retry-After: 2로 바뀌고 Envelope는 null 필드를 보내지 않는다.
55 lines
3.0 KiB
Markdown
55 lines
3.0 KiB
Markdown
# ADR-JPA-003 — Completion unknown is never retried
|
|
|
|
- Status: Accepted; amended 2026-09-25 — `TransactionCompletionResolver`, `CommitFailureClassifier`
|
|
and the retry engine were removed. The invariant holds because `SpringTransactionPort`, the only
|
|
transaction engine, retries nothing; enforcement below is updated accordingly.
|
|
- Date: 2026-08-11
|
|
- Design: §17
|
|
|
|
## Context
|
|
|
|
A connection can break while a commit is in flight. The server may have committed; the
|
|
acknowledgement may simply have been lost. The driver cannot tell the two apart.
|
|
|
|
## Decision
|
|
|
|
`TransactionCompletionUnknownException` is never retried, automatically or otherwise. It is
|
|
produced only by a failure observed while the transaction phase is `COMMITTING`, and only for
|
|
SQLSTATE `40003`, a connection-class (`08*`) state, or a transport break. Recovery is
|
|
domain-specific reconciliation.
|
|
|
|
## Consequences
|
|
|
|
Retrying a possibly-committed write is the most damaging thing this platform could do: a duplicate
|
|
payment, a duplicate order, a double decrement. There is no budget or backoff that makes it safe,
|
|
because the failure is epistemic rather than transient.
|
|
|
|
The invariant is enforced at the type level rather than by policy alone. `JpaFailureContext` refuses
|
|
to construct a retryable completion-unknown context, and the exception rebuilds its context through
|
|
the safe factory whatever it is handed. A future policy bug therefore cannot produce an unsafe
|
|
retry — the value it would need does not exist.
|
|
|
|
The rule is deliberately narrow in the other direction too. Classifying every connection failure as
|
|
completion-unknown would push ordinary pool exhaustion and server restarts into the reconciliation
|
|
queue, which trains operators to clear that queue without reading it — and then the one entry that
|
|
mattered gets cleared with the rest.
|
|
|
|
The cost is that the domain must supply the resolver. The platform cannot: only the domain knows
|
|
which idempotency record, business row, or outbox entry proves the write happened.
|
|
|
|
## Enforcement
|
|
|
|
Production path: `SpringTransaction` records when the action has returned in a write transaction it
|
|
began; a failure after that point goes through
|
|
`PersistenceExceptionTranslator#translateCommitFailure`, which builds this exception for `08*`,
|
|
`40003`, a vendor termination state (`SqlStateErrorMapping#commitOutcomeUnknownStates`, PostgreSQL
|
|
`57P01`/`57P02`) or a transport break. Hibernate's flush inside the commit is not separated from the
|
|
COMMIT itself, so a connection lost during that flush is also reported as unknown — the safe side.
|
|
Until review 04-01 (2026-11-01) nothing constructed the exception and a commit-phase `08*` reached
|
|
callers as the retryable `DB_UNAVAILABLE`.
|
|
|
|
`JpaFailureContextTest`; `SpringTransactionTest`; `PersistenceExceptionTranslatorTest`;
|
|
`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried`
|
|
(asserts `DB_COMPLETION_UNKNOWN`; also the `jpa-failure` lane, i.e. release gate
|
|
`completion-unknown-no-retry`).
|