Files
clean-architecture-backend-…/docs/mongodb/consistency-transaction-guide.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

6.2 KiB

Consistency and Transaction Guide

Design §12–§16, decisions D-07 through D-10. This is the part of the platform where the wrong default is most expensive and the least visible in testing, because every failure mode here needs a primary change to reproduce.

1. Prefer a single-document atomic operation

D-09: a transaction is for a multi-document invariant, nothing else. A single document is already atomic in MongoDB, so wrapping a one-document update in a transaction buys nothing and costs a session, a two-phase commit and a new ambiguous outcome.

D-07: partial change uses update operators, not save(). MongoAtomicOperations / MongoAtomicOperationsTemplate expose the operator set through MongoUpdateOperator ($set, $inc, $push, $pull, $addToSet, $min, $max, $currentDate, …) with an AtomicFilter precondition and a ReturnDocumentMode. Read-modify-write through save() replaces the whole document and silently discards any field another writer changed in between — a lost update with no error.

2. Whole-document replacement needs a revision

D-08. VersionedMongoUpdater requires a MongoRevision: either a Spring Data @Version field or an explicit expected-revision predicate in VersionedUpdateCommand. A replacement whose filter matched zero documents is not "nothing to do" — MongoOptimisticConflictTranslator distinguishes:

  • filter matched nothing and the id does not exist → MongoDocumentNotFoundException
  • filter matched nothing and the id exists → MongoOptimisticConflictException

Collapsing these two into one is how a concurrent overwrite becomes a 404.

3. Consistency profiles

MongoConsistencyProfile names the read/write concern pair; MongoConsistencyRegistry binds a profile to an operation or collection, and MongoConsistencyBinder applies it at execution.

Profile Meaning Use for
PRIMARY_LOCAL primary read, local concern Throughput-sensitive reads that tolerate a rollback window.
PRIMARY_MAJORITY primary read, majority write The default for anything a user will see again immediately.
CAUSAL_MAJORITY majority inside a causal session Read-your-writes across separate operations.
STALE_READ_ALLOWED secondary reads permitted Reporting and analytics that state their staleness.
SNAPSHOT_TRANSACTION snapshot isolation Multi-document reads inside a transaction.

A profile is a declaration, not a hint: the registry is consulted per operation and an operation without a registered profile is rejected rather than defaulting.

4. Causal sessions

MongoCausalSessionContext plus SpringMongoCausalSessionExecutor carry the cluster time and operation time between operations, so "write then read" returns the write even when the read lands on a different node. Without a causal session, PRIMARY_MAJORITY gives you durability but not read-your-writes across two calls.

5. Transactions

MongoTransactionExecutor opens a session through the session factory, run the body, and commit. MongoTransactionProfile carries the consistency profile, the maxCommitTime and the retry budget. Topology matters: a transaction requires a replica set, and MongoStartupValidator refuses a transaction-declaring profile on STANDALONE at startup rather than at the first call.

6. Retry: body and commit are different loops

D-10, and the single most consequential rule in the design.

for each body attempt:
    open a NEW session
    run the body
        TransientTransactionError  -> abort, next body attempt
    commit
        UnknownTransactionCommitResult -> retry COMMIT ONLY, same session

MongoTransactionRetryCoordinator implements exactly this:

  • A new session per body attempt. Reusing the session after an abort carries the aborted transaction's state into the retry.
  • The body is never replayed after a commit ambiguity. An unknown commit means the commit may already have applied. Re-running the body would apply it a second time. Only the commit is retried, and a commit retry on an already-committed transaction is a no-op by design.
  • A budget bounds both loops. MongoRetryBudget limits attempts and elapsed time, with jittered backoff (delayBefore(attempt, random)), so a struggling primary is not retried into the ground.

MongoRetryDecision and MongoRetryScope (in …api.error) say what may be retried: MongoRetryScope.BODY, COMMIT_ONLY, or NONE.

7. Ambiguous outcomes

MongoExecutionOutcome has six values, two of which are ambiguous and must not be collapsed:

Outcome Did the write happen?
NOT_SENT No. Safe to retry.
NO_WRITE_PERFORMED No — the server answered and did nothing.
WRITE_CONFIRMED Yes.
PARTIAL_BULK_WRITE Some of it. See MongoBulkResult.
WRITE_RESULT_UNKNOWN Unknown.
TRANSACTION_COMMIT_UNKNOWN Unknown.

An unknown outcome is not a failure and must not be reported to a caller as one. The caller either reconciles (MongoCommitReconciler re-reads a deterministic marker the body wrote) or surfaces the ambiguity. See runbooks/unknown-commit.md.

MongoFailureContext records only the design-permitted fields — outcome, category, operation name, collection profile, retry scope, attempt — never the query, the document, or the values.

8. Failure translation

DefaultMongoFailureClassifier classifies labels before codes. The server's error labels (TransientTransactionError, UnknownTransactionCommitResult, RetryableWriteError) are the authoritative statement about retryability; an error code is a secondary signal whose meaning varies by server version. DefaultMongoFailureTranslator maps a classification onto the stable exception hierarchy, and anything unmatched becomes MongoUnclassifiedFailureException rather than leaking a driver type.

9. Bulk writes

MongoBulkExecutor returns a MongoBulkResult with per-item MongoBulkItemFailure entries. An unordered bulk write that partially fails is PARTIAL_BULK_WRITE, not a failure: some documents were written. The result's per-item outcomes say which indexes succeeded and which failed, so a caller can resume rather than replay.