fix!: 2026-11 성숙도 리뷰 발견을 고치고 재리뷰를 마친다 #1
@@ -49,6 +49,12 @@ jobs:
|
||||
- name: Run the pull-request gate
|
||||
working-directory: src
|
||||
run: ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --stacktrace
|
||||
# Plans every stage (`--dry-run`: nothing executes) and fails when a strict lane is in no stage
|
||||
# a workflow executes, or a stage is executed by no workflow (review 2026-11-01 08-01). A new
|
||||
# lane fails here, on its own pull request, instead of running nowhere after it merges.
|
||||
- name: Require every strict lane to be in an executed stage
|
||||
working-directory: src
|
||||
run: ./gradlew :verifyStrictLaneStages --dry-run --stacktrace
|
||||
- name: Verify Compose profile contracts render exactly as declared
|
||||
run: bash scripts/verify-compose-profile-contracts.sh
|
||||
|
||||
@@ -59,9 +65,12 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
# `qualityCheck` too: the root one covers the production leaves only, so the sample — the code
|
||||
# adopters copy first — was analysed by no stage, and its SpotBugs exclusions matched nothing
|
||||
# (review 2026-11-03 RR-06-05).
|
||||
- name: Verify the standalone sample application
|
||||
working-directory: src
|
||||
run: ./gradlew :sample-portfolio:check --stacktrace
|
||||
run: ./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --stacktrace
|
||||
|
||||
optional-platforms:
|
||||
runs-on: ubuntu-latest
|
||||
@@ -71,6 +80,11 @@ jobs:
|
||||
- name: Verify the optional gRPC platform build
|
||||
working-directory: src
|
||||
run: ./gradlew -p optional-platforms ci --stacktrace
|
||||
# The optional build's own lane-reachability check: the main build's cannot see these lanes
|
||||
# (review 2026-11-03 RR-06-03).
|
||||
- name: Require every optional-platform strict lane to be in an executed stage
|
||||
working-directory: src
|
||||
run: ./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --stacktrace
|
||||
|
||||
# gRPC schema policy (owner decision 18). protoc compiles src/grpc/grpc-contract inside the
|
||||
# optional-platforms build above; lint and breaking-change policy belong to Buf, configured by
|
||||
|
||||
@@ -32,7 +32,6 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:fileserver:test --tests '*NfsAmbiguityIntegrationTest'
|
||||
|
||||
--stacktrace
|
||||
- name: Tear down the NFS environment
|
||||
if: always()
|
||||
@@ -51,7 +50,6 @@ jobs:
|
||||
:adapter:outbound:fileserver:test --tests '*CrashRecoveryMatrixTest'
|
||||
:application-fileserver:test --tests '*FileReconciliationServiceTest'
|
||||
--rerun-tasks
|
||||
|
||||
--stacktrace
|
||||
|
||||
fileserver-large-file-performance:
|
||||
@@ -69,7 +67,6 @@ jobs:
|
||||
:adapter:outbound:fileserver:test --tests '*LargeFileBoundedMemoryTest'
|
||||
:adapter:outbound:fileserver:test --tests '*LocalAppendMemoryTest'
|
||||
--rerun-tasks
|
||||
|
||||
--stacktrace
|
||||
|
||||
fileserver-multi-instance-lease:
|
||||
@@ -84,5 +81,4 @@ jobs:
|
||||
./gradlew
|
||||
:application-fileserver:test --tests '*MultiInstanceWriterLeaseTest'
|
||||
--rerun-tasks
|
||||
|
||||
--stacktrace
|
||||
|
||||
@@ -56,7 +56,6 @@ jobs:
|
||||
./gradlew
|
||||
:application-fileserver:test
|
||||
:composition:fileserver-platform:test
|
||||
|
||||
--stacktrace
|
||||
|
||||
fileserver-local-ext4-contract:
|
||||
@@ -70,7 +69,6 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:fileserver:test
|
||||
|
||||
--stacktrace
|
||||
|
||||
fileserver-http-contract:
|
||||
@@ -84,7 +82,6 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:inbound:web-fileserver:test
|
||||
|
||||
--stacktrace
|
||||
|
||||
fileserver-security-suite:
|
||||
@@ -99,7 +96,6 @@ jobs:
|
||||
./gradlew
|
||||
:adapter:inbound:web-fileserver:test --tests '*FileserverHardeningContractTest'
|
||||
:adapter:outbound:fileserver:test --tests '*PhysicalPathResolverTest'
|
||||
|
||||
--stacktrace
|
||||
|
||||
fileserver-bounded-memory:
|
||||
@@ -113,5 +109,4 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:fileserver:test --tests '*LargeFileBoundedMemoryTest'
|
||||
|
||||
--stacktrace
|
||||
|
||||
@@ -15,11 +15,13 @@ name: integration-main
|
||||
# shared. They now run on every push to main as well as nightly, which is strictly more often
|
||||
# than before.
|
||||
#
|
||||
# 2. Lanes that were registered in Gradle and invoked by nothing — the MongoDB container lanes and
|
||||
# app-bootstrap's Testcontainers `integrationTest` — existed, failed closed, and executed in no
|
||||
# workflow. A lane nobody runs is not coverage; it is a file that looks like coverage. They
|
||||
# are here rather than in stage 1 because every one of them either starts containers or re-runs
|
||||
# suites the PR gate already covers, and the pull-request budget is minutes for the whole gate.
|
||||
# 2. The container-backed lanes, run as the root category aggregates `:integrationCheck` and
|
||||
# `:performanceCheck` rather than one workflow line per lane. A lane nobody runs is not coverage;
|
||||
# it is a file that looks like coverage — and naming lanes here one by one is how fourteen of
|
||||
# them came to run nowhere (review 2026-11-01 08-01). The pull-request gate's
|
||||
# `verifyStrictLaneStages` now fails when a strict lane is in no stage a workflow executes. They
|
||||
# are here rather than in stage 1 because every one of them starts containers or real servers,
|
||||
# and the pull-request budget is minutes for the whole gate.
|
||||
#
|
||||
# What is deliberately NOT here: the web "Advanced capability" nightly lane that used to exist as
|
||||
# web-advanced-nightly.yml (websocket-advanced-nightly.yml went with the websocket Advanced code,
|
||||
@@ -78,8 +80,13 @@ jobs:
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Run the main-branch stage
|
||||
working-directory: src
|
||||
run: ./gradlew :mainCheck --warning-mode=fail --stacktrace
|
||||
# `--continue`: one failed lane (an external image that cannot be pulled, say) must not stop
|
||||
# the other main-stage gates from reporting (review 2026-11-01 08-04).
|
||||
run: ./gradlew :mainCheck --continue --warning-mode=fail --stacktrace
|
||||
|
||||
# Storability only: the `--dry-run` below plans `integrationCheck` without running a lane. The
|
||||
# lanes run in `integration-check`.
|
||||
#
|
||||
# Two questions. Can every task in the repository-wide gates be *stored* (a property of the task
|
||||
# graph, so `--dry-run` answers it for all of them in seconds)? And is a stored entry *reused* while
|
||||
# the build still executes its work (checked on the two core leaves)?
|
||||
@@ -128,63 +135,87 @@ jobs:
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Load, abuse and graceful shutdown measure behaviour that degrades gradually rather than breaking
|
||||
# outright — which is exactly the kind of regression a per-PR gate never catches.
|
||||
web-load-abuse-and-shutdown:
|
||||
# The integration stage: every integration-category strict lane (`:integrationCheck`).
|
||||
#
|
||||
# This job replaced six jobs that named lanes one by one — the MongoDB lanes, app-bootstrap's
|
||||
# Testcontainers lane, the moved messaging/object-storage/sample contracts, six of the
|
||||
# persistence-jpa PostgreSQL contracts and the httpclient fault injection. Naming lanes was how
|
||||
# eleven persistence-jpa readiness lanes ended up running nowhere: a lane added to Gradle without a
|
||||
# workflow line was declared, failed closed, and executed on no machine (review 2026-11-01 08-01).
|
||||
# The aggregate is the list now. A lane joins it by declaring `integration()`, and the root
|
||||
# `verifyStrictLaneStages` (pull-request gate) fails when a strict lane is in no stage a workflow
|
||||
# executes.
|
||||
#
|
||||
# `--continue` so that one red lane does not hide the others: every failed lane is named in the
|
||||
# same run. Lanes that need an input this job does not have (the Redis topology coordinates, the
|
||||
# protected AWS sandbox) are `explicitOnly`; the aggregate prints which ones it left out.
|
||||
# The container lanes take the build-wide `exclusiveRealServerLane` slot one at a time, so the
|
||||
# job's length is the sum of the lanes. Split the aggregate across jobs when it outgrows its
|
||||
# timeout rather than going back to naming lanes.
|
||||
#
|
||||
# Measured length (one local run of `:integrationCheck`, 2026-11-01, 37 lanes, images already
|
||||
# pulled, machine load 24): 794 s for the command, of which the lanes' test JVMs took about 624 s
|
||||
# in sum — mongoSecurityIntegrationTest 89, jpaPlatformContractTest 104, messagingCertificationTest
|
||||
# 70, mongoCompatibilityTest 69, jpaPlatformMigrationTest 66, mongoFailoverTest 59, the eleven JPA
|
||||
# readiness lanes 57 together, httpClientFailureInjectionTest 27, sample integrationTest 23,
|
||||
# messaging starter integrationTest 21, the rest under 10 each — and the remainder was compilation
|
||||
# and container start-up between lanes. A hosted runner adds cold image pulls (about 5 GB
|
||||
# uncompressed across the PostgreSQL, MongoDB, Kafka, nginx, httpbin and Toxiproxy images) and a
|
||||
# cold Gradle cache; expect 25 to 40 minutes (an estimate, not a measured hosted run). The 240-minute timeout is a ceiling for a hung container, not a budget.
|
||||
integration-check:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 60
|
||||
timeout-minutes: 240
|
||||
env:
|
||||
# Reuse would hand the failover lane a replica set another lane had already faulted.
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Run the load, abuse and shutdown lanes on every container
|
||||
- name: Run every integration-category strict lane
|
||||
working-directory: src
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:inbound:web:test
|
||||
:adapter:inbound:web:webJettyCompatTest
|
||||
|
||||
--stacktrace
|
||||
- name: Publish the test reports
|
||||
run: ./gradlew :integrationCheck --continue --stacktrace
|
||||
- name: Publish the integration lane reports
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: web-integration-reports
|
||||
path: src/adapter/inbound/web/build/reports/tests/
|
||||
name: integration-check-reports
|
||||
path: src/**/build/reports/tests/
|
||||
if-no-files-found: warn
|
||||
|
||||
# Needs a container runtime and real time (design §29). Separated from the per-PR gate rather than
|
||||
# made optional inside it: a lane that cannot run here fails, it does not skip.
|
||||
httpclient-fault-injection:
|
||||
# The performance stage: every performance-category strict lane (`:performanceCheck`) — Tomcat and
|
||||
# Jetty load, slow-client and graceful shutdown, the Hikari pool contract, the httpclient pool,
|
||||
# streaming, retry and rotation bounds, the MongoDB resource budget. They measure behaviour that
|
||||
# degrades gradually rather than breaking outright, which is the kind of regression a per-PR gate
|
||||
# never catches. This job replaced `web-load-abuse-and-shutdown`, which despite its name ran
|
||||
# `:adapter:inbound:web:test` and `webJettyCompatTest` — two lanes the pull-request and main stages
|
||||
# already run — and never the load lanes (review 2026-11-01 08-01), and `httpclient-performance`.
|
||||
performance-check:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Inject TCP faults against a real upstream
|
||||
working-directory: src
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:httpclient:httpClientFailureInjectionTest
|
||||
|
||||
--stacktrace
|
||||
|
||||
httpclient-performance:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
timeout-minutes: 120
|
||||
env:
|
||||
# A project property rather than a command-line flag, so the run command stays a plain,
|
||||
# verifiable task invocation while the machine-dependent bounds are still asserted.
|
||||
GRADLE_OPTS: -Dorg.gradle.project.performance.assertions.enabled=true
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Certify pool, streaming, retry, and rotation bounds
|
||||
- name: Run every performance-category strict lane
|
||||
working-directory: src
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:httpclient:httpClientPerformanceTest
|
||||
|
||||
--stacktrace
|
||||
run: ./gradlew :performanceCheck --continue --stacktrace
|
||||
# The optional gRPC build's performance lanes (grpcPerformanceTest). A separate build, so a
|
||||
# separate command; its own verifyStrictLaneStages counts this line (review 2026-11-03 RR-06-03).
|
||||
- name: Run every optional-platform performance-category strict lane
|
||||
if: always()
|
||||
working-directory: src
|
||||
run: ./gradlew -p optional-platforms performanceCheck --continue --stacktrace
|
||||
- name: Publish the performance lane reports
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: performance-check-reports
|
||||
path: src/**/build/reports/tests/
|
||||
if-no-files-found: warn
|
||||
|
||||
httpclient-http3-experimental:
|
||||
runs-on: ubuntu-latest
|
||||
@@ -198,123 +229,7 @@ jobs:
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Exercise the experimental HTTP/3 opt-in
|
||||
working-directory: src
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:httpclient:test
|
||||
-Phttp3.tests.enabled=true
|
||||
|
||||
--stacktrace
|
||||
|
||||
# The six Docker-backed MongoDB lanes. Until now they ran in no workflow at all: the leaf excludes
|
||||
# every one of their tags from `test` (build.gradle "Docker-backed lanes are excluded from the
|
||||
# default unit run"), `check` gains only the hermetic `mongoStableContractTest`, and the only thing
|
||||
# that named them was scripts/verify-mongodb-platform.sh, which nothing in .github invokes. Six
|
||||
# lanes that fail closed without Docker, and no machine with Docker was ever asked to run them.
|
||||
#
|
||||
# Stage 2 rather than stage 1 because each lane starts real MongoDB containers — mongo:8.0.16,
|
||||
# mongo:7.0.28 and a Toxiproxy in front of a three-node replica set. That is minutes per lane, and
|
||||
# the pull-request budget is minutes for the whole gate.
|
||||
#
|
||||
# One single-line `./gradlew <task>` step per lane, not one folded command running six, because
|
||||
# These command lines name each lane explicitly so that a lane which stops being invoked is
|
||||
# actually executed — a folded command would leave six matrix rows unverifiable. It also means a
|
||||
# red replica-set lane does not hide the compatibility lane behind it.
|
||||
mongo-container-lanes:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 90
|
||||
env:
|
||||
# Reuse would hand the failover lane a replica set another lane had already faulted.
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Single-node replica set contract lane
|
||||
working-directory: src
|
||||
run: ./gradlew :adapter:outbound:persistence-mongo:mongoReplicaSetTest --stacktrace
|
||||
- name: Run MongoDB integration lanes
|
||||
working-directory: src
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:persistence-mongo:mongoReplicaSetTest
|
||||
:adapter:outbound:persistence-mongo:mongoFailoverTest
|
||||
:adapter:outbound:persistence-mongo:mongoMigrationTest
|
||||
:adapter:outbound:persistence-mongo:mongoCompatibilityTest
|
||||
:adapter:outbound:persistence-mongo:mongoSecurityIntegrationTest
|
||||
:adapter:outbound:persistence-mongo:mongoPerformanceTest
|
||||
--stacktrace
|
||||
- name: Publish the MongoDB lane reports
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: mongo-lane-reports
|
||||
path: src/adapter/outbound/persistence-mongo/build/reports/tests/
|
||||
if-no-files-found: warn
|
||||
|
||||
# app-bootstrap's Testcontainers lane. The leaf gave it a source set of its own precisely so that
|
||||
# `./gradlew :app-bootstrap:test` would not require a Docker daemon — and the consequence nobody
|
||||
# closed is that a source set outside `test` is also outside `check`, so the real-PostgreSQL
|
||||
# outbox and idempotency contracts compiled on every build and executed on none.
|
||||
bootstrap-integration:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
env:
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Run the real-PostgreSQL integration contracts
|
||||
working-directory: src
|
||||
run: ./gradlew :app-bootstrap:integrationTest --stacktrace
|
||||
|
||||
# Container contracts moved out of the default `test` source sets must remain executed after the
|
||||
# ownership split. One step per lane keeps a failure attributable to the capability that broke.
|
||||
moved-container-contracts:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 90
|
||||
env:
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Messaging outbox, inbox and admin-journal PostgreSQL contracts
|
||||
working-directory: src
|
||||
run: ./gradlew :messaging:messaging-reliability-jdbc-postgresql:integrationTest --stacktrace
|
||||
- name: Messaging starter Kafka round trip
|
||||
working-directory: src
|
||||
run: ./gradlew :messaging:messaging-spring-boot-starter:integrationTest --stacktrace
|
||||
- name: Object storage MinIO contract
|
||||
working-directory: src
|
||||
run: ./gradlew :adapter:outbound:objectstorage:integrationTest --stacktrace
|
||||
- name: Standalone sample PostgreSQL contract
|
||||
working-directory: src
|
||||
run: ./gradlew :sample-portfolio:integrationTestLaneCheck --stacktrace
|
||||
|
||||
# These six PostgreSQL contracts moved from app-bootstrap into persistence-jpa. They are named
|
||||
# directly instead of relying on readiness-card membership: provider ownership and evidence
|
||||
# grading are different questions, and CI execution must not disappear when a card changes.
|
||||
jpa-provider-ownership-contracts:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 90
|
||||
env:
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Distributed lock contract
|
||||
working-directory: src
|
||||
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest --stacktrace
|
||||
- name: Integer lock migration compatibility
|
||||
working-directory: src
|
||||
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlIntLockMigrationCompatibilityIntegrationTest --stacktrace
|
||||
- name: Outbox transactional append
|
||||
working-directory: src
|
||||
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlOutboxAppendTransactionalIntegrationTest --stacktrace
|
||||
- name: Outbox concurrent relay
|
||||
working-directory: src
|
||||
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlOutboxConcurrentRelayIntegrationTest --stacktrace
|
||||
- name: Outbox row lifecycle
|
||||
working-directory: src
|
||||
run: ./gradlew :adapter:outbound:persistence-jpa:postgresqlOutboxRowLifecycleIntegrationTest --stacktrace
|
||||
run: ./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --stacktrace
|
||||
|
||||
# The optional gRPC platform build declares one strict INTEGRATION lane —
|
||||
# `grpc-operation-ledger-jpa:integrationTest`, which certifies the atomic
|
||||
|
||||
@@ -37,7 +37,6 @@ jobs:
|
||||
./gradlew
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformContractTest
|
||||
-Pjpa.matrix.versions=${{ matrix.postgresql }}
|
||||
|
||||
--stacktrace
|
||||
|
||||
jpa-failure-injection:
|
||||
@@ -51,7 +50,6 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformFailureTest
|
||||
|
||||
--stacktrace
|
||||
|
||||
jpa-query-plan-and-security:
|
||||
@@ -66,7 +64,6 @@ jobs:
|
||||
./gradlew
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformSecurityTest
|
||||
|
||||
--stacktrace
|
||||
|
||||
jpa-pool-pressure:
|
||||
@@ -86,5 +83,4 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest
|
||||
|
||||
--stacktrace
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
name: object-storage-qualification
|
||||
|
||||
# Only pull requests that touch object storage start the MinIO container (review BUILD-계획-B3). The
|
||||
# MinIO lanes left the object storage leaf's `check`; they run in its `mainCheck` on main and here.
|
||||
# MinIO lanes left the object storage leaf's `check`; they run in the root `integrationCheck` (main push
|
||||
# and nightly, integration-main.yml) and here.
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
|
||||
@@ -142,7 +142,6 @@ jobs:
|
||||
./gradlew
|
||||
:adapter:inbound:web:systemTest
|
||||
:adapter:inbound:web:webJettyCompatTest
|
||||
|
||||
--stacktrace
|
||||
- name: Publish the test reports
|
||||
if: always()
|
||||
@@ -165,7 +164,6 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:inbound:websocket:websocketJettyTest
|
||||
|
||||
--stacktrace
|
||||
|
||||
# Docker-gated, and the lane fails rather than skipping. Upgrade handling is the single most
|
||||
@@ -183,7 +181,6 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:inbound:websocket:websocketNginxTest
|
||||
|
||||
--stacktrace
|
||||
|
||||
# One transport per job, so a transport that stops satisfying the shared contract fails on its own
|
||||
@@ -206,7 +203,6 @@ jobs:
|
||||
./gradlew
|
||||
:adapter:outbound:httpclient:httpClientStableContractTest
|
||||
-Phttpclient.contract.transports=${{ matrix.transport }}
|
||||
|
||||
--stacktrace
|
||||
|
||||
# Only the Spring 7.0 lane. httpClientSecurityTest and spring62ApiSurfaceScan used to run here
|
||||
@@ -226,7 +222,6 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:httpclient:spring70CompatibilityTest
|
||||
|
||||
--stacktrace
|
||||
|
||||
# 16 and 18 — the ends of the Stable matrix. 17 runs in the integration stage. What this does not
|
||||
@@ -250,7 +245,6 @@ jobs:
|
||||
./gradlew
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformContractTest
|
||||
-Pjpa.matrix.versions=${{ matrix.postgresql }}
|
||||
|
||||
--stacktrace
|
||||
|
||||
jpa-migration-smoke:
|
||||
@@ -266,5 +260,4 @@ jobs:
|
||||
run: >-
|
||||
./gradlew
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformMigrationTest
|
||||
|
||||
--stacktrace
|
||||
|
||||
@@ -73,7 +73,6 @@ jobs:
|
||||
:adapter:inbound:web:systemTest
|
||||
:adapter:inbound:web:webJettyCompatTest
|
||||
:adapter:inbound:web-advanced:webAdvancedTest
|
||||
|
||||
--stacktrace
|
||||
- name: Publish the release evidence
|
||||
if: always()
|
||||
@@ -100,7 +99,6 @@ jobs:
|
||||
:adapter:inbound:websocket:websocketJettyTest
|
||||
:adapter:inbound:websocket:websocketNginxTest
|
||||
:adapter:inbound:websocket:websocketTransportQualificationTest
|
||||
|
||||
--stacktrace
|
||||
- name: Publish the release evidence
|
||||
if: always()
|
||||
@@ -122,9 +120,10 @@ jobs:
|
||||
# container and no fixed cadence — grpcNettyContractTest opens an ephemeral socket, not a broker —
|
||||
# so the guard is worth asserting once per tag and is not worth a runner every night.
|
||||
#
|
||||
# grpcPerformanceTest is deliberately absent. The leaf excludes it from `test` and says why: "a
|
||||
# measurement in the release gate is a flaky test on a shared CI runner; it runs when somebody asks
|
||||
# for it, by name." It is recorded as a manual entrypoint in the repository README instead.
|
||||
# The optional build's `releaseCheck` is those hermetic lanes, so a lane added there is here
|
||||
# without a workflow edit. grpcPerformanceTest is deliberately absent: a measurement is not release
|
||||
# evidence on a shared runner. It runs in integration-main.yml's performance-check job (the
|
||||
# optional build's `performanceCheck`).
|
||||
grpc-stable-release-gate:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
@@ -133,18 +132,23 @@ jobs:
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Run the gRPC Stable certification lanes
|
||||
working-directory: src
|
||||
run: >-
|
||||
./gradlew -p optional-platforms
|
||||
:grpc:grpc-testkit:grpcInProcessContractTest
|
||||
:grpc:grpc-testkit:grpcNettyContractTest
|
||||
:grpc:grpc-testkit:grpcFaultTest
|
||||
--stacktrace
|
||||
run: ./gradlew -p optional-platforms releaseCheck --stacktrace
|
||||
# The operation ledger's real-PostgreSQL lane ran only on main and nightly
|
||||
# (integration-main.yml), so a tag could be cut from a main whose ledger lane was red. It needs
|
||||
# Docker, which a release runner has (review 2026-11-01 03-12).
|
||||
- name: Certify the gRPC operation ledger against real PostgreSQL
|
||||
working-directory: src
|
||||
env:
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
run: ./gradlew -p optional-platforms integrationCheck --stacktrace
|
||||
- name: Publish the gRPC release evidence
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: grpc-release-evidence
|
||||
path: src/grpc/grpc-testkit/build/reports/tests/
|
||||
path: |
|
||||
src/grpc/grpc-testkit/build/reports/tests/
|
||||
src/grpc/grpc-operation-ledger-jpa/build/reports/tests/
|
||||
if-no-files-found: warn
|
||||
|
||||
# Each gate runs as its own single-line `./gradlew <task>` step so that a failure names the gate
|
||||
|
||||
@@ -65,11 +65,39 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
|
||||
`ca.architecture`가 아키텍처 검증 태스크를 소유한다. 기능별 검사(notification·mongo·messaging·
|
||||
graphql·JPA readiness 등)는 build-logic이 아니라 소유 leaf의 테스트다. 테스트가 저장소 파일을 읽으면
|
||||
그 파일을 그 leaf의 test task `inputs`로 선언한다. 저장소 문서와 대조하는 테스트는 `mainStage()`
|
||||
레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다.
|
||||
레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다. 문서가 아닌 저장소 파일(빌드 스크립트,
|
||||
workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔
|
||||
별도 레인(app-bootstrap `repository-contract`)에 둔다. 저장소 루트(`ca.repository.root`)는 이 두
|
||||
레인에만 주므로 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다.
|
||||
- strict lane 캐시: `TEST`·`ARCHITECTURE` lane은 입력이 같으면 up-to-date·build cache를 쓴다.
|
||||
`INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼
|
||||
입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을
|
||||
입력으로 선언해야 캐시가 거짓 통과를 내지 않는다.
|
||||
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(소유자 결정 4). 구현은 build-logic의
|
||||
`ca.config-contract`다. `src/build-tools/` included build는 비워서 삭제했다.
|
||||
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `releaseCheck`, `qualityCheck`,
|
||||
`configContractCheck`, `integrationCheck`)과 버전/리비전
|
||||
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
|
||||
`releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages
|
||||
--dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는
|
||||
단계(main 빌드: `ci`·`sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·
|
||||
`releaseCheck`, optional-platforms 빌드: `-p optional-platforms`로 부르는 `ci`·`integrationCheck`·
|
||||
`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈
|
||||
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
|
||||
lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·
|
||||
`-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는
|
||||
짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다.
|
||||
(1) 실패해도 단계가 실패하지 않을 수 있다: `|| exit <0 아닌 값>` 밖의 `||`(`|| true` 등), pipefail 없는
|
||||
파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤,
|
||||
`exit 0` 하는 `EXIT`·`ERR` trap 뒤, `continue-on-error`. (2) 돌지 않을 수 있다: `||` 뒤, 마지막이 아닌
|
||||
`&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나
|
||||
부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태
|
||||
함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만
|
||||
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), 세는 job이 부르지 않는
|
||||
`workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job.
|
||||
(3) 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른
|
||||
명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤,
|
||||
`bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). 실패 메시지는 명령마다 이유를
|
||||
적고 단계 명령을 혼자 한 줄로 두라고 안내한다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서
|
||||
시작해 같은 셸이 그 앞에서 확실히 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다.
|
||||
|
||||
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를
|
||||
함께 읽는다. focused test는 registry의 `gradle_path`에서
|
||||
@@ -140,6 +168,10 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
|
||||
9. endpoint는 마지막에 해당 `adapter:inbound:*` leaf에서 얇게 연결한다.
|
||||
10. focused test를 먼저 돌리고, 가능한 경우 전체 Gradle test를 돌린다.
|
||||
|
||||
단계별 판단 지점(배치·저장 포트·트랜잭션·멱등성·오류·권한)은 `docs/manual/`, 뼈대는
|
||||
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. `sample-portfolio`는 모든 계층을 한 leaf에
|
||||
두는 지울 수 있는 샘플이라 배치 예시가 아니다. 실제 기능은 계층 leaf별로 나눈다.
|
||||
|
||||
## 테스트 전략
|
||||
|
||||
계층별 테스트 기준:
|
||||
@@ -154,8 +186,8 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
|
||||
테스트 작성 규칙 (새로 쓰거나 고치는 테스트에 적용):
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
|
||||
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 언어는 영어로
|
||||
통일한다.
|
||||
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로
|
||||
쓴다(소유자 결정 5). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
|
||||
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할
|
||||
것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다.
|
||||
예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때
|
||||
@@ -186,8 +218,12 @@ cd src
|
||||
./gradlew check # 모든 leaf의 check
|
||||
./gradlew architectureCheck # 의존 방향·domain-core/shared-contract/application-* 순수성·ArchUnit
|
||||
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다)
|
||||
./gradlew testQualityCheck # 같은 분석을 테스트 source set에(config/spotbugs/exclude-test.xml, main 단계·optional 빌드는 ci)
|
||||
./gradlew ci # PR 게이트 = leaf check + architecture + quality
|
||||
./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·전송/메시징 레인·leaf 문서 대조 레인
|
||||
./gradlew mainCheck # main 단계 = env 계약·전체 기동(샘플 포함)·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
|
||||
./gradlew integrationCheck # 실제 컨테이너 integration 레인 전체(main·nightly, Docker 필요)
|
||||
./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly)
|
||||
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p optional-platforms로 따로)
|
||||
./gradlew verifyPublicPathSnapshot
|
||||
./gradlew :app-bootstrap:verifyEnvKeys
|
||||
```
|
||||
@@ -216,6 +252,9 @@ capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"):
|
||||
자체를 두지 않는다.
|
||||
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact
|
||||
constructor에서 한다.
|
||||
예외(리뷰 05-18): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
|
||||
`app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중
|
||||
하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/CLAUDE.md`.
|
||||
5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두
|
||||
통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
|
||||
6. 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
|
||||
|
||||
@@ -30,11 +30,31 @@ If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must
|
||||
and one test-lane mechanism (`strictTestLanes`). Feature-specific checks are the owning leaf's
|
||||
tests; a test that reads repository files declares them as that leaf's test `inputs`, and a test
|
||||
that compares a leaf with repository documents is a `mainStage()` lane (tag `document-contract`)
|
||||
in that leaf's `mainCheck`.
|
||||
in that leaf's `mainCheck`; a merge-blocking contract over non-document repository files is a
|
||||
pull-request lane whose inputs are exactly those files (app-bootstrap `repository-contract`).
|
||||
`TEST`/`ARCHITECTURE` lanes are cacheable; `INTEGRATION`/`SYSTEM`/`PERFORMANCE` and main-stage
|
||||
lanes rerun every time.
|
||||
- `verifyEnvKeys` stays an app-bootstrap task (owner decision 4); its implementation is build-logic's
|
||||
`ca.config-contract`. The `src/build-tools/` included build was emptied and removed.
|
||||
- `src/build.gradle`: the root lifecycle (`ci`, `mainCheck`, `releaseCheck` and the named
|
||||
repository-wide gates).
|
||||
- `src/build.gradle`: the root lifecycle (`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
|
||||
`releaseCheck` and the named repository-wide gates). `verifyStrictLaneStages --dry-run` (pull
|
||||
request; the main build and, as `-p optional-platforms`, the optional build each run their own)
|
||||
fails when a non-`explicitOnly` strict lane is in no stage a workflow executes — a lane the
|
||||
command removes with `-x` (abbreviations matched as Gradle does) is not covered; a command after
|
||||
which Gradle runs no task (`--dry-run`, `-v`, `--help`, `--status`, `--stop`, …, bundles such as
|
||||
`-qm` included), a short-option bundle Gradle rejects (`-mx`) and a command for another build do
|
||||
not count, nor does one that does not gate for one of three reasons: (1) its failure may not fail
|
||||
its step (an `||` other than `|| exit <non-zero>`, a pipe without pipefail, an `if` condition,
|
||||
after `set +e` or an `exit 0` trap, `continue-on-error`, …); (2) it may not run (inside
|
||||
`if`/`for`/`case` or a function, after a top-level or conditional `exit 0`, `exec` or `set -n`,
|
||||
under a non-status `if:`, in a workflow only a request starts or a `workflow_call` one no counted
|
||||
job calls, in a job that `needs` a conditional job, …); (3) the check does not read it although
|
||||
its failure would fail the step (`|| exit 1`, inside `{ }`, `( )`, `$( )` or `bash -c`, after a
|
||||
`cd` it cannot follow, a `shell:` other than bash or sh, a runner that may be Windows with its
|
||||
`pwsh` default, …) — the failure names each command's reason and says to put the stage command
|
||||
on a line of its own; the build a command runs is its `working-directory`, then the
|
||||
`cd <relative path>` the same shell surely ran before it, joined with `-p` — or a folded workflow
|
||||
`run:` block splits an option off its command.
|
||||
|
||||
Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes.
|
||||
|
||||
@@ -122,17 +142,22 @@ Architecture-wide commands:
|
||||
A leaf's `check` covers that leaf only — compile, its tests, Spotless, Checkstyle, Error Prone.
|
||||
Repository-wide questions have their own names: `architectureCheck` (dependency direction, purity
|
||||
of domain-core/shared-contract/application-*, Git-carryable sources, ArchUnit), `qualityCheck`
|
||||
(SpotBugs, FindSecBugs), `configContractCheck` (the environment contract), `integrationCheck` (the
|
||||
(SpotBugs, FindSecBugs over production code), `testQualityCheck` (the same over every test source
|
||||
set, against `config/spotbugs/exclude-test.xml`), `configContractCheck` (the environment contract), `integrationCheck` (the
|
||||
declared strict integration lanes; a lane that needs an input the build was not given is left out
|
||||
and named). `ci` (pull request) is leaf checks (API surfaces included, owner decision 20) +
|
||||
architectureCheck + qualityCheck; `mainCheck` (main branch) is configContractCheck +
|
||||
qualificationCheck + the sample web contract + the public-path snapshot + the transport and
|
||||
messaging qualification lanes + every leaf's `mainCheck` (document-contract lanes, MinIO lanes);
|
||||
`releaseCheck` is the tag-only checks: release provenance and the public-path snapshot.
|
||||
and named), `performanceCheck` (the declared performance lanes; main and nightly). `ci` (pull
|
||||
request) is leaf checks (API surfaces included, owner decision 20) + architectureCheck +
|
||||
qualityCheck, and the workflow also runs `verifyStrictLaneStages --dry-run`; `mainCheck` (main branch) is configContractCheck +
|
||||
qualificationCheck (which includes testQualityCheck) + the sample web contract + the sample full boot (`:sample-portfolio:systemTest`)
|
||||
+ the public-path snapshot + the transport and messaging qualification lanes + the feature
|
||||
generator round trip (`verifyFeatureScaffold`) + every leaf's `mainCheck` (document-contract lanes
|
||||
and any lane the leaf adds). `releaseCheck` is the tag-only checks: release provenance and the
|
||||
public-path snapshot.
|
||||
|
||||
Test-writing rules (behavior-sentence names that assert what they promise, given/when/then comments,
|
||||
one `// when`, one fake per port in the port owner's testFixtures, fake and adapter sharing one
|
||||
abstract contract test) are canonical in `AGENTS.md`.
|
||||
Test-writing rules (behavior-sentence names that assert what they promise, `@DisplayName` in Korean
|
||||
only when the name cannot say it (owner decision 5), given/when/then comments, one `// when`, one
|
||||
fake per port in the port owner's testFixtures, fake and adapter sharing one abstract contract test)
|
||||
are canonical in `AGENTS.md`.
|
||||
|
||||
Use public-path and env-key checks only when their surfaces changed. Full `test`, `check` or `ci`
|
||||
requires the controller's workflow authorization.
|
||||
|
||||
@@ -64,7 +64,7 @@ services:
|
||||
-Djava.rmi.server.hostname=127.0.0.1
|
||||
ports:
|
||||
- "8080:8080"
|
||||
- "9001:9001"
|
||||
- "127.0.0.1:9001:9001" # management — localhost only (07-13)
|
||||
- "127.0.0.1:9999:9999" # JMX — localhost only
|
||||
# No health check constraint in dev; let the app start at its own pace.
|
||||
healthcheck:
|
||||
|
||||
@@ -11,12 +11,26 @@
|
||||
# checks this file against them.
|
||||
# =============================================================================
|
||||
|
||||
# The local MinIO runtime, used by the server and by the object-storage smoke client below.
|
||||
#
|
||||
# It is the image the MinIO qualification lanes measured, by the same digest:
|
||||
# src/adapter/outbound/objectstorage/src/test/resources/object-storage/minio-provider-evidence.json
|
||||
# records it with the conditional-write findings, and ComposeMinioImageMatchesEvidenceTest in that
|
||||
# leaf fails when this default and the evidence disagree. Change both together.
|
||||
#
|
||||
# Source: pgsty/minio, a community fork on Docker Hub, after Docker Hub's minio/minio and quay.io
|
||||
# stopped serving MinIO images (review 05-09). cgr.dev/chainguard/minio measured the same but was
|
||||
# not chosen; the evidence file's rejectedCandidates says why. LOCAL_MINIO_IMAGE points this runtime
|
||||
# at a mirror; the lanes take OBJECT_STORAGE_MINIO_IMAGE, digest-checked.
|
||||
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
|
||||
|
||||
services:
|
||||
# ---- PostgreSQL --------------------------------------------------------------
|
||||
db:
|
||||
profiles:
|
||||
- local-jpa
|
||||
- local-messaging-outbox
|
||||
- local-fileserver
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
@@ -123,16 +137,46 @@ services:
|
||||
start_period: 30s
|
||||
|
||||
# ---- Redis — local compose contract for the shipped Redis runtime ----------------
|
||||
# Authenticated the way a deployment authenticates, with the lanes' test-fixture accounts:
|
||||
# infra/redis-sdk/acl/lane-fixture-accounts.acl, the same file the Redis topology lanes use, mounted
|
||||
# as it is rather than copied. It is not a deployment file — its passwords are public and it carries
|
||||
# a lane-only `+@all` account (infra/redis-sdk/acl/README.md). Its first line turns the passwordless
|
||||
# `default` user off, so the application connects as the named accounts the lane contract gives it
|
||||
# (compose-profile-contracts.json, $redisComment).
|
||||
#
|
||||
# This Redis was open and the lanes declared app.redis.authentication.anonymous-access-accepted.
|
||||
# The application then logged that trade, and the missing advanced account, as two startup
|
||||
# warnings — correctly, because in production both are risks — and every Redis lane failed its
|
||||
# "startup is silent" check. Quieting the warning would hide the same trade in production; the
|
||||
# lane now authenticates the way a deployment does instead.
|
||||
#
|
||||
# The passwords are the file's fixture values (infra/redis-sdk/acl/README.md); this container is
|
||||
# on the lane's internal network only and publishes no port.
|
||||
redis:
|
||||
profiles:
|
||||
- local-redis
|
||||
- all-adapters
|
||||
image: redis:7.4
|
||||
command: ["redis-server", "--appendonly", "no", "--save", ""]
|
||||
command:
|
||||
- redis-server
|
||||
- --appendonly
|
||||
- "no"
|
||||
- --save
|
||||
- ""
|
||||
- --aclfile
|
||||
- /etc/redis/acl/lane-fixture-accounts.acl
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/redis-sdk/acl
|
||||
target: /etc/redis/acl
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "redis-cli", "ping"]
|
||||
# As the application account: with `default` off, an unauthenticated PING answers NOAUTH.
|
||||
test:
|
||||
- "CMD-SHELL"
|
||||
- "[ \"$$(redis-cli --user ca-skeleton-application --pass fixture-application --no-auth-warning ping)\" = PONG ]"
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 12
|
||||
@@ -180,7 +224,7 @@ services:
|
||||
profiles:
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
image: minio/minio:RELEASE.2024-09-13T20-26-02Z
|
||||
image: *local-minio-image
|
||||
command: ["server", "/data"]
|
||||
environment:
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
@@ -204,7 +248,9 @@ services:
|
||||
profiles:
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
image: minio/mc:RELEASE.2024-09-16T17-43-14Z
|
||||
# The client from the same supplier as the server. cgr.dev/chainguard/minio-client was not used:
|
||||
# it has no shell, and the bootstrap below is a shell script.
|
||||
image: "${LOCAL_MINIO_MC_IMAGE:-pgsty/mc@sha256:ce62c9053c69ce12a527a322345b5ad9f44b5f8a7b8189f82e516f2e3f30f1d8}"
|
||||
depends_on:
|
||||
minio:
|
||||
condition: service_healthy
|
||||
@@ -286,6 +332,7 @@ services:
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- local-fileserver
|
||||
- all-adapters
|
||||
image: flyway/flyway:11.1.0
|
||||
depends_on:
|
||||
@@ -311,6 +358,18 @@ services:
|
||||
source: ./src/adapter/outbound/persistence-jpa/src/main/resources/db/migration
|
||||
target: /flyway/sql
|
||||
read_only: true
|
||||
# Each capability stream from the leaf that owns it, beside rather than inside /flyway/sql: a
|
||||
# bind mount nested in that read-only one would need its mount point created in the source
|
||||
# tree. They moved out of persistence-jpa with their capabilities, and the mount above stopped
|
||||
# reaching them — the script then refused with "no such stream".
|
||||
- type: bind
|
||||
source: ./src/adapter/outbound/persistence-notification/src/main/resources/db/migration/jpa/notification-platform
|
||||
target: /flyway/streams/notification-platform
|
||||
read_only: true
|
||||
- type: bind
|
||||
source: ./src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/fileserver
|
||||
target: /flyway/streams/fileserver
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
@@ -320,6 +379,7 @@ services:
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- local-fileserver
|
||||
- all-adapters
|
||||
image: postgres:16-alpine
|
||||
depends_on:
|
||||
@@ -415,14 +475,14 @@ services:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# The server image, not the mc client image: minio/mc ships no sed, grep or cmp, and the round-trip
|
||||
# The server image, not the mc client image: the mc image ships no sed, grep or cmp, and the round-trip
|
||||
# client needs a digest tool. See infra/minio/smoke/object-storage-smoke.sh for how that went
|
||||
# unnoticed. The lane already pulls this image for the server itself.
|
||||
object-storage-smoke:
|
||||
profiles:
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
image: minio/minio:RELEASE.2024-09-13T20-26-02Z
|
||||
image: *local-minio-image
|
||||
depends_on:
|
||||
minio-init:
|
||||
condition: service_completed_successfully
|
||||
|
||||
@@ -34,7 +34,7 @@ services:
|
||||
TZ: "UTC"
|
||||
LANG: "C.UTF-8"
|
||||
LC_ALL: "C.UTF-8"
|
||||
# fallback matches env-keys.yaml SSOT default (30s); base compose grace is 40s.
|
||||
# fallback matches env-keys.yaml SSOT default (30s); base compose grace is 60s.
|
||||
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
|
||||
APP_SERVER_SHUTDOWN: "graceful"
|
||||
# Database connection — points to the local `db` service below.
|
||||
|
||||
@@ -26,7 +26,6 @@ services:
|
||||
# generated file and injected an empty string — which the prod env validator then refused, for
|
||||
# the right reason, about a value the lane had actually supplied.
|
||||
APP_DATASOURCE_DDL_AUTO: "validate"
|
||||
APP_LOG_JSON_ENABLED: "true"
|
||||
APP_SECURITY_JWT_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
|
||||
APP_SECURITY_JWT_AUDIENCE: "ca-skeleton-api"
|
||||
networks:
|
||||
|
||||
+18
-24
@@ -9,11 +9,17 @@
|
||||
# Graceful-shutdown sync table (feature-container-runtime-contract D5):
|
||||
# App shutdown timeout : 30s (APP_SERVER_SHUTDOWN_TIMEOUT — SSOT: docs/registries/
|
||||
# env-keys.yaml, owner feature-env-driven-runtime-configuration)
|
||||
# Async executor wait : 19s (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS)
|
||||
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
|
||||
# stop_grace_period : 40s (30s app drain + 5s preStop + 5s safety margin)
|
||||
# stop_grace_period : 60s (30s app drain + 19s async + 5s preStop + 6s safety margin)
|
||||
#
|
||||
# The drain and the async wait are consecutive, not concurrent: Spring finishes the lifecycle
|
||||
# phase (the web server's graceful drain) before it destroys the executor, which then waits for
|
||||
# its queue. A 40s grace let the container be killed 9s into that wait (07-07).
|
||||
# DeveloperExperienceContractTest fails when this value is below the sum.
|
||||
#
|
||||
# Ownership: env-driven-config owns the app shutdown *value* (30s); this contract owns the
|
||||
# *relationship* (stop_grace_period >= app timeout + preStop + margin). The grace is therefore
|
||||
# *relationship* (stop_grace_period >= app timeout + async wait + preStop + margin). The grace is therefore
|
||||
# sized UP to the env-keys SSOT value (30s) — you do not shrink the app drain window to fit an
|
||||
# arbitrary grace. This resolves the earlier 20s/35s drift, which had assumed an app-timeout
|
||||
# value this branch does not own (env-keys.yaml is the SSOT and sets 30s).
|
||||
@@ -49,7 +55,10 @@ services:
|
||||
required: false
|
||||
ports:
|
||||
- "${APP_SERVER_PORT:-8080}:8080"
|
||||
- "9001:9001"
|
||||
# Management (health, info, prometheus — answered without authentication) on loopback only:
|
||||
# published on every interface it reaches the whole LAN (07-13). The smoke lanes read it from
|
||||
# inside the container, so they need no host port at all.
|
||||
- "127.0.0.1:9001:9001"
|
||||
environment:
|
||||
TZ: "UTC"
|
||||
LANG: "C.UTF-8"
|
||||
@@ -66,27 +75,17 @@ services:
|
||||
tmpfs:
|
||||
- /tmp:mode=1777,size=128m
|
||||
- /var/tmp/heap:mode=1777,size=512m
|
||||
# ---- Fileserver storage volume ------------------------------------------
|
||||
# A named volume, not a tmpfs and not the read-only root. The Fileserver platform's default
|
||||
# storage root is /var/lib/backend/files, and with a read-only root and no mount there was
|
||||
# nowhere on the image it could legally write: enabling the capability failed on its first
|
||||
# upload rather than at startup. The volume is declared unconditionally because a volume
|
||||
# nobody writes to costs nothing, while a missing one costs an outage.
|
||||
#
|
||||
# Ownership: the image runs as uid/gid 1000 (see src/Dockerfile). Docker initialises a fresh
|
||||
# named volume from the image path's ownership, so the directory is created in the image with
|
||||
# that owner; a pre-existing volume or a host bind mount must be chowned to 1000:1000 by the
|
||||
# operator, or every write is refused with a permission error the application reports as
|
||||
# STORAGE_UNAVAILABLE.
|
||||
volumes:
|
||||
- fileserver-data:/var/lib/backend/files
|
||||
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
|
||||
# mount in its own overlay file under infra/<capability>/compose/, added with -f when the
|
||||
# capability is selected, so this file never names one (07-08).
|
||||
# ---- Memory limit (D4) --------------------------------------------------
|
||||
# Must be set so -XX:MaxRAMPercentage=75 can compute a meaningful heap bound.
|
||||
mem_limit: 512m
|
||||
memswap_limit: 512m
|
||||
# ---- Graceful shutdown (D5) ---------------------------------------------
|
||||
# stop_grace_period = app drain (30s, env-keys SSOT) + preStop (5s) + margin (5s) = 40s.
|
||||
stop_grace_period: 40s
|
||||
# stop_grace_period = app drain (30s, env-keys SSOT) + async wait (19s) + preStop (5s)
|
||||
# + margin (6s) = 60s.
|
||||
stop_grace_period: 60s
|
||||
# ---- Health check -------------------------------------------------------
|
||||
# Targets the actuator readiness probe on the management port (9001).
|
||||
# The warning that used to stand here — that this probe would report UNHEALTHY until two
|
||||
@@ -106,8 +105,3 @@ services:
|
||||
start_period: 60s
|
||||
retries: 3
|
||||
restart: unless-stopped
|
||||
|
||||
volumes:
|
||||
# Survives container replacement, which is the point: published content outlives the process
|
||||
# that wrote it. Back this with real storage in any deployment that keeps files.
|
||||
fileserver-data:
|
||||
|
||||
@@ -24,6 +24,7 @@
|
||||
| --- | --- |
|
||||
| `adr/` | 아키텍처 결정 기록 |
|
||||
| `architecture/` | 공개 API 표면 스냅숏 |
|
||||
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`) |
|
||||
| `evidence/` | 작업 단계별 증거·체크포인트 |
|
||||
| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT |
|
||||
| `reviews/` | 모듈 코드 리뷰 결과 |
|
||||
|
||||
@@ -47,6 +47,80 @@ retries when everything is failing, which is the behaviour that lets a dependenc
|
||||
transaction annotations, deliberately: a `REQUIRES_NEW` would put the claim in its own transaction and
|
||||
reintroduce the window where the write is durable and the claim is not.
|
||||
|
||||
**A claim expires instead of blocking its key forever** (review 2026-11-01, 03-10). A claim still
|
||||
`IN_PROGRESS` after the claim TTL is presumed abandoned by a dead owner, and the next retry of the same
|
||||
request takes it over with `GrpcOperationLedger.reclaimStale` — one conditional
|
||||
`UPDATE … WHERE state = 'IN_PROGRESS' AND claimed_at < :cutoff`, so of two concurrent takeovers exactly
|
||||
one wins, the same shape as `reclaimFailed`. The TTL is the `claimTtl` argument of
|
||||
`GrpcIdempotencyInterceptor`, refused at construction when it is not longer than every keyed method's
|
||||
deadline. Since the 03-11 follow-up the starter assembles the interceptor when
|
||||
`app.grpc.platform.operation-ledger-enabled=true` and takes the TTL from
|
||||
`app.grpc.platform.operation-ledger-claim-ttl` (default 5m); a TTL the constructor refuses fails startup
|
||||
naming that key, and an enabled flag without a `GrpcOperationLedger` bean fails startup too.
|
||||
|
||||
The takeover is safe only because the commit is recorded in the mutation's own transaction: then a
|
||||
claim still `IN_PROGRESS` means the mutation never committed. An adopter that commits them separately
|
||||
turns an abandoned claim into an unknown outcome, and a takeover can run the mutation twice. A takeover
|
||||
of an owner that is merely slow does the same, which is why the TTL must exceed the slowest keyed
|
||||
method and not just its deadline.
|
||||
|
||||
Rejected: an owner token with a heartbeat lease (the outbox lease model) — needed only when a keyed
|
||||
method can run longer than any fixed TTL; revisit when one exists. A sweeper job that deletes stale
|
||||
rows — it needs a scheduler this family does not have, and deleting a claim makes the next retry a
|
||||
fresh claim with no record that an attempt was abandoned.
|
||||
|
||||
**A taken-over owner is fenced by a claim token** (re-review 2026-11-03, RR-02-04). The owner a
|
||||
takeover presumes dead may only be slow. Without knowing which attempt held the claim, its late
|
||||
`markFailed` turned the new attempt's claim `FAILED_TERMINAL`, the next retry re-claimed it, and two
|
||||
attempts ran the mutation at once; its late `markCommitted` committed beside the new attempt. Every
|
||||
claim now carries a `GrpcClaimToken` (`claim_attempt`, migration V003): 1 for the first claim, one more
|
||||
for each `reclaimFailed` or `reclaimStale`. `decide` returns it on `PROCEED`, and `recordCommit` /
|
||||
`recordFailure` hand it back. A commit or a failure is one conditional
|
||||
`UPDATE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt`: a commit by an attempt that lost
|
||||
the claim is refused with an exception, so its business transaction rolls back; a failure by one is
|
||||
ignored (`markFailed` returns false). The same conditional update closes the JPA commit race —
|
||||
load-check-save let two commits that both read `IN_PROGRESS` both write; now exactly one matches.
|
||||
A claim whose conflicting row is purged between insert and read retries the insert once instead of
|
||||
failing the call.
|
||||
|
||||
`release(identity, claimToken)` is fenced the same way (re-review 2026-11-03 round 2, RR-01-15): it is a
|
||||
conditional `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` and returns whether it
|
||||
deleted. It used to delete by key alone, so any caller could erase the claim of the attempt that held
|
||||
it, or a finished record a retry replays. The counter lives in the row, so a deleted row's key starts
|
||||
again at attempt 1: the token separates the attempts of one row, not attempts across a delete. Both
|
||||
deletions are limited accordingly — release only for a claim whose owner is known to be gone, purge
|
||||
only for rows finished longer ago than any retry. Rejected: dropping `release` from the port
|
||||
(`markFailed` then `reclaimFailed` keeps the counter, but a deployment that must free a key for a
|
||||
different request has no other path), and a tombstone row that keeps the counter (a second state to
|
||||
purge, for a window the two limits already close).
|
||||
|
||||
Chosen over the claim moment as the token (`WHERE claimed_at = :claimedAt`), which needs no column:
|
||||
PostgreSQL stores microseconds while `Instant` carries nanoseconds, so the token a caller holds and
|
||||
the one stored can differ by rounding, and two processes' clocks can give two attempts the same
|
||||
moment. The counter has neither problem. The heartbeat lease above stays rejected for the same reason
|
||||
as before; the token fences without one.
|
||||
|
||||
**What `operation-ledger-enabled=true` promises (03-11 (b), recorded 2026-11-03, RR-02-07).** The
|
||||
2026-11-01 review offered (a) delete the flag and judge by whether a ledger bean exists, or (b) keep the
|
||||
flag and have the starter assemble the decision function from it. (b) is kept: the assembly and the
|
||||
TTL validation live in one place instead of in every adopter. (a) was rejected because it removes the
|
||||
false promise only by removing the assembly with it. The limit stays and is stated where an operator
|
||||
meets it: the starter builds no server, so the flag assembles the decision function only, and keys are
|
||||
honoured once the adopter's `IDEMPOTENCY` stage interceptor or service adapter calls `decide` and
|
||||
`recordCommit`. `GrpcPlatformStartupValidator`'s refusal for a keyed method says exactly that; a running
|
||||
process cannot see whether the stage exists, so the validator does not claim to check it.
|
||||
|
||||
**Finished rows are purged after a retention; in-progress rows never are** (03-10 follow-up).
|
||||
`GrpcOperationLedger.purgeCompletedBefore(cutoff, limit)` deletes at most `limit` `COMMITTED` or
|
||||
`FAILED_TERMINAL` rows that completed before the cutoff, oldest first — on PostgreSQL one bounded
|
||||
`DELETE … WHERE storage_key IN (SELECT … LIMIT … FOR UPDATE SKIP LOCKED)` served by the partial index
|
||||
of migration V002. `GrpcOperationLedgerRetention.purgeExpired(now)` applies
|
||||
`app.grpc.platform.operation-ledger-retention` (default 24h, the HTTP idempotency replay TTL) in
|
||||
batches. A retry after its record was purged is a fresh claim and runs again, so the retention must
|
||||
exceed the callers' retry window. The adopter schedules the purge; the starter assembles the policy
|
||||
only, because a scheduled bean would force a scheduler onto every deployment and the starter cannot
|
||||
know which replica should run it.
|
||||
|
||||
**A key reused for a different request is a caller error, not a duplicate.** The stored request
|
||||
fingerprint turns that into `FAILED_PRECONDITION` rather than silently returning the first request's
|
||||
answer.
|
||||
|
||||
@@ -39,6 +39,16 @@ which idempotency record, business row, or outbox entry proves the write happene
|
||||
|
||||
## Enforcement
|
||||
|
||||
`JpaFailureContextTest`;
|
||||
`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsAFailureAndIsNeverRetried`
|
||||
(also the `jpa-failure` lane, i.e. release gate `completion-unknown-no-retry`).
|
||||
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`).
|
||||
|
||||
@@ -52,7 +52,6 @@ dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchTimeoutException
|
||||
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchValue
|
||||
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderFactory
|
||||
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderName
|
||||
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlDataLoaderRequestRegistry
|
||||
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyException
|
||||
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyPolicy
|
||||
dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorCategory
|
||||
@@ -75,7 +74,6 @@ dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheKey
|
||||
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCacheMetrics
|
||||
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlPreparsedCachePolicy
|
||||
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlRequestCancelledException
|
||||
dev.caskeleton.adapter.inbound.graphql.execution.GraphQlTimeoutPolicy
|
||||
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfile
|
||||
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfileClassifier
|
||||
dev.caskeleton.adapter.inbound.graphql.fetch.GraphQlFetchProfileName
|
||||
@@ -132,12 +130,14 @@ dev.caskeleton.adapter.inbound.graphql.policy.GraphQlOperationType
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlBatchLoaderRegistrar
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlCostBudgetHandler
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlDataFetcherExceptionResolver
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlDeadlineInstrumentation
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlDocumentAuthorizationHandler
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlExecutionChain
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlExecutionContext
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlExecutionHandler
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlExecutionRequest
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlOperationSelectionHandler
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPerParentFetchInstrumentation
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPlatformInstrumentation
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPlatformWebInterceptor
|
||||
dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPreparsedDocumentAdapter
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
# root yet.
|
||||
# Update only after review with:
|
||||
# ./gradlew :adapter:outbound:persistence-jpa:updateJpaApiSurface -PapproveJpaApiSurfaceChange
|
||||
# types: 166
|
||||
# types: 165
|
||||
dev.caskeleton.adapter.outbound.persistence.api.PersistenceOperationName
|
||||
dev.caskeleton.adapter.outbound.persistence.api.capability.CapabilitySupport
|
||||
dev.caskeleton.adapter.outbound.persistence.api.capability.JpaCapability
|
||||
@@ -74,7 +74,6 @@ dev.caskeleton.adapter.outbound.persistence.experimental.schema.SchemaTenantRegi
|
||||
dev.caskeleton.adapter.outbound.persistence.experimental.schema.TenantMigrationStatus
|
||||
dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantAwareRepositoryGuard
|
||||
dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantContext
|
||||
dev.caskeleton.adapter.outbound.persistence.experimental.tenant.TenantId
|
||||
dev.caskeleton.adapter.outbound.persistence.failure.PersistenceExceptionTranslator
|
||||
dev.caskeleton.adapter.outbound.persistence.failure.SqlStateErrorMapping
|
||||
dev.caskeleton.adapter.outbound.persistence.failure.StandardSqlStateErrorMapping
|
||||
|
||||
@@ -27,19 +27,19 @@ lanes and CI; it is not a deployment artifact.
|
||||
|
||||
| Capability | Enabled key (property / env, default) | IMPLEMENTED | WIRED | QUALIFIED | Evidence |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; six `postgresql*IntegrationTest` lanes, run by `integration-main.yml` → `jpa-provider-ownership-contracts`, qualify it against PostgreSQL. `sample-portfolio` selects it by its build dependency and the module's auto-configuration (no broad scan of the persistence package). `bootRunH2` adds the module to its own classpath only. |
|
||||
| Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `mongo-container-lanes` |
|
||||
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `integration-main.yml` → `integration-check` (`:integrationCheck`), qualify it against PostgreSQL. `sample-portfolio` selects it by its build dependency and the module's auto-configuration (no broad scan of the persistence package). `bootRunH2` adds the module to its own classpath only. |
|
||||
| Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
|
||||
| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge, the legacy `KafkaSender` seam and the vendored platform with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). `messaging-kafka:messagingCertificationTest` behind `verifyMessagingCertificationEvidence`, run by `messaging-certification.yml`; the starter's `integrationTest` is the live Kafka round trip. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). |
|
||||
| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. |
|
||||
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis only | One generation: the application `IdempotencyExecutor`, built once by `app-bootstrap` `IdempotencyProviderSelectionConfig` over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `sample-portfolio` cannot depend on `app-bootstrap`, so its own `SampleIdempotencyConfig` builds its one executor from the same keys. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, but no workflow runs it. The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`.. The executor stays in the composition root on purpose — it needs only application-core and its settings — while each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
|
||||
| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. |
|
||||
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap` and `sample-portfolio` both take that module with one `runtimeOnly` line, so there is no second assembly. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `integration-main.yml` → `integration-check` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
|
||||
| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxConfig`) is application composition in `app-bootstrap` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `postgresqlLegacyOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. |
|
||||
| Notification platform | `ca-skeleton.notification.platform.enabled` / `APP_NOTIFICATION_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:notification-platform')`, plus the persistence-jpa line) | claim-scoped | Not in the default composition. The one line brings the use-case assembly, `adapter:outbound:notification`, the HTTP surface `adapter:inbound:web-notification` and its own settings (`config/module-defaults/notification.yml`), each registered through the module's own `AutoConfiguration.imports`; `adapter:inbound:web` no longer depends on `application-notification`. `verifyNotificationEvidence` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; run by `notification-platform.yml`. There is no real-SMTP lane, and the matrix says so rather than implying one. |
|
||||
| File server platform | `app.fileserver-platform.enabled` / `APP_FILESERVER_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:fileserver-platform')`, plus the persistence-jpa line) | yes | On when present; module-owned `config/module-defaults/fileserver.yml` also carries the servlet multipart ceiling. `app-bootstrap:integrationTest` → `FileserverCompositionIntegrationTest` (required by the strict lane), run by `integration-main.yml` → `bootstrap-integration` |
|
||||
| Outbound HTTP client | `app.httpclient.enabled` / `APP_HTTPCLIENT_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:httpclient')`) | yes | On when present (`HttpClientPlatformActivationTest`). `httpclient:httpClientFailureInjectionTest` against a faulted upstream, run by `integration-main.yml` → `httpclient-fault-injection` |
|
||||
| File server platform | `app.fileserver-platform.enabled` / `APP_FILESERVER_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:fileserver-platform')`, plus the persistence-jpa line) | yes | On when present; module-owned `config/module-defaults/fileserver.yml` also carries the servlet multipart ceiling. `app-bootstrap:integrationTest` → `FileserverCompositionIntegrationTest` (required by the strict lane), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
|
||||
| Outbound HTTP client | `app.httpclient.enabled` / `APP_HTTPCLIENT_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:httpclient')`) | yes | On when present (`HttpClientPlatformActivationTest`). `httpclient:httpClientFailureInjectionTest` against a faulted upstream, run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
|
||||
| GraphQL transport | `backend.graphql.enabled` / `APP_GRAPHQL_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:graphql')`) | leaf-level | On when present; `false` also excludes Spring GraphQL's own auto-configuration, so no `/graphql` (`GraphQlCapabilityActivationTest`). `graphqlTransportQualificationTest` runs the HTTP boundary. The deployment-mode/runtime-profile rule is the module's own `GraphQlPlatformStartupValidator`. The default jar does not ship GraphQL, so a compose lane that exercises it runs the qualification jar. |
|
||||
| Object storage | `app.object-storage.enabled` (no `APP_*` row), `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:objectstorage')`) | MinIO only | Own `ObjectStorageAutoConfiguration` (was bound through bootstrap's properties scan); on when present, `false` leaves only the explicit legacy seam (`ObjectStorageAutoConfigurationTest`). `app-bootstrap:integrationTest` assembles it against digest-pinned MinIO. |
|
||||
| Object storage | `app.object-storage.enabled` / `APP_OBJECTSTORAGE_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:objectstorage')`) | MinIO only | Own `ObjectStorageAutoConfiguration` (was bound through bootstrap's properties scan); on when present, `false` leaves only the explicit legacy seam (`ObjectStorageAutoConfigurationTest`). `app-bootstrap:integrationTest` assembles it against digest-pinned MinIO. |
|
||||
| gRPC platform | — (build-level) | yes | **no** | yes | Absent from the main build entirely: `optional-platforms` is a separate Gradle build, so the switch is the `include`, not an environment variable. `-p optional-platforms ci` runs on every PR and `integrationCheck` certifies the operation ledger against real PostgreSQL. |
|
||||
| gRPC transport (`adapter:inbound:grpc`) | `ca-skeleton.grpc.server.enabled` (no `APP_*` row), `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:grpc')`) | leaf-level | Own `AutoConfiguration.imports` (`GrpcServerConfig`); on when present, and the loopback plaintext listener still needs `ca-skeleton.grpc.server.allow-insecure-local=true` (`GrpcSafeActivationTest`, `grpcTransportQualificationTest`). |
|
||||
| gRPC transport (`adapter:inbound:grpc`) | `app.grpc.server.enabled` / `APP_GRPC_SERVER_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:grpc')`) | leaf-level | Own `AutoConfiguration.imports` (`GrpcServerConfig`); on when present, and the loopback plaintext listener still needs `app.grpc.server.allow-insecure-local=true` (`GrpcSafeActivationTest`, `grpcTransportQualificationTest`). |
|
||||
| WebSocket transport | `app.websocket.enabled` / `APP_WEBSOCKET_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:websocket')`) | — | Own `AutoConfiguration.imports` (`WebSocketConfig`), on in a servlet app when present (`WebSocketAutoConfigurationTest`); `ConditionalTransportBuildContractTest` asserts it has no default production edge. |
|
||||
| Web Advanced library (`adapter:inbound:web-advanced`) | — (build-level; three `backend.web.advanced.*.enabled` switches inside) | yes | **no** | — | No composition root depends on it; `app-bootstrap` takes it `testRuntimeOnly` for the ArchUnit import. No real-provider lane: `webAdvancedTest` (the `web-advanced` tag, run by `release.yml` → `web-stable-release-gate`) is unit and context-runner level. The Nginx lane went with the proxy library on 2026-09-25. |
|
||||
|
||||
|
||||
@@ -7,8 +7,8 @@ While `app.fileserver-platform.enabled` is false none of these keys is bound at
|
||||
auto-configuration that binds them is not processed — so a malformed value in a block nobody
|
||||
enabled cannot fail a startup. Once enabled, binding is strict: an unknown key under the prefix is
|
||||
refused rather than ignored. The defaults are the conservative ones: the
|
||||
capability is off, the admin plane is off, background reclamation is off, and there is no permissive
|
||||
authorization fallback. Turning the capability on is a deliberate act, and so is every surface it
|
||||
admin plane is off, background reclamation is on (leaving it off is what fills the volume), copies
|
||||
and moves may only target the default namespace, and there is no permissive authorization fallback. Turning the capability on is a deliberate act, and so is every surface it
|
||||
exposes.
|
||||
|
||||
## Minimum to start
|
||||
@@ -127,7 +127,17 @@ Set `inline-safe-profile: true` only when downloads are never served inline from
|
||||
| `scope-upload-permits` | `4` | concurrent uploads one caller (principal) admits; over it is a retryable `429` |
|
||||
| `direct-download-permits` | `64` | concurrent non-delegated downloads |
|
||||
| `soft-high-water` | `0.70` | storage fraction at which pressure is reported |
|
||||
| `hard-high-water` | `0.85` | storage fraction at which uploads are refused |
|
||||
| `hard-high-water` | `0.85` | storage fraction at which uploads and copies are refused |
|
||||
| `namespace-limit` | unset (unlimited) | most bytes one namespace may hold, live reservations plus committed usage; a create, copy or move that would pass it is refused with `QUOTA_EXCEEDED` (413) before any record, byte or namespace changes |
|
||||
|
||||
`namespace-limit` is checked against the usage the quota ledger reports and then reserved, in one
|
||||
transaction but without a per-namespace lock: reservations admitted at the same moment can overshoot
|
||||
the limit by at most their own size, and the next one is refused. A service that needs an exact cap
|
||||
adds that lock in its persistence adapter.
|
||||
|
||||
A move to another namespace carries the file's bytes in the ledger: in the transaction that relocates
|
||||
the record it checks the target's limit, books the bytes as committed usage there and reclaims them
|
||||
from the source. A refused move leaves the file, and both namespaces' usage, as they were.
|
||||
|
||||
When the storage fraction cannot be read, admission treats it as unknown and does not apply the
|
||||
high-water rule — a synthetic `0` would silently disable the guard, and a synthetic `1` would take
|
||||
@@ -137,14 +147,19 @@ the capability down over a failed syscall.
|
||||
|
||||
| Key | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `enabled` | `false` | run the cleanup worker on this node |
|
||||
| `enabled` | `true` | run the cleanup worker on this node; `false` logs a startup warning |
|
||||
| `interval` | `60s` | fixed delay between batches, not fixed rate |
|
||||
| `max-items` | `100` | items one batch may claim |
|
||||
| `max-bytes` | `1GB` | bytes one batch may reclaim |
|
||||
| `retry-backoff` | `5m` | how long a failed item waits before it is due again |
|
||||
|
||||
The worker deletes physical objects, so it is off until a deployment decides otherwise. A node
|
||||
without it still queues cleanup items; another node or an operator reclaims them. An item that fails
|
||||
The worker is on by default: it deletes only what the cleanup queue names, and without it cancelled
|
||||
and expired staging, rejected and deleted content stay on the volume until the hard high-water mark
|
||||
stops every upload. A node may turn it off — for instance when another node runs it — and startup
|
||||
then logs a `WARN` naming `app.fileserver-platform.cleanup.enabled=false`. A node without it still
|
||||
queues cleanup items; another node or an operator reclaims them. (A required "reason" key was
|
||||
considered instead of the warning and rejected: it would be a setting whose only effect is to
|
||||
silence startup, carried by every non-worker node.) An item that fails
|
||||
eight times is abandoned rather than retried forever — it stays visible to an operator, parked
|
||||
rather than discarded.
|
||||
|
||||
@@ -153,6 +168,14 @@ staged bytes are queued), purges orphans the admin plane retired to quarantine,
|
||||
reconciliation over stale `UPLOADED`/`VERIFYING`/`FAILED` records, so an ambiguous publish settles
|
||||
without an operator.
|
||||
|
||||
## Copy and move targets
|
||||
|
||||
`app.fileserver-platform.target-namespaces` (`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, a comma
|
||||
list, empty by default) names the namespaces copy and move may write into besides
|
||||
`default-namespace`, which is always allowed. The target namespace of a copy or a move comes from the request body, and a namespace is also the
|
||||
quota grouping. Any other target is refused with `ACCESS_DENIED` before a byte moves or a
|
||||
reservation is taken.
|
||||
|
||||
## Management plane — `admin`
|
||||
|
||||
| Key | Default | Meaning |
|
||||
|
||||
@@ -15,7 +15,7 @@ and fails if one is missing, so this file cannot silently fall behind the code.
|
||||
| HEAD | `/v1/files/{fileId}/content` | `200`, `304` | identical headers, no body |
|
||||
| DELETE | `/v1/files/{fileId}` | `202`, `204` | logical delete first |
|
||||
| POST | `/v1/files/{fileId}:copy` | `202` | create-only target |
|
||||
| POST | `/v1/files/{fileId}:move` | `200` | logical namespace change only |
|
||||
| POST | `/v1/files/{fileId}:move` | `200` | namespace change only, bytes stay; the file's quota moves with it, and a target namespace past its `namespace-limit` is `413` |
|
||||
| OPTIONS | `/v1/uploads` | `204` | tus capability discovery |
|
||||
| POST | `/v1/uploads` | `201` | tus creation |
|
||||
| HEAD | `/v1/uploads/{uploadId}` | `204` | tus offset |
|
||||
|
||||
@@ -126,3 +126,74 @@ curl -s -X POST "$ADMIN/internal/fileserver/uploads:cleanup?maxItems=500&maxByte
|
||||
|
||||
If the deferrals are all `ACTIVE_WRITER_LEASE`, the backlog resolves itself as those uploads expire.
|
||||
Never delete staging content to clear a backlog: an upload that is mid-flight will corrupt.
|
||||
|
||||
## Namespace quota drift
|
||||
|
||||
**Signal** — a namespace's usage (`fileserver.quota` rejections, or the drift query below) disagrees
|
||||
with the bytes its files actually hold. The known cause is history: before the 2026-11 maturity
|
||||
review, `move` relocated a file without moving its quota. The bytes of every file moved before that
|
||||
fix are still booked on the namespace it left, and deleting such a file reclaims from the namespace
|
||||
it now lives in: the reclaim draws down the bookings of that namespace's other files, newest first,
|
||||
or stops at zero, and the old booking stays behind either way. A derived
|
||||
service that moved files across namespaces before taking the fix has this drift; one that never did
|
||||
should see none.
|
||||
|
||||
What the ledger must equal: quota is committed when a file is published and reclaimed when cleanup
|
||||
deletes its content, so a namespace's committed bytes are the sizes of its published files that are
|
||||
not yet `DELETED`. The query compares the two and changes nothing.
|
||||
|
||||
```sql
|
||||
WITH booked AS (
|
||||
SELECT scope_value AS namespace, sum(committed_bytes) AS booked_bytes
|
||||
FROM fs_quota_reservation
|
||||
WHERE scope_type = 'namespace' AND status = 'COMMITTED'
|
||||
GROUP BY scope_value),
|
||||
held AS (
|
||||
SELECT namespace, sum(actual_size) AS held_bytes
|
||||
FROM fs_file
|
||||
WHERE published_at IS NOT NULL AND state <> 'DELETED'
|
||||
GROUP BY namespace)
|
||||
SELECT coalesce(b.namespace, h.namespace) AS namespace,
|
||||
coalesce(b.booked_bytes, 0) AS booked_bytes,
|
||||
coalesce(h.held_bytes, 0) AS held_bytes,
|
||||
coalesce(b.booked_bytes, 0) - coalesce(h.held_bytes, 0) AS drift_bytes
|
||||
FROM booked b
|
||||
FULL JOIN held h ON h.namespace = b.namespace
|
||||
WHERE coalesce(b.booked_bytes, 0) <> coalesce(h.held_bytes, 0);
|
||||
```
|
||||
|
||||
A positive `drift_bytes` is booked capacity no file holds (the namespace a file left); a negative one
|
||||
is held content nothing booked (the namespace it arrived in). While uploads, copies, moves or
|
||||
cleanup run, a row can show a drift that only means work in flight, so judge drift with the
|
||||
fileserver's writes stopped.
|
||||
|
||||
To correct a namespace, stop every fileserver write to it first — uploads, copy, move, delete, and
|
||||
the cleanup worker (`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=false`) — because the statement below
|
||||
recomputes from `fs_file` and a publish or reclaim that lands between its two steps would be lost.
|
||||
It zeroes the namespace's committed rows and books the recomputed total as one row, shaped the way a
|
||||
publish leaves one (`COMMITTED`, `reserved_bytes` 0, the bytes in `committed_bytes`); the per-row
|
||||
split has no meaning once reclaims have drawn rows down, and enforcement only ever reads the sum.
|
||||
`RESERVED` rows (uploads in progress) are left alone.
|
||||
|
||||
```sql
|
||||
BEGIN;
|
||||
SET LOCAL lock_timeout = '5s';
|
||||
UPDATE fs_quota_reservation
|
||||
SET committed_bytes = 0, version = version + 1, updated_at = now()
|
||||
WHERE scope_type = 'namespace' AND scope_value = :'namespace'
|
||||
AND status = 'COMMITTED' AND committed_bytes > 0;
|
||||
INSERT INTO fs_quota_reservation (
|
||||
reservation_id, scope_type, scope_value, reserved_bytes, committed_bytes,
|
||||
expires_at, status, version, created_at, updated_at)
|
||||
SELECT gen_random_uuid(), 'namespace', :'namespace', 0, held,
|
||||
now(), 'COMMITTED', 0, now(), now()
|
||||
FROM (SELECT coalesce(sum(actual_size), 0) AS held
|
||||
FROM fs_file
|
||||
WHERE namespace = :'namespace'
|
||||
AND published_at IS NOT NULL AND state <> 'DELETED') AS recomputed
|
||||
WHERE held > 0;
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
Run it with `psql -v namespace=<name>`, then run the drift query again: the namespace must be gone
|
||||
from its result before writes resume.
|
||||
|
||||
@@ -61,6 +61,13 @@ fails closed rather than degrading silently.
|
||||
|
||||
## Adding a new store
|
||||
|
||||
Extend `ContentStoreContract` and pass it. A prose claim of compatibility is not accepted; the
|
||||
contract is executable precisely so a future object-storage adapter has to demonstrate the same
|
||||
offset, digest, and create-only behaviour the local store does.
|
||||
Pass two executable contracts. A prose claim of compatibility is not accepted.
|
||||
|
||||
- `UploadStoragePortContract` — the application port's contract, in `application-fileserver`
|
||||
testFixtures (`testImplementation testFixtures(project(':application-fileserver'))`). The
|
||||
application's `FakeUploadStorageGateway` extends it too, so use case tests and the real store obey
|
||||
the same offset, chunk-checksum and size-ceiling rules (a declared 0-byte upload refuses its first
|
||||
byte).
|
||||
- `ContentStoreContract` — the local adapter's internal `BlockingContentStore` SPI, in this
|
||||
adapter's tests. That SPI stays in the adapter by design (review S1-#12: the application never
|
||||
calls it), so its contract stays with it; a store that reuses the SPI extends it as well.
|
||||
|
||||
@@ -82,8 +82,6 @@ materialise a nameless client in every deployment, which the aggregate validatio
|
||||
| `max-idle-time` | `30s` | Idle eviction |
|
||||
| `max-life-time` | `5m` | Picks up DNS, load-balancer, and certificate changes |
|
||||
| `validate-after-inactivity` | `5s` | Stale and half-open detection |
|
||||
| `eviction-interval` | `15s` | Background cleanup |
|
||||
| `shutdown-timeout` | `5s` | Drain deadline before forced close |
|
||||
| `requires-route-pool` | `false` | Set when route-scoped limits are mandatory; the JDK transport then refuses the profile |
|
||||
| `requires-bounded-pending-queue` | `false` | Same, for a bounded pending queue |
|
||||
|
||||
@@ -94,14 +92,81 @@ materialise a nameless client in every deployment, which the aggregate validatio
|
||||
| `dns` | `300ms` | Hostname resolution |
|
||||
| `connect` | `500ms` | Socket connect |
|
||||
| `tls-handshake` | `1s` | TLS and ALPN |
|
||||
| `proxy-connect` | `500ms` | Proxy socket or CONNECT |
|
||||
| `request-write-idle` | `1s` | No progress writing the request |
|
||||
| `response-header` | `2s` | Until final response headers |
|
||||
| `read-idle` | `3s` | Between response chunks |
|
||||
| `total-call` | `4s` | The whole logical call, including retry backoff |
|
||||
|
||||
`total-call` must not be shorter than `connect` or `response-header`; the validator emits
|
||||
`INVALID_TIMEOUT_BUDGET` otherwise.
|
||||
`INVALID_TIMEOUT_BUDGET` otherwise. Every timeout above, and `pool.pending-acquire-timeout`, must be
|
||||
greater than zero (`TIMEOUT_NOT_POSITIVE`): both engines read zero as "wait forever".
|
||||
|
||||
`total-call` also bounds the setup of a streaming download — connect, send, and the wait for
|
||||
response headers. Once the stream is handed over, each gap of the body is bounded by `read-idle`
|
||||
instead, so a long download is not cut at an arbitrary total (design §15.3). This holds on both
|
||||
transports. The JDK transport keeps its exchange-wide timeout off a streamed body, and a per-stream
|
||||
watchdog bounds each read's wait by `read-idle`, because the JDK client has no socket read timeout.
|
||||
The watchdog wakes on one daemon thread of its own (`httpclient-jdk-read-idle`), not on the common
|
||||
`ForkJoinPool`, so a service that fills that pool with blocking work does not delay it (re-review
|
||||
2026-11-04 RR3-03-01). That thread ends 60 s after the last wake it had queued and the next stream
|
||||
starts it again; it inherits no thread-locals from the request thread that starts it and uses the
|
||||
module's class loader as its context loader, so an idle service keeps no thread and a redeployed
|
||||
application's loader is not pinned (RR4-03-04). Before review 2026-11-03 RR-04-03 every JDK download longer than
|
||||
`response-header` was cut mid-body. A body failure after hand-over is thrown from `read` as `HttpBodyReadException` — an `IOException`, as
|
||||
`InputStream` promises, so `catch (IOException)` still sees it — whose `failure()` is
|
||||
`HttpResponseTimeoutException` (a wait longer than `read-idle`) or `HttpResponseTruncatedException`
|
||||
(the connection ended early), stage `RESPONSE_BODY`, evidence `PARTIAL_RESPONSE` (re-review
|
||||
2026-11-04 RR-03-14). On the JDK transport `read-idle` bounds each read's wait, `skip` included, and
|
||||
time the caller spends between reads does not count (RR-03-12).
|
||||
|
||||
### Removed settings
|
||||
|
||||
Six keys were removed because they were bound and reached no transport (review 2026-11-01 05-15).
|
||||
Setting one now fails startup with a bind error naming the key (`The elements
|
||||
[app.httpclient.clients[0].timeout.request-write-idle] were left unbound.`), instead of being
|
||||
accepted and ignored.
|
||||
|
||||
| Removed key | Why |
|
||||
|---|---|
|
||||
| `timeout.request-write-idle` | Neither engine can bound a blocking socket write |
|
||||
| `timeout.proxy-connect`, `proxy.connect-timeout` | The TCP connect to a proxy is governed by `timeout.connect` |
|
||||
| `pool.eviction-interval` | Apache's idle evictor runs at `max-idle-time` |
|
||||
| `pool.shutdown-timeout` | A retired runtime drains for `app.httpclient.rotation-drain-timeout` |
|
||||
| `observability.operation-name-required` | An operation name is mandatory in the API; the switch could only be true |
|
||||
|
||||
### `circuit-breaker`
|
||||
|
||||
What counts as a failure is fixed: a 5xx, 408 or 429 response — whether the call throws or returns
|
||||
it as a result — and every transport failure. Every other 4xx is a healthy answer. These settings
|
||||
only say how many failures, out of how many calls, open the circuit. Defaults are Resilience4j's own,
|
||||
which every profile ran with before the keys existed.
|
||||
|
||||
Two deadlines can end an attempt in flight, and they are counted differently (review 2026-11-03
|
||||
RR-04-01):
|
||||
|
||||
| Ended by | Breaker | Why |
|
||||
|---|---|---|
|
||||
| The caller's own deadline (`HttpOperation.deadline()`, when earlier than `total-call`) | Not recorded; the permission is given back | The caller ran out of time. Counting it opened the circuit on a healthy upstream whenever callers passed short budgets |
|
||||
| The profile's `timeout.total-call` | Recorded as a failure | `total-call` is the operator's statement of how long a healthy upstream may take; a slow-drip upstream that never trips a per-gap timeout is seen only through it |
|
||||
|
||||
The first row has a blind spot (re-review 2026-11-04 RR-03-16). The attempt is let off whenever the
|
||||
caller's deadline was the earlier one and had passed when the attempt failed — the code does not ask
|
||||
whether the upstream was still answering within the profile's limits. If every caller of a profile
|
||||
passes a budget shorter than `connect` or `response-header`, an upstream that hangs (drops packets,
|
||||
never answers) ends every attempt at the caller's deadline first, so no attempt is recorded and the
|
||||
circuit never opens; every call waits out its own budget. A failure that comes before the caller's
|
||||
deadline — a refused connection — is still counted. For such a profile, set `connect` and
|
||||
`response-header` shorter than the shortest caller budget.
|
||||
|
||||
| Property | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `failure-rate-threshold` | `50` | Percent of failed calls in the window that opens the circuit, 1–100 |
|
||||
| `minimum-number-of-calls` | `100` | Calls recorded before the rate is evaluated; at most `sliding-window-size` |
|
||||
| `sliding-window-size` | `100` | The last N calls the rate is computed over (count-based) |
|
||||
| `wait-duration-in-open-state` | `60s` | How long an open circuit rejects before trial calls; positive |
|
||||
| `permitted-calls-in-half-open-state` | `10` | Trial calls while half-open; at least 1 |
|
||||
|
||||
An out-of-range value fails startup with `CIRCUIT_BREAKER_SETTING_INVALID`. The breaker belongs to
|
||||
the profile, not to a runtime generation, so a certificate rotation keeps its state.
|
||||
|
||||
### `redirect`, `request`, `response`
|
||||
|
||||
@@ -132,12 +197,12 @@ materialise a nameless client in every deployment, which the aggregate validatio
|
||||
| Property | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `policy` | `none` | Named policy for reporting |
|
||||
| `max-attempts` | `1` | Attempts, not retries |
|
||||
| `max-attempts` | `1` | Attempts, not retries; at most 5 (`RETRY_MAX_ATTEMPTS_EXCEEDED`) |
|
||||
| `base-backoff` | `50ms` | |
|
||||
| `max-backoff` | `200ms` | |
|
||||
| `jitter` | `FULL` | `NONE` \| `FULL` \| `DECORRELATED` |
|
||||
| `retry-after` | `HONOR` | `HONOR` \| `IGNORE` \| `CAP` |
|
||||
| `budget` | — | Shared token bucket name |
|
||||
| `budget` | — | Shared token bucket name. A retrying profile that names none gets its own bucket, with the same pool-derived capacity (`max-total-connections / 10`, at least 1, refilled each minute) |
|
||||
|
||||
### `tls`
|
||||
|
||||
@@ -158,9 +223,7 @@ materialise a nameless client in every deployment, which the aggregate validatio
|
||||
| `proxy.enabled` | `false` | |
|
||||
| `proxy.host` / `proxy.port` / `proxy.type` | — / `0` / `HTTP` | |
|
||||
| `proxy.credential-provider` | — | Proxy authentication is separate from target authentication |
|
||||
| `proxy.connect-timeout` | `500ms` | Recorded as its own metric |
|
||||
| `proxy.import-ambient-no-proxy` | `false` | Ambient `NO_PROXY` never widens a validated profile |
|
||||
| `observability.operation-name-required` | `true` | |
|
||||
| `observability.full-url-recording` | `false` | |
|
||||
| `observability.body-logging` | `false` | |
|
||||
|
||||
@@ -193,9 +256,18 @@ materialise a nameless client in every deployment, which the aggregate validatio
|
||||
`HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED`, `POOL_ROUTE_EXCEEDS_TOTAL`,
|
||||
`TLS_PROTOCOL_SET_REQUIRED`,
|
||||
`RETRY_POLICY_CONTRADICTS_ATTEMPTS`, `FULL_URL_RECORDING_FORBIDDEN`, `BODY_LOGGING_FORBIDDEN`,
|
||||
`DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED`, `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED`.
|
||||
`DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED`, `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED`,
|
||||
`TIMEOUT_NOT_POSITIVE`, `RETRY_MAX_ATTEMPTS_EXCEEDED`, `CIRCUIT_BREAKER_SETTING_INVALID`.
|
||||
|
||||
The last three name settings the platform binds but cannot yet honour. Neither the Apache classic
|
||||
A key that names no setting is not a violation code: the shared strict binder
|
||||
(`adapter:outbound:support` `StrictSettingsBinder`) refuses it while binding, at any depth. Spring's
|
||||
own unbound-key check stops at the first level under a list element, so `clients[0].timeout.<typo>`
|
||||
used to bind nothing and fail nothing; the binder now refuses a key under `clients[N]` or
|
||||
`dynamic-targets[N]` that bound nothing, for every capability rather than for this platform alone
|
||||
(review 2026-11-01 05-15). The platform's own guard for it, and its `HTTPCLIENT_UNKNOWN_SETTING`
|
||||
code, were removed with that change.
|
||||
|
||||
`DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED` and `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED` name settings the platform binds but cannot yet honour. Neither the Apache classic
|
||||
client nor the JDK client exposes a DNS-resolution timeout, and no proxy-credential path exists, so
|
||||
a non-default value is refused rather than accepted and ignored. Leaving the defaults alone is
|
||||
unaffected — only a deliberate, unmet request fails.
|
||||
|
||||
@@ -57,10 +57,6 @@ fields:
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_LIFE_TIME
|
||||
- field: clients[N].pool.validate-after-inactivity
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_POOL_VALIDATE_AFTER_INACTIVITY
|
||||
- field: clients[N].pool.eviction-interval
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_POOL_EVICTION_INTERVAL
|
||||
- field: clients[N].pool.shutdown-timeout
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_POOL_SHUTDOWN_TIMEOUT
|
||||
- field: clients[N].pool.requires-route-pool
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_POOL_REQUIRES_ROUTE_POOL
|
||||
- field: clients[N].pool.requires-bounded-pending-queue
|
||||
@@ -71,10 +67,6 @@ fields:
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_CONNECT
|
||||
- field: clients[N].timeout.tls-handshake
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_TLS_HANDSHAKE
|
||||
- field: clients[N].timeout.proxy-connect
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_PROXY_CONNECT
|
||||
- field: clients[N].timeout.request-write-idle
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_REQUEST_WRITE_IDLE
|
||||
- field: clients[N].timeout.response-header
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_RESPONSE_HEADER
|
||||
- field: clients[N].timeout.read-idle
|
||||
@@ -123,8 +115,6 @@ fields:
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_RETRY_RETRY_AFTER
|
||||
- field: clients[N].retry.budget
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_RETRY_BUDGET
|
||||
- field: clients[N].observability.operation-name-required
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_OBSERVABILITY_OPERATION_NAME_REQUIRED
|
||||
- field: clients[N].observability.full-url-recording
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_OBSERVABILITY_FULL_URL_RECORDING
|
||||
- field: clients[N].observability.body-logging
|
||||
@@ -153,12 +143,20 @@ fields:
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_TYPE
|
||||
- field: clients[N].proxy.credential-provider
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_CREDENTIAL_PROVIDER
|
||||
- field: clients[N].proxy.connect-timeout
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_CONNECT_TIMEOUT
|
||||
- field: clients[N].proxy.import-ambient-no-proxy
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_IMPORT_AMBIENT_NO_PROXY
|
||||
- field: clients[N].experimental-acknowledgement
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_EXPERIMENTAL_ACKNOWLEDGEMENT
|
||||
- field: clients[N].circuit-breaker.failure-rate-threshold
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_FAILURE_RATE_THRESHOLD
|
||||
- field: clients[N].circuit-breaker.minimum-number-of-calls
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_MINIMUM_NUMBER_OF_CALLS
|
||||
- field: clients[N].circuit-breaker.sliding-window-size
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_SLIDING_WINDOW_SIZE
|
||||
- field: clients[N].circuit-breaker.wait-duration-in-open-state
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_WAIT_DURATION_IN_OPEN_STATE
|
||||
- field: clients[N].circuit-breaker.permitted-calls-in-half-open-state
|
||||
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_PERMITTED_CALLS_IN_HALF_OPEN_STATE
|
||||
- field: dynamic-targets[N].name
|
||||
env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_NAME
|
||||
- field: dynamic-targets[N].allowed-schemes[M]
|
||||
|
||||
@@ -36,7 +36,7 @@ diverge, retries are absorbing failures — which is the first thing to look at
|
||||
| logical calls fine, attempts spiking | upstream degraded, retries absorbing it | `http.client.retry.count` by reason |
|
||||
| `http.client.ambiguous` non-zero | non-idempotent writes reaching `SENT_NO_RESPONSE` | reconcile with the upstream; consider an idempotency key |
|
||||
| pool pending climbing | pool too small or upstream slow | `http.client.pool.acquire.duration`, `pool.connections` |
|
||||
| circuit open | sustained upstream failure | `http.client.circuit.state`; local rejections do not open it |
|
||||
| circuit open | sustained upstream failure: transport errors, 5xx, 408, 429 | `http.client.circuit.state`; local rejections and other 4xx do not open it |
|
||||
| `http.client.ssrf.rejected` non-zero | a caller is submitting internal URLs | Dynamic Target policy and audit trail |
|
||||
|
||||
## Actuator
|
||||
@@ -111,6 +111,11 @@ evidence, replayability, stage, retryability, attempt, elapsed, remaining deadli
|
||||
| `HttpUnknownTransportException` | the engine failed in a way no category above describes; the metadata evidence, not the type, says whether it was sent | never |
|
||||
| `HttpAmbiguousExecutionException` | a non-idempotent request was sent and the outcome is unknown | never — reconcile instead |
|
||||
|
||||
A streamed body that fails after hand-over is the one place these arrive wrapped: `read` throws
|
||||
`HttpBodyReadException`, an `IOException` as `InputStream` promises, and its `failure()` is the
|
||||
`HttpResponseTimeoutException` or `HttpResponseTruncatedException` above (re-review 2026-11-04
|
||||
RR-03-14).
|
||||
|
||||
## Traces
|
||||
|
||||
```text
|
||||
|
||||
@@ -33,15 +33,20 @@ upgraded to `NOT_SENT`, because that is exactly how a timeout becomes a duplicat
|
||||
`DefaultRetryEligibilityEngine` evaluates in this order, and a later rule can never re-enable
|
||||
something an earlier one forbade:
|
||||
|
||||
1. attempts exhausted → `RetryDenied.maxAttempts()`
|
||||
2. retry budget empty → `RetryDenied.budgetExhausted()`
|
||||
3. body not replayable → `RetryDenied.bodyNotReplayable()`
|
||||
4. first byte already delivered → `RetryDenied.responseAlreadyDelivered()`
|
||||
5. runtime draining → `RetryDenied.runtimeDraining()`
|
||||
6. remaining deadline below the minimum attempt budget → `RetryDenied.deadline()`
|
||||
7. permanent failure category → `RetryDenied.permanentFailure(...)`
|
||||
8. `SENT_NO_RESPONSE` on an operation that is not safely idempotent → `AmbiguousFailure`
|
||||
9. status- and failure-specific rules
|
||||
1. `SENT_NO_RESPONSE` on an operation that is not safely idempotent → `AmbiguousFailure`
|
||||
2. attempts exhausted → `RetryDenied.maxAttempts()`
|
||||
3. retry budget empty → `RetryDenied.budgetExhausted()`
|
||||
4. body not replayable → `RetryDenied.bodyNotReplayable()`
|
||||
5. first byte already delivered → `RetryDenied.responseAlreadyDelivered()`
|
||||
6. runtime draining → `RetryDenied.runtimeDraining()`
|
||||
7. remaining deadline below the minimum attempt budget → `RetryDenied.deadline()`
|
||||
8. permanent failure category → `RetryDenied.permanentFailure(...)`
|
||||
9. `PARTIAL_RESPONSE` on an operation that is not safely idempotent → `AmbiguousFailure`
|
||||
10. status- and failure-specific rules
|
||||
|
||||
Ambiguity comes first because it describes the outcome, not whether another attempt is allowed. It
|
||||
used to sit below the attempt check, so with the default `max-attempts: 1` a POST that timed out
|
||||
after it was sent reached the caller as an ordinary timeout (review 2026-11-01 05-14).
|
||||
|
||||
## Status rules
|
||||
|
||||
@@ -50,7 +55,7 @@ something an earlier one forbade:
|
||||
| 408 | retry inside deadline and budget |
|
||||
| 425 | at most one retry, first attempt only |
|
||||
| 429 | retry inside `Retry-After`, deadline, and budget |
|
||||
| 401 | one refresh-and-replay, safe replayable operations only |
|
||||
| 401 | one refresh-and-replay, safe replayable operations only. The credential is refreshed only once the retry is granted; a 401 that will not be replayed (one attempt, no budget, no deadline) leaves the token cache alone |
|
||||
| 500 | denied unless the upstream registered it as transient **and** the operation is safely idempotent |
|
||||
| 502, 503, 504 | retry for safely idempotent operations; ambiguous otherwise |
|
||||
| other 4xx | denied |
|
||||
@@ -63,6 +68,17 @@ effect, and reporting a plain failure would tell the caller the request did not
|
||||
be false. The caller reconciles, usually by querying the upstream or replaying with an idempotency
|
||||
key.
|
||||
|
||||
### Where the evidence comes from
|
||||
|
||||
Whether a failed request was sent is read from the stage the attempt reached and the engine's
|
||||
exception type. Apache reports the moment it starts writing the request onto an established
|
||||
connection (`RequestWriteSignal`), so a failure while leasing, resolving, connecting or completing
|
||||
the TLS handshake is `NOT_SENT` even when the engine throws a generic exception. Transports that
|
||||
cannot report that moment (JDK, Jetty) are treated as writing from the moment the engine is called,
|
||||
because guessing "not sent" is what turns a timeout into a duplicate payment. An HTTP/2
|
||||
`REFUSED_STREAM` frame is proof the peer processed nothing and is kept as `NOT_SENT` through
|
||||
exception mapping.
|
||||
|
||||
## Budget and backoff
|
||||
|
||||
Retry tokens come from a per-upstream token bucket sized as a fraction of real traffic, so a failing
|
||||
|
||||
@@ -49,12 +49,65 @@ never stays in cache and write amplification grows with the table.
|
||||
|
||||
## Associations
|
||||
|
||||
- To-one associations are `LAZY`. JPA's default is `EAGER`, which means every query that loads a
|
||||
child also queries for its parent — the most common accidental N+1 in a JPA application.
|
||||
- The owning side holds the foreign key. Adding to the inverse collection alone leaves the row
|
||||
unlinked, so aggregates expose an association helper that sets both sides.
|
||||
- `CascadeType.ALL` with `orphanRemoval` is correct only for a child the aggregate genuinely owns.
|
||||
Between independent aggregates it deletes rows another part of the system still owns.
|
||||
Map each association from **one side only**. A JPA association between two entities is one foreign
|
||||
key column. A bidirectional pair (`@ManyToOne` on the child plus `@OneToMany(mappedBy = ...)` on
|
||||
the parent) stores that one column in two Java fields, and JPA writes only the owning one. The pair
|
||||
stays consistent only while every caller remembers to update both fields, and nothing fails when
|
||||
someone forgets.
|
||||
|
||||
What to use, in order of preference:
|
||||
|
||||
1. **An ID reference between aggregates.** Hold the other aggregate's identifier as a plain column
|
||||
(`UUID ownerId`). This is what every production entity in the template does today. Loading the
|
||||
other aggregate is an explicit repository call, so a cross-aggregate load is visible in the code.
|
||||
2. **A unidirectional `@ManyToOne` inside one aggregate**, always `fetch = FetchType.LAZY`. JPA's
|
||||
default for a to-one association is `EAGER`, so every query that loads a child also queries for
|
||||
its parent — the most common accidental N+1 in a JPA application.
|
||||
3. **A collection is a query, not a field.** "The children of X" is a repository method
|
||||
(`findByParentId`, or a fetch-join or projection query that pages in SQL). The query states its
|
||||
own fetch plan and page, where a mapped collection hides both.
|
||||
4. **Values the aggregate owns** — a list of tags, a set of codes — are `@ElementCollection`
|
||||
(`LAZY`), not entities.
|
||||
|
||||
A unidirectional `@OneToMany` with its own `@JoinColumn` is the exception, not the default. Use it
|
||||
only for child entities the root genuinely owns and changes only through itself (the testkit's
|
||||
`LifecycleParent` and `PagedParent` are this shape). It still costs an `UPDATE` per child when the
|
||||
join column is nullable, and the collection still loads as a unit. The child then has no
|
||||
association back to the root — not even a read-only `@ManyToOne` on the same join column
|
||||
(`insertable = false, updatable = false`): that is the bidirectional pair again, without the
|
||||
`mappedBy` that names it. If the child needs the root, it holds the root's ID.
|
||||
|
||||
`CascadeType.ALL` with `orphanRemoval` is correct only for a child the aggregate genuinely owns.
|
||||
Between independent aggregates it deletes rows another part of the system still owns — another
|
||||
reason those are ID references.
|
||||
|
||||
`JpaArchitectureRules.associationsAreMappedFromOneSideOnly()` (testkit) fails the build on every
|
||||
bidirectional pair, on `@Entity`, `@MappedSuperclass` and `@Embeddable` types: an association that
|
||||
declares `mappedBy` (only that inverse half is reported), and two entities whose associations point
|
||||
at each other without `mappedBy` (both halves are reported — the `@JoinColumn` form above, review
|
||||
RR-03-04). The message says how the pair keeps the link: one join column mapped from both ends, or
|
||||
the link stored twice — a `@OneToMany` without `@JoinColumn` in a join table beside the child's own
|
||||
`@ManyToOne` column (what a forgotten `mappedBy` produces), or two `@ManyToMany` each owning a join
|
||||
table (re-review round 3, RR3-02-05). That last check also refuses two entities that each hold their own foreign key to the
|
||||
other (`Order.@OneToOne latestInvoice` with `Invoice.@ManyToOne order`). It is not one link mapped
|
||||
twice, and the message says so; it is refused on purpose, because the two tables then reference each
|
||||
other: neither row can be inserted or deleted first, one key has to be nullable and written by a
|
||||
second `UPDATE`, and the entity graph is a cycle. Keep the association on one side and give the other
|
||||
an ID or a query (re-review round 2, RR-02-15). A class that links to itself is a pair only when a
|
||||
second member points back the other way (`@ManyToOne parent` with `@OneToMany children`); two
|
||||
`@ManyToOne` links of a class to itself (a manager and a mentor) pass, because both keys point into
|
||||
the one table and there are no two tables to order. `JpaProductionArchitectureTest` (app-bootstrap
|
||||
`architectureTest`) runs it over the production graph and `SampleArchitectureTest` over the sample.
|
||||
The failure message names the fields and these alternatives.
|
||||
|
||||
Chosen and rejected:
|
||||
|
||||
| Option | Decision | Why |
|
||||
| --- | --- | --- |
|
||||
| One side only (ID reference, unidirectional `@ManyToOne`, collection by query), enforced by ArchUnit | Chosen | The link lives in one field, so there is nothing to keep in step. The rule turns a developer-memory convention into a build failure |
|
||||
| Bidirectional with `mappedBy` and an `addChild`/`removeChild` helper that sets both sides | Rejected | The helper is the only thing keeping the two fields in step, and it must be remembered by every caller, every serializer (cycles in `toString`/JSON) and every cascade decision. A missed update leaves a row unlinked or a graph that disagrees with the database, with no error |
|
||||
| Ban `@OneToMany` entirely | Rejected for now | It also bans a root-owned child collection, which has no second field to forget. Revisit if a real need for child entities that are read or changed on their own appears — that need is a sign they are a separate aggregate |
|
||||
| Document only | Rejected | A convention the build does not check is invisible where the mapping is written, and the next copy of the template inherits whatever the examples show |
|
||||
|
||||
## Entities never leave the transaction
|
||||
|
||||
|
||||
+103
-2
@@ -12,6 +12,24 @@ Design §31-§32. Flyway owns the schema; Hibernate only validates.
|
||||
Migrating from inside the application in production means every instance of a rolling deploy races
|
||||
to apply the same script, and the loser's failure is indistinguishable from a real one.
|
||||
|
||||
Whoever runs the migration holds Flyway's PostgreSQL migration lock for the session, not in a
|
||||
transaction: `flyway.postgresql.transactional.lock=false`. Flyway's default (`true`) keeps a
|
||||
transaction open until the whole run ends, and a concurrent index build waits for every transaction
|
||||
older than itself, Flyway's own included — the deploy stops with no error and no time limit
|
||||
("Concurrent index builds" below). The template sets it for every Flyway it runs: the module
|
||||
defaults (`config/module-defaults/persistence-jpa.yml`, `spring.flyway.postgresql.transactional-lock:
|
||||
false`) for the one Spring Boot builds at startup, and `FlywaySchemaPolicy.configure()` for every
|
||||
stream it builds itself — a service's own stream starts from it too, and `JpaProductionArchitectureTest`
|
||||
refuses production code that calls `Flyway.configure()` directly. The deployment-owned migration of
|
||||
staging and prod is outside this repository: give its tool the same value
|
||||
(`FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`, or the key above in its configuration file).
|
||||
|
||||
A session lock assumes the connection Flyway takes stays its own for the whole run, which the
|
||||
template's direct Hikari connection gives. Behind a pooler in transaction mode (PgBouncer
|
||||
`pool_mode = transaction`) the unlock can reach another server connection and release nothing, and
|
||||
the next migration waits for a lock that a pooled connection still holds. Run migrations over a
|
||||
direct connection or a session-mode pool.
|
||||
|
||||
`ddl-auto` is `validate` or `none`. Never `update`: it never drops or narrows anything, so it
|
||||
produces a schema that is neither the old one nor the one the migrations describe — silently, on
|
||||
whichever instance started first.
|
||||
@@ -32,16 +50,99 @@ reason, and an approval (design §8.4).
|
||||
Only Flyway's structured error codes reach the exception. Its messages embed the script path and
|
||||
part of the failing statement.
|
||||
|
||||
## Bound the lock wait
|
||||
|
||||
A migration that locks a table already in use starts with `SET LOCAL lock_timeout = '5s';`, before
|
||||
the first statement that takes the lock. `ALTER TABLE` takes the strongest lock there is, which
|
||||
conflicts even with a plain read; a non-concurrent `CREATE INDEX` takes one that stops every write;
|
||||
`UPDATE` and `DELETE` wait on the rows other transactions hold. Unbounded, the migration waits for
|
||||
the oldest open transaction that touched the table — an operator's forgotten `BEGIN` in psql has no
|
||||
deadline — and every read and write that arrives meanwhile queues behind the migration, holding a
|
||||
pool connection while it waits. With the bound, the migration fails after five seconds, Flyway
|
||||
rolls it back whole, the database stays on the version before it and the new release does not
|
||||
start: a failed deploy instead of an outage. Deploy again when the transaction has ended.
|
||||
|
||||
`LOCAL`, because a plain `SET` outlives the migration on the pooled connection Flyway borrowed and
|
||||
changes every statement that later runs on it. The value is not zero: `lock_timeout = 0` (or
|
||||
`DEFAULT`, or a later `RESET`) is no bound at all. A migration with `executeInTransaction=false`
|
||||
cannot use it — `SET LOCAL` outside a transaction only warns — so a statement that locks a table
|
||||
goes into a migration that runs in one. A statement on a table the same migration created a moment
|
||||
earlier waits for nothing and needs no bound; `CREATE TABLE IF NOT EXISTS` does not count, because
|
||||
the table may already be there.
|
||||
|
||||
Flyway also takes a migration out of its transaction on its own, without a `.sql.conf`: on
|
||||
PostgreSQL 12 and later, any statement that starts with `VACUUM`, `CREATE [UNIQUE] INDEX
|
||||
CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX [VERBOSE] SCHEMA|DATABASE|SYSTEM`, `CREATE` or
|
||||
`DROP DATABASE|TABLESPACE|SUBSCRIPTION`, `ALTER SYSTEM` or `DISCARD ALL` (Flyway 11,
|
||||
`PostgreSQLParser`; words inside parentheses are skipped, so `VACUUM (FULL)` and `REINDEX (VERBOSE)
|
||||
SCHEMA` count). One such statement puts the whole script outside a transaction. Next to any other
|
||||
statement — a `SET LOCAL lock_timeout` included — Flyway refuses the migration at deploy under its
|
||||
default `mixed=false`; a service that sets `mixed=true` gets it run, with the bound silently gone.
|
||||
Put such a statement in a migration of its own. `REINDEX TABLE|INDEX CONCURRENTLY` is not on
|
||||
Flyway's list: Flyway runs it in the transaction, PostgreSQL refuses it there, and it needs
|
||||
`executeInTransaction=false` (below). A locking statement that cannot run in a transaction at all —
|
||||
`VACUUM FULL`, a non-concurrent `REINDEX SCHEMA|DATABASE|SYSTEM` — can never be bounded this way and
|
||||
does not belong in a migration: run it by hand as an operations step, outside a deploy, in a psql
|
||||
session that sets `SET lock_timeout = '5s';` first (the session ends with the step, so the plain
|
||||
`SET` is the bound there).
|
||||
|
||||
Enforced, not remembered: `LockWaitMigrationInspector` (persistence-jpa testkit) reads a script —
|
||||
and the `.sql.conf` beside it, as Flyway reads it (a properties file, `false` in any case), and
|
||||
otherwise the statements Flyway takes out of the transaction on its own — and names the statements
|
||||
from its list that lock an existing table with no bound in force: `ALTER TABLE`, `LOCK TABLE`, `TRUNCATE`, `DROP TABLE`; `CREATE INDEX`,
|
||||
`DROP INDEX`, `REINDEX` and `REFRESH MATERIALIZED VIEW` without `CONCURRENTLY`, `CLUSTER`, `VACUUM
|
||||
FULL`; `REFERENCES` on the table it references, in a new table as much as in an `ALTER TABLE` (a
|
||||
foreign key locks its parent against writes while it is added); `CREATE TRIGGER` and `DROP TRIGGER`
|
||||
on their table; `UPDATE` and `DELETE`. It reads text, so a statement outside the list is not
|
||||
checked. `MigrationLockWaitTest` runs it over every tree this leaf's database runs,
|
||||
`SampleMigrationLockWaitTest` over the sample's stream; a service stream copies the latter with its
|
||||
own directory. Both find the migrations the way Flyway does, decimal versions (`V22_1__`) included
|
||||
(`VersionedMigrationFiles`, testkit). The migrations released before the rule wait unbounded and
|
||||
stay that way (they are applied, and applied files are never edited); the test lists them and
|
||||
refuses any new one. `PostgreSqlMigrationLockWaitIntegrationTest`
|
||||
(`postgresqlMigrationLockWaitIntegrationTest`) shows on real PostgreSQL that a bounded migration
|
||||
gives up within the bound while another transaction holds the table, and leaves the version below
|
||||
it; it also compares the inspector's copy of Flyway's list with Flyway itself for the statements it
|
||||
lists (each is named by the inspector exactly when Flyway refuses it next to a `SET LOCAL`), and
|
||||
shows a `VACUUM FULL` run under `mixed=true` waiting out a reader despite its `SET LOCAL`. A
|
||||
statement a Flyway upgrade adds to the list is outside that comparison; `LockWaitMigrationInspectorTest`
|
||||
pins Flyway's own patterns (`PostgreSQLParser`), so such an upgrade fails the pull request's `ci`
|
||||
until the copy follows. The gRPC ledger's tree lives in the
|
||||
optional build, which cannot depend on the testkit: its `GrpcOperationLedgerMigrationLockWaitIT`
|
||||
runs every ledger migration after V001, read from the tree, against a held ledger instead, so its
|
||||
next migration is checked on real PostgreSQL. It finds and orders that tree with the testkit's own
|
||||
`VersionedMigrationFiles`, which the ledger's `build.gradle` copies into its integration-test sources
|
||||
at build time (`sharedMigrationFileSources`), so both builds read one definition. The rule came from
|
||||
V21 having the bound and V22, in the same commit, not having it (re-review 2026-11-03 round 2,
|
||||
RR-02-09; round 3, RR3-02-01, RR3-02-03, RR3-02-04; round 4, RR4-02-01; round 6, RR6-03-02,
|
||||
RR6-03-03).
|
||||
|
||||
## Concurrent index builds
|
||||
|
||||
`CREATE INDEX CONCURRENTLY` cannot run inside a transaction block, and Flyway wraps migrations in
|
||||
one by default. The migration therefore needs a companion configuration:
|
||||
`CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY` and `REINDEX … CONCURRENTLY` cannot run
|
||||
inside a transaction block. Flyway recognizes `CREATE`/`DROP INDEX CONCURRENTLY` and runs such a
|
||||
script outside a transaction on its own (above), but not `REINDEX … CONCURRENTLY`, which it runs in
|
||||
the transaction for PostgreSQL to refuse. Write the companion configuration for every concurrent
|
||||
statement anyway, so the file says what it needs and no reader has to know Flyway's list:
|
||||
|
||||
```conf
|
||||
# V42__order_index.sql.conf
|
||||
executeInTransaction=false
|
||||
```
|
||||
|
||||
Outside a transaction, `CREATE INDEX CONCURRENTLY` and `REINDEX … CONCURRENTLY` still wait until
|
||||
every transaction older than them has ended. Under Flyway's default lock that includes the
|
||||
transaction Flyway itself keeps open, and Flyway waits for the build in turn: the deploy never ends,
|
||||
and the table's other DDL and autovacuum queue behind the build meanwhile. The template's Flyway
|
||||
holds its lock for the session instead ("Who may change the schema"), so the build waits only for
|
||||
other transactions; a deployment tool left on Flyway's default stops on the first such migration.
|
||||
`DROP INDEX CONCURRENTLY` does not wait that way. `PostgreSqlConcurrentIndexMigrationIntegrationTest`
|
||||
(`postgresqlConcurrentIndexMigrationIntegrationTest`) applies both builds as a second deploy, with
|
||||
the Flyway Spring Boot builds from the module defaults and with `FlywaySchemaPolicy.configure()`,
|
||||
on real PostgreSQL. The other transactions still count: a long one an operator or a report keeps
|
||||
open holds the build, and a file run outside a transaction cannot bound that wait with `SET LOCAL`.
|
||||
Look for old transactions (`pg_stat_activity.xact_start`) before deploying one.
|
||||
|
||||
The testkit's `ConcurrentIndexMigrationInspector` checks a script for this in a migration test
|
||||
(nothing checks it at startup), and additionally requires the migration to contain nothing else. A failed concurrent build leaves an invalid index behind;
|
||||
recovering is a single `DROP INDEX` when the migration did nothing else, and a manual reconstruction
|
||||
|
||||
@@ -7,7 +7,18 @@ Design §15-§20. What owns a transaction, what may be retried, and what must ne
|
||||
Repository adapters do not open transactions. The use case does, through `TransactionPort`,
|
||||
because the unit of work is a business decision and only the use case knows where it starts and
|
||||
ends. `SpringTransaction` is the only implementation: one pre-built `TransactionTemplate` per
|
||||
mode over Spring's `PlatformTransactionManager`, every mode pinned to `READ_COMMITTED`.
|
||||
mode over Spring's `PlatformTransactionManager`, every mode running at `READ_COMMITTED` and
|
||||
bounded in time.
|
||||
|
||||
- **Isolation** is pinned on the pool, not per transaction: the module defaults set
|
||||
`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED` and
|
||||
`HikariPoolConstraintValidator` refuses any other level. A template that names the level makes
|
||||
pgjdbc ask the server for it (`SHOW TRANSACTION ISOLATION LEVEL`) at every begin.
|
||||
- **Time bound**: `app.persistence-jpa.transaction.write-timeout` (`inWrite`, `inRootWrite`) and
|
||||
`read-timeout` (`inRead`), 30 s each by default; `inNew` is fixed at 30 s. Spring hands the
|
||||
remaining time to each statement, so the server cancels a slow statement or lock wait
|
||||
(`DB_QUERY_CANCELED`) and the connection returns to the pool. A unit of work that needs longer
|
||||
is usually a batch job that should be split, not a reason to raise the bound.
|
||||
|
||||
| Call | Propagation | When |
|
||||
|---|---|---|
|
||||
@@ -29,7 +40,8 @@ maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1
|
||||
## Nothing is retried by the port
|
||||
|
||||
`SpringTransaction` runs the action once. A failure rolls back and propagates, translated to
|
||||
the shared persistence error codes where the SQLSTATE is known. A caller that decides to retry must
|
||||
the shared persistence error codes where the SQLSTATE is known; a lost `@Version` race has no
|
||||
SQLSTATE and is reported as `DB_OPTIMISTIC_CONFLICT` (409). A caller that decides to retry must
|
||||
re-run the whole use case in a new transaction — never re-issue one statement — because an
|
||||
optimistic conflict or a serialization failure means the state the attempt computed against is no
|
||||
longer the committed state.
|
||||
@@ -45,7 +57,7 @@ A connection can break while a commit is in flight; the server may have committe
|
||||
acknowledgement was lost. `TransactionCompletionUnknownException` is never retried, and the type
|
||||
system enforces it: `JpaFailureContext` refuses to represent a retryable completion-unknown failure.
|
||||
The port itself retries nothing, so such a commit surfaces to the caller as a failure exactly once
|
||||
(`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsAFailureAndIsNeverRetried`).
|
||||
(`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried`).
|
||||
|
||||
Recovery is reconciliation, not retry:
|
||||
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
# 01. 생성 명령 — 새 기능 뼈대
|
||||
|
||||
## 핵심
|
||||
|
||||
`scripts/new-feature.sh <FeatureName>` 한 번으로 새 업무 기능의 뼈대가 계층 leaf 다섯 곳에 생긴다.
|
||||
만든 직후 그대로 PR 게이트(`ci`의 해당 leaf check)와 `architectureCheck`를 통과한다. 이 성질은
|
||||
`scripts/verify-feature-scaffold.sh`가 main 단계(`mainCheck`)에서 매번 확인한다.
|
||||
|
||||
```text
|
||||
scripts/new-feature.sh Invoice
|
||||
-> domain-core Invoice, InvoiceId, InvoiceIdFactory, InvoiceRepository, InvoiceInvariantException
|
||||
+ testFixtures: InMemoryInvoiceRepository, SequentialInvoiceIdFactory, InvoiceRepositoryContract
|
||||
-> application-core CreateInvoiceUseCase, GetInvoiceUseCase, command·query·view, InvoiceErrorCode, 예외 2개
|
||||
-> outbound:identifier UuidInvoiceIdFactory
|
||||
-> inbound:web InvoiceController (POST /invoices, GET /invoices/{id}), 요청·응답 DTO
|
||||
-> app-bootstrap InvoiceConfig + AutoConfiguration.imports 한 줄
|
||||
-> 각 leaf 테스트 불변식, id 문법, 유스케이스, 공유 계약, HTTP 계약, 조립 조건
|
||||
-> spotlessApply (이름 길이에 따라 Javadoc 줄바꿈이 달라져서)
|
||||
```
|
||||
|
||||
## 사용법
|
||||
|
||||
```bash
|
||||
scripts/new-feature.sh Invoice # /invoices, 권한 invoice:create
|
||||
scripts/new-feature.sh PurchaseOrder # /purchaseOrders, 권한 purchase-order:create
|
||||
scripts/new-feature.sh Person --path people # 복수형이 규칙대로 안 될 때
|
||||
scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에 spotlessApply 직접)
|
||||
```
|
||||
|
||||
| 입력 | 규칙 | 어디서 막나 |
|
||||
| --- | --- | --- |
|
||||
| 이름 | PascalCase, 영숫자 | 스크립트 |
|
||||
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
|
||||
| HTTP 경로 | lowerCamel 복수형. AIP-122 모양 | 스크립트, `ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122` |
|
||||
| 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 |
|
||||
|
||||
생성 뒤 확인:
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :domain-core:check :application-core:check :adapter:outbound:identifier:check \
|
||||
:adapter:inbound:web:check :app-bootstrap:check architectureCheck --console=plain
|
||||
```
|
||||
|
||||
## 만드는 것과 만들지 않는 것
|
||||
|
||||
| 만든다 | 만들지 않는다 | 이유 |
|
||||
| --- | --- | --- |
|
||||
| 도메인 모델·포트·불변식, 유스케이스 두 개(쓰기·읽기), id adapter, 컨트롤러, 조립, 테스트 | **저장 adapter**(JPA 엔티티·Spring Data·마이그레이션) | 저장소 종류(JPA/Mongo), 마이그레이션 위치·번호대, 실 DB 계약 lane은 서비스가 정한다(04장). 템플릿이 정하면 upstream과 병합 충돌이 나는 자리다 |
|
||||
| 권한 선언 `@RequiresPermission("<f>:create")` | 역할 → 권한 매핑 | 어떤 역할이 쓸 수 있는지는 서비스의 결정이다(07장). 매핑 전에는 쓰기가 모두 403 — 안전한 쪽 |
|
||||
| `<F>ErrorCode` enum | `docs/registries/error-codes.yaml` 행 | 그 registry는 템플릿 운영 코드 전용이다. 서비스 코드는 서비스 registry에(06장) |
|
||||
| 읽기 유스케이스 | 목록·수정·삭제 | 목록은 페이지·정렬·N+1 판단이, 수정은 동시성(버전) 판단이 필요하다(04장) |
|
||||
|
||||
저장 adapter가 없으면 `<F>Config`의 `@ConditionalOnBean(<F>Repository)`가 꺼져 있어 엔드포인트가
|
||||
**없다**. 반쯤 켜진 상태(엔드포인트는 있는데 저장이 안 됨)가 생기지 않는다.
|
||||
|
||||
생성 결과는 placeholder 필드 `name` 하나를 가진다. 기능의 실제 상태로 바꾸는 것이 첫 작업이다.
|
||||
|
||||
## 왕복 검사
|
||||
|
||||
```text
|
||||
verify-feature-scaffold.sh
|
||||
-> 작업 트리를 임시 디렉터리로 복사(추적 + 무시되지 않은 새 파일), git init
|
||||
-> new-feature.sh Operation / Notification / Common (템플릿 패키지 이름: 거절되고 아무것도 안 씀)
|
||||
-> new-feature.sh Invoice, new-feature.sh PurchaseOrder (한 단어 / 여러 단어)
|
||||
-> 생성 파일이 있는지 확인
|
||||
-> ./gradlew 5 leaf check + architectureCheck
|
||||
-> 각 leaf 테스트 결과에 생성된 테스트 클래스가 실행·통과로 남았는지 확인
|
||||
-> 임시 디렉터리 삭제
|
||||
```
|
||||
|
||||
- 루트 태스크 `verifyFeatureScaffold`(`src/build.gradle`)가 이 스크립트를 부르고 `mainCheck`에 들어
|
||||
있다. 중첩 Gradle 빌드라 PR 단계가 아니라 main 단계다.
|
||||
- 템플릿이나 템플릿이 기대는 규칙(ArchUnit, Error Prone, 포맷)이 바뀌어 생성물이 깨지면 여기서 빨강이 된다.
|
||||
- 생성된 테스트가 실행되지 않고 지나가는 일(빈 녹색)을 막으려고 결과 XML을 확인한다.
|
||||
|
||||
## 고른 형태와 버린 대안
|
||||
|
||||
| 형태 | 결정 | 이유 |
|
||||
| --- | --- | --- |
|
||||
| `scripts/`의 bash + 텍스트 템플릿(`scripts/feature-scaffold/templates/**/*.tmpl`) | **채택** | 개발자 도구는 `scripts/`에 둔다는 repo 관례(`ca.developer-bootstrap` 플러그인을 지우고 `scripts/bootstrap-local.sh`로 옮긴 것, `src/build-logic/README.md`). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다 |
|
||||
| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`CLAUDE.md` Gradle policy). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 |
|
||||
| 생성 대신 예시 기능을 커밋해 두고 복사 | 버림 | 복사본이 하나 더 생겨 규칙과 갈라진다. 이름 바꾸기를 사람이 손으로 한다 |
|
||||
| 왕복 검사를 JUnit 안에서 javac로 컴파일 | 버림 | Spotless·Error Prone·ArchUnit 전체를 다시 구현해야 하고, 실제 게이트와 다른 것을 검사하게 된다. 실제 Gradle 게이트를 그대로 돌리는 쪽을 골랐다 |
|
||||
| 생성 뒤 자동 `spotlessApply` | 채택(끄려면 `--no-format`) | google-java-format이 Javadoc을 이름 길이에 따라 다시 접는다. 템플릿만으로는 모든 이름에서 포맷 검사를 통과시킬 수 없다 |
|
||||
|
||||
## 생성 결과가 기대는 빌드 설정
|
||||
|
||||
생성물이 컴파일되려고 다음 의존이 미리 들어 있다(모두 registry가 허용한 edge).
|
||||
|
||||
| 파일 | 설정 | 왜 |
|
||||
| --- | --- | --- |
|
||||
| `src/domain-core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(AGENTS.md 테스트 규칙 6) |
|
||||
| `src/application-core/build.gradle`, `src/adapter/inbound/web/build.gradle`, `src/app-bootstrap/build.gradle` | `testImplementation testFixtures(project(':domain-core'))` | 유스케이스·HTTP·조립 테스트가 그 fake를 쓴다 |
|
||||
| `src/adapter/inbound/web/build.gradle` | `implementation project(':domain-core')` | 컨트롤러가 경로 문자열을 도메인 id로 바꾼다 |
|
||||
| `src/adapter/outbound/identifier/build.gradle` | `implementation project(':domain-core')` | id adapter가 도메인 `IdFactory` 포트를 구현한다 |
|
||||
@@ -0,0 +1,143 @@
|
||||
# 02. 새 도메인·유스케이스 추가
|
||||
|
||||
## 핵심
|
||||
|
||||
안쪽 계층부터 바깥으로 만든다. 각 단계는 그 단계의 테스트까지 끝내고 다음으로 간다.
|
||||
생성 명령(01장)이 1~5단계의 뼈대를 만들고, 이 장은 각 단계에서 사람이 정할 것을 적는다.
|
||||
|
||||
```text
|
||||
1 domain-core ─▶ 2 application-core ─▶ 3 outbound adapter ─▶ 4 inbound adapter ─▶ 5 app-bootstrap
|
||||
모델·불변식 유스케이스·포트 저장·외부 연동 전송·DTO·오류 bean·조건·권한
|
||||
(Java만) (Java + 계약 타입) (Spring·JPA 등) (HTTP 등) (조립)
|
||||
```
|
||||
|
||||
바깥 계층은 안쪽을 알지만 안쪽은 바깥을 모른다. 그래서 안쪽부터 만들면 각 단계가 앞 단계만 보고
|
||||
컴파일된다. 한 단계가 다른 leaf나 계층을 고쳐야 하면 거기서 멈추고 설계를 다시 본다(`CLAUDE.md`
|
||||
Layer workflow).
|
||||
|
||||
## 0단계 — 배치를 정한다
|
||||
|
||||
먼저 03장으로 이 기능을 어디 둘지 정한다. 기본은 계층 leaf 안 `<feature>` 패키지다. 생성 명령은 이
|
||||
기본값만 만든다.
|
||||
|
||||
## 1단계 — domain-core: 모델과 불변식
|
||||
|
||||
만드는 것: aggregate(`@AggregateRoot`), id(`@ValueObject` record, `ResourceId`), id 생성 포트
|
||||
(`IdFactory` 상속), 저장 포트(`*Repository`), 불변식 예외(`Reason` enum).
|
||||
예: 생성 결과 `src/domain-core/src/main/java/dev/caskeleton/domain/<f>/`.
|
||||
|
||||
검사: `DomainPurityArchitectureTest`(Spring·JPA·전송 타입 금지, setter 비공개, 감사 필드 금지),
|
||||
`ForbiddenApiArchitectureTest.NO_LONG_ID_PK`.
|
||||
|
||||
### 판단: id를 누가 만드나
|
||||
|
||||
- **고르는 기준**: 클라이언트가 같은 요청을 다시 보낼 때 같은 리소스를 가리켜야 하는가.
|
||||
- **기본값**: 서버가 만든다. domain `XIdFactory extends IdFactory<XId>` + `adapter:outbound:identifier`
|
||||
구현. 문법은 id 값 객체 생성자에서 검사한다.
|
||||
- **예외**: 클라이언트가 자연 키(주문번호 등)를 주는 기능은 그 키를 id로 쓴다. 이때 중복은 DB 유일성
|
||||
제약이 막는다(04장). UUIDv7이 필요하면 `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/outbound/identifier/UuidWorkLogIdFactory.java`처럼 바꾼다.
|
||||
|
||||
### 판단: 불변식을 어디 두나
|
||||
|
||||
- **고르는 기준**: 규칙이 aggregate 하나의 상태만 보고 판정되는가.
|
||||
- **기본값**: aggregate 메서드·팩토리 안. 위반은 `XInvariantException(Reason)`.
|
||||
- **예외**: 둘 이상의 aggregate나 저장된 다른 행을 봐야 하는 규칙(중복 금지 등)은 유스케이스 + DB 제약.
|
||||
조회 후 insert만으로는 동시 요청에서 깨진다(04장).
|
||||
|
||||
### 판단: 저장 포트를 누가 소유하나
|
||||
|
||||
- **고르는 기준**: 포트가 aggregate 단위로 말하는가, 기술적 저장·조회인가.
|
||||
- **기본값**: aggregate를 통째로 저장·로드하면 domain 소유 `XRepository`.
|
||||
- **예외**: 읽기 모양이 aggregate와 다르면 application 소유 `XQueryPort` + projection(record).
|
||||
`QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 반환 타입을 검사한다. lease·claim 같은 기술
|
||||
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/CLAUDE.md`.
|
||||
|
||||
## 2단계 — application-core: 유스케이스와 포트
|
||||
|
||||
만드는 것: command/query record, 유스케이스(쓰기 `CommandUseCase`, 읽기 `QueryUseCase`), 반환용 view
|
||||
record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/main/java/dev/caskeleton/application/<f>/`.
|
||||
|
||||
필수 선언(ArchUnit이 강제, `ApplicationBoundaryArchitectureTest`):
|
||||
|
||||
- 모든 유스케이스에 `@UseCaseCapability(transactionMode, idempotency, repositoryAccess)`. 선언과
|
||||
실제 `TransactionPort` 호출이 맞아야 한다(`USE_CASE_CAPABILITY_MATCHES_TRANSACTION_PORT_BOUNDARY`).
|
||||
- 쓰기 유스케이스에 `@RequiresPermission("<resource>:<action>")`(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`).
|
||||
- 유스케이스 클래스는 `final`이 아니다. 권한 프록시가 하위 클래스를 만든다
|
||||
(`src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java`).
|
||||
|
||||
### 판단: 트랜잭션 모양
|
||||
|
||||
- **고르는 기준**: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가.
|
||||
- **기본값**: 쓰기 `tx.inWrite`, 읽기 `tx.inRead`.
|
||||
- **예외**: 커밋 확인 뒤 결과를 노출해야 하면 `inRootWrite`(바깥 트랜잭션이 있으면 거부). 감사·보상만
|
||||
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/CLAUDE.md`
|
||||
「Allowed transactional shapes」.
|
||||
|
||||
### 판단: 무엇을 반환하나
|
||||
|
||||
- **기본값**: application view record(`XView`). 전송 계층이 aggregate를 받지 않는다
|
||||
(`TypeBoundaryArchitectureTest.CONTROLLERS_DO_NOT_RETURN_DOMAIN_OR_ENTITY_TYPES`).
|
||||
- **예외**: 같은 leaf 안 다른 유스케이스가 aggregate를 이어 받아야 하면 aggregate를 반환해도 된다.
|
||||
컨트롤러는 그때도 응답 DTO로 바꾼다.
|
||||
|
||||
### 판단: 멱등성 선언
|
||||
|
||||
05장. 기본값 `NOT_IDEMPOTENT`(쓰기), `IDEMPOTENT`(읽기). 클라이언트가 재전송할 수 있는 결제·주문류
|
||||
쓰기는 `KEYED`.
|
||||
|
||||
## 3단계 — outbound adapter
|
||||
|
||||
만드는 것: 포트 구현. 생성 명령은 id adapter(`adapter:outbound:identifier/<f>/Uuid<F>IdFactory`)만
|
||||
만든다. 저장 adapter는 04장 순서로 직접 만든다.
|
||||
|
||||
필수: adapter는 포트 소유자 testFixtures의 `XRepositoryContract`를 실제 저장소로 상속하는 테스트를
|
||||
가진다(08장). 실 DB가 필요하면 strict lane(`integrationTest` 등)에 둔다.
|
||||
|
||||
## 4단계 — inbound adapter (HTTP)
|
||||
|
||||
만드는 것: 컨트롤러, 요청·응답 DTO. 예: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/<f>/`.
|
||||
|
||||
- 컨트롤러는 변환만 한다: 요청 → command/query → 유스케이스 → `Envelope.ok(응답 DTO, ResponseMetaFactory.fromMdc())`.
|
||||
repository·엔티티 직접 사용 금지(`CONTROLLERS_DO_NOT_ACCESS_REPOSITORIES_OR_JPA_ENTITIES`).
|
||||
- 생성 201은 `Location` 헤더를 준다. 비동기 수락은 202(`DurableOperationController`).
|
||||
- 경로는 lowerCamel 복수형(AIP-122).
|
||||
- 실패는 던지기만 한다. `ApiErrorCarrier`를 전역 핸들러가 매핑한다(06장). 기능 전용 핸들러를 만들지 않는다.
|
||||
|
||||
### 판단: 입력 검증을 어디서 하나
|
||||
|
||||
- **고르는 기준**: 규칙이 도메인 규칙인가, wire 모양(형식·필수 키)인가.
|
||||
- **기본값**: 도메인 규칙은 aggregate가 한 번만 검사한다. DTO에 같은 규칙을 bean validation으로 또 쓰지
|
||||
않는다(두 벌이 갈라진다).
|
||||
- **예외**: 도메인이 볼 수 없는 wire 모양 — 크기 상한, 형식 패턴, 필수 키 — 은 DTO에
|
||||
`@NotNull`·`@Size`·`@Pattern`으로 둔다(`SubmitOperationHttpRequest`). 이것은 400 `VALIDATION_FAILED`로 나간다.
|
||||
|
||||
## 5단계 — app-bootstrap 조립
|
||||
|
||||
만드는 것: `@AutoConfiguration` 클래스 하나 + `AutoConfiguration.imports` 한 줄.
|
||||
예: `src/composition/durable-operation/src/main/java/dev/caskeleton/composition/operation/DurableOperationAutoConfiguration.java`.
|
||||
|
||||
- `@ConditionalOnBean(필요한 포트들)`: 포트 구현이 없으면 기능 전체가 없다.
|
||||
- 유스케이스는 `@Bean`으로 만든다. 직접 `new` 하면 권한 프록시가 없어 `@RequiresPermission`이 조용히
|
||||
빠진다.
|
||||
- 컨트롤러는 component scan이 아니라 `@Import`로 등록한다. scan은 `dev.caskeleton.bootstrap`만 본다
|
||||
(`CaSkeletonApplication`).
|
||||
- 포트 구현이 다른 자동 설정에서 오면 `afterName`으로 순서를 적는다. 안 적으면 조건이 그 bean을 못 본다.
|
||||
- 이벤트를 내면 계약 contribution도 `@Bean`으로 등록한다(09장).
|
||||
- 역할 → 권한 매핑을 `app.authz.role-permissions`에 더한다(07장).
|
||||
|
||||
## 6단계 — 공개 계약이 바뀌었으면 함께 고친다
|
||||
|
||||
| 바뀐 것 | 같이 할 것 |
|
||||
| --- | --- |
|
||||
| 새 공개 경로(인증 없이 열림) | `docs/security/public-paths-snapshot.txt`, `./gradlew verifyPublicPathSnapshot` |
|
||||
| 새 env 키 | `docs/registries/env-keys.yaml`, `./gradlew :app-bootstrap:verifyEnvKeys` |
|
||||
| 새 의존성 | lockfile 갱신(`./gradlew :<leaf>:resolveAndLockAll --write-locks`), `verifyDependencyLocks` |
|
||||
| 새 마이그레이션 | 04장 번호 규칙 |
|
||||
| 새 이벤트 계약 | 09장 |
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 안쪽부터: domain → application → outbound → inbound → bootstrap.
|
||||
- 쓰기 유스케이스는 non-final + `@RequiresPermission` + bean. 셋 중 하나라도 빠지면 권한 검사가 없다.
|
||||
- 조립은 포트가 있을 때만 켜진다. 저장 adapter가 생기기 전 기능은 없는 상태다.
|
||||
- 같은 규칙을 두 곳에 쓰지 않는다. 도메인 규칙은 aggregate, wire 모양은 DTO.
|
||||
@@ -0,0 +1,76 @@
|
||||
# 03. 새 기능을 둘 곳 고르기
|
||||
|
||||
## 핵심
|
||||
|
||||
새 기능을 두는 모양은 셋이다. **업무 기능의 기본은 ① 계층 leaf 안 `<feature>` 패키지**다.
|
||||
선택해서 켜고 끄는 플랫폼 기능만 ② 별도 `application-*` leaf로 만든다. ③ 한 leaf 수직 슬라이스는
|
||||
지울 수 있는 샘플 전용이다. 생성 명령은 ①만 만든다.
|
||||
|
||||
```text
|
||||
① 계층 leaf 안 패키지 (기본)
|
||||
domain-core/.../domain/<f> -> application-core/.../application/<f> -> adapter:*/.../<f> -> app-bootstrap/.../autoconfigure/<f>
|
||||
|
||||
② 기능 전용 leaf (capability)
|
||||
application-<f> -> persistence-<f>, adapter:outbound:<f>, adapter:inbound:web-<f> -> composition:<f>-platform
|
||||
app-bootstrap/build.gradle 에 runtimeOnly 한 줄
|
||||
|
||||
③ 한 leaf 수직 슬라이스 (샘플 전용)
|
||||
sample-portfolio = domain + application + adapter + bootstrap 패키지
|
||||
```
|
||||
|
||||
## 기준표
|
||||
|
||||
| 질문 | ① 계층 leaf 패키지 | ② 기능 leaf | ③ 수직 슬라이스 |
|
||||
| --- | --- | --- | --- |
|
||||
| 서비스마다 켜고 끌 수 있어야 하나 | 아니오 | **예** | — |
|
||||
| 다른 서비스가 같은 기능을 라이브러리로 받나 | 아니오 | **예** | 아니오 |
|
||||
| 한 줄 지워 기능을 통째로 빼야 하나 | 아니오(패키지 삭제) | **예**(`runtimeOnly` 한 줄) | 예(leaf 삭제) |
|
||||
| leaf 단위 의존 방향 검사가 기능 안에도 걸리나 | 예(계층이 leaf) | 예 | **아니오**(ArchUnit 패키지 규칙에만 기댐) |
|
||||
| 고칠 공용 파일 | 없음(+ imports 한 줄) | `modules.json`, `settings.gradle` 매핑, `app-bootstrap/build.gradle`, lockfile | `modules.json` |
|
||||
| 예시 | 생성 명령 출력, `application-core/.../operation` | `application-notification`, `application-fileserver`, `application-objectstorage` | `sample-portfolio` |
|
||||
|
||||
### 판단: ①과 ② 중 무엇인가
|
||||
|
||||
- **고르는 기준**: 이 기능을 쓰지 않는 서비스(또는 같은 서비스의 다른 배포)가 있는가.
|
||||
- **기본값**: ①. 업무 기능은 그 서비스의 존재 이유라 끌 일이 없다. 파일 추가만으로 끝나고, leaf 경계
|
||||
검사가 계층마다 걸린다.
|
||||
- **예외**: ② — 여러 서비스가 쓰는 플랫폼 기능, 배포마다 켜고 끄는 기능, 자기 설정 prefix와 자기
|
||||
저장소를 가진 기능. 이때는 capability 완료 기준 7개를 모두 지킨다(`AGENTS.md`, 10장).
|
||||
- **다시 볼 조건**: 파생 서비스가 둘 이상 생겨 같은 업무 기능을 공유하거나, application-core 컴파일·테스트
|
||||
시간이 문제가 되면 ①을 ②로 옮긴다(리뷰 01 영역 5.2절).
|
||||
|
||||
### 판단: ③을 써도 되나
|
||||
|
||||
- **기본값**: 쓰지 않는다. ③은 leaf 하나가 모든 계층에 의존해서 leaf 단위 방향 검사가 기능 안에서는
|
||||
아무것도 막지 못한다.
|
||||
- **예외**: 통째로 지울 수 있어야 하는 샘플·데모. `sample-portfolio`가 그 예다. 샘플을 계층 leaf로 쪼개지
|
||||
않는 이유는 "leaf 하나 지우면 끝"이라는 성질을 지키려는 것이다.
|
||||
|
||||
## ① 안의 패키지 규칙
|
||||
|
||||
| 계층 | 패키지 | 하위 패키지 |
|
||||
| --- | --- | --- |
|
||||
| domain | `dev.caskeleton.domain.<f>` | fake·계약은 testFixtures `dev.caskeleton.domain.<f>.testkit` |
|
||||
| application | `dev.caskeleton.application.<f>` | 종류별 하위 패키지(`command`, `usecase`, `port`)를 만들지 않는다. 기능별 한 패키지(sample P30 결정과 같다) |
|
||||
| outbound | `dev.caskeleton.adapter.outbound.<leaf>.<f>` | |
|
||||
| inbound | `dev.caskeleton.adapter.inbound.web.<f>` | |
|
||||
| bootstrap | `dev.caskeleton.bootstrap.autoconfigure.<f>` | `@AutoConfiguration`만(`BOOTSTRAP_AUTOCONFIGURE_STEREOTYPES_ARE_AUTO_CONFIGURATIONS`) |
|
||||
|
||||
- `<f>`는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과
|
||||
겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를
|
||||
이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다.
|
||||
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/CLAUDE.md`
|
||||
「Package ownership」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성
|
||||
뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다.
|
||||
- 이름 규칙은 같은 파일 「Naming convention」이 정본이다.
|
||||
|
||||
## 저장 adapter는 어디에
|
||||
|
||||
① 기능의 저장 adapter 위치는 04장 「판단: 저장 adapter를 둘 leaf」. 요약: persistence-jpa에 업무 코드를
|
||||
넣지 않는다(그 leaf는 capability라 "모듈을 아는 곳은 모듈 자신뿐" 규칙이 걸린다).
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 업무 기능 = ① 계층 leaf 패키지. 생성 명령이 이 모양을 만든다.
|
||||
- 켜고 끄는 플랫폼 기능 = ② 별도 leaf, capability 기준 7개.
|
||||
- sample-portfolio는 기법 참고용이지 배치 예시가 아니다.
|
||||
@@ -0,0 +1,150 @@
|
||||
# 04. 영속성
|
||||
|
||||
## 핵심
|
||||
|
||||
저장 adapter는 생성 명령이 만들지 않는다. 이 장의 순서로 만든다. 세 가지를 지킨다.
|
||||
|
||||
1. 엔티티 연관관계는 한쪽에서만 맵핑한다. 빌드가 막는다.
|
||||
2. 중복·경쟁은 코드 순서가 아니라 **DB 제약**이 막고, 위반은 기능의 오류로 바꾼다.
|
||||
3. 마이그레이션은 템플릿 운영 스트림과 **번호가 겹치지 않는 자기 스트림**에 둔다.
|
||||
|
||||
```text
|
||||
use case ── tx.inWrite ──▶ XRepository (domain 포트)
|
||||
│
|
||||
▼
|
||||
JpaXRepository (adapter) ── CallerTransaction.require
|
||||
│ 엔티티 ↔ aggregate 변환(mapper)
|
||||
▼
|
||||
Spring Data / EntityManager ──▶ PostgreSQL (제약·인덱스)
|
||||
│
|
||||
위반·장애 ──▶ PersistenceExceptionTranslator ──▶ OperationalError 또는 기능 예외
|
||||
```
|
||||
|
||||
## 순서
|
||||
|
||||
1. 계약 테스트부터: 생성된 `XRepositoryContract`(domain-core testFixtures)에 필요한 동작을 더한다.
|
||||
in-memory fake가 먼저 통과해야 한다.
|
||||
2. 마이그레이션을 쓴다(아래 번호 규칙).
|
||||
3. 엔티티·Spring Data repository·mapper·adapter를 쓴다. adapter는 aggregate만 주고받는다
|
||||
(`OUTBOUND_ADAPTER_METHOD_RETURNS_ONLY_DOMAIN_OR_PRIMITIVES`).
|
||||
4. `JpaXRepositoryContractTest extends XRepositoryContract`를 실 PostgreSQL lane에 둔다(08장 lane).
|
||||
adapter는 호출자 트랜잭션 밖의 호출을 거부하므로(아래 「트랜잭션 안에서만 쓴다」), 계약의
|
||||
`inTransaction(Supplier)`을 재정의해 거기서 트랜잭션을 열고 커밋한다. 계약은 모든 저장소 호출을 그
|
||||
hook으로 부른다. fake는 기본값(그냥 실행)을 쓴다.
|
||||
예: `src/sample-portfolio/src/integrationTest/java/dev/caskeleton/sample/portfolio/adapter/outbound/persistence/repository/WorkLogRepositoryAdapterContractTest.java`.
|
||||
5. adapter를 bean으로 등록하는 자동 설정을 쓰고, 기능의 `XConfig`에 `afterName`으로 그 순서를 적는다.
|
||||
|
||||
## 판단: 저장 adapter를 둘 leaf
|
||||
|
||||
- **고르는 기준**: upstream 템플릿 leaf에 서비스 코드가 섞이는가.
|
||||
- **기본값**: 서비스 전용 persistence leaf 하나(`adapter:outbound:persistence-<service>`)를 registry에
|
||||
등록하고 업무 기능의 adapter를 모두 거기 둔다. 모양은 `src/adapter/outbound/persistence-notification`
|
||||
(`persistence-jpa`에 의존, 자기 엔티티 scan·자기 Flyway 스트림·자기 자동 설정).
|
||||
- **예외**: 하나도 없다고 보는 편이 낫다. `persistence-jpa`에 업무 패키지를 넣으면 ① capability 규칙 7
|
||||
("모듈을 아는 곳은 모듈 자신뿐")을 어기고, ② 그 leaf의 공개 API 기준선
|
||||
(`docs/architecture/jpa-api-surface.txt`)과 엔티티 scan 목록(`PersistenceJpaConfig`,
|
||||
`PersistenceEntityScanCoverageTest`)을 고쳐야 하며, ③ upstream 병합 충돌 면이 넓어진다.
|
||||
sample은 자기 leaf 안에 adapter를 둔다(③ 수직 슬라이스라서).
|
||||
- 새 leaf는 `modules.json` 등록, lockfile 생성, `app-bootstrap/build.gradle` 한 줄이 필요하다(10장).
|
||||
|
||||
## 엔티티 매핑
|
||||
|
||||
정본: `docs/jpa/entity-mapping-guide.md`.
|
||||
|
||||
| 규칙 | 막는 곳 |
|
||||
| --- | --- |
|
||||
| 연관관계는 한쪽만. aggregate 사이는 id 참조, 같은 aggregate 안은 단방향 `@ManyToOne(LAZY)`, 컬렉션은 쿼리 | `JpaArchitectureRules.associationsAreMappedFromOneSideOnly()`(`src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/arch/JpaArchitectureRules.java`) — `JpaProductionArchitectureTest`가 운영 그래프 전체에 건다 |
|
||||
| 엔티티는 adapter 밖으로 나가지 않는다 | `PERSISTENCE_ENTITIES_STAY_INSIDE_A_PERSISTENCE_ADAPTER`, `noEntityFromWeb` |
|
||||
| `Long` id 금지, id 컬럼 `varchar(255)` 금지 | `NO_LONG_ID_PK`, `NO_VARCHAR_255_FOR_ID_COLUMN` |
|
||||
| 벤더 전용 `columnDefinition` 금지 | `PERSISTENCE_RDBMS_ENTITIES_DO_NOT_PIN_VENDOR_COLUMN_DEFINITIONS` |
|
||||
| 감사 필드는 엔티티에만, 도메인에는 없다 | `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS` |
|
||||
|
||||
### 판단: 단방향 `@OneToMany(@JoinColumn)`을 써도 되나
|
||||
|
||||
- **기본값**: 쓰지 않는다. 자식 목록은 repository 쿼리(`findByParentId`, 페이지는 SQL에서).
|
||||
- **예외**: 루트만 바꾸는 자식(루트를 통해서만 생기고 지워짐). 규칙은 `mappedBy`만 막으므로 허용되지만
|
||||
nullable join column이면 자식마다 UPDATE가 한 번 더 나간다(가이드 「Associations」).
|
||||
|
||||
## 트랜잭션 안에서만 쓴다
|
||||
|
||||
store는 자기 트랜잭션을 열지 않는다. 유스케이스가 연 트랜잭션에 합류해야 하는 쓰기는 시작 전에
|
||||
`CallerTransaction.require("<무엇>")`
|
||||
(`src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/CallerTransaction.java`)를
|
||||
부른다. 없으면 트랜잭션 밖 호출이 문장마다 따로 커밋되어, 같이 커밋돼야 할 행(업무 행 + outbox 행)이
|
||||
갈라진다.
|
||||
|
||||
## 중복·경쟁은 DB가 막는다
|
||||
|
||||
- **고르는 기준**: "같은 X가 둘 있으면 안 된다", "한 작업을 두 인스턴스가 집으면 안 된다" 같은 규칙인가.
|
||||
- **기본값**: DB 제약.
|
||||
- 중복 금지 → 유일성 제약/인덱스. 유스케이스의 사전 조회(`existsBy…`)는 빠른 거절일 뿐이다.
|
||||
READ COMMITTED에서 두 요청이 모두 "없음"을 보고 둘 다 insert한다.
|
||||
- adapter가 그 **이름 붙은 제약**의 위반만 잡아 기능 예외로 바꾼다. 다른 제약 위반은 그대로 둔다.
|
||||
예: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/outbound/persistence/repository/PosterRepositoryAdapter.java`
|
||||
(`DataIntegrityViolationException` → 제약 이름 확인 → `PosterTitleAlreadyExistsException` 409),
|
||||
제약은 `src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql`.
|
||||
- **충돌을 바꾸는 곳은 하나다.** 업무 규칙 충돌(같은 제목)은 포트 옆 domain 패키지의 예외 타입이고,
|
||||
포트가 `@throws`로 선언하고 adapter가 던진다. 유스케이스의 사전 조회도 같은 타입을 던져 두 경로가 같은
|
||||
409가 된다. application 예외를 domain 포트가 Javadoc으로만 가리키면 fake·mock은 그 약속을 지킬 수 없다.
|
||||
기술 충돌(버전 불일치·교착)은 adapter가 프레임워크 예외 그대로 두고 아래 `PersistenceExceptionTranslator`가
|
||||
`DB_*` 코드로 바꾼다(WorkLog의 `ObjectOptimisticLockingFailureException` → `DB_OPTIMISTIC_CONFLICT`).
|
||||
- 그 약속은 포트 소유자 testFixtures의 공유 계약 테스트로 고정한다. fake와 adapter가 같은 계약을 상속한다.
|
||||
예: `PosterRepositoryContract`(`InMemoryPosterRepository`, `PosterRepositoryAdapterContractTest`).
|
||||
- 여러 인스턴스가 집는 작업 → `FOR UPDATE SKIP LOCKED`는 **트랜잭션 안에서**, 그리고 lease(만료 시각)와
|
||||
fence 값을 함께 저장한다. 예: `ReconciliationJobStorePort.claimDue`(application-notification),
|
||||
gRPC operation ledger의 claim.
|
||||
- 수정 충돌 → 버전 열(낙관적 잠금). 예: `UpdateWorkLogUseCase`의 version 비교와 `@Version`.
|
||||
- **예외**: DB가 볼 수 없는 규칙(외부 시스템 상태)은 분산 락(`DistributedLockPort`)이나 멱등성 키(05장).
|
||||
- 동시성 테스트는 실 DB lane에서 동시 요청 N개 → 행 1개를 단언한다(sample `integrationTest` 참고).
|
||||
|
||||
## 기술 실패는 공통 코드로 나간다
|
||||
|
||||
어떤 기능 예외로도 바꾸지 않은 DB 실패는 `PersistenceExceptionTranslator`
|
||||
(`src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java`)가
|
||||
SQLState로 `OperationalError`를 고른다. `DB_UNIQUE_VIOLATION` 409, `DB_SERIALIZATION_FAILURE`·`DB_DEADLOCK`
|
||||
409(retryable), 커밋 중 연결 끊김은 `DB_COMPLETION_UNKNOWN` 500(05장). 분류표는 이 한 곳이다. adapter가
|
||||
SQLState 표를 복사하지 않는다.
|
||||
|
||||
## 마이그레이션 번호
|
||||
|
||||
```text
|
||||
템플릿 운영 스트림 classpath:db/migration/postgresql V1 … V19 … (upstream이 계속 늘린다)
|
||||
capability 스트림 db/migration/jpa/<capability> 각자 history table
|
||||
샘플 스트림 db/sample-migration flyway_sample_schema_history
|
||||
서비스 스트림(권장) db/migration/<service> flyway_<service>_schema_history
|
||||
```
|
||||
|
||||
- **고르는 기준**: upstream 템플릿을 계속 받을 것인가.
|
||||
- **기본값**: 서비스 마이그레이션은 **자기 위치 + 자기 history table** 스트림에 둔다. 모양은
|
||||
`SamplePostgreSqlPersistenceConfig.sampleMigrationStrategy`
|
||||
(`src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SamplePostgreSqlPersistenceConfig.java`)와
|
||||
`NotificationSchemaStream`(persistence-notification). 그러면 번호가 템플릿 스트림과 독립이라 V1부터 쓴다.
|
||||
자기 스트림의 Flyway는 `Flyway.configure()`가 아니라 `FlywaySchemaPolicy.configure()`(persistence-jpa)로
|
||||
만든다. Flyway의 PostgreSQL 잠금을 세션에 두어야 `CREATE INDEX CONCURRENTLY` 마이그레이션이 끝나고,
|
||||
직접 부르면 `:app-bootstrap:architectureTest`가 실패한다(`docs/jpa/migration-guide.md` "Who may change the schema").
|
||||
- **예외**: 템플릿 운영 스트림(`db/migration/postgresql`)에 직접 넣으면 upstream이 다음에 쓸 번호와
|
||||
겹친다. 어쩔 수 없으면 upstream이 쓰지 않을 큰 번호대를 정해 문서에 적는다.
|
||||
- 이미 적용된 파일은 고치지 않는다. 고치면 체크섬 불일치로 기동이 멈추고, `repair`는 쓰지 않는다
|
||||
(`docs/jpa/migration-guide.md`).
|
||||
- 같은 스트림 안에서 기존 두 버전 사이에 끼워야 하면 소수 버전(`V8_1`)을 쓴다. 샘플 테스트 일부가 운영
|
||||
스트림과 샘플 스트림을 한 목록으로 합치는데, 정수 V9 이상은 운영이 이미 쓰고 있어서 `V8_1`을 골랐다
|
||||
(리뷰 README 13.2, 09-02).
|
||||
- 기존 데이터가 새 제약을 어기면 마이그레이션이 이유를 남기고 멈추게 쓴다(`V8_1`의 `DO $$` 블록). 조용히
|
||||
지우지 않는다.
|
||||
- 운영 중인 테이블을 잠그는 문장(`ALTER TABLE`, `CONCURRENTLY` 없는 `CREATE INDEX`, `UPDATE`·`DELETE`, 기존
|
||||
테이블을 가리키는 `REFERENCES`, trigger 만들기·지우기 등 — 전체 목록은 `docs/jpa/migration-guide.md`)이 있으면
|
||||
그 앞에 `SET LOCAL lock_timeout = '5s';`를 둔다(`V8_1`, `V22`). 값은 0이 아니어야 하고,
|
||||
`executeInTransaction=false` 마이그레이션에서는 `SET LOCAL`이 효과가 없으니 잠그는 문장을 거기 두지 않는다. Flyway가
|
||||
스스로 트랜잭션 밖에서 돌리는 문장(`VACUUM`, `CREATE INDEX CONCURRENTLY` 등 — 목록은 같은 가이드)이 하나라도 있는 파일도
|
||||
트랜잭션 밖에서 돌므로, 그런 문장은 따로 한 파일에 둔다. `VACUUM FULL`처럼 트랜잭션 안에서 돌 수 없는 잠금 문장은
|
||||
상한을 걸 수 없으니 마이그레이션에 두지 않고 운영 절차로 돌린다. 상한이 없으면 그 테이블을 건드린 열린
|
||||
트랜잭션 하나(`ALTER TABLE`이면 읽기만 한 것도) 뒤에서 마이그레이션이 끝없이 기다리고, 그동안 뒤에 온 그
|
||||
테이블의 쓰기(`ALTER TABLE`이면 읽기까지)가 모두 마이그레이션 뒤에 줄을 선다. 상한이 있으면 5초 뒤 실패·롤백되고 새 버전이 뜨지 않을 뿐이다. 자기 스트림에도
|
||||
`SampleMigrationLockWaitTest`처럼 `LockWaitMigrationInspector`(persistence-jpa testkit) 검사를 둔다
|
||||
(`docs/jpa/migration-guide.md` "Bound the lock wait").
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 저장 adapter는 서비스 전용 persistence leaf에. persistence-jpa에 업무 코드를 넣지 않는다.
|
||||
- 중복은 유일성 제약, 경쟁은 트랜잭션 안 claim + lease, 수정 충돌은 버전 열.
|
||||
- 마이그레이션은 자기 스트림(자기 history table). 적용된 파일은 고치지 않는다.
|
||||
@@ -0,0 +1,111 @@
|
||||
# 05. 멱등성·결과 불명 처리
|
||||
|
||||
## 핵심
|
||||
|
||||
쓰기 요청의 결과는 세 가지다: 됐다, 안 됐다, **모른다**. "모른다"를 "안 됐다(다시 해도 됨)"로 적으면
|
||||
같은 작업이 두 번 적용된다. 그래서 결과를 증명할 수 없을 때는 항상 "모른다"로 답하고, 클라이언트가
|
||||
안전하게 다시 물을 방법(같은 멱등성 키)을 준다.
|
||||
|
||||
```text
|
||||
클라이언트 ── POST + Idempotency-Key ──▶ 컨트롤러 ──▶ KEYED 유스케이스
|
||||
│ IdempotencyExecutor
|
||||
├─ 처음 본 키 → 실행 → 결과 저장 → 응답
|
||||
├─ 끝난 키 → 저장된 결과 재생
|
||||
├─ 실행 중 키 → 409 IDEMPOTENT_IN_FLIGHT (retryable, Retry-After 2)
|
||||
└─ 다른 본문 → 422 IDEMPOTENT_REQUEST_MISMATCH
|
||||
DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false)
|
||||
```
|
||||
|
||||
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/CLAUDE.md` 「Idempotency (KEYED)」
|
||||
(executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명).
|
||||
|
||||
## 판단: 이 쓰기를 KEYED로 만드나
|
||||
|
||||
- **고르는 기준**: 클라이언트가 응답을 못 받았을 때 다시 보내는가, 그리고 두 번 적용되면 피해가 있는가.
|
||||
- **기본값**: 생성·결제·주문·발송처럼 "두 번 = 피해"인 쓰기는 `KEYED`. 같은 입력이면 같은 결과인
|
||||
쓰기(상태를 X로 설정)는 `IDEMPOTENT`. 그 밖은 `NOT_IDEMPOTENT`(생성 명령의 기본값 — 바꿀지 여기서
|
||||
정한다).
|
||||
- **예외**: 자연 키가 있어 DB 유일성 제약이 중복을 막으면(04장) 키 없이도 두 번째 요청이 409로 끝난다.
|
||||
다만 그 409는 "이미 있음"이지 "첫 요청의 결과"가 아니다. 클라이언트가 첫 결과를 받아야 하면 KEYED.
|
||||
|
||||
### KEYED로 만드는 순서
|
||||
|
||||
1. `@UseCaseCapability(idempotency = Idempotency.KEYED)`.
|
||||
2. 유스케이스 본문을 `IdempotencyExecutor`로 감싼다. executor를 유스케이스가 만들지 않는다 —
|
||||
`composition:idempotency`가 한 번 만든다.
|
||||
3. scope digest(주체 + 키 + operation 코드의 HMAC)와 요청 fingerprint(SHA-256)를 유스케이스 밖(전송)에서
|
||||
만든다. 원본 키는 저장소에 닿지 않는다.
|
||||
4. 작업 결과를 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)으로 돌려준다.
|
||||
예외를 던지면 effect-unknown으로 센다.
|
||||
5. 저장소 provider를 고른다: `app.capabilities.idempotency.provider` = `postgresql` 또는 `redis`
|
||||
(기본 `disabled`). 운영에서 in-memory 금지.
|
||||
|
||||
예: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/` 의
|
||||
`PosterImagePublicationController`(키 헤더 검증), 유스케이스 쪽은 sample `application/posterimage`.
|
||||
|
||||
## 클라이언트에게 무엇을 약속하나
|
||||
|
||||
| 응답 | 의미 | 클라이언트 행동 |
|
||||
| --- | --- | --- |
|
||||
| 409 `IDEMPOTENT_IN_FLIGHT`, `retryable=true`, `Retry-After: 2` | 같은 키가 아직 실행 중. 결과 불명 | **같은 키로** 기다렸다 재전송. 새 키 금지 |
|
||||
| 422 `IDEMPOTENT_REQUEST_MISMATCH` | 같은 키에 다른 본문 | 클라이언트 버그. 재전송 안 함 |
|
||||
| 503 `IDEMPOTENCY_UNAVAILABLE` | 실행 전 거부(저장소 응답 없음, 또는 claim의 lease가 시작 전에 끝남) | 같은 키로 나중에 |
|
||||
| 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, `retryable=true` | 실행 뒤 결과 기록 실패. 적용됐을 수 있음 | "적용 안 됨"이라 하지 않는다. **같은 키로** 나중에 재전송, 새 키 금지 |
|
||||
| 500 `IDEMPOTENCY_RECOVERY_REQUIRED` | 이전 시도 효과를 증명 못함 | 자동 재시도 안 함. 같은 키 재전송은 안전(재생·실행·다시 500을 서버가 판정, 다시 돌리지 않음). 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키 |
|
||||
| 500 `DB_COMPLETION_UNKNOWN`, `retryable=false` | DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 | 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정 |
|
||||
|
||||
같은 키 재전송이 무엇을 막는지는 저장소마다 다르다(재리뷰 2026-11-04 RR5-01-05, 라운드6 RR6-02-05, 정본
|
||||
`docs/web/http-contract.md` 2절). Redis 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을 다시 돌리지
|
||||
않는다. PostgreSQL 저장소를 템플릿처럼 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
|
||||
요청이 다시 실행한다. 그래서 트랜잭션 밖 효과는 따로 멱등하게 만든다. 첫 시도가 processing lease(기본 30s)보다
|
||||
오래 걸릴 때 보이는 모습도 저장소마다 다르다.
|
||||
|
||||
- **Redis**: 첫 시도가 실행을 시작한 뒤 lease가 지나면 그 기록을 넘겨주지 않고 500
|
||||
`IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 넘겨받는 것은 실행 전 claim과 재시도 가능한 실패뿐이다. 이 답은
|
||||
기록을 바꾸지 않는다. executor는 lease를 늘리지 않아 30s를 넘는 정상 요청도 lease가 지나는데, 그 첫
|
||||
시도가 나중에 끝나면 결과가 기록되고 첫 요청은 정상 응답을 받으며 그 뒤 같은 키 요청은 그 결과를
|
||||
재생한다(2026-11-04 소유자 결정).
|
||||
- **PostgreSQL**: executor를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면(템플릿의 모양) claim 기록은 그
|
||||
트랜잭션과 함께 커밋되거나 롤백된다. 같은 키 요청은 409·500 대신 첫 요청이 끝날 때까지 기다렸다가
|
||||
재생(커밋)이나 새 실행(롤백)을 받는다. 작업이 예외로 끝나면 실패 기록도 함께 롤백되어 다음 같은 키
|
||||
요청이 다시 실행한다. 쓰기 트랜잭션 제한(기본 30s)을 넘긴 요청도 기록과 함께 롤백된다
|
||||
(`DB_QUERY_CANCELED`). 그래서 이 저장소가 막는 중복은 같은 트랜잭션 안의 DB 효과다. 트랜잭션 밖 효과는
|
||||
다음 요청에서 다시 일어날 수 있다.
|
||||
|
||||
claim의 lease가 작업 시작 전에 끝나면 두 저장소 모두 시작을 거절하고(`LEASE_EXPIRED`), executor는 작업을
|
||||
돌리지 않은 채 503 `IDEMPOTENCY_UNAVAILABLE`로 답한다. 다음 같은 키 요청이 그 claim을 넘겨받아 실행한다.
|
||||
`IdempotencyClaimAttempt`를 재시도 사이에 들고 있다가 같은 attempt로 다시 부르는 호출자도 넘겨받는다(라운드6
|
||||
RR6-02-01. 전에는 같은 claim을 재생받아 시작을 다시 거절당해 기록이 사라질 때까지 503이었다). 같은 attempt를
|
||||
두 호출이 동시에 쓰면 서버가 가려내지 못하므로, 재시도는 앞 호출이 돌아온 뒤에 한다.
|
||||
기록은 lease + `replay-ttl` 동안 남고, `replay-ttl`이 lease보다 짧으면 기동이 실패한다
|
||||
(`IdempotencyStoreContract`, 재리뷰 2026-11-04 RR-01-11·RR-03-11). 작업이 실패로 끝나 executor가 포기나
|
||||
재시도 가능으로 표시한 기록은 표시한 때부터 `failure-retention`(기본 24h) 동안 남는다(PostgreSQL을 트랜잭션
|
||||
하나로 쓰면 위처럼 롤백과 함께 사라진다). `failure-retention`이 `replay-ttl`보다 짧으면 기동이 실패한다.
|
||||
짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을 다시 돌리기 때문이다(RR3-03-02,
|
||||
2026-11-04 소유자 결정). 거꾸로 말하면 `replay-ttl`(`APP_IDEMPOTENCY_TTL`)은 lease 이상, `failure-retention`
|
||||
이하로 둔다.
|
||||
|
||||
409를 `retryable=true`로 바꾼 이유(리뷰 02-01 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
|
||||
보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.
|
||||
|
||||
## 결과 불명을 만드는 곳마다 같은 규칙
|
||||
|
||||
리뷰가 찾은 반복 원인 1번이 "결과 불명을 확실함으로 기록"이었다(05-01, 04-01, 06-01). 새 경계를
|
||||
만들 때 아래 질문에 답한다.
|
||||
|
||||
- **고르는 기준**: 실패한 호출이 **상대편에서 이미 효과를 냈을 수 있는가**.
|
||||
- **기본값**: 그럴 수 있으면 "결과 불명"으로 분류한다. 재시도 가능(`retryable=true`)으로 분류하지
|
||||
않는다. 근거 코드:
|
||||
- DB 커밋 중 끊김 → `DB_COMPLETION_UNKNOWN`
|
||||
(`src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java`)
|
||||
- 메시지 발행 응답 없음 → `OutboxPublishAmbiguousException`(application-core `outbox`)
|
||||
- 알림 발송 시작 뒤 crash → 재발송하지 않고 reconcile(application-notification evidence 모델)
|
||||
- **예외**: 요청이 상대에게 **도달하기 전**에 실패한 것이 증명되면(연결 수립 실패, 실행 전 거부)
|
||||
재시도 가능이다. 반대 방향 실수(확실히 안 간 것을 불명으로)도 결함이다(리뷰 05-17).
|
||||
- 불명 상태를 푸는 방법(reconcile, 키 재전송, 운영자 확인)을 runbook에 적는다(`docs/runbooks/`).
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- "두 번 = 피해"인 쓰기는 KEYED. executor는 composition이 만든다.
|
||||
- 409 in-flight는 같은 키로 다시, 422는 버그, 500 completion-unknown은 키 없이 재시도 금지.
|
||||
- 상대편에 효과가 났을 수 있으면 "모른다"로 분류한다.
|
||||
@@ -0,0 +1,68 @@
|
||||
# 06. 오류 모델
|
||||
|
||||
## 핵심
|
||||
|
||||
실패마다 먼저 **클라이언트 탓인가 서버 탓인가**를 정한다. 클라이언트 탓이면 안정된 오류 코드를 가진
|
||||
예외를 던지고, 서버 탓이면 코드 없이 던진다. 어느 쪽이든 기능 코드는 던지기만 하고, 전송별 핸들러
|
||||
하나가 wire 모양으로 바꾼다.
|
||||
|
||||
```text
|
||||
domain XInvariantException(Reason) ← 코드 없음. domain-core는 shared-contract를 못 본다
|
||||
│ 유스케이스가 잡아서 감싼다
|
||||
application XRejectedException implements ApiErrorCarrier → XErrorCode.X_INVALID (VALIDATION, 400)
|
||||
XNotFoundException implements ApiErrorCarrier → XErrorCode.X_NOT_FOUND (NOT_FOUND, 404)
|
||||
│ 던진다
|
||||
web GlobalExceptionHandler: ApiErrorCarrier → errorCode() → status + Envelope{error{code, category, retryable}}
|
||||
gRPC/GraphQL/WebSocket: 같은 ApiErrorCarrier를 자기 status 모양으로
|
||||
```
|
||||
|
||||
정본: `src/shared-contract/src/main/java/dev/caskeleton/shared/error/ApiErrorCarrier.java`,
|
||||
`ApiErrorCode.java`, `OperationalError.java`, `docs/registries/error-codes.yaml`, wire 모양은
|
||||
`docs/web/http-contract.md` 1절(null 필드는 내보내지 않는다).
|
||||
|
||||
## 판단: 오류 코드를 어디에 두나
|
||||
|
||||
- **고르는 기준**: 같은 유스케이스를 여는 전송이 둘 이상이 될 수 있는가.
|
||||
- **기본값**: application 기능 패키지의 `XErrorCode implements ApiErrorCode` enum + 예외가
|
||||
`ApiErrorCarrier` 구현. 전송마다 핸들러를 만들 필요가 없다. 생성 명령 출력이 이 모양이다
|
||||
(`<F>ErrorCode`, `<F>NotFoundException`, `<F>RejectedException`).
|
||||
- **예외**: 한 전송에서만 의미가 있는 실패(HTTP 헤더 형식 등)는 그 전송 adapter에 둔다. sample은 기능
|
||||
코드를 web 패키지(`PortfolioErrorCode`, `DomainExceptionHandler`)에 두는데, 한 leaf 수직 샘플이라
|
||||
가능한 모양이다. 따라 하지 않는다.
|
||||
|
||||
## 판단: 어떤 예외 타입으로 던지나
|
||||
|
||||
| 상황 | 던질 것 | 결과 |
|
||||
| --- | --- | --- |
|
||||
| 도메인 불변식 위반 | domain `XInvariantException(Reason)` → 유스케이스가 `XRejectedException`으로 감쌈 | 400 기능 코드 |
|
||||
| 찾는 것이 없음 / 남의 것 | `XNotFoundException`(carrier) | 404. 남의 것도 404로 존재를 숨긴다(07장) |
|
||||
| 상태 충돌(이미 있음, 버전 불일치) | 기능 carrier(Category.CONFLICT, 409) | 409 |
|
||||
| 요청 파라미터 형식 오류(경로 id 문법 등) | `IllegalArgumentException` | 400 `BAD_PARAMETER` |
|
||||
| 서버 조립·설정 오류, 있을 수 없는 상태 | `IllegalStateException` | 500, 로그 남음 |
|
||||
| DB·외부 의존 실패 | adapter가 shared-contract carrier(`PersistenceFailureException`, `DependencyFailureException`)로 | 분류표대로(04·05장) |
|
||||
|
||||
- `IllegalArgumentException`을 "서버 조립이 틀렸다"에 쓰지 않는다. web은 그것을 400으로 바꾸고 WARN
|
||||
한 줄만 남긴다(`GlobalExceptionHandler`). 서버 결함이 클라이언트 오류 통계에 섞여 경보가 울리지 않는다
|
||||
(리뷰 01-04). 서버 쪽 잘못은 `IllegalStateException`(500, 로그)이다.
|
||||
- 메시지는 로그용이다. 클라이언트에는 코드와 category별 고정 문구(`ClientErrorMessages`)만 간다.
|
||||
메시지에 SQLState·내부 경로·토큰을 넣어도 클라이언트에 새지 않지만, 로그 정책은 지킨다.
|
||||
|
||||
## 판단: `retryable`을 무엇으로
|
||||
|
||||
- **기본값**: `false`. 기능 오류 대부분은 같은 요청을 다시 보내도 결과가 같다.
|
||||
- **예외**: 시간이 지나면 성공할 수 있고 **다시 보내도 안전한** 경우만 `true`(일시적 의존 실패,
|
||||
`IDEMPOTENT_IN_FLIGHT`). `true`인 코드는 runbook 링크가 필요하다(registry 규칙).
|
||||
|
||||
## 코드 등록
|
||||
|
||||
- 템플릿 운영 코드: `OperationalError` + `docs/registries/error-codes.yaml`을 같은 변경에서 고친다.
|
||||
`ErrorCodeRegistryMappingTest`(app-bootstrap)가 status 일치를 검사한다.
|
||||
- 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 "Product/fork ApiErrorCode enums own local
|
||||
registries"). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 예:
|
||||
`src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/error/PortfolioErrorCodeRegistryMappingTest.java`.
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 클라이언트 탓 = carrier 예외 + 기능 코드. 서버 탓 = `IllegalStateException`.
|
||||
- 기능 코드는 application에 두고, 전송 핸들러는 기능을 모른다.
|
||||
- `retryable=true`는 다시 보내도 안전할 때만.
|
||||
@@ -0,0 +1,157 @@
|
||||
# 07. 권한
|
||||
|
||||
## 핵심
|
||||
|
||||
권한 검사는 두 층이다. **"이 종류의 작업을 해도 되나"**(권한 이름)는 유스케이스의 `@RequiresPermission`
|
||||
선언과 web이 켜는 method security가 맡는다. **"이 객체를 봐도 되나"**(소유자·tenant)는 유스케이스가
|
||||
객체를 읽은 뒤 직접 판정한다.
|
||||
|
||||
```text
|
||||
요청 ─▶ 인증 필터(JWT 또는 세션) ─▶ AuthenticatedPrincipal(roles, tenant)
|
||||
─▶ 컨트롤러 ─▶ [프록시] RequiresPermissionAuthorizationManager
|
||||
│ role → permission (app.authz.role-permissions)
|
||||
│ 없으면 403, 인증 없으면 401
|
||||
─▶ 유스케이스 본문 ─▶ 객체 로드 ─▶ 소유자·tenant 판정 ─▶ 남의 것이면 404(존재 숨김)
|
||||
```
|
||||
|
||||
## 작업 단위 권한: `@RequiresPermission`
|
||||
|
||||
| 무엇 | 어디 |
|
||||
| --- | --- |
|
||||
| 선언 | `src/application-core/src/main/java/dev/caskeleton/application/security/RequiresPermission.java` — 쓰기 유스케이스에 필수(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`) |
|
||||
| 검사 장치 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/authz/MethodSecurityConfig.java`의 advisor |
|
||||
| 켜는 곳 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java` |
|
||||
| 역할 → 권한 | `app.authz.role-permissions` (`src/app-bootstrap/src/main/resources/config/security.yml`), 바인딩 `RolePermissionPolicy` |
|
||||
| 프록시 가능 | `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java` |
|
||||
|
||||
검사 자동 설정은 인증 체인(`WebSecurityAutoConfiguration`)과 **분리**되어 있다. 서비스가 자기 인증
|
||||
방식으로 인증 체인을 바꿔도 권한 검사는 꺼지지 않는다(1라운드 07-03 수정).
|
||||
|
||||
### 지켜야 할 것 셋
|
||||
|
||||
1. 유스케이스는 **bean**이다. 직접 `new` 하면 프록시가 없어 선언이 주석이 된다.
|
||||
2. 유스케이스 클래스와 그 public 메서드는 **final이 아니다**. final이면 프록시를 못 만들어 기동이 실패한다.
|
||||
3. 유스케이스 안에서 자기 다른 메서드를 부르면(self-invocation) 프록시를 거치지 않는다. 권한이 다른 두
|
||||
작업은 유스케이스 둘로 나눈다.
|
||||
|
||||
### 판단: 권한 이름과 역할 매핑
|
||||
|
||||
- **고르는 기준**: 운영자가 따로 주고 뺄 필요가 있는 작업인가.
|
||||
- **기본값**: `<resource>:<action>`, resource는 kebab-case(`purchase-order:create`). 생성 명령은
|
||||
`<f>:create` 하나를 만든다. 역할 매핑은 권한을 명시적으로 나열한다(와일드카드 없음).
|
||||
- **예외**: 같은 역할이 항상 함께 가지는 작업은 한 역할에 여러 권한을 준다
|
||||
(`operation-submit: operation:submit,operation:cancel`).
|
||||
- 매핑하지 않은 권한은 아무도 갖지 않는다. 새 기능의 쓰기는 매핑 전까지 모두 403이다 — 실수로 열리지
|
||||
않는 쪽.
|
||||
- 읽기 유스케이스는 선언이 필수가 아니다. 인증된 누구나 읽으면 안 되는 데이터면 선언하거나 객체 판정을 둔다.
|
||||
|
||||
### 역할은 어디서 오나
|
||||
|
||||
JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `resource_access.<client>.roles`만
|
||||
읽는다. audience는 필수다(1라운드 02-03 수정). 같은 issuer의 다른 client가 같은 이름의 역할을 정의해도
|
||||
이 서비스 권한이 되지 않는다(`JwtToAuthenticatedPrincipalConverter`, `docs/runbooks/auth-audience-mismatch.md`).
|
||||
|
||||
## 객체 단위 권한
|
||||
|
||||
- **고르는 기준**: 같은 권한을 가진 두 사람이 같은 객체에 대해 다른 답을 받아야 하는가(소유자, tenant).
|
||||
- **기본값**: 유스케이스가 객체를 읽은 뒤 판정하고, 남의 것이면 **없는 것과 같은 404**로 답한다.
|
||||
존재 여부도 정보다. 예: `GetDurableOperationUseCase`와 `DurableOperationAccessPolicy`
|
||||
(`src/application-core/src/main/java/dev/caskeleton/application/operation/`).
|
||||
- **예외**: 여러 전송이 같은 판정을 써야 하거나 목록에서 한 번에 판정해야 하면
|
||||
`ObjectAccessPolicy`(`src/application-core/src/main/java/dev/caskeleton/application/security/ObjectAccessPolicy.java`,
|
||||
batch 메서드로 N+1 회피)를 구현한다. 존재를 숨길 필요가 없는 관리 화면은 403도 된다.
|
||||
- tenant: 인증 정보에서만 만든 `TenantId`를 command에 싣는다. 요청 본문의 tenant 값을 믿지 않는다.
|
||||
|
||||
## 시스템이 부르는 쓰기: `@SystemInvoked`
|
||||
|
||||
스케줄러·relay·메시지 소비자처럼 사람이 아니라 시스템이 부르는 쓰기 유스케이스는 `@RequiresPermission` 대신
|
||||
`@SystemInvoked(reason = "...")`를 단다(`src/application-core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java`).
|
||||
스케줄러·소비 스레드에는 인증(`Authentication`)이 없어서 권한 선언은 매번 거부되거나 아예 검사되지 않는
|
||||
장식이 되기 때문이다. 이 표시가 붙은 유스케이스는 **권한 검사가 없는 쓰기**다. 그래서 사용자 요청이
|
||||
닿으면 안 된다.
|
||||
|
||||
```text
|
||||
사용자 요청 ─▶ web·GraphQL·gRPC·WebSocket ──✗──▶ @SystemInvoked 유스케이스 (빌드 실패)
|
||||
사용자 요청 ─▶ web·GraphQL·gRPC·WebSocket ──✗──▶ @SystemCaller (빌드 실패, 중간 클래스·작업의 인터페이스를 거쳐도.
|
||||
타입을 거치지 않는 길은 아래 「규칙이 못 보는 길」)
|
||||
시스템 ─▶ 스케줄러(조립 모듈이 new로 넘김) ─────▶ @SystemInvoked 유스케이스
|
||||
시스템 ─▶ 메시지 handler(@SystemCaller, 직접 new) ─▶ @SystemInvoked 유스케이스
|
||||
시스템 ─▶ 예약 작업(@SystemCaller, 직접 new) ──────▶ @SystemInvoked 유스케이스
|
||||
어디서든 ─▶ @SystemInvoked 유스케이스를 bean으로 등록 ──✗ (기동 실패)
|
||||
```
|
||||
|
||||
- 사용자 전송: 사용자가 보낸 요청이 들어오는 inbound adapter다(web·GraphQL·gRPC·WebSocket).
|
||||
- 시스템 호출자: broker 전달이나 시간(tick)이 깨우는 코드다. 사용자 요청은 여기로 들어오지 않는다.
|
||||
|
||||
시스템 호출자가 `@SystemInvoked` 유스케이스를 얻는 길은 아래 셋뿐이다. 이 표가 정본이고, 다른 문서는 이
|
||||
절을 가리킨다.
|
||||
|
||||
| 경로 | 어디에 두나 | 유스케이스는 누가 만드나 |
|
||||
| --- | --- | --- |
|
||||
| 조립 모듈의 스케줄러 | `composition:*` leaf. 예: outbox relay(`src/composition/outbox-relay`) | 조립 모듈의 `@Bean` 메서드가 `new`로 만들어 스케줄러에 넘긴다 |
|
||||
| 메시지 handler | `adapter:inbound:messaging` leaf, 또는 서비스 leaf의 `..adapter.inbound.messaging..` 패키지 | handler 생성자가 port를 받아 `new`로 만든다. handler에 `@SystemCaller`. 작업 순서는 09장 「소비」 4단계 |
|
||||
| 예약 작업 | 서비스 자기 leaf의 `..adapter.inbound.scheduler..` 패키지. 등록된 scheduler leaf는 없다 | 작업 클래스 생성자가 port를 받아 `new`로 만든다. 작업 클래스에 `@SystemCaller`. 모양은 메시지 handler와 같고, 깨우는 것이 `@Scheduled` 메서드다. `Runnable`·`ApplicationRunner` 같은 프로젝트 밖 타입을 구현하지 않는다. task scheduler에 직접 등록하면 그 자리에서 `job::run`을 넘긴다 |
|
||||
|
||||
예약 작업은 controller와 같은 leaf에 놓이기 쉽다. 그때 "지금 실행" endpoint가 작업 bean을 주입받아 부르면
|
||||
권한 검사 없는 쓰기를 사용자가 부르게 된다. 아래 `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`가 이것을
|
||||
빌드에서 막는다. 사용자도 같은 일을 시켜야 하면 `@RequiresPermission`을 단 사용자용 유스케이스를 따로
|
||||
만든다(아래 D4 문단).
|
||||
|
||||
| 규칙 | 무엇을 막나 | 어디 |
|
||||
| --- | --- | --- |
|
||||
| bean 금지 | `@SystemInvoked` 유스케이스가 bean이면 기동 실패. 호출자가 `new`로 만들어 혼자 들고 있는 것만 허용한다 | `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java` |
|
||||
| 시스템 호출자만 | inbound adapter가 그 클래스에 의존하면 빌드 실패. `@SystemCaller(reason = "...")`를 단 클래스와 그 안에 중첩된 클래스만 예외 | `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) |
|
||||
| 표시 검사 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping·gRPC·servlet)에 의존하지 않는다 | `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`(같은 파일) |
|
||||
| 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등)에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 셋이다. ① 사용자 전송 패키지에 있는 클래스. ② 설정(`@Configuration`·`@AutoConfiguration`)과 그 안에 중첩된 클래스 가운데 요청 처리기 타입(함수형 `RouterFunction`·`HandlerFunction`, `@RestController`·`@RequestMapping`, servlet·`Filter`·`HandlerInterceptor`, `WebSocketHandler`, GraphQL `DataFetcher`·`RuntimeWiringConfigurer`, gRPC `BindableService`·`ServerInterceptor` 등)에 의존하는 것. 함수형 route나 data fetcher를 람다로 쓰면 그 코드가 설정 클래스의 메서드로 컴파일되어 설정이 곧 endpoint다. ③ 그 밖의 클래스 가운데 사용자 전송 타입에 의존하는 것. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`(설정 필드를 읽는 익명 클래스여도)·controller bean을 함께 만들어도 걸리지 않지만, 같은 클래스에 "지금 실행" route·data fetcher·interceptor를 직접 쓰면 걸린다. 요청 처리 코드는 handler를 등록하는 설정과 다른 클래스에 둔다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
|
||||
| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스와 예외 제외)는 프로젝트(`dev.caskeleton..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler<T>`는 프로젝트 타입이라 된다. record·enum은 언어가 붙이는 상위 타입(`Record`, `Enum`과 `Enum`이 구현하는 `Comparable`·`Serializable`·`Constable`)만은 가져도 된다. 그래서 handler 안의 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외, record로 쓴 handler는 통과하고, `Runnable`을 구현한 record는 걸린다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) |
|
||||
|
||||
규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 이 성질은 **패키지** 쪽에서만 온다.
|
||||
패키지는 허용 목록이라, 나중에 새 전송 패키지가 생겨도 따로 고치지 않아도 막힌다. 사용자 전송 **타입**
|
||||
쪽은 나열 목록이다(`ARE_USER_TRANSPORT_TYPES`). 시스템 패키지 안에 놓인 endpoint를 알아보는 데 쓰는
|
||||
목록이라, 목록에 없는 전송 라이브러리로 만든 endpoint는 전송으로 보이지 않는다. 새 전송 라이브러리를
|
||||
들이면 그 패키지를 이 목록에 더한다. 설정 안의 요청 처리 코드를 알아보는 요청 처리기 타입
|
||||
(`ARE_REQUEST_HANDLER_TYPES`)도 나열 목록이라, 새 전송 라이브러리의 handler 타입을 함께 더한다.
|
||||
|
||||
D4 실패(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)를 끄려고 이 표시를 쓰지 않는다. 사용자가 부르는
|
||||
쓰기라면 권한을 선언하고 역할에 매핑한다. 같은 쓰기를 사용자도 시스템도 부르면 유스케이스를 둘로 나눈다
|
||||
(사용자용 `@RequiresPermission`, 시스템용 `@SystemInvoked`). 업무 규칙은 domain에 두고 둘이 같이 쓴다.
|
||||
|
||||
### 규칙이 못 보는 길
|
||||
|
||||
이 규칙들은 클래스 의존만 본다. 그래서 타입 이름이 코드에 남는 길은 모두 잡는다. `ObjectProvider<작업 클래스>`,
|
||||
`getBean(작업 클래스.class)`, 작업의 인터페이스 주입이 여기에 든다. 타입 이름이 남지 않는 길은 못 본다.
|
||||
|
||||
- 이름이나 `Object`로 bean을 찾는 코드: `getBean("nightlyJob")`, `Map<String, Object>` 주입 뒤 reflection 호출.
|
||||
- 설정이 사용자 전송에 작업을 감싼 함수를 넘기는 코드: `new RunNowController(job::run)`처럼 controller는
|
||||
`Runnable`만 받는다. 의존은 설정 → 작업 쪽에만 있고, 요청 처리 코드를 직접 갖지 않은 설정은 사용자 전송이
|
||||
아니다.
|
||||
- 설정 안의 요청 처리 코드가 요청 처리기 타입 목록(`ARE_REQUEST_HANDLER_TYPES`)에 없는 타입으로 쓰인 경우.
|
||||
목록 방식이라, 목록에 없는 endpoint 타입으로 설정 안에 쓴 endpoint는 사용자 전송으로 보이지 않는다.
|
||||
|
||||
이 길을 막는 것은 ArchUnit 규칙이 아니라 다음 셋이다.
|
||||
|
||||
- `@SystemInvoked` 유스케이스는 bean이 아니고(`PermissionEnforcementGuard`), 시스템 호출자가 `new`로 만들어
|
||||
혼자 든다. 그래서 사용자 전송은 시스템 호출자 객체를 거치지 않고는 그 유스케이스를 부를 수 없다.
|
||||
- 의존 방향 게이트(`src/config/architecture/modules.json`): 등록된 leaf 가운데 `adapter:inbound:messaging`에
|
||||
의존할 수 있는 것은 조립 루트(`app-bootstrap`)뿐이다. 다른 leaf의 사용자 전송은 handler 타입을 컴파일조차
|
||||
못 한다. 예약 작업은 서비스 자기 leaf에 있어서 같은 leaf의 controller와 사이에는 이 게이트가 없다. 그래서
|
||||
위 길들은 사실상 controller와 작업이 같은 leaf에 있을 때, 또는 둘을 모두 보는 설정에서 생긴다.
|
||||
- 리뷰: 설정에서 시스템 호출자를 함수로 감싸 다른 bean에 넘기거나, 사용자 전송이 bean을 이름으로 찾거나, 목록에
|
||||
없는 타입으로 설정 안에 endpoint를 쓰는 코드는 리뷰에서 거절한다. 사용자도 같은 일을 시켜야 하면 위 문단대로
|
||||
사용자용 유스케이스를 따로 만든다.
|
||||
|
||||
## web 없는 조립
|
||||
|
||||
web이 빠진 조립(gRPC 전용·배치 전용)에는 `@RequiresPermission`을 검사할 advisor가 없다. 그런 조립에
|
||||
권한을 선언한 bean이 있으면 `PermissionEnforcementGuard`가 기동을 실패시킨다(리뷰 01-06). web 없이
|
||||
조립하는 서비스는 자기 전송에 맞는 검사 advisor를 함께 넣어야 기동한다.
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 쓰기 = `@RequiresPermission` + non-final + bean + 역할 매핑.
|
||||
- 시스템만 부르는 쓰기 = `@SystemInvoked` + bean 아님 + 사용자 전송에서 안 닿음. 부르는 쪽은 셋뿐이다:
|
||||
조립 모듈의 스케줄러, `@SystemCaller` 메시지 handler, `@SystemCaller` 예약 작업. 사용자 전송은
|
||||
`@SystemCaller`에도, 그 작업의 인터페이스에도 닿지 못한다. 타입 이름이 남지 않는 길(이름으로 찾기,
|
||||
설정이 넘기는 함수)은 빌드가 못 보니 리뷰가 막는다.
|
||||
- 객체 판정은 유스케이스 안, 남의 것은 404.
|
||||
- 역할은 자기 client 것만 읽는다.
|
||||
@@ -0,0 +1,80 @@
|
||||
# 08. 테스트 작성 규칙
|
||||
|
||||
## 핵심
|
||||
|
||||
테스트 규칙의 정본은 `AGENTS.md` 「테스트 전략」이다. 이 장은 새 기능을 만들 때 그 규칙이 **어떤
|
||||
파일 배치가 되는지**와 **어느 단계(PR/main/integration)에서 도는지**를 적는다.
|
||||
|
||||
```text
|
||||
포트 XRepository (domain-core)
|
||||
├─ testFixtures: InMemoryXRepository (fake, 포트당 하나)
|
||||
├─ testFixtures: XRepositoryContract (abstract, 약속 목록)
|
||||
├─ test: InMemoryXRepositoryContractTest extends XRepositoryContract → ci (leaf test)
|
||||
└─ 저장 adapter leaf integrationTest:
|
||||
JpaXRepositoryContractTest extends XRepositoryContract → integrationCheck (실 PostgreSQL)
|
||||
|
||||
유스케이스 테스트 = 실제 유스케이스 + InMemoryXRepository + DirectTransactionPort
|
||||
```
|
||||
|
||||
fake와 실제 adapter가 **같은 계약**을 통과해야 fake 위의 유스케이스 테스트가 거짓 녹색이 되지 않는다.
|
||||
생성 명령은 이 배치를 그대로 만든다(01장).
|
||||
|
||||
## 계층별 테스트
|
||||
|
||||
| 계층 | 테스트 | 쓰는 대역 | 예 (생성 결과) |
|
||||
| --- | --- | --- | --- |
|
||||
| domain | 순수 JUnit. 불변식·id 문법 | 없음 | `<F>Test`, `<F>IdTest` |
|
||||
| domain 포트 | 공유 계약 | fake | `InMemory<F>RepositoryContractTest` |
|
||||
| application | 유스케이스 흐름·트랜잭션 경계·오류 코드 | 포트 소유자 testFixtures의 fake, `DirectTransactionPort` | `Create<F>UseCaseTest` |
|
||||
| outbound adapter | 같은 공유 계약을 실제 저장소로 | Testcontainers(strict lane) | 04장 4번 |
|
||||
| inbound | HTTP status·Envelope·오류 코드 | 실제 유스케이스 + fake, standalone MockMvc | `<F>ControllerTest` |
|
||||
| bootstrap | 조립 조건(있을 때 켜짐, 없을 때 없음), imports 등록 | fake bean | `<F>ConfigTest` |
|
||||
|
||||
## 작성 규칙 요약 (정본은 AGENTS.md)
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장. 이름이 말한 성질을 단언한다. 예: 이름에 "트랜잭션 전에"를 넣었으면
|
||||
트랜잭션이 없었다는 것도 단언하거나, 이름에서 뺀다.
|
||||
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만, **한국어**로
|
||||
(소유자 결정 5). 예: `@DisplayName("이름이 NAME_MAX_LENGTH + 1자이면 거절한다")`.
|
||||
3. 본문 3문장 이상이면 `// given` `// when` `// then`. `// when`은 하나. 예외는 `catchThrowable`로 분리.
|
||||
4. then은 when의 결과 하나만. 예외는 타입과 reason/code를 함께.
|
||||
5. 포트 대역은 hand-rolled fake 하나, **포트 소유 leaf의 testFixtures**에. Mockito는 프레임워크 경계와
|
||||
장애 주입만.
|
||||
|
||||
### 판단: fake가 어디 사나
|
||||
|
||||
- **고르는 기준**: 포트 인터페이스가 어느 leaf에 있나.
|
||||
- **기본값**: 그 leaf의 `src/testFixtures/java/.../<f>/testkit/`. domain 포트면 domain-core,
|
||||
application 포트면 application-core. 소비 leaf는 `testImplementation testFixtures(project(':<owner>'))`.
|
||||
- **예외**: 없다. 테스트 안 private fake는 계약 밖에 있어 실제와 갈라진다(리뷰 01-05의 lock fake).
|
||||
|
||||
## lane과 단계
|
||||
|
||||
`ci`(PR)의 leaf `test`는 Docker 없이 빠르게 끝나야 한다. 실 DB·실 서버가 필요한 테스트는 strict
|
||||
lane으로 선언하고 단계를 지정한다. 선언은 `ca.strict-test-lane`(`src/build-logic/README.md`).
|
||||
|
||||
| lane 종류 | 선언 | 도는 단계 |
|
||||
| --- | --- | --- |
|
||||
| 단위·slice | 기본 `test` | `ci` |
|
||||
| 문서 대조·느린 계약 | 태그 lane + `mainStage()` | `mainCheck` |
|
||||
| 실 DB·컨테이너 | `integration()` + 자기 sourceSet(예: `integrationTest`) | `integrationCheck` |
|
||||
| 성능·부하 | performance 범주 | `performanceCheck` |
|
||||
| 외부 입력 필요(자격증명 등) | `explicitOnly(reason)` | 어떤 집계에도 안 들어가고 이유가 출력된다 |
|
||||
|
||||
예: `src/sample-portfolio/build.gradle`의 `strictTestLanes { lane('integrationTest') { integration() … } }`,
|
||||
`src/app-bootstrap/build.gradle`의 `publicPathSnapshotTest`(`mainStage()`).
|
||||
|
||||
### 판단: 새 테스트를 어느 lane에
|
||||
|
||||
- **고르는 기준**: Docker·네트워크·실 서버가 필요한가, 몇 초 넘게 걸리는가.
|
||||
- **기본값**: 필요 없으면 `test`(ci). 필요하면 integration lane.
|
||||
- **예외**: 반드시 실행돼야 하는 소수 테스트(계약 자격 검사)는 `requires(클래스)` + `rejectSkipped = true`로
|
||||
이름을 박는다. 이름이 바뀌거나 지워지면 lane이 실패한다.
|
||||
- 새 lane이 어떤 단계에도 속하지 않으면 PR 게이트의 `verifyStrictLaneStages --dry-run`이 실패한다
|
||||
(1라운드 08-01). 단계는 집계 태스크(`integrationCheck` 등)를 통해 붙고, workflow 파일을 고치지 않는다.
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- fake와 계약은 포트 주인 testFixtures에, adapter는 같은 계약을 실제 저장소로.
|
||||
- `@DisplayName`은 꼭 필요할 때만, 한국어로.
|
||||
- Docker가 필요한 테스트는 strict lane + 단계 지정. 단계 없는 lane은 PR에서 막힌다.
|
||||
@@ -0,0 +1,197 @@
|
||||
# 09. outbox·이벤트
|
||||
|
||||
## 핵심
|
||||
|
||||
업무 저장과 이벤트 발행을 **같은 DB 트랜잭션**에 묶는다. 유스케이스는 broker에 직접 보내지 않고,
|
||||
이벤트를 outbox 테이블에 업무 행과 함께 쓴다. 별도 relay가 커밋된 outbox 행을 broker로 옮긴다.
|
||||
|
||||
```text
|
||||
use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐ 한 커밋
|
||||
└─▶ OutboxAppendPort.append(validated) ┘
|
||||
▲
|
||||
IntegrationEventDraft ──▶ IntegrationEventEncoderPort (계약으로 검증·인코딩)
|
||||
|
||||
(커밋 뒤, 따로) composition:outbox-relay ─▶ OutboxStorePort.claim(lease) ─▶ broker ─▶ 완료/재시도/DEAD
|
||||
```
|
||||
|
||||
DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을
|
||||
없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다.
|
||||
|
||||
정본: `src/application-core/CLAUDE.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
|
||||
`docs/messaging/delivery-guarantees.md`.
|
||||
|
||||
## 순서
|
||||
|
||||
1. 계약을 정한다: 계약 id(`<service>.<aggregate>.<event>`), 버전, payload record, JSON schema 파일과 해시.
|
||||
예: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogReservedContractContribution.java`,
|
||||
`src/sample-portfolio/src/main/resources/contracts/messaging/portfolio.worklog.reserved/v1.schema.json`(+ `.sha256`).
|
||||
2. payload record(`IntegrationPayload`)를 만든다.
|
||||
3. 유스케이스의 `tx.inWrite` 안에서 저장 뒤 draft → encode → append. 예:
|
||||
`CreateWorkLogUseCase`(sample)와 그 헬퍼 `PortfolioEventOutbox`.
|
||||
4. 계약 contribution을 조립에서 `@Bean`으로 등록한다. encoder는 컨텍스트의 계약 bean으로 만들어진다.
|
||||
등록을 빠뜨리면 append 때 실패한다. 예: `DurableOperationAutoConfiguration.durableOperationSubmittedContract()`.
|
||||
5. 테스트: 계약 contribution 테스트(해시 고정), 유스케이스가 append했는지(`InMemoryOutboxStore`),
|
||||
소비자 중복 제거 계약(sample `WorkLogReservedConsumerDedupeContractTest`).
|
||||
6. schema를 출시한다: `src/test/resources/contracts/released-payload-schemas.sha256`에 새 version 파일의
|
||||
해시를 한 줄 더한다. 출시한 version 파일은 고치지 않는다 — 바뀌면 `ReleasedPayloadSchemaContract`
|
||||
테스트가 실패한다. 필드를 바꾸는 변경은 새 version으로 낸다. 절차: `src/application-core/README.md`
|
||||
"payload version 올리기"(리뷰 06-10).
|
||||
|
||||
## 판단 지점
|
||||
|
||||
### 도메인 이벤트가 필요한가, 통합 이벤트만인가
|
||||
|
||||
- **고르는 기준**: 같은 서비스 안에서 이 사실에 반응하는 코드가 있는가.
|
||||
- **기본값**: 통합 이벤트만. 유스케이스가 저장 뒤 바로 payload를 만든다.
|
||||
- **예외**: aggregate 안에서 일어난 사실을 여러 유스케이스가 같은 방식으로 내보내면 domain
|
||||
`@DomainEvent` record를 두고 유스케이스가 그것을 payload로 옮긴다(sample `WorkLogReserved`).
|
||||
|
||||
### payload에 무엇을 넣나
|
||||
|
||||
- **기본값**: id만(+ 소비자가 라우팅에 필요한 최소 값). 상태 전체를 넣으면 계약이 aggregate 변경마다 깨진다.
|
||||
- **예외**: 소비자가 원 서비스를 다시 조회할 수 없는 경우(외부 파트너)는 필요한 상태를 넣고 버전을 올린다.
|
||||
|
||||
### event id·correlation·순서
|
||||
|
||||
draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occurredAt, requestCorrelationId, payload)`로
|
||||
만든다(`src/application-core/src/main/java/dev/caskeleton/application/messaging/event/IntegrationEventDrafts.java`).
|
||||
계약 id·payload 버전·목적지는 계약에서 오고, 기능이 정하는 것은 aggregate·순서·payload뿐이다.
|
||||
`new IntegrationEventDraft<>(…)`를 직접 쓰면 빌드가 막는다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`).
|
||||
예: sample `PortfolioEventOutbox`, `SubmitDurableOperationUseCase`.
|
||||
|
||||
- event id: 정규 소문자 UUIDv7, 소비자 중복 제거 키. draft(`IntegrationEventDraft`)가 다른 값(대문자,
|
||||
v4, `event-1` 같은 문자열)을 거부하므로 업무 쓰기에서 바로 실패한다 — 커밋된 뒤 relay에서 DEAD가 되지
|
||||
않는다(리뷰 06-06). 같은 작업의 재시도가 같은 event id를 내야 하면(durable operation) 작업 id를 쓰고,
|
||||
작업 id가 UUIDv7이 아니면 작업 id와 접수 시각에서 UUIDv7을 파생한다.
|
||||
- correlation: 헬퍼가 정한다. 요청의 correlation id가 `IntegrationIdentity` 문법·길이에 맞으면 그것,
|
||||
아니면 event id. 문법 밖 헤더가 업무 쓰기를 실패시키지 않는다. 값을 미리 검사해야 하면 문법을 베끼지
|
||||
말고 `IntegrationIdentity.isCanonical(value, IntegrationIdentity.CORRELATION_MAX_LENGTH)`를 부른다
|
||||
(aggregate id는 `AGGREGATE_ID_MAX_LENGTH`).
|
||||
- tenant 범위: tenant가 없는 기능은 `IntegrationEventDrafts.SINGLE_TENANT_SCOPE`(`global`).
|
||||
- aggregate 순서: `OutboxAggregateSequencePort.nextSequence(aggregate)`로 같은 `tx.inWrite` 안에서
|
||||
받는다(V21 카운터, 커밋 순서를 따른다). 이벤트가 하나뿐인 aggregate는 `AggregateOrder.first()`. 발생
|
||||
시각(벽시계)은 쓰지 않는다 — 서버 시계가 어긋나면 순서가 뒤집힌다(리뷰 06-07). 벽시계 번호를 쓰던
|
||||
서비스가 포트로 옮기면 V21 floor 덕분에 새 번호는 옛 번호 뒤에서 시작한다. 그래서 첫 번호가 1이
|
||||
아니라 약 1.7×10¹⁵일 수 있다. 소비자는 번호를 "마지막으로 본 값보다 큰가"로만 비교하고 연속성을
|
||||
가정하지 않는다. 비교는 aggregate identity(tenant scope 포함) 단위다. tenant scope를 바꾸는 배포는 옛
|
||||
버전 인스턴스를 모두 멈춘 뒤 새 버전을 띄운다 — 섞여 돌면 새 scope의 번호가 옛 버전이 방금 쓴 번호보다
|
||||
작을 수 있다(runbook `outbox-dead-letter.md` §8, 재리뷰 2차 RR-02-10).
|
||||
|
||||
## relay와 실패
|
||||
|
||||
- relay는 `composition:outbox-relay`가 `new`로 조립해 스케줄러에만 준다. relay는 `@SystemInvoked`라 권한
|
||||
선언이 없어서, bean이 되면 전송 계층이 **권한 검사 없이** 닿는다. 그래서 bean으로 등록하면
|
||||
`PermissionEnforcementGuard`가 기동을 실패시킨다(07장 「시스템이 부르는 쓰기」).
|
||||
- broker의 **재시도 가능한** 거부와 응답 없음은 DEAD가 아니라 backoff 재시도다. broker가 멈춰도 대량
|
||||
DEAD가 되지 않는다(1라운드 06-01·06-03). 대신 끝이 없다: 진짜 인증 오류, Kafka adapter가 이름을 모르는
|
||||
broker 거부도 영원히 재시도된다. 행의 `last_failure_code`와 로그의 `error.reason`이 원인 코드를 남기고,
|
||||
`outbox.retry.long.size`가 오래 재시도 중인 행을 센다. 처분(보류·재개·skip)은 publish-failed runbook
|
||||
§4.1이다(재리뷰 RR-05-03).
|
||||
- 발행 응답을 못 받으면 결과 불명(`OutboxPublishAmbiguousException`) — 05장 규칙과 같다.
|
||||
- 운영: `docs/runbooks/outbox-dead-letter.md`, `docs/runbooks/outbox-publish-failed.md`.
|
||||
|
||||
## 소비 — 이벤트를 받는 쪽
|
||||
|
||||
같은 메시지는 두 번 이상 올 수 있다. 소비 쪽은 **inbox 예약과 업무 쓰기를 한 트랜잭션**에 묶어 효과를
|
||||
한 번으로 만든다.
|
||||
|
||||
```text
|
||||
Kafka ─▶ platform consumer ─▶ (INBOX_TRANSACTIONAL이면) InboxMessageHandler
|
||||
└─ 한 트랜잭션: messaging_inbox 예약 + handler ─▶ use case 쓰기
|
||||
성공 → 커밋 → offset 커밋
|
||||
예외·Retry → 예약과 쓰기가 함께 롤백 → 같은 메시지 재전달 → 다시 처리
|
||||
이미 예약된 메시지 → handler를 부르지 않고 성공으로 넘김
|
||||
```
|
||||
|
||||
### 순서
|
||||
|
||||
1. 조립에 한 줄 추가: `runtimeOnly project(':adapter:inbound:messaging')`(app-bootstrap). Kafka
|
||||
capability(`adapter:outbound:messaging-kafka`)와 persistence-jpa가 함께 있어야 한다. 이 leaf가 inbox
|
||||
저장소와 트랜잭션 runner를 서비스의 DataSource·트랜잭션 위에 조립한다.
|
||||
2. inbox 테이블은 따로 만들지 않는다: 1번 줄의 leaf가 기동 중에 platform의
|
||||
`db/migration/messaging/V1101__messaging_inbox.sql`을 자기 history 표(`flyway_messaging_inbox_history`)로
|
||||
적용한다. `app.runtime.migration-on-startup=false`로 마이그레이션을 밖에서 돌리는 배포만 이 파일을 직접
|
||||
적용한다.
|
||||
3. destination을 선언한다: `guarantees.external-side-effect: INBOX_TRANSACTIONAL`, `consumer.group`,
|
||||
`retry.mode`·`retry.max-attempts`, `dlq.destination`. 예: `src/adapter/inbound/messaging/README.md`.
|
||||
4. 쓰기 use case와 handler를 만든다. 소비 스레드에는 인증이 없어서 `@RequiresPermission` use case는
|
||||
매번 거부된다. 그래서 handler가 부르는 쓰기 use case는 `@SystemInvoked`이고, handler는 그 use case를
|
||||
**직접 `new`로 만들어 혼자 들고 있는** `@SystemCaller`다(07장 「시스템이 부르는 쓰기」). 이 방법 하나만
|
||||
기동 가드와 빌드 규칙을 모두 통과한다.
|
||||
- use case: `@SystemInvoked(reason = ...)` + `@UseCaseCapability(WRITE, …, WRITE_REPOSITORY)`. 평소처럼
|
||||
`tx.inWrite`로 쓰고, 바깥 inbox 트랜잭션에 합류한다. 업무 규칙은 여기에 둔다.
|
||||
- handler(`MessageHandler<T>`): `adapter:inbound:messaging`(또는 서비스의 `..adapter.inbound.messaging..`
|
||||
패키지)에 두고 `@SystemCaller(reason = ...)`를 단다. 생성자가 port를 받아 use case를 만든다.
|
||||
delivery 하나를 use case 호출 하나로 바꾼다.
|
||||
- bean은 handler 하나다. use case를 bean으로 등록하면 `PermissionEnforcementGuard`가 기동을 막는다.
|
||||
표시 없이 use case에 의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 빌드를 막는다.
|
||||
|
||||
```java
|
||||
@SystemCaller(reason = "order-events 소비자: platform consumer 스레드만 부른다")
|
||||
public final class OrderCreatedHandler implements MessageHandler<OrderCreatedEnvelope> {
|
||||
private final ProjectOrderUseCase useCase; // @SystemInvoked, bean 아님
|
||||
|
||||
public OrderCreatedHandler(TransactionPort tx, OrderProjectionPort projections) {
|
||||
this.useCase = new ProjectOrderUseCase(tx, projections);
|
||||
}
|
||||
// destination(), handle(delivery) → useCase.project(...)
|
||||
}
|
||||
|
||||
@Bean // 이 leaf의 설정 클래스
|
||||
OrderCreatedHandler orderCreatedHandler(TransactionPort tx, OrderProjectionPort projections) {
|
||||
return new OrderCreatedHandler(tx, projections);
|
||||
}
|
||||
```
|
||||
|
||||
같은 쓰기를 사용자 요청(HTTP 등)도 부르면 use case를 둘로 나눈다. 사용자용은 `@RequiresPermission`,
|
||||
소비용은 `@SystemInvoked`이고 업무 규칙은 domain에 둔다. payload는 다른 서비스가 보낸 입력이므로 use
|
||||
case가 검증한다 — 권한 검사가 없다는 것이지 검증이 없다는 것이 아니다.
|
||||
5. payload 타입을 정한다. 템플릿 relay가 보낸 메시지의 payload는 canonical envelope JSON 전체다
|
||||
(`eventId`, `payload` 등). handler의 record는 그 모양이다. 등록 코드는 쓰지 않는다: handler의
|
||||
`destination()`(계약 id, record class)과 `schemaVersions()`(읽는 payloadVersion, 기본 v1)가 decode
|
||||
목록이 된다. 발행 쪽이 v2를 보내기 시작하면 handler가 `schemaVersions()`에 v2를 더한다 — 선언하지 않은
|
||||
버전은 `SCHEMA_VERSION_NOT_REGISTERED`로 DLQ에 간다.
|
||||
6. 테스트 본보기: `SystemInvokedConsumePathTest`(단위, 4단계 모양이 권한 가드 아래에서 기동하고 delivery가
|
||||
use case에 한 번 닿는지, use case를 bean으로 두면 기동이 막히는지)와 `InboxRedeliveryIntegrationTest`
|
||||
(lane `messagingInboxRedeliveryIntegrationTest`, 실제 Kafka + PostgreSQL, 같은 handler 모양). offset을
|
||||
되감아 다시 전달해도, 처리 중 예외 뒤 재전달돼도 효과와 inbox 행이 하나인지 본다.
|
||||
|
||||
### 판단 지점
|
||||
|
||||
#### 멱등 키
|
||||
|
||||
- **기본값**: inbox가 message id(발행 쪽 event id)와 `consumer.group`으로 거른다. handler가 따로 할
|
||||
일은 없다.
|
||||
- `consumer.group`은 바꾸지 않는다. 이름이 바뀌면 이미 처리한 메시지도 처음 보는 것으로 본다.
|
||||
- **예외**: 발행 쪽이 재시도마다 다른 event id를 낸다면 inbox가 못 거른다. 그때는 use case가 업무
|
||||
키(주문 id + 상태 등)로 멱등하게 쓴다.
|
||||
- 쓰기는 handler를 부른 스레드에서 끝낸다. 다른 스레드로 넘긴 쓰기는 inbox 트랜잭션 밖이다.
|
||||
- 메일·외부 API 같은 DB 밖 부작용은 롤백되지 않는다. handler 안에서는 DB 쓰기와 outbox append만 하고,
|
||||
외부 호출은 그 이벤트를 받는 별도 소비자가 한다.
|
||||
|
||||
#### inbox 보존 기간
|
||||
|
||||
- inbox 행은 broker가 같은 메시지를 다시 줄 수 있는 기간보다 오래 남아야 한다. 먼저 지우면 늦게 온
|
||||
재전달이 효과를 한 번 더 낸다.
|
||||
- **기본값**: `InboxRetentionPolicy` — 보존 7일, 재전달 창 1일. topic 보존 기간이나 offset을 되감는 운영
|
||||
범위가 1일보다 길면 이 bean을 덮어쓴다. 너무 짧은 조합은 기동 때 `INBOX_RETENTION_TOO_SHORT`로 거부된다.
|
||||
- 정리 job(`InboxCleanupJob`)은 bean만 있다. 어느 replica에서 언제 돌릴지는 서비스가 스케줄한다.
|
||||
|
||||
#### 실패 시 재처리
|
||||
|
||||
- handler가 예외를 던지거나 `Retry`로 답하면 예약과 쓰기가 함께 롤백되고, platform이 같은 메시지를
|
||||
다시 준다. 다시 처리될 때 효과는 한 번이다.
|
||||
- **기본값**: destination retry는 `NONE`(시도 1회)이라 실패하면 바로 DLQ로 간다. 일시 장애가 있는
|
||||
소비자는 `retry.mode: PAUSE_PARTITION`과 `max-attempts`를 정한다. partition 순서는 유지된다.
|
||||
- 다시 해도 소용없는 입력(검증 실패)은 예외 대신 `Reject`·`DeadLetter`로 답한다. 예외는 시도를 다 쓴
|
||||
뒤에야 DLQ로 간다.
|
||||
- DLQ가 없는 destination은 실패한 메시지 뒤에서 partition이 멈춘다. 운영 소비자는 DLQ를 둔다.
|
||||
- offset을 되감아 다시 읽혀도 보존 기간 안의 메시지는 inbox가 건너뛴다.
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 저장과 append는 같은 `tx.inWrite` 안.
|
||||
- 계약(id·버전·schema·해시)을 먼저 정하고 계약 bean을 등록한다.
|
||||
- 전달은 적어도 한 번. 소비자는 inbox(`INBOX_TRANSACTIONAL`)로 예약과 업무 쓰기를 한 트랜잭션에 묶는다.
|
||||
- 실패한 처리는 예약까지 롤백되어 재전달에서 다시 처리된다. inbox 보존 기간은 재전달 창보다 길게.
|
||||
- 소비 handler = `@SystemCaller` + `@SystemInvoked` use case를 직접 `new`. use case는 bean이 아니다.
|
||||
@@ -0,0 +1,65 @@
|
||||
# 10. capability 추가·제거
|
||||
|
||||
## 핵심
|
||||
|
||||
JPA·Redis·Kafka·알림·파일 서버 같은 부가 기능은 **의존성 한 줄로 켜지고, 그 줄을 지우면 사라지는
|
||||
모듈**이다. 서비스는 `src/app-bootstrap/build.gradle`에서 필요한 모듈만 `runtimeOnly`로 고른다.
|
||||
기본 조립은 web, 운영 관측, cores, support/identifier뿐이다. JPA도 한 줄로 켠다.
|
||||
|
||||
```text
|
||||
app-bootstrap/build.gradle
|
||||
runtimeOnly project(':adapter:outbound:persistence-jpa') ← 이 한 줄
|
||||
│
|
||||
▼
|
||||
모듈의 META-INF/spring/...AutoConfiguration.imports → 자동 설정 → 포트 구현 bean
|
||||
│
|
||||
▼
|
||||
기능 XConfig의 @ConditionalOnBean(포트) → 유스케이스·엔드포인트가 켜진다
|
||||
```
|
||||
|
||||
정본: `AGENTS.md` 「부가 기능(capability) 모듈 규칙」(완료 기준 7개),
|
||||
`docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md`, 현황은 `docs/capability-status.md`.
|
||||
|
||||
## 켜기
|
||||
|
||||
1. `src/app-bootstrap/build.gradle`의 해당 `runtimeOnly` 줄 주석을 푼다.
|
||||
2. lockfile 갱신: `./gradlew :app-bootstrap:resolveAndLockAll --write-locks`, 확인
|
||||
`./gradlew verifyDependencyLocks`.
|
||||
3. 모듈 README의 env 키를 채운다. 키 목록 정본은 `docs/registries/env-keys.yaml`.
|
||||
4. 기본값은 `config/module-defaults/<모듈>.yml`에 이미 있다. 서비스 값만 덮어쓴다.
|
||||
5. `./gradlew :app-bootstrap:check architectureCheck`. 공개 경로가 생기면 `verifyPublicPathSnapshot`.
|
||||
|
||||
## 끄기
|
||||
|
||||
줄을 지우고 lockfile을 갱신한다. 그 모듈의 포트에 기대던 기능(`@ConditionalOnBean`)은 함께 꺼진다.
|
||||
기능이 꺼지면 안 되는데 꺼졌다면, 그 기능이 다른 구현을 가져야 한다는 신호다.
|
||||
|
||||
## 판단: 서비스 코드가 모듈 타입을 직접 불러도 되나
|
||||
|
||||
- **기본값**: 안 된다. 서비스 코드는 application-core 포트만 부른다. 그래야 `runtimeOnly`로 받을 수 있다.
|
||||
- **예외**: 라이브러리형 기능(모듈 타입을 상속·호출해야 하는 것)은 서비스의 adapter leaf에서만
|
||||
`implementation`으로 받는다. 예: 서비스 persistence leaf가 `persistence-jpa`의 감사 base 타입을 상속.
|
||||
|
||||
## 새 capability 모듈을 만들 때
|
||||
|
||||
03장에서 ②(기능 leaf)를 골랐을 때만 해당한다. 완료 기준 7개를 모두 지킨다.
|
||||
|
||||
| # | 기준 | 확인 |
|
||||
| --- | --- | --- |
|
||||
| 1 | 서비스는 포트만 호출 | `runtimeOnly`로 컴파일되는가 |
|
||||
| 2 | 자기 `AutoConfiguration.imports`, 필요하면 `enabled` 스위치, 순서는 `afterName` | 모듈 자동 설정 테스트 |
|
||||
| 3 | 켜면 완전히 동작. 동작하지 않는 설정 키는 두지 않는다 | 설정 바인딩 테스트 |
|
||||
| 4 | 설정 prefix 하나(`app.<모듈>`), `StrictSettingsBinder`, 검증은 record compact constructor | Redis만 예외(AGENTS.md 기준 4) |
|
||||
| 5 | 포트 계약 테스트를 fake와 실제 adapter가 모두 통과, 실 벤더(Testcontainers) 1개 이상 | strict lane(08장) |
|
||||
| 6 | README: 제공하는 것, 추가할 한 줄, env 키 | |
|
||||
| 7 | 이 모듈을 아는 곳은 모듈 자신뿐. bootstrap scan·스위치 목록에 등록하지 않는다 | 줄을 지우면 기능이 완전히 사라지는가 |
|
||||
|
||||
등록할 공용 파일: `src/config/architecture/modules.json`(leaf와 허용 edge), `src/settings.gradle`이 읽는
|
||||
디렉터리 매핑, app-bootstrap의 허용 edge, 새 leaf lockfile. registry가 허용하지 않은 edge는
|
||||
`architectureCheck`(의존 방향)가 막는다.
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 켜기 = `runtimeOnly` 한 줄 + lockfile + env 키.
|
||||
- 서비스 코드는 포트만 부른다.
|
||||
- 새 capability는 완료 기준 7개. 업무 기능은 capability로 만들지 않는다(03장).
|
||||
@@ -0,0 +1,67 @@
|
||||
# 11. 체크리스트 — PR 올리기 전
|
||||
|
||||
빠진 것이 있으면 해당 장으로 돌아간다. 검사 명령은 `src/`에서 실행한다.
|
||||
|
||||
## 배치·이름
|
||||
|
||||
- [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `<feature>` 패키지).
|
||||
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
|
||||
- [ ] 이름이 `src/application-core/CLAUDE.md` 「Naming convention」을 따른다.
|
||||
|
||||
## domain
|
||||
|
||||
- [ ] 불변식은 aggregate 안에 있고, 위반은 `XInvariantException(Reason)`이다.
|
||||
- [ ] id 문법은 id 값 객체 생성자가 검사한다.
|
||||
- [ ] Spring·JPA·전송 타입을 import하지 않는다.
|
||||
|
||||
## application
|
||||
|
||||
- [ ] 모든 유스케이스에 `@UseCaseCapability`, 선언과 `TransactionPort` 호출이 맞다.
|
||||
- [ ] 쓰기 유스케이스: `@RequiresPermission`, non-final, bean으로 조립.
|
||||
- [ ] 외부 호출은 트랜잭션 밖이다.
|
||||
- [ ] 멱등성 선언을 05장 기준으로 골랐다(재전송될 쓰기는 `KEYED`).
|
||||
- [ ] 클라이언트 탓 실패는 carrier 예외 + 기능 코드, 서버 탓은 `IllegalStateException`.
|
||||
|
||||
## persistence
|
||||
|
||||
- [ ] 저장 adapter가 서비스 전용 persistence leaf에 있다(persistence-jpa 아님).
|
||||
- [ ] 연관관계는 한쪽만(`mappedBy` 없음).
|
||||
- [ ] 중복 규칙은 DB 유일성 제약이 막고, adapter가 그 제약 위반만 기능 예외로 바꾼다.
|
||||
- [ ] 여러 인스턴스가 집는 작업은 트랜잭션 안 claim + lease.
|
||||
- [ ] 마이그레이션은 자기 스트림(자기 history table)에 있고, 적용된 파일을 고치지 않았다.
|
||||
- [ ] adapter가 `XRepositoryContract`를 실 DB lane에서 상속한다.
|
||||
|
||||
## inbound
|
||||
|
||||
- [ ] 컨트롤러는 변환만 한다. repository·엔티티를 모른다.
|
||||
- [ ] 경로는 lowerCamel 복수형(AIP-122). 생성은 201 + `Location`.
|
||||
- [ ] 도메인 규칙을 DTO bean validation에 다시 쓰지 않았다.
|
||||
|
||||
## 조립·권한
|
||||
|
||||
- [ ] `XConfig`가 `@ConditionalOnBean(포트)`이고 imports에 한 줄 있다. 포트가 다른 자동 설정에서 오면 `afterName`.
|
||||
- [ ] 역할 → 권한 매핑을 `app.authz.role-permissions`에 더했다.
|
||||
- [ ] 객체 단위 판정이 필요하면 유스케이스 안에서 하고, 남의 것은 404.
|
||||
|
||||
## 이벤트
|
||||
|
||||
- [ ] 저장과 outbox append가 같은 `tx.inWrite` 안이다.
|
||||
- [ ] 계약 id·버전·schema·해시를 정했고 계약 bean을 등록했다.
|
||||
|
||||
## 테스트
|
||||
|
||||
- [ ] 포트마다 fake 하나와 공유 계약이 포트 소유 leaf testFixtures에 있다.
|
||||
- [ ] 이름은 행동 문장, `@DisplayName`은 필요할 때만 한국어, GWT 주석, `// when` 하나.
|
||||
- [ ] Docker가 필요한 테스트는 strict lane이고 단계가 있다.
|
||||
|
||||
## 검사
|
||||
|
||||
```bash
|
||||
./gradlew <owner-leaf>:check --console=plain # 건드린 leaf마다
|
||||
./gradlew architectureCheck --console=plain # leaf 경계를 넘었으면
|
||||
./gradlew verifyPublicPathSnapshot # 공개 경로가 바뀌었으면
|
||||
./gradlew :app-bootstrap:verifyEnvKeys # env 키가 바뀌었으면
|
||||
./gradlew verifyDependencyLocks # 의존성이 바뀌었으면
|
||||
```
|
||||
|
||||
- [ ] 실행한 명령과 결과를 PR 본문 「검증」에 적었다. 못 돌린 것은 이유와 함께 적었다.
|
||||
@@ -0,0 +1,82 @@
|
||||
# 개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점
|
||||
|
||||
이 매뉴얼은 **새 업무 기능을 추가하는 사람**이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다
|
||||
무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 **가리키고**
|
||||
작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).
|
||||
|
||||
판단 지점은 모두 같은 틀로 적는다.
|
||||
|
||||
- **고르는 기준** — 무엇을 보고 고르는가
|
||||
- **기본값** — 기준이 애매하면 이것
|
||||
- **예외** — 기본값을 벗어나도 되는 경우와 그때 같이 해야 하는 것
|
||||
|
||||
근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다.
|
||||
|
||||
## 읽는 순서
|
||||
|
||||
처음이면 1 → 2 → 3을 읽고 생성 명령을 한 번 돌려 본다. 그다음은 기능에 필요한 장만 읽는다.
|
||||
|
||||
| 장 | 언제 읽나 |
|
||||
| --- | --- |
|
||||
| [01. 생성 명령](01-generator.md) | 새 기능 뼈대를 만들 때. 무엇을 만들고 무엇을 안 만드는지 |
|
||||
| [02. 새 도메인·유스케이스 추가](02-new-feature.md) | 기능 하나를 domain → application → outbound → inbound → bootstrap 순서로 만들 때 |
|
||||
| [03. 새 기능을 둘 곳 고르기](03-placement.md) | 계층 leaf 안 패키지 / `application-*` capability / 별도 수직 중 고를 때 |
|
||||
| [04. 영속성](04-persistence.md) | 저장 adapter, 엔티티 매핑, DB 제약과 충돌 변환, 마이그레이션 번호 |
|
||||
| [05. 멱등성·결과 불명](05-idempotency.md) | 재시도될 수 있는 쓰기, 409/422, `DB_COMPLETION_UNKNOWN` |
|
||||
| [06. 오류 모델](06-errors.md) | 실패를 클라이언트 탓/서버 탓으로 나누고 코드로 내보낼 때 |
|
||||
| [07. 권한](07-authorization.md) | `@RequiresPermission`, 역할 매핑, 객체 단위 인가 |
|
||||
| [08. 테스트 작성 규칙](08-testing.md) | 포트당 fake, 공유 계약, 이름·주석, lane 단계 지정 |
|
||||
| [09. outbox·이벤트](09-outbox-events.md) | 저장과 함께 이벤트를 내보낼 때 |
|
||||
| [10. capability 추가·제거](10-capabilities.md) | JPA·Redis·Kafka 같은 부가 기능을 켜고 끌 때 |
|
||||
| [11. 체크리스트](11-checklist.md) | PR 올리기 전 |
|
||||
| [부록. 공통 원칙 후보](appendix-common-principles.md) | 프론트·백엔드 공통 실무 원칙으로 옮길 후보 |
|
||||
|
||||
## 정본 위치
|
||||
|
||||
매뉴얼과 정본이 다르면 정본이 맞다. 매뉴얼을 고친다.
|
||||
|
||||
| 무엇 | 정본 |
|
||||
| --- | --- |
|
||||
| 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(요약은 `CLAUDE.md`) |
|
||||
| leaf 목록·허용 의존 | `src/config/architecture/modules.json` |
|
||||
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/CLAUDE.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
|
||||
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/CLAUDE.md` 「Canonical use case shape」「Allowed transactional shapes」 |
|
||||
| HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` |
|
||||
| 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` |
|
||||
| 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` |
|
||||
| capability 완료 기준 7개 | `AGENTS.md` 「부가 기능(capability) 모듈 규칙」 |
|
||||
|
||||
이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 **따른 결과**를 보여 줄 뿐이고,
|
||||
규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(`scripts/feature-scaffold/templates/`)이 규칙과
|
||||
어긋나면 `scripts/verify-feature-scaffold.sh`가 ArchUnit으로 잡는다.
|
||||
|
||||
## 따라 할 예시는 하나
|
||||
|
||||
예시가 셋(sample-portfolio 수직, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라
|
||||
배치가 달라졌다(리뷰 2026-11-01 01-01·07-09). 이제 **새 업무 기능의 예시는 생성 명령의 출력 하나**다.
|
||||
|
||||
| 코드 | 역할 | 따라 하나 |
|
||||
| --- | --- | --- |
|
||||
| `scripts/new-feature.sh` 출력 | 계층 leaf에 나눈 업무 기능 | **이것을 따른다** |
|
||||
| `src/sample-portfolio` | 한 leaf에 모든 계층을 둔 지울 수 있는 샘플. 개별 기법(조건부 PATCH, 페이지, outbox, DB 유일성 제약)의 참고 | 기법만 본다. 배치는 따르지 않는다 |
|
||||
| `src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/**` | ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture | 따르지 않는다 |
|
||||
| `application-core/.../operation` + `DurableOperationAutoConfiguration`(composition:durable-operation) | 템플릿 플랫폼 기능 | 조립 모양(`@ConditionalOnBean` + 유스케이스 `@Bean`)만 본다 |
|
||||
|
||||
## 1라운드 수정으로 생긴 패턴 (리뷰 README 13절)
|
||||
|
||||
리뷰 뒤 1라운드에서 굳은 모양이다. 각 장에 반영했다.
|
||||
|
||||
| 패턴 | 근거 코드 | 장 |
|
||||
| --- | --- | --- |
|
||||
| Envelope는 null 필드를 내보내지 않는다 | `docs/web/http-contract.md` 1절 | 06 |
|
||||
| 처리 중 409 `IDEMPOTENT_IN_FLIGHT`는 `retryable=true` + `Retry-After: 2`, 같은 키로 재전송 | `docs/web/http-contract.md` 2절 | 05 |
|
||||
| 커밋 중 연결이 끊기면 재시도 가능이 아니라 결과 불명(`DB_COMPLETION_UNKNOWN`, 500) | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java`, `docs/adr/ADR-JPA-003-completion-unknown.md` | 05 |
|
||||
| 중복 규칙은 조회 후 insert가 아니라 DB 유일성 제약, 위반은 같은 409로 변환 | `src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql`, `PosterRepositoryAdapter` | 04 |
|
||||
| 여러 인스턴스가 집는 작업은 lease 있는 claim | `ReconciliationJobStorePort.claimDue`(application-notification) | 04 |
|
||||
| 양방향 연관관계 금지를 ArchUnit으로 | `JpaArchitectureRules.associationsAreMappedFromOneSideOnly()` | 04 |
|
||||
| store는 호출자 트랜잭션을 요구한다 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/CallerTransaction.java` | 04 |
|
||||
| `@RequiresPermission` 검사는 인증 체인과 분리된 자동 설정 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java` | 07 |
|
||||
| JWT audience 필수, 자기 client role만 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/JwtDecoderConfig.java`, `docs/runbooks/auth-audience-mismatch.md` | 07 |
|
||||
| strict lane은 반드시 어떤 단계에 속한다 | `verifyStrictLaneStages`(`src/build.gradle` `strictLaneStages`) | 08 |
|
||||
| 샘플 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 | `SamplePostgreSqlPersistenceConfig`, `V8_1__…` | 04 |
|
||||
| 재시도 가능한 broker 거부는 DEAD가 아니라 재시도 | `docs/runbooks/outbox-dead-letter.md` | 09 |
|
||||
@@ -0,0 +1,20 @@
|
||||
# 부록. 프론트·백엔드 공통 원칙 후보
|
||||
|
||||
사용자 결정(2026-11-01): 프론트·백엔드에 공통인 실무 원칙은 `desktop-server-git/design-docs/`에 둔다.
|
||||
그 위치는 이 repo 밖이라 여기서 쓰지 않는다. 이 매뉴얼을 쓰며 나온 **후보만** 적는다. 옮길 때는 원칙
|
||||
문장만 옮기고, 이 repo의 장은 그 원칙을 가리키도록 바꾼다(두 벌을 두지 않는다).
|
||||
|
||||
| # | 후보 원칙 | 이 repo에서 드러난 곳 | 프론트 쪽 짝 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 결과를 증명할 수 없으면 "모른다"로 분류한다. "실패(재시도 가능)"로 적지 않는다 | 05장, `DB_COMPLETION_UNKNOWN`, outbox ambiguous | 요청 분류기의 timeout·네트워크 오류 처리 |
|
||||
| 2 | 같은 요청의 재전송은 같은 멱등성 키로. 새 키는 새 작업이다 | `docs/web/http-contract.md` 2절 | 재시도 정책, 409 in-flight 처리 |
|
||||
| 3 | 중복·경쟁은 저장소의 제약이 막는다. 앞선 조회는 빠른 거절일 뿐이다 | 04장 | 낙관적 UI 갱신과 서버 409 |
|
||||
| 4 | 같은 규칙을 두 곳에 쓰지 않는다. 쓸 수밖에 없으면 하나가 다른 하나를 검사한다 | DTO 검증 vs aggregate(02장), 오류 코드 registry 대조 테스트 | 폼 검증 스키마 vs 서버 검증 |
|
||||
| 5 | 실패는 클라이언트 탓/서버 탓으로 먼저 나누고, 클라이언트에는 안정된 코드만 보낸다 | 06장 | 오류 코드 → 화면 문구 매핑 |
|
||||
| 6 | 권한이 없으면 닫힌 쪽이 기본이다(매핑 전 403, 남의 것은 404) | 07장 | 권한 없는 메뉴·라우트 숨김과 서버 거절 |
|
||||
| 7 | 계약은 버전·schema·해시로 고정하고, 바꾸면 소비자 계약 테스트가 깨진다 | 09장, Envelope wire 테스트 | 응답 스키마 strict 파싱 |
|
||||
| 8 | 포트(경계)마다 대역 하나, 대역과 실제가 같은 계약 테스트를 통과한다 | 08장 | API mock과 실제 서버의 계약 테스트 |
|
||||
| 9 | 선택 기능은 한 줄로 켜고 한 줄로 끈다. 그 기능을 아는 곳은 자기 자신뿐이다 | 10장 | feature flag·라우트 모듈 |
|
||||
| 10 | 위험은 코드에 드러나야 한다: 의도한 제약·생략은 주석과 테스트 이름에 적는다 | 생성 명령 템플릿의 Javadoc(`NOT_IDEMPOTENT` 이유 등) | 같음 |
|
||||
| 11 | 게이트는 지우지 않고 단계를 지정한다(PR / main / nightly) | 08장 lane 단계, `verifyStrictLaneStages` | 프론트 CI 단계 |
|
||||
| 12 | 선택지가 여럿이면 고른 것·버린 것·이유를 남긴다 | 각 장의 「고른 형태와 버린 대안」 | 같음 |
|
||||
@@ -26,7 +26,9 @@ producing-service identity다.
|
||||
|
||||
## Outbox
|
||||
|
||||
outbox는 canonical 하나다(2026-09-28). use case가 `IntegrationEventEncoderPort`로 만든
|
||||
application의 발행 경로는 하나다(2026-09-28): `outbox_event` 표와 `composition:outbox-relay`. vendored
|
||||
platform의 `messaging_outbox`(`outbox-inbox.md`)는 이 경로에 쓰이지 않는다 — 두 모델의 상태 대응은
|
||||
`outbox-inbox.md` 머리의 표에 있다. use case가 `IntegrationEventEncoderPort`로 만든
|
||||
`ValidatedIntegrationEvent`를 `OutboxAppendPort`로 append하고, relay는 claim한 row의 exact envelope
|
||||
bytes를 `IntegrationEventPublishPort`로 보낸다. 예전의 `app.outbox.canonical-transport-enabled`
|
||||
gate와 legacy `MessageBroker → KafkaSender` 경로는 삭제됐다. 발행할 contract의 logical destination마다
|
||||
|
||||
@@ -19,7 +19,12 @@ public enum PublishCompletion { CONFIRMED, REJECTED, AMBIGUOUS }
|
||||
```
|
||||
|
||||
`REJECTED`와 `AMBIGUOUS`를 하나의 "실패"로 합치면 중복 주문이 만들어진다.
|
||||
전자는 broker가 저장하지 않았음이 **확정**되어 포기해도 안전하고, 후자는 그렇지 않다.
|
||||
전자는 broker가 저장하지 않았음이 **확정**되어 중복 걱정 없이 다시 보내거나 포기할 수 있고, 후자는 그렇지 않다.
|
||||
|
||||
`REJECTED`가 곧 "포기해도 된다"는 뜻은 아니다. 거부 이유가 그 순간에 속하면(종료 중
|
||||
`SHUTTING_DOWN`, permit 대기 초과, `PUBLISH_RUNTIME_UNAVAILABLE`, `KAFKA_TRANSPORT_CLOSED`, Kafka
|
||||
인증·인가 실패) `failure().retryable()`이 true이고, 호출자는 같은 메시지를 나중에 다시 보내야 한다.
|
||||
포기해도 되는 것은 `retryable=false`인 거부뿐이다.
|
||||
|
||||
| 상황 | 결과 |
|
||||
|---|---|
|
||||
|
||||
@@ -1,5 +1,32 @@
|
||||
# Outbox · Inbox
|
||||
|
||||
> **이 문서의 Outbox는 vendored messaging platform의 outbox다**(`messaging_outbox` 표,
|
||||
> `messaging-reliability`의 `OutboxRelay`). 이 템플릿 application이 쓰는 outbox는 그것이 아니다.
|
||||
> application은 `outbox_event` 표(`adapter:outbound:persistence-jpa`)에 append하고, relay는
|
||||
> `composition:outbox-relay`가 돌린다. 그 동작과 운영은 `docs/manual/09-outbox-events.md`,
|
||||
> `src/composition/outbox-relay/README.md`, `docs/runbooks/outbox-dead-letter.md`,
|
||||
> `docs/runbooks/outbox-publish-failed.md`에 있다. platform outbox는 소유자 결정으로 제품 안에 남아
|
||||
> 있지만, platform outbox repository bean이 없으면 그 relay는 만들어지지 않는다(리뷰 2026-11-01 06-11).
|
||||
>
|
||||
> 두 모델은 같은 이름의 상태가 반대 뜻이다. 이름으로 옮기면 확정 거부는 영원히 재시도되고 응답 없는
|
||||
> 메시지는 버려진다. 대응은 아래 표 하나로만 읽는다(`OutboxPublishOutcome` Javadoc과 같은 내용).
|
||||
>
|
||||
> | 일어난 일 | application `outbox_event` | platform `messaging_outbox` |
|
||||
> |---|---|---|
|
||||
> | broker가 확인했다 | `PUBLISHED` | `PUBLISHED` |
|
||||
> | 응답이 없었다(저장됐을 수 있음) | `FAILED`(재시도, 예산 안 씀, 끝 없음) | `AMBIGUOUS`(재시도, 예산을 다 쓰면 `EXHAUSTED`) |
|
||||
> | 지금만 거부됐다(종료·포화·credential) | `FAILED`(재시도, 예산 안 씀, 끝 없음) | `FAILED`(종단) |
|
||||
> | 확정 거부됐다(같은 payload는 또 거부) | `DEAD`(종단, 수동 처분) | `FAILED`(종단) |
|
||||
> | publisher가 예외를 던졌고 시도 예산을 다 썼다 | `DEAD`(종단, 수동 처분) | `EXHAUSTED`(종단) |
|
||||
> | 운영자가 재시도를 멈췄다 | `PARKED`(수동 재개·skip) | 없음 |
|
||||
>
|
||||
> **이 템플릿 application의 소비 경로**: application의 `MessageHandler`와 inbox 부품(애플리케이션
|
||||
> DataSource 위 `JdbcInboxRepository`, `PlatformTransactionManager` 위 `TransactionRunner`)은
|
||||
> `adapter:inbound:messaging`(`src/adapter/inbound/messaging/README.md`)이 둔다. platform starter는 두
|
||||
> bean이 있을 때 `IdempotentConsumer`를 만들어 `INBOX_TRANSACTIONAL` destination의 handler를 감싼다.
|
||||
> 그 leaf는 inbox 마이그레이션(`V1101`)만 자기 history 표로 적용하므로, 아래 "location 추가"는 platform
|
||||
> outbox를 쓰는 배포의 이야기다. payload decode 목록은 handler bean의 선언으로 만든다.
|
||||
|
||||
## 두 패턴이 각각 무엇을 해결하는가
|
||||
|
||||
| 패턴 | 해결하는 문제 | 해결하지 않는 문제 |
|
||||
@@ -125,6 +152,11 @@ consume 계약은 `MessageHandler<T>` 하나다. handler를 bean으로 등록하
|
||||
- `Reject`는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다.
|
||||
|
||||
실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다.
|
||||
애플리케이션 경로(앱 outbox relay가 발행 → `adapter:inbound:messaging`이 조립한 inbox와 JPA 트랜잭션 →
|
||||
handler)의 중복 전달·실패 재처리는 `InboxRedeliveryIntegrationTest`(lane
|
||||
`messagingInboxRedeliveryIntegrationTest`)가 확인한다. 애플리케이션 handler가 쓰기 use case를 부르는 방법
|
||||
(`@SystemCaller` handler가 `@SystemInvoked` use case를 직접 만든다)은 `docs/manual/09-outbox-events.md`
|
||||
「소비」 4단계다.
|
||||
|
||||
### 복합 키
|
||||
|
||||
|
||||
@@ -0,0 +1,144 @@
|
||||
# Mongo 소비 leaf 등록 절차
|
||||
|
||||
파생 서비스가 `adapter:outbound:persistence-mongo`를 실제로 쓰려면 **자기 Mongo 어댑터 leaf**를 하나
|
||||
만든다. 이 leaf(이하 "플랫폼 leaf")는 client·template·정책·실패 분류를 주고, document·repository·
|
||||
mapper·port 구현은 서비스 leaf가 가진다. 플랫폼 leaf에는 예시 도메인을 production으로 넣지 않는다
|
||||
(`src/adapter/outbound/persistence-mongo/CLAUDE.md` "Forbidden").
|
||||
|
||||
전체 흐름:
|
||||
|
||||
```text
|
||||
domain-core (Note) application-core (NoteStore port)
|
||||
\ /
|
||||
adapter:outbound:persistence-note ← 서비스가 새로 만드는 leaf
|
||||
NoteDocument / NoteDocumentMapper / NoteDocumentRepository / MongoNoteStore
|
||||
|
|
||||
| implementation
|
||||
v
|
||||
adapter:outbound:persistence-mongo ← 플랫폼 leaf (executor, 실패 분류, 정책)
|
||||
^
|
||||
| runtimeOnly (둘 다)
|
||||
app-bootstrap
|
||||
```
|
||||
|
||||
## 1. 동작하는 예시
|
||||
|
||||
예시 한 벌이 플랫폼 leaf의 테스트 소스에 있다. `mongoStableContractTest`(그래서 `check`)에서
|
||||
컴파일되고 실행되므로 API가 바뀌면 예시도 같이 깨진다.
|
||||
|
||||
| 역할 | 예시 타입 | 실제 서비스에서 둘 곳 |
|
||||
| --- | --- | --- |
|
||||
| 도메인 타입 | `Note` | `domain-core` |
|
||||
| outbound port, 도메인 예외 | `NoteStore`, `NoteStore.NoteAlreadyExistsException` | `application-core` |
|
||||
| 저장 형태 | `NoteDocument` (`@Document`, `@Id`, `@Field`) | 서비스 Mongo leaf |
|
||||
| 변환 | `NoteDocumentMapper` | 서비스 Mongo leaf |
|
||||
| collection 접근 | `NoteDocumentRepository` (`DefaultMongoImperativeExecutor` 사용) | 서비스 Mongo leaf |
|
||||
| port 구현, 예외 변환 | `MongoNoteStore` | 서비스 Mongo leaf |
|
||||
| 실행 확인 | `MongoNoteStoreExampleTest` | 서비스 Mongo leaf 테스트 |
|
||||
|
||||
위치: `src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/example/`.
|
||||
|
||||
testFixtures가 아니라 테스트 소스에 둔 이유: testFixtures는 소비 leaf의 테스트 classpath에 그대로
|
||||
올라가는 variant다. 예시 타입이 거기 있으면 API처럼 import된다. 테스트 소스는 아무 데도 export되지 않는다.
|
||||
|
||||
## 2. 레지스트리와 Gradle에 leaf 등록
|
||||
|
||||
leaf 목록과 허용 의존 방향의 원본은 `src/config/architecture/modules.json`이다. 레지스트리에 없는 edge는
|
||||
`verifyCleanArchitectureDependencies`가 거부한다.
|
||||
|
||||
1. `modules.json`의 `modules`에 서비스 leaf를 추가한다. 플랫폼 leaf로 가는 edge를 여기서 연다.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "adapter-outbound-persistence-note",
|
||||
"gradle_path": ":adapter:outbound:persistence-note",
|
||||
"source_path": "src/adapter/outbound/persistence-note",
|
||||
"allowed_dependencies": [
|
||||
"domain-core",
|
||||
"application-core",
|
||||
"adapter-outbound-persistence-mongo"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
같은 모양의 선례: `adapter-outbound-persistence-notification`이 `adapter-outbound-persistence-jpa`를
|
||||
같은 방식으로 받는다.
|
||||
|
||||
2. `app-bootstrap`의 `allowed_dependencies`에 `"adapter-outbound-persistence-note"`를 더한다.
|
||||
`adapter-outbound-persistence-mongo`는 이미 들어 있다.
|
||||
|
||||
3. 서비스 leaf의 `build.gradle`:
|
||||
|
||||
```groovy
|
||||
dependencies {
|
||||
implementation project(':domain-core')
|
||||
implementation project(':application-core')
|
||||
implementation project(':adapter:outbound:persistence-mongo')
|
||||
}
|
||||
```
|
||||
|
||||
4. `app-bootstrap/build.gradle`에서 두 leaf를 켠다. 플랫폼 leaf 줄은 주석으로 이미 있다.
|
||||
|
||||
```groovy
|
||||
runtimeOnly project(':adapter:outbound:persistence-mongo')
|
||||
runtimeOnly project(':adapter:outbound:persistence-note')
|
||||
```
|
||||
|
||||
5. 확인: `./gradlew :adapter:outbound:persistence-note:check architectureCheck --console=plain`.
|
||||
|
||||
## 3. 서비스 leaf가 등록해야 하는 bean
|
||||
|
||||
자동 구성되는 `MongoCollectionProfileRegistry`는 **비어 있다**. 등록하지 않은 collection profile로
|
||||
executor를 부르면 거부된다. 서비스 leaf가 자기 collection을 등록한 registry bean을 준다.
|
||||
|
||||
```java
|
||||
@Bean
|
||||
MongoCollectionProfileRegistry mongoCollectionProfileRegistry() {
|
||||
return MongoCollectionProfileRegistry.builder()
|
||||
.register(NoteDocument.COLLECTION, NoteDocument.COLLECTION)
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
여러 서비스 leaf가 각자 collection을 가지면 registry bean은 하나여야 하므로 composition(보통
|
||||
`app-bootstrap`)에서 합친다.
|
||||
|
||||
`DefaultMongoImperativeExecutor`는 자동 구성 bean이다. 서비스 leaf는 그것을 주입받아
|
||||
`NoteDocumentRepository`처럼 감싼다.
|
||||
|
||||
## 4. 예외 변환
|
||||
|
||||
- executor는 driver·Spring 실패를 한 번만 플랫폼 예외로 바꾼다:
|
||||
`MongoDuplicateKeyException`, `MongoTimeoutException`, `MongoWriteConcernException`,
|
||||
`MongoServerSelectionException` 등(`dev.caskeleton.adapter.outbound.mongo.api.error`).
|
||||
- port 구현은 **port가 약속한 실패만** 도메인 예외로 바꾼다. 예시에서는
|
||||
`MongoDuplicateKeyException` → `NoteAlreadyExistsException` 하나다.
|
||||
- 나머지는 그대로 내보낸다. 플랫폼 예외는 `outcome()`·`ambiguous()`로 "쓰기가 됐는지 모름"을 알려
|
||||
준다. 이것을 일반 도메인 예외로 감싸면 호출자가 재시도해도 되는지 판단할 근거가 사라진다.
|
||||
- 트랜잭션은 `MongoTransactionRetryCoordinator`로 실행한다. 본문의 `TransientTransactionError`는 새
|
||||
세션에서 본문을 다시 실행하고, commit 결과를 모르면 commit만 재시도한 뒤
|
||||
`MongoTransactionCommitUnknownException`으로 알린다. 본문은 재실행될 수 있으므로 본문 안에서 외부
|
||||
호출(메시지 발행, HTTP)을 하지 않는다.
|
||||
|
||||
## 5. 정책을 우회하는 경로 — 쓰기 전에 알 것
|
||||
|
||||
| 경로 | 받는 것 | 잃는 것 |
|
||||
| --- | --- | --- |
|
||||
| `DefaultMongoImperativeExecutor` (+ `MongoAtomicOperationsTemplate`, `MongoBulkExecutor`) | operation 이름, collection profile 확인, consistency, deadline, 관측, 실패 변환 | 없음. 기본 경로 |
|
||||
| Spring Data `MongoRepository` (adapter-local) | 짧은 CRUD 코드 | 위 전부. 실패가 Spring `DuplicateKeyException` 등으로 온다. derived query는 `MongoQueryPolicy`를 거치지 않는다. deadline·consistency profile이 붙지 않는다 |
|
||||
| `MongoTemplate` / `MongoClient` 직접 주입 | 모든 명령 | 위 전부 + collection 범위 확인 |
|
||||
|
||||
- `MongoRepository`는 adapter leaf 안에서만 허용된다
|
||||
(`MongoRepositoryArchitectureRules.allowedRepositorySuperTypes`). 고르면 예외 변환과 timeout을 서비스
|
||||
leaf가 직접 책임진다. 플랫폼 공통 CRUD base(`CommonMongoRepository` 등)는 만들지 않는다.
|
||||
- 사용자 입력으로 조건이 바뀌는 **동적 조회**는 `PolicyAwareMongoQueryBuilder`(`MongoQueryPolicy`
|
||||
allowlist)로 만든다. 예시의 `_id` 조회처럼 adapter 코드가 고정한 조건은 `Query`를 직접 써도 된다.
|
||||
- inbound adapter(controller 등)는 `MongoTemplate`·`MongoClient`를 갖지 않는다. 서비스 leaf 테스트에서
|
||||
플랫폼 testFixtures의 `MongoAccessRules.noMongoAccessFrom(...)`으로 확인할 수 있다
|
||||
(`testImplementation testFixtures(project(':adapter:outbound:persistence-mongo'))`).
|
||||
|
||||
## 6. 연결 설정
|
||||
|
||||
URI만 주는 배포(`SPRING_MONGODB_URI`)는 유한 timeout·pool 기본값을 받는다. 값과 바꾸는 법은
|
||||
`src/adapter/outbound/persistence-mongo/README.md`의 `SPRING_MONGODB_URI` 예시 바로 아래 문단과 `MongoUriOnlyClientDefaults`에 있다.
|
||||
production은 typed profile(`app.persistence-mongo.platform.profiles.*`)을 쓴다.
|
||||
@@ -2,7 +2,7 @@
|
||||
# Every top-level public type under the platform packages. Growth is a reviewed change.
|
||||
# Update only after review with:
|
||||
# ./gradlew :adapter:outbound:notification:updateNotificationApiSurface -PapproveNotificationApiSurfaceChange
|
||||
# types: 362
|
||||
# types: 364
|
||||
dev.caskeleton.adapter.outbound.notification.NotificationConfig
|
||||
dev.caskeleton.adapter.outbound.notification.NotificationRoutesSettings
|
||||
dev.caskeleton.adapter.outbound.notification.core.FailOpenNotificationProvider
|
||||
@@ -24,6 +24,7 @@ dev.caskeleton.adapter.outbound.notification.platform.autoconfigure.ProviderType
|
||||
dev.caskeleton.adapter.outbound.notification.platform.autoconfigure.SmtpProviderRuntimeAssembler
|
||||
dev.caskeleton.adapter.outbound.notification.platform.callback.CallbackLimits
|
||||
dev.caskeleton.adapter.outbound.notification.platform.callback.CallbackVerificationResult
|
||||
dev.caskeleton.adapter.outbound.notification.platform.callback.CallbackVerificationUnavailableException
|
||||
dev.caskeleton.adapter.outbound.notification.platform.callback.MapProviderCallbackAdapterRegistry
|
||||
dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackAdapter
|
||||
dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackAdapterRegistry
|
||||
@@ -256,6 +257,7 @@ dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStore
|
||||
dev.caskeleton.application.notification.platform.dispatch.ReconciliationService
|
||||
dev.caskeleton.application.notification.platform.dispatch.ScheduleNotificationApplicationUseCase
|
||||
dev.caskeleton.application.notification.platform.dispatch.SubmitNotificationApplicationUseCase
|
||||
dev.caskeleton.application.notification.platform.dispatch.SuppressionSideEffect
|
||||
dev.caskeleton.application.notification.platform.dispatch.SyntheticEventFingerprint
|
||||
dev.caskeleton.application.notification.platform.dispatch.TenantContextPort
|
||||
dev.caskeleton.application.notification.platform.inbox.CreateInboxItemCommand
|
||||
|
||||
@@ -20,7 +20,7 @@ variable names from Boot's relaxed binding. `NotificationEnvironmentRegistryTest
|
||||
| Property | Environment variable | Default | Meaning |
|
||||
|---|---|---|---|
|
||||
| `enabled` | `APP_NOTIFICATION_PLATFORM_ENABLED` | `true` | On while the module is present. `false` binds nothing at all: no runtime, no schema check, no scheduler thread, no secret required |
|
||||
| `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING` refuses to start without a working provider; `INGEST_ONLY` stores requests and does not dispatch |
|
||||
| `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING` refuses to start without a working provider; `INGEST_ONLY` stores requests and does not dispatch: it builds no provider runtime but records each enabled profile's route, so a request accepted now is delivered later on that route by a `SERVING` deployment (handoff) |
|
||||
|
||||
## Dispatch
|
||||
|
||||
@@ -44,18 +44,25 @@ still waiting on gets claimed by a second worker, and the recipient receives the
|
||||
| Property | Environment variable | Default | Bound |
|
||||
|---|---|---|---|
|
||||
| `callbacks.enabled` | `APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED` | `false` | boolean |
|
||||
| `callbacks.max-body-bytes` | `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES` | `65508` | 1..65508 |
|
||||
| `callbacks.replay-skew` | `APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW` | `5m` | positive; SNS messages whose `Timestamp` is further than this from receipt, either way, are rejected |
|
||||
| `callbacks.max-body-bytes` | `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES` | `65251` | 1..65251 |
|
||||
| `callbacks.replay-skew` | `APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW` | `1h` | positive; SNS messages whose `Timestamp` is further than this from receipt, either way, are rejected. The default is SNS's longest HTTP/S retry period (3,600 s), so a bounce or complaint SNS redelivers after an outage is still accepted; a replay inside the window is a duplicate in the provider event ledger, not a second event (review 05-20) |
|
||||
| `callbacks.trusted-proxies` | `APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES` | *(empty)* | CSV of peer addresses |
|
||||
|
||||
콜백 응답: 기록(중복 포함) `204`, 거절 `400`(서명·topic·시각·형식), 본문 초과 `413`. SNS 서명 인증서를 가져오지 못하면(5xx·408·429·네트워크 실패) 거절하지 않고 `503`+`Retry-After`로 답한다 — SNS는 4xx를 처리 완료로 보고 재전송을 멈추지만 5xx는 다시 보낸다(review 05-20). 인증서 URL이 그 밖의 4xx(403·404 등)로 답하면 SNS가 발급하지 않은 인증서를 가리킨 위조 콜백이므로 서명 검증 실패로 `400` 거절하고 보안 감사(`callbackSignatureRejected`)에 남긴다(review 2026-11-03 RR-07-03). 호스트 검사를 통과한 URL이라 답하는 쪽은 SNS다.
|
||||
|
||||
여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다.
|
||||
`trusted-proxies`가 비어 있으면 forwarded 헤더를 **믿지 않고** 컨테이너가 관측한 값을 쓴다. 무조건 믿으면
|
||||
아무 호출자나 자기 서명이 검증될 URL을 고를 수 있어 서명 자체가 무의미해진다. 로드밸런서 뒤에 있는 배포는
|
||||
그 peer를 명시한다.
|
||||
|
||||
65508 is not a round number by accident: it is the ciphertext column's 65536 bytes minus the AES-GCM
|
||||
nonce and tag. A larger configured value would pass every check above the database and fail the
|
||||
`CHECK` constraint after the callback had already been acknowledged to the provider.
|
||||
65251 is not a round number by accident: it is the ciphertext column's 65536 bytes minus the largest
|
||||
envelope the protector writes — a version byte, a key-id length byte, a key id of up to 255 bytes, the
|
||||
AES-GCM nonce and tag. A larger configured value is refused when the settings bind, so the capability
|
||||
does not start; before that check existed it passed every layer above the database and failed the
|
||||
`CHECK` constraint after the callback had already been acknowledged to the provider. The shipped
|
||||
default was 65508 (nonce and tag only) for a while after the envelope gained its key id, and every
|
||||
deployment that turned the platform on failed to start until it was corrected (review 2026-11-01
|
||||
r3-i, found by booting the compose lanes).
|
||||
|
||||
## Provider profiles
|
||||
|
||||
|
||||
@@ -7,7 +7,11 @@
|
||||
"continue-on-error. So the strongest claim in the document rested on the weakest evidence in",
|
||||
"the pipeline, and nothing connected the two.",
|
||||
"NotificationEvidenceVerifierTest reads this file, checks that every claim marked satisfied names",
|
||||
"test classes that exist, and refuses a grade whose claims are not all satisfied."
|
||||
"test classes that exist, and refuses a grade whose claims are not all satisfied.",
|
||||
"A PostgreSql*ContractTest runs a shared port contract (application-notification testFixtures)",
|
||||
"against the JPA store; its cases are the contract's, and the verifier follows the superclass to",
|
||||
"find them. Those contracts replaced RecipientClaimContractTest, ProjectionFactDurabilityContractTest",
|
||||
"and LateEventBindingContractTest, which ran the adapter's SQL over a bare connection (r3-J)."
|
||||
],
|
||||
"claims": {
|
||||
"durable": {
|
||||
@@ -15,8 +19,9 @@
|
||||
"status": "satisfied",
|
||||
"lane": ":adapter:outbound:persistence-jpa:jpaPlatformContractTest",
|
||||
"evidence": [
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/RecipientClaimContractTest.java",
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/ProjectionFactDurabilityContractTest.java",
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/PostgreSqlRecipientDeliveryStoreContractTest.java",
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/PostgreSqlRecipientLeaseStoreContractTest.java",
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/PostgreSqlDeliveryProjectionStoreContractTest.java",
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/ServingStateContractTest.java"
|
||||
]
|
||||
},
|
||||
@@ -25,7 +30,8 @@
|
||||
"status": "satisfied",
|
||||
"lane": ":adapter:outbound:persistence-jpa:jpaPlatformContractTest",
|
||||
"evidence": [
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/RecipientClaimContractTest.java",
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/PostgreSqlRecipientLeaseStoreContractTest.java",
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/PostgreSqlRecipientDeliveryStoreContractTest.java",
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlRecipientLeaseFencingIntegrationTest.java"
|
||||
]
|
||||
},
|
||||
@@ -34,11 +40,13 @@
|
||||
"status": "satisfied",
|
||||
"lanes": [
|
||||
":adapter:outbound:persistence-jpa:jpaPlatformContractTest",
|
||||
":application-notification:test"
|
||||
":application-notification:test",
|
||||
":adapter:outbound:notification:test"
|
||||
],
|
||||
"evidence": [
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/LateEventBindingContractTest.java",
|
||||
"application-notification/src/test/java/dev/caskeleton/application/notification/platform/callback/CallbackIngestionAtomicityTest.java"
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/PostgreSqlProviderEventLedgerContractTest.java",
|
||||
"application-notification/src/test/java/dev/caskeleton/application/notification/platform/callback/CallbackIngestionAtomicityTest.java",
|
||||
"adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/provider/ses/SesCallbackContractTest.java"
|
||||
]
|
||||
},
|
||||
"recoverable": {
|
||||
@@ -46,7 +54,8 @@
|
||||
"status": "satisfied",
|
||||
"lane": ":adapter:outbound:persistence-jpa:jpaPlatformContractTest",
|
||||
"evidence": [
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/WorkerCrashRecoveryContractTest.java"
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/WorkerCrashRecoveryContractTest.java",
|
||||
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlNotificationBackgroundPassIntegrationTest.java"
|
||||
]
|
||||
},
|
||||
"provider-wire-qualified": {
|
||||
|
||||
@@ -42,8 +42,8 @@ that owns its responsibility. No public contract, evidence rule, or reliability
|
||||
| `notification-observability` (Micrometer impl) | `adapter:outbound:notification` | `…platform.observation` |
|
||||
| `notification-admin-runtime` | `adapter:outbound:notification` | `…platform.admin` |
|
||||
| `notification-spring-boot-starter` | `adapter:outbound:notification` | `…platform.autoconfigure` |
|
||||
| `notification-persistence-jpa` | `adapter:outbound:persistence-notification` | `dev.caskeleton.adapter.outbound.persistence.notification.platform` |
|
||||
| `notification-inbox-jpa` | `adapter:outbound:persistence-notification` | `…persistence.notification.platform.inbox` |
|
||||
| `notification-persistence-jpa` | `adapter:outbound:persistence-notification` | `dev.caskeleton.adapter.outbound.persistence.notification.platform` (store adapters), `….platform.entity` (JPA rows), `….platform.repository` (Spring Data interfaces and SQL text) |
|
||||
| `notification-inbox-jpa` | `adapter:outbound:persistence-notification` | `…persistence.notification.platform` (`JpaNotificationInbox`, `InboxCommitEventPublisher`, `InboxOutboxRecordFactory`); row and repository in `….platform.entity` / `….platform.repository` |
|
||||
| `notification-callback-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.callback` |
|
||||
| `notification-submission-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.submission` |
|
||||
| application composition (use cases, callback bridge, `config/module-defaults/notification.yml`) | `composition:notification-platform` | `dev.caskeleton.composition.notification` |
|
||||
|
||||
@@ -49,10 +49,13 @@ assembler is absent because the relay was not configured.
|
||||
| Extension | nothing; the receiving contract owns its own guarantees |
|
||||
| Experimental | nothing; the grade is the warning |
|
||||
|
||||
`recoverable` was met on 2026-08-15 by `WorkerCrashRecoveryContractTest`, which walks the four
|
||||
phases a dispatch passes through — claimed, attempt written, request started, body committed — and
|
||||
asserts for each that the delivery becomes claimable again or becomes a question for the provider,
|
||||
never both and never neither.
|
||||
`recoverable` is backed by two tests. `WorkerCrashRecoveryContractTest` walks the four phases a
|
||||
dispatch passes through — claimed, attempt written, request started, body committed — and pins the
|
||||
rows a dead worker leaves at each: a passed lease, and from the attempt insert on an unfinished
|
||||
attempt carrying that phase's evidence. It writes those rows itself, so it checks recovery's input,
|
||||
not recovery. `PostgreSqlNotificationBackgroundPassIntegrationTest` runs lease recovery and
|
||||
reconciliation over rows the dispatcher's own factory wrote and asserts the outcome: requeued before
|
||||
any attempt, reconciled after one (review 05-01, RR-03-07).
|
||||
|
||||
The remaining unmet claim, and what would meet it:
|
||||
|
||||
|
||||
+229
-23
@@ -259,9 +259,9 @@ env_keys:
|
||||
|
||||
- name: APP_MULTI_INSTANCE_ENABLED
|
||||
# source: feature-env-driven-runtime-configuration D8 (2026-06-06)
|
||||
# When true, StartupSafetyValidator (SmartInitializingSingleton) requires the 5
|
||||
# instance-coordination beans (distributed lock / cache-stampede / outbox leader
|
||||
# / rate-limiter / migration runner) to be present, else startup fails. Consumed
|
||||
# When true, StartupSafetyValidator (a StartupRule, run before any other singleton)
|
||||
# requires a cross-instance DistributedLockPort bean named distributedLockProvider,
|
||||
# else startup fails (exit 72). Consumed
|
||||
# by feature-runtime-health-lifecycle-contract, feature-background-job-async-contract,
|
||||
# feature-cache-consistency-contract, feature-domain-event-outbox-contract,
|
||||
# feature-rate-limit-idempotency-contract, feature-migration-startup-contract.
|
||||
@@ -380,8 +380,9 @@ env_keys:
|
||||
|
||||
- name: APP_FLYWAY_ENABLED
|
||||
# source: local PostgreSQL parity / explicit H2 developer lane.
|
||||
# Local PostgreSQL runs migrations by default; bootRunH2 disables them because the migration
|
||||
# tree is PostgreSQL-specific.
|
||||
# Every profile runs migrations by default — the persistence-jpa module default reads this key
|
||||
# (07-08; dev/prod no longer pin a literal over it); bootRunH2 disables them because the
|
||||
# migration tree is PostgreSQL-specific.
|
||||
property: spring.flyway.enabled
|
||||
type: boolean
|
||||
default: true
|
||||
@@ -543,6 +544,9 @@ env_keys:
|
||||
- name: OTEL_EXPORTER_OTLP_ENDPOINT
|
||||
# source: feature-distributed-tracing-contract 2026-05-22
|
||||
# "Micrometer Tracing + OpenTelemetry exporter를 기본 기준으로 둠"
|
||||
# OTLP base address (OpenTelemetry spec). TracingEnvironmentPostProcessor bridges it to
|
||||
# management.opentelemetry.tracing.export.otlp.endpoint as <value>/v1/traces (OTLP/HTTP);
|
||||
# blank = no span exporter bean (review 07-01, 2026-11-01).
|
||||
type: url
|
||||
default: null
|
||||
allowed_values: null
|
||||
@@ -573,7 +577,7 @@ env_keys:
|
||||
# "trace sampling rate default = prod 1%, dev/local 100%"
|
||||
# D-1 ISSUE-1 fix (2026-06-16): blank = per-profile resolver 기본값 사용.
|
||||
# RuntimeEnvironment is the profile SSOT; resolver policy is prod=0.01, dev/local=1.0.
|
||||
# TracingSamplingEnvironmentPostProcessor bridges resolved rate to
|
||||
# TracingEnvironmentPostProcessor bridges resolved rate to
|
||||
# management.tracing.sampling.probability.
|
||||
type: string
|
||||
default: ""
|
||||
@@ -1597,7 +1601,11 @@ env_keys:
|
||||
|
||||
- name: APP_IDEMPOTENCY_TTL
|
||||
# app.capabilities.idempotency.replay-ttl: how long a completed response stays
|
||||
# replayable. One value for every provider; IdempotencySettings refuses more than 72h at startup.
|
||||
# replayable. One value for every provider; IdempotencySettings refuses more than 72h, less than
|
||||
# APP_IDEMPOTENCY_PROCESSING_LEASE (re-review 2026-11-04 RR-03-11), and more than
|
||||
# APP_IDEMPOTENCY_FAILURE_RETENTION (RR3-03-02, owner decision 2026-11-04), at startup: raising
|
||||
# this key alone past the failure retention (default 24h) fails startup, so raise both
|
||||
# (RR5-03-01). Each record lives for the processing lease plus this value in both stores.
|
||||
type: duration
|
||||
default: 24h
|
||||
allowed_values: null
|
||||
@@ -1605,7 +1613,7 @@ env_keys:
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: feature-rate-limit-idempotency-contract
|
||||
validation: spring_duration_shorthand_le_72h
|
||||
validation: spring_duration_shorthand_le_72h_ge_processing_lease_le_failure_retention
|
||||
compatibility_impact: behavior-change
|
||||
required_test: idempotency-contract:ttl-applied
|
||||
|
||||
@@ -1659,6 +1667,10 @@ env_keys:
|
||||
required_test: redis-idempotency-contract:key-namespace
|
||||
|
||||
- name: APP_IDEMPOTENCY_PROCESSING_LEASE
|
||||
# app.capabilities.idempotency.processing-lease: how long one attempt holds its claim. Longer
|
||||
# than the in-flight Retry-After (2s), at most 1h, and not longer than APP_IDEMPOTENCY_TTL. A
|
||||
# claim whose lease runs out is taken over only if it never started; an execution whose lease
|
||||
# ran out is answered IDEMPOTENCY_RECOVERY_REQUIRED and never run again.
|
||||
type: duration
|
||||
default: 30s
|
||||
allowed_values: null
|
||||
@@ -1666,11 +1678,16 @@ env_keys:
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: redis-production-capability-completion
|
||||
validation: positive_duration_le_1h
|
||||
validation: duration_gt_in_flight_retry_after_2s_le_1h
|
||||
compatibility_impact: additive
|
||||
required_test: redis-idempotency-contract:processing-lease-bounded
|
||||
|
||||
- name: APP_IDEMPOTENCY_FAILURE_RETENTION
|
||||
# app.capabilities.idempotency.failure-retention: how long a record the executor marked failed
|
||||
# (abandoned with an unknown effect, or retryable without one) stays, from the marking. At most
|
||||
# 30d, and IdempotencySettings refuses less than APP_IDEMPOTENCY_TTL at startup: a shorter one
|
||||
# lets an abandoned record go first, and a same-key resend runs the work again (re-review
|
||||
# 2026-11-04 RR3-03-02, owner decision 2026-11-04).
|
||||
type: duration
|
||||
default: 24h
|
||||
allowed_values: null
|
||||
@@ -1678,8 +1695,8 @@ env_keys:
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: redis-production-capability-completion
|
||||
validation: positive_duration_le_30d
|
||||
compatibility_impact: additive
|
||||
validation: positive_duration_le_30d_ge_replay_ttl
|
||||
compatibility_impact: behavior-change
|
||||
required_test: redis-idempotency-contract:failure-retention-bounded
|
||||
|
||||
- name: APP_LEASE_PROVIDER
|
||||
@@ -1802,6 +1819,24 @@ env_keys:
|
||||
compatibility_impact: additive
|
||||
required_test: redis-capability:cache-region-composition
|
||||
|
||||
- name: APP_CACHE_REDIS_MAXIMUM_SCRIPT_CONNECTIONS
|
||||
# The cache's own script-lane connections. Separate from APP_REDIS_CAPACITY_MAXIMUM_SCRIPT_CONNECTIONS,
|
||||
# which idempotency, rate limiting and leases share, so cache fills cannot starve them (review
|
||||
# 2026-11-03 README section 4, RR-04-02).
|
||||
property: app.capabilities.cache.maximum-script-connections
|
||||
owner_module: adapter-outbound-cache-redis
|
||||
type: integer
|
||||
default: 4
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
required_when: app.capabilities.cache.bindings.default=redis
|
||||
reload_policy: restart-only
|
||||
owner_branch: refactor/maturity-review-2026-11
|
||||
validation: positive_integer
|
||||
compatibility_impact: additive
|
||||
required_test: redis-capability:cache-script-lane-separate-from-correctness
|
||||
|
||||
- name: APP_IDEMPOTENCY_REDIS_COMMAND_TIMEOUT
|
||||
# The ceiling on one owner-safe transition.
|
||||
type: duration
|
||||
@@ -1992,6 +2027,11 @@ env_keys:
|
||||
# APP_REDIS_ENABLED is true, and deliberately absent from application.yml and .env.
|
||||
|
||||
- name: APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE
|
||||
# Pointer to the account registered scripts run as, in the same
|
||||
# secret://<acl-account>@<source>/<name> form as the application reference. Unset, scripts run
|
||||
# as the application account and startup logs a warning saying so. The Compose Redis lanes use
|
||||
# secret://ca-skeleton-application-advanced@environment/REDIS_LANE_ADVANCED_PASSWORD, a fixture
|
||||
# account of infra/redis-sdk/acl/lane-fixture-accounts.acl.
|
||||
property: app.redis.authentication.advanced-credential-reference
|
||||
owner_module: adapter-outbound-cache-redis
|
||||
type: string
|
||||
@@ -2014,6 +2054,8 @@ env_keys:
|
||||
# cannot run a single command on any deployment which disabled the `default` ACL user — the
|
||||
# failure moves from startup to the first request, where it reads as an outage rather than a
|
||||
# missing setting. Setting this to true keeps the deployment running and logs the trade.
|
||||
# No Compose lane sets it: the Redis lanes authenticate with the fixture accounts instead, because
|
||||
# the warning this logs is the one their "startup is silent" check exists to catch.
|
||||
type: boolean
|
||||
default: false
|
||||
allowed_values: [true, false]
|
||||
@@ -2028,6 +2070,11 @@ env_keys:
|
||||
|
||||
- name: APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE
|
||||
# Pointer to the application ACL account credential. The value lives in the secret manager.
|
||||
# Form: secret://<acl-account>@<source>/<name>; the environment source reads the variable
|
||||
# <name>. Without the account part the client authenticates as `default`, which a hardened
|
||||
# Redis turns off. The Compose Redis lanes use
|
||||
# secret://ca-skeleton-application@environment/REDIS_LANE_APPLICATION_PASSWORD, a fixture
|
||||
# account of infra/redis-sdk/acl/lane-fixture-accounts.acl.
|
||||
property: app.redis.authentication.credential-reference
|
||||
owner_module: adapter-outbound-cache-redis
|
||||
type: string
|
||||
@@ -2584,6 +2631,11 @@ env_keys:
|
||||
required_test: cache-contract:redis-soft-hard-ttl-order
|
||||
|
||||
- name: APP_CACHE_REDIS_TTL_JITTER
|
||||
# DEPRECATED 2026-11-02: no settings class binds it. Its only reader was a block in
|
||||
# sample-portfolio's application.yml that nothing bound either (07-10), removed with it.
|
||||
# Kept so a deployment still setting it is told it does nothing.
|
||||
deprecated_orphaned: true
|
||||
removal_deadline: 2027-02-28
|
||||
type: float
|
||||
default: 0.10
|
||||
allowed_values: null
|
||||
@@ -2987,6 +3039,20 @@ env_keys:
|
||||
compatibility_impact: additive
|
||||
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
|
||||
|
||||
- name: APP_FILESERVER_PLATFORM_TARGET_NAMESPACES
|
||||
# Namespaces copy and move may write into besides the default namespace, which is always
|
||||
# allowed. Empty means the default namespace only; any other target is ACCESS_DENIED.
|
||||
type: csv_list
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: fileserver-http-platform-activation-boundary
|
||||
validation: storage_namespace_list
|
||||
compatibility_impact: additive
|
||||
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
|
||||
|
||||
- name: APP_FILESERVER_PLATFORM_STORAGE_ROOT
|
||||
# Absolute path on its own volume. A relative root resolves against the process working
|
||||
# directory, which differs between a container and a test, so it is refused.
|
||||
@@ -3437,6 +3503,20 @@ env_keys:
|
||||
compatibility_impact: additive
|
||||
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
|
||||
|
||||
- name: APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT
|
||||
# Most bytes one namespace may hold, live reservations plus committed usage. Empty means
|
||||
# unlimited; a reservation past a set limit is refused with QUOTA_EXCEEDED (413).
|
||||
type: data_size
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: fileserver-http-platform-activation-boundary
|
||||
validation: positive_data_size_when_set
|
||||
compatibility_impact: additive
|
||||
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
|
||||
|
||||
- name: APP_FILESERVER_PLATFORM_ADMIN_ENABLED
|
||||
# Management plane, a separate decision from the data plane. Requires APP_FILESERVER_PLATFORM_ENABLED too:
|
||||
# enabling it alone now does nothing instead of half-building a bean graph.
|
||||
@@ -3466,9 +3546,11 @@ env_keys:
|
||||
required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip
|
||||
|
||||
- name: APP_FILESERVER_PLATFORM_CLEANUP_ENABLED
|
||||
# Background reclamation. Off by default because the worker deletes physical objects.
|
||||
# Background reclamation. On by default: without it cancelled/expired staging and rejected or
|
||||
# deleted content stay on the volume until the hard high-water mark stops uploads. Turning it
|
||||
# off logs a startup warning (another node or the admin plane must reclaim instead).
|
||||
type: boolean
|
||||
default: false
|
||||
default: true
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
@@ -3707,7 +3789,7 @@ env_keys:
|
||||
property: spring.jpa.properties.hibernate.jdbc.batch_size
|
||||
owner_module: adapter-outbound-persistence-jpa
|
||||
type: integer
|
||||
default: 0
|
||||
default: 50
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
@@ -3715,14 +3797,14 @@ env_keys:
|
||||
reload_policy: restart-only
|
||||
owner_branch: 2026-09-22-persistence-jpa-review-remediation
|
||||
validation: non_negative_integer
|
||||
compatibility_impact: additive
|
||||
compatibility_impact: behavior-change
|
||||
required_test: jpa-contract:hibernate-runtime-settings
|
||||
|
||||
- name: APP_JPA_HIBERNATE_ORDER_INSERTS
|
||||
property: spring.jpa.properties.hibernate.order_inserts
|
||||
owner_module: adapter-outbound-persistence-jpa
|
||||
type: boolean
|
||||
default: false
|
||||
default: true
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
@@ -3730,14 +3812,14 @@ env_keys:
|
||||
reload_policy: restart-only
|
||||
owner_branch: 2026-09-22-persistence-jpa-review-remediation
|
||||
validation: boolean_strict
|
||||
compatibility_impact: additive
|
||||
compatibility_impact: behavior-change
|
||||
required_test: jpa-contract:hibernate-runtime-settings
|
||||
|
||||
- name: APP_JPA_HIBERNATE_ORDER_UPDATES
|
||||
property: spring.jpa.properties.hibernate.order_updates
|
||||
owner_module: adapter-outbound-persistence-jpa
|
||||
type: boolean
|
||||
default: false
|
||||
default: true
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
@@ -3745,7 +3827,7 @@ env_keys:
|
||||
reload_policy: restart-only
|
||||
owner_branch: 2026-09-22-persistence-jpa-review-remediation
|
||||
validation: boolean_strict
|
||||
compatibility_impact: additive
|
||||
compatibility_impact: behavior-change
|
||||
required_test: jpa-contract:hibernate-runtime-settings
|
||||
|
||||
- name: APP_JPA_HIBERNATE_DEFAULT_BATCH_FETCH_SIZE
|
||||
@@ -3917,6 +3999,114 @@ env_keys:
|
||||
compatibility_impact: behavior-change
|
||||
required_test: websocket-contract:canonical-property-namespace
|
||||
|
||||
- name: APP_WEBSOCKET_MESSAGE_SIZE_LIMIT
|
||||
# Spring's own default, now explicit (review 03-06); at most 2147483647 bytes.
|
||||
property: app.websocket.message-size-limit
|
||||
owner_module: adapter-inbound-websocket
|
||||
type: data_size
|
||||
default: 64KB
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: 2026-11-01-maturity-review-round2
|
||||
validation: positive_data_size
|
||||
compatibility_impact: additive
|
||||
required_test: websocket-contract:canonical-property-namespace
|
||||
|
||||
- name: APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT
|
||||
# Spring's own default, now explicit (review 03-06); at most 2147483647 bytes.
|
||||
property: app.websocket.send-buffer-size-limit
|
||||
owner_module: adapter-inbound-websocket
|
||||
type: data_size
|
||||
default: 512KB
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: 2026-11-01-maturity-review-round2
|
||||
validation: positive_data_size
|
||||
compatibility_impact: additive
|
||||
required_test: websocket-contract:canonical-property-namespace
|
||||
|
||||
- name: APP_WEBSOCKET_SEND_TIME_LIMIT
|
||||
# Spring's own default, now explicit (review 03-06); at most 2147483647 ms.
|
||||
property: app.websocket.send-time-limit
|
||||
owner_module: adapter-inbound-websocket
|
||||
type: duration
|
||||
default: 10s
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: 2026-11-01-maturity-review-round2
|
||||
validation: positive_duration
|
||||
compatibility_impact: additive
|
||||
required_test: websocket-contract:canonical-property-namespace
|
||||
|
||||
- name: APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE
|
||||
# Spring's own default, now explicit (review 03-06); at most 2147483647 ms.
|
||||
property: app.websocket.time-to-first-message
|
||||
owner_module: adapter-inbound-websocket
|
||||
type: duration
|
||||
default: 60s
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: 2026-11-01-maturity-review-round2
|
||||
validation: positive_duration
|
||||
compatibility_impact: additive
|
||||
required_test: websocket-contract:canonical-property-namespace
|
||||
|
||||
- name: APP_WEBSOCKET_MAX_CONNECTIONS
|
||||
# New per-node STOMP session ceiling (review 03-06); the next session is closed with 1013. 1000 x 512KB send buffer bounds worst-case outbound buffering near 512 MiB.
|
||||
property: app.websocket.max-connections
|
||||
owner_module: adapter-inbound-websocket
|
||||
type: integer
|
||||
default: 1000
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: 2026-11-01-maturity-review-round2
|
||||
validation: positive_integer
|
||||
compatibility_impact: behavior-change
|
||||
required_test: websocket-contract:canonical-property-namespace
|
||||
|
||||
- name: APP_OBJECTSTORAGE_ENABLED
|
||||
# 2026-11-03 RR-06-07: the explicit off the Compose smoke wrapper sets for every lane that is
|
||||
# not about object storage. It bound by relaxed binding and was in no registry, so the env
|
||||
# contract could not tell it from an unread name. The module is on when present; absent from
|
||||
# the build is the ordinary off state.
|
||||
property: app.object-storage.enabled
|
||||
owner_module: adapter-outbound-objectstorage
|
||||
type: boolean
|
||||
default: true
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: refactor/maturity-review-2026-11
|
||||
validation: boolean
|
||||
compatibility_impact: none
|
||||
required_test: off-state-zero-side-effects-and-env-round-trip
|
||||
- name: APP_GRPC_SERVER_ENABLED
|
||||
# 2026-11-03 RR-06-07: the explicit off for the gRPC server the Compose lanes set (it replaced
|
||||
# CASKELETON_GRPC_ENABLED, which nothing read). The module is on when present; absent from the
|
||||
# build is the ordinary off state.
|
||||
property: app.grpc.server.enabled
|
||||
owner_module: adapter-inbound-grpc
|
||||
type: boolean
|
||||
default: true
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: refactor/maturity-review-2026-11
|
||||
validation: boolean
|
||||
compatibility_impact: none
|
||||
required_test: off-state-zero-side-effects-and-env-round-trip
|
||||
- name: APP_GRAPHQL_ENABLED
|
||||
# 2026-09-25 capability packaging: the module is on when present (its own config yml maps
|
||||
# this key with default true); false is the explicit off. Absent from the build is the
|
||||
@@ -4084,6 +4274,21 @@ env_keys:
|
||||
compatibility_impact: additive
|
||||
required_test: graphql-contract:wired-operator-settings
|
||||
|
||||
- name: APP_GRAPHQL_PER_PARENT_FETCH_WARNING_THRESHOLD
|
||||
property: app.graphql.limits.per-parent-fetch-warning-threshold
|
||||
owner_module: adapter-inbound-graphql
|
||||
type: integer
|
||||
default: 10
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
required_when: APP_GRAPHQL_ENABLED=true
|
||||
reload_policy: restart-only
|
||||
owner_branch: 2026-11-01-maturity-review-round2
|
||||
validation: positive_integer
|
||||
compatibility_impact: additive
|
||||
required_test: graphql-contract:wired-operator-settings
|
||||
|
||||
- name: APP_OUTBOX_ENABLED
|
||||
# source: five-adapter-runtime-remediation §6.1 JPA-INT-004 — the outbox capability switch.
|
||||
# relay-enabled below only starts the scheduler; conflating the two meant a relay-off deployment
|
||||
@@ -5079,22 +5284,23 @@ env_keys:
|
||||
required_test: adapter-contract:notification-callback-ingestion
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES
|
||||
# source: NTF-025 — ceiling is 65508 = ciphertext column minus AES-GCM nonce and tag; larger is refused at binding
|
||||
# source: NTF-025 — ceiling is 65251 = ciphertext column minus the largest envelope (version, key-id length, 255-byte key id, AES-GCM nonce and tag); larger is refused at binding
|
||||
type: integer
|
||||
default: 65508
|
||||
default: 65251
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: integer_1_to_65508
|
||||
validation: integer_1_to_65251
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-callback-body-bound
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW
|
||||
# source: NTF-025 — how far a callback timestamp may differ from local time before it is treated as a replay
|
||||
# review 05-20 — 1h covers SNS's whole HTTP/S retry period (capped at 3,600 s); a replay inside it is a ledger duplicate
|
||||
type: duration
|
||||
default: 5m
|
||||
default: 1h
|
||||
allowed_values: null
|
||||
classification: security-relevant
|
||||
required: false
|
||||
|
||||
@@ -399,18 +399,22 @@ errors:
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:rate-limit
|
||||
|
||||
# source: feature-rate-limit-idempotency-contract L71 — "200ms 초과 시 409 IDEMPOTENT_IN_FLIGHT (retryable=false, client는 polling)"
|
||||
# source: docs/web/http-contract.md §2 (2026-11-01 소유자 결정, 리뷰 02-01 대안 A) — 결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송. 새 키 금지.
|
||||
# 2초 = 기본 processing lease(30s)보다 짧은 고정값. 이전 "client는 polling"(retryable=false)은 조회 엔드포인트가 없어 폐기.
|
||||
# 값 하나: IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER. processing-lease가 이 값 이하면 기동 실패(재리뷰 RR-02-05).
|
||||
# behavior-change: retryable false→true는 web Envelope뿐 아니라 gRPC trailer error-retryable(status ABORTED)과
|
||||
# GraphQL extension retryable에도 나간다(재리뷰 RR-02-06, GrpcStatusMapperTest·GraphQlWireErrorMapperTest가 고정).
|
||||
- code: IDEMPOTENT_IN_FLIGHT
|
||||
category: CONFLICT
|
||||
http_status: 409
|
||||
retryable: false
|
||||
retry_after_seconds: null
|
||||
retryable: true
|
||||
retry_after_seconds: 2
|
||||
owner_branch: feature-rate-limit-idempotency-contract
|
||||
owner_layer: application
|
||||
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
compatibility_impact: behavior-change
|
||||
required_test: contract-verification:idempotency
|
||||
|
||||
# source: feature-rate-limit-idempotency-contract L72 — "fingerprint mismatch (same key + different body) = 422 IDEMPOTENT_REQUEST_MISMATCH"
|
||||
@@ -441,6 +445,22 @@ errors:
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:idempotency
|
||||
|
||||
# source: 재리뷰 2026-11-03 README 4절 결정, RR-02-03 — action이 돈 뒤 complete 단계에서 저장소가 응답하지 않음.
|
||||
# 실행 전 거부(IDEMPOTENCY_UNAVAILABLE)와 code로 구분한다. 결과 불명: 같은 키로 재전송하면 서버가 replay·in-flight·
|
||||
# recovery-required로 판정한다. 새 키 금지. docs/web/http-contract.md §2.
|
||||
- code: IDEMPOTENCY_COMPLETION_UNKNOWN
|
||||
category: TRANSIENT_DEPENDENCY
|
||||
http_status: 503
|
||||
retryable: true
|
||||
retry_after_seconds: null
|
||||
owner_branch: feature-rate-limit-idempotency-contract
|
||||
owner_layer: application
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://idempotency/unavailable"
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:idempotency
|
||||
|
||||
# source: review-followup P15 (X2-P2-2a) — replay cannot decide whether an external effect happened
|
||||
- code: IDEMPOTENCY_RECOVERY_REQUIRED
|
||||
category: DATA_INTEGRITY
|
||||
|
||||
+124
-204
@@ -349,8 +349,10 @@ metrics:
|
||||
cardinality_limit: 50
|
||||
- name: outcome
|
||||
cardinality_limit: 5
|
||||
# STALE: the relay's claim was taken over before its result could be written (V17 lease fence).
|
||||
allowed_values: [PUBLISHED, FAILED, DEAD, IN_FLIGHT, STALE]
|
||||
# The relay cycle outcomes (OutboxRelayResult.Outcome), not row statuses: IN_FLIGHT is a status
|
||||
# and is never counted. STALE: the relay's claim was taken over before its result could be
|
||||
# written (V17 lease fence). RELEASED: a stopping relay gave back a claim it had not used.
|
||||
allowed_values: [PUBLISHED, FAILED, DEAD, STALE, RELEASED]
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
@@ -378,22 +380,55 @@ metrics:
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
# source: feature-domain-event-outbox-contract — row status enum + Outbox Defaults attemptCount
|
||||
# PARKED: an operator held a row that was retried without end (re-review 2026-11-03 RR-05-03).
|
||||
- name: outbox.pending.size
|
||||
type: gauge
|
||||
unit: total
|
||||
tags:
|
||||
- name: status
|
||||
cardinality_limit: 5
|
||||
allowed_values: [PENDING, IN_FLIGHT, PUBLISHED, FAILED, DEAD]
|
||||
cardinality_limit: 6
|
||||
allowed_values: [PENDING, IN_FLIGHT, PUBLISHED, FAILED, DEAD, PARKED]
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
# DEAD > 0: the claim moves a row it will not hand out to DEAD without a relay result, so
|
||||
# outbox.publisher.published.total{outcome=DEAD} misses it (re-review round 2, RR-02-12).
|
||||
alert_severity_thresholds:
|
||||
p1: "DEAD > 0 (runbook://outbox/dead-letter)"
|
||||
p2: "PENDING size growing for 10m"
|
||||
owner_branch: feature-domain-event-outbox-contract
|
||||
log_field_mapping: [status]
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
# source: re-review 2026-11-03 RR-05-03 — a refusal for now and an unanswered publish are retried
|
||||
# without end; these count the FAILED rows deferred at least 10 times (OutboxMetrics
|
||||
# LONG_RETRY_DEFERRED_CLAIMS, the publish-failed runbook's §4.1 query) and age the oldest of them.
|
||||
- name: outbox.retry.long.size
|
||||
type: gauge
|
||||
unit: total
|
||||
tags: []
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
p2: "> 0 for 10m (runbook://outbox/publish-failed §4.1)"
|
||||
owner_branch: feature-domain-event-outbox-contract
|
||||
log_field_mapping: []
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
- name: outbox.retry.long.age
|
||||
type: gauge
|
||||
unit: seconds
|
||||
tags: []
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
p2: "> 3600 (runbook://outbox/publish-failed §4.1)"
|
||||
owner_branch: feature-domain-event-outbox-contract
|
||||
log_field_mapping: []
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
# === Cache ===
|
||||
# source: feature-cache-consistency-contract — Decisionized Work Items "cache pattern | cache-aside default"
|
||||
- name: cache.gets.total
|
||||
@@ -501,240 +536,125 @@ metrics:
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
# source: redis-production-capability Task 16 — closed semantic operation outcomes
|
||||
- name: redis.capability.operations.total
|
||||
type: counter
|
||||
unit: total
|
||||
tags:
|
||||
- name: capability
|
||||
cardinality_limit: 6
|
||||
allowed_values: [cache, rate_limit, idempotency, efficiency_lease, session, runtime]
|
||||
- name: role
|
||||
cardinality_limit: 3
|
||||
allowed_values: [cache, coordination, session]
|
||||
- name: operation
|
||||
cardinality_limit: 24
|
||||
allowed_values:
|
||||
- lookup
|
||||
- record
|
||||
- invalidate
|
||||
- refresh_claim
|
||||
- refresh_release
|
||||
- rate_evaluate
|
||||
- idempotency_claim
|
||||
- idempotency_start
|
||||
- idempotency_renew
|
||||
- idempotency_complete
|
||||
- idempotency_fail
|
||||
- idempotency_release
|
||||
- idempotency_inspect
|
||||
- lease_acquire
|
||||
- lease_inspect
|
||||
- lease_renew
|
||||
- lease_release
|
||||
- session_create
|
||||
- session_inspect
|
||||
- session_save
|
||||
- session_touch
|
||||
- session_revoke
|
||||
- session_rotate
|
||||
- route_command
|
||||
- name: redis_outcome
|
||||
cardinality_limit: 15
|
||||
allowed_values:
|
||||
- success
|
||||
- hit
|
||||
- miss
|
||||
- denied
|
||||
- contended
|
||||
- conflict
|
||||
- incompatible
|
||||
- unavailable
|
||||
- overloaded
|
||||
- closed
|
||||
- indeterminate
|
||||
- stale
|
||||
- skipped
|
||||
- tombstoned
|
||||
- absolute_expired
|
||||
- name: certainty
|
||||
cardinality_limit: 3
|
||||
allowed_values: [definite, not_applied, indeterminate]
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
p1: "required coordination/session unavailable or indeterminate mutation sustained for 2m"
|
||||
p2: "optional cache unavailable or overloaded above baseline for 5m"
|
||||
owner_branch: redis-production-capability
|
||||
log_field_mapping: [capability, role, operation, redis_outcome, certainty]
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
# source: redis-production-capability Task 16 — monotonic semantic operation duration
|
||||
- name: redis.capability.duration.seconds
|
||||
# === Redis connection lanes ===
|
||||
# source: review 2026-11-03 RR-04-02 — the cache's conditional writes got their own lane
|
||||
# (CACHE_SCRIPT) so that cache fills cannot take the SCRIPT lane's connections from idempotency,
|
||||
# rate limiting and leases. These meters show, per lane, whether that holds. Emitted by
|
||||
# redis-runtime RedisLaneMetrics for every lane RedisRuntimeOwner pools, only when the context has
|
||||
# a MeterRegistry. Every counter series is registered at zero at startup.
|
||||
- name: redis.lane.acquire.wait.seconds
|
||||
type: timer
|
||||
unit: seconds
|
||||
tags:
|
||||
- name: capability
|
||||
cardinality_limit: 6
|
||||
allowed_values: [cache, rate_limit, idempotency, efficiency_lease, session, runtime]
|
||||
- name: role
|
||||
cardinality_limit: 3
|
||||
allowed_values: [cache, coordination, session]
|
||||
- name: operation
|
||||
cardinality_limit: 24
|
||||
allowed_values:
|
||||
- lookup
|
||||
- record
|
||||
- invalidate
|
||||
- refresh_claim
|
||||
- refresh_release
|
||||
- rate_evaluate
|
||||
- idempotency_claim
|
||||
- idempotency_start
|
||||
- idempotency_renew
|
||||
- idempotency_complete
|
||||
- idempotency_fail
|
||||
- idempotency_release
|
||||
- idempotency_inspect
|
||||
- lease_acquire
|
||||
- lease_inspect
|
||||
- lease_renew
|
||||
- lease_release
|
||||
- session_create
|
||||
- session_inspect
|
||||
- session_save
|
||||
- session_touch
|
||||
- session_revoke
|
||||
- session_rotate
|
||||
- route_command
|
||||
- name: redis_outcome
|
||||
cardinality_limit: 15
|
||||
allowed_values:
|
||||
- success
|
||||
- hit
|
||||
- miss
|
||||
- denied
|
||||
- contended
|
||||
- conflict
|
||||
- incompatible
|
||||
- unavailable
|
||||
- overloaded
|
||||
- closed
|
||||
- indeterminate
|
||||
- stale
|
||||
- skipped
|
||||
- tombstoned
|
||||
- absolute_expired
|
||||
percentiles: [0.5, 0.9, 0.95, 0.99]
|
||||
histogram_buckets: slo_driven
|
||||
- name: lane
|
||||
# The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING,
|
||||
# TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution.
|
||||
cardinality_limit: 12
|
||||
- name: outcome
|
||||
cardinality_limit: 2
|
||||
allowed_values: [admitted, refused]
|
||||
# As RedisLaneMetrics registers it: a percentile histogram (publishPercentileHistogram, expected
|
||||
# range 1ms..10s) and no client-side percentiles and no SLO boundaries. The p99 below is a
|
||||
# histogram_quantile over the buckets (re-review 2026-11-04 RR-03-17).
|
||||
percentiles: null
|
||||
histogram_buckets: percentile_histogram
|
||||
alert_severity_thresholds:
|
||||
p2: "p99 approaches the configured command or caller deadline for 10m"
|
||||
p2: "SCRIPT admitted p99 > 100ms for 10m (the correctness lane is queueing)"
|
||||
p3: "CACHE_SCRIPT admitted p99 > 100ms for 30m"
|
||||
owner_branch: redis-production-capability
|
||||
log_field_mapping: [capability, role, operation, redis_outcome]
|
||||
log_field_mapping: [lane, outcome]
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
# source: redis-production-capability Task 16 — admission rejected before command ownership
|
||||
- name: redis.capability.admission.rejected.total
|
||||
- name: redis.lane.acquire.refused.total
|
||||
type: counter
|
||||
unit: total
|
||||
tags:
|
||||
- name: role
|
||||
cardinality_limit: 3
|
||||
allowed_values: [cache, coordination, session]
|
||||
- name: admission
|
||||
cardinality_limit: 2
|
||||
allowed_values: [rejected_saturated, rejected_closed]
|
||||
- name: lane
|
||||
# The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING,
|
||||
# TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution.
|
||||
cardinality_limit: 12
|
||||
- name: reason
|
||||
cardinality_limit: 4
|
||||
allowed_values: [saturated, closing, interrupted, connect_failed]
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
p1: "required role rejection sustained above zero for 2m"
|
||||
p2: "optional cache saturation sustained for 5m"
|
||||
p1: "SCRIPT or REGULAR saturated or connect_failed above zero for 2m while a correctness role is selected"
|
||||
p2: "CACHE_SCRIPT saturated above baseline for 10m"
|
||||
owner_branch: redis-production-capability
|
||||
log_field_mapping: [role, admission]
|
||||
log_field_mapping: [lane, reason]
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
# source: redis-production-capability Task 16 — bounded admitted command count observation
|
||||
- name: redis.capability.inflight.total
|
||||
- name: redis.lane.connections.opened.total
|
||||
type: counter
|
||||
unit: total
|
||||
tags:
|
||||
- name: lane
|
||||
# The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING,
|
||||
# TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution.
|
||||
cardinality_limit: 12
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
p3: "opened rate after warm-up above baseline for 15m (reconnect churn against a slow Redis)"
|
||||
owner_branch: redis-production-capability
|
||||
log_field_mapping: [lane]
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
- name: redis.lane.connections.discarded.total
|
||||
type: counter
|
||||
unit: total
|
||||
tags:
|
||||
- name: lane
|
||||
# The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING,
|
||||
# TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution.
|
||||
cardinality_limit: 12
|
||||
- name: reason
|
||||
cardinality_limit: 2
|
||||
allowed_values: [invalidated, broken]
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
p3: "invalidated rate above baseline for 15m (timed-out or failed calls discarding connections)"
|
||||
owner_branch: redis-production-capability
|
||||
log_field_mapping: [lane, reason]
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
- name: redis.lane.connections.active
|
||||
type: gauge
|
||||
unit: total
|
||||
tags:
|
||||
- name: role
|
||||
cardinality_limit: 3
|
||||
allowed_values: [cache, coordination, session]
|
||||
- name: state
|
||||
cardinality_limit: 3
|
||||
allowed_values: [idle, active, saturated]
|
||||
- name: lane
|
||||
# The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING,
|
||||
# TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution.
|
||||
cardinality_limit: 12
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
p2: "saturated series remains nonzero for 5m"
|
||||
p2: "SCRIPT active == configured maximum-script-connections for 5m"
|
||||
owner_branch: redis-production-capability
|
||||
log_field_mapping: [role, state]
|
||||
log_field_mapping: [lane]
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
# source: redis-production-capability Task 16 — observations of exact sanitized RoleHealth
|
||||
- name: redis.capability.readiness.total
|
||||
type: counter
|
||||
- name: redis.lane.connections.pending
|
||||
type: gauge
|
||||
unit: total
|
||||
tags:
|
||||
- name: capability
|
||||
cardinality_limit: 5
|
||||
allowed_values: [cache, rate_limit, idempotency, efficiency_lease, session]
|
||||
- name: role
|
||||
cardinality_limit: 3
|
||||
allowed_values: [cache, coordination, session]
|
||||
- name: state
|
||||
cardinality_limit: 3
|
||||
allowed_values: [available, unavailable, overloaded]
|
||||
- name: reason
|
||||
cardinality_limit: 11
|
||||
allowed_values:
|
||||
- command_unavailable
|
||||
- route_closed
|
||||
- semantic_probe_succeeded
|
||||
- semantic_read_write_failed
|
||||
- semantic_program_acl_denied
|
||||
- semantic_program_failed
|
||||
- server_version_unsupported
|
||||
- semantic_probe_in_progress
|
||||
- semantic_observation_stale
|
||||
- command_saturated
|
||||
- recent_command_failure
|
||||
- name: requirement
|
||||
cardinality_limit: 2
|
||||
allowed_values: [optional, required]
|
||||
- name: lane
|
||||
# The lane's name: REGULAR, SCRIPT (redis-runtime), CACHE_SCRIPT (cache-redis), BLOCKING,
|
||||
# TRANSACTION, ADMIN (redis-sdk), plus any lane a service composes as a RedisLaneContribution.
|
||||
cardinality_limit: 12
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
p1: "required coordination/session unavailable for 2m"
|
||||
p2: "optional cache unavailable or overloaded for 5m"
|
||||
p2: "SCRIPT pending > 0 for 5m"
|
||||
owner_branch: redis-production-capability
|
||||
log_field_mapping: [capability, role, state, reason, requirement]
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
# source: redis-production-capability Task 16 — bounded router shutdown drain result
|
||||
- name: redis.capability.lifecycle.drain.total
|
||||
type: counter
|
||||
unit: total
|
||||
tags:
|
||||
- name: role
|
||||
cardinality_limit: 3
|
||||
allowed_values: [cache, coordination, session]
|
||||
- name: drain_outcome
|
||||
cardinality_limit: 3
|
||||
allowed_values: [drained, forced_after_timeout, interrupted]
|
||||
percentiles: null
|
||||
histogram_buckets: null
|
||||
alert_severity_thresholds:
|
||||
p1: "required role forced_after_timeout or interrupted during shutdown"
|
||||
p2: "optional cache forced close during shutdown"
|
||||
owner_branch: redis-production-capability
|
||||
log_field_mapping: [role, drain_outcome]
|
||||
log_field_mapping: [lane]
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
|
||||
|
||||
@@ -10,6 +10,11 @@
|
||||
# (feature-secrets-config-source-contract 2026-05-22: "dev/local sentinel value prefix = __LOCAL_DEV_").
|
||||
# - prod profile에서 `__LOCAL_DEV_` prefix 발견 시 startup fail
|
||||
# (feature-secrets-config-source-contract 2026-05-22).
|
||||
# - prod profile에서 비밀값이 `fixture-`로 시작하면(이 저장소에 적힌 lane fixture 비밀번호 —
|
||||
# infra/redis-sdk/acl, compose lane의 REDIS_LANE_*) 같은 이유로 startup fail (review 2026-11-03
|
||||
# RR-07-04). 비밀값만 본다: 이 파일의 `secret` 행(SecretSourceValidator.CLASSIFIED_SECRETS,
|
||||
# SecretsClassificationRegistryTest가 1:1로 묶음), 모듈이 기여한 비밀, `secret://…/<VAR>` 참조가
|
||||
# 가리키는 변수. HOSTNAME·앱 이름 같은 비밀이 아닌 값은 보지 않는다 (review 2026-11-04 RR2-04-01).
|
||||
# - Masking 기본 = `full_except_last_4` (feature-secrets-config-source-contract 2026-05-22:
|
||||
# "full mask except last 4 chars for non-secret tokens"). 진짜 secret(password/private key)은 `full`.
|
||||
# - Naming suffix는 보조 신호 (feature-secrets-config-source-contract: "_TOKEN, _KEY, _PASSWORD").
|
||||
|
||||
@@ -0,0 +1,490 @@
|
||||
# 01. 코어(domain-core · shared-contract · application-core)와 기능 개발 패턴 리뷰
|
||||
|
||||
대상 leaf: `domain-core`(`:domain-core`), `shared-contract`(`:shared-contract`), `application-core`(`:application-core`).
|
||||
추가 범위: repo 전체의 폴더 구조, 중복 복사본·갈라진 유틸, 새 기능을 추가하는 작업 순서(sample-portfolio 포함).
|
||||
|
||||
경로는 `src/`를 생략한다. 패키지 앞부분이 긴 경로는 `.../`로 줄인다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 | `clean-architecture-backend-template`, 브랜치 `main`, 커밋 `01a8a2a70` |
|
||||
| 확인 시점 | 2026-11-01 |
|
||||
| 목적과 실행 구성 | 템플릿(파생 서비스의 시작점). 코어 세 leaf는 모든 조립에 들어간다(`app-bootstrap/build.gradle:149-150,214`). 업무 도메인은 비어 있고 예시는 `sample-portfolio`에 있다. |
|
||||
| 규모·운영 목표 | 합의된 SLO·처리량 없음. 이 영역은 성능 목표보다 "새 기능을 넣는 사람이 틀리지 않는가"를 본다. |
|
||||
| 읽은 범위 | 세 leaf의 main·test·testFixtures 전부(domain-core main 7파일 110줄, shared-contract main 42파일 2,115줄, application-core main 130파일 5,080줄). 세 leaf의 `CLAUDE.md`·`README.md`, 루트 `AGENTS.md`·`CLAUDE.md`, `config/architecture/modules.json`. 기능 패턴을 따라가려고 sample-portfolio의 domain·application 전부와 web·persistence·bootstrap 중 WorkLog·Poster 경로, `app-bootstrap`의 `DurableOperationConfig`, onboarding fixture(`app-bootstrap/src/test/java/dev/caskeleton/onboarding/**`)와 `DomainFeatureOnboardingContractTest`, ArchUnit 규칙(`ApplicationBoundaryArchitectureTest`, `NamingConventionTest`, `ForbiddenApiArchitectureTest`, `RequiresPermissionProxyabilityTest`), web의 `MethodSecurityConfig`·`RequiresPermissionAuthorizationManager`·`GlobalExceptionHandler`, support의 `JsonIntegrationEventEncoder`. 중복 탐색은 repo 전체 main을 grep으로 훑었다(같은 단순 이름 클래스, SHA-256·HMAC 직접 구현, 식별자 문법). |
|
||||
| 실행한 것 | ① 게이트 결과 읽기: `ci` rc=0(세 leaf `test`·`check`, `:app-bootstrap:architectureTest` 181개 통과), `mainCheck` rc=1(objectstorage MinIO 이미지 pull 404, 이 영역 밖). ② `build/test-results` XML 집계(ci가 20:36~20:38에 만든 결과). ③ 별도 worktree(`wt-01`)에서 `flock` 잠금으로 기준 실행 1회와 변이 실험 5회(아래 표). worktree는 끝나고 지웠다. |
|
||||
| 확인 못 한 것 | 실제 Postgres·Redis로 도는 포트 어댑터 계약 lane(이 영역 소유 아님), 앱 기동 상태에서의 인가 프록시 동작(정적 근거와 기존 테스트로만 판단), 부하 측정. 지난 리뷰의 실행 결과는 증거로 쓰지 않았다. |
|
||||
| 비교 가능한 범위 | techlead `01-core.md`, followup-status 「A Core」「S1 Core」「X1/X2」. 파생 서비스 `tech-log-backend`의 현재 작업 트리를 참고 자료로 읽었다(이 repo의 커밋이 아니므로 판정 근거가 아니라 "실제로 어떻게 쓰였는가"의 사례로만 쓴다). |
|
||||
|
||||
### 변이 실험 (worktree `wt-01`, 실행 후 원복·삭제)
|
||||
|
||||
기준 실행: `./gradlew :domain-core:test :shared-contract:test :application-core:test` rc=0 (부하 21.4, 캐시 적중으로 1초).
|
||||
|
||||
| # | 바꾼 코드 | 돌린 테스트 (부하) | 결과 |
|
||||
| --- | --- | --- | --- |
|
||||
| M1 | `DurableOperationAccessPolicy.java` `mayAccess`에서 tenant 비교 삭제 | `:application-core:test` (13.0) | 잡힘 — 217개 중 5개 실패 |
|
||||
| M2 | `TenantId.java:22` 문법에 `/` 허용 | `:application-core:test` | **살아남음** — 전부 통과 (01-03) |
|
||||
| M3 | `PublishPendingOutboxEventsUseCase.java:112` 정렬을 역순으로 | `:application-core:test` | 잡힘 — 3개 실패 |
|
||||
| M4 | `Backoff.java` `ceiling`의 overflow 방어 삭제 | `:shared-contract:test` | 잡힘 — 260개 중 2개 실패 |
|
||||
| M5 | `IntegrationEventDraft.java:49` correlation 길이 상한 96→200 | `:application-core:test` | **살아남음** — 전부 통과 (01-07) |
|
||||
|
||||
테스트 실행 시간(ci 결과): domain-core 2개 0.13초, shared-contract 260개 0.81초, application-core 217개 1.38초. `:app-bootstrap:architectureTest` 181개 17.1초. 변이 1회당 leaf 재실행은 2~4초였다. 과하지 않다.
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
상태: 해결 / 남음 / 바뀜(형태가 달라짐) / 일부.
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| techlead C1 application-core가 HTTP 프로토콜 구현 | 해결 | application-core main에 HTTP 타입 0건. "http"는 `SubmitDurableOperationUseCase` 주석과 schema 파일에만 있다. fileserver 프로토콜은 `application-fileserver`·`adapter:inbound:web-fileserver`로 갔다 |
|
||||
| techlead C2 HTTP 요청 DTO가 inbound port 인자 | 해결 | ArchUnit `APPLICATION_METHODS_DO_NOT_ACCEPT_WEB_DTOS`(`ApplicationBoundaryArchitectureTest.java:855`)가 ci에서 통과 |
|
||||
| techlead H1 `inNew` 프로덕션 미사용 | 바뀜 | 이제 `CreateUploadApplicationUseCase.java:143`, `FinalizeUploadApplicationUseCase.java:332`(application-fileserver)가 쓴다 |
|
||||
| techlead H4 application-core 76%가 고르지 않은 제품 | 바뀜 | main 35,894줄 → 5,080줄. 알림·파일·객체 저장소는 별도 leaf로 나갔다. 남은 플랫폼 기능(outbox·idempotency·operation·lease·lock·cache·realtime)은 01-10 |
|
||||
| techlead H5 캐시 엔진·lease watchdog 미조립 | 일부 | 캐시 엔진·watchdog 삭제. `lease/*`는 남았고 main 호출자는 Redis 구현뿐(`RedisLeaseConfig.java:29`). 소유자 결정 8(유지)로 의도된 확장 지점 |
|
||||
| techlead H8 알림 멱등키 `Objects.hash` | > 05 영역 | application-notification으로 이동. 이 영역 밖 |
|
||||
| techlead M6 application-core 정적 `ThreadLocal` | 해결 | `static.*ThreadLocal` 0건 |
|
||||
| techlead M10 domain-core 테스트 0줄 | 해결(형식만) | `DomainCoreContractTest` 2개. 마커의 retention·target만 본다. domain-core에 행위가 없어서 충분하다 |
|
||||
| A-2b `RuntimeProfileSnapshot` "유일한 reader" 주장 | 남음 | `adapter/outbound/support/.../runtime/RuntimeProfileSnapshot.java:12-13` 그대로. 실제 reader는 5곳(`RuntimeProfileAccessArchitectureTest` 허용 목록) |
|
||||
| A-2d `RuntimeEnvironment` Javadoc이 bridge를 app-bootstrap 소유로 서술 | 남음 | `shared-contract/.../runtime/RuntimeEnvironment.java:32-33` "app-bootstrap's RuntimeProfileSnapshot" (실제 support leaf) |
|
||||
| A-5a README "1001번째 tenant부터 bucket folding 자동" | 남음 | `shared-contract/README.md:374`. 적용 코드 없음 |
|
||||
| A-6a application-core 문서가 알림 타입을 core 것으로 설명, operation·cache·lease·realtime 절 없음 | 남음 | `application-core/CLAUDE.md:78-82`, `README.md:501-537`(알림 절). README에 operation·cache·lease·realtime·tenant·outbound 절 없음 |
|
||||
| A-6e shared-contract README의 없는 `RateLimiter` 인용 | 해결 | `RateLimiter` 0건 |
|
||||
| S1-#3b `lease/*` use case 호출자 0 | 바뀜 | 소유자 결정 8로 capability 유지. 계약 키트 `DistributedLeaseContract`(testFixtures)를 in-memory·Redis 둘 다 상속 |
|
||||
| S1-#15d shared-contract CLAUDE.md 책임 목록이 일부 패키지만 설명 | 남음 | `concurrency`·`operation`·`ratelimit`·`runtime`·`security` 패키지가 `shared-contract/CLAUDE.md`에 없다. 빈 패키지 `annotation`·`headers`·`registry`(`.gitkeep`만)도 설명 없음 |
|
||||
| S1-#19 이력 주석 | 일부 | 코어 main에서 리뷰 ID를 적은 주석 2곳(`TenantId.java:12`, `MdcKeys.java`) |
|
||||
| X1-#3a `TransactionPort` fake를 testFixtures 1개로 | 일부 | `DirectTransactionPort`(testFixtures)가 생겼고 sample·web이 쓴다. 그러나 다른 구현 9개가 남음: application-core 테스트 4곳(`SubmitDurableOperationUseCaseTest`, `OutcomeAwareRelayTest`, `PublishPendingOutboxEventsUseCaseTest`, `TransactionPortTest`), `application-fileserver/.../testkit/DirectTransactions.java`, application-notification 테스트 4곳 |
|
||||
| X1-#3b 포트별 계약 키트를 소유 leaf testFixtures에 | 일부 | 있음: `DurableOperationStoreContract`, `DistributedLeaseContract`, `OutboxLeaseFencingContract`. 없음: `IdempotencyStorePort`, `DistributedLockPort`, `TransactionPort`, `CacheRegionPort`, `LiveEventReplayPort`, `IntegrationEventEncoderPort`. 01-05 |
|
||||
| X1-#3d `DistributedLockPortContractTest`가 테스트 안 fake를 검증 | 남음 | `application-core/src/test/.../lock/DistributedLockPortContractTest.java:35-46` |
|
||||
| X1-#6b lock과 lease 중 하나만 | 바뀜 | 소유자 결정 8: 둘 다 유지 + 공통 계약 테스트. lease는 키트가 있고 lock은 없다(위 X1-#3d) |
|
||||
| X1-#6d `ClaimFencingContract`를 row lease store마다 | 일부 | outbox는 `OutboxLeaseFencingContract`를 in-memory·JPA가 실행. durable operation lease에 fencing 시나리오가 있는지는 확인 못 함 |
|
||||
| X1-#10b / X2-P1-5 SHA-256 헬퍼 → `Sha256` | 일부 | 대부분 정리. 잔존 복사본은 01-11 |
|
||||
| X2-P1-2b httpclient `RuntimeEnvironment`가 정본과 이름이 같음 | 남음 | `adapter/outbound/httpclient/.../profile/RuntimeEnvironment.java` |
|
||||
| X2-P2-6a 같은 이름 `TenantContext` 2개, 문법이 다름 | 바뀜 | web·GraphQL은 `application-core` `TenantId` 하나로 통일. 그러나 `TenantId` 자체가 3벌, 문법 3가지 — 01-03 |
|
||||
|
||||
## 3. 새 발견
|
||||
|
||||
High 이상은 없다. Medium은 필요한 필드를 모두, Low는 필요한 필드만 쓴다. 설계 선택이 아닌 단순 결함은 "대안 비교: 적용 제외 — 이유"로 둔다.
|
||||
|
||||
### 01-01 새 기능을 어느 leaf에 두는지 세 가지 모양이 있고, 고르는 기준이 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 2, 3, 4, 20, 23, 25 |
|
||||
| 근거 | ① 공유 계층 leaf 안의 패키지: durable operation은 `application-core/.../operation/*` + `persistence-jpa` + web `DurableOperationController` + `app-bootstrap/.../DurableOperationConfig.java`. ② 기능 전용 application leaf: `application-notification`, `application-fileserver`, `application-objectstorage`와 짝이 되는 `persistence-notification`·`persistence-fileserver`·`composition:*`. ③ 한 leaf 수직 슬라이스: `sample-portfolio`가 domain·application·adapter·bootstrap 패키지를 한 leaf에 둔다. `AGENTS.md:128-141` 「기능 개발 프로토콜」은 "새 비즈니스 개념은 domain-core에 먼저 둔다"고만 쓰고, 언제 ②를 고르는지는 어디에도 없다. 유일하게 끝까지 동작하는 예시(sample)는 ③이고 `AGENTS.md:259`는 그것을 "격리된 예시"라고 부른다. 계층 leaf에 기능을 넣는 모양(①)은 테스트 fixture(`app-bootstrap/src/test/java/dev/caskeleton/onboarding/**`)에만 있다. |
|
||||
| 사례(참고) | 파생 서비스 `tech-log-backend` 작업 트리: 기능 파일이 `application-core` 273개, web 53개, persistence-jpa 41개, app-bootstrap 6개, **domain-core 0개**. 도메인 모델은 `application/techlog/*/model`에 있고 `@AggregateRoot`·`ResourceId` 사용 0건. 템플릿의 domain-core 경로가 실제로는 쓰이지 않았다. 이 repo 커밋의 증거가 아니라 사례로만 적는다. |
|
||||
| 발생 조건 | 개발자가 첫 업무 기능을 추가한다. |
|
||||
| 영향 | 기능마다 배치가 달라진다. 계층 leaf(①)에 넣으면 upstream 템플릿 파일과 같은 leaf·같은 패키지 트리에서 병합 충돌이 난다(`persistence-jpa`는 capability 모듈 규칙 7 "이 모듈을 아는 곳은 모듈 자신뿐"과도 부딪힌다). ②를 고르면 `modules.json`·`settings.gradle`·`app-bootstrap/build.gradle`을 고쳐야 한다. domain-core를 건너뛰는 선택은 ArchUnit의 domain 순수성 규칙 밖으로 빠진다(규칙은 `..domain..` 패키지만 본다). |
|
||||
| 심각도·우선순위 | Medium / P2. 기능이 깨지지는 않지만 템플릿의 핵심 약속("경계를 지키며 기능을 추가")을 사용자가 매번 스스로 해석해야 한다. 파생 서비스로 그대로 복제된다. |
|
||||
| 확실성 | 세 모양은 코드로 확인(E1). 각 모양의 병합 비용은 측정 안 함. |
|
||||
| 결정의 근거 | 기록된 의도: 메모와 `AGENTS.md:259`는 "sample은 삭제 가능한 fixture", 실제 기능은 계층 leaf로. 소유자 결정 3·33·34는 ②(별도 leaf)를 기능 플랫폼에 썼다. 두 방향이 문서로 합쳐지지 않았다. |
|
||||
| 이해 비용 | 첫 기능 작성자가 sample·onboarding fixture·durable operation·notification 네 곳을 읽고 공통점을 직접 뽑아야 한다. |
|
||||
| 최소 개선 방향 | `docs/manual/`(또는 `AGENTS.md` 「기능 개발 프로토콜」)에 배치 규칙 표 하나를 둔다: 업무 기능 기본 = ①(domain-core·application-core 아래 `<feature>` 패키지, persistence는 기능 전용 adapter leaf 또는 persistence-jpa 아래 `<feature>` 패키지 중 하나로 고정), 독립 배포·선택 조립이 필요하면 ②. 그리고 ①의 끝까지 동작하는 예시를 하나 둔다(아래 01-02의 onboarding fixture를 그 예시로 키우는 것이 가장 싸다). |
|
||||
| 대안 비교 | (a) 위 방법: 문서 1개 + 예시 1개. (b) sample을 계층 leaf로 쪼갠다: 예시가 실제 모양과 같아지지만 sample 삭제가 어려워진다(지금은 leaf 하나 지우면 끝). (c) 업무 기능도 항상 ② 별도 leaf: 경계가 가장 선명하지만 기능마다 registry 3파일을 고친다. (a)를 고른다. sample의 "통째로 지운다" 성질을 지키면서 판단 기준만 추가한다. |
|
||||
| 비용·부작용 | 문서 유지. 예시 fixture를 실제 컴파일·기동 대상으로 올리면 테스트 시간이 조금 는다. |
|
||||
| 재검토 조건 | 파생 서비스가 2개 이상 생기거나 기능 leaf 추가가 반복되면 (c)와 registry 오버레이(메모의 `modules.project.json` 안)를 다시 비교한다. |
|
||||
| 완료 기준 | 새 기능 작성자가 문서 하나로 "어느 leaf, 어느 패키지, 어떤 이름"을 정할 수 있고, 그 모양의 예시가 ci에서 컴파일·테스트된다. |
|
||||
| 검증 방법 | 예시 기능에 대해 `DomainFeatureOnboardingContractTest`류 검사가 production 규칙(`ProductionClassImportOption` 대상 규칙 포함)을 그대로 통과하는지 본다. |
|
||||
|
||||
### 01-02 onboarding fixture가 "새 기능의 계약 모양"으로 박아 둔 유스케이스가 실제로는 기동에 실패하는 모양이다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 10, 20, 21, 23 |
|
||||
| 근거 | ① `app-bootstrap/src/test/java/dev/caskeleton/onboarding/application/usecase/CreateFeatureAggregateUseCase.java:15,20` — `@RequiresPermission` + `public final class`. ② 같은 조합을 금지하는 규칙 `RequiresPermissionProxyabilityTest.java:44`는 `ProductionClassImportOption`으로 test 클래스를 뺀다. 그래서 fixture는 검사받지 않는다. ③ 규칙의 설명(`:26-34`)은 "final 클래스를 bean으로 만들면 'Cannot subclass final class'로 기동 실패, 16개 유스케이스가 이 상태였다"고 적는다. ④ fixture의 `FeatureAggregateIdFactory`는 `IdFactory<FeatureAggregateId>`를 상속하지 않는다(sample `WorkLogIdFactory`는 상속). ⑤ fixture의 쓰기 포트는 application 쪽 `FeatureAggregateWritePort`, sample은 domain 쪽 `WorkLogRepository` — 같은 역할에 이름·위치가 다르다. `DomainFeatureOnboardingContractTest.java:63-78`는 이 이름들을 "최소 계약"으로 고정한다. |
|
||||
| 발생 조건 | 개발자가 onboarding fixture를 복사해 첫 쓰기 유스케이스를 만들고 bean으로 등록한다. |
|
||||
| 영향 | 앱이 기동하지 않는다(시끄럽지만 늦게 드러난다). bean으로 등록하지 않고 직접 `new` 하면 권한 검사가 조용히 빠진다. |
|
||||
| 심각도·우선순위 | Medium / P2. 템플릿이 "이 모양으로 만들라"고 제시하는 유일한 계층 예시라 복제 범위가 넓다. production ArchUnit이 같은 규칙으로 잡으므로(production 코드로 옮기면 ci가 실패) 피해는 개발 시간 손실이다. |
|
||||
| 확실성 | 정적 확인(E1). fixture를 bean으로 띄워 보지는 않았다. 규칙 설명의 실패 메시지는 규칙 작성자의 기록이다. |
|
||||
| 결정의 근거 | 적용 제외 — fixture가 production 규칙을 따라가지 못한 단순 drift다. |
|
||||
| 최소 개선 방향 | `CreateFeatureAggregateUseCase`에서 `final`을 빼고, `FeatureAggregateIdFactory extends IdFactory<FeatureAggregateId>`로, 쓰기 포트 이름·위치를 sample과 같은 규칙으로 맞춘다(01-12에서 규칙을 정한 뒤). `DomainFeatureOnboardingContractTest`에 `RequiresPermissionProxyabilityTest`의 두 규칙과 `NamingConventionTest`를 fixture에도 평가하는 단언을 추가한다. |
|
||||
| 완료 기준 | fixture가 production에 적용되는 모든 application·domain ArchUnit 규칙을 통과한다. |
|
||||
| 검증 방법 | fixture에 `final`을 다시 넣었을 때 `DomainFeatureOnboardingContractTest`가 실패하는지 변이로 확인한다. |
|
||||
|
||||
### 01-03 `TenantId`가 3벌이고 받아들이는 문법이 셋 다 다르다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(갈라진 중복 복사본) |
|
||||
| 관련 관점 | 11, 15, 17, 23 |
|
||||
| 근거 | ① `application-core/.../tenant/TenantId.java:22` `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}` (1~64자, 대문자·점 허용). web·GraphQL 전송이 인증 토큰에서 만든다(`JwtToAuthenticatedPrincipalConverter.java:60-62`). ② `application-notification/.../platform/api/TenantId.java:6-12` 공백 아님 + 100자 이하뿐(어떤 문자든 허용). 41개 파일이 쓴다. 값은 요청 tenant가 아니라 설정의 `SingleTenantContext`(`adapter/outbound/notification/.../SingleTenantContext.java:20`)에서 오고, `EmailAttachments.java:47`은 환경 이름(`profile().environment()`)으로 TenantId를 만든다. ③ `persistence-jpa/.../experimental/tenant/TenantId.java:17` `[a-z0-9][a-z0-9_-]{1,62}` (2~63자, 소문자만, 점 불가). RLS binder가 쓴다. ④ 변이 M2: 정본 문법에 `/`를 허용해도 `TenantIdTest` 전부 통과. `../public` 케이스는 첫 글자 규칙에서 막혀 `/` 검사를 증명하지 못한다. X2-P2-6a는 `TenantContext` 2개를 하나로 합치며 "완료"됐지만 그 아래 값 타입은 그대로 갈라져 있다. |
|
||||
| 발생 조건 | 파생 서비스가 멀티 테넌시를 켠다. 예: 토큰의 tenant가 `Acme.EU`면 web은 받고, experimental RLS binder는 거부한다. 알림은 요청 tenant를 아예 모른다. |
|
||||
| 영향 | tenant는 보안 경계다. 같은 tenant가 계층마다 다르게 읽히거나 거부되면, 거부 쪽은 기능 실패, 허용 쪽은 경로·키 구성에 들어가는 문자(`/`, 공백)를 막지 못한다. 알림 쪽은 tenant가 요청과 연결되지 않아 tenant 격리 검사를 둘 자리가 없다. |
|
||||
| 심각도·우선순위 | Medium / P2. 기본 조립은 단일 tenant라 지금 피해는 없다. 멀티 테넌시를 켜는 순간 세 문법을 사용자가 직접 맞춰야 하고, 템플릿이 이를 알려 주지 않는다. |
|
||||
| 확실성 | 세 문법은 코드로 확인(E1), 테스트 공백은 변이로 확인(E2). 알림이 요청 tenant를 써야 하는지는 05 영역 판단이 필요하다. |
|
||||
| 결정의 근거 | 정본 `TenantId`의 Javadoc(`:7-12`)은 "모든 전송이 받는 하나의 문법"을 목표로 적는다. 알림·experimental은 그 정리 이전에 만들어졌다. 둘 다 `application-core` edge가 있어(`modules.json`) 정본을 쓸 수 있다. |
|
||||
| 최소 개선 방향 | 알림·experimental의 `TenantId`를 정본으로 바꾼다. RLS가 더 좁은 문법(소문자)을 원하면 binder가 정본을 받아 자기 제약을 추가 검사한다(새 타입을 만들지 않는다). `TenantIdTest` 거부 목록에 `acme/eu`, `acme:eu`를 넣는다. |
|
||||
| 대안 비교 | (a) 위 방법. (b) 문법 문자열만 정본에서 가져다 쓰기: 타입이 셋으로 남아 같은 값을 세 번 검사한다. (c) 현상 유지 + 문서화: 멀티 테넌시를 켜는 사람이 세 곳을 기억해야 한다(원칙상 결함). (a)를 고른다. |
|
||||
| 단순화의 보존 조건 | 알림 DB에 이미 저장된 tenant 값이 정본 문법을 만족하는지 먼저 확인한다(기본값 확인 필요). 만족하지 않으면 읽기 경로에서 거부되므로 이행 순서를 정한다. |
|
||||
| 완료 기준 | `record TenantId` 정의가 repo에 하나뿐이다(messaging vendored 제외). 거부 목록 테스트가 `/`를 포함한다. |
|
||||
| 검증 방법 | 변이 M2를 다시 돌려 테스트가 실패하는지 본다. `git ls-files '*/main/*TenantId.java'`가 1건. |
|
||||
|
||||
### 01-04 `IllegalArgumentException` 하나가 "입력이 틀렸다"와 "서버 조립이 틀렸다"를 함께 뜻하고, web은 둘 다 로그 없이 400으로 바꾼다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 5, 6, 8, 17 |
|
||||
| 근거 | ① `adapter/inbound/web/.../error/GlobalExceptionHandler.java:75-81` — `IllegalArgumentException`이면 `BAD_PARAMETER`(400, retryable false)로 응답하고 로그를 남기지 않는다(같은 파일의 `log.error`는 `:154-194` 다른 경로에만). ② 서버 조립 결함도 IAE로 던져진다: `adapter/outbound/support/.../JsonIntegrationEventEncoder.java:100-102` "no integration event contract is registered", `:104-110` 목적지 불일치, `:113-116` payload 타입 불일치, `:119-127` 크기 초과. ③ 코어 값 객체도 불변식 위반에 IAE를 쓴다(`ValidatedIntegrationEvent`, `ContractDescriptor.java:20-47`, `SchemaResourceId`). 이 값 객체는 요청 입력이 아니라 서버 코드가 만든다. ④ 유스케이스 테스트의 표준 fake `FakeIntegrationEventEncoder`(application-core testFixtures)는 어떤 계약이든 받아 준다(01-05). |
|
||||
| 발생 조건 | 개발자가 새 이벤트 계약을 만들고 bean 등록(`SampleApplicationUseCaseConfig.java:60-93`처럼 계약마다 `@Bean`)을 빠뜨린다. 또는 payload record를 바꾸고 계약의 `exactPayloadRecordType`을 안 바꾼다. |
|
||||
| 영향 | 그 기능의 모든 쓰기 요청이 400 "잘못된 요청"으로 끝난다. 트랜잭션은 롤백되어 데이터 손상은 없다. 서버 로그에 아무것도 없고 5xx 경보도 울리지 않는다. 클라이언트는 자기 요청을 고치려 한다. fake로 쓴 유스케이스 테스트는 통과한다. |
|
||||
| 심각도·우선순위 | Medium / P2. 기능 전체가 멈추지만 실제 encoder로 도는 통합 테스트가 있으면 잡힌다. 진단이 어렵다는 점이 핵심이다. |
|
||||
| 확실성 | 경로는 정적 확인(E1). 실제 요청으로 재현하지는 않았다. |
|
||||
| 결정의 근거 | `X2-P2-2b`(IAE는 모든 전송에서 400)는 현황표의 "에이전트가 정한 것(소유자가 뒤집을 수 있음)" 목록에 있다. 이 발견은 그 결정을 뒤집자는 것이 아니라, 결정이 전제한 "IAE = 입력 오류"가 코어·adapter 코드에서 지켜지지 않는다는 것이다. |
|
||||
| 이해 비용 | 400 하나를 받은 운영자가 원인을 찾으려면 디버거를 붙여야 한다. |
|
||||
| 최소 개선 방향 | 서버 조립 결함을 IAE가 아닌 `IllegalStateException`(→ 기존 catch-all 500 + `log.error`)으로 바꾼다: encoder의 미등록 계약·타입 불일치, 서버가 만드는 값 객체(`ValidatedIntegrationEvent`, `ContractDescriptor`)의 불변식. 요청 크기 초과처럼 입력 탓일 수 있는 것은 IAE로 둔다. 그리고 400 응답에도 WARN 한 줄(예외 타입만)을 남긴다. |
|
||||
| 대안 비교 | (a) 위 방법: 던지는 쪽을 고친다. 소유자 결정을 유지한다. (b) 전송이 IAE를 500으로: 진짜 입력 오류가 500이 된다 — X2-P2-2b와 충돌. (c) 전용 `ServerMisconfigurationException`(shared-contract) 추가: 의미는 가장 선명하지만 타입이 하나 는다. 지금 규모에서는 (a)로 충분하고, IAE/ISE 구분이 반복해서 흐려지면 (c)로 간다. |
|
||||
| 비용·부작용 | encoder·값 객체 테스트의 예외 타입 단언을 바꿔야 한다. |
|
||||
| 완료 기준 | 미등록 계약으로 encode하면 500 + `log.error`가 남는다. |
|
||||
| 검증 방법 | web slice 테스트: 미등록 계약 draft를 append하는 유스케이스를 부르면 500 `INTERNAL_ERROR`, 로그에 원인 메시지. |
|
||||
|
||||
### 01-05 application-core가 소유한 포트 중 절반이 "fake와 실제 adapter가 같은 계약 테스트를 통과한다"는 규칙 밖에 있다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 10, 21, 23 |
|
||||
| 근거 | `AGENTS.md:168-170` 테스트 규칙 6: 포트당 fake 하나를 소유 leaf testFixtures에, fake와 adapter가 같은 추상 계약 테스트를 통과. application-core 포트 17개(`*Port` 인터페이스) 중 계약 키트가 있는 것: `DurableOperationStorePort`(in-memory·JPA), `DistributedLeasePort`(in-memory·Redis), `OutboxStorePort` fencing(in-memory·JPA). 없는 것 중 adapter가 있는 포트: `IdempotencyStorePort`(Redis·PostgreSQL 두 adapter + `InMemoryIdempotencyStore` fake, 공통 계약 없음), `TransactionPort`(`SpringTransaction` vs `DirectTransactionPort` + 다른 구현 9개), `DistributedLockPort`(JPA adapter, fake는 테스트 안 private 클래스 `DistributedLockPortContractTest.java:46`), `CacheRegionPort`(Redis만), `LiveEventReplayPort`(JPA만), `IntegrationEventEncoderPort`(`JsonIntegrationEventEncoder` vs `FakeIntegrationEventEncoder`). `OutboxAppendContract`는 JPA만 상속하고 `InMemoryOutboxStore`는 상속하지 않는다. |
|
||||
| 발생 조건 | 사용 프로젝트가 fake로 유스케이스 테스트를 쓰고 실제 adapter로 배포한다. |
|
||||
| 영향 | fake가 실제와 다르게 동작하면 테스트가 거짓 녹색이다. 예: `FakeIntegrationEventEncoder`는 미등록 계약·목적지 불일치·payload 타입 불일치를 거부하지 않는다 — 01-04의 결함이 단위 테스트에서 안 보이는 이유. 멱등성은 05-02(Redis renew 결함을 fake가 그대로 따라 함)가 실제 사례다. |
|
||||
| 심각도·우선순위 | Medium / P2. 결함 자체가 아니라 결함을 못 잡는 구조다. 멱등성·트랜잭션은 중복 실행·부분 커밋과 직결된다. |
|
||||
| 확실성 | 키트 유무는 grep으로 전수 확인(E1). |
|
||||
| 결정의 근거 | 규칙과 일부 키트(outbox·operation·lease)는 이미 있다. 나머지가 비어 있는 것은 작업 미완(X1-#3a/b/d 남음)이다. |
|
||||
| 최소 개선 방향 | 우선순위: ① `IdempotencyStoreContract`(05-02와 같은 작업), ② `TransactionPortContract`(inRootWrite 중첩 거부, 예외 시 롤백, inNew 독립 커밋) — `SpringTransaction` IT와 `DirectTransactionPort`가 상속, 다른 구현 9개는 `DirectTransactionPort`로 교체, ③ `FakeIntegrationEventEncoder`가 생성자에서 계약 목록을 받아 미등록·목적지·타입을 실제와 같은 예외로 거부, ④ lock fake를 testFixtures로 옮기고 키트화. |
|
||||
| 대안 비교 | (a) 위 순서. (b) fake를 없애고 Testcontainers만: 계약은 맞지만 유스케이스 테스트가 느려지고 application-core가 Spring·DB를 알게 된다. (c) 현상 유지. (a)를 고른다. 규칙과 기존 키트 모양을 그대로 따른다. |
|
||||
| 완료 기준 | adapter가 있는 application-core 포트마다 testFixtures에 `XxxContract`가 있고, fake와 모든 adapter 테스트가 상속한다. `implements TransactionPort`가 main 1개 + testFixtures 1개뿐이다. |
|
||||
| 검증 방법 | 키트마다 fake에 결함 하나를 넣어 키트가 실패하는지 변이로 확인한다. |
|
||||
|
||||
### 01-06 `@RequiresPermission`은 application 계약인데, 검사는 web leaf가 켜 주는 AOP에만 있다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 5, 15, 21, 27 |
|
||||
| 근거 | ① 선언: `application-core/.../security/RequiresPermission.java`. ArchUnit `MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`(`ApplicationBoundaryArchitectureTest.java:404-425`)이 쓰기 유스케이스에 선언을 강제한다. ② 검사: `adapter/inbound/web/.../authz/MethodSecurityConfig.java:26-60`의 advisor 하나. `WebSecurityAutoConfiguration.java:47`이 import한다. web 외 전송(GraphQL·gRPC·WebSocket)과 composition 모듈에는 검사 장치가 없다. web이 빠진 조립에서 선언만 남는지 확인하는 기동 검사도 없다(app-bootstrap main에서 `RequiresPermission` 참조는 `DurableOperationConfig` 주석뿐). ③ 시스템이 부르는 유스케이스: `PublishPendingOutboxEventsUseCase.java:31` `@RequiresPermission("outbox:relay")`는 relay가 bean이 아니라 `new`로 만들어져(`composition/outbox-relay/.../OutboxRelayAutoConfiguration.java:76-77`) 한 번도 검사되지 않는다. 규칙을 통과하려고 붙인 선언이다. ④ 그 이유를 설명하는 `application-core/README.md:389-391`은 "final 클래스라 프록시 불가"라고 적지만 지금 클래스는 final이 아니다(`:37`). 남은 진짜 이유(스케줄러 스레드엔 Authentication이 없어 bean으로 만들면 매 tick 거부)는 README에만 있고 코드에는 없다. |
|
||||
| 발생 조건 | (가) 파생 서비스가 gRPC 전용·배치 전용으로 `adapter:inbound:web`을 뺀다(`app-bootstrap/build.gradle:213`). (나) 누군가 relay 유스케이스를 bean으로 등록한다. |
|
||||
| 영향 | (가) 권한 선언이 있는 모든 유스케이스가 검사 없이 실행된다. 기동은 정상이다. (나) relay가 매 tick 거부되어 outbox가 쌓인다. |
|
||||
| 심각도·우선순위 | Medium / P3. 기본 조립에는 web이 `implementation`으로 고정이라 (가)는 사용자가 구조를 바꿀 때만 생긴다. 생기면 조용한 인가 우회다. |
|
||||
| 확실성 | 정적 확인(E1). web 없는 조립을 띄워 보지는 않았다. |
|
||||
| 결정의 근거 | `application-core/README.md:161-188`: 결정(포트)은 framework-free, 메커니즘(AOP)은 web. 이 분리 자체는 타당하다. 빠진 것은 "메커니즘이 없을 때 실패하는 장치"와 "시스템 호출자의 권한 표현"이다. 41절 검토는 5.1. |
|
||||
| 최소 개선 방향 | ① `@RequiresPermission` 선언 bean이 있는데 advisor bean이 없으면 기동 실패하는 검사를 support 또는 composition:service-runtime에 둔다. ② 시스템 호출 유스케이스는 `@RequiresPermission` 대신 `@UseCaseCapability`에 "시스템 전용" 표시를 두고 ArchUnit 규칙이 그 경우를 면제한다. 그리고 그 클래스 Javadoc에 "bean으로 만들지 말 것, 이유"를 적는다. ③ README:389-391을 고친다. |
|
||||
| 대안 비교 | (a) 위 방법. (b) 유스케이스 본문에서 `AuthorizationPort`를 직접 부른다: 전송과 무관하게 검사되지만 principal을 command에 실어야 하고 모든 유스케이스 시그니처가 바뀐다. (c) composition이 유스케이스를 데코레이터로 감싼다: AOP 의존은 없어지지만 bean 등록 규칙이 하나 더 생긴다. (a)를 고른다. 지금 구조를 유지하면서 빠지는 경우만 시끄럽게 만든다. |
|
||||
| 완료 기준 | web을 뺀 조립에서 선언 bean이 있으면 기동이 실패한다. relay 유스케이스에 장식용 권한 선언이 없다. |
|
||||
| 검증 방법 | `ApplicationContextRunner`로 web 없이 `@RequiresPermission` bean 하나를 등록해 기동 실패를 단언한다. |
|
||||
|
||||
### 01-07 이벤트 식별자 문법이 다섯 곳에 복사되어 있고 길이 상한이 둘로 갈린다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(갈라진 중복) |
|
||||
| 관련 관점 | 10, 17, 23 |
|
||||
| 근거 | `[A-Za-z0-9][A-Za-z0-9._:-]` 문법: `EventId.java:6,9`(96자), `IntegrationEventDraft.java:22,49` correlation(96자), `ValidatedIntegrationEvent.java:37` correlation·causation(128자), `SubmitDurableOperationUseCase.java:67-68`(복사, 96자), sample `PortfolioEventOutbox.java:41-42`(복사, 96자). 변이 M5: draft 상한 96→200이어도 테스트 전부 통과. 같은 encoder를 가리키는 `ContractDescriptor.serializerId`가 `"json-envelope-v1"`(`PortfolioEventContract.java:46`, `DurableOperationSubmittedContract.java:44`)과 `"json-schema-envelope-v1"`(`WorkLogReservedContractContribution.java:28`) 두 표기다. serializerId는 검증 없이 catalog revision 해시에만 들어간다(`JsonIntegrationEventEncoder.java:267`). |
|
||||
| 발생 조건 | 누가 한 곳의 상한을 바꾼다. 또는 draft를 거치지 않고 DB에서 복원한 이벤트(128자 correlation)를 다시 draft 경로로 보낸다. |
|
||||
| 영향 | 같은 값이 경로에 따라 통과·거부가 갈린다. serializerId 표기 차이는 지금은 해시 값만 바꾸지만, 나중에 serializer 선택에 쓰이면 한 계약이 조용히 다른 serializer를 고른다. |
|
||||
| 심각도·우선순위 | Low / P3. 지금 상한은 draft(96) ≤ validated(128)라 정상 경로에서 충돌하지 않는다. |
|
||||
| 결정의 근거 | 적용 제외 — 같은 규칙의 복사본을 하나로 모으는 단순 정리다. |
|
||||
| 최소 개선 방향 | application-core `messaging.event`에 `IntegrationIdentity.GRAMMAR`·`MAX_LENGTH`(또는 `isCanonical(String)`) 하나를 두고 다섯 곳이 쓴다. correlation 상한은 DB 열(varchar 128)에 맞춰 하나로 정한다. serializerId는 encoder가 아는 값 목록과 대조해 모르는 값이면 기동 시 거부한다. draft 상한 경계값 테스트를 추가한다. |
|
||||
| 완료 기준 | 문법 문자열 리터럴이 main에 한 번만 나온다. M5 변이가 실패한다. |
|
||||
| 검증 방법 | grep + 변이 M5 재실행. |
|
||||
|
||||
### 01-08 장기 실행 작업(LRO) 공개 계약이 두 벌이다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(갈라진 중복) |
|
||||
| 관련 관점 | 17, 23, 24, 27 |
|
||||
| 근거 | ① shared-contract `operation/Operation.java`·`OperationStatus.java`: 필드 `status`, 값 `PENDING·RUNNING·SUCCEEDED·FAILED·CANCELLED`, Javadoc이 `GET /v1/operations/{id}`의 본문이라고 선언. main 소비자는 sample의 `OperationsController`·`SampleOperationStore`뿐. ② application-core `DurableOperation`·`DurableOperationState`(`CANCELED`·`EXPIRED` 포함, 철자 다름) + web `OperationHttpResponse`(필드 `state`, `submittedAt`·`progress`·`expiresAt` 등) — 같은 경로 `GET /operations/{operationId}`(`DurableOperationController.java:48,106`). 소유자 결정 15·26은 ②를 정본 HTTP 어댑터로 정했다. |
|
||||
| 발생 조건 | 파생 서비스가 LRO를 만들 때 shared-contract의 이름이 "skeleton-wide 계약"이라 ①을 고른다. 또는 sample 경로와 durable operation을 함께 켠다(두 컨트롤러가 같은 경로를 잡는다). |
|
||||
| 영향 | 같은 개념에 두 개의 공개 응답 모양과 두 개의 상태 어휘가 생긴다. 클라이언트 SDK가 둘 다 처리해야 한다. 같은 앱에 둘 다 있으면 경로 충돌로 기동이 실패한다(sample 앱은 app-bootstrap을 쓰지 않아 지금은 충돌 없음). sample은 모르는 id에 IAE를 던져 404가 아니라 400을 준다(`OperationsController.java` `poll`). |
|
||||
| 심각도·우선순위 | Medium / P3. 공개 계약의 일관성 문제이고, 템플릿 사용자가 고를 때 틀린 쪽을 고르기 쉽다. |
|
||||
| 결정의 근거 | 기록된 결정은 ②를 정본으로 만들었고 ①을 정리하는 결정은 없다. |
|
||||
| 최소 개선 방향 | ①을 sample leaf로 옮기거나 삭제한다. sample LRO 예시는 ②의 유스케이스로 다시 쓰거나, sample 전용 타입으로 남기고 shared-contract에서는 뺀다. shared-contract README의 operation 절(`README.md:293-`)을 정리한다. |
|
||||
| 대안 비교 | (a) ①을 sample로 내림: shared-contract가 줄고 정본이 하나가 된다. sample의 wire 모양은 유지. (b) ①을 정본으로 하고 ②의 HTTP 응답을 ①에 맞춤: 소유자 결정 26과 충돌. (c) 둘 다 유지 + 문서: 원칙상 결함 유지. (a)를 고른다. |
|
||||
| 단순화의 보존 조건 | sample의 `POST /worklogs:export` 응답 모양(202 + Location + 상태 enum)과 그 계약 테스트는 그대로 통과해야 한다. |
|
||||
| 완료 기준 | shared-contract에 `operation` 패키지가 없거나, 있으면 production 소비자가 있다. |
|
||||
| 검증 방법 | sample web contract 테스트 통과, `git grep shared.operation`이 sample 밖에서 0건. |
|
||||
|
||||
### 01-09 통합 이벤트를 만드는 규칙(tenant 범위·순서·correlation)을 기능마다 다시 정한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 3, 11, 20, 22, 23 |
|
||||
| 근거 | `IntegrationEventDraft`는 10개 필드를 받는다. 채우는 규칙이 두 곳에서 다르게 정해졌다. ① durable operation `SubmitDurableOperationUseCase.java:64,66,143-157`: tenant 범위는 상수 `"global"`(요청에는 `command.tenantId()`가 있는데 쓰지 않음), 순서 `(1,0)` 고정, correlation = 이벤트 id. ② sample `PortfolioEventOutbox.java:39-42,72-97`: tenant 범위 `"portfolio"`, 순서 = 발생 시각 마이크로초, correlation = 요청 correlation(문법에 안 맞으면 이벤트 id). 조립 헬퍼(②)는 sample에만 있어 production 기능은 ①처럼 직접 조립한다. 도메인 이벤트 쪽도 틀만 있다: `@DomainEvent` 마커는 있지만 aggregate가 이벤트를 모으는 수단은 없고, sample `CreateWorkLogUseCase.java:79-84`는 `WorkLogReserved`(category·periodStart 포함)를 만들어 id만 꺼내 쓴다. |
|
||||
| 발생 조건 | 새 기능이 이벤트를 발행한다. |
|
||||
| 영향 | 같은 outbox·relay를 지나는 이벤트가 tenant 범위와 순서의 의미를 기능마다 다르게 가진다. 소비자가 tenant로 나누거나 순서로 중복을 거르면 기능마다 다르게 동작한다. tenant가 있는 durable operation 이벤트가 `"global"`로 나가 소비자 쪽 tenant 격리 근거가 사라진다. |
|
||||
| 심각도·우선순위 | Medium / P3. 지금 소비자가 템플릿 안에 없다. 이벤트를 쓰는 첫 파생 기능부터 갈라진다. |
|
||||
| 결정의 근거 | `PortfolioEventOutbox` Javadoc(`:19-35`)이 규칙과 이유를 잘 적어 두었다. 그 결정을 application-core로 올리지 않은 것이 빠진 부분이다. |
|
||||
| 최소 개선 방향 | application-core에 `IntegrationEventAppender`(이름은 예시) 하나: 입력은 계약·aggregate 종류·aggregate id·tenant(`TenantId` 또는 "단일 tenant" 상수)·payload, 순서·correlation 규칙은 한 곳에서. sample과 durable operation이 이것을 쓴다. 도메인 이벤트→통합 이벤트 변환 위치는 01-01 문서의 판단 지점으로 적는다. |
|
||||
| 대안 비교 | (a) 헬퍼 승격. (b) 규칙을 문서로만: 기능마다 다시 구현한다. (c) aggregate가 도메인 이벤트를 모으고 저장 시 adapter가 변환(Spring Data `@DomainEvents` 방식): 도메인이 프레임워크 없이 이벤트를 들 수 있지만 domain-core에 베이스 클래스가 생기고 변환 위치가 persistence로 간다. (a)를 고른다. (c)는 두 번째 이벤트 소비자가 생기면 다시 본다. |
|
||||
| 완료 기준 | `new IntegrationEventDraft<>(`가 main에서 헬퍼 한 곳에만 있다. |
|
||||
| 검증 방법 | 헬퍼 단위 테스트(tenant·순서·correlation 규칙)와 grep. |
|
||||
|
||||
### 01-10 application-core 한 이름공간에 커널·플랫폼 기능·(파생 시) 업무 기능이 섞인다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안 |
|
||||
| 관련 관점 | 2, 4, 24, 25 |
|
||||
| 근거 | `application-core/src/main/java/dev/caskeleton/application/` 아래 17개 패키지: 커널(`usecase`·`command`·`query`·`capability`·`transaction`·`security`·`tenant`), 플랫폼 기능(`outbox`·`idempotency`·`operation`·`lease`·`lock`·`cache`·`realtime`·`messaging`), 묶음 이름만 있는 `outbound`(`CallBudget`·`SecretReference`·`SecretSourcePort` — 서로 관계없음), `observability`. 01-01의 ①을 따르면 업무 기능도 같은 수준(`application/<feature>`)에 들어간다(파생 사례: `application/techlog`). |
|
||||
| 영향 | 업무 기능 이름이 플랫폼 패키지와 겹칠 수 있다(`operation`, `lock`, `cache`). 새 사람은 어느 패키지가 "건드리지 말 템플릿"이고 어느 것이 "우리 기능"인지 경로로 구분할 수 없다. upstream 병합 시 충돌 범위도 같은 트리다. |
|
||||
| 심각도·우선순위 | Low / P3. |
|
||||
| 최소 개선 방향 | 업무 기능 패키지 규칙을 01-01 문서에서 정한다(예: `dev.caskeleton.application.feature.<name>` 또는 파생 서비스 루트 패키지). `outbound` 패키지는 내용별로 흩는다(`SecretSourcePort`·`SecretReference` → `secret`, `CallBudget` → 사용처). 이름 변경은 API surface 파일과 함께 한 번에. |
|
||||
| 대안 비교 | (a) 패키지 규칙만. (b) 플랫폼 기능을 `application-platform` leaf로 분리: 경계는 선명하지만 registry·edge가 늘고 결정 34(edge를 늘리지 않음)와 같은 비용 판단이 필요. (a)를 고른다. |
|
||||
|
||||
### 01-11 공용 다이제스트 헬퍼가 있는데 복사본이 남아 있고, 일부 leaf는 registry 때문에 복사가 강제된다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(갈라진 중복) |
|
||||
| 관련 관점 | 16, 23 |
|
||||
| 근거 | shared-contract `digest/Sha256`·`HmacSha256`이 정본이다(`shared-contract/CLAUDE.md` 책임 목록). shared-contract edge가 **있는데** 복사한 곳: `application-fileserver/.../observability/SafeFileFingerprint.java:37-43`(`HmacSha256.sign` + hex 앞 16자와 같음), `cache-redis/.../capability/RedisKeys.java:59-71`(inline FQN `javax.crypto.Mac`). edge가 **없어서** 복사할 수밖에 없는 곳: `identifier/HmacUserPrincipalPseudonymizer.java:38`, `persistence-mongo`의 `MongoTenantContext.java:28`·`MongoCredentialReference.java:57`·`MongoAdminCommand.java:98`·`MongoKeysetCursorCodec.java:160`, `application-objectstorage`의 `ObjectIdentitySupport.java:77`·`ObjectDigest.java:35`, `redis-sdk/ConfiguredRedisPolicyAuthority.java:85`. X1-#10b·X2-P1-5는 "완료"로 닫혔다. |
|
||||
| 영향 | 다음 수정(예: 키 길이 검사, constant-time 비교)이 정본에만 들어가고 복사본은 남는다. |
|
||||
| 심각도·우선순위 | Low / P3. 지금 복사본에 알려진 결함은 없다. |
|
||||
| 최소 개선 방향 | edge가 있는 두 곳은 정본으로 바꾼다. edge가 없는 leaf는 registry에 `shared-contract` edge를 줄지(stdlib 전용 leaf라 방향상 문제 없음), 복사를 허용하고 그 사실을 leaf CLAUDE.md에 적을지 정한다. |
|
||||
| 대안 비교 | (a) edge 추가: 복사 제거, 대신 shared-contract가 더 많은 leaf의 공통 의존이 된다. (b) 복사 허용 + 문서: edge 그래프 유지. messaging·gRPC는 이미 (b)를 의도로 적었다(`shared-contract/CLAUDE.md` "keep their own copies"). 템플릿 자체 leaf는 (a), vendored 플랫폼은 (b)를 권한다. |
|
||||
|
||||
### 01-12 이름 규칙의 정본 문서가 없고, 같은 역할에 이름이 여러 가지다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(문서) + 개선 제안 |
|
||||
| 관련 관점 | 4, 23, 24 |
|
||||
| 근거 | `NamingConventionTest.java:12-17`이 이름 규칙의 SSOT로 `.agents/plugins/ca-superpowers/rules/code-conventions.md`를 가리키고 "[판단] 규칙(N2/N7/N8...)은 리뷰가 맡는다"고 적는다. 그 파일은 repo에 없다(`git ls-files` 0건). 실제 이름: 유스케이스 `*UseCase`(application-core 7, sample 21) vs `*ApplicationUseCase`(fileserver 21, notification 7) + `*Service`(notification 8, fileserver 4). 저장 포트 `*Repository`(sample domain) vs `*StorePort`(application-core 3, notification 12) vs `*WritePort`(onboarding fixture) vs `*QueryPort`. id 팩토리는 `IdFactory` 상속(sample) vs 상속 안 함(onboarding, `OutboxEventIdFactory`). |
|
||||
| 영향 | 새 기능 작성자가 어느 이름을 따라야 할지 정할 근거가 없다. 판단 규칙을 "리뷰가 맡는다"고 했는데 리뷰가 볼 문서가 없다. |
|
||||
| 심각도·우선순위 | Low / P3. |
|
||||
| 최소 개선 방향 | 이름 규칙 표를 `application-core/CLAUDE.md`(이미 "Naming convention" 절이 있음, `:84-90`)에 합치고 `NamingConventionTest`의 링크를 그쪽으로 바꾼다. 저장 포트는 "domain이 소유하면 `*Repository`, application이 소유하면 `*StorePort`" 같은 한 줄 기준을 적는다. |
|
||||
|
||||
### 01-13 참조 예시의 수정 유스케이스에 소유자 검사가 없다는 사실이 코드에 보이지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안(위험 가시성) |
|
||||
| 관련 관점 | 5, 15, 20 |
|
||||
| 근거 | `sample-portfolio/.../UpdateWorkLogUseCase.java:31-74`는 `worklog:write` 권한만 보고 `WorkLog.owner()`를 확인하지 않는다. 다른 사용자의 work log를 고칠 수 있다. `sample-portfolio/README.md:259-263`은 "소유자 범위 인가(ABAC)는 의도적으로 뒤로 미룬 확장"이라고 적는다. 코드에는 그 표시가 없다. 템플릿의 객체 인가 포트 `application-core/.../security/ObjectAccessPolicy.java`는 sample에서 쓰이지 않고, durable operation은 자기 전용 `DurableOperationAccessPolicy`를 쓴다. 객체 인가의 모양이 셋(없음 / 전용 정책 / `ObjectAccessPolicy`)이다. |
|
||||
| 영향 | 사용자가 sample을 복사하면 객체 인가 없는 수정이 그대로 복제된다(가이드 31절 "다른 사용자 리소스 접근"). |
|
||||
| 심각도·우선순위 | Low / P3. sample은 fixture이고 의도가 README에 있다. 그러나 원칙상 코드에 드러나야 한다. |
|
||||
| 최소 개선 방향 | `UpdateWorkLogUseCase` Javadoc 첫 줄에 "소유자 검사 없음 — 의도적, README 링크"를 적는다. 더 나은 방법은 sample의 수정·삭제 하나를 `ObjectAccessPolicy`로 보호해 객체 인가 예시를 만드는 것이다. |
|
||||
|
||||
### 01-14 작은 결함 묶음 (각각 독립, Low / P3)
|
||||
|
||||
| 항목 | 근거 | 개선 |
|
||||
| --- | --- | --- |
|
||||
| README가 relay 유스케이스를 final이라고 설명 | `application-core/README.md:389-391` vs 클래스 `PublishPendingOutboxEventsUseCase.java:37`(non-final) | 01-06의 ③ |
|
||||
| shared-contract 빈 패키지 3개 | `shared/annotation`·`headers`·`registry`에 `.gitkeep`만. 무엇을 둘 자리인지 설명 없음 | 쓰임을 CLAUDE.md에 적거나 삭제 |
|
||||
| `IdempotencyContractTest`·`CacheRegionContractTest`가 이름은 계약 테스트인데 값 타입 테스트다 | `application-core/src/test/.../idempotency/IdempotencyContractTest.java`, `cache/CacheRegionContractTest.java` — 포트 구현을 받지 않는다. 01-05의 진짜 계약 키트와 이름이 겹친다 | `*ValueTest` 등으로 이름 변경 |
|
||||
| sample `OutboxEventIdFactory`가 domain 패키지에 있다 | `sample-portfolio/.../domain/worklog/OutboxEventIdFactory.java` — outbox는 도메인 개념이 아니고 이 팩토리는 `application/event/PortfolioEventOutbox`만 쓴다 | application 쪽으로 이동 |
|
||||
| `WorkLogInvariantException.TITLE_BLANK`이 409로 나간다 | `DomainExceptionHandler.java` `handleWorkLogInvariant` → `WORKLOG_CONFLICT` | reason별 매핑(Poster처럼) |
|
||||
|
||||
## 4. 31절 시나리오 추적
|
||||
|
||||
### 4.1 정상 쓰기 요청 — sample `POST /worklogs` (적용)
|
||||
|
||||
```text
|
||||
HTTP 요청
|
||||
→ (web 보안 필터) JWT 검증 → AuthenticatedPrincipal(roles, tenant)
|
||||
→ WorkLogController.create(@Valid CreateWorkLogRequest) ── 입력 검증(Bean Validation)
|
||||
→ WorkLogWebMapper.toCommand(body, 소유자=토큰 subject) ── DTO → Command
|
||||
→ [AOP 프록시] RequiresPermissionAuthorizationManager ── "worklog:write" 권한 검사
|
||||
→ CreateWorkLogUseCase.handle
|
||||
tx.inWrite { ── 트랜잭션 시작
|
||||
WorkLog.create(...) ── 불변식(제목 공백 등)
|
||||
WorkLogRepository.save → WorkLogRepositoryAdapter(JPA) ── INSERT + 감사 필드
|
||||
PortfolioEventOutbox.append → encoder → OutboxAppendPort ── 같은 트랜잭션에 outbox INSERT
|
||||
} ── 커밋
|
||||
→ 200 + ETag + WorkLogResponse
|
||||
(커밋 뒤) outbox relay가 따로 claim → 발행
|
||||
```
|
||||
|
||||
| 항목 | 관찰 |
|
||||
| --- | --- |
|
||||
| 입력 신뢰 수준 | 본문은 신뢰하지 않음 → `@Valid`와 `CreateWorkLogCommand` compact constructor(`CreateWorkLogCommand.java:24-30`)가 두 번 검사. 소유자는 본문이 아니라 검증된 토큰에서 온다(`WorkLogController.java:217-`). |
|
||||
| 인가 위치 | 유스케이스 bean의 AOP 프록시. 유스케이스 코드 안에는 없다(01-06). 객체 인가는 생성이라 해당 없음. |
|
||||
| 규칙 소유 객체 | `WorkLog`(aggregate). 기본 소유자 상수 `"sample-owner"`(`WorkLog.java:16`)가 남아 있어 owner 없는 `create` 오버로드가 호출되면 가짜 소유자가 찍힌다 — 현재 호출자는 owner 있는 쪽만. |
|
||||
| 트랜잭션 | `tx.inWrite` 하나. 저장과 outbox append가 한 커밋이다(이중 쓰기 없음). |
|
||||
| 외부 부작용 | 요청 안에서는 없다. 발행은 relay가 커밋 뒤에 한다. |
|
||||
| 성공의 의미 | 200은 "DB와 outbox에 커밋됨"이다. 이벤트 발행 완료는 아니다. 생성인데 201이 아니라 200이다. |
|
||||
| 오류 변환 | 불변식 → `DomainExceptionHandler`(sample, web 전용) → `PortfolioErrorCode`. GraphQL·gRPC로 같은 유스케이스를 열면 이 매핑을 다시 써야 한다(4.4·7절 판단 지점). 서버 조립 오류는 400으로 숨는다(01-04). |
|
||||
| 진단 정보 | correlation id가 MDC와 이벤트 correlation에 같이 실린다(`PortfolioEventOutbox`). 400 경로에는 로그가 없다. |
|
||||
| 성능 | 생성 1건 = INSERT 2(work_log, outbox). 수정은 `WorkLogRepositoryAdapter.save`가 감사 필드를 옮기려고 `findById`를 한 번 더 부른다(유스케이스의 `findById` 포함 SELECT 2 + UPDATE 1). 같은 영속성 컨텍스트라 두 번째 SELECT는 1차 캐시에서 끝날 수 있지만 코드상 보장은 아니다. |
|
||||
|
||||
### 4.2 다른 사용자 리소스 접근 (적용)
|
||||
|
||||
- sample `PATCH /worklogs/{id}`: 권한만 보고 소유자는 안 본다. 다른 사용자의 글을 고칠 수 있다(01-13, README상 의도).
|
||||
- core `GET /operations/{id}`: `DurableOperationAccessPolicy.mayAccess`가 principal과 tenant를 둘 다 비교하고, 실패하면 없는 것과 같은 404를 준다. 변이 M1(tenant 비교 삭제)을 테스트 5개가 잡았다. 템플릿 안에서 객체 인가가 가장 잘 된 경로다.
|
||||
|
||||
### 4.3 중복·동시 요청 (적용, 범위 한정)
|
||||
|
||||
- sample 생성은 `NOT_IDEMPOTENT`로 선언하고 `Idempotency-Key`를 받지 않는다(`sample-portfolio/README.md:253-255`). 선언과 동작이 맞다.
|
||||
- sample 수정은 `If-Match` 버전을 트랜잭션 안에서 비교한다(`UpdateWorkLogUseCase.java:39-41`) + JPA `@Version`. 동시 수정은 412 또는 낙관적 락 충돌로 끝난다.
|
||||
- durable operation 제출은 store가 `ON CONFLICT`로 "이미 있음"을 답하고, 새로 만든 경우에만 outbox에 append한다(`SubmitDurableOperationUseCase.java:124-131`).
|
||||
- 멱등성 executor 자체의 경쟁은 05 영역(05-02)에서 다룬다.
|
||||
|
||||
### 4.4 선택 어댑터 제거 — `adapter:inbound:web`을 뺀다 (적용, 정적 추적)
|
||||
|
||||
`@RequiresPermission` 검사기가 함께 사라지고, 기동 검사가 없어 선언만 남는다(01-06). 이 영역 코어 타입(shared-contract `ApiErrorCarrier`·`ApiErrorCode`)은 GraphQL·gRPC 오류 매퍼도 쓰므로 web을 빼도 오류 모델은 남는다.
|
||||
|
||||
### 적용 제외·다른 영역
|
||||
|
||||
| 시나리오 | 사유 |
|
||||
| --- | --- |
|
||||
| 외부 응답 지연·유실 | > 05(httpclient·알림). 코어는 `CallBudget` 값 타입만 소유 |
|
||||
| DB 오류·경쟁 | > 03(persistence). 코어는 `TransactionPort` 계약만 소유 — 계약 키트 공백은 01-05 |
|
||||
| 메시지 중복·역순 | > 메시징 영역. 코어 쪽 영향(순서·tenant 규칙 분기)은 01-09 |
|
||||
| 신·구 버전 공존 | 이벤트 payload 버전(`payloadVersion`)과 schema 해시 고정은 확인. 실제 v1→v2 공존 예시가 없어 미검증 |
|
||||
| 여러 서버의 작업 실행 | > outbox relay·lock(03/메시징). 코어 쪽 fencing 키트는 2절 X1-#6d |
|
||||
| 세션·토큰 갱신 경쟁 | > web 영역 |
|
||||
| 큰 입력·목록 조회 | sample 배치 생성 1000건 상한 확인(`README.md:256-258`). 페이지 조회는 web·persistence 영역 |
|
||||
| 종료·재시작 | > bootstrap 영역 |
|
||||
|
||||
## 5. 41절 설계 선택 검토
|
||||
|
||||
### 5.1 `@RequiresPermission`: 선언은 application, 검사는 web의 AOP
|
||||
|
||||
| 질문 | 답 |
|
||||
| --- | --- |
|
||||
| 1. 무엇이 필요한가 | 쓰기 유스케이스가 권한 없이 실행되지 않는다. application-core는 Spring을 모른다. |
|
||||
| 2. 지킬 성질 | 선언된 모든 유스케이스 호출은 검사를 거친다. 검사 장치가 없으면 실행되지 않는다(fail-closed). |
|
||||
| 3. 현재 보장 | 선언 강제(ArchUnit D4), 프록시 가능성 강제(`RequiresPermissionProxyabilityTest`), 검사(`MethodSecurityConfig`), 인증 없으면 거부. **보장하지 않는 것**: web이 없을 때, bean이 아니게 만들었을 때, self-invocation. 마지막 둘은 README가 "정적 분석 사각지대"로 적었다. |
|
||||
| 4. 대안 | (a) 현행 + 장치 부재 시 기동 실패. (b) 유스케이스 본문에서 `AuthorizationPort` 직접 호출. (c) composition이 데코레이터로 감싸기. |
|
||||
| 5. 득실 | (a) 변경 작고 기존 구조 유지, AOP 사각지대는 남음. (b) 전송·bean 여부와 무관하게 검사, 대신 principal을 command에 실어야 하고 모든 유스케이스·테스트가 바뀜. (c) AOP 없이 명시적, 대신 bean 등록 규칙 하나 추가. |
|
||||
| 6. 현재 조건에서의 선택 | 기본 조립에 web이 고정이므로 (a)가 비용 대비 맞다. 01-06. |
|
||||
| 7. 바뀔 조건 | web 없는 조립(gRPC 전용·배치 전용)이 실제로 생기거나, 시스템 호출 유스케이스가 늘면 (b)를 다시 본다. |
|
||||
|
||||
### 5.2 새 기능의 배치: 계층 leaf 패키지 vs 기능 leaf vs 수직 슬라이스
|
||||
|
||||
| 질문 | 답 |
|
||||
| --- | --- |
|
||||
| 1. 무엇이 필요한가 | 파생 서비스가 업무 기능을 추가해도 upstream 변경을 계속 받고(메모의 운영 방식), 경계 검사가 기능 코드에도 적용된다. |
|
||||
| 2. 지킬 성질 | 의존 방향(registry), domain 순수성, 유스케이스 계약. 그리고 템플릿 파일과 기능 파일이 섞이지 않아 병합이 쉽다. |
|
||||
| 3. 현재 보장 | 의존 방향은 leaf 단위로 강제된다. 패키지 수준 규칙은 `..domain..`·`..application..`·`..adapter..` 이름에 걸린다 — 어느 leaf에 두든 패키지 이름을 지키면 검사된다. 배치 자체에 대한 규칙·문서는 없다(01-01). |
|
||||
| 4. 대안 | ① 공유 계층 leaf 안 `<feature>` 패키지. ② 기능별 leaf(`application-<f>`, `persistence-<f>`, `composition:<f>`). ③ 한 leaf 수직 슬라이스(sample). |
|
||||
| 5. 득실 | ① 파일 추가만으로 끝나 시작이 빠르다. 템플릿 leaf와 같은 트리라 병합 충돌 면이 넓고, persistence-jpa 같은 capability 모듈에 업무 코드가 섞인다. ② 경계·삭제가 가장 선명하다. 기능마다 registry 3파일을 고친다. ③ 기능 하나를 통째로 지울 수 있다. 대신 leaf 하나가 모든 계층에 의존해 leaf 단위 방향 검사가 기능 안에서는 무력하고 ArchUnit 패키지 규칙에만 기댄다. |
|
||||
| 6. 현재 조건에서의 선택 | 업무 기능 기본은 ①(파생 사례도 이쪽), 단 persistence 위치는 하나로 고정. 선택 조립이 필요한 플랫폼 기능은 ②(이미 그렇게 함). ③은 fixture 전용. 이 선택을 문서와 예시로 고정하는 것이 01-01. |
|
||||
| 7. 바뀔 조건 | 파생 서비스가 여럿이 되어 같은 업무 기능을 공유하거나, 한 서비스의 기능 수가 늘어 application-core 컴파일·테스트 시간이 문제가 되면 ②로 옮긴다. |
|
||||
|
||||
### 5.3 `TransactionPort`: 콜백 포트로 트랜잭션 경계를 유스케이스 본문에 둔다
|
||||
|
||||
| 질문 | 답 |
|
||||
| --- | --- |
|
||||
| 1. 무엇이 필요한가 | 유스케이스가 트랜잭션 경계를 정하되 Spring `@Transactional`을 import하지 않는다. |
|
||||
| 2. 지킬 성질 | 저장과 outbox append가 한 커밋. 외부 호출은 트랜잭션 밖. root write는 바깥 트랜잭션이 있으면 거부. |
|
||||
| 3. 현재 보장 | 인터페이스(`TransactionPort.java`), ArchUnit `USE_CASE_CAPABILITY_MATCHES_TRANSACTION_PORT_BOUNDARY`·`APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION`, `@UseCaseCapability.transactionMode` 선언과 실제 호출의 대조. **보장하지 않는 것**: fake와 `SpringTransaction`이 같은 의미라는 것(공통 계약 없음, 01-05). Runnable 기본 메서드는 `TransactionPortTest`가 위임을 검사한다. |
|
||||
| 4. 대안 | (a) 현행 콜백 포트. (b) composition이 유스케이스 bean에 `@Transactional` 프록시를 씌움. (c) 유스케이스마다 "unit of work" 객체를 주입. |
|
||||
| 5. 득실 | (a) 경계가 본문에 보이고, 트랜잭션 밖 외부 호출을 코드 모양으로 강제할 수 있다(relay가 그렇게 씀). 람다 중첩이 생기고 checked 예외를 못 던진다(문서화됨). (b) 본문이 깨끗하지만 경계가 선언으로 숨어 "어디까지가 한 커밋인가"를 코드로 못 본다. 01-06과 같은 AOP 사각지대도 생긴다. (c) 더 유연하지만 지금 요구보다 무겁다. |
|
||||
| 6. 현재 조건에서의 선택 | (a)가 맞다. "위험은 코드에 드러나야 한다"는 기준에 가장 잘 맞는다. 남은 일은 계약 키트(01-05)다. |
|
||||
| 7. 바뀔 조건 | 한 유스케이스 안에서 여러 저장소(JPA + Mongo)를 묶는 요구가 생기면 `TransactionPort` 의미(어느 리소스의 트랜잭션인가)를 다시 정해야 한다. |
|
||||
|
||||
## 6. 리팩토링 후보
|
||||
|
||||
| # | 무엇을 | 왜 | 보존해야 할 것 |
|
||||
| --- | --- | --- | --- |
|
||||
| R1 | `TenantId` 3벌 → application-core 하나 (01-03) | 보안 경계 값의 문법 통일 | 이미 저장된 알림 tenant 값 읽기, RLS가 원하는 소문자 제약(binder의 추가 검사로) |
|
||||
| R2 | 이벤트 식별자 문법 5곳 → `IntegrationIdentity` 하나 (01-07) | 상한 분기 제거 | event id 96자, outbox correlation 열 128자, 기존 테스트의 거부 메시지 |
|
||||
| R3 | `PortfolioEventOutbox` 규칙을 application-core 헬퍼로 승격 (01-09) | 기능마다 tenant·순서·correlation 재정의 방지 | 저장과 append가 같은 트랜잭션, 문법 밖 correlation이 쓰기를 실패시키지 않음, durable operation의 "같은 operation → 같은 event id" |
|
||||
| R4 | shared-contract `operation` → sample로 (01-08) | 공개 계약 하나 | sample `POST /worklogs:export` wire 모양과 계약 테스트 |
|
||||
| R5 | `TransactionPort` 구현 10개 → `SpringTransaction` + `DirectTransactionPort` (01-05) | fake 의미 통일 | 각 테스트가 단언하던 경계 기록(`committed()` 순서), notification 테스트의 nesting 거부 |
|
||||
| R6 | `SafeFileFingerprint` → `HmacSha256.sign` (01-11) | 복사 제거 | 출력: hex 앞 16자, 키 최소 16바이트 거부 |
|
||||
| R7 | `PublishPendingOutboxEventsUseCase`의 장식용 `@RequiresPermission` 제거 + 시스템 전용 표시 (01-06) | 거짓 선언 제거 | ArchUnit D4가 다른 쓰기 유스케이스에는 계속 선언을 강제 |
|
||||
|
||||
## 7. 기능 개발 패턴과 판단 지점 (매뉴얼 재료)
|
||||
|
||||
### 7.1 템플릿이 주는 틀 — 단계별
|
||||
|
||||
```text
|
||||
domain-core ─▶ application-core ─▶ outbound adapter ─▶ inbound adapter ─▶ bootstrap 조립
|
||||
(모델·불변식) (유스케이스·포트) (저장·외부) (전송·DTO·오류) (bean·조건)
|
||||
```
|
||||
|
||||
| 단계 | 템플릿이 주는 것 | 빠진 것 |
|
||||
| --- | --- | --- |
|
||||
| domain | `@AggregateRoot`·`@ValueObject`·`@DomainEvent` 마커(ArchUnit이 setter·no-arg 생성자·전송 타입 import를 검사), `ResourceId<SELF>`(Long id 금지 규칙 D17), `IdFactory<T>` 포트. 예시: sample `WorkLog`·`WorkLogId`·`WorkLogInvariantException(Reason)` | aggregate가 도메인 이벤트를 모으는 수단, 도메인 예외의 공통 모양(각자 `RuntimeException` + `Reason` enum), domain-core가 shared-contract를 못 봐서 도메인 예외는 오류 코드를 가질 수 없다는 안내 |
|
||||
| application | `CommandUseCase`/`QueryUseCase`, `Command`/`Query` 마커, `@UseCaseCapability`(필수, ArchUnit이 트랜잭션 호출과 대조), `@RequiresPermission`(쓰기 필수), `TransactionPort`, `IdempotencyExecutor`, `OutboxAppendPort` + `IntegrationEventEncoderPort`, `ObjectAccessPolicy`, `CorrelationIdPort`, `TenantId`. `*QueryPort`는 projection만 반환(ArchUnit). testFixtures: `DirectTransactionPort`, `InMemoryOutboxStore`, `FakeIntegrationEventEncoder`, `InMemoryIdempotencyStore`, `InMemoryDurableOperationStore` | 이벤트 draft 조립 헬퍼(01-09), application 예외가 `ApiErrorCarrier`를 구현하는 예시(sample은 web 핸들러로 매핑), 저장 포트 이름·위치 규칙(01-12), 객체 인가 예시(01-13) |
|
||||
| outbound | persistence-jpa의 `SpringTransaction`, outbox store, `CallerTransaction.require`, Flyway. 계약 키트 3개(operation·lease·outbox fencing). 예시: sample `WorkLogRepositoryAdapter` + `WorkLogEntity` + mapper + `WorkLogRepositoryAdapterContractTest`(integrationTest) + `InMemoryWorkLogRepositoryContractTest` | 기능 adapter를 둘 leaf의 기준(01-01), Flyway 번호대 규칙(메모에만 있음: 프로덕션·sample 번호 충돌), 감사 필드 처리 위치 안내 |
|
||||
| inbound | web `GlobalExceptionHandler`(`ApiErrorCarrier`·`ApiErrorCode`·`Envelope`), `ErrorResponseFactory`, `Patch<T>`(PATCH 3상태), `MethodSecurityConfig`, `TenantContext`. 예시: sample `WorkLogController`·`WorkLogWebMapper`·DTO·`DomainExceptionHandler`·`PortfolioErrorCode` | 비-web 전송에서 같은 유스케이스를 여는 예시, 기능 오류 코드를 어디에 두는지(sample은 web 패키지) |
|
||||
| bootstrap | `DurableOperationConfig` 모양: `@AutoConfiguration` + `@ConditionalOnBean(포트들)` + 유스케이스 `@Bean`(프록시를 위해 bean 필수) + 이벤트 계약 `@Bean` 등록 | 계약 bean 등록 누락을 기동 때 잡는 장치(01-04), role→permission 매핑 추가 위치 안내 |
|
||||
|
||||
### 7.2 개발자가 내려야 하는 판단 (순서대로)
|
||||
|
||||
1. **배치**: 이 기능은 공유 계층 leaf의 패키지인가, 별도 leaf인가? (선택 조립·삭제가 필요하면 별도 leaf, 아니면 계층 leaf.) 업무 패키지 이름이 플랫폼 패키지(`operation`·`lock`·`cache`)와 겹치지 않는가?
|
||||
2. **id**: 서버가 만드는가(`IdFactory` 상속 포트 + identifier adapter), 클라이언트가 주는가? id 문법은 어디서 검사하는가(값 객체 생성자)?
|
||||
3. **불변식 위치**: aggregate 메서드인가, 유스케이스인가? 둘 이상의 aggregate에 걸치면 유스케이스 + 트랜잭션.
|
||||
4. **저장 포트 소유자**: domain(`*Repository`, aggregate 단위 저장)인가 application(`*StorePort`, 기술적 저장·조회)인가? 읽기 모양이 쓰기와 다르면 `*QueryPort` + projection.
|
||||
5. **트랜잭션 모양**: `inWrite`(기본) / `inRootWrite`(커밋 후 결과 노출, 중첩 금지) / `inRead` / `inNew`(감사·보상만, 루프 금지). 외부 호출은 트랜잭션 밖.
|
||||
6. **멱등성**: `NOT_IDEMPOTENT`·`IDEMPOTENT`·`KEYED` 중 무엇인가? KEYED면 scope digest와 fingerprint를 무엇으로 만드는가?
|
||||
7. **인가**: 권한 이름(`resource:action`)과 role 매핑. 객체 인가가 필요한가(소유자·tenant)? 필요하면 `ObjectAccessPolicy` 구현을 어디에 두는가? 실패 시 403인가 404인가(존재 숨김)?
|
||||
8. **tenant**: 이 데이터는 tenant 범위인가? `TenantId`를 command에 싣는가? 이벤트 tenant 범위는 무엇인가?
|
||||
9. **이벤트**: 도메인 이벤트가 필요한가, 통합 이벤트만 필요한가? payload에 무엇을 넣는가(id만 vs 상태)? 계약 id·버전·schema 파일·해시·descriptor(크기 상한·순서 필요·민감도)를 정하고 계약을 bean으로 등록했는가?
|
||||
10. **오류 모델**: 실패마다 "클라이언트 탓(4xx)인가 서버 탓(5xx)인가"를 정한다. 클라이언트 탓이면 `ApiErrorCode` 하나와 carrier 예외, 서버 탓이면 `IllegalStateException`(01-04). 도메인 예외의 매핑을 application에서 할지 전송 핸들러에서 할지 정한다(여러 전송이면 application 쪽 carrier가 낫다).
|
||||
11. **성공의 의미**: 200/201/202 중 무엇이고, 응답 시점에 무엇이 보장되는가(커밋됨 vs 발행됨)?
|
||||
12. **테스트**: 포트마다 fake + 추상 계약 테스트를 testFixtures에, adapter는 같은 계약을 실제 저장소로 상속. 유스케이스는 `DirectTransactionPort`와 fake로.
|
||||
13. **조립**: 유스케이스는 bean으로(권한 프록시), `@ConditionalOnBean`으로 필요한 포트가 있을 때만. Flyway 번호대, env 키(`docs/registries/env-keys.yaml`), 공개 경로 스냅숏이 바뀌면 해당 검사를 돌린다.
|
||||
|
||||
### 7.3 스캐폴드 명령이 만든다면 (후보 목록, 만들지 않음)
|
||||
|
||||
입력: 기능 이름 `X`, 배치(계층 leaf / 별도 leaf), 쓰기·읽기 여부, 이벤트 여부.
|
||||
|
||||
| 계층 | 생성 파일 |
|
||||
| --- | --- |
|
||||
| domain | `X`(`@AggregateRoot`, private 생성자 + `create`/`restore`), `XId`(`record implements ResourceId<XId>`, `@ValueObject`, 문법 검사), `XIdFactory extends IdFactory<XId>`, `XRepository`, `XInvariantException`(+ `Reason` enum), 선택 `XCreated`(`@DomainEvent` record) |
|
||||
| application | `CreateXCommand implements Command`, `GetXQuery implements Query`, `CreateXUseCase`(non-final, `@UseCaseCapability(WRITE, NOT_IDEMPOTENT, WRITE_REPOSITORY)`, `@RequiresPermission("x:write")`, `tx.inWrite`), `GetXUseCase`(`READ_ONLY`, `READ_REPOSITORY`, `tx.inRead`), `XNotFoundException implements ApiErrorCarrier`, `XErrorCode implements ApiErrorCode`. 이벤트면 `XCreatedPayload implements IntegrationPayload`, 계약 contribution, `contracts/messaging/x.created/v1.schema.json`과 해시 고정 테스트 |
|
||||
| testFixtures | `InMemoryXRepository`, `XRepositoryContract`(abstract), `InMemoryXRepositoryContractTest` |
|
||||
| test | `CreateXUseCaseTest`·`GetXUseCaseTest`(`DirectTransactionPort` + fake, GWT 주석), `XTest`(불변식), `XIdTest` |
|
||||
| outbound | `XEntity`, `XPersistenceMapper`, `XJpaRepository`, `XRepositoryAdapter`, `UuidXIdFactory`(identifier), Flyway `V<번호대>__x.sql`, `JpaXRepositoryContractTest extends XRepositoryContract`(Testcontainers) |
|
||||
| inbound | `XController`, `CreateXRequest`·`XResponse`, `XWebMapper`, web slice 테스트(400·403·404·성공) |
|
||||
| bootstrap | `XUseCaseConfig`(`@AutoConfiguration`, `@ConditionalOnBean`, 유스케이스·계약 `@Bean`), `AutoConfiguration.imports` 한 줄, role→permission 정책에 `x:write`·`x:read` |
|
||||
| 검증 | 생성 직후 `:app-bootstrap:architectureTest`, 소유 leaf `test`, 공개 경로가 바뀌면 `verifyPublicPathSnapshot` |
|
||||
|
||||
스캐폴드의 템플릿 원본은 onboarding fixture를 01-02대로 고친 뒤 그것으로 삼는 것이 가장 싸다. fixture가 이미 `DomainFeatureOnboardingContractTest`로 production 규칙과 대조되고 있기 때문이다.
|
||||
|
||||
## 8. 28개 관점 판정표
|
||||
|
||||
기호: O 충족, P 부분, X 미충족, ? 미검증, - 적용 제외, > 다른 영역.
|
||||
|
||||
| # | 관점 | 판정 | 한 줄 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | O | 코어 값 객체가 생성자에서 검사하고, 지난 리뷰의 죽은 코드가 정리됐다(main 5,080줄) |
|
||||
| 2 | 구조적 성숙도 | P | leaf 방향은 강제되나 기능 배치 모양이 셋(01-01), application-core 이름공간 혼합(01-10) |
|
||||
| 3 | 변경 용이성 | P | 이벤트 조립 규칙·식별자 문법이 여러 곳에 복사(01-07, 01-09) |
|
||||
| 4 | 인지 부하 | P | 첫 기능 작성자가 네 예시에서 공통점을 뽑아야 함, 이름 규칙 문서 없음(01-12) |
|
||||
| 5 | 위험 가시성 | P | 설계 이유는 README에 잘 적혔으나 일부 제약이 코드에 없음(01-06 relay, 01-13 소유자 검사) |
|
||||
| 6 | 실패 성숙도 | P | 결과 불명을 타입으로 표현(outbox·idempotency outcome)하나, 서버 조립 오류가 400으로 숨는다(01-04) |
|
||||
| 7 | 운영 성숙도 | > | bootstrap·운영 영역 |
|
||||
| 8 | 디버깅 가능성 | P | correlation 전파는 있음, IAE 400 경로에 로그 없음(01-04) |
|
||||
| 9 | 유지보수 성숙도 | P | 문서 drift 남음(A-2b, A-2d, A-5a, A-6a, 01-14) |
|
||||
| 10 | 테스트 성숙도 | P | 코어 테스트 빠르고 변이 5개 중 3개를 잡음. 계약 키트 절반 공백(01-05), fixture가 규칙 밖(01-02) |
|
||||
| 11 | 데이터 성숙도 | P | 저장+outbox 한 트랜잭션은 강제, 이벤트 tenant 범위 규칙이 기능마다 다름(01-09) |
|
||||
| 12 | 동시성 성숙도 | P | inRootWrite 중첩 거부·outbox fencing 키트 있음, lock 계약 키트 없음 |
|
||||
| 13 | 확장성 | - | 코어 영역에 규모 목표 없음 |
|
||||
| 14 | 성능 성숙도 | O | 코어는 CPU 작업뿐(이벤트당 SHA-256 3~4회, 128KB 상한). 테스트 2.3초 |
|
||||
| 15 | 보안 성숙도 | P | 쓰기 권한 선언 강제·fail-closed, 단 검사기가 web에 묶임(01-06), TenantId 3벌(01-03) |
|
||||
| 16 | 의존성 성숙도 | O | domain-core·shared-contract stdlib 전용, 방향 게이트 통과(ci). 복사 강제 leaf는 01-11 |
|
||||
| 17 | API / Contract 성숙도 | P | Envelope·ApiErrorCode 하나로 통일됨, LRO 계약 2벌(01-08) |
|
||||
| 18 | 배포 성숙도 | > | CI·배포 영역 |
|
||||
| 19 | 설정 성숙도 | - | 코어는 설정을 읽지 않는다(ArchUnit D11·K6) |
|
||||
| 20 | 개발자 경험 | X | 새 기능을 끝까지 따라갈 문서·예시·스캐폴드가 없음(01-01, 01-02, 7절) |
|
||||
| 21 | Guardrail 성숙도 | P | ArchUnit 규칙이 촘촘함, 단 test fixture는 production 규칙 밖(01-02), web 없는 조립 검사 없음(01-06) |
|
||||
| 22 | 추상화 성숙도 | P | 포트·값 타입은 적절, draft 조립 헬퍼가 없어 10필드 생성자를 직접 다룸(01-09) |
|
||||
| 23 | 일관성 | X | TenantId 3벌, LRO 2벌, 식별자 문법 5곳, 이름 규칙 여러 개(01-03, 01-07, 01-08, 01-12) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | P | `*ApplicationUseCase`/`*UseCase`, `*Repository`/`*StorePort`/`*WritePort`, "Contract"라는 이름의 값 테스트(01-12, 01-14) |
|
||||
| 25 | 조직 확장성 | P | 파생 서비스 기능이 템플릿과 같은 leaf·트리에 섞여 병합 충돌 면이 넓다(01-01, 01-10) |
|
||||
| 26 | Ownership 성숙도 | P | leaf별 CLAUDE.md·README 있음, 코어 README가 다른 leaf 타입을 설명(A-6a) |
|
||||
| 27 | 삭제 가능성 | P | sample은 leaf 하나로 지울 수 있음, shared-contract `operation`이 sample 전용인데 코어에 있음(01-08) |
|
||||
| 28 | 회복 가능성 | > | persistence·운영 영역 |
|
||||
|
||||
## 발견 요약
|
||||
|
||||
| 심각도 | 건수 | ID |
|
||||
| --- | --- | --- |
|
||||
| Critical | 0 | |
|
||||
| High | 0 | |
|
||||
| Medium | 8 | 01-01, 01-02, 01-03, 01-04, 01-05, 01-06, 01-08, 01-09 |
|
||||
| Low | 6 | 01-07, 01-10, 01-11, 01-12, 01-13, 01-14 |
|
||||
|
||||
| 우선순위 | 건수 | ID |
|
||||
| --- | --- | --- |
|
||||
| P2 | 5 | 01-01, 01-02, 01-03, 01-04, 01-05 |
|
||||
| P3 | 9 | 01-06 ~ 01-14 |
|
||||
@@ -0,0 +1,420 @@
|
||||
# 02 inbound HTTP (web · web-notification · web-fileserver · web-advanced · 멱등성 HTTP 계약)
|
||||
|
||||
## 1. 범위
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 | `clean-architecture-backend-template`, `main` 커밋 `01a8a2a70` |
|
||||
| 맡은 leaf | `:adapter:inbound:web`, `:adapter:inbound:web-notification`, `:adapter:inbound:web-fileserver`, `:adapter:inbound:web-advanced`, 그리고 `:composition:idempotency`가 만든 executor의 HTTP 쪽 계약 |
|
||||
| 목적·지원 구성 | 서비스가 파생해 쓰는 템플릿. 기본 조립은 servlet(Spring MVC) + JWT 보안 체인. 짝 프론트 템플릿(`clean-architecture-frontend-template`)이 이 서버를 부른다고 가정한다 |
|
||||
| 읽은 코드 | web main 68파일 전부, testFixtures 중 계약·장애 fixture, web-notification main 16파일, web-fileserver의 보안·오류·tus·admin 컨트롤러, web-advanced의 예외 10종·자동 구성 3개·`VirtualThreadMvcConfiguration`, `composition:idempotency` main 2파일과 README, application-core `idempotency/` 예외 4종과 `IdempotencyExecutor`의 claim·complete 분기, sample `PosterImagePublicationController`·`PublishPosterImageUseCase`(멱등 HTTP 경로 추적용) |
|
||||
| 읽은 문서 | `AGENTS.md`·`CLAUDE.md`, web `README.md`·`CLAUDE.md`, web-advanced `README.md`, `composition/idempotency/README.md`, `docs/web/*.md`, `docs/registries/error-codes.yaml`·`env-keys.yaml`, 지난 리뷰 `2026-09-18-techlead-review/02-inbound-web.md`, `2026-09-25-review-followup-status.md`(I Web, S5, 소유자 결정, P6-new-2). 짝 프론트의 `docs/architecture/backend-api-and-server-state-contract.md` §4·§6과 `src/adapters/http/schema-registry.ts` |
|
||||
| 게이트 결과(오케스트레이터 실행, 다시 돌리지 않음) | `ci` rc=0. web 테스트 259건·web-fileserver 142건·web-advanced 184건·web-notification 16건 모두 통과(`build/test-results/test` XML, 11:39Z). `mainCheck` rc=1 — 원인은 objectstorage MinIO 이미지 pull 404(이 영역 아님). 같은 실행에서 `:adapter:inbound:web:systemTest`, `webJettyCompatTest`는 통과 |
|
||||
| 직접 실행(격리 worktree, `flock` 사용) | ① 실제 Tomcat에서 429 본문 문자셋 실험 ② `@WebMvcTest`로 실제 Envelope JSON과 in-flight 409 관찰 ③ MockMvc로 `HandlerMethodValidationException`·`AsyncRequestTimeoutException`·`String` 반환·`AdmissionRefusedException`의 응답 관찰 ④ 변이 실험 3건. 실행 직전 load average 5.6~21. 결과는 각 발견에 적었다. 실험 코드는 scratchpad `review02-experiments/`에 보관, worktree는 삭제 |
|
||||
| 확인 못 한 것 | 짝 프론트를 실제 백엔드에 붙여 실행하지 않았다(프론트 쪽은 코드 읽기만). actuator 응답이 `EnvelopeBodyAdvice`로 감싸지는지 실행하지 않았다. Redis·PostgreSQL 멱등성 저장소에서 같은 키 동시 요청을 실제로 보내 보지 않았다(application·persistence 영역). 성능은 테스트 시간만 쟀고 부하는 걸지 않았다 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
followup-status에서 이 영역에 `남음`·`보류`로 남았던 항목과, 이번에 관련 코드를 다시 본 항목만 적는다. 나머지 I-*·S5-* `완료`/`해당 없음` 항목은 표의 근거 경로를 열어 같은 상태임을 확인했다.
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| I-2c / TEST-F-2d (콜백 크기 테스트가 컨버터 경로를 건너뜀) | 바뀜 | 컨트롤러가 `HttpServletRequest`를 직접 읽게 바뀌어 컨버터 버퍼링 경로는 사라졌다(`web-notification/.../callback/NotificationCallbackMvcController.java` `callback`). 테스트는 여전히 컨트롤러를 직접 호출한다(`NotificationCallbackMvcControllerTest.java:109-140`). 남은 위험은 "필터 체인의 무엇인가가 form 본문을 먼저 파싱해 서명할 원본 바이트를 잃는 경우"이며 MockMvc 경로 테스트가 없다 |
|
||||
| I-3c (필수 파라미터·헤더 누락, `HandlerMethodValidationException` 형식 테스트 0) | 바뀜(일부 해결) | 누락 헤더·파라미터 테스트 추가됨 `TransportErrorHandlingTest.java:105,114`. `HandlerMethodValidationException`은 여전히 테스트가 없고, 실행해 보니 `BAD_PARAMETER`·details 없음으로 나간다 → 02-08 |
|
||||
| I-7 (`wire-type-manifest.yaml`이 런타임에 없는 wire 계약 공개) | 남음 | `web-advanced/src/main/resources/META-INF/web/wire-type-manifest.yaml`, `web-advanced/.../advanced/contract/WebWireTypeManifest.java`. 적용하는 Jackson 설정은 여전히 없다 |
|
||||
| S5-#12 (profile-name record 5개가 같은 정규식 복사) | 남음 | `web-advanced/.../operation/{Admission,Authorization,Response}ProfileName.java:17`, `CachePolicyName.java:17`, `budget/WebBudgetProfileName.java:17` |
|
||||
| S5-#14c (web-fileserver·web-notification에 README/CLAUDE.md 없음) | 남음 | 두 leaf 루트에 `*.md` 0개 |
|
||||
| TEST-FAKE-UploadApplicationService (tus fake와 실제 서비스가 같은 계약이 아님) | 남음 | `web-fileserver/src/test/.../testkit/InMemoryUploadApplicationService.java`. 공통 추상 계약 테스트 없음 |
|
||||
| P6-new-2 (complete가 UNAVAILABLE이면 action 뒤에도 `IdempotencyUnavailableException`) — 결정 24 "현재 동작 유지 + 문서화" | 남음(문서화 안 됨) | `IdempotencyExecutor.java:233`이 action 실행 뒤 complete 단계에서 던진다. 그런데 예외 Javadoc은 "raised before an action"(`IdempotencyUnavailableException.java:7`), web README는 "action 전에 거부"(`adapter/inbound/web/README.md:214`). HTTP 계약 표가 이 경우를 거짓으로 설명한다 |
|
||||
| L-11a (테스트·sample yml이 `ca-skeleton.rate-limit.*`) | 해결 | `sample-portfolio/src/main/resources/application.yml:189`, `app-bootstrap/src/test/resources/application-test.yml:113` 모두 `app.rate-limit` |
|
||||
| I-3a (Spring MVC 예외가 problem+json으로 샘) | 해결 유지 | `GlobalExceptionHandler.java:332-351`. 다만 상태→코드 표가 503을 500으로 바꾼다 → 02-08 |
|
||||
| I-4a·I-4b (요청 ID가 보안 체인 뒤에서 생성, trace 두 벌) | 해결 유지 | `WebMvcRequestIdFilter.java:103-122`(HIGHEST+10, 보안 체인 앞) |
|
||||
| I-5a (XFF 맨 왼쪽으로 rate-limit 키) | 해결 유지 | `RateLimitKeyResolver.java`는 `getRemoteAddr()`만, `RateLimitWebConfig`가 `forward-headers-strategy=framework`면 기동 거부 |
|
||||
|
||||
지난 리뷰에서 남은 High/P1은 이 영역에 없다. 새로 찾은 High 3건은 아래에 있다.
|
||||
|
||||
## 3. 새 발견
|
||||
|
||||
| ID | 제목 | 심각도·우선순위 |
|
||||
| --- | --- | --- |
|
||||
| 02-01 | "처리 중" 409(`IDEMPOTENT_IN_FLIGHT`)의 클라이언트 행동이 코드·문서·짝 계약에서 서로 다르다 | High · P1 |
|
||||
| 02-02 | 실제 Envelope JSON이 `data:null`·`error:null`·`meta.page`를 항상 싣는데 짝 프론트 계약은 이를 거절한다 | High · P1 |
|
||||
| 02-03 | JWT audience 검증이 기본으로 꺼져 있고, 모든 client의 role을 합친다 | High · P1 |
|
||||
| 02-04 | rate-limit 거부 본문이 실제 Tomcat에서 ISO-8859-1로 나가 한국어 문구가 `???`가 된다 | Medium · P2 |
|
||||
| 02-05 | CORS에 노출 헤더가 없어 브라우저가 `Retry-After`·`X-Request-Id`·`Location`·tus 헤더를 못 읽는다 | Medium · P2 |
|
||||
| 02-06 | `String`을 반환하는 컨트롤러는 `Accept: application/json`에서 500(ClassCastException)이 된다 | Medium · P2 |
|
||||
| 02-07 | web-advanced 예외 10종이 문서에 적힌 상태(409·503 등) 대신 500 `INTERNAL_ERROR`로 나간다 | Medium · P2 |
|
||||
| 02-08 | Spring MVC 예외의 상태→코드 변환이 의미를 잃는다(503→500, 메서드 검증→details 없는 `BAD_PARAMETER`) | Low · P2 |
|
||||
| 02-09 | JSON 본문 상한의 두 갈래가 테스트로 묶여 있지 않고(변이 2건 생존), JSON 아닌 본문은 상한이 없다 | Low · P2 |
|
||||
| 02-10 | `GlobalExceptionHandler`가 두 경로로 등록되어 `app.web.mvc.enabled=false`가 말한 대로 동작하지 않는다 | Low · P3 |
|
||||
| 02-11 | `X-Correlation-Id` 허용 문자·길이가 요청 ID 규칙·짝 계약과 다르다 | Low · P3 |
|
||||
| 02-12 | `Idempotency-Key` 헤더 검증이 공용 부품 없이 컨트롤러마다 새로 쓰인다 | Low · P3 |
|
||||
|
||||
집계: High 3, Medium 4, Low 5 / P1 3, P2 6, P3 3.
|
||||
|
||||
### 02-01 "처리 중" 409의 클라이언트 행동이 코드·문서·짝 계약에서 서로 다르다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(계약 불일치) |
|
||||
| 관련 관점 | 17, 6, 5, 23, 12, 28 |
|
||||
| 근거 | **코드가 실제로 내는 응답**: `@WebMvcTest` 실행 결과 `status=409`, `Retry-After` 없음, 본문 `{"success":false,"data":null,"error":{"code":"IDEMPOTENT_IN_FLIGHT","category":"CONFLICT","message":"현재 상태에서는 요청을 처리할 수 없습니다.","retryable":false,"details":null},"meta":{…}}`. 정의 `shared-contract/.../OperationalError.java:47`(`CONFLICT, 409, false`), 발생 `IdempotencyExecutor.java:104-105`(claim 단계), `:136-137`(재조정 단계). executor는 기다리지 않는다. `Retry-After` 표에 이 코드가 없다(`RetryAfterAdvisor.java:14-23`), retryable=false라 표를 보지도 않는다(`:36-38`). 메시지는 일반 충돌과 같은 CONFLICT 문구다. **백엔드 문서**: web README 표 `adapter/inbound/web/README.md:216`은 409·retryable=false·"executor는 기다리지 않는다"까지만 적고 클라이언트가 할 일은 없다. `docs/registries/error-codes.yaml:402-406`은 근거 주석에 "200ms 초과 시 409 … client는 polling"이라 적었지만 executor에는 대기도, 키로 조회하는 HTTP 엔드포인트도 없다. `docs/web/runbook.md:41-42`는 "the caller should retry after `Retry-After`"라고 적었지만 이 응답에는 그 헤더가 없다. "같은 키로 다시 보내라"는 문장은 백엔드 어디에도 없다. `docs/web/repository-adaptation.md` §6(`:75-104`)은 모듈 소유권만 다룬다. **짝 프론트 계약**: `clean-architecture-frontend-template/docs/architecture/backend-api-and-server-state-contract.md:211`은 409를 "fingerprint, revision 또는 semantic conflict"로, `:298`은 키 재사용을 `409 IDEMPOTENCY_KEY_REUSED`로, `:299-300`은 처리 중을 "bounded `IN_PROGRESS` 결과"로만 적는다. 백엔드의 키 재사용은 `422 IDEMPOTENT_REQUEST_MISMATCH`다(`OperationalError.java:48`) |
|
||||
| 발생 조건 | 쓰기 응답을 잃은 클라이언트(게이트웨이 504, 클라이언트 타임아웃)가 첫 요청이 아직 처리 중일 때 같은 키로 다시 보낸다. 느린 쓰기에서 흔한 순서다 |
|
||||
| 영향 | `retryable:false`는 "이 요청은 실패했고 다시 보내지 말라"로 읽힌다. 이 필드만 보는 클라이언트(파생 서비스의 다른 앱, 프론트의 다른 기능 패키지)는 사용자에게 다시 제출하게 하고, 그 제출은 새 키라 서버가 막지 못한다. 첫 요청이 끝나면 같은 작업이 두 번 적용된다. 프론트는 코드 이름으로 이 경우를 따로 처리하게 바뀌었지만(`reference-feature-contract-contribution.ts:33-51`), 그 근거가 백엔드 문서에 없으니 다른 소비자는 같은 판단을 할 수 없다 |
|
||||
| 심각도·우선순위 | High · P1. 35.2의 "결과 불명 작업의 무방비 재실행"에 해당하고, 기본 응답과 기본 문서만으로 생기는 경로다. 실제 중복을 관측하지는 않았다 |
|
||||
| 통제·증거 | 통제 M1(README 표에 status·code는 있음, 클라이언트 행동은 없음) · 증거 E2(백엔드 `@WebMvcTest` 출력, `IdempotencyExceptionMappingTest.inFlightMapsToNonRetryable409ConflictWithTheConflictMessage`) + E1(문서·짝 계약 읽기) |
|
||||
| 확실성과 남은 가정 | status·code·retryable·헤더 없음은 실행으로 확인했다. 파생 서비스(tech-log)가 같은 값을 쓰는지는 이번에 보지 않았다 |
|
||||
| 결정의 근거 | `[사실]` retryable=false는 2026-05의 "client polls" 결정에서 왔다(`error-codes.yaml:402` 주석, `OperationalErrorTest.java:232` 주석). `[사실]` 그 뒤 poll 대상이 될 키 조회 엔드포인트는 만들어지지 않았다. `[추론]` "다시 보내지 말고 조회하라"는 전제가 없어진 채 플래그만 남았다 |
|
||||
| 이해 비용 | 새 KEYED 엔드포인트를 만드는 사람은 README 표, error-codes.yaml, runbook, `IdempotencyExecutor` 분기, 짝 프론트 §6을 모두 읽어야 409의 뜻을 안다. 다섯 곳의 말이 다르다 |
|
||||
| 최소 개선 방향 | 백엔드 HTTP 계약 문서 한 곳(아래 대안 A)에 멱등성 응답 4종을 status·code·retryable·`Retry-After`·클라이언트 행동으로 고정한다. in-flight는 "결과 불명. 같은 `Idempotency-Key`로 `Retry-After` 뒤 재전송. 새 키 금지"로 적는다. 그에 맞게 `IDEMPOTENT_IN_FLIGHT`에 `Retry-After`(예: processing-lease 이하의 고정 초)를 붙이고, runbook·error-codes.yaml 주석을 같은 문장으로 고친다 |
|
||||
| 대안 비교 | A) **retryable=true + `Retry-After` + 문서 고정**(권장): 일반 클라이언트도 "같은 요청을 나중에 다시"로 읽는다. 같은 키 재전송은 서버가 replay·in-flight·mismatch로 안전하게 판정하므로 retryable=true가 거짓이 아니다. 비용은 registry·enum·테스트 3곳 수정. B) **retryable=false 유지 + 문서에만 "같은 키 재전송"**: 코드 변경이 없지만 필드와 문서가 반대 말을 한다. 필드만 읽는 소비자는 계속 틀린다. C) **executor가 짧게 기다렸다가 결과를 replay**: 클라이언트 단순화. 대가로 요청 스레드 점유와 대기 상한 설계가 필요하고, 결국 시간 초과면 409가 다시 나간다. D) **키 조회 엔드포인트 추가 후 "poll"을 실제로 만들기**: 원래 의도대로지만 엔드포인트·인가·보존 기간이 새로 생긴다. 지금 요구에는 과하다 |
|
||||
| 단순화의 보존 조건 | 같은 키·같은 fingerprint는 replay, 다른 fingerprint는 422, 진단 정보(scope digest)는 클라이언트에 나가지 않는다 |
|
||||
| 비용·부작용 | A는 retryable 의미 변경이므로 짝 프론트의 분류기·테스트(`reference-http-problem-mapping.test.ts:152`)와 같이 바꿔야 한다 |
|
||||
| 재검토 조건 | executor가 대기 방식으로 바뀌거나 키 조회 엔드포인트가 생기면 다시 비교한다 |
|
||||
| 완료 기준 | 백엔드 계약 문서 한 곳과 README·runbook·error-codes.yaml이 in-flight에 대해 같은 status·code·retryable·헤더·행동을 말한다. 짝 프론트 §6이 그 문서를 가리킨다 |
|
||||
| 검증 방법 | `IdempotencyExceptionMappingTest`에 `Retry-After`·retryable 단언 추가. 문서 문장은 리뷰로 확인 |
|
||||
|
||||
### 02-02 실제 Envelope JSON이 `data:null`·`error:null`·`meta.page`를 싣는데 짝 프론트 계약은 이를 거절한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(짝 계약 불일치) + 테스트 공백 |
|
||||
| 관련 관점 | 17, 10, 23, 5 |
|
||||
| 근거 | `@WebMvcTest`(Boot의 ObjectMapper) 실행 결과: 성공 `{"success":true,"data":{"k":"v"},"error":null,"meta":{"requestId":…,"traceId":…,"correlationId":…,"page":null}}`, 실패 `{"success":false,"data":null,"error":{…,"details":null},"meta":{…,"page":null}}`. `shared-contract/.../response/Envelope.java`는 record 4필드 그대로이고 저장소 전체에 `JsonInclude`·`non_null` 설정이 없다(grep 0). 짝 프론트는 `successEnvelopeSchema`·`failureEnvelopeSchema`를 `.strict()`로 둬(`frontend/src/adapters/http/schema-registry.ts:12-34`) 성공에 `error` 키, 실패에 `data` 키가 있으면 거절한다. 프론트 계약 §4.1도 "Envelope 최상위 unknown field는 현재 거절된다"(`backend-api-and-server-state-contract.md:195`). 백엔드 테스트 `EnvelopeBodyAdviceTest.rawBodyIsWrappedInEnvelope`는 `jsonPath("$.error").doesNotExist()`(`:57`)로 단언하는데, Spring의 `doesNotExist`는 값이 `null`이어도 통과하므로 이 차이를 잡지 못한다 |
|
||||
| 발생 조건 | 짝 프론트의 기본 HTTP 클라이언트(`client.ts:917`의 `validateEnvelope`)가 이 백엔드의 아무 JSON 응답이나 받을 때 |
|
||||
| 영향 | 성공 응답이 `ENVELOPE_MISMATCH`, 실패 응답이 `HTTP_FAILURE`로 바뀐다. 실패 쪽에서는 `error.code`가 분류기에 닿지 않아 02-01의 `IDEMPOTENT_IN_FLIGHT` 구분도 동작하지 않는다. 두 템플릿을 그대로 붙인 첫 화면에서 드러날 결함이라 탐지는 쉽지만, 원인이 "null 필드"라는 것은 양쪽 테스트가 모두 숨긴다 |
|
||||
| 심각도·우선순위 | High · P1. 짝 템플릿을 같이 쓰는 기본 조합에서 모든 응답이 계약 위반이다 |
|
||||
| 통제·증거 | 백엔드 쪽 통제 M0(wire 모양을 고정하는 문서·테스트 없음) · 증거 E2(백엔드 실행) + E1(프론트 코드 읽기, 프론트 실행 안 함) |
|
||||
| 확실성과 남은 가정 | 백엔드 JSON은 실행으로 확인했다. 프론트가 `validateEnvelope` 전에 null을 지우는 단계가 있는지는 `client.ts:899-917`까지 읽어 없음을 확인했지만 실제 결합 실행은 안 했다 |
|
||||
| 결정의 근거 | `[사실]` Envelope 하나로 통일은 소유자 결정 2다. 이 발견은 결정을 뒤집지 않는다. `[사실]` 백엔드에는 소비자가 읽을 wire 계약 문서가 없고(README의 예외 표뿐), 프론트가 자기 문서에 백엔드 모양을 추측해 적었다 |
|
||||
| 이해 비용 | 파생 서비스 개발자는 Envelope record를 보고는 null 필드가 나가는지 알 수 없다. ObjectMapper 기본값을 알아야 한다 |
|
||||
| 최소 개선 방향 | 백엔드에 HTTP wire 계약 문서를 하나 둔다(`docs/web/http-contract.md` 같은 이름). Envelope의 필드 존재 규칙(성공은 `success·data·meta`, 실패는 `success·error·meta`, null 필드 생략)과 `meta`의 키를 적고, `Envelope`·`ApiError`·`ResponseMeta`에 `@JsonInclude(NON_NULL)`을 붙인다. 테스트는 `doesNotExist` 대신 원문 JSON의 키 집합을 단언한다 |
|
||||
| 대안 비교 | A) **백엔드가 null 필드를 생략**(권장): shared-contract 타입 3개에 한 줄씩. GraphQL·STOMP 등 다른 전송도 같은 타입을 쓰면 함께 바뀌므로 그쪽 계약도 확인해야 한다. B) **프론트가 `.strict()`를 풀거나 null 허용**: 백엔드 변경 없음. 대신 "unknown field 거절"이라는 프론트의 방어 규칙을 약하게 만든다. C) **둘 다 문서만 맞춤**: 실행 결과가 바뀌지 않는다. 기각 |
|
||||
| 단순화의 보존 조건 | `success` 판별자, `error.code` 안정성, 빈 목록(`[]`)과 null의 구분(목록 필드는 생략하지 않음) |
|
||||
| 비용·부작용 | A는 shared-contract 변경이라 모든 전송의 직렬화 테스트를 한 번 돌려야 한다. `details:null`을 기대하는 기존 테스트가 있으면 같이 고친다 |
|
||||
| 재검토 조건 | 프론트가 envelope 검증을 느슨하게 바꾸기로 결정하면 B로 간다 |
|
||||
| 완료 기준 | 성공 응답 원문에 `error` 키가 없고 실패 응답 원문에 `data` 키가 없다. 계약 문서에 키 목록이 있고 짝 프론트 §4.1이 그 문서를 가리킨다 |
|
||||
| 검증 방법 | `EnvelopeBodyAdviceTest`와 `GlobalExceptionHandlerTest`에 응답 원문 JSON의 최상위 키 집합 단언. 프론트 fixture를 백엔드 실제 응답 문자열로 한 번 교체해 `validateEnvelope` 통과 확인 |
|
||||
|
||||
### 02-03 JWT audience 검증이 기본으로 꺼져 있고, 모든 client의 role을 합친다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(안전하지 않은 기본값, 문서와 코드 불일치) |
|
||||
| 관련 관점 | 15, 19, 21, 5 |
|
||||
| 근거 | `SecuritySettings.java:35-42`: audience가 null이면 WARN 한 줄을 남기고 `""`로 둔다. 빈 문자열이면 경고도 없다. `JwtDecoderConfig.java:80-82`: 비어 있으면 audience validator를 넣지 않는다. 기본 설정은 `config/security.yml:11-12`(`audience: ${APP_SECURITY_JWT_AUDIENCE}`, 주석 "blank to skip"), `.env.example:97`(`APP_SECURITY_JWT_AUDIENCE=` 빈 값). 반면 env 레지스트리는 `required: true`, `validation: csv_non_empty`, 타입 `csv_list`(`docs/registries/env-keys.yaml:1177-1187`). 코드는 값 하나만 비교하므로(`JwtDecoderConfig.java:101-104`, `contains(audience)`) `a,b`처럼 목록을 주면 모든 토큰이 거절된다. role 추출은 `resource_access`의 **모든 client** role을 합친다(`JwtToAuthenticatedPrincipalConverter.java:79-87`) |
|
||||
| 발생 조건 | 같은 issuer(예: Keycloak realm 하나)에 이 서비스 말고 다른 client가 있다. 운영자가 `APP_SECURITY_JWT_AUDIENCE`를 비워 둔 채 배포한다(템플릿 기본값) |
|
||||
| 영향 | 다른 앱을 위해 발급된 토큰도 이 API에서 인증된다. 그 토큰의 `resource_access.<다른 client>.roles`에 이 서비스의 role 이름(예: `operation-submit`, `ROLE_FILE_ADMIN`)과 같은 값이 있으면 권한까지 얻는다. 기본 role-permission 표(`security.yml` `app.authz.role-permissions`)가 일반적인 이름을 쓰므로 겹칠 여지가 있다 |
|
||||
| 심각도·우선순위 | High · P1. 인증 경계의 기본값이 열려 있고, 레지스트리는 "필수"라고 말해 운영자가 안심한다. 실제 다른 client 토큰으로 접근한 실험은 하지 않아 Critical로 올리지 않았다 |
|
||||
| 통제·증거 | 통제 M1(레지스트리에 required로 명시, 코드는 강제 안 함) · 증거 E1(코드·설정 읽기). audience 불일치 거부 자체는 기존 테스트가 있다(`JwtDecoderConfigTest`) |
|
||||
| 확실성과 남은 가정 | 코드 경로는 확정. `verifyEnvKeys`가 런타임 값의 비어 있음을 막지 않는다는 것은 레지스트리 형식과 `.env.example` 빈 값으로 추론했다(실행 안 함) |
|
||||
| 결정의 근거 | `[기록된 의도]` "blank to skip audience check"(`security.yml:11`). `[추론]` 로컬·테스트 편의를 위한 기본값이 운영 기본값으로 남았다. local·test 프로필은 audience를 채운다(`application-local.yml:174`, `application-test.yml:54`) |
|
||||
| 이해 비용 | 운영자는 레지스트리의 `required: true`를 믿고, 개발자는 WARN 로그를 보지 않는다. 두 문서를 대조해야 위험이 보인다 |
|
||||
| 최소 개선 방향 | JWT 모드에서 audience가 비면 기동을 거부한다(issuer와 같은 방식, `SecuritySettings.java:30-33`). 목록을 받으려면 `List<String>`으로 바인딩하고 "하나라도 포함"으로 비교한다. role 추출은 `resource_access` 중 audience(또는 설정한 client id)의 role만 읽는다 |
|
||||
| 대안 비교 | A) **audience 필수 + 자기 client role만**(권장): 기본값이 닫힌다. 비용은 기존 배포가 env 하나를 채워야 한다는 것. B) **prod 프로필에서만 필수**: 로컬 편의 유지. 대신 프로필 이름에 보안이 걸리고 dev·staging이 열린다. C) **현상 유지 + 문서 강조**: 숨은 위험이 그대로 남는다. 사용자 원칙("위험은 코드에 드러나야 한다")에 어긋나 기각 |
|
||||
| 단순화의 보존 조건 | issuer·timestamp 검증, 오류 코드 `AUTH_AUDIENCE_MISMATCH` 401, realm role 읽기 |
|
||||
| 비용·부작용 | 기존 파생 서비스의 기동이 env 누락으로 실패할 수 있다. 실패 메시지에 env 키 이름을 넣는다 |
|
||||
| 재검토 조건 | issuer를 서비스 전용으로 쓰는 배포만 지원한다고 명시하면 A의 role 범위 부분은 완화할 수 있다 |
|
||||
| 완료 기준 | JWT 모드에서 audience가 비면 기동 실패. 다른 client의 role만 가진 토큰이 권한을 얻지 못한다 |
|
||||
| 검증 방법 | `SecuritySettingsTest`에 빈 audience 거부, `JwtToAuthenticatedPrincipalConverterTest`에 "다른 client의 role은 무시" 케이스 |
|
||||
|
||||
### 02-04 rate-limit 거부 본문이 실제 Tomcat에서 ISO-8859-1로 나가 한국어 문구가 깨진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 1, 17, 23, 10 |
|
||||
| 근거 | `RateLimitInterceptor.java:77-81`은 `setContentType("application/json")` 뒤 `getWriter()`로 쓴다. 문자셋을 정하지 않는다. 같은 일을 하는 `AuthErrorResponseWriter.java:43-44`와 `GraphQlRequestBodyLimitFilter.java:119-120`은 UTF-8을 지정한다. **실험(E3)**: 실제 embedded Tomcat + Spring Boot 기본값과 같은 `CharacterEncodingFilter("UTF-8", forceRequest=true, forceResponse=false)`로 거부 응답을 받으니 `content-type=application/json;charset=ISO-8859-1`, 본문 `"message":"??? ?? ????. ?? ? ?? ??? ???."`. 기존 `RateLimitInterceptorTest`는 code·category·retryable만 단언해 이 문제를 못 잡는다 |
|
||||
| 발생 조건 | `app.rate-limit.enabled=true`에서 429 `RATE_LIMIT_EXCEEDED`, 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE` 응답 |
|
||||
| 영향 | 사용자에게 보일 문구가 `?`로 바뀐다. `content-type`의 문자셋도 틀린다. code·retryable은 ASCII라 기계 판정은 유지된다 |
|
||||
| 심각도·우선순위 | Medium · P2. 기능 판정은 살아 있고 문구만 망가진다 |
|
||||
| 통제·증거 | M0(이 경로의 문자셋 통제 없음) · E3(실제 Tomcat 실험) |
|
||||
| 확실성과 남은 가정 | Boot의 Tomcat factory가 응답 문자셋을 따로 정하지 않는다는 것은 `spring-boot-tomcat-4.0.8.jar`에서 `setResponseCharacterEncoding` 호출이 없음을 확인해 판단했다 |
|
||||
| 결정의 근거 | 적용 제외 — 같은 저장소의 다른 writer가 이미 UTF-8을 지정하고 있어 고를 선택지가 없는 단순 누락 |
|
||||
| 이해 비용 | 필터·인터셉터에서 본문을 직접 쓰는 곳이 셋이고 각각 문자셋을 기억해야 한다(41절 C 참고) |
|
||||
| 최소 개선 방향 | `RateLimitInterceptor.reject`에 `setCharacterEncoding(UTF_8)`. 더 나은 방법은 "직접 쓰는 Envelope 응답" writer 하나를 두고 셋이 그것을 쓰게 하는 것(리팩토링 후보 R-1) |
|
||||
| 대안 비교 | 적용 제외 — 단순 결함 수정 |
|
||||
| 완료 기준 | 실제 Tomcat에서 429 본문이 UTF-8이고 문구가 `ClientErrorMessages`와 같다 |
|
||||
| 검증 방법 | `RateLimitInterceptorTest`에 `getContentAsString(UTF_8)`의 message 단언 + `getCharacterEncoding()`이 UTF-8임을 단언 |
|
||||
|
||||
### 02-05 CORS에 노출 헤더가 없어 브라우저가 계약 헤더를 못 읽는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(설정 공백) |
|
||||
| 관련 관점 | 17, 15, 19, 8 |
|
||||
| 근거 | `SecurityConfig.java:150-156`은 origins·methods·headers·credentials·maxAge만 설정하고 `setExposedHeaders`가 없다. `CorsSettings`에도 해당 필드가 없다. 저장소 전체에서 `exposedHeaders`는 gRPC-Web 계약 클래스에만 있다 |
|
||||
| 발생 조건 | 브라우저 앱이 API와 다른 origin에서 부른다(`app.cors.enabled=true`, sample 기본값 `http://localhost:3000`) |
|
||||
| 영향 | 브라우저는 CORS 안전 목록 밖의 응답 헤더를 숨긴다. `Retry-After`(429·503, 그리고 02-01의 개선안), `X-Request-Id`(지원 문의용), `Location`(202 operation, poster publication), `ETag`(조건부 쓰기), `X-RateLimit-*`, tus의 `Upload-Offset`·`Location`·`Tus-Resumable`이 모두 `null`로 보인다. 짝 프론트는 `Retry-After`를 읽는다(`frontend/src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts:20`). cross-origin tus 업로드는 offset을 못 읽어 재개가 깨진다 |
|
||||
| 심각도·우선순위 | Medium · P2. same-origin(BFF·리버스 프록시) 배포에는 영향이 없다 |
|
||||
| 통제·증거 | M0 · E1(코드·설정 읽기). 브라우저 실행은 안 함 |
|
||||
| 확실성과 남은 가정 | CORS 안전 목록 동작은 Fetch 표준의 정의다. 배포가 프록시에서 `Access-Control-Expose-Headers`를 붙이는지는 템플릿 밖이라 모른다 |
|
||||
| 결정의 근거 | 적용 제외 — 노출할 헤더는 이미 계약에 있는 헤더라 선택지가 아니라 누락이다. 다만 목록을 설정으로 열지 고정할지는 아래에서 비교 |
|
||||
| 최소 개선 방향 | `CorsSettings`에 `exposedHeaders`를 추가하고 기본값을 플랫폼 계약 헤더(`ApiHeaders`의 `Retry-After`·`X-Request-Id`·`X-Correlation-Id`·`Location`·`ETag`·`X-RateLimit-*`)로 둔다. fileserver composition은 tus·draft-12 헤더를 기여한다 |
|
||||
| 대안 비교 | A) 기본 목록 + 설정 확장(권장). B) env 하나로 전부 운영자에게 맡김: 기본 배포가 계속 깨진다. C) `*` 노출: credentials 모드에서 `*`는 리터럴로 취급돼 동작하지 않는다 |
|
||||
| 완료 기준 | CORS preflight·실 요청 응답에 `Access-Control-Expose-Headers`가 위 목록을 담는다 |
|
||||
| 검증 방법 | `CorsSecurityFilterIntegrationTest`에 노출 헤더 단언 |
|
||||
|
||||
### 02-06 `String`을 반환하는 컨트롤러는 `Accept: application/json`에서 500이 된다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(숨은 함정) |
|
||||
| 관련 관점 | 5, 21, 20, 1 |
|
||||
| 근거 | `EnvelopeBodyAdvice.java:45-48`은 선택된 content type이 JSON이면 무엇이든 `Envelope`로 바꾼다. `String` 반환은 `StringHttpMessageConverter`가 고르므로 바뀐 `Envelope`를 String 컨버터가 받는다. **실행(E2)**: `Accept: application/json` → `500`, `ClassCastException`, 본문 `INTERNAL_ERROR`. `Accept: */*` → `200 text/plain "hello"`. 같은 엔드포인트가 curl에서는 되고 JSON 클라이언트에서는 깨진다. 이를 막는 ArchUnit 규칙(`WebArchitectureRules`)이나 문서가 없다 |
|
||||
| 발생 조건 | 파생 서비스 개발자가 `@GetMapping String ...`을 만든다 |
|
||||
| 영향 | 그 엔드포인트가 JSON 클라이언트에서 항상 500이고, 로그에는 ERROR로 ClassCastException이 남는다 |
|
||||
| 심각도·우선순위 | Medium · P2. 개발 중 바로 보이지만 원인 추적이 어렵고, 템플릿이 숨긴 규칙이다 |
|
||||
| 통제·증거 | M0 · E2 |
|
||||
| 결정의 근거 | 적용 제외 — 동작 결함. 막는 방식만 고른다 |
|
||||
| 최소 개선 방향 | `beforeBodyWrite`에서 `selectedConverterType`이 `StringHttpMessageConverter`면 감싸지 않거나, `supports`에서 String 반환을 제외한다. 또는 `WebArchitectureRules`에 "컨트롤러는 `String`을 반환하지 않는다" 규칙을 둔다 |
|
||||
| 대안 비교 | A) advice가 String을 통과(텍스트로 응답): 간단하지만 "모든 JSON은 Envelope"가 깨진다. B) ArchUnit으로 금지(권장): 규칙이 코드에 드러난다. C) String 컨버터 앞에 Jackson을 두기: 전역 컨버터 순서를 바꿔 다른 곳에 영향 |
|
||||
| 완료 기준 | String 반환 컨트롤러가 빌드에서 거부되거나 200으로 응답한다 |
|
||||
| 검증 방법 | `EnvelopeBodyAdviceTest`에 String probe 추가 또는 `WebArchitectureRulesTest`에 위반 fixture |
|
||||
|
||||
### 02-07 web-advanced 예외 10종이 문서의 상태 대신 500으로 나간다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(라이브러리 계약 미연결) |
|
||||
| 관련 관점 | 17, 6, 23, 22 |
|
||||
| 근거 | `web-advanced/src/main/java/.../advanced/` 아래 예외 10종(`AdmissionRefusedException`, `JsonPatchTestFailedException`, `JsonPatchRejectedException`, `PatchAuthorizationException`, `UnsupportedApiVersionException`, `SunsetViolationException`, `UntrustedTenantInputException`, `ReplayCursorExpiredException`, `StreamItemTooLargeException`, `RouteInventoryMismatchException`)이 모두 `RuntimeException`만 상속하고 `ApiErrorCarrier`가 아니다. leaf에 `@ExceptionHandler`도 없다. 문서는 상태를 약속한다: "maps to 503 with a Retry-After"(`AdmissionRefusedException.java:6`), "A failed `test` is 409"(`docs/web/patch-contract.md:66`). **실행(E2)**: `AdmissionRefusedException` → `500 INTERNAL_ERROR`, `Retry-After` 없음, 그리고 `GlobalExceptionHandler.handleUnknown`이 ERROR 로그를 남긴다 |
|
||||
| 발생 조건 | 서비스가 web-advanced의 admission guard, JSON Patch, API 버전 정책을 컨트롤러에서 쓴다(opt-in, 현재 운영 소비자 0) |
|
||||
| 영향 | 부하 거절이 500으로 보여 클라이언트가 재시도하지 않고, 알림이 장애로 울린다. patch `test` 실패가 500이라 "다시 읽고 재시도"를 못 한다 |
|
||||
| 심각도·우선순위 | Medium · P2. 기본 조합에는 없지만 라이브러리를 켜는 순간 모든 서비스에 복제된다 |
|
||||
| 통제·증거 | M1(Javadoc·문서) · E2(AdmissionRefused 한 종 실행, 나머지는 E1) |
|
||||
| 결정의 근거 | `[사실]` S5 정리 때 problem 어휘(`WebProblem`)를 지우면서 이 예외들의 매핑도 같이 사라졌다(`docs/capability-status.md` 「제거된 코드」 표 「WebProblem 어휘」). `[추론]` 예외는 남고 변환만 빠졌다 |
|
||||
| 최소 개선 방향 | 각 예외가 `ApiErrorCarrier`를 구현하고 코드 enum 하나(`WebAdvancedError`: 상태·category·retryable)를 둔다. 그러면 `GlobalExceptionHandler.handleCarrier` 한 분기로 처리되고 `Retry-After`도 `RetryAfterAdvisor` 표로 붙는다 |
|
||||
| 대안 비교 | A) carrier + enum(권장): 기존 한 분기 재사용. B) web-advanced 전용 `@RestControllerAdvice`: 오류 경로가 하나 더 생긴다(지난 리뷰가 지운 모양). C) 문서에서 상태 약속 삭제: 라이브러리의 쓸모가 줄고 500은 그대로 |
|
||||
| 완료 기준 | 10종 각각이 문서의 상태·코드로 나간다. 문서와 enum이 같은 값을 말한다 |
|
||||
| 검증 방법 | web-advanced에 예외별 MockMvc 매핑 테스트(실험 코드 `Review02AdvancedExceptionStatusExperimentTest`를 그대로 시작점으로) |
|
||||
|
||||
### 02-08 Spring MVC 예외의 상태→코드 변환이 의미를 잃는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 17, 23, 6 |
|
||||
| 근거 | `GlobalExceptionHandler.java:353-369`의 표는 4xx 나머지를 `BAD_PARAMETER`, 5xx를 전부 `INTERNAL_ERROR`로 보낸다. **실행(E2)**: `AsyncRequestTimeoutException`(Spring은 503) → `500 INTERNAL_ERROR retryable=false`. `@RequestParam @Max(10) int limit`에 99 → `HandlerMethodValidationException` → `400 BAD_PARAMETER details:null`. 같은 종류의 위반을 `ConstraintViolationException` 경로는 `VALIDATION_FAILED` + 필드 details로 낸다(`GlobalExceptionHandler.java:83-88`) |
|
||||
| 발생 조건 | async·streaming(web-advanced) 타임아웃, 컨트롤러 파라미터에 Bean Validation 제약 |
|
||||
| 영향 | 일시적 타임아웃이 재시도 불가 내부 오류로 보인다. 클라이언트는 어느 파라미터가 틀렸는지 모른다. 같은 위반이 경로에 따라 코드가 다르다 |
|
||||
| 심각도·우선순위 | Low · P2 |
|
||||
| 통제·증거 | M2(변환은 있음, 의미는 틀림) · E2 |
|
||||
| 결정의 근거 | 적용 제외 — 표에 두 줄을 더하는 단순 수정 |
|
||||
| 최소 개선 방향 | 503 → 일시적 코드(retryable), `handleHandlerMethodValidationException` override로 `VALIDATION_FAILED` + `ClientSafeValidationDetails` |
|
||||
| 완료 기준 | 위 두 요청이 각각 503 retryable, 400 `VALIDATION_FAILED` + field details |
|
||||
| 검증 방법 | `TransportErrorHandlingTest`에 두 케이스(I-3c의 남은 부분도 여기서 닫힌다) |
|
||||
|
||||
### 02-09 JSON 본문 상한의 두 갈래가 테스트로 묶여 있지 않고, JSON 아닌 본문은 상한이 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(테스트 공백) + 구조적 위험 |
|
||||
| 관련 관점 | 15, 10, 14 |
|
||||
| 근거 | **변이 실험**: ① `JsonBodyLimitFilter.java:87`의 선언 길이 사전 거부를 `if (false)`로 바꿈 → `JsonBodyLimitFilterTest`·`RequestBodyBoundaryTest`·`GlobalExceptionHandlerTest`·`TransportErrorHandlingTest` 모두 통과(생존). Javadoc이 약속한 "읽기 전에 거부"가 깨져도 아무 테스트도 실패하지 않는다. ② `shouldNotFilter`의 `+json` 분기 삭제(`:57-58`) → 생존. `application/merge-patch+json` 본문이 상한 없이 읽혀도 모른다. ③ 대조군: `handleCarrier`의 `Retry-After` 줄 삭제 → 5건 실패(죽음), 하네스가 정상임을 확인. 또 `shouldNotFilter`는 content type이 JSON이 아니면 통과시킨다(`:50-61`). `@RequestBody String`·`byte[]`를 `text/plain`·`application/octet-stream`·XML로 받는 엔드포인트에는 상한이 없다. Javadoc은 "Other media types keep their own ceilings"라고 적지만 multipart·form·tus·콜백 외에는 없다 |
|
||||
| 발생 조건 | 누군가 사전 거부를 리팩터링으로 지우거나, 서비스가 JSON 아닌 `@RequestBody`를 받는다 |
|
||||
| 영향 | 인증된 호출자가 큰 본문으로 힙을 채울 수 있다(인증 전 경로는 Tomcat이 막지 않는다) |
|
||||
| 심각도·우선순위 | Low · P2. 기본 조합의 JSON 경로는 스트림 계수로 여전히 막힌다 |
|
||||
| 통제·증거 | M2(구현) · M3 아님(변이 생존) · E2(변이 실험) |
|
||||
| 최소 개선 방향 | 테스트 2개 추가(선언 길이 초과면 `getInputStream`을 부르기 전에 예외, `+json` 본문도 상한 적용). JSON 아닌 본문은 같은 래퍼를 "multipart·form·등록된 업로드 경로 제외 전부"에 적용하는 쪽을 검토 |
|
||||
| 대안 비교 | A) 상한 대상을 "JSON"에서 "예외 목록 외 전부"로 뒤집기: 새 media type이 자동으로 보호된다. 업로드 경로를 빠뜨리면 업로드가 막히므로 예외 목록 테스트가 필요. B) JSON만 유지 + 문서에 "다른 타입은 직접 상한": 숨은 규칙이 남는다 |
|
||||
| 완료 기준 | 변이 ①②가 테스트에서 죽는다 |
|
||||
| 검증 방법 | 같은 변이를 다시 적용해 실패 확인 |
|
||||
|
||||
### 02-10 `GlobalExceptionHandler`가 두 경로로 등록된다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(Javadoc과 동작 불일치) |
|
||||
| 관련 관점 | 4, 24, 19, 27 |
|
||||
| 근거 | `WebAdapterAutoConfiguration.java:47`이 `GlobalExceptionHandler.class`를 조건 없이 `@Import`한다. `WebMvcPlatformAutoConfiguration.java:46-52`는 같은 타입을 `@ConditionalOnMissingBean`으로 다시 정의하는데, 앞의 import가 먼저라 이 정의는 실행되지 않는다. `WebMvcPlatformAutoConfiguration` Javadoc은 "off means no beans"라고 하지만 `app.web.mvc.enabled=false`여도 핸들러는 남고, 꺼지는 것은 요청 ID 필터와 JSON 본문 상한뿐이다 |
|
||||
| 발생 조건 | 서비스가 자기 오류 핸들러로 바꾸려고 스위치를 끄거나 같은 타입의 bean을 등록한다 |
|
||||
| 영향 | 끄면 보안 관련 본문 상한만 조용히 빠진다. 같은 타입 bean을 하나 더 두면 `@RestControllerAdvice` 두 개가 생기고 어느 쪽이 이길지 순서에 달린다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제·증거 | M1 · E1 |
|
||||
| 최소 개선 방향 | 등록 경로를 하나로(Platform 쪽 `@Bean`만 남기고 `@Import` 목록에서 제거). 스위치가 무엇을 끄는지 README 한 줄 |
|
||||
| 완료 기준 | `enabled=false`에서 무엇이 남는지 테스트가 단언한다 |
|
||||
| 검증 방법 | `WebMvcPlatformAutoConfigurationTest`에 스위치 off 케이스 |
|
||||
|
||||
### 02-11 `X-Correlation-Id` 허용 문자·길이가 요청 ID 규칙·짝 계약과 다르다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(계약 불일치) |
|
||||
| 관련 관점 | 8, 17, 23 |
|
||||
| 근거 | 요청 ID는 `[A-Za-z0-9._-]{1,128}`만 받는다(`WebMvcRequestIdFilter.java:62`). correlation ID는 `HeaderSanitizer`가 `0x20` 미만만 지우고 200자까지 그대로 둔다(`HeaderSanitizer.java:19`, `WebMvcRequestIdFilter.java:64,160-165`). 공백·유니코드·`DEL`이 응답 헤더와 `meta.correlationId`로 그대로 돌아간다. 짝 계약은 세 ID 모두 "1..128 안전한 opaque"(`backend-api-and-server-state-contract.md:199-200`)이고, 프론트 스키마는 `[A-Za-z0-9._:-]{1,128}`로 검증한다(`schema-registry.ts:6-8`) |
|
||||
| 발생 조건 | 프록시나 다른 클라이언트가 규칙 밖의 correlation ID를 보낸다 |
|
||||
| 영향 | 그 응답의 envelope 검증이 프론트에서 실패한다. 로그 검색 키가 공백·유니코드를 담는다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제·증거 | M2(개행 제거는 됨) · E1 |
|
||||
| 최소 개선 방향 | correlation ID도 요청 ID와 같은 패턴을 쓰고, 맞지 않으면 새로 발급한다 |
|
||||
| 완료 기준 | 규칙 밖 값이 들어오면 서버가 만든 값이 응답에 나간다 |
|
||||
| 검증 방법 | `WebMvcRequestIdFilterTest`에 공백·유니코드·129자 케이스 |
|
||||
|
||||
### 02-12 `Idempotency-Key` 헤더 검증이 컨트롤러마다 새로 쓰인다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안(구조적 위험) |
|
||||
| 관련 관점 | 20, 23, 3, 25 |
|
||||
| 근거 | web leaf는 헤더 이름 상수만 준다(`ApiHeaders.java:10`). 키 추출은 "구체 엔드포인트의 몫"이라고 정했다(`docs/web/repository-adaptation.md:99`). 유일한 운영 예시 `PosterImagePublicationController.java:61-69`는 blank·256자 초과면 `IllegalArgumentException`(→ `BAD_PARAMETER`), 문자 집합 규칙 없음, 헤더가 아예 없으면 Spring의 `MissingRequestHeaderException`(→ `BAD_PARAMETER`, 같은 코드). testFixtures의 `FaultFixtureController`는 또 다른 방식으로 받는다 |
|
||||
| 발생 조건 | 서비스가 KEYED 엔드포인트를 늘린다 |
|
||||
| 영향 | 엔드포인트마다 길이·문자·누락 처리·오류 코드가 갈라진다. 클라이언트는 "키 형식 오류"와 "다른 파라미터 오류"를 구분하지 못한다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제·증거 | M1 · E1 |
|
||||
| 결정의 근거 | `[기록된 의도]` claim·fingerprint는 use case가 소유(`README.md:460-466`). 이 제안은 그 결정을 바꾸지 않고 "헤더 → 검증된 값" 한 단계만 공용으로 만든다 |
|
||||
| 최소 개선 방향 | web leaf에 `IdempotencyKeyHeader`(값 객체 + argument resolver 또는 정적 parse)를 두고 길이·문자 규칙과 전용 코드(예: `IDEMPOTENCY_KEY_INVALID` 400)를 한 곳에서 정한다. sample이 그것을 쓴다 |
|
||||
| 대안 비교 | A) 공용 parse(권장). B) 현상 유지 + 문서 규칙: 복사본이 갈라지는 것을 막지 못한다. C) 필터로 모든 POST에 강제: KEYED가 아닌 엔드포인트까지 막는다 |
|
||||
| 완료 기준 | KEYED 컨트롤러가 같은 parse를 쓰고, 형식 오류는 한 코드로 나간다 |
|
||||
| 검증 방법 | parse 단위 테스트 + sample 컨트롤러 테스트 |
|
||||
|
||||
## 4. 31절 시나리오 추적
|
||||
|
||||
### 4.1 중복·동시 요청 — sample `POST /posters/{id}/imagePublications` 같은 키 재전송
|
||||
|
||||
```text
|
||||
브라우저 --Idempotency-Key--> WebMvcRequestIdFilter(요청 ID) -> JsonBodyLimitFilter(multipart라 통과)
|
||||
-> Spring Security(JWT) -> RequestLoggingFilter -> RateLimitInterceptor(켜졌을 때)
|
||||
-> PosterImagePublicationController(키 blank·길이 검사)
|
||||
-> PublishPosterImageUseCase: transactions.inWrite( IdempotencyExecutor.execute(scope, fingerprint, attempt, action) )
|
||||
-> 결과: 202 / replay 202 / 409 IN_FLIGHT / 422 MISMATCH / 503 UNAVAILABLE / 500 RECOVERY_REQUIRED
|
||||
```
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 입력 신뢰 | 키는 호출자 값. 길이만 본다(02-12). scope는 tenant·principal·키를 digest한 값이라 원문 키는 저장소에 가지 않는다 |
|
||||
| 인가 | 보안 체인이 인증. 권한은 use case 쪽(sample 정책). principal이 없으면 `IllegalArgumentException` → 400(401이 아님 — 보안 체인이 먼저 막으므로 도달 불가) |
|
||||
| 규칙 소유 | 같은 요청 판정은 `IdempotencyExecutor`와 use case의 fingerprint(`PosterImagePublicationFingerprint`) |
|
||||
| 트랜잭션 | `execute`가 `inWrite` 안에서 돈다. PostgreSQL 저장소면 claim이 같은 트랜잭션에 묶이고, Redis면 밖에 있다. 두 경우의 동시 요청 동작 차이는 application·persistence 영역(이 리뷰 범위 밖, 미검증) |
|
||||
| 외부 부작용 | object storage staging은 트랜잭션 뒤(`stageAndPrepare`) |
|
||||
| 성공의 의미 | 202는 "예약됨". 상태는 `GET .../{operationId}`로 본다 |
|
||||
| 오류 변환 | carrier 한 분기. in-flight 409의 클라이언트 행동이 정해지지 않았다(02-01). complete 단계의 503은 "action 전"이라는 문서와 다르다(P6-new-2) |
|
||||
| 진단 | 응답 `meta.requestId`·`traceId`. scope digest는 로그에만 |
|
||||
|
||||
### 4.2 다른 사용자 리소스 접근 — `GET /operations/{id}`
|
||||
|
||||
`DurableOperationController.get`은 principal·tenant를 query에 담아 `GetDurableOperationUseCase`로 넘기고, 없음과 남의 것을 같은 404 `OPERATION_NOT_FOUND`로 답한다(`DurableOperationController.java:106-118`). 판정은 use case와 `DurableOperationAccessPolicy`가 소유한다(I-1a 해결 유지). ID를 바꿔도 존재 여부가 새지 않는다. 남은 점: `OperationErrorCode`가 web 패키지 안의 enum이라 GraphQL·gRPC가 같은 연산을 노출하면 코드가 따로 생긴다(관찰, 발견으로 올리지 않음).
|
||||
|
||||
### 4.3 큰 입력 — JSON 본문, 콜백 본문, 목록
|
||||
|
||||
JSON은 1 MiB 기본 상한(`WebMvcPlatformSettings`)으로 선언 길이·스트림 계수 두 단계로 막는다(테스트 공백은 02-09). 알림 콜백은 컨트롤러가 `readNBytes(max+1)`로 직접 막는다. fileserver admin의 `limit`·`maxItems`는 HTTP에서 상한 없이 받아 use case로 넘긴다(use case 쪽 상한은 fileserver 영역에서 확인). 페이지 파라미터는 `PageParams`가 막는다.
|
||||
|
||||
### 4.4 적용 제외
|
||||
|
||||
| 시나리오 | 사유 |
|
||||
| --- | --- |
|
||||
| 외부 응답 지연·유실, DB 오류·경쟁, 메시지 중복·역순, 여러 서버 작업 실행 | 이 영역은 변환만 한다. 원인 쪽은 httpclient·persistence·messaging 영역 |
|
||||
| 신·구 버전 공존 | web-advanced 버전 정책은 운영 소비자 0. 예외 변환 결함만 02-07에 적었다 |
|
||||
| 세션·토큰 갱신 경쟁 | JWT 기본 모드는 서버 세션이 없다. redis-session 모드는 실행하지 않았다(미검증) |
|
||||
| 종료·재시작 | `GracefulShutdownProbe`·`TomcatLoadAndShutdownIT`가 있으나 `performanceTest`는 게이트에서 컴파일만 됐다(미검증) |
|
||||
| 선택 어댑터 제거 | composition 영역 |
|
||||
|
||||
## 5. 41절 설계 선택 검토
|
||||
|
||||
### 5.1 HTTP 오류를 Envelope 하나로(소유자 결정 2)
|
||||
|
||||
| 질문 | 답 |
|
||||
| --- | --- |
|
||||
| 1. 무엇이 필요한가 | 모든 HTTP 오류가 한 모양이고 `error.code`가 안정적이어야 한다. 짝 프론트가 이 모양을 검증한다 |
|
||||
| 2. 지킬 성질 | 어떤 경로(MVC 예외, 보안 체인, 인터셉터, fileserver)에서도 같은 키 집합·같은 문구 표·같은 코드 규칙 |
|
||||
| 3. 현재 보장 | `ErrorResponseFactory`가 본문을 만들고 `ClientErrorMessages`가 문구를 정한다. problem+json 누수는 막혔다(I-3a). 보장하지 않는 것: null 필드 존재(02-02), 직접 쓰는 writer의 문자셋(02-04), 라이브러리 예외의 코드(02-07) |
|
||||
| 4. 대안 | 현상 유지 / RFC 9457 problem+json / Envelope + wire 계약 문서 |
|
||||
| 5. 득실 | problem+json은 표준 도구와 맞지만 결정 2를 뒤집는다. Envelope 유지는 비용이 작고, 대신 wire 규칙을 문서·테스트로 고정해야 한다 |
|
||||
| 6. 왜 이 선택 | 결정 2를 유지한다. 부족한 것은 선택이 아니라 "키 집합을 단언하는 테스트와 소비자용 문서"다 |
|
||||
| 7. 재검토 조건 | 외부 공개 API로 쓰여 표준 도구 연동이 요구되면 problem+json을 다시 비교한다 |
|
||||
|
||||
### 5.2 멱등성 in-flight는 기다리지 않고 409, retryable=false
|
||||
|
||||
| 질문 | 답 |
|
||||
| --- | --- |
|
||||
| 1. 필요 | 결과 불명 쓰기를 같은 키로 안전하게 다시 보낼 수 있어야 한다 |
|
||||
| 2. 성질 | 같은 키는 한 번만 실행. 처리 중인 동안 다른 시도는 실행하지 않는다. 클라이언트는 "새 키로 다시"를 하지 않는다 |
|
||||
| 3. 현재 보장 | 앞 두 성질은 executor가 보장한다. 세 번째는 응답이 오히려 반대로 말한다(02-01) |
|
||||
| 4. 대안 | 409 + retryable=true + `Retry-After` / 서버 대기 후 replay / 키 조회 엔드포인트 / 202 + 상태 URL |
|
||||
| 5. 득실 | 02-01 표 참고. 202 + 상태 URL은 모든 KEYED 엔드포인트를 비동기 모양으로 바꿔야 해 비용이 크다 |
|
||||
| 6. 선택 | 기다리지 않는 409는 스레드를 잡지 않아 유지할 가치가 있다. retryable 값과 문서를 고친다 |
|
||||
| 7. 재검토 | 처리 시간이 대부분 lease보다 짧다는 측정이 나오면 짧은 대기 + replay가 더 단순할 수 있다 |
|
||||
|
||||
### 5.3 rate limit·인증 거부는 컨버터 밖에서 본문을 직접 쓴다
|
||||
|
||||
| 질문 | 답 |
|
||||
| --- | --- |
|
||||
| 1. 필요 | 컨트롤러 전에 거부한 요청도 Envelope로 답한다 |
|
||||
| 2. 성질 | 본문·문자셋·헤더가 컨트롤러 응답과 같다 |
|
||||
| 3. 현재 보장 | 세 writer(`AuthErrorResponseWriter`, `RateLimitInterceptor.reject`, GraphQL body limit)가 각자 `setContentType`·`writeValue`를 한다. 하나가 문자셋을 빠뜨렸다(02-04) |
|
||||
| 4. 대안 | 현상 유지 / 공용 `EnvelopeResponseWriter` / 인터셉터가 예외를 던져 `GlobalExceptionHandler`가 쓰게 함 |
|
||||
| 5. 득실 | 공용 writer는 파일 하나로 세 경로가 같아진다. 예외 방식은 보안 체인 안에서는 쓸 수 없다(MVC 밖) |
|
||||
| 6. 선택 | 공용 writer(리팩토링 R-1) |
|
||||
| 7. 재검토 | 보안 체인 거부를 MVC로 넘기는 구조로 바뀌면 예외 방식으로 합칠 수 있다 |
|
||||
|
||||
## 6. 리팩토링 후보
|
||||
|
||||
| ID | 무엇을 | 왜 | 보존 조건 |
|
||||
| --- | --- | --- | --- |
|
||||
| R-1 | `AuthErrorResponseWriter`·`RateLimitInterceptor.reject`의 본문 쓰기를 web의 `EnvelopeResponseWriter` 하나로 | 문자셋·content type·`Retry-After` 규칙이 한 곳에 있게(02-04) | 401의 `WWW-Authenticate`, 429의 `X-RateLimit-*`, 문구는 `ClientErrorMessages` |
|
||||
| R-2 | web-advanced 예외 10종 → `ApiErrorCarrier` + `WebAdvancedError` enum | 변환이 `handleCarrier` 한 분기로(02-07) | 예외 타입 이름(공개 API surface), 메시지의 서버 전용 정보는 본문에 안 나감 |
|
||||
| R-3 | profile-name record 5개 → `ProfileName` 하나(S5-#12) | 같은 정규식 다섯 벌 | 각 타입이 서로 대입되지 않게 하려면 래퍼 타입은 유지하고 검증만 공용 |
|
||||
| R-4 | `GlobalExceptionHandler` 등록 경로 하나로(02-10) | 스위치 의미가 코드와 같게 | 사용자가 같은 타입 bean을 주면 그것이 쓰인다 |
|
||||
| R-5 | `FileserverRequestContextFactory.java:63` 주석 "set by the request-logging filter" → `WebMvcRequestIdFilter` | 주석이 옛 구조를 말함 | 없음 |
|
||||
| R-6 | web `build.gradle`의 `testImplementation project(':adapter:inbound:web-fileserver')` | 부모 leaf 테스트가 자식 leaf를 안다(방향 역전, 테스트 범위). `PresentationWebConfigTest`의 예시를 web 안 fixture로 바꾸면 끊을 수 있다 | prefix가 절대 경로 컨트롤러를 건드리지 않는다는 단언 |
|
||||
|
||||
## 7. 기능 개발 패턴과 판단 지점
|
||||
|
||||
### 7.1 템플릿이 주는 틀
|
||||
|
||||
- 새 HTTP 엔드포인트: 컨트롤러는 DTO를 반환하고 `EnvelopeBodyAdvice`가 감싼다. 예시는 sample-portfolio 컨트롤러와 `DurableOperationController`.
|
||||
- 도메인 오류: `ApiErrorCarrier` + 자기 `ApiErrorCode` enum이면 `GlobalExceptionHandler`가 한 분기로 처리한다(`OperationErrorCode`가 예).
|
||||
- 인가: use case의 `@RequiresPermission` + 소유자·tenant 검사는 use case 안. 관리 경로는 `RestrictedPathRule` bean으로 보안 체인에서 한 번 더.
|
||||
- 입력: `PageParams`·`SortParam`, `ETags`·`PreconditionFailedException`.
|
||||
- 테스트: `WebContractAssertions`, `ContractFixtureApplication`, `WebArchitectureRules`(ArchUnit), 장애 fixture(`IdempotencyResponseLossContract`, `CommitThenConnectionResetIT`).
|
||||
|
||||
### 7.2 빠진 것
|
||||
|
||||
- 소비자용 HTTP 계약 문서(Envelope 키 규칙, 상태·코드·retryable·헤더·클라이언트 행동 표). 지금은 README 예외 표가 유일하다(02-01, 02-02).
|
||||
- `Idempotency-Key` 공용 parse(02-12).
|
||||
- CORS 노출 헤더 기본값(02-05).
|
||||
- `String` 반환 금지 규칙(02-06).
|
||||
- web-fileserver·web-notification README(S5-#14c).
|
||||
|
||||
### 7.3 개발자가 내려야 하는 판단(매뉴얼 재료)
|
||||
|
||||
1. **응답 모양**: DTO를 반환할지 `Envelope`를 직접 만들지. `String`은 반환하지 않는다. 202·Location이 필요하면 `ResponseEntity<Envelope<…>>`.
|
||||
2. **오류 코드 설계**: 새 실패마다 status·category·retryable을 정한다. retryable은 "같은 요청을 그대로 다시 보내면 성공할 수 있는가"로 판단한다(02-01이 이 기준을 어긴 예).
|
||||
3. **404와 403**: 남의 리소스는 "없음"과 같은 404로 답할지(operation이 이 방식), 403으로 답할지.
|
||||
4. **KEYED 여부**: 중복 실행이 피해인지. 그렇다면 키를 필수로 받고, fingerprint에 넣을 필드를 use case에서 정하고, in-flight·mismatch 응답을 클라이언트에 어떻게 설명할지.
|
||||
5. **입력 상한**: JSON 1 MiB 밖의 media type을 받으면 자체 상한을 둔다.
|
||||
6. **공개 경로·관리 경로**: `public-paths`에 넣을지, `RestrictedPathRule`로 막을지.
|
||||
7. **브라우저 노출 헤더**: 클라이언트가 읽어야 하는 응답 헤더면 CORS 노출 목록에 넣는다.
|
||||
|
||||
## 8. 28개 관점 판정표
|
||||
|
||||
| # | 관점 | 판정 | 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | P | 대부분 명확하다. 문자셋 누락(02-04), String 함정(02-06) |
|
||||
| 2 | 구조적 성숙도 | O | leaf 분리와 의존 방향이 registry대로. 인가·멱등 판정이 use case에 있다 |
|
||||
| 3 | 변경 용이성 | P | 오류 코드 추가는 enum 한 곳. 멱등 키 처리는 엔드포인트마다(02-12) |
|
||||
| 4 | 인지 부하 | P | 등록 경로 이중(02-10), in-flight 의미를 다섯 곳에서 맞춰 읽어야 함(02-01) |
|
||||
| 5 | 위험 가시성 | X | audience 기본 off(02-03), String 함정(02-06), null 필드(02-02)가 코드에 드러나지 않음 |
|
||||
| 6 | 실패 성숙도 | P | 실패 변환은 한 분기. 503→500, 라이브러리 예외 500(02-07, 02-08) |
|
||||
| 7 | 운영 성숙도 | P | 런북 있음. in-flight 런북 문장이 틀림(02-01) |
|
||||
| 8 | 디버깅 가능성 | O | 요청·trace ID가 보안 체인 앞에서 한 번 발급되고 모든 응답 `meta`에 실림. correlation ID 규칙만 다름(02-11) |
|
||||
| 9 | 유지보수 성숙도 | P | 남은 Nit(S5-#12, I-7), 낡은 주석(R-5) |
|
||||
| 10 | 테스트 성숙도 | P | 테스트 600건 13초대. 그러나 `doesNotExist`가 null을 못 가림(02-02), 본문 상한 변이 2건 생존(02-09), 문구 미단언(02-04) |
|
||||
| 11 | 데이터 성숙도 | - | 이 영역은 저장하지 않는다 |
|
||||
| 12 | 동시성 성숙도 | P | in-flight 판정은 저장소가 함. HTTP 계약이 클라이언트 행동을 틀리게 말함(02-01) |
|
||||
| 13 | 확장성 | ? | 부하를 걸지 않았다 |
|
||||
| 14 | 성능 성숙도 | ? | 필터 4개·HMAC 한 번 정도로 요청당 비용은 작다고 추정. 측정 안 함. 비JSON 본문 상한 없음(02-09) |
|
||||
| 15 | 보안 성숙도 | X | audience·role 범위(02-03). 그 밖의 경계(XFF 불신, 요청 ID 불신, 중복 키 JSON 거부, 콜백 별도 체인)는 좋음 |
|
||||
| 16 | 의존성 성숙도 | O | 방향 위반 없음. 테스트 범위 역방향 하나(R-6) |
|
||||
| 17 | API / Contract 성숙도 | X | 짝 계약과 3곳 불일치(02-01, 02-02, 02-11), 소비자용 계약 문서 없음 |
|
||||
| 18 | 배포 성숙도 | > | 13 build/CI 영역 |
|
||||
| 19 | 설정 성숙도 | P | 대부분 fail-closed. audience만 fail-open(02-03), CORS 노출 설정 없음(02-05) |
|
||||
| 20 | 개발자 경험 | P | 예시·testkit은 충분. 함정 2개(02-06, 02-12) |
|
||||
| 21 | Guardrail 성숙도 | P | ArchUnit 규칙 있음. String 반환·audience는 막지 않음 |
|
||||
| 22 | 추상화 성숙도 | O | `ApiErrorCarrier` 한 분기, `RestrictedPathRule` 기여 방식이 적절. web-advanced 예외만 빠짐(02-07) |
|
||||
| 23 | 일관성 | P | 같은 위반이 경로에 따라 다른 코드(02-08), writer 문자셋(02-04) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | P | `retryable=false`가 실제 권장 행동과 반대(02-01), 스위치 이름과 동작 불일치(02-10) |
|
||||
| 25 | 조직 확장성 | P | KEYED 엔드포인트가 늘면 키 처리 갈라짐(02-12) |
|
||||
| 26 | Ownership 성숙도 | P | web-fileserver·web-notification에 README·CLAUDE.md 없음(S5-#14c) |
|
||||
| 27 | 삭제 가능성 | O | web-notification·web-fileserver·web-advanced가 한 줄로 빠진다. 스위치 의미만 02-10 |
|
||||
| 28 | 회복 가능성 | P | 결과 불명 쓰기의 복구 경로(같은 키 재전송)가 문서에 없다(02-01, P6-new-2) |
|
||||
@@ -0,0 +1,434 @@
|
||||
# 03 — inbound 실시간·GraphQL·gRPC (websocket · graphql · grpc 어댑터, vendored `grpc:*`·`grpc-advanced:*`)
|
||||
|
||||
2026-11-01 백엔드 성숙도 리뷰, 영역 03. 기준 커밋 `01a8a2a70`(main).
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 | `src/adapter/inbound/websocket`, `src/adapter/inbound/graphql`, `src/adapter/inbound/grpc`, `src/grpc/*`(registry의 `optional-grpc` leaf 7개), `src/grpc-advanced/*`(2개), `src/optional-platforms` |
|
||||
| 커밋·시점 | `main` @ `01a8a2a70`, 2026-11-01 |
|
||||
| 목적·실행 구성 | 템플릿. 세 어댑터 모두 기본 bootJar에 없고 `runtimeOnly` 한 줄로 고르는 opt-in. gRPC 플랫폼은 별도 Gradle build(`-p optional-platforms`)이고 어떤 composition도 쓰지 않는다. qualification 이미지(`COMPOSITION=qualification`)만 세 어댑터를 모두 싣는다 |
|
||||
| 규모·운영 목표 | 문서에 없음. "대규모 운영 준비" 판정은 하지 않는다 |
|
||||
| 읽은 코드 | 세 어댑터 main 전부(websocket 1,557줄, grpc 어댑터 약 900줄), graphql은 `cost/`·`runtime/`·`dataloader/`·`policy/`·`autoconfigure/`·`context/`·`execution/` 전부와 나머지 목록, gRPC 플랫폼은 `grpc-core-api/ledger`·`grpc-runtime/idempotency`·`grpc-spring-boot-starter` 전부·`grpc-operation-ledger-jpa` 전부·`grpc-testkit/netty/GrpcNettyTestServer`, advanced는 지난 발견 재확인 범위만. 각 leaf `CLAUDE.md`·`README.md`, `src/grpc/CLAUDE.md`, `src/grpc-advanced/CLAUDE.md`, `.github/workflows/{integration-main,ci-quality-gates,release,pr-adapters}.yml`. Spring 소스 `spring-messaging-7.0.9` `SimpleBrokerMessageHandler` |
|
||||
| 실행한 명령 | 아래 표 |
|
||||
| 확인 못 한 것 | `-p optional-platforms ci`(grpc-runtime·testkit·advanced 단위 테스트, Netty·fault lane) 이번 커밋에서 미실행. `websocketNginxTest`는 오늘 미실행(결과 파일이 2026-09-28). 실부하·다중 노드·실 TLS 없음. GitHub Actions에서 `grpc-optional-platform-integration` job이 실제로 green인지는 확인하지 않음(외부 조회 금지) |
|
||||
| 이전 리뷰와 비교 | `docs/reviews/2026-09-18-techlead-review/{03,04,11}-*.md`, `docs/reviews/2026-09-25-review-followup-status.md`의 J·K·N·S5·S6·S7·NEW·P*-new 행, `docs/reviews/2026-08-14-graphql-module-code-review.md` |
|
||||
|
||||
실행 기록(모두 scratchpad worktree `wt-03`, `flock heavy.lock`으로 감쌈, 끝나고 worktree 제거):
|
||||
|
||||
| 명령 | 부하(uptime) | 결과 |
|
||||
| --- | --- | --- |
|
||||
| 오케스트레이터 게이트 `ci` | 9.15 | rc=0(7분 9초). 세 어댑터 `check`(test·spotless·checkstyle·Error Prone·API surface) 통과 |
|
||||
| 오케스트레이터 게이트 `mainCheck` | 20.68 | rc=1. 실패는 objectstorage MinIO 이미지 pull 404 두 건뿐. 이 영역의 `systemTest`(websocket·graphql), `websocketJettyTest`, `*TransportQualificationTest` 3개, `graphqlStableTest`, `conditionalTransportQualification`은 실행됐고 실패 없음 |
|
||||
| `:adapter:inbound:graphql:test --tests '*Review03ComplexityProbeTest'` (리뷰용 임시 테스트) | 8.65 | 통과 = 결함 재현. `REVIEW03 explicit20=410 omitted=40 nested4=100 variableDefault100000=40` (03-01) |
|
||||
| `:adapter:inbound:websocket:test --tests '*Review03WebSocketProbeTest'` (임시) | 8.65 | 통과 = 결함 재현. `leakedGlobalBytes=500`(03-07), `openAfterStop=1 running=false`(03-08) |
|
||||
| `-p optional-platforms :grpc:grpc-operation-ledger-jpa:integrationTest` | 7.89 | 통과. `GrpcOperationLedgerPostgresIT` 2건 + `JpaGrpcOperationLedgerContractIT` 16건, skip 0, `postgres:16-alpine`, V001 SQL을 그대로 적용. 벽시계 77초(잠금 대기 포함) |
|
||||
| 변이 1: `GraphQlCostBudgetHandler`의 `structuralLimits.verify(shape)` 무력화 → `:adapter:inbound:graphql:systemTest` | 6.13 | 잡힘. 25건 중 2건 실패(`aDocumentDeeperThanTheStructuralLimit…`, `anAliasBomb…`) |
|
||||
| 변이 2: STOMP SUBSCRIBE destination 검사 무력화 → `:adapter:inbound:websocket:test` | 6.13 | 잡힘. `WebSocketInboundAuthorizationInterceptorTest.permitsAuthenticatedSubscribeOnlyToConfiguredTopic` 실패 |
|
||||
|
||||
임시 테스트 원본은 scratchpad `src03/Review03*.java`에 남겼다. 메인 repo에는 이 문서 말고 바꾼 파일이 없다.
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
상태: 해결 / 남음 / 바뀜. followup-status에서 이미 `완료`이고 이번에 다시 볼 이유가 없던 행은 생략했다. 아래는 남음·보류였거나 이번 주제(연결 상한·깊이·N+1·deadline·ledger)에 걸린 행이다.
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| J-3b (Javadoc "detail은 로그에") | 해결 | `graphql/.../error/GraphQlWireErrorMapper.java:35`가 실제로 로그하는 `GraphQlExceptionResolver`를 가리킨다(J-3a에서 ERROR 로그 추가) |
|
||||
| J-4c (DataLoader 실패 테스트가 `isNotEmpty()`만) | 남음 | `graphql/src/test/.../runtime/GraphQlBatchLoaderRegistrationTest.java:133,146,162,198` |
|
||||
| J-9b (chunked 본문 경로 테스트 없음) | 해결 | `graphql/src/systemTest/.../runtime/GraphQlPlatformExecutionPathTest.java:263` `aChunkedBodyOverTheRawCapIsRefusedWith413` |
|
||||
| J-11b (README가 없는 resolver 설명) | 해결 | `graphql/README.md`에 `GraphqlExceptionResolver` 0건 |
|
||||
| J-12 / X2-P2-6b | 보류(소유자 결정 35) | 결정대로 유지. 다시 열지 않음 |
|
||||
| S5-#7c (autoconfig 주석이 사실과 다름) | 남음 | `graphql/.../autoconfigure/GraphQlRootAutoConfiguration.java:39` "component scan excludes by regex" 문장이 아직 있다 |
|
||||
| S5-#14d (graphql 주석 과다·"design §") | 남음 | graphql main에 `design §` 46곳 |
|
||||
| S5-#14e (interceptor 생성자 인자 과다) | 남음 | `graphql/.../runtime/GraphQlPlatformWebInterceptor.java:70-80` 인자 10개(9 → 10) |
|
||||
| K-5b (종료 IT가 context를 안 닫음) | 해결 | `websocket/src/systemTest/.../runtime/TomcatWebSocketShutdownIT.java:29-58`이 context를 닫고 1001을 단언. 단 `TomcatWebSocketAbuseIT.java:69`는 여전히 `handler.stop()` 직접 호출(중복 테스트) |
|
||||
| P25-new-1 (shutdown 테스트 시간 경계 flaky) | 남음 | `TomcatWebSocketAbuseIT.java:73-77` `took < 20s`와 `await(20s)`가 같은 경계 |
|
||||
| K-12c (CLAUDE.md "Boot 4.0.0") | 남음 | `adapter/inbound/grpc/CLAUDE.md:8`, `adapter/inbound/graphql/CLAUDE.md:8` |
|
||||
| techlead 03-H3 (`CONNECTION_MUST_CLOSE` 무시) | 해결 | `websocket/.../servlet/PlatformWebSocketHandler.java:176-180` 1013으로 닫음 |
|
||||
| techlead 03-H7 (gRPC loopback 전용) | 남음(의도·문서화) | `adapter/inbound/grpc/CLAUDE.md` "Current transport limit". TLS는 P2로 미룸 |
|
||||
| techlead 03-M4 (글로벌 예산을 poll 때 반납) | 해결 | `OutboundQueue.java:119-124` `releaseInFlight`가 write 뒤 반납. 다만 close 경합은 새 결함 03-07 |
|
||||
| techlead 03-M5 (모든 `BindableService` 노출) | 해결 | `GrpcServerConfig` `@GrpcExposedService` 한정 |
|
||||
| techlead 04-M5 (parser 한계 미설치) | 바뀜 | parse 전 `maxDocumentBytes` 16 KiB 검사(`GraphQlPlatformWebInterceptor.java:125-133`) + graphql-java 기본 parser 한계. 별도 설치는 여전히 없음 |
|
||||
| techlead 04-L2 (전역 `Clock` 빈) | 해결 | `GraphQlRequestContextConfiguration.java:35-37` `@ConditionalOnMissingBean(Clock.class)` |
|
||||
| techlead 11-C1 / N-1 / N-11a (ledger claim 원자성) | 해결 | `JpaGrpcOperationLedger.java:39-65`(native `INSERT … ON CONFLICT DO NOTHING`), 이번 PG lane 18건 통과 |
|
||||
| techlead 11-H1 (startup validator 미호출) | 해결 | `GrpcPlatformAutoConfiguration` `grpcPlatformStartupCheck`(`SmartInitializingSingleton`) |
|
||||
| techlead 11-M9 (starter가 JPA를 끌어옴) | 해결 | starter `build.gradle`에 ledger 의존 없음, `src/grpc/CLAUDE.md` "Durable operation ledger adoption" |
|
||||
| N-12a (`GrpcClientMessageDeduplicator` "constant space") | 남음 | `grpc-advanced/.../streaming/GrpcClientMessageDeduplicator.java:13,112` |
|
||||
| N-12b (`ReactiveGrpcClient.serverStream`) | 남음 | `grpc-advanced-compat/.../reactor/ReactiveGrpcClient.java:50` |
|
||||
| P5-new-1 (Envoy `VirtualHost.cors` deprecated) | 남음 | `grpc-advanced-compat/src/test/resources/envoy/envoy.yaml:37` |
|
||||
| P15-new-4 (status description 변경 이행 안내) | 바뀜(부분) | `adapter/inbound/grpc/README.md:79-81`에 trailer 안내 추가. 그러나 `:87`은 여전히 "code 문자열만 status description/trailer로 노출"이라 적어 설명이 엇갈린다 |
|
||||
| S7-lead-2 (root family 표에 gRPC 행 없음) | 남음 | root `CLAUDE.md` 「Module families」 표에 `messaging:*` 행만 있고 `grpc:*`·`grpc-advanced:*` 행이 없다 |
|
||||
|
||||
이번 커밋에서 남은 High/P1은 지난 발견 쪽에는 없다. High는 아래 새 발견 두 건이다.
|
||||
|
||||
## 3. 새 발견
|
||||
|
||||
심각도별: High 2 · Medium 7 · Low 3. 우선순위별: P1 2 · P2 7 · P3 3. Critical·P0 없음.
|
||||
|
||||
### 03-01 GraphQL 복잡도 점수가 목록 크기를 놓친다 — 페이지 인자 생략·변수 기본값·일반 list 필드
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 1, 5, 6, 10, 13, 14, 15, 17 |
|
||||
| 근거 | `graphql/.../cost/GraphQlDocumentComplexityScorer.java:217-222` — `first`/`last` 인자가 **값으로 읽힐 때만** `connectionCost`(자식 비용 × 페이지 크기)를 쓰고, 아니면 `fieldCost`(자식 비용 × 1). `:242-249` 변수 참조는 요청 `variables` 맵에 없으면 `null`. `GraphQlCostBudgetHandler.java:78`이 넘기는 맵은 클라이언트가 보낸 원본이라 연산의 변수 기본값(`$n: Int = 100000`)이 없다. `:206` `unwrap`이 `GraphQLList`를 벗겨 버려 일반 list 필드의 개수 정보가 사라진다. 반면 `GraphQlComplexityCalculator.java:9-11` Javadoc은 "first를 생략하면 기본 페이지로 계산해야 한다, 1로 계산하면 예산 우회"라고 적고 있다. 페이지 상한 검사(`GraphQlComplexityCalculator.java:51`)도 `connectionCost`에만 있다. 임시 테스트 결과: `items(first: 20){name}` = 410, `items{name}` = 40, `items{children{children{children{name}}}}` = 100(4단 중첩 list가 선형 합), `query($n:Int=100000){items(first:$n){name}}` = 40으로 통과(같은 값을 리터럴로 쓰면 `GraphQlComplexityRejectedException`) |
|
||||
| 발생 조건 | adopter 스키마에 list 반환 필드가 있으면 항상. 공격자는 `first`를 빼거나, 변수 기본값으로 숨기거나, 변수를 아예 안 보낸다 |
|
||||
| 영향 | 복잡도 예산(기본 10,000)과 페이지 상한(기본 100)이 사실상 꺼진다. 중첩 list는 실제 작업이 곱으로 늘어나는데 점수는 합으로만 는다. resolver가 플랫폼 밖 라이브러리 `GraphQlConnectionPolicy`를 직접 부르지 않으면 `first: 100000`이 그대로 DB까지 간다 |
|
||||
| 심각도·우선순위 | High · P1. GraphQL은 opt-in이지만 이 플랫폼이 판매하는 핵심 보호(`CLAUDE.md` 등급표 "depth/complexity 제한 `wired`")가 list 필드가 생기는 순간 무력하다. 템플릿을 복사한 서비스로 그대로 퍼진다 |
|
||||
| 확실성 | 직접 확인(E2 임시 테스트). systemTest 스키마(`src/systemTest/resources/graphql-platform/platform.graphqls`)에 list·connection 필드가 하나도 없어서 기존 테스트가 이 경로를 밟지 않는다. `GraphQlDocumentComplexityScorer` 전용 단위 테스트도 없다 |
|
||||
| 통제 수준 | 깊이·필드·alias 상한은 M3(변이 1로 확인). 목록 크기 반영은 M0 |
|
||||
| 결정의 근거 | 적용 제외 — 문서화된 계약(Javadoc)과 코드가 어긋난 단순 결함 |
|
||||
| 최소 개선 방향 | (1) 필드 정의가 list(또는 connection 규약 타입)면 `first`/`last`가 없거나 `null`일 때 `defaultPageSize`를 곱한다. (2) 변수 값은 `ExecutionInput`이 아니라 graphql-java가 기본값을 적용한 `CoercedVariables`(`ValuesResolver.coerceVariableValues`)로 읽는다. (3) 페이지 인자가 없는 일반 list는 기본 배수(`defaultPageSize`)로 곱하고, adopter가 `GraphQlFieldCostDescriptor`로 필드별 배수를 줄 수 있게 한다. 버린 대안: graphql-java 기본 `MaxQueryComplexityInstrumentation` 도입 — 이 역시 list 배수를 모르는 필드 개수 합이라 같은 구멍이 남고, 플랫폼 점수와 두 벌이 된다 |
|
||||
| 완료 기준 | 위 네 쿼리의 점수가 각각 페이지 크기만큼 곱해지고, 변수 기본값 100000은 `page size exceeds maximum`으로 거부된다 |
|
||||
| 검증 방법 | `cost/`에 scorer 단위 테스트(위 네 케이스) + systemTest 스키마에 list 필드 하나와 "first 생략 + 중첩" 거부 케이스 |
|
||||
|
||||
### 03-02 GraphQL 요청 deadline(10초)이 실행 중에는 강제되지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(문서와 동작 불일치) + 구조적 위험 |
|
||||
| 관련 관점 | 5, 6, 9, 14, 22 |
|
||||
| 근거 | `policy/GraphQlClientPolicy.java:90` `maxExecutionTime` 10초 → `GraphQlPlatformWebInterceptor.java:147` deadline 생성. 읽는 곳은 `GraphQlCostBudgetHandler.java:62`(실행 **전** 한 번)과 `dataloader/GraphQlBatchExecutor.java:110`(platform registrar로 등록한 batch만)뿐. resolver 실행 자체를 끊는 장치(Spring GraphQL `TimeoutWebGraphQlInterceptor`, `DataFetcher` timeout)는 없다. `execution/GraphQlTimeoutPolicy.java`는 main 호출자 0(테스트만). `context/GraphQlDeadline.java:9-12` Javadoc은 "resolver, DataLoader batch, JPA/Mongo/HTTP client deadline으로 같은 budget을 내려준다"고 적는다 |
|
||||
| 발생 조건 | 느린 resolver·외부 호출이 있는 adopter 쿼리 |
|
||||
| 영향 | 요청이 10초 뒤에도 servlet 스레드를 잡고 계속 돈다. 클라이언트는 이미 끊었는데 DB 커넥션·스레드가 묶인다. 운영자는 설정만 보고 10초 상한이 있다고 믿는다 |
|
||||
| 심각도·우선순위 | Medium · P2. 기본 composition에 없고 피해는 자원 점유로 제한된다 |
|
||||
| 통제 수준 | M1(설정·Javadoc만), 실행 강제 M0 |
|
||||
| 결정의 근거 | 적용 제외 — 이미 정한 계약(`maxExecutionTime`)을 실행에 연결하는 문제 |
|
||||
| 최소 개선 방향 | 고른 방법: Spring GraphQL의 `TimeoutWebGraphQlInterceptor`(또는 같은 일을 하는 interceptor)를 `maxExecutionTime`으로 auto-config에 넣고, 시간 초과를 `REQUEST_TIMEOUT`으로 매핑한다. 쓰지 않는 `GraphQlTimeoutPolicy`는 지우거나 하위 호출이 쓰도록 연결한다. 버린 대안: resolver마다 deadline을 검사 — adopter가 기억해야 하는 숨은 규칙이 된다 |
|
||||
| 완료 기준 | 11초 걸리는 resolver를 가진 systemTest 쿼리가 10초 근처에서 `REQUEST_TIMEOUT`으로 끝난다 |
|
||||
| 검증 방법 | systemTest에 느린 resolver 케이스 하나(주입 시계 대신 짧은 `maxExecutionTime` 설정) |
|
||||
|
||||
### 03-03 N+1을 막는 길이 adopter 기억에만 있다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 4, 5, 14, 20, 21 |
|
||||
| 근거 | 플랫폼 batch 보호(chunk·deadline·tenant scope)는 `runtime/GraphQlBatchLoaderRegistrar.java:58-82`로 **명시 등록한** loader에만 붙는다. Spring 표준 `@BatchMapping`이나 per-parent `@SchemaMapping`은 이 경로를 거치지 않는다. 템플릿에는 feature GraphQL 예시가 없고(`graphql/README.md` 「아직 구현하지 않은 범위」), README는 registrar 사용법을 한 줄도 적지 않는다. 비용 카탈로그는 기본이 비어 있어(`GraphQlExecutionChainConfiguration` `GraphQlCostCatalog.of()`) 모든 필드가 같은 가중치 10이다. `EXTERNAL_PER_OBJECT(20)`과 `BATCHED_RELATION(3)` 구분은 adopter가 등록해야만 의미가 있다 |
|
||||
| 발생 조건 | adopter가 list 부모 아래 자식 필드를 일반 `@SchemaMapping`으로 구현 |
|
||||
| 영향 | 부모 N개마다 하위 호출 N번. 03-01과 겹치면 점수도 낮게 나와 거부되지 않는다 |
|
||||
| 심각도·우선순위 | Medium · P2 |
|
||||
| 통제 수준 | M2(registrar 경로는 `GraphQlBatchLoaderRegistrationTest`로 50 parent → 3 호출 확인), 그 밖 경로 M0 |
|
||||
| 결정의 근거 | 현재 선택: 플랫폼은 feature-agnostic이고 resolver를 모른다(사실, `CLAUDE.md`). 대안 (a) 문서·예시만 추가, (b) graphql-java instrumentation으로 같은 필드의 per-parent fetch 횟수를 세어 임계값 넘으면 WARN/metric, (c) 카탈로그 미등록 list 자식 필드를 기동 때 경고. 고른 방향: (a)+(b). (c)는 스키마 전체를 adopter가 등록해야 해서 비용 대비 효과가 작다. 재검토 조건: sample에 GraphQL feature가 들어오면 그 예시가 (a)를 대신한다 |
|
||||
| 최소 개선 방향 | README에 "자식 필드는 `GraphQlBatchLoaderRegistrar.register`로" 조립 예와 `@BatchMapping`과의 차이(플랫폼 budget 미적용)를 적고, 요청당 같은 좌표 fetch 횟수 metric을 추가 |
|
||||
| 완료 기준 | README 예시가 컴파일되는 테스트로 고정되고, per-parent fetch가 임계값을 넘는 systemTest에서 WARN/metric이 관찰된다 |
|
||||
| 검증 방법 | systemTest에 list 부모 + 일반 `@SchemaMapping` 자식 쿼리 하나 |
|
||||
|
||||
### 03-04 `GraphQlDataLoaderRequestRegistry`는 도달 불가인데 README가 요청 스코프 장치로 설명한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(갈라진 중복 복사본) |
|
||||
| 관련 관점 | 4, 9, 22, 27 |
|
||||
| 근거 | `dataloader/GraphQlDataLoaderFactory.java:37` `newRequestRegistry()`의 호출자는 테스트 하나(`GraphQlDataLoaderRequestRegistryTest.java:84`)뿐. 실제 요청 스코프는 Spring이 실행마다 새로 만드는 `DataLoaderRegistry`다(`GraphQlBatchLoaderRegistrar.java:19-23,48-50` Javadoc이 스스로 "아무것도 연결하지 않던 registry"라고 적음). 그런데 `graphql/README.md:204-208`은 이 registry가 요청마다 새로 만들어져 tenant 누출을 막는다고 설명한다 |
|
||||
| 영향 | 읽는 사람이 죽은 타입을 보호 장치로 믿는다. public 타입이라 API surface에도 남는다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 결정의 근거 | 적용 제외 — 두 번째 경로가 이미 대체된 상태라 비교할 선택이 없다 |
|
||||
| 단순화의 보존 조건 | `GraphQlBatchLoaderRegistrar`의 요청 스코프(실행마다 새 `DataLoaderRegistry`)와 `GraphQlBatchContext.cacheScope()` 지문 동작은 유지 |
|
||||
| 최소 개선 방향 | `GraphQlDataLoaderRequestRegistry`와 `newRequestRegistry()` 삭제, API surface 재승인, README 절을 registrar 기준으로 다시 쓴다 |
|
||||
| 완료 기준 | main·test grep 0건, `verifyGraphQlApiSurface` 통과 |
|
||||
| 검증 방법 | `:adapter:inbound:graphql:check` |
|
||||
|
||||
### 03-05 batch loader가 플랫폼 context 없이 불리면 `REQUEST_TIMEOUT`으로 나간다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6, 8, 17 |
|
||||
| 근거 | `runtime/GraphQlBatchLoaderRegistrar.java:73-76` context가 없으면 `GraphQlBatchTimeoutException` → mapper가 `REQUEST_TIMEOUT`/TIMEOUT(J-4a 매핑). 원인은 interceptor 미배선 같은 조립 오류인데 클라이언트·운영자는 시간 초과로 본다. 같은 조립 오류를 instrumentation은 WARN과 `PLATFORM_CONTEXT`로 따로 다룬다(P8-new-2) |
|
||||
| 영향 | 잘못 조립된 배포가 "느리다"로 오진된다. retryable 시간 초과로 보이면 클라이언트가 재시도한다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 결정의 근거 | 적용 제외 — 이미 있는 `PLATFORM_CONTEXT` 처리와 맞추는 일 |
|
||||
| 최소 개선 방향 | 전용 플랫폼 거부(예: `GraphQlPlatformContextMissingException`, INTERNAL + WARN 한 번)로 바꾼다 |
|
||||
| 완료 기준·검증 | context 없는 batch 호출 테스트가 `INTERNAL_ERROR`와 WARN 한 줄을 단언 |
|
||||
|
||||
### 03-06 WebSocket 연결 수·구독 수·연결 수명 상한이 없고, STOMP 전송 한도가 코드에 드러나지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 5, 6, 13, 14, 15, 19 |
|
||||
| 근거 | (1) STOMP: `stomp/WebSocketConfig.java:62-68`은 `configureWebSocketTransport`를 두지 않아 메시지 크기 64 KiB·send buffer 512 KiB·send time 10초·첫 메시지 60초가 Spring 기본값으로만 정해진다. 노드·principal당 연결 수 상한이 없다. (2) 구독 수: `WebSocketInboundAuthorizationInterceptor.java:34-36`은 destination만 보고 개수를 세지 않는다. Spring `SimpleBrokerMessageHandler`(7.0.9 소스 `:397-402`)는 세션 하나의 subscription id마다 메시지를 한 번씩 보낸다. 같은 `/topic/events`를 id만 바꿔 N번 SUBSCRIBE하면 broadcast 한 건이 그 세션에 N번 나가고, 구독 registry가 N만큼 커진다. (3) 라이브러리 handler: `servlet/PlatformWebSocketHandler.java:110` `openConnections()`는 세기만 하고 거부하지 않는다. `README.md` 「서비스가 챙길 것」은 인증·origin·크기·idle만 적고 연결 수는 적지 않는다. (4) 연결 수명: 인증은 handshake 한 번이고 토큰 만료·폐기 뒤에도 연결이 유지된다. 이 한계도 문서에 없다 |
|
||||
| 발생 조건 | 인증된 사용자 한 명(또는 탈취된 토큰)이 연결을 많이 열거나 SUBSCRIBE를 반복 |
|
||||
| 영향 | 노드 메모리·broker 채널 큐(기본 10,000)를 한 사용자가 채운다. broker 큐가 차면 다른 사용자의 live event가 drop된다(R1 best-effort라 오류 없이) |
|
||||
| 심각도·우선순위 | Medium · P2. opt-in이고 인증된 사용자만 가능 |
|
||||
| 통제 수준 | destination allowlist M3(변이 2로 확인). 연결·구독 수 M0 |
|
||||
| 결정의 근거 | 현재: 노드 내 simple broker, 연결 관리는 컨테이너·프록시 몫(README). 대안 (a) 문서로만 "프록시에서 연결 수 제한", (b) STOMP inbound interceptor에서 세션당 구독 수 1개(이 채널은 destination이 하나뿐)와 노드 연결 수 상한을 설정 키로, (c) principal별 연결 수 제한(분산 카운터 필요). 고른 방향: (b) — destination이 하나뿐이라 "세션당 구독 1"은 비용이 거의 없고, 노드 상한은 지역 카운터로 충분. (c)는 다중 노드에서 Redis가 필요해 이 leaf 범위를 넘으므로 문서로 남긴다. 재검토 조건: broker relay·다중 노드 전달을 도입할 때 |
|
||||
| 최소 개선 방향 | `configureWebSocketTransport`로 Spring 기본값을 명시 설정 키로 꺼내고, 세션당 중복 SUBSCRIBE 거부, 노드 연결 상한(`app.websocket.max-connections`) 추가. 라이브러리 handler는 생성자에 연결 상한을 받거나 README에 필수 항목으로 적는다 |
|
||||
| 완료 기준 | 같은 세션의 두 번째 SUBSCRIBE가 ERROR 프레임으로 거부되고, 상한+1번째 연결이 거부되는 systemTest |
|
||||
| 검증 방법 | `WebSocketBoundaryQualificationTest`에 두 케이스 |
|
||||
|
||||
### 03-07 `SerializedOutboundWriter`의 offer와 close가 겹치면 노드 버퍼 예산이 영구히 샌다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 1, 6, 12, 14 |
|
||||
| 근거 | `outbound/SerializedOutboundWriter.java:86`에서 `closed`를 본 뒤 `:93` queue lock을 잡기 전에 `close()`(`:179-192`)가 끼어들면, close가 빈 큐를 비운 다음 offer가 메시지를 넣고 `GlobalBufferBudget`에 바이트를 예약한다. 이어지는 `drain()`(`:112`)은 `closed`라 아무것도 쓰지 않는다. writer는 handler map에서 이미 빠졌으므로 그 예약을 돌려줄 주체가 없다. 임시 테스트(queue lock을 잡고 producer를 그 앞에 세운 뒤 close)로 `leakedGlobalBytes=500` 재현 |
|
||||
| 발생 조건 | 응답 enqueue(`PlatformWebSocketHandler.writeReply`)와 연결 종료(`afterConnectionClosed`·`stop`)가 다른 스레드에서 동시에. 연결이 많고 끊김이 잦을수록 누적 |
|
||||
| 영향 | 노드 예산이 조금씩 줄어 결국 모든 연결의 GUARANTEED 응답이 1013으로 닫힌다. 코드 주석(`PlatformWebSocketHandler.java:94-96`)이 막는다고 적은 바로 그 누수다. 재시작 전까지 회복되지 않는다 |
|
||||
| 심각도·우선순위 | Medium · P2. 라이브러리형이라 조립한 서비스에만 해당 |
|
||||
| 통제 수준 | M2(정상 경로), 경합 경로 M0 |
|
||||
| 결정의 근거 | 적용 제외 — 동시성 결함 수정 |
|
||||
| 최소 개선 방향 | `queue.offer`를 queue lock 안에서 `closed`를 다시 확인한 뒤에만 하고, 닫힌 뒤면 `CONNECTION_MUST_CLOSE` 반환. 또는 `close()`의 `discardAll`을 offer와 같은 lock 아래 마지막 단계로 두고 offer도 lock 안에서 closed를 본다 |
|
||||
| 완료 기준 | 위 경합 테스트에서 `global.buffered() == 0` |
|
||||
| 검증 방법 | 결정적 경합 테스트를 `SerializedOutboundWriterTest`에 추가(테스트용 hook 대신 queue를 감싼 latch fake로) |
|
||||
|
||||
### 03-08 `PlatformWebSocketHandler.stop()` 뒤에 들어온 연결은 1001을 받지 못한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6, 7, 18, 28 |
|
||||
| 근거 | `servlet/PlatformWebSocketHandler.java:63-71` `afterConnectionEstablished`가 `running`을 보지 않는다. `stop()`(`:133-148`)은 그 시점의 세션만 닫는다. handler 단계(`DEFAULT_PHASE`)와 web server graceful 단계(`DEFAULT_PHASE - 1024`) 사이에 서버는 아직 upgrade를 받는다. 임시 테스트: `stop()` 뒤 연결 → `openAfterStop=1`, `close` 호출 0회 |
|
||||
| 발생 조건 | 롤링 재시작. 1001을 받은 클라이언트가 바로 재접속하고, 로드밸런서 endpoint 제거가 늦어 같은 pod로 다시 붙는 경우 |
|
||||
| 영향 | 그 연결은 서버 종료 때 1006으로 끊긴다. stop()이 막으려던 "공격적 재접속"이 바로 그 창에서 생긴다 |
|
||||
| 심각도·우선순위 | Medium · P2 |
|
||||
| 결정의 근거 | 적용 제외 — 이미 정한 종료 계약(1001)의 빈틈 |
|
||||
| 최소 개선 방향 | `afterConnectionEstablished`에서 `!running`이면 즉시 1001(또는 1012)로 닫는다 |
|
||||
| 완료 기준 | stop 뒤 연결이 즉시 1001로 닫히는 단위 테스트, `TomcatWebSocketShutdownIT`에 "stop 직후 재접속" 케이스 |
|
||||
| 검증 방법 | `PlatformWebSocketHandlerTest`, systemTest |
|
||||
|
||||
### 03-09 gRPC 어댑터 서버가 io.grpc 기본값으로 뜬다 — deadline·동시 호출·executor·메시지 크기 상한이 없고, 플랫폼 한도는 testkit 서버에만 적용된다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 5, 6, 13, 14, 19, 23 |
|
||||
| 근거 | `adapter/inbound/grpc/.../GrpcServerRunner.java:75` `NettyServerBuilder.forAddress(...)`에 `maxInboundMessageSize`, `maxConcurrentCallsPerConnection`, `executor`, keepalive·`maxConnectionAge` 설정이 없다. io.grpc 기본은 메시지 4 MiB, 연결당 동시 호출 무제한, 스레드 수 제한 없는 cached executor다. 서버 쪽 기본 deadline(클라이언트가 deadline 없이 부른 호출을 끊는 장치)도 없다. 플랫폼은 `GrpcTransportLimits`(1 MiB/8 KiB), `GrpcServerProfile`, `GrpcAdmissionController`를 갖지만 이를 `NettyServerBuilder`에 적용하는 코드는 `grpc-testkit/.../netty/GrpcNettyTestServer.java:69-70` 하나뿐이고, starter(`GrpcPlatformAutoConfiguration`)는 profile bean만 만들고 서버를 만들지 않는다. 종료는 `stop()`(`:112-130`)이 health를 NOT_SERVING으로 바꾸자마자 `shutdown()`해 LB가 상태를 볼 시간이 없다 |
|
||||
| 발생 조건 | adopter가 어댑터로 feature 서비스를 노출하고 호출이 몰릴 때. 현재 P1은 loopback 전용이라 같은 Pod sidecar 정도만 해당 |
|
||||
| 영향 | 느린 handler가 스레드를 무한정 늘린다. Netty lane이 인증한 한도(1 MiB 등)는 실제 production 서버와 다른 서버에 대한 증거다 |
|
||||
| 심각도·우선순위 | Medium · P2. loopback 제한이 노출을 줄인다. TLS·외부 bind(P2)를 열기 전에는 해결해야 한다 |
|
||||
| 통제 수준 | 어댑터 M0, 플랫폼 M2(testkit 한정) |
|
||||
| 결정의 근거 | 현재: 두 스택 공존은 X1-#10·techlead 11-K6에서 의도로 수용됐다(다시 열지 않는다). 대안 (a) 어댑터가 `GrpcTransportLimits`와 같은 값을 자기 `GrpcServerSettings`로 노출해 builder에 설정, (b) 어댑터가 플랫폼 `GrpcServerProfile`을 받는다(registry edge 추가 = "배선은 별도 결정"), (c) 현상 유지 + README에 기본값 명시. 고른 방향: (a). 두 스택 분리 결정을 건드리지 않고 기본값을 코드에 드러낸다. (b)는 소유자가 플랫폼 배선을 결정할 때 다시 본다 |
|
||||
| 최소 개선 방향 | `GrpcServerSettings`에 `maxInboundMessageBytes`(1 MiB), `maxConcurrentCallsPerConnection`, bounded executor 크기, 기본 deadline을 두고 builder에 적용. stop에 짧은 drain 대기(`shutdownGraceSeconds` 안에서) |
|
||||
| 완료 기준 | `GrpcP1BoundaryWireTest`에 1 MiB 초과 메시지 `RESOURCE_EXHAUSTED`, deadline 없는 느린 호출이 기본 deadline에 `DEADLINE_EXCEEDED` 케이스 |
|
||||
| 검증 방법 | `:adapter:inbound:grpc:grpcTransportQualificationTest` |
|
||||
|
||||
### 03-10 operation ledger의 `IN_PROGRESS` claim에 만료·회수가 없다 — 소유자가 죽으면 그 key는 영구히 막힌다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 1, 6, 11, 12, 28 |
|
||||
| 근거 | `grpc-runtime/.../idempotency/GrpcIdempotencyInterceptor.java:118-121`: claim이 `IN_PROGRESS`면 `waitAndPoll` 또는 `rejectInProgress`. 만료 판단이 없다. `GrpcOperationLedger` port와 `JpaGrpcOperationLedger`에 stale claim 회수 메서드가 없다. `V001__create_grpc_operation_ledger.sql:35-37`은 "owner가 죽은 IN_PROGRESS 행을 찾아 release하기 위한 인덱스"라고 적지만 그 회수 코드는 main 어디에도 없다. COMMITTED 행 보존 기간·정리도 없다 |
|
||||
| 발생 조건 | claim 뒤 commit/fail 전에 프로세스가 죽거나 트랜잭션 밖에서 claim이 커밋된 경우(`tryInsertClaim`은 `@Transactional`이라 호출자 트랜잭션이 없으면 즉시 커밋) |
|
||||
| 영향 | 같은 key의 재시도가 영원히 대기하거나 거부된다. 클라이언트가 key를 바꾸면 중복 실행 방지가 깨진다. 테이블은 끝없이 자란다 |
|
||||
| 심각도·우선순위 | High · P1(ledger 채택 전 차단). 현재는 어떤 서버 경로도 이 판단 함수를 쓰지 않아(03-11) 노출은 없다. 채택하는 순간 pod 재시작 한 번으로 발생하는 일반 장애다 |
|
||||
| 확실성 | E1(코드 경로 확인). PG lane 18건은 claim 원자성만 다루고 stale claim 케이스는 없다 |
|
||||
| 통제 수준 | claim 유일성 M4(DB 제약 + PG lane E3). stale 회수 M0 |
|
||||
| 결정의 근거 | 현재: claim이 소유를 정하는 lease 없는 lock이다. 대안 (a) `claimed_at` + TTL로 stale `IN_PROGRESS`를 조건부 UPDATE로 재claim(`tryReclaimStale`, 기존 `tryReclaimFailed`와 같은 모양), (b) owner token + heartbeat lease(outbox lease와 같은 방식), (c) stale 행을 지우는 sweeper job. 고른 방향: (a). 인덱스가 이미 있고 SQL 한 문장으로 끝나며 회수 시 "결과 불명"을 `GrpcCompletionReconciler`로 넘길 수 있다. (b)는 장시간 작업에만 필요하다. 재검토 조건: 처리 시간이 TTL보다 길 수 있는 method가 생기면 (b) |
|
||||
| 최소 개선 방향 | port에 `reclaimStale(identity, fingerprint, olderThan, now)` 추가, JPA는 `UPDATE … WHERE state='IN_PROGRESS' AND claimed_at < :cutoff`, interceptor가 stale이면 재claim. 보존 기간 정리 쿼리와 문서 |
|
||||
| 완료 기준 | 계약 테스트 `GrpcOperationLedgerContract`에 "TTL이 지난 IN_PROGRESS는 같은 요청이 한 번만 재claim" 추가, fake와 JPA(PG lane) 모두 통과 |
|
||||
| 검증 방법 | `-p optional-platforms :grpc:grpc-operation-ledger-jpa:integrationTest`, `grpc-core-api:test` |
|
||||
|
||||
### 03-11 `app.grpc.platform.operation-ledger-enabled`는 검증만 통과시키고 실제로 key를 처리하는 코드가 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(설정 키가 하지 않는 일을 약속) |
|
||||
| 관련 관점 | 5, 17, 19, 21 |
|
||||
| 근거 | `grpc-spring-boot-starter/.../GrpcPlatformProperties.java:53` 플래그, `GrpcPlatformStartupValidator.java:149-155` "key would be accepted and never honoured"를 막는 검사. 하지만 starter(`GrpcPlatformAutoConfiguration`)는 ledger bean도 `GrpcIdempotencyInterceptor`도 만들지 않고, `GrpcIdempotencyInterceptor`의 호출자는 테스트(`GrpcIdempotencyInterceptorTest`)뿐이다. 플래그를 `true`로 두면 검증은 통과하고 key는 여전히 처리되지 않는다. `adapter/inbound/websocket/CLAUDE.md` 「Forbidden」의 "하지 않는 동작에 대한 설정 키 금지"와 같은 원칙을 이 family는 어긴다 |
|
||||
| 영향 | 운영자가 멱등 처리가 켜졌다고 믿는다 |
|
||||
| 심각도·우선순위 | Medium · P2(optional build, 채택 시 문제) |
|
||||
| 결정의 근거 | 대안 (a) 플래그를 지우고 validator는 `GrpcOperationLedger` bean 존재로 판단, (b) 플래그가 true면 ledger bean + 서버 interceptor를 조립. 고른 방향: (a). 서버 interceptor 조립은 "플랫폼 배선은 별도 결정"(`src/grpc/CLAUDE.md`)에 속하므로, 그 전까지는 거짓 약속만 없앤다 |
|
||||
| 완료 기준 | 플래그 삭제, ledger bean이 없으면 `IDEMPOTENCY_KEY_REQUIRED` method가 기동 거부되는 context test |
|
||||
| 검증 방법 | `GrpcPlatformAutoConfigurationContextTest` |
|
||||
|
||||
### 03-12 ledger PG lane은 main push·nightly에서만 돌고 PR·릴리스 게이트에 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(게이트 범위) |
|
||||
| 관련 관점 | 10, 18, 21 |
|
||||
| 근거 | `.github/workflows/integration-main.yml:329-345` job `grpc-optional-platform-integration`이 `-p optional-platforms integrationCheck`를 push(main)와 nightly cron에 실행한다. PR 게이트(`ci-quality-gates.yml:66-73`)는 `-p optional-platforms ci`만, 릴리스(`release.yml:128-147` `grpc-stable-release-gate`)는 testkit lane 3개만 부른다. integration-main은 머지 뒤 알리는 단계라 tag 릴리스가 이 lane 결과를 보지 않는다. 오늘 로컬 실행은 18건 통과 |
|
||||
| 영향 | ledger SQL을 깨는 변경이 PR에서 통과하고, main이 빨간 상태로 tag가 나갈 수 있다 |
|
||||
| 심각도·우선순위 | Low · P3. 플랫폼이 아직 채택되지 않았고, 다음 main push에서 드러난다 |
|
||||
| 결정의 근거 | 적용 제외 — 기존 단계 설계(container lane은 stage 2) 안에서 릴리스 needs 한 줄 문제 |
|
||||
| 최소 개선 방향 | `release.yml` gRPC gate에 `-p optional-platforms integrationCheck` 추가(PR 예산은 그대로) |
|
||||
| 완료 기준·검증 | `release.yml` needs와 실행 목록에 포함, 릴리스 dry-run에서 lane 실행 확인 |
|
||||
|
||||
## 4. 31절 시나리오 추적
|
||||
|
||||
### 4.1 큰 입력·목록 조회 — GraphQL `POST /graphql`
|
||||
|
||||
```text
|
||||
HTTP body ─> GraphQlRequestBodyLimitFilter(raw cap, 413)
|
||||
─> Spring GraphQL decode ─> GraphQlPlatformWebInterceptor
|
||||
├─ document bytes ≤ 16 KiB, variables bytes ≤ 64 KiB, JSON 구조·extension allowlist
|
||||
├─ principal resolver → GraphQlRequestContext(deadline = now + 10s)
|
||||
─> parse/validate(BoundedPreparsedDocumentProvider 캐시)
|
||||
─> GraphQlPlatformInstrumentation → GraphQlExecutionChain
|
||||
├─ OperationSelection(named 필요 여부)
|
||||
├─ DocumentAuthorization(좌표 규칙, fragment 1회 전개)
|
||||
└─ CostBudget: deadline 1회 확인 → 깊이·필드·alias·fragment 상한 → 복잡도 점수
|
||||
─> resolver 실행 (시간 상한 없음)
|
||||
─> 오류는 GraphQlWireErrorMapper 하나
|
||||
```
|
||||
|
||||
| 항목 | 결과 |
|
||||
| --- | --- |
|
||||
| 입력 신뢰 수준 | 신뢰하지 않음. 바이트·구조 상한은 parse 전에 걸린다(M3) |
|
||||
| 인가 위치 | 문서 단위 좌표 인가는 실행 전(`GraphQlDocumentAuthorizationHandler`). 객체 단위 인가는 `modelled`(요청 경로 없음) — adopter resolver 책임 |
|
||||
| 규칙 소유 | 상한 값은 `GraphQlClientPolicy` 하나 |
|
||||
| 트랜잭션 | 이 leaf는 열지 않는다. use case 몫 |
|
||||
| 외부 부작용 | 없음(health 표면만) |
|
||||
| 성공의 의미 | 상한·인가·예산을 통과하고 resolver가 응답 |
|
||||
| 오류 변환 | 플랫폼 거부 → `ApiErrorCarrier` → 등록 매핑 → `IllegalArgumentException`=`BAD_PARAMETER` → 나머지 `INTERNAL_ERROR` + ERROR 로그(executionId) |
|
||||
| 진단 정보 | executionId, MDC requestId, operation name은 allowlist일 때만 metric label |
|
||||
| 판정 | 깊이·alias·문서 크기는 막힌다(변이 1). **목록 크기는 막히지 않는다(03-01). 실행 시간도 막히지 않는다(03-02)** |
|
||||
|
||||
### 4.2 종료·재시작 — WebSocket
|
||||
|
||||
| 경로 | 결과 |
|
||||
| --- | --- |
|
||||
| STOMP 채널 | Spring `SubProtocolWebSocketHandler`의 lifecycle stop이 세션을 GOING_AWAY로 닫는다(Spring 동작, 이 leaf 테스트 없음). broker 큐에 남은 live event는 버려진다(R1 문서화) |
|
||||
| 라이브러리 handler | context close → `stop()`(DEFAULT_PHASE)이 열린 연결에 1001 → web server graceful 종료. `TomcatWebSocketShutdownIT`로 E2. stop 뒤 새 연결은 빠진다(03-08) |
|
||||
| gRPC 어댑터 | `GrpcServerRunner.stop()`이 health terminal → `shutdown()` → `shutdownGraceSeconds`(5초) 대기 → `shutdownNow()`. drain 대기 없음(03-09) |
|
||||
|
||||
### 4.3 중복·동시 요청 — gRPC operation ledger
|
||||
|
||||
| 항목 | 결과 |
|
||||
| --- | --- |
|
||||
| 요청 식별 | `GrpcOperationIdentity`(caller 지문, method, key 해시). 컬럼 폭 검증(N-11b) |
|
||||
| DB 제약 | PK `storage_key` + UNIQUE(caller, method, key hash). `INSERT … ON CONFLICT DO NOTHING`의 affected row로 승자 결정. PG lane `concurrentClaimsHaveExactlyOneOwner` 통과(E3, 로컬) |
|
||||
| 실패 뒤 재시도 | FAILED_TERMINAL은 같은 fingerprint 한 번만 재claim(`tryReclaimFailed`) |
|
||||
| 결과 불명 | 소유자가 죽은 IN_PROGRESS는 회수 경로가 없다(03-10) |
|
||||
| 실제 요청 경로 | 없음. 판단 함수만 있고 서버 interceptor가 없다(03-11) |
|
||||
|
||||
### 4.4 외부 응답 지연 — gRPC deadline
|
||||
|
||||
| 항목 | 결과 |
|
||||
| --- | --- |
|
||||
| 플랫폼 | `GrpcDeadlineBudget`이 단조 시계 절대 deadline으로 바뀜(N-2 해결). 하위 호출 budget 계산 라이브러리 |
|
||||
| 어댑터 | 클라이언트 deadline은 io.grpc가 취소로 전달하지만, deadline 없는 호출에 서버 기본값이 없고 executor도 무제한(03-09) |
|
||||
|
||||
### 적용 제외
|
||||
|
||||
| 시나리오 | 사유 |
|
||||
| --- | --- |
|
||||
| 정상 쓰기 요청 | 세 어댑터 모두 feature mutation이 없다(health 표면만) |
|
||||
| DB 오류·경쟁 | ledger 외 DB 접근 없음. ledger는 4.3에서 다룸 |
|
||||
| 메시지 중복·역순 | 영역 10(messaging) |
|
||||
| 신·구 버전 공존 | gRPC proto 호환은 Buf breaking(CI job `grpc-proto-buf`)이 맡는다. 이번에 미실행 — 다른 영역(13 빌드·CI)과 겹침 |
|
||||
| 여러 서버의 작업 실행 | 이 영역에 scheduler 없음 |
|
||||
| 세션·토큰 갱신 경쟁 | 인증은 HTTP 계층·adopter resolver 몫. WebSocket 연결 수명 동안 토큰 재확인이 없다는 점만 03-06에 기록 |
|
||||
| 다른 사용자 리소스 접근 | GraphQL 객체 인가는 `modelled`(요청 경로 없음), 결정 35로 보류. feature resolver가 없어 따라갈 요청이 없다 |
|
||||
| 선택 어댑터 제거 | `conditionalTransportQualification`·`conditionalTransportBuildContractTest`가 mainCheck에서 통과(오늘). 영역 12(bootstrap)와 겹쳐 상세는 생략 |
|
||||
|
||||
## 5. 41절 설계 선택 검토
|
||||
|
||||
### 5.1 GraphQL 비용 제한을 플랫폼 자체 scorer로 둔 것
|
||||
|
||||
1. **필요한 것**: 실행 전에 비싼 문서를 거절. 대상은 adopter가 나중에 붙일 임의 스키마.
|
||||
2. **지킬 성질**: 거절 판단이 실제 작업량의 상한이어야 한다. 특히 list 크기에 비례해야 한다.
|
||||
3. **현재 보장**: 깊이·필드·alias·fragment 상한은 지켜진다(변이 1). 복잡도는 페이지 인자가 값으로 보일 때만 곱한다. list 기본 배수·변수 기본값은 반영하지 않는다(03-01, E2).
|
||||
4. **대안**: (a) graphql-java `MaxQueryComplexityInstrumentation` + `FieldComplexityCalculator`, (b) 현재 scorer를 고친다, (c) 깊이·필드 상한만 남기고 복잡도는 버린다.
|
||||
5. **얻고 지불하는 것**: (a)는 graphql-java가 coerced 변수·기본값을 계산해 준다. 대신 플랫폼의 페이지 상한 거부·카탈로그 가중치를 calculator로 다시 써야 하고, 테스트가 바뀐다. (b)는 코드 변경이 작지만 변수 coercion을 직접 맞춰야 한다. (c)는 가장 단순하지만 `first: 100`을 12단 중첩하는 문서를 막지 못한다.
|
||||
6. **현재 조건의 선택**: (b). 기존 카탈로그·거부 코드와 테스트를 유지하면서 구멍만 막는다. 변수는 graphql-java `ValuesResolver`로 coercion하면 (a)의 장점을 가져온다.
|
||||
7. **바뀌는 조건**: adopter가 federation·persisted query처럼 graphql-java 표준 계측을 함께 쓰게 되면 (a)로 옮기는 편이 두 벌 유지를 줄인다.
|
||||
|
||||
### 5.2 gRPC를 두 스택(어댑터 서버 + vendored 플랫폼)으로 둔 것
|
||||
|
||||
1. **필요한 것**: 지금은 loopback unary 하나. 나중에 TLS·streaming·멱등성이 필요할 수 있다.
|
||||
2. **지킬 성질**: production 서버가 문서가 말하는 한도로 동작한다.
|
||||
3. **현재 보장**: 어댑터 서버는 io.grpc 기본값. 플랫폼 한도는 testkit 서버에만 적용(03-09). 멱등성은 판단 함수와 ledger만 있고 서버 경로가 없다(03-11).
|
||||
4. **대안**: (a) 현상 유지 + 어댑터에 한도 명시, (b) 어댑터가 플랫폼 `grpc-runtime`을 받는다(registry edge 추가), (c) 플랫폼을 템플릿에서 빼고 필요할 때 가져온다.
|
||||
5. **얻고 지불하는 것**: (a)는 작고 두 스택 결정을 건드리지 않는다. 같은 한도 값을 두 곳이 갖는 중복은 남는다. (b)는 증거(Netty lane)가 production 서버를 가리키게 되지만 플랫폼 143개 파일이 어댑터 의존에 들어온다. (c)는 유지비를 없애지만 소유자가 만든 플랫폼을 버린다.
|
||||
6. **선택**: 소유자 결정(X1-#10 수용, "배선은 별도 결정")을 존중해 (a). 중복 값은 `GrpcTransportLimits` 값을 어댑터 문서에 인용해 두 곳이 같다는 사실을 테스트로 고정한다.
|
||||
7. **바뀌는 조건**: TLS·외부 bind(P2)를 열거나 streaming이 필요해지면 (b)를 다시 본다. 그때 03-10·03-11이 먼저 닫혀야 한다.
|
||||
|
||||
### 5.3 WebSocket live push를 simple broker + best-effort로 둔 것
|
||||
|
||||
1. **필요한 것**: 단일 노드에서 도메인 이벤트 알림.
|
||||
2. **지킬 성질**: 발행 스레드를 느리게 하지 않는다. 한 사용자가 다른 사용자의 수신을 막지 않는다.
|
||||
3. **현재 보장**: broker 채널 bounded executor(K-11b, 테스트 있음), 꽉 차면 drop. 구독·연결 수 상한이 없어 한 사용자가 큐를 채울 수 있다(03-06).
|
||||
4. **대안**: (a) 현상 + 세션당 구독 1·연결 상한, (b) broker relay(RabbitMQ·ActiveMQ), (c) SSE로 전환.
|
||||
5. **비용**: (a)는 interceptor 몇 줄. (b)는 운영 인프라 추가. (c)는 STOMP 클라이언트 계약을 깨고 servlet 스레드 점유 모델이 다르다.
|
||||
6. **선택**: (a). README가 이미 단일 노드 best-effort라고 선언했고, 그 범위 안에서 공정성만 막으면 된다.
|
||||
7. **바뀌는 조건**: 다중 노드 전달이나 재전송이 요구되면 (b).
|
||||
|
||||
## 6. 리팩토링 후보
|
||||
|
||||
| 대상 | 무엇을 왜 | 보존 조건 |
|
||||
| --- | --- | --- |
|
||||
| `GraphQlDataLoaderRequestRegistry` + `GraphQlDataLoaderFactory.newRequestRegistry()` | 도달 불가 중복 경로 삭제(03-04) | registrar 요청 스코프, `cacheScope()` 지문, API surface 재승인 |
|
||||
| `GraphQlTimeoutPolicy` | main 호출자 0. 03-02에서 쓰거나 삭제 | `REQUEST_TIMEOUT` wire code 유지 |
|
||||
| `GraphQlPlatformWebInterceptor` 생성자 10개 | anonymous 3값을 record 하나로(S5-#14e) | 거부 순서·오류 코드·`GraphQlRequestStageErrorMappingTest` |
|
||||
| `TomcatWebSocketAbuseIT.shutdownClosesLiveConnections` | `TomcatWebSocketShutdownIT`와 중복, 시간 경계 flaky(P25-new-1). 삭제하거나 "close code만" 단언으로 축소 | 1001 단언은 ShutdownIT가 계속 가진다 |
|
||||
| `TomcatWebSocketAbuseIT` inline FQN 9곳 | import로 | 없음(형식만) |
|
||||
| `GrpcClientMessageDeduplicator` | 세션별 map으로 나눠 `endSession` O(1)(N-12a) | 중복 판정 결과, 세션 종료 후 outcome 미보존 |
|
||||
| gRPC 어댑터 `GrpcServerSettings` | 한도 값을 `GrpcTransportLimits`와 같은 이름·값으로(03-09) | `ignoreUnknownFields=false` 바인딩, loopback 강제 |
|
||||
|
||||
## 7. 기능 개발 패턴과 판단 지점 (매뉴얼 재료)
|
||||
|
||||
### 7.1 템플릿이 주는 틀
|
||||
|
||||
| 기능 | 주는 것 | 빠진 것 |
|
||||
| --- | --- | --- |
|
||||
| GraphQL 필드 추가 | `classpath:graphql/*.graphqls` 병합, `@Controller` 자동 바인딩, 플랫폼 상한·인가·비용·오류 매핑, `GraphQlBatchLoaderRegistrar`, 전송 경계 ArchUnit | feature 예시(sample에 GraphQL 없음), 목록 필드 비용 규약(03-01), DataLoader 조립 예(03-03), 실행 시간 상한(03-02) |
|
||||
| WebSocket 서버 push | `LiveEventProjector<T>` 하나 등록하면 broadcast, bounded 채널 | projector 예시(sample 0), 연결·구독 상한(03-06) |
|
||||
| WebSocket 요청/응답 | `PlatformWebSocketHandler` + budget, README 조립 예 | 연결 수 상한, stop 뒤 연결 처리(03-08) |
|
||||
| gRPC 서비스 | `@GrpcExposedService` + `GrpcAuthenticationPolicy` 하나, 오류 매핑, health | `.proto` 예시, 서버 한도(03-09), TLS(P2) |
|
||||
| gRPC 멱등 mutation | ledger 테이블·JPA 어댑터·판단 함수 | 서버 interceptor, stale claim 회수(03-10·03-11) |
|
||||
|
||||
### 7.2 개발자가 내려야 하는 판단
|
||||
|
||||
1. **어느 전송인가.** 요청/응답이면 web. 서버가 먼저 알려야 하면 STOMP 채널. 연결 하나에서 명령을 주고받으면 라이브러리 handler. 내부 서비스 간이면 gRPC(지금은 같은 Pod만).
|
||||
2. **GraphQL list 필드를 만들 때.** connection(`first`/`last`)으로 둘지 일반 list로 둘지 정한다. 지금 scorer는 인자가 값으로 보일 때만 곱한다. 03-01 수정 전까지는 모든 list에 `first` 인자를 필수(non-null)로 두는 것이 안전하다.
|
||||
3. **자식 필드를 어떻게 가져오나.** 부모가 list면 `GraphQlBatchLoaderRegistrar.register`로 batch loader를 쓴다. `@BatchMapping`은 플랫폼 chunk·deadline이 붙지 않는다.
|
||||
4. **비용 가중치.** 외부 호출이 있는 필드는 `GraphQlCostCatalog`에 `EXTERNAL_PER_OBJECT`로 등록한다. 등록하지 않으면 모두 10이다.
|
||||
5. **오류 코드.** product 오류는 `ApiErrorCode`를 가진 예외(`ApiErrorCarrier`)로 던진다. GraphQL 전용 코드는 `GraphQlErrorCode.platform`에 `GRAPHQL_` 접두로만.
|
||||
6. **WebSocket 연결 상한.** 프록시(Nginx `limit_conn`)에서 둘지 앱에서 둘지 정한다. 지금 앱에는 없다.
|
||||
7. **gRPC 멱등성.** `IDEMPOTENCY_KEY_REQUIRED` method는 03-10·03-11이 닫히기 전에는 application `IdempotencyExecutor`를 use case 안에서 쓰는 쪽이 안전하다(websocket `CLAUDE.md`와 같은 권고).
|
||||
8. **opt-in 절차.** `runtimeOnly` 한 줄 + registry edge + env key 등록 + `conditionalTransportQualification` 실행. 세 leaf `CLAUDE.md` 「Adopting」 절이 순서를 준다.
|
||||
|
||||
## 8. 28개 관점 판정표
|
||||
|
||||
기호: O 충족, P 부분, X 미충족, ? 미검증, - 적용 제외, > 다른 영역.
|
||||
|
||||
| # | 관점 | 판정 | 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | P | 대부분 정돈. 동시성 누수(03-07)·비용 계산 구멍(03-01) |
|
||||
| 2 | 구조적 성숙도 | P | inbound→outbound 금지·전송 경계 ArchUnit은 M3. gRPC 두 스택이 같은 한도를 따로 가진다(03-09) |
|
||||
| 3 | 변경 용이성 | P | GraphQL auto-config가 기능별 8개로 나뉨(S5-#7a). 비용 규칙을 바꾸려면 scorer·calculator·policy 세 곳을 같이 봐야 한다 |
|
||||
| 4 | 인지 부하 | P | 등급표·README가 잘 돼 있음. 죽은 registry를 장치로 설명(03-04), graphql 주석 32% |
|
||||
| 5 | 위험 가시성 | X | 실행 시간 상한(03-02)·ledger 플래그(03-11)·STOMP 전송 한도(03-06)가 코드에 없거나 약속과 다르다 |
|
||||
| 6 | 실패 성숙도 | P | 오류 매핑 단일화·마스킹+로그는 O. stale claim·종료 창·deadline 미강제 |
|
||||
| 7 | 운영 성숙도 | P | 1001 종료·health terminal 있음. gRPC drain 대기 없음 |
|
||||
| 8 | 디버깅 가능성 | P | executionId·requestId 연결 O. batch context 누락이 timeout으로 보임(03-05) |
|
||||
| 9 | 유지보수 성숙도 | P | 남은 W5 nit 다수(S5-#14d·#14e, K-12c, N-12) |
|
||||
| 10 | 테스트 성숙도 | P | 변이 2개 모두 잡힘. list 필드·scorer 단위 테스트 없음(03-01). shutdown 테스트 시간 경계 flaky(P25-new-1) |
|
||||
| 11 | 데이터 성숙도 | P | ledger DB 제약·마이그레이션 PG 검증 O. 보존·정리 없음(03-10) |
|
||||
| 12 | 동시성 성숙도 | P | claim 원자성 E3, gRPC admission·rotation 경합 수정(N-5). writer close 경합(03-07) |
|
||||
| 13 | 확장성 | X | 연결·구독 수 상한 없음(03-06), gRPC executor 무제한(03-09) |
|
||||
| 14 | 성능 성숙도 | P | 문서 캐시·bounded 채널 O. 비용 점수가 실제 작업과 비례하지 않음(03-01). 실부하 증거 없음 |
|
||||
| 15 | 보안 성숙도 | P | handshake principal·origin allowlist·introspection off·좌표 인가 O. 목록 크기 DoS(03-01), 구독 증폭(03-06) |
|
||||
| 16 | 의존성 성숙도 | O | grpc BOM·lockfile, 플랫폼 별도 build, registry edge 최소 |
|
||||
| 17 | API / Contract 성숙도 | P | wire 오류 코드 카탈로그·API surface 스냅샷 O. 설정 키가 약속만 함(03-11), README 설명 엇갈림(P15-new-4) |
|
||||
| 18 | 배포 성숙도 | P | build-time opt-in 명확. ledger lane이 릴리스 게이트 밖(03-12) |
|
||||
| 19 | 설정 성숙도 | P | `ignoreUnknownFields=false`, `@Validated`, 필수 deployment-mode O. 숨은 기본값(STOMP·gRPC) |
|
||||
| 20 | 개발자 경험 | P | 「Adopting」 절차 O. GraphQL·WebSocket feature 예시 없음 |
|
||||
| 21 | Guardrail 성숙도 | P | strict lane(no-skip)·전송 경계 ArchUnit·production 인가 정책 강제 O. 비용·deadline 가드 부재 |
|
||||
| 22 | 추상화 성숙도 | P | 판단 함수 + port 구조는 적절. 쓰이지 않는 `GraphQlTimeoutPolicy`·registry |
|
||||
| 23 | 일관성 | P | 오류 문구 shared 표 통일 O. 같은 한도가 두 gRPC 스택에 따로 |
|
||||
| 24 | 네이밍 / 의미 성숙도 | P | 대체로 명확. `operation-ledger-enabled`가 실제 의미와 다름 |
|
||||
| 25 | 조직 확장성 | - | 이 영역 단독으로 판단할 근거 없음(팀·소유 정보 없음) |
|
||||
| 26 | Ownership 성숙도 | P | leaf별 `CLAUDE.md`가 소유 규칙을 가짐. root family 표에 gRPC 행 없음(S7-lead-2) |
|
||||
| 27 | 삭제 가능성 | O | 세 어댑터 모두 한 줄 제거로 빠지고 `conditionalTransportQualification`이 확인(오늘 통과) |
|
||||
| 28 | 회복 가능성 | X | stale `IN_PROGRESS` 회수 불가(03-10), 예산 누수는 재시작 전 회복 불가(03-07) |
|
||||
|
||||
### 성능·테스트 시간 메모
|
||||
|
||||
오늘 게이트의 테스트 결과 XML(testsuite time 합, JVM·Spring 기동 시간 제외):
|
||||
|
||||
| lane | 건수 | 시간 |
|
||||
| --- | --- | --- |
|
||||
| websocket `test` / `systemTest` / `websocketJettyTest` / `websocketTransportQualificationTest` | 74 / 18 / 8 / 5 | 3.6초 / 1.8초 / 0.9초 / 1.9초 |
|
||||
| graphql `test` / `systemTest` / `graphqlStableTest` / `graphqlTransportQualificationTest` | 377 / 25 / 4 / 8 | 9.7초 / 2.1초 / 0.3초 / 1.9초 |
|
||||
| grpc 어댑터 `test` / `grpcTransportQualificationTest` | 48 / 20 | 2.7초 / 2.3초 |
|
||||
| ledger `integrationTest`(로컬) | 18 | 0.55초(+ container 기동) |
|
||||
|
||||
실행 시간은 과하지 않다. 비용은 기동 쪽에 있다(graphql systemTest가 random-port 서버를 띄움). 요청당 복잡도 계산 비용은 측정하지 않았다(scorer 방문 노드 상한 200,000이 상한).
|
||||
@@ -0,0 +1,480 @@
|
||||
# 04 Persistence — 성숙도 리뷰 (2026-11-01)
|
||||
|
||||
영역: `adapter:outbound:persistence-jpa`, `adapter:outbound:persistence-mongo`,
|
||||
`adapter:outbound:persistence-fileserver`, `adapter:outbound:persistence-notification`, Flyway 마이그레이션과 스키마.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 | `clean-architecture-backend-template`, Gradle 루트 `src/` |
|
||||
| 커밋 | `main` @ `01a8a2a70` (리뷰 후속 Wave 1–3 머지 직후). 작업 트리 깨끗함 |
|
||||
| 목적·지원 구성 | 템플릿(reference implementation). 파생 서비스가 복사해 쓴다. JPA·Mongo는 `runtimeOnly` 한 줄로 켜는 capability다. 다중 인스턴스를 전제로 한 장치(outbox lease fencing, `FOR UPDATE SKIP LOCKED` claim)가 있으므로 다중 인스턴스를 지원 구성으로 본다 |
|
||||
| 규모·운영 목표 | 문서에 합의된 수치 없음. 그래서 "대규모 운영 준비" 판정은 하지 않는다 |
|
||||
| 읽은 코드 | 네 leaf의 `src/main`(JPA 193개·Mongo 278개·notification 48개·fileserver 27개 파일)의 트랜잭션·예외 변환·엔티티·쿼리·claim 경로, `src/test`·`postgresqlIntegrationTest`·`testFixtures`의 관련 부분, 각 `build.gradle`, 루트 `src/build.gradle` lifecycle, `.github/workflows/*.yml`, `config/module-defaults/persistence-jpa.yml`, 마이그레이션 디렉터리 9곳, `docs/jpa/*.md`, ADR-JPA-003. sample의 WorkLog 영속 경로(참조 패턴으로서) |
|
||||
| 위임 조사 | Mongo leaf, notification·fileserver leaf는 읽기 전용 하위 조사로 나눠 읽었다. High로 올린 항목과 핵심 근거는 내가 코드를 다시 열어 확인했다 |
|
||||
| 실행한 명령 | 아래 표 |
|
||||
| 확인 못 한 것 | Mongo 컨테이너 lane(현재 커밋 미실행. 결과 XML은 09-28 것), JPA platform 태그 lane(`jpaPlatformContractTest` 등, 현재 커밋 미실행), 04-05의 실제 중복 처리 재현, 04-11의 실제 WriteConflict 재현, 쿼리 수 실측(04-09는 계산값) |
|
||||
| 이전 리뷰와 비교 | techlead `05`·`06`, followup-status E·F·S2 행과 persistence 관련 TEST·X1·S6·S7·P*·ORCH 행 |
|
||||
|
||||
실행한 명령 (모두 scratchpad worktree `wt-04`에서, `flock heavy.lock` 안에서 실행. 끝난 뒤 worktree 삭제):
|
||||
|
||||
| 명령 | 부하(uptime 1분) | 결과 |
|
||||
| --- | --- | --- |
|
||||
| `./gradlew :adapter:outbound:persistence-jpa:test` (+ 실험 테스트 1개 파일 추가) | 26.38 | 통과. 503개, 테스트 시간 합 8.6초, wall 2분 29초(컴파일 포함, 고부하) |
|
||||
| `./gradlew :adapter:outbound:persistence-jpa:postgresql{FileserverMetadata,FileserverReclamation,Idempotency,Migration}IntegrationTest --continue` | 14.03 | 4개 lane 모두 통과. 16/15/8/5개, 테스트 시간 4.9/0.6/4.5/8.1초, Gradle 56초(lock 대기 포함 wall 181초) |
|
||||
| `./gradlew :adapter:outbound:persistence-jpa:test --tests '*ScratchReview*'` | 7.92 | 실험 3개 통과(04-01·04-02·04-03 근거) |
|
||||
|
||||
게이트 결과(오케스트레이터 실행, `scratchpad/gates`): `ci rc=0`(434초). `mainCheck rc=1` — 원인은 objectstorage MinIO 이미지 pull 실패 2건이고 이 영역과 무관하다. 이 영역에서 `ci`가 돌린 것은 `persistence-jpa:test`(502개, 16.6초), `persistence-notification:test`(19개, 1.1초), `persistence-mongo:test`(79개, 6.1초)·`mongoStableContractTest`(465개, 6.1초)다. `persistence-fileserver:test`는 `NO-SOURCE`다. `mainCheck`에서 이 영역이 실제로 돌린 테스트는 `mongoDocumentContractTest`(2개)뿐이다. 실 DB lane은 두 게이트 어디에도 없다.
|
||||
|
||||
### 0.1 전제
|
||||
|
||||
| 전제 | 기록 |
|
||||
| --- | --- |
|
||||
| 사용 목적 | 사내 서비스 시작점 템플릿. 파생 서비스(tech-log-backend 등)가 복사한다 |
|
||||
| 지원 실행 형태 | 다중 인스턴스 서버(근거: outbox·durable operation·recipient lease의 fencing 설계) |
|
||||
| 데이터와 권한 | 알림 수신 거부·연락처(개인정보 해시), 파일 메타데이터·쿼터, 멱등성 기록 |
|
||||
| 의존 시스템 | PostgreSQL(주), H2(로컬 전용), MongoDB(선택, 소비자 0) |
|
||||
| 운영 목표 | 미정. 허용 지연·데이터 손실·복구 시간 수치 없음 |
|
||||
| 지원·비지원 | JPA: PostgreSQL만 운영 대상. Mongo: imperative만, outbox·멱등성·lock 미지원 |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
경로 약어: `PJ` = `src/adapter/outbound/persistence-jpa`, `PM` = `src/adapter/outbound/persistence-mongo`, `PN` = `src/adapter/outbound/persistence-notification/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform`, `PF` = `src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver`.
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| E-3c canonical append ownership 테스트 | 해결 | 테스트가 `PJ/src/test/.../outbox/jpa/JpaOutboxStoreTest.java:157-174`(append·claim·mark의 트랜잭션 없는 호출 거부)로 옮겨졌다 |
|
||||
| E-4c inbox 테스트가 운영 쿼리 복사본 실행 | 바뀜 | 이제 `@Query` 어노테이션에서 SQL을 읽어 실행한다(`PJ/src/postgresqlIntegrationTest/.../PostgreSqlInboxCutoffIntegrationTest.java:122-147`). 아직 adapter(`JpaNotificationInbox.markAllRead`)를 거치지 않는다. `'UNREAD'`는 fixture INSERT(`:165`)에만 남았다 |
|
||||
| E-5c README "aggregate당 최대 한 row" | 남음 | `PJ/README.md:255` 문장 그대로 |
|
||||
| E-6a tenant 규칙이 필드 이름 `tenantId`로만 판정 | 남음 | `PJ/src/testFixtures/.../testkit/arch/TenantScopedRepositoryPredicate.java:19,49-51` |
|
||||
| E-12 CLAUDE.md 벤더 표에 `55P03` 누락 | 남음 | `PJ/CLAUDE.md:273-279`에 없음. 코드는 `PJ/src/main/.../postgresql/PostgreSqlSqlStateErrorMapping.java:20`에서 매핑 |
|
||||
| F-1d security lane "injection" 과장 | 바뀜 | 단위 테스트에 `$ne`·`$gt` 거부가 생겼다(`PM/src/test/.../query/PolicyAwareMongoQueryBuilderTest.java:121-161`). lane 설명(`PM/build.gradle:209`)은 여전히 injection을 주장하지만 lane 테스트(`MongoSecurityIntegrationLaneTest.java:93-165`)에는 없다 |
|
||||
| F-5d CSFLE 테스트·호출자 없음 | 바뀜 | 테스트 5개 추가(`MongoCsfleClientFactoryTest.java:59-124`). leaf 밖 호출자는 0. README "테스트 없는 진입점"(`PM/README.md:165-167`)에 5개가 남음 |
|
||||
| F-9a inline FQN | 남음 | `PM/src/main/.../autoconfigure/MongoPlatformAutoConfiguration.java` 37줄(:62, :69, :129-166 외). 규칙 `PM/CLAUDE.md:70` |
|
||||
| S2-#8b "두 조립 루트가 adapter를 스캔" 서술 | 남음 | `PJ/src/test/.../CandidateAdapterCompositionTest.java:6-14`, `PJ/src/main/.../idempotency/postgresql/PostgreSqlIdempotencyStore.java:52` |
|
||||
| S2-#12 이력 서술 Javadoc | 남음 | 네 문구("used to" 등) JPA main 16줄, Mongo main 41개 파일 51회 |
|
||||
| S2-#14a JPA CLAUDE.md의 "NoSQL은 미래 모듈"·MapStruct 절 | 남음 | `PJ/CLAUDE.md:17-19, 317-340` |
|
||||
| S2-#14b API surface에 옮겨간 타입 | 해결 | `docs/architecture/jpa-adopter-api-surface.txt`에 `FileserverSchemaActivation` 없음 |
|
||||
| S2-lead-2 / X1-#3b 멱등성 공통 계약 | 남음 | testFixtures 어디에도 `IdempotencyStoreContract` 없음 |
|
||||
| TEST-F-2a claim 순서 단언 없음 | 남음 | `PJ/src/postgresqlIntegrationTest/.../platform/PostgreSqlWorkClaimContractTest.java:78-86` `isNotEmpty()`만 |
|
||||
| TEST-FAKE-DeliveryProjectionStorePort | 남음 | fake 3개, 공통 계약 없음 |
|
||||
| S7-lead-4 / X1-#6d recipient lease 공통 fencing 계약 | 남음 | PG IT 하나뿐(`PostgreSqlRecipientLeaseFencingIntegrationTest`) |
|
||||
| ORCH-new-2 `NotificationPayloadAtRestContractTest` inputs 미선언 | 남음 | `src/adapter/outbound/notification/src/test/.../NotificationPayloadAtRestContractTest.java:155-163`가 다른 leaf의 V10 SQL을 읽는데 `notification/build.gradle`에 `inputs` 없음 |
|
||||
| P4-new-1 fileserver migration 불변성 테스트 없음 | 해결 | `PJ/src/test/.../migration/AppliedMigrationImmutabilityTest.java:39-43`이 notification·fileserver 디렉터리도 검사. inputs 선언 `PJ/build.gradle:267-271` |
|
||||
| P20-new-5 / 결정 36 JPA 설정 prefix | 남음 | 플랫폼 키가 아직 `app.persistence.vendor`, `app.runtime.migration-on-startup`에 있다(`PJ/src/main/resources/config/module-defaults/persistence-jpa.yml:160-164`, `PostgreSqlIdempotencyStoreConfig.java:38`). 결정 36은 이것을 `app.persistence-jpa.*`로 모으라고 했다(Wave 4 P33 예정) |
|
||||
| S6-#16c hikari 이력 주석 | 남음 | `persistence-jpa.yml:33-37` |
|
||||
| S6-#16e OSIV 예외 메시지의 문서 ID | 남음 | `PJ/src/main/.../startup/OpenInViewSafetyValidator.java:29` |
|
||||
|
||||
남은 High/P1급 지난 발견: 없음. 남은 항목은 모두 W4(테스트)·W5(문서) 성격이다.
|
||||
|
||||
## 3. 새 발견
|
||||
|
||||
심각도 순. 단순 결함은 설계 선택 필드를 `적용 제외`로 둔다.
|
||||
|
||||
### 04-01 커밋 중 연결이 끊기면 "재시도 가능(DB_UNAVAILABLE)"으로 답한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6 실패, 12 동시성, 17 계약, 11 데이터, 5 위험 가시성 |
|
||||
| 근거 | `PJ/src/main/.../failure/PersistenceExceptionTranslator.java:24,97` — SQLState가 `08`로 시작하면 무조건 `DB_UNAVAILABLE`. `OperationalError.DB_UNAVAILABLE`은 `retryable=true`(`src/shared-contract/.../OperationalError.java:54`). `SpringTransaction.execute`(`PJ/src/main/.../transaction/SpringTransaction.java:98-105`)는 커밋 실패도 같은 번역기로 보낸다. `TransactionCompletionUnknownException`은 main 어디에서도 생성되지 않는다(생성자 호출 0건). 실험: `TransactionSystemException(SQLException "08006")`을 커밋에서 던지는 `PlatformTransactionManager`로 `inWrite`를 호출 → `DB_UNAVAILABLE retryable=true`(E2). web은 retryable 코드에 `Retry-After`를 붙인다(`src/adapter/inbound/web/.../observability/RetryAfterAdvisor.java:29`) |
|
||||
| 발생 조건 | 커밋 요청을 보낸 뒤 응답 전에 DB 연결이 끊김(장애 조치, 네트워크 단절, `pg_terminate_backend`) |
|
||||
| 영향 | 서버는 커밋했을 수 있다. 클라이언트는 "일시 장애, 다시 시도"를 받고 같은 쓰기를 다시 보낸다. 멱등성 키가 없는 쓰기는 중복된다. ADR-JPA-003("completion unknown은 자동이든 아니든 재시도하지 않는다")과 반대다 |
|
||||
| 심각도·우선순위 | High / P1. 데이터 중복으로 이어지는 도달 가능한 경로이고, 기본 조립의 모든 쓰기 유스케이스가 지난다. 템플릿을 복사하면 그대로 퍼진다 |
|
||||
| 확실성 | 분류 결과는 실험으로 확인. 실제 PG에서 같은 SQLState가 나오는지는 `PostgreSqlTransactionIntegrationTest:147-197`이 연결 종료를 재현하지만 결과 코드를 단언하지 않아 미확인 |
|
||||
| 결정의 근거 | 적용 제외 — 기대 계약(ADR-JPA-003)이 이미 정해져 있다 |
|
||||
| 이해 비용 | 쓰기 유스케이스 작성자는 "503+Retry-After면 재시도해도 안전한가"를 코드에서 알 수 없다 |
|
||||
| 최소 개선 방향 | `SpringTransaction`이 커밋 단계에서 난 예외를 따로 잡는다. `TransactionTemplate.execute` 대신 `getTransaction`/`commit`을 직접 부르거나, 액션 완료 여부를 플래그로 기록한다. 액션이 끝난 뒤 난 `08*`·`40003`·전송 단절은 `DB_COMPLETION_UNKNOWN`(retryable=false)로 바꾼다 |
|
||||
| 완료 기준 | 커밋 중 연결 종료 시 호출자가 `DB_COMPLETION_UNKNOWN`을 받는다. 커밋 전 연결 실패는 여전히 `DB_UNAVAILABLE`이다 |
|
||||
| 검증 방법 | `PostgreSqlTransactionIntegrationTest#connectionLossDuringCommit…`에 결과 코드·retryable 단언 추가. 커밋 전 실패와 구분하는 단위 테스트 1개 |
|
||||
|
||||
### 04-02 다중 인스턴스에서 알림 정산 job이 중복 처리된다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(정적). 중복 처리의 업무 영향 범위는 일부 미확인 |
|
||||
| 관련 관점 | 12 동시성, 13 확장성, 6 실패, 5 위험 가시성 |
|
||||
| 근거 | `PN/JdbcReconciliationJobStore.java:43-52` claim은 `SELECT … FOR UPDATE SKIP LOCKED`다. `:117-123`은 이것을 트랜잭션 없이 `JdbcOperations.query`로 실행한다. 호출자 `src/adapter/outbound/notification/.../dispatch/ReconciliationJobWorker.java:81`과 스케줄러 `NotificationBackgroundWorkers.java:79-104`에도 트랜잭션이 없다. autocommit이라 행 잠금은 SELECT가 끝나는 순간 풀린다. lease·owner 컬럼도 없다. 같은 leaf의 다른 쓰기는 모두 `CallerTransaction.require`를 부르는데 이 store의 네 메서드(`:93-143`)만 부르지 않는다 |
|
||||
| 발생 조건 | 인스턴스 2개 이상, 정산 대기 job이 있을 때 |
|
||||
| 영향 | 같은 job을 여러 인스턴스가 동시에 가져간다. 공급자 상태 조회가 중복되고 `attempts`가 두 번 오른다(최대 시도 도달이 빨라짐). 결과 기록이 두 번 일어날 때의 업무 영향은 reconciler 구현의 멱등성에 달려 있고 확인하지 않았다 |
|
||||
| 심각도·우선순위 | High / P1. 코드가 "잠근다"는 의도를 보이지만 실제로 잠그지 않는다. 다중 서버 업무 중복 실행에 해당한다 |
|
||||
| 결정의 근거 | 적용 제외 — 같은 leaf의 recipient claim(`RecipientClaimSql`)이 이미 lease+fence 방식을 쓴다. 그 방식을 따르면 된다 |
|
||||
| 최소 개선 방향 | claim을 `UPDATE … SET claimed_by, claimed_until … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED) RETURNING`으로 바꾸고, reschedule·complete는 owner+token 조건 UPDATE로 바꾼다. 마이그레이션으로 컬럼 추가 |
|
||||
| 완료 기준 | 두 연결에서 동시에 claim하면 겹치는 job이 0개. lease가 지난 job만 다른 인스턴스가 가져간다 |
|
||||
| 검증 방법 | 실 PG 동시 claim 테스트(두 스레드, 교집합 0 단언). 가능하면 X1-#6d의 범용 `ClaimFencingContract`를 상속 |
|
||||
|
||||
### 04-03 JPA 연관관계 원칙(양방향 금지)을 막는 장치가 없고, 템플릿 문서와 fixture는 반대로 가르친다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 5 위험 가시성, 21 guardrail, 20 개발자 경험, 23 일관성, 4 인지 부하 |
|
||||
| 근거 | 전수 확인 결과 production 엔티티 28개(JPA 4, notification 12, fileserver 6, sample 5, gRPC ledger 1)에 `@ManyToOne`·`@OneToMany`·`@OneToOne`·`@ManyToMany`가 하나도 없다. 모두 UUID 컬럼으로 서로를 가리킨다. sample `WorkLogEntity.java:52-58`만 `@ElementCollection`(LAZY) 2개. 그러나 (1) ArchUnit 규칙 묶음 `JpaArchitectureRules`(`PJ/src/testFixtures/.../testkit/arch/JpaArchitectureRules.java:34-102`)와 `JpaProductionArchitectureTest`(`src/app-bootstrap/src/architectureTest/.../JpaProductionArchitectureTest.java`)에 연관관계 규칙이 없다. (2) `docs/jpa/entity-mapping-guide.md:50-57`은 "inverse collection + 양쪽을 맞추는 association helper"를 권장한다. (3) testFixtures `PagedParent.java:41-46`·`LifecycleParent.java:46-51`이 `@OneToMany(mappedBy, cascade=ALL, orphanRemoval)` + `@ManyToOne` 양방향 예시다. (4) sample 엔티티는 `JpaProductionArchitectureTest`의 import 대상이 아니다(app-bootstrap이 sample에 의존하지 않음) |
|
||||
| 발생 조건 | 파생 서비스 개발자가 가이드나 fixture를 따라 첫 연관관계를 만들 때 |
|
||||
| 영향 | 양방향 매핑이 아무 경고 없이 들어온다. 그러면 한쪽만 바꿔 FK가 비는 실수, `cascade=ALL`이 다른 aggregate 행을 지우는 실수, 직렬화·toString 순환, 컬렉션 로딩 N+1이 개발자 기억에 맡겨진다. 사용자가 정한 "위험은 코드에 드러나야 한다" 원칙과 반대다 |
|
||||
| 심각도·우선순위 | Medium / P1. 지금 production에 위반은 없다. 그러나 템플릿이 반대 패턴을 문서와 예제로 배포하므로 복제 범위가 크다 |
|
||||
| 결정의 근거 | 확인한 사실: 현재 코드는 이미 "ID 참조만" 방식으로 일관된다. 기록된 의도: 가이드는 양방향 helper를 권장한다. 둘이 어긋난다. 추론: 현재 코드의 일관성은 의도된 규칙이 아니라 결과일 가능성이 있다 |
|
||||
| 최소 개선 방향 | `JpaArchitectureRules`에 "필드에 `@OneToMany(mappedBy=…)`가 있으면 위반"(또는 "`@OneToMany`·`@ManyToMany` 금지, `@ManyToOne`은 LAZY 필수") 규칙을 추가하고 `JpaProductionArchitectureTest`와 sample 아키텍처 테스트에서 호출한다. 가이드 50-57행을 "aggregate 사이는 ID 참조, aggregate 안 자식은 단방향 `@ManyToOne` 또는 `@ElementCollection`"으로 바꾼다. fixture는 단방향으로 바꾸거나 "규칙의 위반 예시"로 이름과 위치를 옮긴다 |
|
||||
| 대안 비교 | (a) 문서만 고침: 비용 최소, 강제 없음(M1). (b) ArchUnit 규칙(선택): 빌드에서 막힘(M3), 규칙 1개·테스트 1개. (c) 컴파일 단계 annotation processor: 강제 강도는 같고 비용 큼. (d) 현상 유지: 원칙과 문서가 계속 충돌. (b)를 고른다. (c)는 얻는 것 대비 비용이 크다 |
|
||||
| 단순화의 보존 조건 | pagination·lifecycle 계약 테스트가 쓰는 fixture 동작(LAZY 컬렉션 페이지 경고, orphan 삭제)은 단방향 매핑이나 별도 위반 fixture로 유지해야 한다 |
|
||||
| 재검토 조건 | aggregate 안 자식 컬렉션을 엔티티로 다뤄야 하는 실제 요구(예: 자식 단독 조회·수정)가 생기면 `@OneToMany` 단방향(+`@JoinColumn`) 허용 범위를 다시 정한다 |
|
||||
| 완료 기준 | 양방향 fixture를 production 패키지에 넣으면 `architectureCheck`가 실패한다. 가이드와 fixture가 원칙과 같은 말을 한다 |
|
||||
| 검증 방법 | 위반 fixture로 규칙이 실패하는지 보는 red/green 테스트 |
|
||||
|
||||
### 04-04 실 PostgreSQL lane 9개(57개 테스트)가 어떤 게이트·workflow에서도 돌지 않는다. persistence-fileserver는 자기 테스트가 0개다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(게이트 누락) |
|
||||
| 관련 관점 | 10 테스트, 21 guardrail, 26 ownership, 18 배포 |
|
||||
| 근거 | readiness lane 16개(`PJ/build.gradle:166-183`) 중 workflow가 이름으로 부르는 것은 5개뿐이다(`.github/workflows/integration-main.yml:305-317`). `postgresql{Lifecycle,SecurityBaseline,Migration,Aggregate,Query,Idempotency,FileserverMigration,FileserverMetadata,FileserverReclamation}IntegrationTest`는 workflow·`release-registry.json` 어디에도 없다. 이 클래스들에는 `@Tag`가 없어 태그 lane(`jpaPlatformContractTest` 등)에도 안 잡힌다. 루트 `integrationCheck`(`src/build.gradle:100-105`)가 유일한 집계인데 `ci`·`mainCheck`에 들어 있지 않고, workflow는 `--dry-run`만 한다(`integration-main.yml:96-99`). 게이트 로그: `persistence-fileserver:test NO-SOURCE`, `mainCheck`는 JPA 실 DB lane을 하나도 실행하지 않음. 실행 확인: 4개 lane을 직접 돌려 44개 모두 통과(E2) — 지금은 깨져 있지 않다 |
|
||||
| 발생 조건 | fileserver·멱등성·마이그레이션 영속 코드를 바꾸는 PR |
|
||||
| 영향 | 파일 메타데이터·쿼터 회수·멱등성 저장소의 실제 SQL 동작이 바뀌어도 아무 게이트가 실패하지 않는다. `PJ/CLAUDE.md:97`("Contracts run against real PostgreSQL")과 `:119-121`("fail closed")의 주장이 실행으로 뒷받침되지 않는다 |
|
||||
| 심각도·우선순위 | Medium / P1. 결함 자체가 아니라 검출 공백이지만, persistence-fileserver는 다른 검증 경로가 없다 |
|
||||
| 결정의 근거 | 적용 제외 — 원하는 계약(실 DB 계약 실행)이 이미 문서에 있다 |
|
||||
| 최소 개선 방향 | `integration-main.yml`에 `./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck` 한 step을 추가하거나, fileserver·idempotency lane을 `fileserver-pr.yml`·`pr-adapters.yml`의 해당 path filter job에 넣는다. 장기적으로는 fileserver IT를 `persistence-fileserver` leaf로 옮긴다(04-13 참고) |
|
||||
| 완료 기준 | 16개 readiness lane이 모두 하나 이상의 workflow에서 실행된다. lane 목록과 workflow를 대조하는 테스트가 있으면 더 좋다 |
|
||||
| 검증 방법 | workflow 실행 기록, 또는 lane 이름 ↔ workflow 텍스트 대조 테스트 |
|
||||
|
||||
### 04-05 `@Version` 충돌이 변환되지 않고 500 INTERNAL_ERROR로 나간다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6 실패, 17 계약, 12 동시성, 8 디버깅 |
|
||||
| 근거 | `SpringTransaction`의 번역기는 SQLState만 본다(`PersistenceExceptionTranslator.java:73-84`). `ObjectOptimisticLockingFailureException`은 SQLException이 없어 `Optional.empty()` → `.orElse(failure)`(`SpringTransaction.java:105`)로 원래 예외가 나간다. web은 이것을 `INTERNAL_ERROR` 500으로 답한다(`src/adapter/inbound/web/.../error/GlobalExceptionHandler.java:189-196`). 실험으로 확인(E2). `DB_OPTIMISTIC_CONFLICT`(409)는 정의돼 있고 `LockFailureClassificationContractTest`가 enum 값만 확인한다(`src/app-bootstrap/src/test/.../LockFailureClassificationContractTest.java:38-60`). 이 코드를 만드는 곳은 라이브러리 API인 `PostgreSqlExceptionTranslator`뿐이고, 기본 조립은 이것을 쓰지 않는다 |
|
||||
| 발생 조건 | 같은 aggregate를 두 요청이 동시에 수정. sample `UpdateWorkLogUseCase.java:32-73`은 읽은 뒤 버전을 비교하지만, 비교와 커밋 사이 경쟁은 커밋 시점 `@Version` 충돌로만 잡힌다 |
|
||||
| 영향 | 클라이언트는 "다시 읽고 고쳐라"(409) 대신 "서버 오류"(500)를 받는다. 운영 로그에는 정상 경쟁이 error로 남는다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 결정의 근거 | 적용 제외 — 기대 코드(`DB_OPTIMISTIC_CONFLICT`)가 이미 정해져 있다 |
|
||||
| 최소 개선 방향 | `SpringTransaction.execute`(또는 `PersistenceExceptionTranslator`)에서 Spring `OptimisticLockingFailureException`을 `DB_OPTIMISTIC_CONFLICT`로 바꾼다. 04-06의 표 통합과 같이 하면 한 곳만 고친다 |
|
||||
| 완료 기준 | 커밋 시점 버전 충돌 시 호출자가 `PersistenceFailureException(DB_OPTIMISTIC_CONFLICT)`를 받고 web은 409를 답한다 |
|
||||
| 검증 방법 | 단위 테스트(실험과 같은 형태) + 실 PG 두 트랜잭션 경쟁 테스트 1개 |
|
||||
|
||||
### 04-06 SQLState 분류표가 두 벌이고 이미 갈라졌다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(갈라진 중복) |
|
||||
| 관련 관점 | 23 일관성, 9 유지보수, 17 계약, 22 추상화 |
|
||||
| 근거 | 표 1: `failure/StandardSqlStateErrorMapping` + `postgresql/PostgreSqlSqlStateErrorMapping.java:17-23`(SQLState → `OperationalError`). `TransactionPort` 경로가 쓴다. 표 2: `postgresql/error/PostgreSqlFailureClassifier.java:50-61`(SQLState → `FailureCategory`) + `api/error/JpaPersistenceException.java:59-75`(`FailureCategory` → `OperationalError`). 라이브러리 API 경로가 쓴다. 실험: `25P03`이 표 1에서는 `DB_IDLE_IN_TX_TIMEOUT`(retryable=true), 표 2에서는 `TRANSACTION_TIMEOUT` → `DB_QUERY_CANCELED`(retryable=false)(E2). `40003`은 표 2에만 있다(completion unknown). `@Version` 충돌은 표 2에만 있다(04-05) |
|
||||
| 발생 조건 | 같은 DB 오류가 어느 경로로 올라오느냐에 따라 |
|
||||
| 영향 | 같은 장애에 클라이언트가 받는 retryable 값이 경로마다 다르다. SQLState를 하나 추가할 때 두 곳을 고쳐야 하고, 하나만 고쳐도 아무 테스트가 실패하지 않는다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 결정의 근거 | 확인한 사실: 두 표 모두 `PersistenceFailureException`을 만든다(`JpaPersistenceException extends PersistenceFailureException`). 기록된 의도: 표 2 Javadoc은 "세 갈래 병렬 분류 대신 같은 코드"를 말한다(`JpaPersistenceException.java:19`). 의도는 하나로 모으는 것이었고 끝나지 않았다 |
|
||||
| 최소 개선 방향 | 표 2(`PostgreSqlFailureClassifier` → `FailureCategory`)를 정본으로 하고, `PostgreSqlSqlStateErrorMapping`은 그 결과로부터 파생한다. 또는 반대로 표 1에 `FailureCategory`를 얹는다 |
|
||||
| 대안 비교 | (a) 표 2 정본(선택): 범주가 더 풍부(completion unknown, optimistic, schema mismatch). 표 1의 SPI(`SqlStateErrorMapping`)는 vendor 확장점이라 어댑터 하나로 남긴다. (b) 표 1 정본: 기본 경로라 영향 범위 작음, 그러나 completion-unknown·optimistic 표현이 없다. (c) 두 표 유지 + 일치 테스트: 가장 싸지만 중복이 남는다. (a)를 고르고, 이행 중에는 (c)의 일치 테스트로 보호한다 |
|
||||
| 단순화의 보존 조건 | `SqlStateErrorMapping` SPI(H2 행 기여)와 중복 SQLState 기여 시 기동 실패(`PersistenceExceptionTranslator.java:43-56`)는 유지 |
|
||||
| 재검토 조건 | 두 번째 RDBMS 벤더가 운영 대상이 되면 vendor별 표 구조를 다시 정한다 |
|
||||
| 완료 기준 | 모든 SQLState에 대해 두 경로의 결과 코드가 같다(또는 표가 하나다) |
|
||||
| 검증 방법 | `PostgreSqlState` 전 값에 대한 parameterized 일치 테스트 |
|
||||
|
||||
### 04-07 bulk UPDATE가 `@Version`을 올리지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 12 동시성, 11 데이터, 21 guardrail |
|
||||
| 근거 | `PN/inbox/InboxItemJpaRepository.java:82-108` `markAllRead`는 `state`·`read_at`을 바꾸지만 `version`을 올리지 않고 `clearAutomatically`도 없다. 엔티티는 `@Version`(`PN/inbox/InboxItemEntity.java:72-74`). `PN/RecipientClaimSql.java:53-64` `EXPIRE_OVERDUE`도 같다. 같은 leaf의 claim SQL은 이미 version을 올린다(`RecipientClaimSql.java:42-46`). `JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit`는 audit 컬럼만 본다 |
|
||||
| 발생 조건 | 같은 트랜잭션이나 다른 요청이 그 전에 읽은 엔티티를 수정·flush |
|
||||
| 영향 | 낙관적 락이 충돌을 못 잡고 `read_at`이나 EXPIRED 상태를 되돌린다(lost update) |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 결정의 근거 | 적용 제외 |
|
||||
| 최소 개선 방향 | 두 쿼리에 `version = version + 1`, `@Modifying(clearAutomatically = true, flushAutomatically = true)`. 그리고 audit 규칙과 같은 방식으로 "`@Version` 엔티티 테이블을 바꾸는 native/JPQL UPDATE는 version을 올린다" ArchUnit/문자열 규칙을 추가 |
|
||||
| 완료 기준 | 두 쿼리 뒤에 이전 버전으로 flush하면 낙관적 락 충돌이 난다 |
|
||||
| 검증 방법 | 실 PG 테스트 1개(읽기 → bulk → 이전 엔티티 수정 → 충돌 단언) |
|
||||
|
||||
### 04-08 upsert가 "찾고 없으면 넣기"라 동시 요청에서 깨진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 12 동시성, 11 데이터, 6 실패 |
|
||||
| 근거 | 수신 거부: `PN/JpaSuppressionStore.java:47-64` find → save. DDL에 unique 제약이 없고 일반 인덱스뿐이다(`persistence-notification/src/main/resources/db/migration/jpa/notification-platform/V2__notification_platform_contact_template_policy.sql:77-93`). finder는 단건 `Optional`(`PN/SuppressionJpaRepository.java:33`). 선호 설정: `PN/JpaPolicyStores.java:50-72` 같은 구조, 제약 `uk_notification_preference`는 있음(V2:102) |
|
||||
| 발생 조건 | 같은 대상의 bounce webhook 두 개가 동시에 도착, 또는 첫 선호 저장이 동시에 두 번 |
|
||||
| 영향 | 수신 거부: 행이 2개 생기고, 그 뒤 같은 키의 upsert는 매번 `IncorrectResultSizeDataAccessException`(500)으로 실패한다. 수동 정리 전까지 회복되지 않는다. 선호 설정: 한쪽이 `DB_UNIQUE_VIOLATION`(409)을 받는다. 멱등해야 할 동작이 충돌 오류가 된다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 결정의 근거 | 적용 제외 — 같은 클래스의 dedup 경로가 이미 `ON CONFLICT`로 고쳐져 있다 |
|
||||
| 최소 개선 방향 | 새 마이그레이션 `UNIQUE (tenant_id, normalized_target_hmac, reason)`(기존 중복 정리 포함), 두 store를 `INSERT … ON CONFLICT … DO UPDATE` native upsert로 |
|
||||
| 완료 기준 | 동시 upsert 두 개 후 행 1개, 두 호출 모두 성공 |
|
||||
| 검증 방법 | 실 PG 동시 upsert 테스트 |
|
||||
|
||||
### 04-09 sample 목록 조회가 N+1이다(페이지당 최대 202쿼리)
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(정적 계산, 실측 안 함) |
|
||||
| 관련 관점 | 14 성능, 10 테스트, 20 개발자 경험, 21 guardrail. sample 영역과 겹침(>) |
|
||||
| 근거 | `WorkLogEntity.java:52-58` LAZY `@ElementCollection` 2개. `WorkLogRepositoryAdapter.java:77-80` `findAll(pageRequest)` 뒤 행마다 `toDomain` → `WorkLog.rehydrate`가 `List.copyOf(techStack)`, `List.copyOf(links)`(`domain/worklog/WorkLog.java:51-52`)로 두 컬렉션을 초기화. `default_batch_fetch_size` 기본 0(`persistence-jpa.yml:150`). 페이지 크기 상한 100(`PageParams.java:20`). 쿼리 수 = 1(page) + 1(count) + 2×N → N=20이면 42, N=100이면 202. testkit에 `JpaQueryAssertions`(`PJ/src/testFixtures/.../testkit/query/`)가 있지만 sample은 persistence-jpa testFixtures를 쓰지 않는다 |
|
||||
| 발생 조건 | `GET` 목록 요청마다 |
|
||||
| 영향 | 요청당 DB 왕복이 행 수에 비례한다. 템플릿의 "참조 구현"이 N+1을 보여 주므로 파생 서비스가 그대로 복사한다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 결정의 근거 | 대안: (a) `default_batch_fetch_size`를 100 정도로 기본 설정(선택: 한 줄, 모든 LAZY 컬렉션에 효과, 쿼리 수 4로 고정). (b) 목록은 이미 있는 `WorkLogSummaryQueryPort`(컬렉션 없는 projection)로 돌림: 목록 화면 요구가 요약뿐이면 가장 싸다. (c) `@EntityGraph` fetch join: 컬렉션 2개 동시 join은 카테시안 곱과 페이지 메모리 처리 경고를 만든다 → 기각 |
|
||||
| 최소 개선 방향 | (a)와 함께, sample 목록 테스트에 `JpaQueryAssertions`로 "쿼리 수 ≤ 4" 단언을 넣는다 |
|
||||
| 완료 기준 | 목록 요청의 쿼리 수가 N과 무관하다 |
|
||||
| 검증 방법 | statement 수 단언 테스트(실 PG lane) |
|
||||
|
||||
### 04-10 기본 쓰기·읽기 트랜잭션에 시간 제한이 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 6 실패, 7 운영, 14 성능 |
|
||||
| 근거 | `SpringTransaction.java:58`은 `inNew`에만 30초를 건다. `inWrite`·`inRootWrite`·`inRead`는 timeout 없음. `statement_timeout`·`lock_timeout`·`idle_in_transaction_session_timeout`을 설정하는 코드·설정이 없다(`set_config`는 COPY loader·실험 패키지에만). Hikari `leak-detection-threshold: 30000`(`persistence-jpa.yml`)은 경고만 한다 |
|
||||
| 발생 조건 | 느린 쿼리, 행 잠금 대기, 트랜잭션 안의 외부 호출 |
|
||||
| 영향 | 커넥션 10개(기본 pool) 풀이 오래 붙잡혀 다른 요청이 `connection-timeout` 5초 뒤 실패한다. 원인 쿼리는 끝나지 않는다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 결정의 근거 | 대안: (a) `TransactionTemplate.setTimeout`을 모드별로(선택: JPA query hint로 전파, 코드 한 곳). (b) DB role 수준 `ALTER ROLE … SET statement_timeout`: 앱 밖이라 템플릿이 보장 못 함, runbook에 병기. (c) 매 트랜잭션 `set_config('statement_timeout', …, true)`: 왕복 1회 추가 → (a)로 충분할 때 기각 |
|
||||
| 최소 개선 방향 | `app.persistence-jpa.transaction.write-timeout`/`read-timeout` 설정(기본 예: 10초/5초)을 두고 템플릿에 적용 |
|
||||
| 완료 기준 | 기본 설정에서 `pg_sleep(실제보다 긴 값)`이 든 `inWrite`가 정해진 시간 안에 실패한다 |
|
||||
| 검증 방법 | 실 PG 테스트 1개 |
|
||||
|
||||
### 04-11 Mongo 트랜잭션 본문의 일시 오류가 재시도되지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(정적, 실 서버 미재현) |
|
||||
| 관련 관점 | 6 실패, 12 동시성, 10 테스트 |
|
||||
| 근거 | 본문에 넘기는 것은 `template.withSession(session)`(`PM/src/main/.../transaction/SpringMongoTransactionSessionFactory.java:92`)이다. `MongoTemplate`은 드라이버 예외를 Spring `DataAccessException`으로 바꿔 던진다. 그런데 `runBody`는 `MongoException`만 잡는다(`:141-142`). 그래서 WriteConflict(TransientTransactionError)는 `MongoTransactionTransientException`이 되지 않고, `MongoTransactionRetryCoordinator.execute`(`retry/MongoTransactionRetryCoordinator.java:85-92`)의 본문 재시도 분기에 걸리지 않는다. coordinator를 실 서버에서 검증하는 테스트는 없다 |
|
||||
| 영향 | `PM/CLAUDE.md:137-139`가 보장하는 "본문 재시도"가 템플릿 경로에서는 동작하지 않는다. 쓰기 경쟁이 그대로 실패로 나간다. 소비자가 0이라 현재 피해는 없다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 결정의 근거 | 적용 제외 |
|
||||
| 최소 개선 방향 | `runBody`에서 `DataAccessException`의 cause 사슬에서 `MongoException`을 찾아 분류한다 |
|
||||
| 완료 기준 | replica set lane에서 강제 WriteConflict 후 본문이 한 번 더 실행되고 성공한다 |
|
||||
| 검증 방법 | `mongoReplicaSetTest`에 테스트 추가 |
|
||||
|
||||
같은 파일의 관련 소항목(Low): commit 재시도 대기 중 인터럽트가 `IllegalStateException`으로 바뀌어 "commit 결과 모름" 표시가 사라진다(`MongoTransactionRetryCoordinator.java:150,186`). `MongoTransactionCommitUnknownException`으로 감싸야 한다.
|
||||
|
||||
### 04-12 Mongo 기본 경로(URI만 준 배포)에 timeout·pool 제한이 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 19 설정, 6 실패, 7 운영 |
|
||||
| 근거 | typed profile이 없으면 설정 적용을 건너뛴다(`PM/src/main/.../client/MongoProfileClientSettingsAutoConfiguration.java:82-83`). 그러면 드라이버 기본값(pool 100, server selection 30초, socket timeout 무제한)을 쓴다. `PM/src/main/resources/config/mongo.yml:11` 주석은 "active-profile이 비면 안 된다"고 하지만 `MongoPlatformSettings.java:84-86`은 profile이 있을 때만 검사한다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 최소 개선 방향 | `mongo.yml`에 `spring.mongodb` timeout·pool 기본값을 두거나, 주석을 실제 동작에 맞춘다 |
|
||||
| 결정의 근거 | 적용 제외 — 문서와 코드 불일치 정리 |
|
||||
| 완료 기준·검증 | URI만 준 기동에서 `MongoClientSettings`의 socket·selection timeout이 유한값임을 단위 테스트로 확인 |
|
||||
|
||||
### 04-13 persistence adapter가 정책을 소유하고, claim 토큰을 프로세스 메모리에 둔다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 2 구조, 5 위험 가시성, 12 동시성, 22 추상화 |
|
||||
| 근거 | `PF/JpaCleanupQueue.java:36` `MAXIMUM_ATTEMPTS = 8`, `:151-160` 소진 시 ABANDONED 판정, `:67` lease 10분 상수. `:100-116` claim은 행마다 UPDATE를 따로 보내고 `SKIP LOCKED`가 없다. claim 토큰은 `heldClaims` 맵(`:77`)에 두고 `CleanupItem`으로 돌려주지 않는다. 다른 인스턴스가 reclaim하거나 트랜잭션이 롤백되면 항목이 남는다. inbox 상태 전이(seen/read/archive 단조성)는 엔티티 메서드에 있다(`PN/inbox/InboxItemEntity.java:106-151`) |
|
||||
| 영향 | 재시도 한도·lease 길이를 바꾸려면 persistence 코드를 고쳐야 한다(HARD-STOP 4 "비즈니스 규칙이 mapper·설정으로 이동"과 같은 방향의 위험). 토큰이 프로세스에 있어 fencing 정보가 포트 계약에 드러나지 않는다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 결정의 근거 | 기록된 의도: 주석(`:110-113`)은 "재시작하면 토큰을 잃는 것이 목적"이라 한다. 그 목적은 토큰을 `CleanupItem`에 실어 호출자가 들고 있어도 똑같이 지켜진다 |
|
||||
| 최소 개선 방향 | 토큰과 시도 횟수를 `CleanupItem`에 싣고, `markFailed`의 소진 판정은 application(`application-fileserver`)으로, 한도·lease는 포트 인자나 설정으로. claim은 notification의 CTE + `SKIP LOCKED` + `RETURNING` 한 문장 패턴으로 |
|
||||
| 대안 비교 | (a) 현상 유지 + 문서화: 비용 0, 숨은 위험 유지. (b) 위 방향(선택). (c) 범용 lease 모듈로 통합(X1-#6): 범위가 커서 이번 항목과 분리 |
|
||||
| 단순화의 보존 조건 | "늦게 깬 worker의 완료는 적용되지 않는다"(토큰 불일치 시 0행)는 유지 |
|
||||
| 완료 기준 | adapter에 정책 상수 없음, claim 한 문장, 토큰이 포트 타입에 있음 |
|
||||
| 검증 방법 | `PostgreSqlFileserverReclamationIntegrationTest` 확장 |
|
||||
|
||||
### 04-14 notification·fileserver 영속 leaf가 테스트 규칙(공유 계약)을 따르지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(규칙 위반) |
|
||||
| 관련 관점 | 10 테스트, 26 ownership, 23 일관성 |
|
||||
| 근거 | `application-notification`, `application-fileserver`에 `testFixtures` source set이 없다. fileserver fake는 `application-fileserver/src/test/.../testkit/InMemory*.java`에 있고, `MetadataPortContractTest`는 abstract가 아니다. PG IT는 fake와 별개로 작성됐다. AGENTS.md 테스트 규칙 6("fake와 adapter가 같은 추상 계약을 통과")과 capability 완료 기준 5 위반. fileserver IT 37개는 `persistence-jpa`의 source set에 있다(`PJ/build.gradle:102-115`) |
|
||||
| 영향 | fake로 통과한 유스케이스 테스트가 실제 저장소 동작과 다를 수 있다. leaf 소유자와 테스트 소유자가 다르다 |
|
||||
| 심각도·우선순위 | Medium / P2 (지난 W4 항목 TEST-FAKE-*·X1-#3b·S7-lead-4와 같은 묶음) |
|
||||
| 결정의 근거 | 적용 제외 — 규칙이 이미 정해져 있다 |
|
||||
| 최소 개선 방향 | 포트별 abstract `XxxContract`를 각 application leaf testFixtures로, fake 테스트와 PG IT가 상속. fileserver IT는 `persistence-fileserver`의 integration lane으로 이동 |
|
||||
| 완료 기준·검증 | 포트마다 계약 1개, 구현 2개 이상이 상속. `persistence-fileserver:test`가 NO-SOURCE가 아님 |
|
||||
|
||||
### 04-15 Mongo 라이브러리를 파생 서비스가 쓸 경로와 예시가 없다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 / 개선 제안 |
|
||||
| 관련 관점 | 20 개발자 경험, 22 추상화, 27 삭제 가능성, 13 확장성 |
|
||||
| 근거 | 레지스트리에서 mongo leaf에 의존할 수 있는 모듈은 `app-bootstrap`뿐이고 그 줄도 주석이다(`src/app-bootstrap/build.gradle:164`). README는 "서비스 어댑터 leaf가 `implementation`으로 받는다"(`PM/README.md:140-142`)고 하지만 등록 절차 안내가 없다. `@Document`·`MongoRepository` 예시가 0개. main 278개 파일·18,939줄, 공개 타입 271개(`docs/architecture/mongo-api-surface.txt`), leaf 밖 production 소비자 0 |
|
||||
| 영향 | 파생 서비스는 레지스트리 edge, 예외 변환(`MongoDuplicateKeyException` 등), 정책 적용 범위(repository 직접 사용 시 `MongoQueryPolicy` 우회)를 추측해야 한다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 결정의 근거 | 사용자 원칙상 소비자 없는 코드는 확장 지점이지 죽은 코드가 아니다. 다만 확장 지점이면 "어떻게 꽂는지"가 있어야 한다. 그 부분이 빠졌다 |
|
||||
| 최소 개선 방향 | testFixtures에 document·repository·mapper·port 구현 예시 한 벌, `docs/mongodb`에 "소비 leaf 등록" 절차(레지스트리 edge 추가 예) |
|
||||
| 대안 비교 | (a) 예시+절차(선택). (b) advanced 패키지를 별도 leaf로 분리해 표면 축소: 효과 크지만 이동 범위 큼(CLAUDE.md가 이미 별도 커밋으로 미룸). (c) 소비자 생길 때까지 삭제: 소유자 결정(capability 유지)과 충돌 → 기각 |
|
||||
| 완료 기준·검증 | 예시가 `mongoStableContractTest`에서 컴파일·실행된다 |
|
||||
|
||||
### 04-16 notification·fileserver leaf에 가까운 안내 문서가 없고 패키지가 평평하다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안 |
|
||||
| 관련 관점 | 4 인지 부하, 9 유지보수, 26 ownership |
|
||||
| 근거 | 두 leaf에 `CLAUDE.md`·`README.md`가 없다(루트 CLAUDE.md는 "nearest guidance가 local rules를 소유"한다고 말한다). notification은 엔티티·repository·adapter·SQL 상수 약 37개가 `platform` 한 패키지에 있고 하위는 `inbox`뿐. fileserver는 `entity/`·`repository/`로 나눴고 adapter는 루트에 있어 두 leaf 규칙이 다르다 |
|
||||
| 심각도·우선순위 | Low / P3 |
|
||||
| 최소 개선 방향 | 두 leaf에 짧은 CLAUDE.md(테스트 위치, 트랜잭션 guard 규칙, 마이그레이션 위치·불변성 테스트). notification을 기능별 하위 패키지로 |
|
||||
| 결정의 근거·완료 기준 | 적용 제외 — 문서·배치 정리. 완료: 두 leaf에 안내 문서, 같은 패키지 규칙 |
|
||||
|
||||
### 04-17 미리 정한 UUID + primitive `long` version이라 `save()`가 merge로 동작한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(작음) |
|
||||
| 관련 관점 | 14 성능, 11 데이터 |
|
||||
| 근거 | `PF/entity/FileEntity.java:78` 외 fileserver 엔티티의 `@Version long`. Spring Data는 primitive version이면 id null 여부로 새 엔티티를 판단하는데 id가 미리 정해져 있어 merge가 된다. `save` 호출: `PF/JpaFileMetadata.java:76`, `JpaFileQuota.java:50`, `JpaUploadSession.java:58` 등 |
|
||||
| 영향 | insert마다 SELECT 1회 추가. id가 겹치면 unique 오류 대신 낙관적 락 오류나 덮어쓰기 |
|
||||
| 심각도·우선순위 | Low / P3 |
|
||||
| 최소 개선 방향 | `Persistable<UUID>` 구현 또는 `Long version`(null = 새 엔티티) |
|
||||
| 결정의 근거·검증 | 적용 제외. 검증: statement 수 단언 테스트 |
|
||||
|
||||
## 4. 31절 시나리오 추적
|
||||
|
||||
### 선택 1 — DB 오류·경쟁: sample WorkLog 동시 수정
|
||||
|
||||
```
|
||||
WorkLog 수정 요청 (expectedVersion 선택)
|
||||
→ WorkLogController (입력 검증, inbound DTO → command)
|
||||
→ UpdateWorkLogUseCase.handle ── tx.inWrite 시작 (REQUIRED, READ_COMMITTED, timeout 없음)
|
||||
→ repository.findById → 버전 비교(있으면) → 도메인 메서드로 규칙 적용
|
||||
→ WorkLogRepositoryAdapter.save → findById(audit created_* 이월) → jpa.save = merge
|
||||
── 커밋: flush 시 UPDATE … WHERE version=?
|
||||
→ 응답
|
||||
```
|
||||
|
||||
| 항목 | 결과 |
|
||||
| --- | --- |
|
||||
| 입력 신뢰 수준 | 인증된 사용자 입력. 크기·형식은 web에서 검증 |
|
||||
| 권한 판단 위치 | 이 영역 밖(> 인증 영역). 영속 계층은 소유자 조건 없이 id로만 조회한다 |
|
||||
| 규칙 소유 객체 | `WorkLog` 도메인(상태 전이). 버전 비교는 유스케이스. audit 스탬프는 adapter(`WorkLogRepositoryAdapter.java:42-56`) — 인프라 관심사라 적절 |
|
||||
| 트랜잭션 | 유스케이스가 `TransactionPort.inWrite`로 연다. adapter는 열지 않는다. 시간 제한 없음(04-10) |
|
||||
| 외부 부작용 | 없음(outbox 미사용 경로) |
|
||||
| 성공의 의미 | 커밋 후 반환. `@Version`이 경쟁을 막는다 |
|
||||
| 오류 변환 | 버전 비교 실패 → `WorkLogVersionMismatchException`(sample 핸들러가 409). 비교 통과 후 커밋 경쟁 → `ObjectOptimisticLockingFailureException` 원본 → 500(04-05). 커밋 중 연결 끊김 → `DB_UNAVAILABLE` retryable(04-01) |
|
||||
| 진단 정보 | 500 경로는 스택 포함 error 로그. persistence carrier는 SQLState만 로그(파라미터 없음) — 민감정보 보호는 지켜진다 |
|
||||
|
||||
### 선택 2 — 여러 서버의 작업 실행: 알림 정산 job
|
||||
|
||||
`NotificationBackgroundWorkers`(인스턴스마다 스케줄러 1개) → `ReconciliationJobWorker.reconcileOnce` → `JdbcReconciliationJobStore.claimDue`(autocommit `FOR UPDATE SKIP LOCKED`) → 공급자 조회 → `reschedule`/`complete`. 소유권 표시가 없어 중복 실행된다(04-02). 같은 leaf의 recipient claim, JPA outbox claim은 owner+token fencing으로 올바르게 처리한다(`PJ/README.md` outbox 절, V17).
|
||||
|
||||
### 선택 3 — 큰 입력·목록 조회
|
||||
|
||||
web `PageParams.MAX_SIZE=100` → 유스케이스 → adapter `PageRequest`. 크기 상한은 web에만 있고 adapter는 `size<=0`만 보정한다(`WorkLogRepositoryAdapter.java:69`). 쿼리 수는 N에 비례(04-09). 라이브러리 keyset은 상한 500(`api/query/KeysetPageRequest.java:19`), Mongo keyset 1,000·skip 상한 있음. notification의 limit 없는 List 조회 4곳(`ConsentJpaRepository.java:23`, `ProviderEventJpaRepository.java:32`, `RecipientDeliveryJpaRepository.java:28`, `SuppressionJpaRepository.java:24`)은 누적 데이터에 비례해 커진다(Low, 04-14 작업 때 같이).
|
||||
|
||||
### 적용 제외
|
||||
|
||||
| 시나리오 | 사유 |
|
||||
| --- | --- |
|
||||
| 정상 쓰기 요청 | 선택 1이 같은 경로를 포함 |
|
||||
| 중복·동시 요청 | 멱등성 executor는 composition·application 영역. 영속 측 공통 계약 부재는 S2-lead-2로 재확인 |
|
||||
| 외부 응답 지연·유실 | 영속 영역에 외부 호출 없음 |
|
||||
| 메시지 중복·역순 | outbox 발행·소비는 messaging 영역. 영속 측 fencing은 V17·`OutboxLeaseFencingContract`로 확인 |
|
||||
| 신·구 버전 공존 | 마이그레이션 불변성 테스트(해시 고정)로 적용된 파일 변경은 막힌다. expand/contract 지침은 `docs/jpa/migration-guide.md`. 실제 무중단 전환 실험은 범위 밖 |
|
||||
| 세션·토큰 갱신 경쟁, 다른 사용자 리소스 접근 | 인증·인가 영역 |
|
||||
| 종료·재시작 | 스케줄러 종료는 notification adapter 영역 |
|
||||
| 선택 어댑터 제거 | `JpaActivationEnvironmentPostProcessor`(enabled=false → Boot 자동설정 제외)와 Mongo `MongoCapabilityActivationTest`가 다룬다. composition 영역에서 확인 |
|
||||
|
||||
## 5. 41절 설계 선택 검토
|
||||
|
||||
### 5.1 엔티티 사이를 연관관계 없이 ID로만 잇는다(현재 코드의 선택)
|
||||
|
||||
1. 필요한 것: aggregate 경계 유지, 의도치 않은 로딩·cascade 방지, 사용자 원칙(양방향 금지).
|
||||
2. 지킬 성질: 한 aggregate의 저장이 다른 aggregate 행을 바꾸지 않는다. 로딩 범위가 쿼리에서 보인다.
|
||||
3. 현재 보장: production 엔티티 전부가 UUID 컬럼으로 참조한다(전수 확인). 강제 장치는 없다(M2, 04-03).
|
||||
4. 대안: (a) 단방향 `@ManyToOne` LAZY 허용, (b) 가이드대로 양방향 + helper, (c) ID 참조만.
|
||||
5. 대가: (a) 조인 쿼리 작성이 편하다. 프록시·LAZY 예외를 알아야 한다. (b) 양쪽 동기화를 기억해야 한다. cascade 오용 위험이 크다. (c) 조인이 필요하면 JPQL/projection을 직접 쓴다. 로딩이 늘 명시적이다.
|
||||
6. 현재 조건에서의 선택: (c)가 원칙과 aggregate 경계에 맞는다. aggregate 안 자식은 `@ElementCollection` 또는 단방향 `@ManyToOne`까지 허용하는 것이 현실적이다.
|
||||
7. 바뀌는 조건: aggregate 안 자식을 독립 엔티티로 조회·수정해야 하는 요구가 생기면 단방향 `@OneToMany(@JoinColumn)` 허용 여부를 다시 본다.
|
||||
|
||||
판정: 선택은 타당하지만 코드에 강제되지 않고 문서가 반대로 말한다. 그래서 설명 검증은 "부분 통과"다.
|
||||
|
||||
### 5.2 예외 변환을 TransactionPort 경계에서 SQLState로 한 번만 한다
|
||||
|
||||
1. 필요한 것: DB 세부(SQL, 제약 이름)가 클라이언트로 새지 않게, 그리고 재시도 가능 여부를 정확히 알린다.
|
||||
2. 지킬 성질: 결과 불명은 재시도 불가로, 경쟁은 409로, 장애는 503으로.
|
||||
3. 현재 보장: 누출 방지는 지켜진다(carrier는 코드만, 로그도 코드만). 재시도 판단은 두 곳에서 틀린다(04-01 커밋 단계 구분 없음, 04-05 SQLState 없는 Spring 예외 미처리). 분류표가 두 벌이다(04-06).
|
||||
4. 대안: (a) adapter마다 변환, (b) 경계에서 한 번(현재), (c) 경계에서 한 번 + 단계(액션/커밋) 인지 + Spring 예외 타입 인지.
|
||||
5. 대가: (a) 누락이 쉽고 중복된다. (b) 단순하지만 단계 정보를 잃는다. (c) `SpringTransaction`에 수십 줄 추가.
|
||||
6. 선택: (b)의 위치는 맞다. (c)로 보강해야 ADR-JPA-003을 지킨다.
|
||||
7. 바뀌는 조건: 트랜잭션 엔진이 둘이 되거나 reactive 트랜잭션이 들어오면 다시 본다.
|
||||
|
||||
### 5.3 실 PostgreSQL 계약 lane을 `ci`·`mainCheck` 밖에 둔다
|
||||
|
||||
1. 필요한 것: PR이 빨라야 하고(ci 7분), 실 DB 동작은 검증돼야 한다.
|
||||
2. 지킬 성질: 실 DB lane마다 적어도 한 workflow가 실행한다.
|
||||
3. 현재 보장: 태그 lane 5개와 readiness 5개는 workflow가 돈다. readiness 9개는 아무도 돌리지 않는다(04-04).
|
||||
4. 대안: (a) 전부 `mainCheck`로, (b) path filter workflow로(현재 일부), (c) `integrationCheck`를 nightly에 통째로.
|
||||
5. 대가: (a) main 단계가 수 분 늘어난다(이번 측정: 4개 lane Gradle 56초). (b) 필터 누락이 생긴다(지금 상태). (c) 반나절 늦게 발견.
|
||||
6. 선택: (c)를 기본 안전망으로 두고 (b)를 유지하는 것이 비용 대비 낫다. 지금은 안전망이 없다.
|
||||
7. 바뀌는 조건: lane 수가 늘어 nightly 시간이 문제가 되면 matrix로 나눈다.
|
||||
|
||||
## 6. 리팩토링 후보
|
||||
|
||||
| 무엇 | 왜 | 보존할 동작·타입·실패 계약 |
|
||||
| --- | --- | --- |
|
||||
| SQLState 분류표 두 벌 → 한 벌(04-06) | 갈라진 중복, retryable 값 불일치 | `SqlStateErrorMapping` SPI, 중복 기여 시 기동 실패, `PersistenceFailureException` 타입과 web의 carrier 처리, 로그에 SQL 미포함 |
|
||||
| `SpringTransaction.execute`에 커밋 단계 구분(04-01·04-05) | ADR-JPA-003 준수, 409 정상화 | 모드별 propagation·isolation·readOnly 표(`PJ/CLAUDE.md:221-226`), `inRootWrite`의 중첩 거부, 재시도 0회 |
|
||||
| `JpaCleanupQueue` 정책·토큰 이동(04-13) | 정책이 adapter에, 토큰이 메모리에 | 토큰 불일치 시 완료 무시, lease 만료 후 reaper 인수 |
|
||||
| notification `platform` 패키지 분할(04-16) | 37개 파일 평면 | 공개 타입 이름, Spring bean 이름(조립 코드가 참조) |
|
||||
| Mongo `internal` 패키지 이동(CLAUDE.md 보류 항목) | 공개 타입 271개 | `verifyMongoApiSurface` 스냅샷이 줄어드는 것으로 증명, Stable 패키지가 advanced를 참조하지 않는 규칙 |
|
||||
|
||||
## 7. 기능 개발 패턴과 판단 지점 (매뉴얼 재료)
|
||||
|
||||
새 aggregate 하나를 JPA로 저장할 때 템플릿이 주는 것:
|
||||
|
||||
- 따라 할 예시: sample `WorkLogEntity`·`WorkLogPersistenceMapper`·`WorkLogRepositoryAdapter`·`WorkLogJpaRepository`, 계약 테스트 `WorkLogRepositoryContract`(fake와 adapter 공용).
|
||||
- 기반: `AuditableEntity`(audit 컬럼), `AuditContextPort`, `TransactionPort`, `CallerTransaction.require`(adapter가 호출자 트랜잭션을 요구), `PersistenceExceptionTranslator`.
|
||||
- 검사: `JpaProductionArchitectureTest`(엔티티 노출·final·generic repository·audit·tenant), `AppliedMigrationImmutabilityTest`(마이그레이션 해시 고정).
|
||||
- 문서: `docs/jpa/entity-mapping-guide.md`, `query-fetch-guide.md`, `migration-guide.md`, `transaction-guide.md`.
|
||||
|
||||
빠진 것:
|
||||
|
||||
- 연관관계 규칙과 그 검사(04-03). 지금 가이드는 원칙과 반대다.
|
||||
- 목록 조회의 쿼리 수 검사 예시(04-09). testkit 도구는 있는데 sample이 쓰지 않는다.
|
||||
- 낙관적 락 충돌의 표준 처리(04-05).
|
||||
- notification·fileserver처럼 "application leaf가 따로 있는 capability"의 영속 leaf 템플릿: testFixtures 계약, 테스트 위치, CLAUDE.md(04-14, 04-16).
|
||||
- Mongo로 aggregate를 저장하는 예시 한 벌(04-15).
|
||||
|
||||
개발자가 여기서 내려야 하는 판단:
|
||||
|
||||
1. 이 데이터는 독립 aggregate인가, 다른 aggregate의 자식인가. → 독립이면 ID 컬럼, 자식이면 `@ElementCollection` 또는 단방향 `@ManyToOne`(LAZY). 양방향은 쓰지 않는다.
|
||||
2. 같은 행을 동시에 바꿀 수 있는가. → 그렇다면 `@Version`(wrapper `Long`, null = 새 행)을 둔다. bulk UPDATE를 쓰면 version도 올린다.
|
||||
3. "같은 것이 두 번 생기면 안 되는가". → 애플리케이션 조회가 아니라 DB unique 제약으로 막고, upsert는 `ON CONFLICT`로 쓴다.
|
||||
4. 여러 인스턴스가 같은 행을 처리하는가(큐·스케줄러). → claim은 `UPDATE … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED) RETURNING`, 완료는 owner+token 조건 UPDATE. autocommit SELECT FOR UPDATE는 잠그지 않는다.
|
||||
5. 트랜잭션은 누가 여는가. → 유스케이스가 `TransactionPort`로 연다. adapter는 `CallerTransaction.require`만 부른다. 예외는 포트 자체가 원자 단위인 저장 프로토콜뿐이다.
|
||||
6. 목록 조회는 몇 번 쿼리하는가. → 컬렉션을 가진 엔티티를 페이지로 읽으면 N+1이다. projection 포트나 batch fetch를 쓰고 쿼리 수를 테스트로 고정한다.
|
||||
7. 스키마 변경은 새 파일인가. → 적용된 `V*` 파일은 고치지 않는다. 새 버전을 추가하고 `applied-migrations.sha256`에 해시를 추가한다.
|
||||
8. 오류를 클라이언트에 어떻게 알리는가. → adapter에서 잡지 말고 `TransactionPort` 경계 변환에 맡긴다. 업무 의미가 있는 충돌(버전 불일치 등)만 유스케이스가 자기 예외로 바꾼다.
|
||||
|
||||
## 8. 28개 관점 판정표
|
||||
|
||||
기호: O 충족, P 부분, X 미충족, ? 미검증, - 적용 제외, > 다른 영역.
|
||||
|
||||
| 번호 | 관점 | 판정 | 한 줄 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | P | 트랜잭션·fencing 코드는 의도가 드러난다. 갈라진 분류표(04-06)와 adapter 안 정책(04-13)이 남음 |
|
||||
| 2 | 구조적 성숙도 | P | leaf 방향은 레지스트리로 강제됨. adapter가 정책을 소유(04-13), JPA leaf가 플랫폼 라이브러리와 capability 저장소를 함께 가짐 |
|
||||
| 3 | 변경 용이성 | P | SQLState 하나 추가에 두 표 수정(04-06). 마이그레이션은 해시 고정으로 안전 |
|
||||
| 4 | 인지 부하 | P | JPA CLAUDE.md는 상세하나 길고 일부 낡음(S2-#14a). 분리 leaf 2개에 안내 없음(04-16) |
|
||||
| 5 | 위험 가시성 | X | 양방향 금지·bulk version·claim 잠금이 모두 개발자 기억에 의존(04-02·04-03·04-07) |
|
||||
| 6 | 실패 성숙도 | X | 커밋 결과 불명이 재시도 가능으로 나감(04-01), 버전 충돌 500(04-05), 시간 제한 없음(04-10) |
|
||||
| 7 | 운영 성숙도 | P | Hikari·OSIV·DDL·Flyway 위험 설정을 기동 시 거부. timeout 기본값 없음(04-10, 04-12) |
|
||||
| 8 | 디버깅 가능성 | P | 오류 로그에 SQL·파라미터 없음(보호 O). 정상 경쟁이 error 로그(04-05) |
|
||||
| 9 | 유지보수 성숙도 | P | 이력 서술 Javadoc(S2-#12), 중복 표(04-06) |
|
||||
| 10 | 테스트 성숙도 | P | unit 503개·실 PG lane 다수, 그러나 9개 lane 미실행(04-04), 공유 계약 부재(04-14), 쿼리 수 검사 미사용(04-09) |
|
||||
| 11 | 데이터 성숙도 | P | 마이그레이션 불변성 O, unique 제약 누락(04-08), bulk version 누락(04-07) |
|
||||
| 12 | 동시성 성숙도 | P | outbox·recipient·durable operation fencing O. 정산 job 무잠금(04-02), upsert 경합(04-08) |
|
||||
| 13 | 확장성 | P | 다중 인스턴스 claim 패턴 존재, 한 곳 누락(04-02). Mongo 소비 경로 없음(04-15) |
|
||||
| 14 | 성능 성숙도 | P | keyset·상한 제공. sample N+1(04-09), merge 추가 SELECT(04-17). 실측은 안 함 |
|
||||
| 15 | 보안 성숙도 | O | SQL·파라미터 비노출, runtime role 권한 lane, RLS `set_config(…, true)`(트랜잭션 범위), schema provider는 반환 시 search_path 초기화·실패 시 abort |
|
||||
| 16 | 의존성 성숙도 | O | vendor 드라이버 격리 ArchUnit, Mongo 레지스트리 parity 테스트 |
|
||||
| 17 | API / Contract | P | `DB_*` 코드 표 존재. 실제 도달 코드가 계약과 다름(04-01, 04-05) |
|
||||
| 18 | 배포 성숙도 | ? | 마이그레이션 기동 순서·readiness 연계는 코드로 확인. 실제 무중단 배포 실험 없음 |
|
||||
| 19 | 설정 성숙도 | P | 위험 값 기동 거부 O. prefix 분산(P20-new-5 남음), Mongo 주석·코드 불일치(04-12) |
|
||||
| 20 | 개발자 경험 | P | 예시·testkit 풍부. 원칙과 반대인 가이드(04-03), Mongo 예시 없음(04-15) |
|
||||
| 21 | Guardrail | P | 엔티티·노출·audit·마이그레이션 규칙 M3. 연관관계·bulk version 규칙 없음 |
|
||||
| 22 | 추상화 성숙도 | P | `TransactionPort`·`CallerTransaction`은 적절. Mongo 공개 타입 271개 대비 소비자 0 |
|
||||
| 23 | 일관성 | P | 두 분류표(04-06), 두 분리 leaf의 패키지 규칙 상이(04-16), claim 패턴 3종 |
|
||||
| 24 | 네이밍 / 의미 | P | `claimDue`가 잠그지 않음(04-02), `QUOTA_EXCEEDED`를 상태 충돌에 사용(`PF/JpaFileQuota.java:94-96`) |
|
||||
| 25 | 조직 확장성 | P | fileserver 테스트가 JPA leaf에 있어 소유가 섞임(04-14) |
|
||||
| 26 | Ownership | P | 분리 leaf 2개 안내 문서 없음(04-16) |
|
||||
| 27 | 삭제 가능성 | O | `enabled=false`가 Boot 자동설정까지 제외, runtimeOnly 한 줄로 제거 |
|
||||
| 28 | 회복 가능성 | P | completion-unknown 회복 경로가 커밋 단계에서 끊김(04-01). 수신 거부 중복은 수동 정리 필요(04-08) |
|
||||
|
||||
미검증: 18(무중단 배포), 04-02의 업무 중복 효과, 04-11 실 서버 재현, 04-09 실측, JPA 태그 lane과 Mongo 컨테이너 lane의 현재 커밋 실행 결과.
|
||||
@@ -0,0 +1,566 @@
|
||||
# 05. Outbound capability 영역 성숙도 리뷰
|
||||
|
||||
대상 leaf: `adapter:outbound:redis-runtime`, `redis-sdk`, `cache-redis`, `httpclient`, `objectstorage`,
|
||||
`notification`, `fileserver`, `identifier`, `support`, `application-notification`, `application-fileserver`,
|
||||
`application-objectstorage`, `composition:fileserver-platform`, `composition:notification-platform`.
|
||||
|
||||
경로는 `src/`를 생략한다. 패키지 앞부분이 긴 경로는 파일 이름만 적고, 처음 나올 때 leaf를 밝힌다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 | `clean-architecture-backend-template`, 브랜치 `main`, 커밋 `01a8a2a70` |
|
||||
| 확인 시점 | 2026-11-01 |
|
||||
| 목적과 실행 구성 | 템플릿(파생 서비스의 시작점). 기본 조립은 web·support·identifier뿐이고, 이 영역의 나머지는 `app-bootstrap/build.gradle`에 `runtimeOnly` 한 줄로 켜는 선택 모듈이다(`app-bootstrap/build.gradle:162-171`). 다중 인스턴스 배포를 전제로 한 설정(lease, `FOR UPDATE SKIP LOCKED`, Redis 공유 상태)이 있다. |
|
||||
| 규모·운영 목표 | 합의된 SLO·처리량 없음. 그래서 "운영 준비 완료" 판정은 하지 않는다. |
|
||||
| 읽은 범위 | 14개 leaf의 main 코드(약 9.5만 줄) 중 위험 경로: 알림 제출·dispatch·recovery·SES/SMTP·SNS 콜백, 파일 업로드(tus)·복사·다운로드·권한·쿼터, 객체 저장소 S3/local-dev 오류 분류, Redis 캐시·멱등성·rate-limit Lua·연결 lane, HTTP client retry·deadline·circuit breaker·SSRF, support의 module-defaults 로더, identifier. 각 leaf의 README·CLAUDE.md·`config/module-defaults/*.yml`, `AutoConfiguration.imports`, `app-bootstrap`의 관련 설정. 하위 조사 4개(알림, 파일·객체 저장소, Redis, HTTP client·support·identifier)가 코드를 읽었고, High 판정 항목은 리뷰어가 해당 줄을 직접 다시 읽어 확인했다. |
|
||||
| 실행한 것 | ① 오케스트레이터 게이트 결과 읽기: `ci` rc=0(이 영역 14개 leaf `test` 전부 실행·통과), `mainCheck` rc=1(objectstorage MinIO lane 2개 실패, 원인은 이미지 pull 404). ② 변이 실험 2회(별도 worktree, `flock` 잠금): 아래 표. ③ 현재 `build/test-results` XML 집계(ci가 11-01 20:38~20:40에 만든 결과). |
|
||||
| 확인 못 한 것 | Redis 실제 서버 lane(`ca.redis-topology-lane`, explicit-only라 게이트에 없음), HTTP client Toxiproxy lane(`httpClientFailureInjectionTest`, `integrationCheck`에만 있음), MinIO lane(이미지 소멸로 실행 불가), SES/SMTP 실제 발송, 다중 인스턴스 경쟁 실험, 부하 측정. 지난 리뷰의 실행 결과는 증거로 쓰지 않았다. |
|
||||
| 비교 가능한 범위 | techlead 07·08·09, followup-status B·C·D·G·H·S3·S4 그룹과 후속 발견(P·ORCH), 2026-08-14 notification 모듈 리뷰. |
|
||||
|
||||
변이 실험(worktree `wt-05`, 실행 후 원복·삭제):
|
||||
|
||||
| # | 바꾼 코드 | 돌린 테스트 | 결과 |
|
||||
| --- | --- | --- | --- |
|
||||
| M1 | `AppendUploadApplicationUseCase.java:165` 클라이언트 offset 불일치 검사 무력화 | `:application-fileserver:test` (부하 15.7) | 잡힘 — `ResumableUploadUseCasesTest.anOffsetTheClientGuessedWrongIsRejectedWithoutWriting` 실패 |
|
||||
| M2 | `CopyFileApplicationUseCase.java:70-71`, `PrepareDownloadApplicationUseCase.java:53-54`에서 권한 검사에 넘기는 descriptor를 `Optional.empty()`로 (소유자 검사가 사라짐) | `:application-fileserver:test`, `:composition:fileserver-platform:test`, `:adapter:inbound:web-fileserver:test` (부하 8.0) | **살아남음** — 442개 전부 통과 (05-08) |
|
||||
|
||||
테스트 실행 시간(현재 결과, ci 실행분): 14개 leaf 합계 테스트 약 1,790개, 클래스 시간 합 약 63초. 가장 긴 것은 objectstorage 19.4초(`ObjectStorageArchitectureTest`가 대부분), cache-redis 6.5초, httpclient 8.3초. 과하지 않다.
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
상태: 해결 / 남음 / 바뀜(형태가 달라짐) / 일부.
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| B-7d tenant 거부를 SUPPRESS로 보고 | 해결 | `AdminAuthorizationGuard.java:41-49`가 호출 연산의 authority를 인자로 받음 |
|
||||
| B-10a 알림 README·CLAUDE.md "R0 legacy" | 남음 | `adapter/outbound/notification/README.md:1,3`, `CLAUDE.md:15,23` |
|
||||
| B-10b application-notification CLAUDE.md 없음 | 남음 | `application-notification/`에 `build.gradle`·`src`만 |
|
||||
| B-10c / C-12c / D-11c / G-12b CLAUDE.md "Boot 4.0.0" | 남음 | notification `CLAUDE.md:8`, fileserver `CLAUDE.md:8`, objectstorage `CLAUDE.md:8`, cache-redis `CLAUDE.md:8`, identifier `CLAUDE.md:8`(새로 확인) |
|
||||
| B-10d / S1-#19 / S3-#11 / S4-#16a·b inline FQN·이력 주석 | 남음(줄어듦) | notification main FQN 약 93줄, objectstorage 약 60줄, httpclient 약 59줄. 예: `LeaseRecoveryService.java:103-104`, `RedisCacheRegionAdapter.java:262-266` |
|
||||
| S1-#20 notification `dispatch/` 46파일 | 남음 | 제출·템플릿·ContactPoint·reconciliation이 한 패키지 |
|
||||
| S4-#3a 미조립 provider 5종 삭제 | 일부 | adapter는 삭제(`ProviderType`은 SES·SMTP만). `ApnsDeviceToken`, `FcmInstallationId`, `WebPushContent` 같은 contact/content 타입은 남음 |
|
||||
| S4-#3b SES projector 연결 | 해결 | `NotificationPlatformRegistriesConfig.java:39` `StandardDeliveryProjector` |
|
||||
| S4-#17b `*ProviderProperties` 이름 | 남음 | `SesProviderProperties`·`SmtpProviderProperties`는 바인딩 대상이 아닌 record |
|
||||
| SesSuppressionUpdater dead code | 해결(삭제) | suppression은 `ProviderEventProjectionService.java:84-88` |
|
||||
| ORCH-new-2 알림 계약 테스트 inputs 미선언 | 남음(범위 넓어짐) | `NotificationPayloadAtRestContractTest`와 ReleaseGate·LegacyNamespaceRetirement·ModeSsot 테스트가 저장소 파일을 읽지만 `notification/build.gradle`에 `inputs` 없음 |
|
||||
| 결정 13 category 생략 → 400 | 해결(위치 다름) | 유스케이스가 아니라 `AcceptNotificationCommand.java:71-72`에서 거부 |
|
||||
| 결정 21 provider profile 소실 → 일반 재시도 후 FAILED | 해결 | `NotificationDispatchService.java:170-176, 249-286` |
|
||||
| C-10 / S2-#11 fileserver 경쟁 SQL leaf 테스트 0 | 바뀜 | leaf 안에는 여전히 없음. 실제 SQL은 `persistence-jpa`의 `PostgreSqlFileserverMetadataStoreIntegrationTest:107,258,283,313`(Testcontainers)이 검증 |
|
||||
| C-12b composition 주석 drift | 남음 | `composition/fileserver-platform/build.gradle:8-10` |
|
||||
| C-12c fileserver "default off" | 남음 | `adapter/outbound/fileserver/CLAUDE.md:19`, `README.md:17` vs `fileserver.yml`의 `enabled: true` |
|
||||
| D-4 staged kernel·handoff 동작 테스트 | 대부분 해결 | `StagedObjectPublicationLifecycleTest`(666줄), `ObjectPublicationHandoffRaceTest`. `StagedObjectPublicationKernelTest`는 이름과 달리 verdict policy만 봄 |
|
||||
| D-7a direct·multipart 업로드 코드 | 해결(삭제) | 해당 클래스 없음 |
|
||||
| D-11a~e objectstorage 문서 drift | 남음 | `objectstorage/CLAUDE.md:8,19,21`, `README.md:18-19`, `LocalDevObjectDataStore.java:77` |
|
||||
| P4-new-1 fileserver migration 불변성 테스트 | 해결 | `AppliedMigrationImmutabilityTest.java:43-45` manifest에 V1~V5 |
|
||||
| P14-new-5 application-objectstorage testFixtures 없음 | 남음 | testFixtures 디렉터리 없음, `PosterImagePublicationWorkflowTest.java:253` 자체 fake |
|
||||
| P30-new-3 local-dev create-only가 JVM 단위 | 일부 | `LocalObjectPathGuard.java:37-39,157-170`에 범위가 적힘. 동시 생성 테스트 없음 |
|
||||
| S5-#14c web-fileserver README·CLAUDE.md 없음 | 남음 | 디렉터리에 `*.md` 0개 |
|
||||
| S3AsyncResponseBodyBridgeTest 간헐 실패 | 개선, 위험 남음 | sleep 제거·1분 상한. `:40-41` await 없는 `shutdownNow`, `:84` 비동기화 `ByteArrayOutputStream` |
|
||||
| G-2b fake가 rate-limit HDEL/PEXPIRE 미흉내 | 일부 | 고정 필드 구조로 HDEL 불필요, 실제 Redis 필드 수 단언 추가(`LiveRedisSemanticPortsTest.java:242-255`). fake는 여전히 PEXPIRE 무시(`InMemorySemanticRedisCommands.java:395-475`) |
|
||||
| G-4j env-keys "Replaced by"가 없는 키 | 남음 | `docs/registries/env-keys.yaml:1428, 1460` |
|
||||
| G-5b redis-runtime README·CLAUDE.md 없음 | 남음 | 디렉터리에 `build.gradle`·`src`만 |
|
||||
| G-12c `src/README.md` orphan Redis 키 | 남음 | `src/README.md:312-320`(`external` client-mode는 존재하지 않음) |
|
||||
| G-12d cache-redis README 테스트 명령 | 해결 | `cache-redis/README.md:230-234` |
|
||||
| G-12e runtime 키의 owner_module | 일부 | runtime이 바인딩하는 22개 키의 owner가 아직 cache-redis |
|
||||
| S1-#3b lease 호출자 0 / 결정 8 공통 계약 | 일부 | `DistributedLeaseContract`(testFixtures)를 in-memory·Redis·live Redis가 상속. lock+lease 공통 계약은 없음 |
|
||||
| S2-lead-2 멱등성 공통 계약 테스트 | 남음 | `application-core/src/testFixtures/.../idempotency/testkit/`에 `InMemoryIdempotencyStore`뿐 |
|
||||
| S3-#12a `CacheKeys` 가변 generation, `KeyDigest` 위치 | 남음 | `RedisCacheRegionAdapter.java:352-354`, `capability/RedisKeys.java` |
|
||||
| S3-#12b CLAUDE.md "legacy cache router" | 남음 | `cache-redis/CLAUDE.md:22` |
|
||||
| S3-#13c Redis health indicator 중복 | 남음 | `RedisRuntimeAutoConfiguration.java:276-288`, `:308-331` |
|
||||
| ORCH-new-4 redis-sdk 테스트 경로·inputs | 일부 | 경로 수정됨(`RedisSdkModuleBoundaryTest:181`). `inputs` 미선언, `RedisSupportMatrixTest`에 document-contract 태그 없음 |
|
||||
| P13-new-2 local-redis lane 기동 WARN | 남음 | `RedisRuntimeSettings.java:207,215` WARN 2줄과 `run-compose-runtime-smoke.sh:520-522` 무음 검사 충돌 |
|
||||
| P20-new-3 sample 죽은 키 | 남음 | `sample-portfolio/src/main/resources/application.yml:254-273`(`app.cache.redis.*`), `:286-287`(`app.outbound.http.*`) |
|
||||
| H-3d `DefaultDynamicTargetGateway.exchange` 테스트 0 | 해결, 공백 남음 | `DefaultDynamicTargetGatewayTest` exchange 7건. 사설 IP로 resolve되는 hop 거부는 exchange 경로로 미검증 |
|
||||
| H-10a / P20-new-4 README httpclient 절 | 남음 | `src/README.md:337-365`가 `app.capabilities.http-client`·`bindLegacy`를 설명(코드에 0건) |
|
||||
| S3-#1 / H-5 / H-7 reactive 스택 (결정 9) | 해결 | src·build.gradle·lockfile에 webflux·reactor 0건 |
|
||||
| S3-#13a Jackson 2 사용 | 남음 | `RemoteProblemDecoder.java:3-4`, `httpclient/build.gradle:56,64` |
|
||||
| P11-new-2 `verify-httpclient-docs.py` 경로 | 남음 | `scripts/verify-httpclient-docs.py:22,64`. `.github/workflows/release.yml:188`에서 실행되므로 release 작업이 실패한다 |
|
||||
| P11-new-3 FailureInjection lane이 docker-proxy에 의존 | 수정됨, 미실행 | `FailureInjectionContractTest.java:53-68` 루프백 거부 방식. 이번 게이트에 이 lane 없음 |
|
||||
| S3-#6 `HttpClientTagPolicy` | 해결 | `HttpClientTagPolicy.java:32` |
|
||||
|
||||
지난 발견 중 남은 High/P1은 없다. 남은 것은 대부분 W5(문서·Nit)와 W4(테스트 규칙)다. 다만 W4 중 "공통 포트 계약 테스트 없음"(S2-lead-2, P14-new-5)은 이번 새 발견 05-02·05-16과 직접 연결된다.
|
||||
|
||||
## 3. 새 발견
|
||||
|
||||
심각도 분포는 문서 끝 「발견 요약」에 있다. High는 전체 양식으로, Medium·Low는 필요한 필드만 쓴다. 설계 선택이 아닌 단순 결함은 "대안 비교: 적용 제외 — 이유"로 둔다.
|
||||
|
||||
### 05-01 알림 attempt를 "요청 시작 안 함(확정)"으로 저장한 채 provider를 호출한다 — 워커가 발송 중 죽으면 같은 알림이 다시 나간다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 1, 5, 6, 10, 11, 12, 28 |
|
||||
| 근거 | ① `application-notification/.../dispatch/DeliveryAttemptFactory.java:54-56` — attempt 행을 처음 만들 때 `ProviderExecutionEvidence.notStarted()`(값 false, 확실성 PROVEN). ② `NotificationDispatchService.java:189-199` 이 행을 insert하고, `:201` lease 확인 뒤 `:215` `submitOutsideTransaction`이 provider를 부른다. 그 사이에 evidence를 바꾸는 쓰기가 없다(`requestStarted`를 쓰는 곳은 insert `JpaDeliveryAttemptStore.java:80-83`과 완료 기록 `:288-291`뿐). ③ `LeaseRecoveryService.java:101-106` `provablyNeverStarted`가 PROVEN+false면 true, `:134-136`이 그 경우 reconcile 없이 `READY_TO_DISPATCH`로 되돌린다. 리뷰어가 세 곳 모두 직접 읽었다. |
|
||||
| 발생 조건 | SES/SMTP 호출 중 pod가 SIGKILL·OOM으로 죽는다. 또는 shutdown-grace(20s)를 넘긴다. 또는 워커가 lease 만료(`lease-duration` 2m, `NotificationDeliveryConfiguration.java:131`에서 staleAfter로도 쓰임)를 넘겨 멈춘다. |
|
||||
| 영향 | recovery가 그 수신자를 다시 큐에 넣고 다른 워커가 같은 메일을 다시 보낸다. 늦게 깨어난 첫 워커의 결과 기록은 fence로 버려진다. 이 경로는 `LeaseRecoveryService` 주석과 `allow-ambiguous-fallback: false` 설정이 막겠다고 한 바로 그 경우다. |
|
||||
| 심각도·우선순위 | High / P1. 가이드 35.2의 "결과 불명 작업의 무방비 재실행"에 해당한다. 기본 구성(SERVING, 다중 인스턴스)에서 프로세스 중단만으로 도달한다. 금전 피해는 아니므로 Critical은 아니다. 템플릿 기본값이라 파생 서비스로 그대로 복제된다. |
|
||||
| 확실성 | 코드 경로는 확인(E1). 실제 crash 재현은 하지 않았다. |
|
||||
| 테스트가 못 잡는 이유 | `LeaseRecoveryServiceTest.java:241-247`과 `PostgreSqlNotificationBackgroundPassIntegrationTest.java:370`이 attempt를 factory가 아니라 직접 만들어 넣는다. factory → crash → recovery를 잇는 테스트가 없다. |
|
||||
| 결정의 근거 | 코드 주석은 "호출 전에는 아무것도 시작 안 됨이 증명된 사실"이라고 적는다. 행을 insert한 순간에는 맞지만, 그 행이 호출이 끝날 때까지 그대로 남는다는 점이 빠졌다. "증명"은 insert 시점에만 참이다. |
|
||||
| 최소 개선 방향 | factory가 `requestStarted = UNKNOWN`으로 행을 만든다. "확정 미시작"은 `closedBeforeSubmission`(`:205-211`)이나 adapter가 돌려준 `ProviderCallNotStartedException` 결과로만 기록한다. |
|
||||
| 대안 비교 | (a) 위 방법: 쓰기 추가 없음, crash 시 항상 reconcile. SMTP처럼 상태 조회가 없는 provider는 운영자 대기로 간다. (b) insert는 미시작 확정으로 두고 호출 직전에 UNKNOWN으로 갱신하는 쓰기를 추가: 트랜잭션 한 번 더, insert~갱신 사이 crash만 안전 requeue. (c) 현상 유지: 중복 발송 허용. (a)를 고른다. (b)가 얻는 것은 "insert 직후 crash" 한 구간의 requeue뿐이고 쓰기가 늘어난다. |
|
||||
| 단순화의 보존 조건 | 행이 없을 때의 requeue(`:117-122`)와 완료된 attempt의 requeue(`:124-133`)는 유지한다. |
|
||||
| 완료 기준 | factory로 만든 attempt를 recovery에 넣으면 reconcile 경로를 탄다. |
|
||||
| 검증 방법 | `LeaseRecoveryServiceTest`에 `DeliveryAttemptFactory.create(...)`로 만든 미완료 attempt → `recoverOnce()` → `reconciled`에 포함, `transitions` 비어 있음. Postgres lane에서 같은 흐름 1건. |
|
||||
|
||||
### 05-02 Redis 멱등성 `renew()`가 처리 lease를 연장하지 못한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(현재 호출자 없음 — 잠복) |
|
||||
| 관련 관점 | 1, 10, 12, 17 |
|
||||
| 근거 | `cache-redis/.../idempotency/RedisIdempotencyStoreAdapter.java:183-190` renew를 `Transition("EXECUTING", "EXECUTING", …, leaseMillis, …)`로 보낸다. `IdempotencyScripts.java:101-108`은 revision·from 상태를 보기 전에 `state == ARGV[5]`(목표 상태)면 `ALREADY`를 반환한다. 현재 상태가 EXECUTING이면 renew는 항상 이 분기에 걸리고 `leaseUntil` 갱신(`:122-126`)에 닿지 않는다. fake도 같은 순서라 버그를 따라 한다(`InMemorySemanticRedisCommands.java:258-263`). main 코드에 `renew(` 호출자는 없다(grep). 리뷰어가 Lua를 직접 읽었다. |
|
||||
| 발생 조건 | 파생 서비스가 30초(기본 processing lease)보다 긴 작업에서 renew로 lease를 늘린다. |
|
||||
| 영향 | renew는 `ALREADY_RENEWED_SAME_OPERATION`(성공처럼 보이는 값)을 돌려주고 lease는 그대로 만료된다. 다른 요청이 `TAKEN_OVER`로 가져가 같은 부작용을 두 번 실행한다. |
|
||||
| 심각도·우선순위 | High / P1. 공개 포트의 계약이 조용히 깨져 있고 성공 값으로 숨는다. 템플릿 안에 호출자가 없어 지금 피해는 없지만, 쓰는 순간 중복 실행이다. |
|
||||
| 결정의 근거 | 적용 제외 — "같은 상태로의 전이"를 재시도 응답으로 해석한 Lua 분기 순서의 단순 결함이다. |
|
||||
| 최소 개선 방향 | Lua에서 `ARGV[4] ~= ARGV[5]`일 때만 ALREADY 분기를 탄다. fake도 같이 고친다. |
|
||||
| 완료 기준 | renew 후 lease가 연장되고, 다른 owner의 claim이 `IN_PROGRESS`를 받는다. |
|
||||
| 검증 방법 | application-core testFixtures에 멱등성 공통 계약(`IdempotencyStoreContract`)을 만들고 in-memory·Redis fake·live Redis·PostgreSQL store가 상속한다(S2-lead-2와 같은 작업). renew 정상 경로 케이스를 넣는다. |
|
||||
|
||||
### 05-03 캐시 `ONLY_IF_SOURCE_REVISION_NEWER`가 조건 없이 덮어쓴다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 1, 5, 11, 17 |
|
||||
| 근거 | `application-core/.../cache/CacheRecordIntent.java:8`이 이 intent를 공개한다. `cache-redis/.../cache/RedisCacheRegionAdapter.java:238-253`은 `ONLY_IF_OBSERVED`만 Lua CAS로 보내고, 나머지는 `presenceOf`(`:262-266`)로 보낸다. `presenceOf`는 `ONLY_IF_ABSENT`가 아니면 `ALWAYS`다. `sourceRevision`은 envelope에 저장만 하고(`:229`) 비교하지 않는다. 이 intent를 쓰는 테스트는 없다. 리뷰어가 직접 읽었다. |
|
||||
| 발생 조건 | 호출자가 "원본 revision이 더 새로울 때만 기록"을 요청했는데, 늦게 끝난 loader가 옛 revision으로 기록한다. |
|
||||
| 영향 | 새 값이 옛 값으로 덮인다. 결과는 `RECORDED`라 호출자는 조건이 지켜졌다고 믿는다. hard TTL(5분) 동안 옛 값을 읽는다. |
|
||||
| 심각도·우선순위 | High / P1. 호출자가 명시한 일관성 조건을 성공 응답으로 무시한다. 지원하지 않으면 거부해야 할 계약이다. |
|
||||
| 결정의 근거 | 적용 제외 — enum 값 하나의 구현 누락이다. |
|
||||
| 최소 개선 방향 | `ONLY_IF_OBSERVED`처럼 Lua로 envelope의 revision을 비교하고 교체한다. 당장 구현하지 않으면 이 intent에 `NOT_RECORDED_CONDITION`이 아니라 명시적 미지원 예외를 던진다. |
|
||||
| 완료 기준 | 더 작은 revision의 기록은 `NOT_RECORDED_CONDITION`, 큰 revision은 `RECORDED`. |
|
||||
| 검증 방법 | application-core testFixtures에 `CacheRegionContract`를 만들고 fake와 Redis adapter가 같은 표를 통과한다. |
|
||||
|
||||
### 05-04 캐시 무효화와 느린 loader의 경합, stampede 보호 없음, 문서는 jitter를 주장
|
||||
|
||||
- 성격: 구조적 위험(경합 결과는 추론). 관점 1, 5, 12, 14.
|
||||
- 근거: Miss는 항상 `CacheWriteCondition.unavailable()`을 돌려준다(`RedisCacheRegionAdapter.java:135,169,173`). `invalidate`는 `GETDEL` 하나다(`:277`). single-flight, early refresh, TTL jitter 구현은 없다(grep 0건). 그런데 `cache-redis/CLAUDE.md:17-18`은 "deterministic bounded jitter"를 구현했다고 적는다. region 무효화 반영은 generation 재확인 주기가 softTtl(30s)과 같아 인스턴스 간에 최대 30초 늦는다(`:316`, 테스트가 이 지연을 고정: `RedisCacheRegionAdapterTest.java:237-240`).
|
||||
- 발생 조건: 미스 → 원본에서 옛 값 로드 중 → 다른 요청이 invalidate → `UPSERT`/`ONLY_IF_ABSENT`로 옛 값 재기록. 인기 키 만료 순간 동시 미스.
|
||||
- 영향: 무효화 직후 옛 값이 최대 hard TTL(5분) 남는다. 동시 미스가 모두 원본을 친다.
|
||||
- 심각도·우선순위: Medium / P2. 캐시 사용처가 템플릿에 없고, 05-03을 고치면 revision 비교로 첫 시나리오를 막을 수단이 생긴다.
|
||||
- 최소 개선 방향: 고른 방법 — invalidate를 key 단위 tombstone(짧은 TTL, 이전 revision 기록 거부)으로 바꾸고 Miss에도 observation token을 돌려준다. 버린 대안 — 분산 lock 기반 single-flight: Redis 왕복과 lock 만료 처리가 늘고, 대부분의 캐시에는 tombstone+CAS로 충분하다. stampede는 문서에 "보호 없음, 호출자가 single-flight 책임"을 적거나 로컬 single-flight를 붙인다. CLAUDE.md의 jitter 문장은 지운다.
|
||||
- 완료 기준: "invalidate 후 옛 loader의 기록이 거부된다" 계약 케이스 통과.
|
||||
|
||||
### 05-05 HTTP client: 4xx 응답이 circuit breaker 실패로 집계된다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6, 7, 17, 19 |
|
||||
| 근거 | `httpclient/.../restclient/BlockingResponseMapper.java:72-76` THROW_ON_ERROR(기본)에서 2xx가 아니면 `HttpRemoteErrorException`. `BlockingAttemptExecutor.java:95-100`이 이를 `REMOTE_STATUS`로 만들고, `:111-114`가 REMOTE_STATUS면 breaker에 실패로 넘긴다. `resilience/AttemptResiliencePipeline.java:104-106` `circuitBreaker.onError`. breaker는 `ResilienceRegistry.java:37-41` `CircuitBreakerRegistry.ofDefaults()`라 모든 예외를 실패로 센다. breaker 임계값·창·대기 시간을 바꾸는 설정 키는 없다. 리뷰어가 직접 읽었다. |
|
||||
| 발생 조건 | 조회 API가 정상적으로 404/409/422를 많이 돌려준다(라이브러리 기본: 최소 100회 중 50% 실패). |
|
||||
| 영향 | breaker가 열리고 그 profile의 모든 호출이 기본 60초 동안 `HttpCircuitOpenException`으로 거부된다. 상대 서버는 건강하다. |
|
||||
| 심각도·우선순위 | High / P1. 상대가 정상인데 기능 전체가 멈춘다. 프로젝트가 고칠 설정 키도 없다. |
|
||||
| 결정의 근거 | 적용 제외 — 실패 분류 기준의 누락이다. 업계 관행(5xx·timeout만 실패)과 다를 이유가 코드·문서에 없다. |
|
||||
| 최소 개선 방향 | 5xx·408·429와 전송 실패만 `onError`, 그 밖의 4xx는 `onSuccess`(또는 ignore)로 기록한다. profile별 breaker 설정(임계값·최소 호출 수·대기 시간)을 `app.httpclient.clients[n].circuit-breaker.*`로 노출한다. |
|
||||
| 완료 기준 | 404 응답 200회 뒤에도 breaker가 CLOSED. |
|
||||
| 검증 방법 | `AttemptResiliencePipeline` 단위 테스트에 상태 코드 표(`@ParameterizedTest`). |
|
||||
|
||||
### 05-06 HTTP client: 전체 시간 예산이 진행 중인 attempt를 끊지 못한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6, 7, 14, 17 |
|
||||
| 근거 | transport timeout은 profile 고정값(connect 0.5s, 응답 헤더 2s, read idle 3s)이고 남은 deadline으로 줄이지 않는다(`apache/ApacheClientFactory.java:74,79-80,129`). main에 `cancel(`/`abort(` 호출이 없다. deadline 검사는 attempt 시작 전에만 있다(`DefaultGenericHttpGateway.java` `attempt()`). JDK transport는 read idle을 쓰지 않는다(`jdk/JdkBlockingTransportProvider.java:66`). README는 "One effective deadline covers … read"라고 적는다. |
|
||||
| 발생 조건 | 상대가 바이트를 3초보다 짧은 간격으로 조금씩 보낸다(slow drip). 또는 JDK transport로 body가 멈춘다. |
|
||||
| 영향 | `totalCall` 4초를 무제한 넘긴다. 호출 스레드(virtual thread)와 pool 연결(기본 50)이 묶인다. 호출자의 요청 deadline이 깨진다. |
|
||||
| 심각도·우선순위 | High / P1. 31절 "외부 응답 지연" 시나리오의 핵심 계약(대기 제한)이 문서와 다르다. |
|
||||
| 결정의 근거 | 적용 제외 — 문서가 약속한 성질의 구현 누락. |
|
||||
| 최소 개선 방향 | attempt마다 `min(stage timeout, 남은 deadline)`으로 RequestConfig를 만들고, 남은 시간이 끝나면 요청을 취소(Apache `cancel`, JDK `CompletableFuture` timeout)한다. |
|
||||
| 완료 기준 | slow-drip 서버에 대해 호출이 `totalCall + 작은 오차` 안에 끝난다. |
|
||||
| 검증 방법 | Toxiproxy `slicer`/`latency` toxic으로 `httpClientFailureInjectionTest`에 케이스 추가, 이 lane을 `mainCheck`에 포함(05-16). |
|
||||
|
||||
### 05-07 파일 서버: copy가 디스크 수위 검사를 우회하고, 쿼터는 기록만 한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6, 13, 14, 15, 28 |
|
||||
| 근거 | `application-fileserver/.../lifecycle/CopyFileApplicationUseCase.java:66-103`에 admission(디스크 high-water)도 quota도 없다. 대상 namespace는 요청 본문에서 온다(`web-fileserver/.../FileLifecycleController.java:88,109`). 업로드 쪽 쿼터도 상한을 비교하지 않는다(`persistence-fileserver/.../JpaFileQuota.java:21-30`), 범위는 namespace 단위(`CreateUploadApplicationUseCase.java:100-102`)이고 commit은 예약보다 큰 값을 받는다(`JpaQuotaCommit.java:37-52`). 리뷰어가 copy 경로를 직접 읽었다. |
|
||||
| 발생 조건 | `file:copy` 권한을 가진 사용자가 큰 파일을 반복 복사한다. |
|
||||
| 영향 | 업로드는 high-water(0.85)에서 멈추지만 copy는 그 선을 넘어 볼륨을 끝까지 채운다. 그 뒤 모든 사용자의 업로드·복사가 실패한다. 같은 볼륨을 쓰는 다른 프로세스도 영향을 받을 수 있다. |
|
||||
| 심각도·우선순위 | High / P1. 인증된 사용자 하나로 서비스 전체 쓰기가 멈춘다. 기본 역할 `ROLE_FILE_WRITE`가 `file:copy`를 포함한다(`app-bootstrap/.../config/security.yml:58`). |
|
||||
| 결정의 근거 | 사용자별 쿼터를 둘지는 서비스 정책이다(0.2절). 하지만 "디스크를 다 채우지 않는다"는 템플릿이 지켜야 할 안전한 기본값이고, 업로드 경로는 이미 지킨다. copy만 빠졌다. |
|
||||
| 최소 개선 방향 | copy에 `admissionController.acquireUpload`와 `quotaService.reserve`를 넣는다. 대상 namespace는 policy 허용 목록으로 제한한다. 쿼터 상한 강제(principal/tenant 범위)는 별도 결정으로 분리한다. |
|
||||
| 대안 비교 | (a) copy에 admission만 추가: 볼륨 고갈은 막고 사용자 간 공정성은 남는다. (b) (a) + 쿼터 상한: 공정성까지, 쿼터 정책 결정 필요. (c) copy 기능을 서버 측 링크(참조 카운트)로: 바이트가 늘지 않지만 삭제·정리 모델이 바뀐다. 최소 변경은 (a), 템플릿 기본값으로는 (b)를 권장. |
|
||||
| 완료 기준 | high-water 이상에서 copy가 거절된다. |
|
||||
| 검증 방법 | `FileLifecycleUseCasesTest`에 수위 초과 fake admission으로 copy 거절 케이스. |
|
||||
|
||||
### 05-08 파일 서버: 소유자 검사를 지워도 테스트가 하나도 실패하지 않는다
|
||||
|
||||
- 성격: 확인된 결함(테스트 공백). 관점 10, 15, 21.
|
||||
- 근거: 변이 M2. `CopyFileApplicationUseCase.java:70-71`과 `PrepareDownloadApplicationUseCase.java:53-54`에서 descriptor를 `Optional.empty()`로 바꾸면 `RoleBasedFileAccessPolicy.java:65`(`descriptor.isPresent() && …`)가 소유자 검사를 건너뛴다. application-fileserver·composition·web-fileserver 테스트 442개가 모두 통과했다(E2). 원인은 `application-fileserver/src/test/.../testkit/FakeFileAccessPolicy.java:22-28`이 descriptor를 무시하고 연산만 기록하는 것이다. 소유자·tenant 판정은 `RoleBasedFileAccessPolicyTest:133,164,187`에만 있다.
|
||||
- 발생 조건: 누군가 use case를 고치다 descriptor를 빼먹는다. `DownloadDescriptor`는 public record라 새 inbound 경로가 권한 검사 없이 `OpenDownloadContent`를 부를 수도 있다(`OpenDownloadContentApplicationUseCase.java:38-40`).
|
||||
- 영향: 다른 사용자의 파일 다운로드(31절 "다른 사용자 리소스 접근")가 회귀해도 게이트가 통과한다.
|
||||
- 심각도·우선순위: Medium / P1. 지금 코드는 안전하지만 인가 회귀를 막는 장치가 없다.
|
||||
- 최소 개선 방향: fake가 받은 descriptor를 기록하고, use case 테스트마다 "descriptor.owner == record owner"를 단언한다. COPY·MOVE·READ_METADATA 거부 테스트를 추가한다.
|
||||
- 완료 기준: M2 변이가 죽는다.
|
||||
|
||||
### 05-09 객체 저장소: MinIO 이미지 공급원이 사라져 mainCheck가 빨갛다
|
||||
|
||||
- 성격: 확인된 결함(외부 공급원 의존). 관점 7, 10, 16, 18, 28.
|
||||
- 근거: `mainCheck` rc=1. `objectStorageMinioContractTest`, `objectStorageMinioFaultTest`가 `ContainerFetchException`(pull 404, "repository does not exist"). 같은 머신에서 `alpine:3`은 받아졌다(오케스트레이터 확인). 이미지 고정이 네 곳에 복사돼 있다: `MinioManagedObjectContractTest.java:52`, `MinioManagedObjectFaultTest.java:37-39`, `minio-provider-evidence.json:5`(test·integrationTest 두 벌, 내용 동일), 그리고 compose가 다른 태그를 쓴다(`docker-compose.infra.yml:183,425` `minio/minio:RELEASE.2024-09-13…`). 고정된 버전(2024-01-16)의 evidence는 `status: UNSUPPORTED`이고 create-only 계열 5개 프로필을 제외한다(`minio-provider-evidence.json`의 `excludedProfiles`, `limitations`). lane은 `rejectSkipped = true`로 fail-closed다(`objectstorage/build.gradle:85-103`), `mainCheck`가 둘 다 요구한다(`:123-125`).
|
||||
- 발생 조건: Docker Hub 저장소 삭제·비공개 전환·rate limit. 이번이 실제 사례다.
|
||||
- 영향: main 브랜치 게이트가 코드와 무관하게 실패한다. 이 영역의 유일한 실제 S3 벤더 증거(완료 기준 5)가 사라진다. local compose 개발 환경도 같은 공급원을 쓴다.
|
||||
- 심각도·우선순위: Medium / P1. 데이터 피해는 없지만 main 게이트가 막혀 있어 다른 회귀를 가린다.
|
||||
- 게이트가 어떻게 반응해야 하는가: 지금처럼 skip하지 않고 실패하는 것은 맞다(조용히 skip하면 벤더 증거가 없는데 초록이 된다). 부족한 것은 두 가지다. ① 실패 이유가 "코드 결함"인지 "공급원 소멸"인지 메시지로 구분되지 않는다. lane 시작 전에 이미지 pull을 별도 단계로 두고, 실패하면 "pinned image unavailable: <digest>"로 실패시킨다. ② 공급원이 사라졌을 때 바꿀 곳이 네 군데다. 이미지 참조를 `minio-provider-evidence.json` 하나에서 읽게 하고 compose도 같은 값을 쓰게 한다.
|
||||
- 대안 비교:
|
||||
|
||||
| 후보 | 얻는 것 | 비용·위험 | 판단 |
|
||||
| --- | --- | --- | --- |
|
||||
| (a) 같은 digest를 조직 레지스트리(GHCR/ECR)에 미러하고 거기서 받기 | 공급원 소멸에 영향받지 않음, digest 그대로라 evidence 유효 | 미러 운영(최초 push, 보존 정책), 원본 digest를 아직 가진 곳이 있어야 함(로컬 캐시·CI 캐시) | 1순위. 원본 digest를 확보할 수 있으면 증거 연속성을 지킨다 |
|
||||
| (b) 같은 제작사의 다른 레지스트리(예: `quay.io/minio/minio`) | 코드 변경 최소 | 그 레지스트리도 같은 이유로 사라질 수 있음. digest가 같은지 확인 필요. 이번 리뷰에서 가용성 미확인 | (a)가 불가능할 때 임시 |
|
||||
| (c) 커뮤니티 fork·재배포 이미지(예: Chainguard 등) | 계속 유지되는 공급원 | 다른 빌드라 evidence 재작성 필요, S3 조건부 쓰기 동작이 다를 수 있음 | evidence 재측정을 감수할 때 |
|
||||
| (d) 다른 S3 호환 구현(SeaweedFS, Garage, LocalStack S3, Ceph RGW) | MinIO 의존 제거 | `If-None-Match`·`If-Match` 의미가 구현마다 다름. 계약 lane의 판정 기준(create-only 지원 여부)을 다시 정해야 함 | 장기 선택지. 단기 복구 수단은 아님 |
|
||||
| (e) lane을 explicit-only로 내리고 mainCheck에서 빼기 | 게이트 즉시 초록 | 실제 벤더 증거 0개가 됨(기준 5 위반) | 기각 |
|
||||
|
||||
후보의 현재 가용성은 외부 접속 금지 규칙 때문에 확인하지 않았다.
|
||||
- 완료 기준: 이미지 참조 한 곳, 미러 또는 대체 공급원에서 두 lane 통과, 공급원 실패 시 이유가 구분되는 메시지.
|
||||
|
||||
### 05-10 알림: collapse 미지원 예외가 try 밖에서 터져 끝없이 재시도된다
|
||||
|
||||
- 성격: 확인된 결함. 관점 6, 7, 11.
|
||||
- 근거: `NotificationDispatchService.java:331` `requireCollapseSupported`가 `new ProviderSubmission(...)` 인자를 만드는 중에 실행되고, `try`(`:334`)보다 앞이다. 던진 `ProviderCallNotStartedException`(`:355-359`)이 dispatch 밖으로 나가고 attempt는 DISPATCHING으로 남는다. 05-01 때문에 recovery가 이 행을 "확정 미시작"으로 보고 다시 큐에 넣는다. collapse는 HTTP 요청으로 들어온다(`web-notification/.../SubmitNotificationHttpRequest.java`). 템플릿의 provider(SES·SMTP)는 둘 다 collapse를 지원하지 않는다.
|
||||
- 영향: collapse를 지정한 요청은 약 lease 주기마다 같은 실패를 반복한다. attempt 행이 계속 늘고 재시도 한도도, FAILED 종료도 없다.
|
||||
- 심각도·우선순위: Medium / P2. 발송은 일어나지 않는다. 대신 독이 든 요청 하나가 영구히 워커를 쓴다.
|
||||
- 최소 개선 방향: collapse 확인을 attempt insert 전, `failBeforeAttempt` 경로(`:167-187`)로 옮긴다. 05-01을 고치면 루프는 reconcile로 바뀌지만 원인은 여기서 고쳐야 한다.
|
||||
|
||||
### 05-11 알림: SMTP 실패가 전부 "결과 불명"이 되어 재시도 없이 운영자 대기로 멈춘다
|
||||
|
||||
- 성격: 확인된 결함. 관점 6, 7, 8.
|
||||
- 근거: `adapter/outbound/notification/.../provider/smtp/JavaMailSenderSmtpDispatch.java:44-52`가 모든 `MailException`을 `replyCode=empty, dataCommitted=true`로 감싼다. 그래서 `SmtpFailureClassifier.java:49-75`의 4xx/550 분기는 운영 경로에서 실행되지 않는다. SMTP는 상태 조회가 없어 reconcile은 `Unsupported` → `RECONCILIATION_REQUIRED`(`ReconciliationService.java:122-127,148-159`).
|
||||
- 영향: 릴레이 다운·인증 실패·잘못된 수신자처럼 "보내지 않은 것이 확실한" 실패도 재시도되지 않고 운영자가 하나씩 처리해야 한다.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 최소 개선 방향: nested `SMTPSendFailedException`·`SMTPAddressFailedException`의 return code를 꺼낸다. `MailAuthenticationException`과 connect 실패는 `dataCommitted=false`. 같은 성격으로 SES 사전 오류(`SesNotificationProviderAdapter.java:107-138`, `SesRequestMapper.java:99`)를 `ProviderCallNotStartedException`으로 감싼다.
|
||||
- 검증: 실제 `JavaMailSender` 예외를 넣는 분류 테스트, GreenMail 같은 실제 SMTP 컨테이너 테스트 1건(기준 5).
|
||||
|
||||
### 05-12 파일 서버: tus PATCH가 쓰기를 커밋한 뒤 `file:read`를 요구한다
|
||||
|
||||
- 성격: 확인된 결함. 관점 1, 15, 17.
|
||||
- 근거: `web-fileserver/.../TusController.java:171-181` append(`file:upload`) 커밋 후 `:183` `status.handle(...)` 호출. `GetUploadStatusApplicationUseCase.java:28` `@RequiresPermission("file:read")`. 기본 역할은 상속하지 않는다(`security.yml:51-59`, "a writer that also reads holds both roles"). 리뷰어가 직접 읽었다.
|
||||
- 영향: write 역할만 가진 클라이언트는 바이트·offset이 커밋됐는데 403을 받는다. 자동 finalize(`:184-191`)가 실행되지 않고 HEAD로 이어받기도 못 한다.
|
||||
- 심각도·우선순위: Medium / P2. 두 역할을 함께 주면 피할 수 있지만 문서가 권하는 최소 권한 구성에서 깨진다.
|
||||
- 최소 개선 방향: `AppendUploadResult`에 `expectedLength`·`expiresAt`을 실어 status 재조회를 없앤다. 버린 대안 — `ROLE_FILE_WRITE`에 `file:read`를 더함: 최소 권한 원칙과 security.yml의 의도에 어긋난다.
|
||||
|
||||
### 05-13 파일 서버: 정리 worker가 기본으로 꺼져 있다
|
||||
|
||||
- 성격: 확인된 결함(위험한 기본값). 관점 7, 19, 28.
|
||||
- 근거: `composition/fileserver-platform/.../config/module-defaults/fileserver.yml:79` `admin.enabled: false`, `:82` `cleanup.enabled: false`. `FileserverCleanupConfiguration.java:24-28`은 true일 때만 켜진다. 만료 세션을 정리 작업으로 바꾸는 곳은 `DefaultCleanupService.java:126`뿐이다. 기동 검증에 cleanup 관련 검사가 없다.
|
||||
- 영향: 기본 구성에서 staging `.part`, 거절·삭제된 콘텐츠가 쌓여 결국 high-water에 걸린다. 05-07과 합쳐지면 디스크 문제가 더 빨리 온다.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 최소 개선 방향: cleanup을 기본 on으로 한다. 끄려면 운영 프로필에서 명시적 이유 키를 요구하거나 기동 경고를 낸다.
|
||||
|
||||
### 05-14 HTTP client: 기본 설정에서 결과 불명 분류가 틀린 경로로 나간다
|
||||
|
||||
- 성격: 확인된 결함. 관점 6, 8, 17.
|
||||
- 근거: ① `resilience/DefaultRetryEligibilityEngine.java:19-21`의 maxAttempts 거부가 `:47-49`의 ambiguity 판정보다 먼저다. 기본 maxAttempts=1이면 SENT_NO_RESPONSE인 비멱등 요청이 `HttpAmbiguousExecutionException`이 아니라 일반 timeout 예외로 나간다. README는 ambiguous 예외를 약속한다. ② `restclient/BlockingAttemptExecutor.java:222-234`가 transport 호출 전에 단계를 REQUEST_BODY로 올려, `ApacheFailureClassifier`의 "보내기 전 실패" 분기가 실행될 수 없다. TLS handshake timeout이 SENT_NO_RESPONSE가 된다. ③ `:136`에서 계산한 evidence를 `StableBlockingExceptionMapper.java:26-27`이 덮어써 HTTP/2 REFUSED_STREAM → NOT_SENT 보정이 사라진다.
|
||||
- 영향: 호출자가 "보냈는지 모름"과 "안 보냄"을 구분하지 못한다. POST를 정산해야 할 때 일반 실패로 보고 다시 보내거나, 안 보낸 요청을 운영자 대기로 보낸다.
|
||||
- 심각도·우선순위: Medium / P2. retry는 idempotency 선언으로 막혀 있어(`RetryContext.java:71-75`) 클라이언트 자체가 중복 POST를 만들지는 않는다. 오류 계약이 틀린 것이다.
|
||||
- 최소 개선 방향: ambiguity 판정을 먼저 한다. 단계는 연결 이벤트나 엔진 예외 타입으로 정한다. evidence는 더 구체적인 쪽을 유지한다. gateway 수준의 ambiguous 테스트를 추가한다.
|
||||
|
||||
### 05-15 HTTP client: 바인딩되지만 동작하지 않는 설정 키, 0 timeout 허용
|
||||
|
||||
- 성격: 확인된 결함. 관점 5, 19, 21. capability 기준 3 위반.
|
||||
- 근거: `timeout.request-write-idle`, `timeout.proxy-connect`, `proxy.connect-timeout`, `pool.eviction-interval`, `pool.shutdown-timeout`, `observability.operation-name-required` 6개는 profile factory 밖 소비처가 0이다. `profile/ClientProfileValidator.java:94-107`은 비슷한 미지원 키를 거부하면서 이 6개는 받는다. `:109-118`은 totalCall만 0을 거부한다(Apache에서 0은 무한). maxAttempts 상한이 없고, budget 이름이 없으면 retry budget이 무제한이다(`RestClientRuntimeFactory.java:90`).
|
||||
- 영향: 운영자가 timeout을 설정했다고 믿지만 적용되지 않는다. 0을 넣으면 무한 대기.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 최소 개선 방향: 6개 키를 지우거나 `*_UNSUPPORTED` 위반으로 거부한다. 모든 timeout에 `> 0`, maxAttempts에 상한.
|
||||
|
||||
### 05-16 capability 완료 기준 5가 영역 전체에서 지켜지지 않는다
|
||||
|
||||
- 성격: 확인된 결함(규칙과 구조의 불일치). 관점 10, 21, 23, 27.
|
||||
- 근거:
|
||||
- 포트 계약 테스트가 포트 소유 모듈 testFixtures가 아니라 adapter의 `src/test`에 있다: `notification/.../testkit/ProviderAdapterContract.java`, `CallbackContract.java`, `fileserver/.../testkit/ContentStoreContract.java`, `objectstorage/.../contract/ObjectStorageProviderContract.java`. `application-notification`, `application-fileserver`, `application-objectstorage`에는 testFixtures 디렉터리가 없다.
|
||||
- cache·idempotency·rate-limit 포트에는 공통 계약이 없다. testFixtures에 있는 것은 `DistributedLeaseContract`, `DurableOperationStoreContract`, `OutboxLeaseFencingContract`뿐이다(`application-core/src/testFixtures`). 그래서 05-02·05-03이 fake와 adapter 양쪽에서 같은 버그로 숨었다.
|
||||
- `ObjectStorageProviderContract`는 local-dev provider만 상속하고 MinIO 테스트는 상속하지 않는다.
|
||||
- 실제 벤더 테스트: Redis는 Testcontainers가 아니라 외부 topology lane이고 `-Predis.topology.mode` 없이는 explicit-only다. HTTP client Toxiproxy lane은 `integrationCheck`에만 있다. 알림 SES/SMTP 실제 테스트는 없다(`ProviderSandboxSmokeTest`는 env로만 켜짐). 이번 게이트에서 돈 실제 벤더 lane은 MinIO 2개뿐이었고 둘 다 실패했다(05-09).
|
||||
- 영향: 파생 서비스가 새 adapter(예: 다른 캐시, 다른 메일 provider)를 만들 때 상속할 계약이 없다. AGENTS.md 규칙 6과 기준 5가 문서에만 있다.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 최소 개선 방향: 포트 소유 leaf에 `java-test-fixtures`를 붙이고 계약 클래스를 옮긴다. cache·idempotency 계약을 새로 만든다(05-02·05-03의 검증 수단). Redis·HTTP client 실제 lane 하나씩을 `mainCheck`에 넣는다.
|
||||
- 버린 대안: 기준 5를 완화해 "adapter test에 계약이 있으면 충분"으로 바꾸기 — 파생 서비스가 계약을 재사용할 수 없어 기준의 목적(갈아끼울 수 있는 포트)이 사라진다.
|
||||
|
||||
### 05-17 Redis: 연결 실패를 "결과 불명"으로 보고하고, 시간 초과된 연결을 pool에 돌려준다
|
||||
|
||||
- 성격: 확인된 결함. 관점 6, 12, 14.
|
||||
- 근거: `redis-runtime/.../RedisRuntimeOwner.java:201` `openLane` 예외가 `RedisLaneUnavailableException`이 아니어서 `SemanticRedisCall`(`:73,109-111`)이 unknown으로 분류한다. Redis가 완전히 내려가면 멱등성 claim은 `Indeterminate`(→ reconcile 경로), rate-limit은 `NO_MUTATION_CONFIRMED`가 된다. 명령은 하나도 보내지 않았다. 또 `SemanticRedisCall`은 실패·시간 초과 뒤 `invalidate()`를 부르지 않는다(`:98-112`). 로컬 await 200ms, Lettuce timeout 2초(`RedisTopologyClientFactory.java:295`)라 큐에 명령이 남은 연결이 다음 사용자에게 간다. 최악 지연: lane 대기 2s + 연결 2s + 명령 0.2s ≈ 4.2s, health probe는 두 lane에서 약 9.5s(`RedisHealthContributor.java:86-104`).
|
||||
- 영향: Redis 장애 때 "안 보냈음"이 확실한 경우도 reconcile·불명 처리로 간다. 시간 초과 직후 다음 명령이 앞 명령의 응답을 기다린다.
|
||||
- 심각도·우선순위: Medium / P2. 결정 24(포화 시 UNAVAILABLE)는 lane 포화 경우만 충족한다.
|
||||
- 최소 개선 방향: 연결 열기 실패를 lane unavailable로 분류한다. 실패·시간 초과 lease는 invalidate한다. rate-limit은 남은 caller deadline을 borrow·connect에도 적용한다.
|
||||
|
||||
### 05-18 설정 prefix·바인딩 방식이 capability 기준 4와 다르다
|
||||
|
||||
- 성격: 확인된 결함(규칙 불일치). 관점 19, 23.
|
||||
- 근거: redis-runtime은 `@ConfigurationProperties("app.redis")`(`RedisRuntimeAutoConfiguration.java:85`)와 setter+`validate()` 방식이다. cache-redis는 `app.capabilities.*`와 `app.rate-limit.*`를 쓴다. 알림은 `@Value` 두 곳에 기본값을 중복한다(`NotificationCallbackMvcController.java:58`, `NotificationSubmissionConfiguration.java:91`). 같은 auto-configuration이 R0 legacy prefix(`app.notification.slack-webhook`, `google-email`)를 함께 import한다(`NotificationPlatformAutoConfiguration.java:29-31`).
|
||||
- 영향: 모르는 키 거부(StrictSettingsBinder)가 일부 모듈에서 동작하지 않는다. 운영자가 한 모듈의 설정을 여러 트리에서 찾아야 한다.
|
||||
- 심각도·우선순위: Low / P3. 결정 36처럼 예외로 인정할지 정하고, 인정하면 AGENTS.md 규칙 4에 적는다.
|
||||
|
||||
### 05-19 bootstrap이 알림·파일 서버 권한 이름을 안다
|
||||
|
||||
- 성격: 확인된 결함(기준 7). 관점 3, 27.
|
||||
- 근거: `app-bootstrap/src/main/resources/config/security.yml:40-45`(notification 권한 2개), `:50-59`(`ROLE_FILE_*` → `file:*`). 모듈을 빼도 이 매핑이 남고, 모듈을 넣는 서비스는 bootstrap 파일을 알아야 한다.
|
||||
- 심각도·우선순위: Low / P3. 남은 매핑은 동작하지 않는 문자열일 뿐이다.
|
||||
- 최소 개선 방향: 각 composition 모듈의 `module-defaults/*.yml`이 `app.security.authz.role-permissions.<role>` 항목을 싣는다. Spring Binder는 여러 property source의 Map 항목을 합치므로 bootstrap은 이 줄들을 지울 수 있다. 버린 대안 — 모듈별 `RolePermissionContributor` bean: 코드가 늘고 설정 한 곳에서 보이지 않는다.
|
||||
- 완료 기준: 모듈 한 줄을 지우면 security 설정에서 해당 권한이 사라진다.
|
||||
|
||||
### 05-20 SES 콜백: replay 창 5분이 장애 뒤 SNS 재전송을 버린다
|
||||
|
||||
- 성격: 구조적 위험(SNS 재전송 시 Timestamp가 유지된다는 점은 AWS 동작에 대한 추론). 관점 6, 11, 28.
|
||||
- 근거: `SesCallbackAdapter.java:79-81,101-111`이 메시지 `Timestamp`와 수신 시각 차이가 5분(`notification.yml` replay-skew)을 넘으면 거부한다. 중복 방지는 이미 ledger unique 제약이 한다(`persistence-notification` `V1__…sql:174-178`). 또 `SnsSignatureVerifier.java:80`은 cert fetch 실패(`IllegalStateException`, `NotificationCallbackProviderConfig.java:74-86`)를 잡지 않아 500이 된다.
|
||||
- 영향: 서버가 5분 넘게 내려가 있었다면 그동안의 bounce·complaint가 영구 손실되고 suppression이 누락된다. 반송 주소로 계속 보내 발신 평판이 떨어질 수 있다.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 최소 개선 방향: 중복은 unique 제약에 맡기고 창을 SNS 재시도 기간에 맞춰 늘린다(설정 키는 이미 있다 — 기본값 변경). cert fetch 실패는 일시 장애(503)로 명시 매핑한다.
|
||||
|
||||
### 05-21 identifier leaf: 이름·문서가 내용과 맞지 않는다
|
||||
|
||||
- 성격: 개선 제안. 관점 4, 24, 26.
|
||||
- 근거: main 코드는 `HmacUserPrincipalPseudonymizer` 한 클래스(53줄)다. README·CLAUDE.md·`package-info.java`는 "식별자 생성/인코딩(UUIDv7), clock, crypto/random"을 말한다. README `:3`의 패키지 루트(`dev.caskeleton.adapter.identifier`)는 실제(`…adapter.outbound.identifier`)와 다르다. README는 `app-bootstrap`이 조립한다고 적지만 실제는 `composition/service-runtime/.../PseudonymizationConfig.java:26`이다. `composition:fileserver-platform`의 registry edge(`adapter-outbound-identifier`)는 build.gradle에서 쓰이지 않는다. 테스트에 알려진 정답 벡터(RFC 4231)가 없어 charset·알고리즘을 바꾸는 변이가 살아남을 수 있다(추론).
|
||||
- 심각도·우선순위: Low / P3.
|
||||
- 최소 개선 방향: leaf 이름은 유지하고(소비자 영향) 문서를 실제 내용으로 고친다. 정답 벡터 테스트 1건. 쓰지 않는 registry edge 삭제.
|
||||
|
||||
### 05-22 파일 서버: finalize가 writer lease 없이 돈다
|
||||
|
||||
- 성격: 구조적 위험(결과는 추론). 관점 12.
|
||||
- 근거: `FinalizeUploadApplicationUseCase.java:118-148`은 lease를 잡지 않는다. `AtomicMoveContentPublisher.java:32-39`는 hash 계산과 move 사이에 틈이 있다. `LocalUploadContent.java:83-105`의 lease 해제는 노드 단위 `instanceId`가 같으면 해제한다.
|
||||
- 영향: 길이를 미루는 Draft-12 업로드에서 append와 finalize가 겹치면 INTEGRITY_MISMATCH 후 고아 파일, 레코드는 VERIFYING에 멈춘다.
|
||||
- 심각도·우선순위: Low / P3(Draft-12 경로에서만 도달, 켜면 Medium).
|
||||
- 최소 개선 방향: finalize도 lease·fence로 감싸고 해제는 lease token 기준으로.
|
||||
|
||||
### 05-23 작은 결함 묶음 (각각 독립, Low / P3)
|
||||
|
||||
| ID | 내용 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| 05-23a | 0바이트로 선언한 업로드에 1바이트를 쓸 수 있고, 그 세션은 만료까지 finalize 불가 | `UploadSessions.java:67`, `LocalUploadContent.java:108` `Math.max(expected, 1)` |
|
||||
| 05-23b | S3 mutation의 500/503을 "확정 미반영"으로 분류. 요청 본문 bridge가 재구독 불가라 `maxAttempts>1`이어도 PUT 재시도는 항상 실패 | `S3ProviderErrorMapper.java:45,63`, `S3AsyncRequestBodyBridge.java:60-63`, `S3AsyncClientFactory.java:28-32`. kernel이 다음 시도에서 `resolveCreate`로 확인해 손상은 없음 |
|
||||
| 05-23c | 알림 dedup DROP 결과를 저장하지 않아 같은 idempotency key의 응답이 시간에 따라 바뀜 | `NotificationSubmissionService.java:135-138` |
|
||||
| 05-23d | module-defaults 파일 간 같은 키·같은 파일명을 검출하지 않음(지금 7개 파일 사이 충돌 0건) | `support/.../ModuleDefaultsEnvironmentPostProcessor.java:43-49` |
|
||||
| 05-23e | Redis `DEGRADED` 상태가 health status order에 없음 — 전체 health가 DOWN 대신 DEGRADED로 보일 수 있음(추론, 미검증) | `RedisRuntimeAutoConfiguration.java:70-71`, yml에 `status.order` 없음 |
|
||||
| 05-23f | rate-limit dedup 정책이 기본으로 켜져 있지만 adapter·Lua 어디서도 쓰지 않음. `evaluationId`도 무시 → INDETERMINATE 뒤 재시도가 두 번 차감 | `RateLimitPolicy.java:36`, `EdgeRateLimitTransportBridge.java:69` |
|
||||
| 05-23g | HTTP client 401마다 retry 가능 여부와 상관없이 토큰을 다시 받음 | `DefaultGenericHttpGateway.java:194` |
|
||||
|
||||
다른 영역으로 넘기는 것(>): `AuthenticationMode.REDIS_SESSION`이 요구하는 `redisVersionedSessionRepository` bean을 main 코드 어디서도 만들지 않는다(`app-bootstrap/.../AuthenticationModeSettings.java:50-53`) — 인증 영역.
|
||||
|
||||
## 4. 31절 시나리오 추적
|
||||
|
||||
### 4.1 외부 응답 지연·유실 — 알림 1건 발송 (적용)
|
||||
|
||||
`POST /v1/notifications` → 제출 → dispatch → SES 호출을 따라갔다.
|
||||
|
||||
```text
|
||||
HTTP 요청 → web-notification 컨트롤러(DTO 검증, @RequiresPermission notification:submit)
|
||||
→ NotificationSubmissionService: tx { (tenant, idempotency_key) UNIQUE insert, 지문 비교 }
|
||||
→ (스케줄러) RecipientClaimSql: FOR UPDATE SKIP LOCKED, lease 2m
|
||||
→ tx { attempt insert (evidence = 미시작 확정) } ← 05-01
|
||||
→ lease 재확인 → [tx 밖] SES 호출 (connect 2s, apiCallTimeout 10s, SDK 재시도 꺼짐)
|
||||
→ tx { recorder.record (owner + fence 조건) } → retryPolicy → lease 해제
|
||||
```
|
||||
|
||||
| 항목 | 결과 |
|
||||
| --- | --- |
|
||||
| 입력 신뢰 수준 | HTTP 본문은 비신뢰. DTO 검증 후 `AcceptNotificationCommand` 생성자가 category를 강제(`:71-72`) |
|
||||
| 인가 위치 | use case 메서드의 `@RequiresPermission`, 관리자 연산은 `AdminAuthorizationGuard` |
|
||||
| 규칙 소유 객체 | 중복 제출: DB unique 제약 + 지문. 발송 상태: `RecipientDeliveryRecord`, 재시도: `RetryPolicy` |
|
||||
| 트랜잭션 | insert·claim·attempt insert·결과 기록이 각각 짧은 트랜잭션. provider 호출은 트랜잭션 밖(`NotificationDispatchService.java:215`) — 맞다 |
|
||||
| 외부 부작용 | SES·SMTP 발송. provider 쪽 idempotency key는 없다(SES API가 지원하지 않음) |
|
||||
| 성공의 의미 | 제출 응답은 "접수", 발송 성공은 provider 수락(`SubmissionOutcome`)과 콜백 기반 delivery 결과가 따로다 |
|
||||
| 오류 변환 | timeout → AMBIGUOUS → reconcile(SES), SMTP는 전부 AMBIGUOUS(05-11) |
|
||||
| 진단 정보 | attempt 행에 evidence·failure code, health endpoint의 backlog·stuck lease 임계값 |
|
||||
| 결론 | 정상 경로와 timeout 분류는 계약대로다. 프로세스 중단 시 결과 불명이 "확정 미시작"으로 바뀌는 구멍(05-01)과 독 요청 루프(05-10)가 남는다. |
|
||||
|
||||
### 4.2 큰 입력 — tus 업로드 (적용)
|
||||
|
||||
`POST /v1/uploads`(Upload-Length) → `PATCH`(Upload-Offset, body) → finalize.
|
||||
|
||||
| 항목 | 결과 |
|
||||
| --- | --- |
|
||||
| 입력 신뢰 | `Upload-Length` 상한(`TusRequestParser.java:75`)과 policy 상한(`CreateUploadApplicationUseCase.java:171-177`). PATCH body는 쓰기 전 상한 검사(`LocalAppendEngine.java:221`), 선언 초과 거절(`:249-268`), 실패 시 truncate(`:82-101`), 고정 버퍼 스트리밍 |
|
||||
| 경로 | 서버가 만든 키만 경로가 된다. normalize 후 `startsWith` 검사(`DefaultPhysicalPathResolver.java:26-27,115-133`), NOFOLLOW로 한 단계씩 내려감. 클라이언트 파일명은 경로에 쓰이지 않는다 |
|
||||
| 콘텐츠 타입 | magic byte 판별 6종 또는 octet-stream(`MediaTypeVerifier.java:23-30`), 다운로드에 `nosniff`, 기본 `attachment`(`HttpContentDispositionFactory.java:41-86`) |
|
||||
| 인가 | 역할(`@RequiresPermission file:*`) + `FileAccessPolicyPort`(소유자·tenant) 둘 다(결정 32 반영). 테스트 공백은 05-08 |
|
||||
| 동시성 | offset·lease·terminal 전이가 조건부 UPDATE(`UploadLeaseRepository.java:26-148`). offset 검사는 변이 M1로 테스트가 잡음을 확인 |
|
||||
| 결론 | 크기·경로·타입 방어는 잘 돼 있다. 남은 것은 디스크 상한(05-07), 권한 조합(05-12), 정리 기본값(05-13) |
|
||||
|
||||
### 4.3 다른 사용자 리소스 접근 — 파일 다운로드 (적용)
|
||||
|
||||
`GET /v1/files/{id}/content` → `PrepareDownloadApplicationUseCase`가 `authorize(DOWNLOAD, subject, descriptor)` → `RoleBasedFileAccessPolicy`가 소유자·tenant 비교. 현재 코드는 다른 사용자의 id로 요청하면 거부한다. 하지만 이 검사를 지워도 게이트가 통과한다(변이 M2, 05-08). 콘텐츠를 여는 use case는 descriptor를 그대로 신뢰한다(`OpenDownloadContentApplicationUseCase.java:38-40`).
|
||||
|
||||
### 4.4 중복·동시 요청 — 멱등성 claim (부분 적용)
|
||||
|
||||
Redis 멱등성 store는 Lua 단일 키 원자 실행과 Redis `TIME`을 쓴다. 같은 owner의 재시도는 `ALREADY`로 처리한다. renew가 그 분기에 먹혀 lease를 늘리지 못한다(05-02). executor 조립은 `composition:idempotency`(다른 영역)다.
|
||||
|
||||
### 4.5 선택 어댑터 제거 (적용)
|
||||
|
||||
`app-bootstrap/build.gradle:162-171`에서 이 영역의 선택 모듈은 모두 주석 처리돼 있고 기본 조립은 support·identifier만 `implementation`으로 받는다(`:211-212`). `ci`의 `:app-bootstrap` 테스트가 이 기본 조립으로 통과했다. 모듈을 빼도 남는 흔적은 `security.yml`의 권한 매핑(05-19)과 Redis readiness 관련 주석·session bean 이름(`observability.yml:51-77`, `AuthenticationModeSettings.java`)이다. 각 모듈 기준 충족 여부는 7절 표에 있다.
|
||||
|
||||
### 4.6 적용 제외
|
||||
|
||||
| 시나리오 | 사유 |
|
||||
| --- | --- |
|
||||
| 정상 쓰기 요청(일반 도메인) | 이 영역은 도메인 쓰기가 아니라 capability. 4.1·4.2가 같은 경계를 다룬다 |
|
||||
| DB 오류·경쟁 | 영역의 SQL은 persistence leaf(다른 영역). 조건부 UPDATE 사용만 확인 |
|
||||
| 메시지 중복·역순 | messaging은 다른 영역. SNS 콜백 중복은 ledger unique로 처리됨을 확인(05-20) |
|
||||
| 신·구 버전 공존 | 캐시 envelope schema version(`CacheEnvelope.CURRENT_SCHEMA_VERSION`)만 확인, 실험 안 함 |
|
||||
| 여러 서버의 작업 실행 | 4.1의 lease·SKIP LOCKED로 대신함. 다중 인스턴스 실험은 미실행 |
|
||||
| 세션·토큰 갱신 경쟁 | HTTP client 토큰 single-flight(`SingleFlightTokenLoaderTest`)만 확인. 세션은 인증 영역 |
|
||||
| 종료·재시작 | 알림 shutdown-grace 20s 설정 확인. 05-01이 이 시나리오의 결함이다. 실제 종료 실험은 안 함 |
|
||||
|
||||
## 5. 41절 설계 선택 검토
|
||||
|
||||
### 5.1 알림 attempt의 "요청 시작 증거"로 recovery 경로를 고르는 설계
|
||||
|
||||
1. 필요한 것: 워커가 죽은 뒤 남은 DISPATCHING 건을 처리해야 한다. 상태 조회가 없는 provider(SMTP)도 있다.
|
||||
2. 지킬 성질: provider가 받았을 수 있는 요청은 다시 보내지 않는다. 확실히 안 보낸 것만 다시 큐에 넣는다.
|
||||
3. 현재 보장: `provablyNeverStarted`가 PROVEN+false만 requeue한다(`LeaseRecoveryService.java:101-106`). 규칙 자체는 맞다. 하지만 그 증거를 insert 시점에 "확정"으로 쓰고 갱신하지 않아 보장이 깨진다(05-01).
|
||||
4. 대안: (a) 모든 미완료 attempt를 reconcile(이전 방식). (b) 증거 기반 분기 + insert는 UNKNOWN. (c) 호출 직전 증거 갱신 쓰기 추가.
|
||||
5. 비용: (a) 단순하지만 상태 조회 없는 provider는 전부 운영자 대기. (b) 쓰기 추가 없음, "확정 미시작"이 생기는 곳이 명확(adapter 결과·lease 상실 종료). (c) 쓰기 1회 추가로 insert 직후 crash만 자동 requeue.
|
||||
6. 선택: (b). 현재 설계의 의도(증거로 분기)를 유지하면서 증거가 참인 시점에만 기록한다.
|
||||
7. 다시 볼 조건: 상태 조회를 지원하는 provider가 대부분이 되면 (a)로 단순화할 수 있다. insert 직후 crash 비율이 측정상 의미 있으면 (c).
|
||||
|
||||
### 5.2 캐시 무효화 모델: region generation + 키 GETDEL
|
||||
|
||||
1. 필요한 것: 키 단위·region 단위 무효화, Redis 장애 시 원본으로 우회.
|
||||
2. 지킬 성질: 무효화 뒤 옛 값이 다시 보이지 않는다(적어도 정해진 시간 안에).
|
||||
3. 현재 보장: region은 generation 카운터, 인스턴스는 softTtl(30s)마다 재확인. 키는 `GETDEL`. 느린 loader가 무효화 뒤 옛 값을 다시 쓰는 것은 막지 못한다(05-04). revision 조건은 구현되지 않았다(05-03).
|
||||
4. 대안: (a) 현상 유지 + 문서에 "최대 hard TTL 동안 옛 값 가능" 명시. (b) 키 tombstone + revision CAS. (c) pub/sub로 무효화 전파(로컬 캐시가 있을 때만 의미). (d) 분산 lock single-flight.
|
||||
5. 비용: (a) 0, 일관성 약함. (b) Lua 하나, tombstone TTL 관리. (c) pub/sub 전송이 아직 없다(G-4i). (d) 왕복 증가, lock 만료 처리.
|
||||
6. 선택: (b). 이미 `ONLY_IF_OBSERVED`용 Lua CAS가 있어 같은 모양으로 확장된다.
|
||||
7. 다시 볼 조건: 로컬(L1) 캐시를 추가하면 (c)가 필요하다. 쓰기 빈도가 높아 CAS 충돌이 측정되면 재검토.
|
||||
|
||||
### 5.3 MinIO 하나에 기대는 실제 S3 벤더 증거
|
||||
|
||||
1. 필요한 것: S3 호환 저장소에서 adapter 계약이 맞다는 실행 증거(기준 5).
|
||||
2. 지킬 성질: 게이트가 초록이면 실제 벤더로 계약을 확인했다는 뜻이어야 한다.
|
||||
3. 현재 보장: digest 고정 + `rejectSkipped`로 fail-closed. 공급원이 사라지자 실패했다 — 성질은 지켰다. 대신 복구 수단이 없고, 고정 버전 자체도 create-only를 지원하지 않는다(`UNSUPPORTED`).
|
||||
4~6. 대안과 선택은 05-09 표. 조직 레지스트리 미러를 고른다.
|
||||
7. 다시 볼 조건: 운영 대상이 AWS S3로 정해지면 `objectStorageAwsQualificationTest`(현재 explicit-only)를 정기 실행하고 MinIO는 보조로 내린다.
|
||||
|
||||
## 6. 리팩토링 후보
|
||||
|
||||
| 대상 | 무엇을, 왜 | 보존 조건 |
|
||||
| --- | --- | --- |
|
||||
| notification `dispatch/` 46파일 | `submission/`, `dispatch/`, `reconciliation/`, `contact/`로 나눈다. 한 패키지에 기능 4개 | public 타입 이름·api surface 스냅샷(`docs/notification/api-surface-snapshot.txt`) 갱신, 테스트 패키지 동기 이동 |
|
||||
| notification adapter의 R0 legacy(`core/`, `slack/`, `email/google/`) | platform과 한 auto-config에 있음. 별도 leaf로 떼거나 삭제 결정 | `app.notification.slack-webhook`·`google-email` 키 동작, 해당 env 키 |
|
||||
| 포트 계약 테스트 위치 | adapter `src/test` → 포트 소유 leaf testFixtures(05-16) | 상속하는 구현 목록이 줄지 않을 것 |
|
||||
| `RedisCacheRegionAdapter`의 `CacheKeys` 가변 generation | `RegionGeneration` 객체로 분리(S3-#12a) | softTtl 재확인 주기, generation 0 처리 |
|
||||
| Redis health indicator 2개 | 상태 값만 인자로 받는 하나로(S3-#13c) | readiness 그룹 멤버 이름 `redisRequired`/`redisOptional` |
|
||||
| httpclient 단계 추적 | 연결 이벤트로 단계를 올리게(05-14) | `ExecutionEvidence` 값의 의미, 기존 분류 테스트 |
|
||||
| support의 `messaging/` encoder | support는 module-defaults·startup 규칙이 책임. messaging encoder는 messaging bridge 쪽이 맞다 | `IntegrationEventEncoderAutoConfiguration` bean 이름, 조립 순서 |
|
||||
| `NotificationPlatformSettings.ProviderProfile` | provider마다 전용 필드(`Ses ses`)를 추가하는 구조 → provider별 설정 record를 sealed 하위 타입으로 | 기존 키 경로 `…profiles[n].ses.*`, 검증 메시지 |
|
||||
|
||||
## 7. 기능 개발 패턴과 판단 지점 (매뉴얼 재료)
|
||||
|
||||
### 7.1 capability 모듈별 완료 기준 현황
|
||||
|
||||
| 기준 | redis(runtime+cache) | httpclient | objectstorage | notification | fileserver |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 포트만 호출 | O | X — 호출 surface가 모듈 타입(`GenericHttpGateway`, `@HttpClientProfile`). 라이브러리형이라 `implementation`이 필요한데 README는 runtimeOnly 한 줄이라고만 함 | O | O | O |
|
||||
| 2 imports·enabled·순서 | O | O(순서 의존 없음) | O | P — adapter 쪽 순서 지정 없음 | P — `beforeName`만 |
|
||||
| 3 동작하지 않는 키 없음 | P — sample 죽은 키(P20-new-3) | X — 05-15 | O | P — R0 키 동거 | O |
|
||||
| 4 prefix 하나·StrictSettingsBinder | X — 05-18 | O | O | X — `@Value` 중복 | O |
|
||||
| 5 계약 테스트·실제 벤더 | P — lease만, 실제 lane은 explicit-only | P — 계약 위치, 실제 lane은 integrationCheck만 | P — 계약 위치, MinIO 실패(05-09) | X — testFixtures 없음, 실제 벤더 없음 | P — 계약 위치, Postgres는 다른 leaf |
|
||||
| 6 README 3가지 | P — redis-runtime README 없음 | O | O | O(composition README) | P — web-fileserver README 없음 |
|
||||
| 7 모듈만 안다 | O(주석 외) | O | O | P — security.yml | P — security.yml |
|
||||
|
||||
### 7.2 새 기능을 추가할 때 개발자가 내려야 하는 판단
|
||||
|
||||
**외부 API client 추가 (httpclient)**
|
||||
1. profile 설정(`APP_HTTPCLIENT_CLIENTS_N_*`): base-url, allowed-hosts·ports, body 상한, prod TLS profile.
|
||||
2. `@HttpExchange` 인터페이스 + 메서드마다 `@HttpOperationPolicy(name, idempotency)`.
|
||||
3. application-core에 포트를 정의하고 adapter leaf가 httpclient를 `implementation`으로 받는다.
|
||||
- 판단 지점: 이 연산은 멱등한가(아니면 idempotency key를 보낼 수 있는가)? 결과 불명(`SENT_NO_RESPONSE`)을 어떻게 정산하는가? 4xx 중 무엇이 업무상 정상인가(05-05가 고쳐지기 전에는 breaker에 주의)? 전체 deadline이 transport timeout 합보다 큰가(05-06)?
|
||||
|
||||
**알림 provider·채널 추가**
|
||||
1. `ProviderType`, adapter·failure classifier, `ProviderRuntimeAssembler`, `Notification<X>ProviderConfig`, `ProviderProfile` 필드, `NotificationSecretRequirements`, `notification.yml`, api surface 스냅샷·evidence manifest.
|
||||
2. 채널이면 `Channel`, sealed `NotificationContent`, `ContactPointType`, renderer·slot policy, persistence 매핑, web DTO까지.
|
||||
- 판단 지점: provider가 상태 조회를 지원하는가(없으면 결과 불명이 전부 운영자 대기)? 어떤 예외가 "확실히 안 보냄"인가? 콜백 서명 방식과 replay 창은? collapse·priority 같은 선택 기능을 지원하는가?
|
||||
|
||||
**파일 연산 추가**
|
||||
1. `FileOperation` 값과 `RoleBasedFileAccessPolicy.tierOf` 매핑, `@RequiresPermission`, security 매핑.
|
||||
2. use case 안에서 `authorize(op, subject, Optional.of(record.toDescriptor()))` — descriptor를 빠뜨리면 소유자 검사가 조용히 꺼진다(05-08).
|
||||
3. 바이트를 새로 만드는 연산이면 admission·quota(05-07). 실패 시 cleanup·recovery 큐에 넣을 것.
|
||||
- 판단 지점: 이 연산은 디스크를 늘리는가? 대상 namespace를 누가 정하는가? 중간 실패 시 고아 파일을 누가 회수하는가?
|
||||
|
||||
**캐시 region·rate-limit 정책 추가**
|
||||
1. cache region은 지금 `CacheRegionPort<String, byte[]>` bean 하나(`RedisCacheConfig.java:281`). 새 region은 cache-redis 안에 bean 추가가 필요하다 — 템플릿이 확장 지점을 주지 않는다.
|
||||
2. rate-limit 정책은 `app.capabilities.rate-limit.policies.<id>` yml 블록. 라우트별 정책은 inbound 코드를 고쳐야 한다.
|
||||
- 판단 지점: 키에 tenant·사용자 범위를 넣었는가(호출자 책임)? 무효화 뒤 옛 값이 얼마나 허용되는가(05-04)? Redis 장애 시 원본으로 갈 것인가 거부할 것인가? rate-limit revision을 바꾸면 카운터가 초기화된다.
|
||||
|
||||
### 7.3 템플릿이 주는 틀과 빠진 것
|
||||
|
||||
- 주는 것: capability별 auto-configuration·module-defaults·README 모양, StrictSettingsBinder, lease 공통 계약, 알림·파일 서버의 완성된 참조 구현.
|
||||
- 빠진 것: 포트별 공통 계약 테스트(cache·idempotency·rate-limit·알림 provider·파일 콘텐츠 store)를 testFixtures에서 상속하는 틀, 새 cache region을 서비스가 선언하는 확장 지점, httpclient를 포트 뒤로 숨기는 예제 adapter, application-* leaf의 CLAUDE.md(B-10b와 같은 성격, fileserver·objectstorage도 없음).
|
||||
|
||||
### 7.4 폴더 구조
|
||||
|
||||
- 찾기 쉬운 것: composition 모듈이 조립을, application-* 가 유스케이스를, adapter가 벤더 코드를 갖는 3단 구조는 알림·파일 서버에서 일관된다.
|
||||
- 찾기 어려운 것: Redis는 runtime·sdk·cache 세 leaf인데 runtime에 README가 없고 규칙이 cache-redis CLAUDE.md에 섞여 있다(G-5b). `redis-sdk`(main 24,506줄)는 소비자가 0인 라이브러리형 모듈이다 — 사용자 원칙상 확장 지점이지만, 무엇을 위해 남기는지 README에 소비 예제가 없다. identifier leaf는 이름과 내용이 다르다(05-21). 알림 adapter는 R0 legacy와 platform이 한 leaf에 있다.
|
||||
|
||||
### 7.5 성능 (코드에서 읽은 값, 측정 아님)
|
||||
|
||||
| 항목 | 값 |
|
||||
| --- | --- |
|
||||
| Redis lane 연결 수 | REGULAR 64, SCRIPT 8(rate-limit·멱등성·lease 공유) — `RedisRuntimeSettings.java:457-458` |
|
||||
| Redis 대기·timeout | lane 대기 2s, connect 2s, 명령 500ms/1s/2s, capability 명령 200ms. 최악 약 4.2s(05-17) |
|
||||
| SCRIPT lane 처리량(추정) | 왕복 1ms면 pod당 약 8k ops/s, Redis가 200ms로 느려지면 약 40 ops/s |
|
||||
| HTTP client pool | 전체 50, route당 25, pending 100(200ms 대기) |
|
||||
| HTTP client timeout | connect 0.5s, TLS 1s, 응답 헤더 2s, read idle 3s, 전체 4s |
|
||||
| HTTP 응답 버퍼링 | 응답 전체를 메모리에, profile당 최악 50 × 5MB = 250MB |
|
||||
| 알림 dispatch | claim 50건, 동시 64(virtual thread + semaphore), lease 2m, poll 1s |
|
||||
| 캐시 TTL | soft 30s, hard 5m, negative 10s |
|
||||
| 테스트 시간 | 14 leaf 합 약 63s, 1,790개 |
|
||||
|
||||
## 8. 28개 관점 판정표
|
||||
|
||||
기호: O 충족, P 부분, X 미충족, ? 미검증, - 적용 제외, > 다른 영역.
|
||||
|
||||
| # | 관점 | 판정 | 한 줄 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | P | 경로·크기 방어는 견고하나 공개 계약이 조용히 깨진 곳이 있다(05-02, 05-03) |
|
||||
| 2 | 구조적 성숙도 | O | application-*/adapter/composition 분리와 registry edge가 지켜진다. ci의 architectureCheck 통과 |
|
||||
| 3 | 변경 용이성 | P | provider 추가 시 일반 profile record 수정 필요, bootstrap security.yml 수정 필요(05-19) |
|
||||
| 4 | 인지 부하 | P | 알림·파일 서버는 개념이 많고 문서 drift(W5 항목 다수)가 읽는 비용을 올린다 |
|
||||
| 5 | 위험 가시성 | P | 결과 불명·lease 의도가 주석에 잘 드러나지만, 그 주석이 틀린 곳(05-01)과 문서가 jitter를 주장하는 곳(05-04)이 있다 |
|
||||
| 6 | 실패 성숙도 | P | 결과 불명 분류 체계는 있으나 SMTP·HTTP 기본 경로·Redis 연결 실패에서 분류가 틀린다(05-11, 05-14, 05-17) |
|
||||
| 7 | 운영 성숙도 | P | health·backlog 임계값은 있음. 정리 worker 기본 꺼짐(05-13), breaker 설정 키 없음(05-05) |
|
||||
| 8 | 디버깅 가능성 | P | attempt evidence·failure code가 남는다. MinIO 실패가 공급원 문제로 구분되지 않는다(05-09) |
|
||||
| 9 | 유지보수 성숙도 | P | 이력 주석·FQN·CLAUDE.md 버전 drift가 남아 있음(2절) |
|
||||
| 10 | 테스트 성숙도 | P | offset 검사는 테스트가 잡음(M1). 소유자 검사 제거는 못 잡음(M2), fake가 adapter 버그를 따라 함(05-02) |
|
||||
| 11 | 데이터 성숙도 | P | 제출 중복은 DB unique로 강제. 재발송(05-01), 캐시 옛 값(05-03), bounce 손실(05-20) |
|
||||
| 12 | 동시성 성숙도 | P | SKIP LOCKED·fence·조건부 UPDATE는 좋다. lease 만료 후 재발송, finalize lease 없음(05-22) |
|
||||
| 13 | 확장성 | ? | 다중 인스턴스·부하 실험 없음. SCRIPT lane 8개가 병목 후보(추정) |
|
||||
| 14 | 성능 성숙도 | P | 상한(pool·body·lane)은 정해져 있음. deadline이 진행 중 요청을 끊지 못함(05-06) |
|
||||
| 15 | 보안 성숙도 | P | 경로 탐색·SSRF·SNS 서명·nosniff 방어 확인. copy로 디스크 고갈(05-07), 인가 회귀 미검출(05-08) |
|
||||
| 16 | 의존성 성숙도 | P | reactive 스택 제거(결정 9), SES는 AWS SDK. MinIO 공급원 소멸(05-09), Jackson 2 잔존(S3-#13a) |
|
||||
| 17 | API / Contract 성숙도 | P | 포트 계약이 공개돼 있으나 구현이 일부 intent·renew를 지키지 않는다 |
|
||||
| 18 | 배포 성숙도 | > | 배포 파이프라인은 다른 영역. 이 영역은 release 스크립트 경로 오류(P11-new-2)만 기록 |
|
||||
| 19 | 설정 성숙도 | P | module-defaults 구조는 일관. 동작 안 하는 키·0 timeout 허용(05-15), prefix 여러 개(05-18) |
|
||||
| 20 | 개발자 경험 | P | 모듈 한 줄로 켜지는 경험은 좋다. 새 adapter가 상속할 계약·확장 지점이 없다(7.3) |
|
||||
| 21 | Guardrail 성숙도 | P | StrictSettingsBinder, fail-closed lane. 기준 5를 강제하는 장치는 없다(05-16) |
|
||||
| 22 | 추상화 성숙도 | P | 포트 경계는 적절. httpclient는 포트 없이 모듈 타입을 노출(7.1 기준 1) |
|
||||
| 23 | 일관성 | P | 계약 테스트 위치·설정 바인딩 방식이 모듈마다 다르다 |
|
||||
| 24 | 네이밍 / 의미 성숙도 | P | identifier leaf 이름 불일치(05-21), `*ProviderProperties`(S4-#17b) |
|
||||
| 25 | 조직 확장성 | ? | 담당자·소유 표기 없음. 판단할 자료 없음 |
|
||||
| 26 | Ownership 성숙도 | P | env-keys owner_module 오기(G-12e), application-* CLAUDE.md 없음 |
|
||||
| 27 | 삭제 가능성 | P | 한 줄 제거로 대부분 사라짐(`ci`의 기본 조립 통과). security.yml 잔여(05-19) |
|
||||
| 28 | 회복 가능성 | P | reconcile·recovery 경로가 있다. 증거 오기로 회복이 재발송이 됨(05-01), 정리 기본 꺼짐(05-13) |
|
||||
|
||||
## 발견 요약
|
||||
|
||||
| 심각도 | 개수 | ID |
|
||||
| --- | --- | --- |
|
||||
| Critical | 0 | |
|
||||
| High | 6 | 05-01, 05-02, 05-03, 05-05, 05-06, 05-07 |
|
||||
| Medium | 12 | 05-04, 05-08, 05-09, 05-10, 05-11, 05-12, 05-13, 05-14, 05-15, 05-16, 05-17, 05-20 |
|
||||
| Low | 11 | 05-18, 05-19, 05-21, 05-22, 05-23a~g |
|
||||
|
||||
| 우선순위 | 개수 | ID |
|
||||
| --- | --- | --- |
|
||||
| P1 | 8 | 05-01, 05-02, 05-03, 05-05, 05-06, 05-07, 05-08, 05-09 |
|
||||
| P2 | 10 | 05-04, 05-10, 05-11, 05-12, 05-13, 05-14, 05-15, 05-16, 05-17, 05-20 |
|
||||
| P3 | 11 | 05-18, 05-19, 05-21, 05-22, 05-23a~g |
|
||||
|
||||
사용 결정: **조건부 사용 가능.** 파일 서버의 크기·경로·타입 방어와 알림의 제출 중복 방지는 그대로 써도 된다. 알림 발송(05-01), Redis 멱등성 renew·캐시 revision 조건(05-02, 05-03), HTTP client(05-05, 05-06), 파일 copy(05-07)는 고치기 전에는 파생 서비스에서 쓰지 않거나 우회 조건을 문서로 정해야 한다.
|
||||
@@ -0,0 +1,495 @@
|
||||
# 06 — messaging 영역 성숙도 리뷰
|
||||
|
||||
- 대상: vendored `messaging:*`(`src/messaging`), `adapter:outbound:messaging`(anti-corruption bridge),
|
||||
`adapter:outbound:messaging-kafka`, `composition:outbox-relay`
|
||||
- 기준 커밋: `main` `01a8a2a70`
|
||||
- 작성일: 2026-11-01
|
||||
- 소유자 결정 유지: vendored 플랫폼은 Clean Architecture 레이어가 아니다(MSG-023 §6.2). messaging outbox도
|
||||
유지한다(followup `X1-지도-Outbox`). 이 문서는 그 결정을 뒤집지 않고 그 안의 품질과 결정의 반영 상태를 본다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 저장소 | `clean-architecture-backend-template`, Gradle 루트 `src/` |
|
||||
| 커밋·확인 시점 | `01a8a2a70`, 2026-11-01 20:30–21:10 KST |
|
||||
| 목적과 지원 실행 구성 | 서비스 시작점 템플릿. 다중 인스턴스 배포를 전제한다(relay가 `SKIP LOCKED` + lease fencing을 쓴다). broker는 Kafka 하나 |
|
||||
| 규모·운영 목표 | 합의된 수치 없음. 그래서 처리량·복구 시간은 "현재 기본값으로 계산한 값"으로만 적는다 |
|
||||
| 읽은 코드 | `composition/outbox-relay/src/main/**` 전부, `adapter/outbound/messaging/src/main/**` 전부, `adapter/outbound/messaging-kafka`(코드 없음, `module-defaults/messaging.yml`), `application-core/.../application/outbox/**`(relay 동작 확인용), `persistence-jpa/.../outbox/**`(claim SQL·완료 확인용), `messaging-runtime-core` `DefaultMessagePublisher`, `messaging-transport-spi` `DefaultMessagingRuntimeRegistry`, `messaging-policy` `MessagingAdmissionController`, `messaging-kafka` `KafkaMessagingTransport`·`KafkaPublishFailureClassifier`, starter의 `MessagingShutdownLifecycle`·`MessagingOutboxRelayLifecycle`·`MessagingReliabilityAutoConfiguration`·`MessagingConsumeConfiguration`·`MessagingPublishConfiguration`, starter-kafka `KafkaMessagingAutoConfiguration`·`KafkaDeadLetterQuarantine`, sample `PortfolioEventOutbox`, `SubmitDurableOperationUseCase`, runbook `outbox-dead-letter`·`outbox-publish-failed`, `docs/messaging/*`. Spring Framework 7.0.9 소스(`ExecutorConfigurationSupport`, `ScheduledAnnotationBeanPostProcessor`)로 종료 순서 확인 |
|
||||
| 읽지 않은 코드 | vendored admin·claim-check·cloudevents·schema-avro/protobuf·observability 내부, `KafkaConsumerRegistrar` 786줄 중 settlement 세부 |
|
||||
| 수행한 테스트·실험 | 아래 "실행" 참고 |
|
||||
| 확인 못 한 것 | 실제 Kafka·PostgreSQL로 앱 relay를 끝까지 돌리는 실험(그런 테스트가 저장소에 없고 이번에 만들지도 않음), 실제 SIGTERM 종료 순서 실측, 처리량 실측 |
|
||||
| 이전 리뷰와 비교 범위 | techlead `10-messaging.md`, followup-status M·H 그룹, 모듈 리뷰 `2026-08-14-messaging-module-code-review.md`(MSG-015·MSG-023) |
|
||||
|
||||
### 실행
|
||||
|
||||
| 명령 | 결과 |
|
||||
| --- | --- |
|
||||
| 오케스트레이터 `ci` 게이트 로그(`gates/ci.log`) | rc=0. 이 영역 leaf의 `test` 전부 통과 |
|
||||
| 오케스트레이터 `mainCheck` 게이트 로그 | rc=1. 원인은 `objectstorage`의 MinIO 이미지 pull 404(이 영역 밖). 이 영역의 broker 실연 lane(`integrationTest`)은 `mainCheck`에 들어 있지 않아 컴파일만 됐다 |
|
||||
| 실험 1 (worktree `wt-06`, 부하 load avg 13.3): `./gradlew :messaging:messaging-runtime-core:test --tests '*DefaultMessagePublisherTest.reviewExperiment*' :adapter:outbound:messaging:test --tests '*PlatformIntegrationEventPublishAdapterTest.reviewExperiment*'` | 통과. 출력: `completion=REJECTED transmission=NOT_TRANSMITTED code=SHUTTING_DOWN retryable=true`, 이어서 bridge `outcome=REJECTED_BEFORE_SEND retryable=false`. 06-01 근거 |
|
||||
| 실험 2 (변이, worktree, load avg 7.6): `OutboxRelayScheduler`에서 `metrics.recordRelayResult`·`metrics.refresh` 호출을 사실상 제거하고 `./gradlew :composition:outbox-relay:test` | 18개 전부 통과(변이 생존). 06-05 근거 |
|
||||
| 테스트 시간(`build/test-results` XML 합계) | `adapter:outbound:messaging` 36개 2.8s, `messaging-kafka` adapter 4개 3.5s, `composition:outbox-relay` 18개 2.2s, `messaging-spring-boot-starter` 72개 4.9s, 나머지 messaging leaf는 각 1.5s 이하. 실행 시간은 문제 아님 |
|
||||
|
||||
실험용 테스트 편집은 worktree에만 했고 끝나고 worktree를 지웠다.
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| ID | 지난 내용(요약) | 상태 | 근거 |
|
||||
| --- | --- | --- | --- |
|
||||
| techlead H10 | 자동조립 publisher가 관측을 기록하지 않음 | 해결 | `messaging-spring-boot-starter/.../MessagingPublishConfiguration.java:224-231` observation 주입 |
|
||||
| techlead H3 | consumer가 배선되지 않음 | 바뀜 | starter-kafka가 `MessageHandler` bean마다 consumer를 연다(`MessagingConsumeConfiguration.java:60-68`). 다만 application leaf 쪽 경로가 없다 → 06-08 |
|
||||
| techlead M4 | 실행 경로에 스키마 호환성 검사 없음 | 바뀜 | 문서가 "선언만 하고 강제하지 않음"으로 표시(`docs/messaging/configuration-reference.md:123`). 앱 payload 버전에는 여전히 없음 → 06-10 |
|
||||
| techlead M5 | outbox 두 개 공존 | 남음(소유자 결정으로 유지) | vendored `MessagingReliabilityAutoConfiguration`·`JdbcOutboxRepository`가 runtime classpath에 있음. 문서·종료 순서 비용 → 06-02, 06-11 |
|
||||
| techlead M7 / H-1b | producer-id 키 부재, 빈 값 통과 | 해결 | `messaging-kafka/src/main/resources/config/module-defaults/messaging.yml` `producer-id`, `MessagingBridgeRootAutoConfiguration.java:77-87` |
|
||||
| H-1a | bridge 조건이 platform보다 먼저 평가 | 해결 | `MessagingBridgeRootAutoConfiguration.java:32-33` `afterName` |
|
||||
| H-8 | bridge `prepare`가 모든 예외를 REJECTED로 | 해결 | `PlatformIntegrationEventPublishAdapter.java:59-67`, 테스트 `aFailureOtherThanAnIncompatibleValueIsNotTurnedIntoARefusal` |
|
||||
| H-9, H-10b, H-10c | `KafkaSender` seam 관련 | 해당 없음(코드 삭제) | `adapter/outbound/messaging-kafka/src/main` 아래 Java 없음 |
|
||||
| M-1 | 이미 인코딩된 payload 재인코딩 | 해결 | `DefaultMessagePublisher.java:314-322` |
|
||||
| M-2a~f | Kafka 보안 설정 미적용 | 해결 | `KafkaMessagingAutoConfiguration.java:154-209`, followup의 테스트 존재 확인 |
|
||||
| M-3, M-7 | handler timeout 중복, poison 무한 재시도 | 해결 | `KafkaConsumerRegistrarTest.java:160,191,219` |
|
||||
| M-4a | admission 거부를 동기 예외로 던짐 | 해결 | `DefaultMessagePublisher.java:228-233` (결과로 반환). 단, 그 결과의 의미가 bridge에서 뒤집힌다 → 06-01 |
|
||||
| M-4b, M-4c, M-6, M-11 | vendored relay·cleanup | 해결 | `OutboxRelayTest.java:90`, `MessagingOutboxRelayLifecycleTest.java:77`, `OutboxOperationsTest.java:114`, `OutboxPostgresIT.java:226`. 이 relay는 앱이 쓰지 않는다 |
|
||||
| M-5a | publish가 최대 65초 막힘 | 해결 | `KafkaMessagingAutoConfiguration.java:203-206` `max.block.ms` = 5s |
|
||||
| M-8a | 옛 prefix `backend.messaging` fixture yml 2개 | 남음 | `messaging-spring-boot-starter/src/test/resources/application-valid.yml:2-3`, `application-invalid-ordering.yml`. 참조 0건 |
|
||||
| TEST-FAKE-MessagePublisher | fake와 `DefaultMessagePublisher`의 공통 계약 없음 | 남음 | `messaging-core-api`에 `testFixtures` 없음. `implements EncodedMessagePublisher`는 test fake 3곳과 본체뿐 |
|
||||
| A-2 그룹 밖(followup:173) | `MessagingAdminDurabilityValidator`의 profile 대소문자 판정 | 남음 | `MessagingAdminDurabilityValidator.java:25,53-54` `Set.of("prod","production")::contains`. `Prod`면 검사를 건너뛴다 |
|
||||
|
||||
남은 High/P1 지난 항목은 없다. 남은 것은 Low/Nit(M-8a, admin profile 판정)와 테스트 계약(TEST-FAKE)이다.
|
||||
|
||||
## 3. 새 발견
|
||||
|
||||
심각도별: High 2 · Medium 10 · Low 2. 우선순위별: P1 2 · P2 8 · P3 4.
|
||||
|
||||
### 06-01 — 다시 시도하면 될 거부를 relay가 즉시 DEAD로 보낸다
|
||||
|
||||
- 성격: 확인된 결함
|
||||
- 관련 관점: 6, 1, 17, 28, 5
|
||||
- 근거
|
||||
- platform은 일시적 거부를 `REJECTED` + `retryable=true`로 돌려준다.
|
||||
- 종료 중 admission 거부: `MessagingAdmissionController`가 `MessageBackpressureException("SHUTTING_DOWN")`(category `TRANSIENT_INFRASTRUCTURE`, retryable true)을 던지고 `DefaultMessagePublisher.java:228-233`이 `PublishResult.rejected`로 바꾼다.
|
||||
- permit 대기 초과: 같은 경로. 기존 테스트 `DefaultMessagePublisherTest.aSaturatedPermitPoolRejectsAsRetryableWithinTheCallersDeadline`이 `(REJECTED, retryable=true)`를 단언한다.
|
||||
- runtime 없음(종료 후 registry close): `DefaultMessagingRuntimeRegistry.java:86-90` → `DefaultMessagePublisher.java:261-267` `PUBLISH_RUNTIME_UNAVAILABLE` REJECTED.
|
||||
- transport 닫힘: `KafkaMessagingTransport.java:121-123` `KAFKA_TRANSPORT_CLOSED` REJECTED.
|
||||
- Kafka 인증·인가 오류: `KafkaPublishFailureClassifier.java:51-58`가 `AuthenticationException`·`AuthorizationException`을 확정 거부로 본다. credential 교체 중 실패나 ACL 배포 순서 문제도 여기로 온다.
|
||||
- bridge는 `retryable`을 보지 않는다. `PlatformIntegrationEventPublishAdapter.java:140-151`은 completion과 transmission만 보고 `REJECTED_BEFORE_SEND`/`REJECTED_AFTER_BROKER`를 만든다.
|
||||
- relay는 그 둘을 "같은 payload는 또 거부된다"로 보고 시도 예산을 쓰지 않고 바로 DEAD로 보낸다(`PublishPendingOutboxEventsUseCase.java:149-153`, `OutboxPublishOutcome.java` `retryable()`은 `AMBIGUOUS`만 true).
|
||||
- DEAD row는 같은 aggregate의 뒤 row를 모두 막는다(`PostgreSqlOutboxClaimRepository.java:27-36`, `p.status <> 'PUBLISHED'`).
|
||||
- 실험 1: `SHUTTING_DOWN` 거부가 `REJECTED/NOT_TRANSMITTED/retryable=true`로 나오고, 같은 모양의 결과를 bridge가 `REJECTED_BEFORE_SEND`(retryable false)로 바꾸는 것을 실행으로 확인했다. 마지막 고리(`REJECTED_BEFORE_SEND` → DEAD)는 기존 `OutcomeAwareRelayTest.aRefusalBeforeTransmissionIsDeadLettered`가 단언한다.
|
||||
- platform 문서도 "REJECTED는 포기해도 안전"이라고 적는다(`docs/messaging/delivery-guarantees.md:21-22`). 같은 platform이 retryable REJECTED를 만든다.
|
||||
- 발생 조건: 배포 종료 중 relay가 돌고 있을 때(06-02), 다른 publisher와 permit을 다툴 때, Kafka 인증 정보 교체·ACL 변경 순간.
|
||||
- 영향: 이미 커밋된 비즈니스 이벤트가 DEAD가 되고 그 aggregate의 이후 이벤트가 전부 멈춘다. 자동 복구가 없다. runbook의 수동 SQL이 필요하다.
|
||||
- 심각도·우선순위: High / P1. 배포는 정상 운영 동작이다. 결과가 영구 정지라서 출시 전 차단 항목으로 본다.
|
||||
- 확실성: 각 고리는 코드와 테스트로 확인했다(E2). 실제 종료에서 몇 건이 걸리는지는 미측정이다.
|
||||
- 결정의 근거: 적용 제외 — 두 계약(platform `retryable`, application "확정 거부") 사이의 번역 누락이다. 선택 비교가 아니라 번역을 맞추는 문제다.
|
||||
- 통제 수준: M0(retryable 거부를 retryable로 다루는 수단 없음). 증거 E2.
|
||||
- 최소 개선 방향: bridge `mapOutcome`에서 `result.failure().retryable()`이 true인 REJECTED는 "다시 시도 가능, 전송 안 됨"으로 번역한다. application 어휘에 그 값이 없으므로 `OutboxPublishOutcome`에 `DEFERRED_NOT_SENT`(가칭) 하나를 추가하고, relay는 이 값에서 `markFailed`를 하되 시도 횟수를 늘리지 않는 쪽을 고른다. Kafka 인증·인가 오류는 classifier에서 retryable 거부로 분류한다.
|
||||
- 버린 대안 1: `AMBIGUOUS`로 번역. 동작은 비슷하지만 "전송됐을 수 있음"이라는 거짓 정보를 남기고 중복 경고를 오염시킨다.
|
||||
- 버린 대안 2: relay가 platform `FailureDescriptor`를 직접 본다. application-core가 platform 타입을 알게 돼 bridge의 존재 이유가 사라진다.
|
||||
- 완료 기준: retryable REJECTED가 relay에서 FAILED가 되고 DEAD가 되지 않는다. 인증 오류가 retryable로 분류된다.
|
||||
- 검증 방법: bridge 테스트에 retryable REJECTED → 새 값 케이스, relay 테스트에 새 값 → FAILED(시도 미소비) 케이스. 실험 1의 두 테스트를 정식 테스트로 옮긴다.
|
||||
|
||||
### 06-02 — platform 종료 순서가 앱 relay를 모른다
|
||||
|
||||
- 성격: 확인된 결함(정적)
|
||||
- 관련 관점: 6, 7, 12, 28, 23
|
||||
- 근거
|
||||
- 앱이 실제로 쓰는 relay는 `@Scheduled` 메서드다(`OutboxRelayScheduler.java:36`). SmartLifecycle이 아니다.
|
||||
- platform 종료 순서는 vendored relay(`MessagingOutboxRelayLifecycle`, phase `Integer.MAX_VALUE`)를 먼저 멈추고 그다음 admission을 닫도록 설계됐다(`MessagingShutdownLifecycle.java:109-123`, phase `MAX_VALUE - 1024`). 앱은 vendored relay를 만들지 않는다(`OutboxRepository` bean을 만드는 production 코드 없음).
|
||||
- Spring 7.0.9에서 `@Scheduled` 작업은 `ContextClosedEvent`에 `cancel(false)`로 취소된다(`ScheduledAnnotationBeanPostProcessor` 597·613행). 실행 중인 relay 회차는 계속 돈다. scheduler executor의 lifecycle phase는 `Integer.MAX_VALUE / 2`다(`ExecutorConfigurationSupport` 75행).
|
||||
- 그래서 종료 순서는 "admission 닫기(MAX-1024) → scheduler가 실행 중 회차를 기다림(MAX/2) → bean destroy(registry·transport close)"다. 실행 중 회차의 남은 row는 `SHUTTING_DOWN`, `RUNTIME_NOT_INSTALLED`, `KAFKA_TRANSPORT_CLOSED` 순으로 거부된다. 06-01 때문에 모두 DEAD가 된다.
|
||||
- `MessagingShutdownLifecycle` 주석은 이 상황을 "row가 ambiguous가 된다"고 설명한다(`:113-116`). 앱 경로에서는 DEAD가 된다. 주석과 실제가 다르다.
|
||||
- 발생 조건: SIGTERM 순간 relay 회차가 진행 중. 적체가 있거나 broker가 느리면 회차가 길어 확률이 커진다(배치 20 × publish 최대 약 10초).
|
||||
- 영향: 06-01이 있는 지금은 배포마다 일부 row가 DEAD가 될 수 있다. 06-01을 고쳐도 시도 예산을 쓰고 FAILED 경고를 남긴다.
|
||||
- 심각도·우선순위: Medium / P1. 단독 영향은 중간이지만 06-01과 같이 고쳐야 배포 경로가 안전해진다.
|
||||
- 확실성: 순서는 Spring 소스와 phase 값으로 확인했다(E1). 실제 종료 실측은 하지 않았다.
|
||||
- 결정의 근거: 확인된 사실은 위와 같다. 기록된 의도는 "relay가 먼저 멈춘다"(`MessagingOutboxRelayLifecycle.java:55-68`)이다. 리뷰어 추론: vendored relay를 기준으로 설계한 뒤 앱 relay가 composition으로 옮겨지면서(2026-09-28) 이 순서에 들어가지 않았다.
|
||||
- 이해 비용: 운영자가 배포 후 DEAD를 보면 원인을 broker에서 찾게 된다. 종료 순서를 알아야 원인을 찾는다.
|
||||
- 최소 개선 방향: `OutboxRelayScheduler`를 SmartLifecycle로 바꾸고 phase를 `MessagingShutdownLifecycle`보다 높게 둔다. stop에서 진행 중 회차를 끝내고 새 회차를 막는다. 남은 claim은 lease를 놓아(release) 다른 인스턴스가 바로 가져가게 한다.
|
||||
- 대안 비교: (a) 현상 유지 + 06-01만 수정 — 비용 최소, 배포마다 FAILED 잡음과 시도 소비가 남는다. (b) scheduler executor phase를 올리기 — 전역 설정이라 다른 `@Scheduled` 작업까지 바뀐다. (c) relay 전용 SmartLifecycle — 범위가 relay에 한정된다. (c)를 고른다.
|
||||
- 비용·부작용: relay 루프를 직접 소유하게 된다. `@Scheduled` 의존이 사라지므로 `@EnableScheduling` 결정(L-1)도 함께 다시 본다.
|
||||
- 재검토 조건: relay를 별도 프로세스(worker 배포 단위)로 분리하면 이 순서 문제는 그 프로세스의 종료 절차로 옮겨 간다.
|
||||
- 완료 기준: 종료 중에 claim된 row가 DEAD가 되지 않고, PUBLISHED 또는 lease 해제 상태로 남는다.
|
||||
- 검증 방법: 컨텍스트 테스트에서 relay 회차를 막아 둔 채 `context.close()`를 호출하고 row 상태를 단언한다.
|
||||
|
||||
### 06-03 — broker가 몇 분만 멈춰도 row가 대량으로 DEAD가 되고 복구는 수작업이다
|
||||
|
||||
- 성격: 구조적 위험
|
||||
- 관련 관점: 28, 6, 7, 19, 14
|
||||
- 근거
|
||||
- 시도 예산은 고정 3회, 기본 지연 30초다(`OutboxBackoffPolicy.java:24,27`). 실패 지연은 1회차 30–60초, 2회차 60–90초다.
|
||||
- 지연의 기준 시각은 회차 시작 시각이다(`PublishPendingOutboxEventsUseCase.java:99`의 `now`를 `:176`에서 사용). broker가 멈추면 publish 하나가 약 5초(`max.block.ms` 5s 또는 publish deadline 5s) 걸린다. 배치 20개면 회차 하나가 약 100초다. 그래서 뒤쪽 row는 FAILED로 표시되는 순간 이미 재시도 시각이 지나 있다. 다음 회차에 바로 다시 시도된다.
|
||||
- 계산(추론): 전면 장애에서 row 하나가 DEAD까지 가는 데 약 3회차, 대략 5분이다. 5분 넘는 broker 장애는 그동안 claim된 모든 head row를 DEAD로 만든다.
|
||||
- `AMBIGUOUS`(전송됐을 수 있음)도 시도를 쓴다(`:143-147`). 장애 동안 실제로는 저장된 메시지도 DEAD가 될 수 있다. 코드 주석은 "parking it loses a message that was delivered"라며 이 결과를 피하려 하지만 3회 뒤에는 결국 parking한다.
|
||||
- 복구 절차는 row마다 `UPDATE`다(`docs/runbooks/outbox-dead-letter.md:39-41`). runbook의 차단 범위 조회(`:27`)는 `aggregate_id`·`occurred_at` 기준이라 현재 FIFO 키 `(tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)`와 다르다.
|
||||
- 상수를 바꾸면 registry와 runbook을 같이 바꿔야 한다는 결정(I10)이 있다(`application-core/README.md` OutboxBackoffPolicy 절).
|
||||
- 발생 조건: Kafka 장애·네트워크 단절이 약 5분 이상.
|
||||
- 영향: 장애가 끝나도 이벤트 발행이 자동으로 재개되지 않는다. 장애 동안 이벤트를 만든 모든 aggregate가 운영자 개입 전까지 멈춘다.
|
||||
- 심각도·우선순위: High / P2. 지원 장애 조건에서 중요한 기능이 멈춘다. 데이터는 남아 있고 경보(`outcome=DEAD`)와 수동 절차가 있어 P2로 둔다.
|
||||
- 통제 수준: M1(runbook·경보 문서), 자동 복구 M0. 증거 E1 + 계산.
|
||||
- 결정의 근거: 기록된 의도는 "상수를 runbook과 맞춘다"이다. 장애 길이와 예산의 관계는 기록되어 있지 않다.
|
||||
- 최소 개선 방향
|
||||
- (a) 재시도 시각을 실패 시점 `clock.instant()`로 계산한다. 비용이 가장 작고 예산이 의도한 시간만큼 유지된다.
|
||||
- (b) `AMBIGUOUS`와 broker 도달 불가류 실패는 시도 예산을 쓰지 않고 상한 있는 지연(예: 최대 5분)으로 계속 재시도한다. 예산은 payload 자체의 거부에만 쓴다.
|
||||
- (c) DEAD 일괄 재구동 절차(조건별 `UPDATE`와 차단 범위 조회)를 runbook에 현재 FIFO 키로 고친다.
|
||||
- 버린 대안: `MAX_ATTEMPTS`만 늘리기. 장애 길이에 비례해 숫자를 계속 키워야 하고, 진짜 poison row가 늦게 격리된다.
|
||||
- 재검토 조건: relay가 per-row 지연 대신 broker 상태(circuit)를 보고 회차를 건너뛰게 되면 (b)는 불필요할 수 있다.
|
||||
- 완료 기준: broker가 10분 멈췄다가 돌아오면 운영자 개입 없이 PENDING/FAILED가 PUBLISHED로 간다.
|
||||
- 검증 방법: 시계를 주입한 relay 테스트로 장애 10분을 흉내 낸다. 실제 확인은 Toxiproxy lane(이미 vendored 쪽에 있다)에 앱 relay를 올려서 한다(06-09).
|
||||
|
||||
### 06-04 — aggregate 하나의 발행 속도가 poll 주기당 1건으로 묶인다
|
||||
|
||||
- 성격: 구조적 위험(성능)
|
||||
- 관련 관점: 14, 13, 5
|
||||
- 근거
|
||||
- claim은 aggregate마다 가장 앞 row 하나만 고른다(`PostgreSqlOutboxClaimRepository.java:27-36`).
|
||||
- relay는 tick마다 한 번만 claim한다. 배치가 꽉 차도 바로 다음 claim을 하지 않는다(`OutboxRelayScheduler.java:36-39`, fixed-delay `PT5S`).
|
||||
- 그래서 e1이 이번 회차에 발행돼도 e2는 다음 tick까지 기다린다.
|
||||
- 계산(추론): aggregate 하나는 최대 0.2건/초다. 인스턴스 하나는 최대 20건/5초 ≈ 4건/초다. aggregate 하나에 이벤트 100건이 쌓이면 비우는 데 약 8분 이상 걸린다.
|
||||
- 한 회차의 DB 왕복은 claim 1 + row마다 UPDATE(claim flush) + row마다 완료 트랜잭션 1 + 지표 GROUP BY 2다. 배치 20이면 약 43문장이다.
|
||||
- 발생 조건: 한 aggregate가 초당 0.2건 넘게 이벤트를 만들거나, 백로그가 인스턴스당 초당 4건을 넘는다.
|
||||
- 영향: `outbox.publisher.lag`가 계속 늘어난다. 하류 소비가 분 단위로 늦어진다.
|
||||
- 심각도·우선순위: Medium / P2. 업무 부하에 따라 달라진다. 템플릿 기본값이 그대로 복제된다.
|
||||
- 통제 수준: 처리량 상한을 알리는 문서·검사 없음(M0). 증거 E1 + 계산. 실측 안 함.
|
||||
- 최소 개선 방향: 배치가 꽉 찼으면 다음 tick을 기다리지 않고 곧바로 다시 claim한다(상한 있는 반복). aggregate 안 처리량이 필요하면 claim에서 aggregate별로 "앞 row가 같은 lease에 잡힌 경우" 다음 row까지 함께 가져오는 방법을 비교한다.
|
||||
- 버린 대안: poll 주기만 줄이기. 빈 tick마다 DB 질의와 지표 질의가 늘어난다.
|
||||
- 재검토 조건: 목표 처리량을 합의하면 그 수치로 다시 판단한다.
|
||||
- 완료 기준: 백로그 상태에서 인스턴스 처리량이 poll 주기에 묶이지 않는다. 처리량 상한을 README에 숫자로 적는다.
|
||||
- 검증 방법: PostgreSQL 통합 테스트에서 같은 aggregate 이벤트 N건이 몇 번의 relay 호출로 비워지는지 센다.
|
||||
|
||||
### 06-05 — relay가 꺼져 있거나 실패하는 동안 outbox 지표가 갱신되지 않는다
|
||||
|
||||
- 성격: 확인된 결함
|
||||
- 관련 관점: 7, 8, 10, 5
|
||||
- 근거
|
||||
- relay 기본값은 꺼짐이다(`persistence-jpa.yml:190` `${APP_OUTBOX_RELAY_ENABLED:false}`, `OutboxSettings.java:39-43`).
|
||||
- `outbox.pending.size`·`outbox.publisher.lag` 갱신은 relay scheduler 안에서만 일어난다(`OutboxRelayScheduler.java:48-49`가 유일한 호출자).
|
||||
- relay 회차가 예외로 끝나면 catch로 가서 지표 갱신을 건너뛴다(`:39-58`). DB 장애 동안 게이지가 마지막 값에 멈춘다.
|
||||
- 실험 2: 지표 호출 두 줄을 막아도 `composition:outbox-relay` 테스트 18개가 모두 통과했다. `OutboxMetrics` 단위 테스트가 없다.
|
||||
- 대비: vendored relay는 "relay를 잊으면 조용히 실패한다"를 문제로 적고 lifecycle로 강제한다(`MessagingOutboxRelayLifecycle.java:11-13`).
|
||||
- 발생 조건: messaging을 고르고 `APP_OUTBOX_RELAY_ENABLED`를 빠뜨린 배포. 또는 relay가 매 회차 예외를 던지는 장애.
|
||||
- 영향: row가 쌓여도 `outbox_publisher_lag` 경보가 울리지 않는다. runbook의 감지 조건(`outbox-publish-failed.md:21-23`)이 성립하지 않는다.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 통제 수준: M0(감지 경로가 relay 실행에 종속). 증거 E2(변이 실험).
|
||||
- 결정의 근거: 적용 제외 — 지표 수집 위치를 relay에서 떼어 내는 단순 결함이다.
|
||||
- 최소 개선 방향: 게이지 갱신을 relay와 독립된 주기 작업(또는 Micrometer gauge의 지연 조회)으로 옮긴다. relay가 꺼져 있고 발행 포트가 있으면 기동 시 WARN 한 줄을 남긴다. `OutboxMetrics` 테스트를 추가한다.
|
||||
- 완료 기준: relay가 꺼진 상태에서도 `outbox.pending.size{status=PENDING}`가 실제 행 수를 보여 준다.
|
||||
- 검증 방법: relay를 끈 컨텍스트 테스트에서 PENDING row를 넣고 게이지 값을 단언한다. 실험 2 변이가 죽는지 확인한다.
|
||||
|
||||
### 06-06 — application EventId 문법과 platform MessageId(UUID)가 다르다
|
||||
|
||||
- 성격: 확인된 결함(잠재)
|
||||
- 관련 관점: 17, 1, 5, 22
|
||||
- 근거
|
||||
- application은 `[A-Za-z0-9][A-Za-z0-9._:-]*` 1–96자를 받는다(`EventId.java:6-12`).
|
||||
- bridge는 `UUID.fromString`으로 바꾼다. UUID가 아니면 `IllegalArgumentException` → `REJECTED_BEFORE_SEND` → DEAD다(`PlatformIntegrationEventPublishAdapter.java:62-67,132-134`). 기존 테스트도 `"event-1"`이 REJECTED가 됨을 단언한다.
|
||||
- `SubmitDurableOperationUseCase.canonicalIdentity`는 UUID가 아닌 operation id를 `"operation-" + sha256`으로 바꾼다(`SubmitDurableOperationUseCase.java:167-173`). 이 값은 UUID가 아니므로 이 경로로 들어온 이벤트는 항상 DEAD다. 지금은 HTTP adapter가 UUID만 만들어 도달하지 않는다(`DurableOperationController.java:86`).
|
||||
- 발생 조건: UUID가 아닌 operation id(새 inbound adapter, 클라이언트 지정 id) 또는 UUID가 아닌 event id를 만드는 use case.
|
||||
- 영향: append는 성공하고 비즈니스 트랜잭션은 커밋된다. 실패는 나중에 relay에서 DEAD로 나타나고 aggregate를 막는다. 원인이 호출 지점과 멀다.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 통제 수준: M0. 증거 E1(+ 기존 bridge 테스트).
|
||||
- 최소 개선 방향: 둘 중 하나로 계약을 맞춘다. (a) application `EventId`를 UUID로 좁힌다. 비용이 작고 실패가 append 시점으로 당겨진다. (b) bridge가 비 UUID id를 결정적 UUIDv5로 바꾼다. 소비자가 보는 id가 원래 값과 달라진다. 소비자 중복 제거 키가 event id라는 계약(`application-core/README.md`)을 지키려면 (a)가 낫다. `canonicalIdentity`의 digest 경로는 (a)에 맞춰 UUIDv5로 바꾼다.
|
||||
- 완료 기준: bridge가 거부할 id는 `IntegrationEventDraft` 생성 또는 encode 단계에서 거부된다.
|
||||
- 검증 방법: 비 UUID event id로 encode를 호출하면 예외가 나는 테스트.
|
||||
|
||||
### 06-07 — 샘플이 aggregate 순서 번호를 벽시계로 만든다
|
||||
|
||||
- 성격: 구조적 위험
|
||||
- 관련 관점: 12, 1, 11, 20
|
||||
- 근거
|
||||
- `PortfolioEventOutbox.java:92,98-105`가 `AggregateOrder(sequenceOf(occurredAt), 0)`으로 순서를 만든다. 값은 epoch 마이크로초다.
|
||||
- FIFO gate는 이 번호로 앞뒤를 정한다(`PostgreSqlOutboxClaimRepository.java:33-35`).
|
||||
- `(tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)`에 유일 제약이 없다(V3·V13·V18·V19 확인, PK는 `event_id`뿐).
|
||||
- 설계 문서는 "strict aggregate ordering은 timestamp가 아니라 explicit aggregate sequence를 요구한다"고 적는다(`docs/superpowers/specs/2026-07-28-messaging-production-capability-design.md:595`).
|
||||
- 발생 조건: 같은 aggregate를 두 인스턴스가 연달아 바꾸고 두 서버 시계가 어긋남. 또는 NTP가 시계를 되돌림. 또는 같은 마이크로초에 두 이벤트.
|
||||
- 영향: 나중에 커밋된 변경의 이벤트가 먼저 나간다. 같은 번호 두 개는 서로를 막지 않아 순서가 정해지지 않는다. 소비자의 "마지막 상태" 판단이 틀린다.
|
||||
- 심각도·우선순위: Medium / P2. 샘플은 새 기능의 복사 원본이다.
|
||||
- 통제 수준: M1(설계 문서), 코드 M0. 증거 E1.
|
||||
- 최소 개선 방향: 샘플에서 aggregate의 버전(낙관적 락 version) 또는 DB 시퀀스를 순서 번호로 쓴다. outbox에 순서 키 유일 제약을 추가해 중복 번호를 append 시점에 거부한다.
|
||||
- 버린 대안: 순서를 `occurred_at`으로만 두기. 지금 바로 이 문제다.
|
||||
- 완료 기준: 샘플의 순서 번호가 aggregate 쓰기와 같은 트랜잭션에서 단조 증가한다. 같은 번호 두 번 append는 실패한다.
|
||||
- 검증 방법: 같은 aggregate에 같은 순서 번호 두 건 append → 제약 위반 테스트. 샘플 use case 테스트에서 연속 변경의 번호가 증가하는지 단언.
|
||||
- 비고: 소유 leaf는 `sample-portfolio`·`persistence-jpa`다. 계약은 이 영역의 FIFO 의미라서 여기 적는다.
|
||||
|
||||
### 06-08 — 소비(consume)를 지원한다는 결정이 application 쪽 경로로 이어지지 않는다
|
||||
|
||||
- 성격: 구조적 위험(기능 개발 경로 공백)
|
||||
- 관련 관점: 2, 20, 25, 17
|
||||
- 근거
|
||||
- 소유자 결정 10: "Kafka 소비 지원. `MessageHandler<T>` 하나 + starter-kafka가 consumer 조립"(followup-status:38).
|
||||
- inbox 중복 제거는 `IdempotentConsumer` bean이 있어야 한다(`MessagingConsumeConfiguration.java:137-144`, 문서 `docs/messaging/outbox-inbox.md:115-119`). 이 타입은 `messaging-reliability`에 있다.
|
||||
- registry에서 `messaging-reliability`·`messaging-reliability-jdbc-postgresql`로 가는 application leaf 간선이 없다. bridge leaf는 `messaging-core-api`만 볼 수 있다(`modules.json` `:adapter:outbound:messaging`). `adapter:inbound:*`에 messaging leaf가 없다.
|
||||
- 저장소 전체에서 application 쪽 `MessageHandler` 구현·예제가 0건이다.
|
||||
- 소비자 중복 제거 의무는 문서에만 있다(`adapter/outbound/messaging/README.md` "중복 가능 구간", runbook `outbox-dead-letter.md:40`).
|
||||
- 발생 조건: 파생 서비스가 이벤트 소비 기능을 처음 만든다.
|
||||
- 영향: 어디에 handler를 둘지, inbox를 어떻게 조립할지 템플릿이 답하지 않는다. 각 팀이 registry 간선을 임의로 늘리거나 중복 제거 없이 소비한다.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 통제 수준: M1(문서). 증거 E1.
|
||||
- 결정의 근거: 기록된 의도는 "지원"이다. 현재 코드는 platform 안에서만 지원한다. 리뷰어 추론: consumer 조립은 platform 조립 경계(starter)에서 끝났고 application 경계 설계가 남았다.
|
||||
- 최소 개선 방향: `adapter:inbound:messaging`(가칭) leaf를 registry에 추가하고 `messaging-core-api`와 inbox 조립용 edge를 준다. 그 leaf가 application 포트(예: `IntegrationEventHandlerPort`)를 platform `MessageHandler`로 감싸는 bridge를 소유한다. 예제 handler 하나와 INBOX_TRANSACTIONAL destination 예시를 둔다.
|
||||
- 버린 대안: app-bootstrap에서 직접 handler bean 등록. composition root에 업무 handler가 들어가 HARD-STOP 4에 가까워진다.
|
||||
- 완료 기준: 샘플 이벤트 하나를 소비하는 handler가 inbox로 중복을 거르고, registry gate를 통과한다.
|
||||
- 검증 방법: Kafka+PostgreSQL 통합 테스트로 같은 메시지 두 번 전달 시 부작용 1회.
|
||||
|
||||
### 06-09 — 실제로 쓰는 발행 경로에는 broker 실연 테스트가 없고, broker 실연 lane은 어떤 기본 게이트에도 없다
|
||||
|
||||
- 성격: 확인된 결함(검증 공백)
|
||||
- 관련 관점: 10, 21, 18
|
||||
- 근거
|
||||
- 앱 경로 `PublishPendingOutboxEventsUseCase → OutboxMessagePublishAdapter → PlatformIntegrationEventPublishAdapter → DefaultMessagePublisher → Kafka`를 한 번에 도는 테스트가 없다. `PublishPendingOutboxEventsUseCase`를 쓰는 통합 테스트는 PostgreSQL + fake publisher뿐이다(`persistence-jpa/src/postgresqlIntegrationTest/.../readiness/*`). 앱 leaf 쪽 Kafka Testcontainers 사용은 0건이다.
|
||||
- Kafka 실연 테스트(`KafkaBrokerIT`, `KafkaAmbiguityChaosIT`, `MessagingLiveRoundTripQualificationTest` 등)는 vendored relay나 publisher 직접 호출을 검증한다. 앱은 vendored relay를 쓰지 않는다.
|
||||
- 이 lane들은 `integrationCheck`에만 묶인다(`src/build.gradle:100-105`). `mainCheck` 로그에서 messaging `integrationTest`는 컴파일만 됐다(`mainCheck.log:246-292`).
|
||||
- 06-01은 각 고리의 단위 테스트가 서로 다른 가정(retryable REJECTED / REJECTED=확정)을 단언하면서 통과해서 숨어 있었다.
|
||||
- 영향: 앱 경로의 실패 분류·종료·재시도가 실제 broker와 맞는지 아무 게이트도 확인하지 않는다.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 통제 수준: M0(앱 경로). 증거 E1.
|
||||
- 최소 개선 방향: `adapter:outbound:messaging-kafka`에 Kafka+PostgreSQL 통합 lane 하나를 두고 앱 relay를 실제로 돌린다: 정상 발행, broker 정지 후 재개(06-03), 종료 중 회차(06-02). lane은 CI 방향 결정에 따라 `mainCheck` 단계에 지정한다.
|
||||
- 버린 대안: vendored relay 테스트를 앱 증거로 인용하기. 다른 코드다.
|
||||
- 완료 기준: 앱 relay가 실제 Kafka로 발행한 레코드를 테스트가 읽어 envelope 바이트를 비교한다. 이 lane이 이름 있는 게이트에 들어 있다.
|
||||
- 검증 방법: 그 lane의 실행 로그.
|
||||
|
||||
### 06-10 — 이벤트 payload 버전을 올리는 방법과 호환성 검사가 없다
|
||||
|
||||
- 성격: 구조적 위험
|
||||
- 관련 관점: 17, 11, 20
|
||||
- 근거
|
||||
- encoder catalog는 `(contractId, payloadVersion)`을 키로 여러 버전을 함께 둘 수 있다(`JsonIntegrationEventEncoder.java:98,157-161`).
|
||||
- 버전 사이 호환성 검사가 없다. 기동 시 검사는 선언 hash와 classpath schema 파일의 일치뿐이다(`src/messaging/CLAUDE.md` "IntegrationEventEncoderPort" 절).
|
||||
- platform의 `schema.compatibility`는 선언만 한다(`docs/messaging/configuration-reference.md:123`).
|
||||
- payload v2를 추가하는 절차 문서가 없다. `payloadVersion`을 설명하는 문서는 `application-core/README.md:28` 한 줄이다.
|
||||
- outbox에 이미 쌓인 v1 row는 저장된 바이트 그대로 나간다(`JpaOutboxStore.java:197-235`). 이 점은 옳다. 다만 소비자가 v1·v2를 함께 받는 기간이 생긴다는 사실이 적혀 있지 않다.
|
||||
- 발생 조건: 기존 이벤트에 필드를 바꾸거나 지우는 변경.
|
||||
- 영향: 깨지는 schema 변경이 게이트를 통과한다. 소비자가 배포 순서에 따라 실패한다.
|
||||
- 심각도·우선순위: Medium / P2.
|
||||
- 통제 수준: M0. 증거 E1.
|
||||
- 최소 개선 방향: 같은 contract의 직전 버전 schema와 새 schema를 비교하는 테스트 fixture를 `shared-contract` 또는 `adapter:outbound:support` testFixtures에 두고, contract를 추가할 때 그 테스트를 함께 만들게 한다. 버전 올리기 절차(새 버전 추가 → 소비자 배포 → 생산자 전환 → 옛 버전 제거)를 README에 적는다.
|
||||
- 버린 대안: 외부 schema registry 도입. 이 템플릿 범위에 비해 운영 비용이 크다.
|
||||
- 완료 기준: 필드 삭제 같은 깨지는 변경이 테스트에서 실패한다.
|
||||
- 검증 방법: 샘플 contract에 깨지는 v2를 넣는 변이 실험.
|
||||
|
||||
### 06-11 — outbox가 둘인데 문서와 주석은 하나처럼 말한다
|
||||
|
||||
- 성격: 개선 제안(이해 비용)
|
||||
- 관련 관점: 4, 5, 23, 24
|
||||
- 근거
|
||||
- `docs/messaging/configuration-reference.md:28-33`: "outbox는 canonical 하나다".
|
||||
- 같은 폴더 `docs/messaging/outbox-inbox.md:28-60`은 vendored `messaging_outbox`와 그 relay(`REJECTED → markFailed`, 종단)를 "Outbox"로 설명한다. 앱이 쓰는 `outbox_event`·`composition:outbox-relay`는 `docs/messaging`에 언급이 없다.
|
||||
- 두 모델은 같은 이름의 상태가 반대 뜻이다. `OutboxPublishOutcome.java` javadoc이 "naming trap between the two outbox models is real"이라고 직접 경고한다.
|
||||
- vendored relay·lifecycle·cleanup bean 정의와 DDL은 runtime classpath에 있다(`messaging-spring-boot-starter/build.gradle:41-42` `implementation`). 조건이 맞지 않아 bean은 안 생긴다.
|
||||
- `MessagingShutdownLifecycle.java:113-116`은 존재하지 않는 relay를 전제로 순서를 설명한다(06-02).
|
||||
- 영향: 새 개발자가 `docs/messaging`을 읽고 앱 outbox의 동작을 잘못 예측한다. DEAD/FAILED 의미를 반대로 읽는다.
|
||||
- 심각도·우선순위: Medium / P3.
|
||||
- 통제 수준: M1(경고 주석 한 곳). 증거 E1.
|
||||
- 결정의 근거: 소유자 결정은 "messaging outbox 유지"다. 이 항목은 유지 자체가 아니라 두 모델의 경계 표시를 다룬다.
|
||||
- 최소 개선 방향: `docs/messaging/outbox-inbox.md` 맨 앞에 "이 문서는 vendored platform outbox다. 이 템플릿의 application은 `outbox_event`와 `composition:outbox-relay`를 쓴다"를 적고 앱 outbox 문서로 연결한다. 두 상태 이름 대응표를 한 곳에 둔다. `configuration-reference.md`의 "하나다"를 "application 경로는 하나다"로 고친다.
|
||||
- 완료 기준: `docs/messaging`에서 앱 outbox 문서로 가는 링크가 있고, 상태 대응표가 하나 있다.
|
||||
- 검증 방법: 문서 리뷰.
|
||||
|
||||
### 06-12 — 배치 크기와 lease 시간의 관계를 검사하지 않는다
|
||||
|
||||
- 성격: 구조적 위험
|
||||
- 관련 관점: 12, 19, 21
|
||||
- 근거
|
||||
- 회차 하나의 최악 시간은 배치 크기 × (송신 전 대기 5s + 응답 대기 5s)다(`KafkaMessagingAutoConfiguration.java:203-206`, `PublishOptions` 기본 5s). 기본값 20이면 약 200초다.
|
||||
- lease는 `in-flight-timeout` 기본 5분이다(`persistence-jpa.yml:196`). 지금은 여유가 있다.
|
||||
- `OutboxSettings`는 각 값을 따로 검사한다(`OutboxSettings.java:35-53`). `batch-size: 40`이면 최악 약 400초로 lease를 넘는다. 그러면 다른 인스턴스가 row를 다시 claim해 같은 이벤트를 또 보낸다. 늦은 쪽은 STALE이 된다(fencing은 상태 덮어쓰기만 막는다).
|
||||
- 영향: 설정 하나로 다중 인스턴스 중복 발행이 정상 운영 중에 생긴다.
|
||||
- 심각도·우선순위: Medium / P3. 기본값에서는 발생하지 않는다.
|
||||
- 통제 수준: M0. 증거 E1 + 계산.
|
||||
- 최소 개선 방향: 기동 시 `batchSize × 2 × publishDeadline < inFlightTimeout`을 검사하고 어기면 기동을 거부한다. 또는 relay가 회차 중 남은 lease를 보고 남은 row를 놓는다.
|
||||
- 완료 기준: lease를 넘을 수 있는 설정 조합이 기동에서 거부된다.
|
||||
- 검증 방법: `OutboxSettings` 바인딩 테스트에 경계 조합 추가.
|
||||
|
||||
### 06-13 — 이 영역 문서·주석의 낡은 설명
|
||||
|
||||
- 성격: 개선 제안
|
||||
- 관련 관점: 24, 9, 26
|
||||
- 근거
|
||||
- `OutboxRelayScheduler.java:15` "Registered by `OutboxConfig`"(실제 `OutboxRelayAutoConfiguration`).
|
||||
- `PublishPendingOutboxEventsUseCase.java:27` "Wired manually by `app-bootstrap`"(실제 `composition:outbox-relay`).
|
||||
- `adapter/outbound/messaging/README.md:73-77` 검증이 "build-tools로 옮겼다", `VerifyMessagingEvidenceTask`(둘 다 없음. 실제는 루트 `src/build.gradle:140` `verifyMessagingContracts`).
|
||||
- `adapter/outbound/messaging/CLAUDE.md:8` "Spring Boot 4.0.0"(실제 4.0.8).
|
||||
- `docs/runbooks/outbox-dead-letter.md:27` 차단 범위 조회가 옛 FIFO 키 사용(06-03).
|
||||
- `OutboxLeaderElectionToken.java:4-5` "presence satisfies the multi-instance coordination requirement". 이 bean을 요구하는 검사가 없다. 리더 선출도 하지 않는다(row 단위 claim이다).
|
||||
- `composition:outbox-relay`, `adapter:outbound:messaging-kafka`에 `CLAUDE.md`가 없다(README만 있음).
|
||||
- 심각도·우선순위: Low / P3.
|
||||
- 최소 개선 방향: 위 문장을 현재 위치로 고친다. `OutboxLeaderElectionToken`은 지우거나 이름을 `OutboxClaimStrategy`처럼 실제 동작으로 바꾼다.
|
||||
- 완료 기준: 위 위치의 설명이 코드와 맞는다.
|
||||
- 검증 방법: 문서 리뷰.
|
||||
|
||||
### 06-14 — DLQ 격리 레코드가 모든 원인을 `POISON_MESSAGE`로 적는다
|
||||
|
||||
- 성격: 개선 제안
|
||||
- 관련 관점: 8, 28
|
||||
- 근거: `KafkaDeadLetterQuarantine.java:41-47`. 복원 불가 레코드와 "시도 예산 소진"(일시 장애로 handler가 계속 실패한 경우)을 같은 category로 적는다.
|
||||
- 영향: redrive 판단 때 원인을 구분하지 못한다. 일시 장애로 격리된 메시지를 poison으로 오해한다.
|
||||
- 심각도·우선순위: Low / P3.
|
||||
- 최소 개선 방향: 호출자가 사유 category를 넘기게 한다(`UNDECODABLE` / `ATTEMPTS_EXHAUSTED`).
|
||||
- 완료 기준: 두 경로가 다른 header 값을 남긴다.
|
||||
- 검증 방법: `KafkaConsumerRegistrarTest`에 header 단언 추가.
|
||||
|
||||
## 4. 31절 시나리오 추적
|
||||
|
||||
### 4.1 정상 쓰기 → 발행 (`POST` durable operation)
|
||||
|
||||
| 항목 | 내용 |
|
||||
| --- | --- |
|
||||
| 입력 신뢰 수준 | HTTP 본문은 외부 입력이다. operation id는 서버가 UUID로 만든다(`DurableOperationController.java:86`) |
|
||||
| 인가 위치 | web adapter(이 영역 밖). relay는 `@RequiresPermission("outbox:relay")`가 붙어 있지만 bean이 아니라 관례로만 지킨다 |
|
||||
| 규칙 소유 객체 | 이벤트 생성 규칙: `SubmitDurableOperationUseCase`. 봉투 규칙: `JsonIntegrationEventEncoder`. 순서 규칙: FIFO gate(SQL) |
|
||||
| 트랜잭션 | `transactions.inWrite` 하나 안에서 operation 저장과 `outbox.append`(`SubmitDurableOperationUseCase.java:106-140`). append는 caller 트랜잭션이 없으면 거부한다(`JpaOutboxStore.java:61`) |
|
||||
| 외부 부작용 | 요청 안에서는 없다. relay가 커밋 뒤 비동기로 Kafka에 보낸다 |
|
||||
| 성공의 의미 | 202 응답은 "operation과 발행 의도가 함께 커밋됨"이다. 발행 완료가 아니다 |
|
||||
| 오류 변환 | 발행 실패는 요청에 영향이 없다. relay에서 FAILED/DEAD로 남고 `Slf4jOutboxRelayFailureReportAdapter`가 ERROR 한 줄을 남긴다 |
|
||||
| 진단 정보 | `correlation_id`(= operation id), `event_id`, `outbox.*` 지표. 단 relay가 꺼져 있으면 지표가 안 움직인다(06-05) |
|
||||
|
||||
원자성 판정: outbox 기록과 비즈니스 쓰기는 같은 JPA 트랜잭션에서 커밋된다. `CallerTransaction.require`가 경계에서 강제한다(M4, 이 경로 한정). 비즈니스 저장소가 JPA가 아닌 경우(Mongo 등)의 원자성은 다른 영역에서 확인해야 한다(>).
|
||||
|
||||
### 4.2 메시지 중복·역순
|
||||
|
||||
- 중복: lease 만료 재claim, `markPublished` 실패, AMBIGUOUS 재시도에서 같은 event id로 다시 나간다. 소비자 중복 제거가 필요하지만 application 쪽 소비 경로가 없다(06-08).
|
||||
- 역순: FIFO gate는 aggregate마다 head 하나만 내보낸다. relay는 응답을 기다린 뒤 다음 row로 간다(`OutboxMessagePublishAdapter.java:43` `join`). Kafka producer는 idempotence를 켠다(`KafkaMessagingAutoConfiguration.java:184-190`). 그래서 순서 번호가 맞으면 역순은 없다. 순서 번호 자체가 벽시계면 역순이 생긴다(06-07).
|
||||
|
||||
### 4.3 여러 서버의 relay 실행
|
||||
|
||||
- claim은 `FOR UPDATE SKIP LOCKED`, 인스턴스마다 UUID owner, row마다 token 증가(`JpaOutboxStore.java:105-127`).
|
||||
- 완료는 owner·token이 맞을 때만 적용된다. 아니면 STALE(`:136-162`). `PostgreSqlOutboxConcurrentRelayIntegrationTest`가 있다.
|
||||
- 같은 aggregate의 두 row는 두 인스턴스가 동시에 가져갈 수 없다. 앞 row가 PUBLISHED가 아니면 뒤 row는 gate에 걸린다.
|
||||
- 남은 위험: 배치 시간이 lease를 넘는 설정(06-12).
|
||||
|
||||
### 4.4 외부 응답 지연·유실 (Kafka 느림·정지)
|
||||
|
||||
- 송신 전 대기 5s(`max.block.ms`), 응답 대기 5s(publish deadline)로 묶인다. relay thread가 무한정 막히지 않는다.
|
||||
- deadline 초과는 AMBIGUOUS로 분류된다(`DefaultMessagePublisher.java:244-256`). 결과 불명을 "전송됐을 수 있음"으로 남기는 것은 옳다.
|
||||
- 장애가 약 5분을 넘으면 DEAD가 대량으로 생긴다(06-03).
|
||||
|
||||
### 4.5 종료·재시작
|
||||
|
||||
- 진행 중 relay 회차는 끝까지 돈다. 그러나 platform admission이 먼저 닫혀 남은 row가 DEAD가 된다(06-01, 06-02).
|
||||
- 프로세스가 강제 종료되면 IN_FLIGHT row는 5분 뒤 다른 인스턴스가 가져간다. 이 경로는 설계대로다.
|
||||
- consumer 쪽은 drain 마감 30s 뒤 미정산 메시지를 broker 재전달에 맡긴다(`MessagingShutdownLifecycle.java:21-28`). 앱 handler가 없어 앱 경로로는 확인 대상이 없다.
|
||||
|
||||
### 4.6 신·구 버전 공존
|
||||
|
||||
- outbox row는 append 때의 바이트를 그대로 내보낸다. 배포가 바뀌어도 옛 row의 봉투는 변하지 않는다.
|
||||
- destination 선언이 새 배포에서 빠지면 옛 row는 `PUBLISH_PREPARATION_FAILED` REJECTED → DEAD가 된다. 이것은 설정 오류라 확정 거부로 보는 것이 맞다.
|
||||
- payload 버전 호환성 검사와 절차가 없다(06-10).
|
||||
|
||||
### 4.7 선택 어댑터 제거
|
||||
|
||||
- `app-bootstrap/build.gradle`에서 `messaging-kafka` 줄을 지우면 bridge·platform·Kafka client·기본 설정이 함께 빠진다(README 서술, `KafkaCapabilityActivationTest`).
|
||||
- 발행 포트가 없으면 relay scheduler가 생기지 않고 PENDING row가 그대로 남는다(`OutboxRelayAutoConfiguration.java:62-64`). 대역 publisher가 row를 DEAD로 소진하지 않는다. 설계대로다.
|
||||
- 이때 지표도 갱신되지 않아 적체가 보이지 않는다(06-05).
|
||||
|
||||
### 4.8 적용 제외
|
||||
|
||||
| 시나리오 | 사유 |
|
||||
| --- | --- |
|
||||
| 세션·토큰 갱신 경쟁 | 이 영역에 사용자 세션이 없다 |
|
||||
| 다른 사용자 리소스 접근 | 사용자 요청 경로가 없다. tenant는 봉투 필드로만 옮긴다 |
|
||||
| 큰 입력·목록 조회 | payload 상한은 platform이 검사한다(`KafkaMessagingTransport.java:124-130`, admission). 목록 조회 API는 없다 |
|
||||
| DB 오류·경쟁 | `markPublished` 실패 경로만 해당하며 4.3·README에 설명된 대로 IN_FLIGHT로 남아 재claim된다. 별도 추적 생략 |
|
||||
|
||||
## 5. 41절 설계 선택 검토
|
||||
|
||||
### 5.1 application outcome 어휘: "REJECTED = 확정 거부 → 즉시 DEAD"
|
||||
|
||||
1. 필요한 것: relay가 재시도할 실패와 재시도해도 소용없는 실패를 구분해야 한다.
|
||||
2. 지킬 성질: 다시 보내면 성공할 수 있는 이벤트는 DEAD가 되면 안 된다. 다시 보내도 실패할 이벤트는 예산을 낭비하지 않는다.
|
||||
3. 현재 보장: 4값 enum(`OutboxPublishOutcome`)과 bridge 번역. platform의 `retryable` 정보는 번역에서 버려진다. 성질 1을 지키지 못한다(06-01).
|
||||
4. 대안: (a) 현상 유지, (b) 5번째 값 "전송 안 됨 + 재시도 가능", (c) REJECTED는 전부 retryable로 보고 예산으로 제한, (d) relay가 platform 타입을 직접 본다.
|
||||
5. 비용: (a) 배포·장애마다 영구 정지 위험. (b) enum 값 하나와 relay 분기 하나. (c) 진짜 poison row가 3회 동안 aggregate를 막고 예산을 쓴다. (d) 경계가 깨진다.
|
||||
6. 선택: (b). 의미를 잃지 않는 가장 작은 변경이다.
|
||||
7. 재검토 조건: platform이 retryable REJECTED를 없애고 그 경우를 AMBIGUOUS가 아닌 별도 completion으로 바꾸면 (a)로 돌아가도 된다.
|
||||
|
||||
### 5.2 relay 실행 방식: `@Scheduled` fixed-delay, tick당 claim 1회, aggregate당 head 1건
|
||||
|
||||
1. 필요한 것: 커밋된 이벤트를 순서대로, 다중 인스턴스에서 겹치지 않게 내보낸다.
|
||||
2. 지킬 성질: aggregate 안 순서, 같은 row 동시 발행 금지, 종료 시 진행 중 row를 망가뜨리지 않음.
|
||||
3. 현재 보장: 순서와 동시성은 SQL gate와 fencing으로 M4에 가깝게 지킨다. 종료 조율은 없다(06-02). 처리량은 poll 주기에 묶인다(06-04).
|
||||
4. 대안: (a) 현상 유지, (b) relay 전용 SmartLifecycle 루프(배치가 차면 바로 다시 claim, stop에서 drain), (c) vendored `OutboxRelayWorker`로 교체, (d) CDC(Debezium).
|
||||
5. 비용: (a) 0, 종료·처리량 문제 유지. (b) 루프 코드 소유, 테스트 필요. (c) outbox 모델·DDL·상태 의미 전환이 필요하고 소유자 결정 7(앱 outbox 하나)과 충돌한다. (d) 운영 인프라 추가, 2026-09-25에 삭제한 방향.
|
||||
6. 선택: (b). 지금 결정과 충돌하지 않고 두 문제를 같이 줄인다.
|
||||
7. 재검토 조건: relay를 별도 worker 배포 단위로 떼면 lifecycle 대신 그 프로세스의 종료 절차로 판단한다. 목표 처리량이 수백 건/초를 넘으면 (d)를 다시 비교한다.
|
||||
|
||||
### 5.3 outbox 두 개 유지(소유자 결정)
|
||||
|
||||
1. 필요한 것: application은 검증된 봉투를 같은 트랜잭션에 기록하는 outbox가 필요하다. platform은 제품으로서 자기 outbox를 가진다.
|
||||
2. 지킬 성질: 개발자가 어느 outbox가 동작 중인지 헷갈리지 않는다. platform의 종료·지표 설계가 앱 경로에도 맞는다.
|
||||
3. 현재 보장: bean 조건으로 vendored relay가 앱에서 생기지 않는다. 문서·종료 순서는 vendored relay 기준이다(06-02, 06-11).
|
||||
4. 대안: (a) 결정 유지 + 경계 표시 보강, (b) vendored outbox를 starter `implementation`에서 빼서 opt-in 의존으로, (c) 하나로 합치기.
|
||||
5. 비용: (a) 문서·주석 수정. (b) starter 의존 정리와 vendored 테스트 classpath 조정. (c) 결정 번복.
|
||||
6. 선택: (a)를 먼저, (b)는 다음 단계 후보. 결정은 유지한다.
|
||||
7. 재검토 조건: 앱이 vendored relay의 기능(claim-check, ordering key 등)을 필요로 하면 다시 비교한다.
|
||||
|
||||
## 6. 리팩토링 후보
|
||||
|
||||
| 대상 | 무엇을 왜 | 단순화의 보존 조건 |
|
||||
| --- | --- | --- |
|
||||
| `OutboxRelayScheduler` + `OutboxRelayAutoConfiguration` | `@Scheduled`를 relay 전용 lifecycle 루프로 바꾼다(06-02, 06-04) | 발행 포트가 없으면 relay가 없다. `relay-enabled=false`면 relay가 없다. 예상 못 한 예외에도 루프가 산다. 같은 ERROR 필드(`retry.disposition=next-tick`)를 남긴다. 회차가 겹치지 않는다 |
|
||||
| `OutboxMetrics` | relay에서 떼어 내 독립 갱신(06-05) | PUBLISHED는 세지 않는다. `MeterRegistry`가 없으면 no-op. event type이 사라지면 series를 덮어쓴다 |
|
||||
| `OutboxLeaderElectionToken` | 소비자 없는 marker. 지우거나 실제 동작 이름으로 | `BootstrapCapabilityReachabilitySystemTest.java:30`의 단언을 함께 고친다 |
|
||||
| `PlatformIntegrationEventPublishAdapter.mapOutcome` | retryable 정보를 보존하는 번역(06-01) | CONFIRMED·AMBIGUOUS 번역은 그대로. transmission 근거로 before/after를 나누는 규칙 유지. 문자열 비교 금지(MSG-022) |
|
||||
| starter 테스트 리소스 2개 | 참조 없는 옛 prefix fixture 삭제(M-8a) | 없음 |
|
||||
|
||||
## 7. 기능 개발 패턴과 판단 지점 (매뉴얼 재료)
|
||||
|
||||
### 템플릿이 주는 틀
|
||||
|
||||
- 새 이벤트 발행: `IntegrationEventContractContribution` bean 등록 → use case에서 `IntegrationEventDraft` 생성 → `IntegrationEventEncoderPort.encode` → 같은 `inWrite` 안에서 `OutboxAppendPort.append`. 예시는 `SubmitDurableOperationUseCase`(단건 aggregate)와 sample `PortfolioEventOutbox`(여러 이벤트).
|
||||
- destination 선언: `app.messaging.destinations.<logical>`(`docs/messaging/configuration-reference.md`).
|
||||
- 발행 켜기: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, `APP_MESSAGING_PRODUCER_ID`, `APP_MESSAGING_KAFKA_BROKERS`, `APP_OUTBOX_ENABLED=true`, `APP_OUTBOX_RELAY_ENABLED=true`.
|
||||
- fake: application-core testFixtures `InMemoryOutboxStore`, 계약 `OutboxLeaseFencingContract`.
|
||||
|
||||
### 빠진 것
|
||||
|
||||
- 이벤트 소비(handler 위치, inbox 조립) 예제와 leaf(06-08).
|
||||
- aggregate 순서 번호를 만드는 올바른 예(06-07).
|
||||
- payload 버전 올리기 절차와 호환성 테스트(06-10).
|
||||
- 앱 relay를 실제 Kafka로 돌리는 테스트 틀(06-09).
|
||||
- `MessagePublisher` fake와 본체의 공통 계약(TEST-FAKE-MessagePublisher).
|
||||
|
||||
### 개발자가 내려야 하는 판단
|
||||
|
||||
1. 이 이벤트의 aggregate는 무엇이고 순서 번호는 어디서 오는가? 벽시계가 아니라 aggregate version이나 DB 시퀀스를 쓴다.
|
||||
2. event id는 무엇으로 만드는가? 소비자 중복 제거 키가 되므로 재시도해도 같은 값이 나와야 한다. 지금 bridge는 UUID만 받는다(06-06).
|
||||
3. 이 이벤트는 발행 완료를 기다려야 하는 요청인가? 아니라면 202 + outbox. 기다려야 하면 outbox만으로는 요구를 못 채운다(가이드 41.6).
|
||||
4. payload를 바꾸는가? 바꾸면 새 `payloadVersion`을 추가하고 소비자가 먼저 두 버전을 읽게 한다.
|
||||
5. 이 destination의 소비자는 부작용이 있는가? 있으면 INBOX_TRANSACTIONAL을 쓴다.
|
||||
6. 한 aggregate가 초당 몇 건을 만드는가? 0.2건/초를 넘으면 현재 relay 기본값으로는 지연이 쌓인다(06-04).
|
||||
7. relay를 몇 개 인스턴스에서 켤 것인가? batch-size를 올리면 lease 시간과 함께 계산한다(06-12).
|
||||
|
||||
## 8. 28개 관점 판정표
|
||||
|
||||
기호: O 충족, P 부분, X 미충족, ? 미검증, - 적용 제외, > 다른 영역.
|
||||
|
||||
| 번호 | 관점 | 판정 | 한 줄 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | P | 실패 경로를 의식한 코드가 많다. platform과 application 사이 실패 의미 번역에 결함(06-01, 06-06) |
|
||||
| 2 | 구조적 성숙도 | P | 발행 경로는 port → bridge → platform으로 깨끗하다. 소비 경로에 application leaf가 없다(06-08) |
|
||||
| 3 | 변경 용이성 | P | 새 이벤트 추가 경로는 짧다. payload 버전 변경 경로가 없다(06-10) |
|
||||
| 4 | 인지 부하 | P | 두 outbox 모델과 반대 뜻의 상태 이름(06-11) |
|
||||
| 5 | 위험 가시성 | P | 중복 가능 구간은 README에 있다. "REJECTED = 영구"라는 가정이 코드에서 보이지 않는다(06-01) |
|
||||
| 6 | 실패 성숙도 | X | 일시 거부·종료·짧은 장애가 영구 DEAD로 이어진다(06-01, 06-02, 06-03) |
|
||||
| 7 | 운영 성숙도 | P | runbook·경보·구조화 ERROR가 있다. relay 꺼짐·실패 중 지표 정지(06-05), runbook 조회가 옛 키 |
|
||||
| 8 | 디버깅 가능성 | P | failure report에 event·aggregate·correlation id가 있다. DLQ 사유가 한 값(06-14) |
|
||||
| 9 | 유지보수 성숙도 | P | 주석·README에 낡은 위치 설명(06-13) |
|
||||
| 10 | 테스트 성숙도 | P | 단위 테스트 촘촘하고 빠름(합계 수 초). 앱 경로 실연 테스트 없음(06-09), 지표 변이 생존(06-05) |
|
||||
| 11 | 데이터 성숙도 | P | 봉투 바이트·hash 보존이 좋다. 순서 키 유일 제약 없음(06-07) |
|
||||
| 12 | 동시성 성숙도 | P | SKIP LOCKED + fencing은 좋다. 배치·lease 관계 미검사(06-12), 종료 순서(06-02) |
|
||||
| 13 | 확장성 | P | 인스턴스 수평 확장은 된다. aggregate당 처리량 상한(06-04) |
|
||||
| 14 | 성능 성숙도 | ? | 계산만 했다. 실측 없음. 회차당 약 43 DB 문장, 인스턴스당 최대 약 4건/초 |
|
||||
| 15 | 보안 성숙도 | O | Kafka TLS/SASL·ACL 적용 확인(M-2 해결). 실패 report에 payload를 싣지 못하게 타입으로 막음 |
|
||||
| 16 | 의존성 성숙도 | P | broker SDK는 선택 줄을 지우면 빠진다. starter가 쓰지 않는 vendored outbox 구현을 `implementation`으로 싣는다 |
|
||||
| 17 | API / Contract 성숙도 | P | 봉투 v1 schema와 hash 검사가 있다. EventId/MessageId 불일치(06-06), payload 호환성 없음(06-10) |
|
||||
| 18 | 배포 성숙도 | X | 배포 종료 중 row가 DEAD가 될 수 있다(06-02). broker 실연 lane이 기본 게이트 밖(06-09) |
|
||||
| 19 | 설정 성숙도 | P | strict 바인딩, producer-id 필수. relay 기본 꺼짐의 결과가 안 보임(06-05), 값 사이 관계 미검사(06-12) |
|
||||
| 20 | 개발자 경험 | P | 발행 한 줄 켜기가 쉽다. 소비·버전·순서 번호 안내가 없다(06-07, 06-08, 06-10) |
|
||||
| 21 | Guardrail 성숙도 | P | caller 트랜잭션 강제, 대역 publisher 금지, producer-id 필수가 좋다. 이벤트 id·순서 번호·설정 조합 가드 없음 |
|
||||
| 22 | 추상화 성숙도 | P | bridge는 필요한 만큼만 안다. outcome 어휘가 platform 의미 하나를 담지 못한다(06-01) |
|
||||
| 23 | 일관성 | P | platform 종료 설계와 앱 relay 방식이 다르다(06-02, 06-11) |
|
||||
| 24 | 네이밍 / 의미 성숙도 | P | `OutboxLeaderElectionToken`이 하지 않는 일을 이름으로 말한다. 두 outbox의 FAILED 의미 반대 |
|
||||
| 25 | 조직 확장성 | P | 발행은 팀별로 독립 추가 가능. 소비는 registry 간선을 각자 만들게 된다(06-08) |
|
||||
| 26 | Ownership 성숙도 | P | leaf README가 근거를 잘 남긴다. composition·messaging-kafka에 `CLAUDE.md` 없음 |
|
||||
| 27 | 삭제 가능성 | O | messaging 줄 하나로 bridge·platform·Kafka가 함께 빠지고, relay는 남은 row를 소진하지 않는다 |
|
||||
| 28 | 회복 가능성 | X | DEAD는 수동 SQL로만 풀리고 짧은 장애에도 대량 발생한다(06-03) |
|
||||
@@ -0,0 +1,422 @@
|
||||
# 07 — 조립 루트·공용 런타임·설정 계약·컨테이너 (bootstrap-composition-config)
|
||||
|
||||
- 기준: 브랜치 `main`, 커밋 `01a8a2a70`
|
||||
- 맡은 leaf: `app-bootstrap`, `composition:service-runtime`, `composition:idempotency`(조립 쪽), `sample-portfolio`
|
||||
- 맡은 비-leaf 범위: 설정·환경 계약(`app.*` prefix, env key, `verifyEnvKeys`), `src/Dockerfile`, `src/Dockerfile.sample`, 루트 compose 파일, 보안 기본값
|
||||
- 증거 표기: 가이드 35.5 — E1 정적 확인, E2 테스트 실행, E3 실험 확인
|
||||
|
||||
## 1. 범위
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 | `clean-architecture-backend-template`, Gradle 루트 `src/` |
|
||||
| 커밋·시점 | `01a8a2a70`, 2026-11-01 20:30~20:50 KST. 메인 repo 작업 트리는 깨끗한 상태 |
|
||||
| 목적·실행 구성 | 템플릿. 기본 조합은 web + 관측 + cores + support/identifier. 단일 배포 단위, 다중 인스턴스는 `APP_MULTI_INSTANCE_ENABLED`로 선택 |
|
||||
| 규모·운영 목표 | 정해진 목표 없음. 그래서 "운영 준비 완료" 판정은 하지 않는다 |
|
||||
| 읽은 코드·구성 | `app-bootstrap/src/main` 전체(31 java, yml 8, logback), `build.gradle` 전체, `composition/service-runtime`·`composition/idempotency` main 전체, `sample-portfolio`의 조립(`SamplePortfolioApplication`, `bootstrap/**`), `WorkLogController`, WorkLog 유스케이스, `application.yml`, README·CLAUDE.md, `src/Dockerfile`, `src/Dockerfile.sample`, `src/.dockerignore`, `src/.env.example`, 루트 `docker-compose*.yml`, build-logic `ca.config-contract`, support `startup/*`, persistence-jpa `JpaStartupAutoConfiguration`·`MigrationStartupRunner`(타이밍 확인용), web `WebSecurityAutoConfiguration`·`MethodSecurityConfig`·`JwtDecoderConfig`·`SecuritySettings` |
|
||||
| 게이트(오케스트레이터 실행) | `ci` rc=0(434s, 잠금 대기 포함). `mainCheck` rc=1 — 실패는 `:adapter:outbound:objectstorage:objectStorageMinioContractTest`·`objectStorageMinioFaultTest`의 `ContainerFetchException`(MinIO 이미지 조회 실패, 08 영역). 같은 실행에서 `:app-bootstrap:verifyEnvKeys` OK(346 env keys, 249 APP_ 참조), `:app-bootstrap:systemTest` 4 suite 8 test 통과, `:app-bootstrap:publicPathSnapshotTest`, `:sample-portfolio:webSystemTest` 실행됨 |
|
||||
| 이 리뷰가 돌린 실험 | (1) worktree `wt-07`에서 `:app-bootstrap:systemTest --tests '*ExperimentProbeTest*'` — BUILD SUCCESSFUL 10s, 부하 7~15. 기본 조합을 실제로 띄워 트레이서·로깅·audience·지연 초기화를 관찰. (2) `Dockerfile.sample`과 `Dockerfile`의 builder 단계 COPY 집합을 그대로 재현한 디렉터리에서 `./gradlew help --offline` — sample 집합 rc=1, main 집합 rc=0. 둘 다 끝난 뒤 worktree·임시 디렉터리 삭제 |
|
||||
| 확인 못 한 것 | 실제 `docker build`(이미지 빌드·기동). JPA를 켠 조합에서 prod 검증 순서의 실측(PostgreSQL 필요). `:app-bootstrap:integrationTest`는 이번 게이트에 없음(결과 파일이 2026-09-28). sample `systemTest`·`integrationTest`도 이번 게이트에 없음. 부하·메모리 측정 |
|
||||
| 이전 리뷰와 비교 | techlead `12-bootstrap-sample.md`, followup-status L·S6 행, `2026-09-07-app-bootstrap-module-code-review.md`(BOOT-001~017, 2026-09-19 closure에서 전부 닫힘) |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
followup-status에서 `남음`이던 행과 이 영역의 핵심 행만 다시 봤다. BOOT-001~017은 closure 문서 이후 코드가 크게 바뀌어(바인더·startup 어휘가 support로 이동) 표본만 확인했다.
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| L-2b runtime.yml multi-instance 주석 | 남음 | `src/app-bootstrap/src/main/resources/config/runtime.yml:11-13`이 여전히 "requires the 5 instance-coordination beans". 실제 검사는 `distributedLockProvider` 하나(`StartupSafetyValidator.java:18-19,48-57`) |
|
||||
| L-4a sample이 중앙 ArchUnit에서 빠짐 | 해결(바뀜) | `src/app-bootstrap/build.gradle:192` `architectureTestRuntimeOnly project(':sample-portfolio')`. `..application..`·`..domain..` 패턴 규칙이 sample 패키지에도 걸린다(`ApplicationBoundaryArchitectureTest.java:55-59`) |
|
||||
| L-4b 없는 ArchUnit 규칙 인용 | 남음 | `src/sample-portfolio/CLAUDE.md:43`, `src/app-bootstrap/README.md:478`, `src/domain-core/README.md:27`. 규칙 정의 0건 |
|
||||
| L-7b `ActuatorSecurityHttpTest`가 도달 불가 200 단언 | 해결 | `ActuatorSecurityHttpTest.java:95-97`이 이제 `loggers`가 404임을 단언 |
|
||||
| L-10f build.gradle 고아 주석 | 남음 | `src/app-bootstrap/build.gradle:280-281` "Kafka producer ownership…" 주석이 `jakarta.ws.rs-api` 줄 위에 있음 |
|
||||
| L-11a `ca-skeleton.rate-limit.*` | 해결 | `application-test.yml`·sample `application.yml`에 `ca-skeleton.` 키 0건. sample은 `app.rate-limit`(`sample-portfolio/.../application.yml:189`) |
|
||||
| L-11b test yml `api-base-path: ""` + `/api/healthcheck` | 남음 | `src/app-bootstrap/src/test/resources/application-test.yml:112,118` |
|
||||
| L-11c 참조 없는 `broken-readme.md` | 남음 | `src/app-bootstrap/src/test/resources/developer-experience/broken-readme.md` 존재 |
|
||||
| S6-#2d 멱등성 provider 기본값 | 해결(유지) | `composition/idempotency/.../module-defaults/idempotency.yml:12` `disabled`, `IdempotencySettings.java` `Provider.DISABLED` |
|
||||
| S6-#4 root 넓은 scan | 해결(유지) | `CaSkeletonApplication.java:19-26` 자기 패키지 scan + bootstrap 4개 패키지 properties scan |
|
||||
| S6-#7 sample이 bootstrap 인프라 복사 | 해결(유지) | sample이 `composition:service-runtime`·`composition:idempotency`를 `runtimeOnly`로 받음(`sample-portfolio/build.gradle` dependencies) |
|
||||
| S6-#9 sample yml의 읽는 코드 없는 블록 | 남음(범위 커짐) | `app.capabilities.cache`(`application.yml:150-177`), `app.bootstrap`(`:180-181`), `app.logging`(`:209-225`) 그대로. 추가로 sample이 `WebSecurityAutoConfiguration`을 제외해서 `app.security`·`app.authz`·`app.cors`(`:194-208`)도 읽히지 않는다(07-03) |
|
||||
| S6-#10e sample CLAUDE.md 경로 | 남음 | `src/sample-portfolio/CLAUDE.md:20-23` `adapter/web`, `adapter/persistence`, `adapter/identifier`(실제는 `adapter/inbound/web`, `adapter/outbound/persistence`, `adapter/outbound/identifier`) |
|
||||
| S6-#15 bootstrap `:test`의 저장소 governance 테스트 | 남음 | `app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/` 45파일 6,991줄. Wave 4 P33에 배정됨 |
|
||||
| S6-#16a 이력·리뷰 ID 주석 | 남음 | bootstrap·composition main에서 `BOOT-n`/`Dn`/`DRIFT-` 류 35줄 |
|
||||
| S6-#16d config yml 같은 3줄 헤더 | 남음 | `config/{server,observability,runtime,security}.yml` 4개가 같은 3줄 |
|
||||
| S6-#17 `TracingSettings.sampleRate`가 String | 남음(이동) | `composition/service-runtime/.../TracingSettings.java:13,56-63`, `TracingSampleRateResolver.java:18-29`, `TracingSamplingEnvironmentPostProcessor.java:30`에서 세 번 파싱 |
|
||||
| BOOT-005 startup 순서 | 해결(유지) | `StartupOrder` 상수, `RuntimeEnvironmentProfileValidator.java:90-92`, `TracingSamplingEnvironmentPostProcessor.getOrder()` |
|
||||
| BOOT-017 bootstrap이 어댑터 구현 소유 | 해결 | bootstrap main에 포트 구현 없음. 단 `DurableOperationConfig`가 유스케이스를 조립한다(07-08) |
|
||||
|
||||
지난 리뷰에서 남은 High/P1은 이 영역에 없다. 위 `남음`은 전부 W4·W5(테스트 규칙·문서)다.
|
||||
|
||||
## 3. 새 발견
|
||||
|
||||
### 07-01 트레이스가 어디로도 나가지 않는다 — OTLP endpoint를 설정해도 span을 만들지도 보내지도 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 7, 8, 5, 16, 19 |
|
||||
| 근거 | `composition/service-runtime/.../tracing/TracingConfig.java:66-91` — 자체 `Tracer` bean이 `SdkTracerProvider.builder().setSampler(...).build()`로 만든다. span processor·exporter를 붙이는 줄이 없다. `TracingSettings.Exporter.isConfigured()`(`TracingSettings.java:35`)는 호출하는 곳이 없다. `app-bootstrap/gradle.lockfile`의 runtime classpath에 Boot의 tracing 자동 설정 모듈(`spring-boot-micrometer-tracing*`, `spring-boot-opentelemetry`)이 없다. 그래서 `TracingSamplingEnvironmentPostProcessor`가 넣는 `management.tracing.sampling.probability`(`:30-38`)를 읽는 코드도 없다. 문서는 반대로 말한다: `composition/service-runtime/README.md:72-75` "엔드포인트를 설정하면 export 가 시작된다", `config/observability.yml:153-158` |
|
||||
| 실행 결과 (E3) | 기본 조합을 `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318`로 띄움 → Tracer bean은 `micrometerTracer` 하나, `SpanExporter` 0개, `SpanProcessor` 0개, `ObservationHandler`는 `defaultMeterObservationHandler` 하나(트레이싱 핸들러 없음). 즉 HTTP 요청 observation이 span을 만들지 않는다 |
|
||||
| 발생 조건 | 항상. 운영자가 OTLP collector 주소를 넣는 순간 문제가 드러나야 하지만 아무 오류도 경고도 없다 |
|
||||
| 영향 | "트레이스 기본 제공" 주장이 거짓이다. 로그의 `trace_id`는 web filter가 만든 W3C 값(`WebMvcRequestIdFilter.java:108-118`)이라 로그 상관은 된다. 그러나 서비스 간 span 트리, 지연 분해, 오류 span(`SpanErrorRecorder`)은 없다. 파생 서비스가 그대로 복제한다 |
|
||||
| 심각도·우선순위 | High / P1. 관측성은 이 템플릿이 기본 조합에 넣었다고 선언한 기능이다. 설정 옵션이 동작하지 않는데 조용하다(AGENTS.md capability 기준 3 "동작하지 않는 옵션은 설정 키 자체를 두지 않는다" 위반) |
|
||||
| 확실성 | 직접 확인: 빈 목록, lockfile. 추론: Boot 4의 tracing 자동 설정 모듈을 넣으면 `micrometerTracer`의 `@ConditionalOnMissingBean`과 순서 경쟁이 생길 수 있다 — 수정 때 확인할 것 |
|
||||
| 통제 수준 | M1(문서만 있음). 테스트 `TracingActivationContextTest`는 bean 존재만 본다 |
|
||||
| 결정의 근거 | 설계 선택 포함. 기록된 의도: "Plan A — seam activated"(`observability.yml:154`). 현재 효과: seam만 있고 출력이 없다 |
|
||||
| 최소 개선 방향 | 고른 방법: 자체 `Tracer` 조립을 지우고 Boot 4의 tracing 모듈(`spring-boot-micrometer-tracing-opentelemetry` 계열 starter)과 OTLP export 설정 키 하나로 바꾼다. `app.tracing.sample-rate`의 profile 기본값(prod 0.01)은 EPP로 Boot 키에 넣는 현재 방식을 유지한다. 버린 대안 1: 자체 `SdkTracerProvider`에 `BatchSpanProcessor`+`OtlpHttpSpanExporter`를 직접 붙인다 — observation→span 연결(`TracingObservationHandler`, propagator)까지 손으로 만들어야 해서 Boot가 이미 주는 것을 다시 짠다. 버린 대안 2: tracing 의존성과 설정을 지우고 "로그 상관만 제공"으로 범위를 줄인다 — 가능하지만 owner가 관측 기본 제공을 정했으므로 소유자 결정이 필요하다 |
|
||||
| 단순화의 보존 조건 | `app.tracing.enabled=false`면 Tracer 없음. `SpanErrorRecorder`는 Tracer가 없어도 NOOP bean으로 남음. prod 기본 sample rate 0.01, 그 밖 1.0. 응답 `meta.traceId`와 로그 `trace_id`가 같은 값 |
|
||||
| 완료 기준 | endpoint를 넣으면 span exporter bean이 생기고, 넣지 않으면 exporter가 없거나 비활성이다. HTTP 요청 하나가 span 하나를 만든다 |
|
||||
| 검증 방법 | systemTest에 in-memory span exporter를 주입해 HTTP 요청 1건 → span 1건, `trace_id`가 응답 meta·MDC와 같음을 단언 |
|
||||
|
||||
### 07-02 prod 기동 검사가 DB 연결과 Flyway 마이그레이션이 끝난 뒤에 돈다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(실측은 미실행) |
|
||||
| 관련 관점 | 6, 15, 11, 5, 21 |
|
||||
| 근거 | 모든 `StartupRule`은 `StartupRuleRunner.afterSingletonsInstantiated()`(`adapter/outbound/support/.../startup/StartupRuleRunner.java:35`)에서 한 번에 돈다. 이 콜백은 모든 싱글턴이 만들어진 뒤에 불린다. JPA 모듈을 켜면 그 전에 이미 (a) `FlywayMigrationInitializer`가 `MigrationStartupRunner.migrate()`로 마이그레이션을 실행하고, (b) `jpaResolvedDataSourceCheck`(`JpaStartupAutoConfiguration.java:101-107`, `InitializingBean`)가 DB 연결을 연다. 그런데 prod를 지키는 `PostgreSqlTransportSecurityValidator`(sslmode=verify-full), `FlywayProdSafetyValidator`(baseline-on-migrate·out-of-order·clean), `RequiredEnvironmentValidator`는 모두 `StartupRule`이다. 주석은 반대로 적었다: `JpaStartupAutoConfiguration.java:59` "datasource connection env present **before migration runs**" |
|
||||
| 발생 조건 | JPA 모듈 선택 + prod + 금지 값 하나(예: `sslmode=disable`, `APP_…`로 `spring.flyway.out-of-order=true`) |
|
||||
| 영향 | 기동은 결국 실패한다. 그러나 실패 전에 (1) 평문 연결로 DB 비밀번호가 나간다, (2) out-of-order·baseline 옵션으로 마이그레이션이 이미 적용된다. (2)는 되돌릴 수 없는 스키마 변경이다. 검증기의 존재 이유가 "운영 DB에 위험한 옵션이 닿기 전에 막기"인데 순서가 그 뒤다 |
|
||||
| 심각도·우선순위 | High / P1. prod 안전 검사의 약속 자체가 순서 때문에 깨진다. 기본 조합에는 JPA가 없어서 P0은 아니다 |
|
||||
| 확실성 | 직접 확인: runner 호출 시점(Spring 계약), JPA 쪽 bean 종류. 실측하지 않음: PostgreSQL이 필요해 이 리뷰에서 재현하지 않았다. `lazy-initialization=true`에서도 `SmartInitializingSingleton` 기반 검사는 돈다는 것은 실험으로 확인했다(E3: `lazy-prod-no-salt => FAILED`, `lazy-prod-include-stacktrace => FAILED`). 단 `InitializingBean` 기반 JPA 검사(`jpaPlatformStartupCheck`, `jpaResolvedDataSourceCheck`)는 지연 초기화에서 건너뛸 수 있다 — 05 영역 확인 필요 |
|
||||
| 통제 수준 | M2(검사는 구현돼 있음), 순서는 M0 |
|
||||
| 결정의 근거 | 41절 D2 참조. 단일 runner로 모은 결정은 옳았다. 문제는 실행 시점이 phase 이름(`PROFILE_CHECK`, `ENV_VALIDATION`)과 맞지 않는 것이다 |
|
||||
| 최소 개선 방향 | 고른 방법: 환경만 읽는 rule(`violations(Environment)`만 쓰는 것 — 현재 전부 해당)은 `EnvironmentPostProcessor`나 `BeanFactoryPostProcessor` 단계에서 돌리는 두 번째 진입점을 support에 둔다. rule 인터페이스와 종료 코드는 그대로 둔다. 버린 대안 1: Flyway 전략(`MigrationStartupRunner`) 안에서 rule을 먼저 부른다 — JPA만 고치고 다른 모듈의 같은 문제를 남긴다. 버린 대안 2: DataSource bean에 `@DependsOn("startupRuleRunner")` — 그래도 runner 자체가 `afterSingletonsInstantiated`라 효과가 없다 |
|
||||
| 단순화의 보존 조건 | 위반 시 같은 종료 코드(71/72/78), 같은 `startup.phase`·`error.code` 로그 필드, 한 rule의 위반을 한 번에 보고 |
|
||||
| 완료 기준 | prod + `sslmode=disable`에서 DataSource가 연결을 열기 전에 기동이 실패한다 |
|
||||
| 검증 방법 | JPA systemTest에 연결 시도를 세는 DataSource 프록시를 두고, 금지 값에서 연결 횟수 0 + 종료 코드 71을 단언 |
|
||||
|
||||
### 07-03 실행 중인 샘플에서는 `@RequiresPermission`이 아무 일도 하지 않는다 — 익명 삭제 가능, 생성은 500
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(정적 확인) |
|
||||
| 관련 관점 | 15, 5, 20, 21, 10 |
|
||||
| 근거 | `SamplePortfolioApplication.java:31` `@EnableAutoConfiguration(exclude = WebSecurityAutoConfiguration.class)`. 제외한 클래스가 `MethodSecurityConfig`·`AuthorizationAdapter`·`RolePermissionRegistry`를 들여오는 유일한 곳이다(`adapter/inbound/web/.../WebSecurityAutoConfiguration.java:41-49`). 그 대신 들어오는 `SamplePublicAccessSecurityConfig.java:21-26`은 `/**` 전체 permitAll이고 인증 수단이 없다. 그런데 유스케이스는 권한을 선언한다: `DeleteWorkLogUseCase.java:14` `@RequiresPermission("worklog:close")`(주석 "admin-tier"), `CreateWorkLogUseCase.java:23` `worklog:write`. 컨트롤러는 인증 주체가 없으면 owner를 `null`로 넘기고(`WorkLogController.java:221-229`) 도메인은 `Objects.requireNonNull`로 거부한다(`WorkLogOwner.java`) — NPE라 `GlobalExceptionHandler`의 `Exception` 처리(500)로 간다. 권한 E2E 테스트는 보안 필터와 자동 설정을 끄고 advisor를 직접 넣는다(`WorkLogAuthorizationE2ETest`), 그래서 실행본의 상태를 보지 못한다 |
|
||||
| 발생 조건 | `:sample-portfolio:bootRun` 또는 sample 이미지로 띄운 앱 |
|
||||
| 영향 | 누구나 `DELETE /api/worklogs/{id}`로 아무 기록이나 지운다. 생성은 항상 500이다. README의 curl 예시(`sample-portfolio/README.md:33-58`)는 경로(`/work-logs`)도 틀렸다. 더 큰 문제는 복제 범위다. 샘플은 adopter가 가장 먼저 베끼는 코드이고, 여기서 "보안 자동 설정 하나 제외"가 메서드 보안 전체를 조용히 끈다는 사실이 어디에도 드러나지 않는다. `@RequiresPermission`이 붙은 bean이 있는데 advisor가 없으면 실패하는 장치도 없다 |
|
||||
| 심각도·우선순위 | High / P1. 데모라 데이터 가치는 낮지만, 인가 위치(유스케이스)라는 핵심 규칙이 예시에서 무력화되고 복제된다(35.2 "샘플을 통해 복제되는 범위") |
|
||||
| 확실성 | 정적 경로는 끝까지 확인했다. HTTP로 실제 삭제를 재현하지는 않았다(PostgreSQL 필요) |
|
||||
| 통제 수준 | M0(실행본에서). 단위 계층은 M3 |
|
||||
| 결정의 근거 | 기록된 의도: "IdP 없이 둘러볼 수 있는 공개 데모"(`sample-portfolio/README.md:410-412`). 의도는 URL 공개였지 권한 검사 제거가 아니었다고 읽힌다 — README도 "JWT 필터 체인·메서드 보안·권한 port만 뺀다"고 적어 메서드 보안 제거를 인정하면서 유스케이스 주석은 admin 전용이라고 말한다 |
|
||||
| 최소 개선 방향 | 고른 방법: `WebSecurityAutoConfiguration`을 제외하지 않고, 샘플은 JWT 대신 고정 데모 주체(예: `X-Demo-Role` 헤더나 local 전용 dev 토큰)를 넣는 인증 필터 하나만 둔다. 그러면 권한 검사는 production과 같은 경로로 돈다. 버린 대안 1: 지금 구조 유지 + README 경고 — 위험이 코드에 드러나지 않는다는 원칙에 어긋난다. 버린 대안 2: 샘플에서 `@RequiresPermission`을 지운다 — 인가 위치를 보여 주는 예시가 사라진다. 함께 할 것: `@RequiresPermission` bean이 있는데 `requiresPermissionAuthorizationAdvisor`가 없으면 기동 실패하는 rule을 web 모듈에 둔다 |
|
||||
| 완료 기준 | 실행 중인 샘플에서 권한 없는 주체의 DELETE가 403, 권한 있는 주체는 204. 생성은 주체가 있으면 201 |
|
||||
| 검증 방법 | sample `systemTest`(실제 컨텍스트, 보안 자동 설정 포함)에서 위 세 경우를 HTTP로 단언 |
|
||||
|
||||
### 07-04 `Dockerfile.sample`은 빌드되지 않는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 18, 20, 10 |
|
||||
| 근거 | `src/Dockerfile.sample:50-53`은 `gradlew`, `gradle/`, `config/`, `settings.gradle build.gradle **/build.gradle **/gradle.lockfile`만 복사한다. `src/Dockerfile:46,53`이 따로 복사하는 `gradle.properties`와 `build-logic/` 전체가 없다. `settings.gradle:1-6`은 `includeBuild('build-logic')`로 convention plugin을 가져오므로 build-logic의 `settings.gradle`(version catalog)과 `src/main/groovy` 플러그인이 없으면 settings 단계에서 실패한다. main Dockerfile 주석(`:49-52`)이 같은 실패를 이미 설명하고 고쳤는데 sample은 따라가지 않았다. 이 파일을 빌드하는 CI lane도 없다(`git grep Dockerfile.sample` → 문서·계획서만) |
|
||||
| 실행 결과 (E3) | 두 COPY 집합을 그대로 재현한 디렉터리에서 `./gradlew help --offline`. sample 집합: rc=1, `settings.gradle line 9 … A problem occurred evaluating project ':build-logic' … unknown property 'libs'`. main 집합(+`build-logic/`, `gradle.properties`): rc=0. 실제 `docker build`는 하지 않았다 |
|
||||
| 발생 조건 | 문서대로 `docker build -f src/Dockerfile.sample src/`(`Dockerfile.sample:12`) |
|
||||
| 영향 | 샘플 이미지를 만들 수 없다. 07-03의 문제를 이미지로 배포하는 경로는 지금은 막혀 있지만, 고치면 그대로 드러난다 |
|
||||
| 심각도·우선순위 | Medium / P2. 운영 이미지가 아니라 데모 이미지다 |
|
||||
| 통제 수준 | M0(검증 lane 없음) |
|
||||
| 결정의 근거 | 적용 제외 — main Dockerfile이 이미 정답을 갖고 있어 선택 비교가 필요 없다 |
|
||||
| 최소 개선 방향 | builder 단계를 main과 같게 맞춘다. 더 나은 방법: 두 Dockerfile의 builder 단계를 하나로 두고 `ARG` 하나로 `:app-bootstrap`/`:sample-portfolio`를 고른다(main이 이미 `COMPOSITION` 인자로 같은 일을 함). 갈라진 복사본을 없애는 쪽이 원칙에 맞다 |
|
||||
| 완료 기준 | `docker build -f src/Dockerfile.sample src/` 성공, 이미지 HEALTHCHECK 통과 |
|
||||
| 검증 방법 | 두 Dockerfile을 모두 빌드하는 CI lane(또는 `DeveloperExperienceContractTest`에 builder COPY 집합 동일성 단언) |
|
||||
|
||||
### 07-05 prod에서 JWT audience를 비워도 기동하고, 경고도 없이 audience 검사를 끈다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 15, 19, 6 |
|
||||
| 근거 | `.env.example:97` `APP_SECURITY_JWT_AUDIENCE=`(빈 값). `SecuritySettings.java:35-41`은 값이 `null`일 때만 경고하고, 빈 문자열이면 경고 없이 `""`로 둔다. `JwtDecoderConfig.java:80-82`는 audience가 비면 검사기를 붙이지 않는다. prod secret guard(`SecretSourceValidator.REQUIRED_PROD_SECRETS`, `:34-35`)와 그 밖의 prod rule 어디에도 audience가 없다. `.env.example:12-15`는 "issuer와 audience는 기본값이 없다 — 아무도 고르지 않은 대상을 막기 위해"라고 말한다 |
|
||||
| 실행 결과 (E3) | prod + 빈 audience(두 경로 모두 빈 값)로 기본 조합 기동 → `BOOTED` |
|
||||
| 발생 조건 | `.env.example`을 복사하고 audience를 채우지 않은 prod 배포 |
|
||||
| 영향 | 같은 IdP realm에서 다른 클라이언트용으로 발급된 토큰을 이 API가 받는다(토큰 혼용). 문서의 약속과 반대로 동작한다 |
|
||||
| 심각도·우선순위 | Medium / P2. issuer 검사는 남아 있어 외부 토큰은 막힌다. 피해 범위가 같은 IdP의 다른 client로 제한된다 |
|
||||
| 통제 수준 | M0(prod 강제 없음) |
|
||||
| 결정의 근거 | 설계 선택 포함. 기록된 의도는 "blank disables the check"(`application.yml:45`)로, 로컬 편의 때문이다 |
|
||||
| 최소 개선 방향 | 고른 방법: prod에서 JWT 모드면 audience 필수인 `StartupRule`을 web 모듈에 둔다(local·dev는 지금처럼 허용, 대신 빈 값도 경고). 버린 대안: 모든 profile에서 필수 — 로컬 IdP 없이 띄우는 흐름을 깨고, 이 템플릿의 local 경험을 바꾼다 |
|
||||
| 완료 기준 | prod + JWT + 빈 audience → 기동 실패(ENV_VALIDATION). local은 경고 1줄 |
|
||||
| 검증 방법 | `DefaultCompositionBootTest`에 prod 빈 audience 거부 케이스 추가 |
|
||||
|
||||
### 07-06 로그 설정이 두 군데에서 읽힌다 — `LoggingSettings`는 아무도 쓰지 않고, logback은 env 키를 직접 읽는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 19, 5, 8, 22 |
|
||||
| 근거 | `bootstrap/settings/LoggingSettings.java`는 `app.logging.*`를 바인딩하고 잘못된 값을 "경고 후 기본값"으로 고친다(예: 빈 경로 → `logs/app.json`, `:20-23`). main 코드에 이 record를 쓰는 곳이 없다(사용처는 `LoggingSettingsTest`뿐). 실제 로깅을 정하는 `logback-spring.xml:17-46`은 `springProperty source="APP_LOG_FILE_ENABLED"` 같은 env 키 이름을 직접 읽는다. 그래서 (1) `app.logging.*`를 yml이나 profile 파일로 바꾸면 반영되지 않고, (2) `LoggingSettings`의 경고는 실제로 적용되지 않는 대체값을 알린다(경로 대체값 `logs/app.json` vs logback 기본 `logs/ca-skeleton.json`) |
|
||||
| 실행 결과 (E3) | `--app.logging.file.enabled=true --app.logging.file.path=…`로 기동 → root appender `[ASYNC_CONSOLE]`만. 파일 appender가 붙지 않는다 |
|
||||
| 발생 조건 | 운영자가 env 대신 `application-prod.yml`이나 설정 서버로 `app.logging.*`를 바꿀 때 |
|
||||
| 영향 | 로그 파일·보관 기간이 설정과 다르게 동작한다. 경고 로그가 거짓 정보를 준다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 통제 수준 | M1 |
|
||||
| 결정의 근거 | 설계 선택 포함. logback은 Spring 바인딩보다 먼저 초기화돼 typed settings를 쓸 수 없다는 제약이 있다(`logback-spring.xml:5` 주석) |
|
||||
| 최소 개선 방향 | 고른 방법: `LoggingSettings`를 지우고, logback `springProperty`의 `source`를 `app.logging.*` 키로 바꾼다(`springProperty`는 Spring Environment를 읽으므로 env→yml placeholder 경로가 그대로 산다). 값 검증은 logback이 실패할 값(예: maxHistory<=0)만 `StartupRule` 하나로 fail-fast. 버린 대안: `LoggingSettings`를 유지하고 logback을 런타임에 재구성 — 초기 로그와 이후 로그가 다른 설정을 쓰는 구간이 생긴다 |
|
||||
| 단순화의 보존 조건 | env 키 이름(`APP_LOG_*`)과 기본값, JSON 필드, 마스킹 |
|
||||
| 완료 기준 | `app.logging.file.enabled=true`(yml)로 파일 appender가 붙는다. 같은 값이 한 곳에서만 정의된다 |
|
||||
| 검증 방법 | 위 실험을 systemTest로 고정 |
|
||||
|
||||
### 07-07 종료 시간 예산표에 async executor 대기 19초가 빠져 있다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 7, 18, 12, 9 |
|
||||
| 근거 | 루트 `docker-compose.yml:9-19,88-89`의 예산: 앱 30s(`timeout-per-shutdown-phase`) + preStop 5s + 여유 5s = `stop_grace_period: 40s`. 그런데 `AsyncExecutorConfig.java:27-28,53-54`는 `setWaitForTasksToCompleteOnShutdown(true)` + `awaitTermination 19s`이고 주석은 "container app-shutdown budget (20s)"라고 적는다. Spring은 lifecycle 단계(웹 서버 graceful 30s까지)를 끝낸 뒤 bean destroy에서 executor 대기를 한다. 최악은 30 + 19 = 49s로 40s를 넘는다 |
|
||||
| 발생 조건 | 종료 시점에 HTTP 요청 처리가 길고, 동시에 async 작업이 큐에 남아 있을 때 |
|
||||
| 영향 | 컨테이너가 SIGKILL로 끝나 async 작업이 중간에 끊긴다. 종료 로그가 남지 않는다 |
|
||||
| 심각도·우선순위 | Medium / P2. 최악 경로에서만 일어난다 |
|
||||
| 확실성 | lifecycle → destroy 순서는 Spring 계약으로 판단했다. 최악 시간은 측정하지 않았다. `AsyncGracefulShutdownBehaviorTest`(2 test, 통과)는 executor만 따로 본다 |
|
||||
| 통제 수준 | M1(표는 있음, 표가 틀림) |
|
||||
| 결정의 근거 | 적용 제외 — 숫자 정합성 문제다 |
|
||||
| 최소 개선 방향 | executor 대기를 `spring.lifecycle.timeout-per-shutdown-phase`에서 계산하거나, 예산표에 executor 대기를 넣어 `stop_grace_period`를 다시 잡는다. 숫자는 한 곳(env-keys)에만 두고 compose·주석은 그것을 가리킨다 |
|
||||
| 완료 기준 | 예산표의 합 ≤ `stop_grace_period`, 코드 상수와 주석이 같은 값 |
|
||||
| 검증 방법 | 종료 순서를 기록하는 systemTest(웹 요청 1개 + async 작업 1개를 걸고 close 시간 측정) |
|
||||
|
||||
### 07-08 기본 조립 루트가 아직 선택 capability를 안다 (capability 기준 7 위반)
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 2, 27, 26, 23, 19 |
|
||||
| 근거 | AGENTS.md capability 기준 7: "이 모듈을 아는 곳은 모듈 자신뿐". 현재 bootstrap·이미지·compose에 남은 것: (1) `config/security.yml:39-59` — notification·durable operation·fileserver 권한 매핑. (2) `src/Dockerfile:158-167` — fileserver 저장 경로 `VOLUME` (기본 이미지는 fileserver가 없다). (3) `docker-compose.yml:70-82,110-113` — `fileserver-data` 볼륨을 무조건 마운트. (4) `application-dev.yml:20-22`, `application-prod.yml:22-28` — persistence-jpa 키(`app.persistence.vendor`, `spring.flyway.enabled`)와 이미 삭제된 `JpaSchemaSafetyValidator` 설명(`application-prod.yml:11`). (5) `bootstrap/autoconfigure/operation/DurableOperationConfig.java:37-74` — 유스케이스 조립이 bootstrap에 남음. 소유자 결정 3은 같은 성격(outbox relay·멱등성 executor)을 `composition:*`으로 옮겼다. 그래서 sample은 이 조립을 재사용할 수 없다. (6) build-logic `ConfigContractPlugin.java` `dependsOn(':adapter:outbound:redis-runtime:compileJava')` — env 계약 태스크가 특정 leaf를 안다 |
|
||||
| 발생 조건 | capability를 지우거나 새 capability를 더할 때 |
|
||||
| 영향 | 한 줄 삭제로 기능이 "완전히" 사라지지 않는다. 지운 기능의 권한 문자열·볼륨·설정이 남아, 읽는 사람이 그 기능이 켜져 있다고 오해한다. 새 capability 작성자는 bootstrap 파일을 고쳐야 하는지 판단해야 한다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 통제 수준 | M1. `DefaultCompositionBootTest`는 bean만 보고 설정·이미지 자산은 보지 않는다 |
|
||||
| 결정의 근거 | 41절 D1 참조 |
|
||||
| 최소 개선 방향 | 고른 방법: 권한 매핑은 각 capability의 `config/module-defaults/<모듈>.yml`로, durable operation 조립은 `composition:durable-operation`(또는 기존 outbox-relay 모듈)로 옮긴다. fileserver 볼륨은 fileserver README의 "필요한 마운트"로 옮기고 기본 compose에서는 뺀다. 버린 대안: bootstrap에 두고 "선택 시 사용" 주석만 단다 — 기준 7을 문서로 대체하는 것이라 기각 |
|
||||
| 완료 기준 | bootstrap main·기본 compose·기본 Dockerfile에서 capability 이름(`fileserver`, `notification`, `operation`, `persistence`) grep 0건 |
|
||||
| 검증 방법 | 위 grep을 `DefaultCompositionBootTest` 옆 계약 테스트로 고정 |
|
||||
|
||||
### 07-09 새 기능을 만들 때 따라 할 예시가 세 갈래다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(갈라진 복사본) |
|
||||
| 관련 관점 | 3, 4, 23, 20, 25 |
|
||||
| 근거 | (1) `sample-portfolio` — 한 Gradle 모듈 안에 `domain/`·`application/<기능>/`·`adapter/`를 두고 기능별 패키지(P30 결정). (2) `app-bootstrap/src/test/java/dev/caskeleton/onboarding/**` — `DomainFeatureOnboardingContractTest`가 쓰는 예시는 종류별 패키지(`application/usecase`, `application/port`, `application/query`, `application/command`). (3) AGENTS.md "기능 개발 프로토콜" — production 기능은 `domain-core` → `application-core` → `adapter:*` leaf로 여러 Gradle 모듈에 나눠 둔다. 셋이 서로 다른 배치를 가르친다. 또 sample의 posterimage 기능은 application 클래스만 45개라, 가장 단순한 WorkLog 흐름보다 먼저 눈에 띈다 |
|
||||
| 발생 조건 | 처음 기능을 추가하는 개발자·에이전트 |
|
||||
| 영향 | 어느 예시를 베끼느냐에 따라 패키지 규칙이 달라진다. ArchUnit은 `..application..` 같은 넓은 패턴이라 셋 다 통과시키므로, 일관성이 리뷰에만 의존한다 |
|
||||
| 심각도·우선순위 | Medium / P2 |
|
||||
| 통제 수준 | M1 |
|
||||
| 결정의 근거 | 41절 질문은 7절(매뉴얼 재료)과 함께 적었다 |
|
||||
| 최소 개선 방향 | 고른 방법: 패키지 규칙 하나를 정하고(P30이 고른 기능별 배치), onboarding fixture를 같은 배치로 바꾼다. AGENTS.md 프로토콜에 "sample은 한 모듈에 모든 계층을 두지만 실제 기능은 leaf별로 나눈다"는 차이를 한 줄로 적는다. sample README 첫 절을 WorkLog 한 흐름(생성 1건)으로 시작한다. 버린 대안: sample을 leaf 여러 개로 쪼갠다 — 템플릿 삭제 용이성(샘플 한 모듈 삭제)을 잃는다 |
|
||||
| 완료 기준 | 예시 패키지 배치가 하나. ArchUnit에 "application 하위는 기능 패키지" 규칙(선택) |
|
||||
| 검증 방법 | onboarding fixture와 sample에 같은 규칙 적용 |
|
||||
|
||||
### 07-10 설정 오타·죽은 키가 기동에서도 게이트에서도 안 잡히는 곳이 있다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 19, 21, 23 |
|
||||
| 근거 | (1) bootstrap 자기 설정은 `@ConfigurationProperties`(관대한 바인딩, 모르는 키 무시): `AsyncExecutorSettings.java:16-17`, `BootstrapSettings`, `RuntimeSafetySettings`, `SecretSourceSettings`, `AuthenticationModeSettings`. 모듈들은 `StrictSettingsBinder`(모르는 키면 실패)를 쓴다. 그래서 `app.async.executor.core-sise` 같은 오타는 조용히 기본값이 된다. (2) `verifyEnvKeys`는 yml·java만 본다(`ConfigContractPlugin.java` file trees). compose 파일·`logback-spring.xml`은 대상이 아니다. 실제로 `docker-compose.prod-smoke.yml:29` `APP_LOG_JSON_ENABLED`는 어디서도 읽지 않는 키다. (3) sample `application.yml`의 죽은 블록(S6-#9, 07-03) |
|
||||
| 영향 | 운영자가 값을 바꿨다고 믿지만 반영되지 않는다 |
|
||||
| 심각도·우선순위 | Low / P3. 기본값이 안전한 쪽이라 피해가 작다 |
|
||||
| 통제 수준 | 모듈 M3, bootstrap M1 |
|
||||
| 결정의 근거 | 적용 제외에 가깝다 — 기준 4가 이미 strict 바인딩으로 정했다 |
|
||||
| 최소 개선 방향 | bootstrap 설정 record도 `StrictSettingsBinder`로 묶는다(prefix `app.async`, `app.runtime`, `app.bootstrap`, `app.secret-source`). `verifyEnvKeys` 입력에 루트 compose 파일과 `logback-spring.xml`의 `source="APP_*"`를 넣는다 |
|
||||
| 완료 기준 | 오타 키로 기동 실패. compose의 미등록 `APP_*` 키로 `verifyEnvKeys` 실패 |
|
||||
| 검증 방법 | 각각 실패 테스트 1건 |
|
||||
|
||||
### 07-11 주석·문서가 현재 동작과 다르다 (이번에 새로 찾은 것)
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안(문서 결함) |
|
||||
| 관련 관점 | 9, 5, 20 |
|
||||
| 근거 | `application-prod.yml:11` 삭제된 `JpaSchemaSafetyValidator`를 prod 규칙으로 나열. `src/Dockerfile:201-202` "readiness 그룹이 datasource를 포함한다" — 기본 조합의 readiness는 `readinessState`뿐(`config/observability.yml:79-80`), JPA를 켤 때만 `db`가 붙는다. `AsyncExecutorConfig.java:27` "budget (20s)"(07-07). `sample-portfolio/README.md:22-58` 엔드포인트 표·curl이 `/work-logs`, `/work-logs/import` — 실제는 `/worklogs`, `/worklogs:batchCreate`(`WorkLogController.java:89-165`). `SamplePortfolioApplication.java` Javadoc "The one exclusion is the web leaf's security root"는 맞지만 그 결과(메서드 보안 없음)를 말하지 않는다 |
|
||||
| 심각도·우선순위 | Low / P3 |
|
||||
| 결정의 근거 | 적용 제외 — 문서 수정 |
|
||||
| 최소 개선 방향 | 위 줄을 고친다. 샘플 curl은 sample webSystemTest의 실제 요청에서 생성하거나, 테스트가 README 경로를 읽어 대조한다 |
|
||||
| 완료 기준 | 위 위치가 코드와 같다 |
|
||||
| 검증 방법 | 리뷰 + README 경로 대조 테스트(선택) |
|
||||
|
||||
### 07-12 virtual thread를 켠 상태에서 `server.tomcat.threads.max`는 동시 처리 상한이 아니다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 미검증(구조적 위험 후보) |
|
||||
| 관련 관점 | 14, 13, 19 |
|
||||
| 근거 | `application.yml:54-57` virtual thread 기본 켜짐. `config/server.yml:15-17` `threads.max: 200`, `RuntimeNumericBoundsValidator.java:22`가 이 값을 검증한다. Boot는 virtual thread를 켜면 Tomcat 요청 처리에 virtual thread executor를 쓰고, 이때 `threads.max`는 동시 처리 상한으로 작동하지 않는다(Boot 동작, 이번에 실측 안 함). 실제 상한은 `max-connections: 8192` |
|
||||
| 영향 | 운영자가 `threads.max`로 부하를 제한한다고 믿으면, JPA를 켠 서비스에서 수천 요청이 커넥션 풀(기본 10)에서 대기한다 |
|
||||
| 심각도·우선순위 | Low / P3(미검증) |
|
||||
| 최소 개선 방향 | 설정 주석에 "virtual thread가 켜져 있으면 상한은 max-connections와 하위 자원(풀·rate limit)"이라고 적고, 필요하면 동시 요청 제한(semaphore filter)을 선택 항목으로 둔다 |
|
||||
| 검증 방법 | 기본 조합에서 지연 엔드포인트에 300 동시 요청 → 동시 처리 수 측정 |
|
||||
|
||||
### 07-13 기본 compose가 관리 포트 9001을 모든 인터페이스에 연다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안(보안 기본값) |
|
||||
| 관련 관점 | 15, 18 |
|
||||
| 근거 | `docker-compose.yml:52` `"9001:9001"`. 관리 체인은 `health`·`info`·`prometheus`를 인증 없이 허용한다(`ManagementSecurityConfig.java` `permitAll`). `info.env.enabled: true`(`observability.yml:96-97`)라 `info.capabilities.*`와 build revision이 보인다. local override는 DB 포트를 loopback으로만 연다(`docker-compose.local.yml:14-16` 설명)와 대조된다 |
|
||||
| 영향 | compose로 띄운 개발 장비가 LAN에 메트릭·구성 정보를 노출한다. 운영(k8s)과는 무관하다 |
|
||||
| 심각도·우선순위 | Low / P3 |
|
||||
| 최소 개선 방향 | `"127.0.0.1:9001:9001"`. 앱 포트도 같은 원칙을 쓸지 결정 |
|
||||
| 검증 방법 | `docker compose config` 결과 대조(기존 compose 계약 테스트에 추가) |
|
||||
|
||||
### 07-14 프로필 검증기가 main class 이름을 문자열로 비교한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안 |
|
||||
| 관련 관점 | 21, 20 |
|
||||
| 근거 | `RuntimeEnvironmentProfileValidator.java:83-87` `"dev.caskeleton.bootstrap.CaSkeletonApplication".equals(...)`. AGENTS.md 템플릿 재사용 체크리스트 2·3단계가 바로 이 패키지와 클래스 이름을 바꾸라고 한다. 바꾸고 문자열을 놓치면 profile 없는 jar가 기동한다. 다만 `RuntimeEnvironmentProfileValidatorTest`가 class literal로 주입해 검사하므로, 이름만 바꾸면 그 테스트가 실패해 알려 준다(M3) |
|
||||
| 심각도·우선순위 | Low / P3 |
|
||||
| 최소 개선 방향 | `CaSkeletonApplication.class.getName()`을 쓴다. 같은 leaf라 의존 문제가 없다 |
|
||||
| 검증 방법 | 기존 단위 테스트 |
|
||||
|
||||
## 4. 31절 시나리오 추적
|
||||
|
||||
### 4.1 선택 어댑터 제거 — 기본 조합 기동 (적용)
|
||||
|
||||
- 입력 신뢰: 운영자 env. 필수는 `SPRING_PROFILES_ACTIVE`, `APP_NAME`, `APP_SECURITY_JWT_ISSUER`, `APP_SECURITY_JWT_AUDIENCE`(빈 값 허용 — 07-05), prod는 `APP_PRIVACY_PSEUDONYMIZATION_SALT`.
|
||||
- 흐름: `RuntimeEnvironmentProfileValidator`(EPP, profile 정확히 1개) → 모듈 기본값 EPP(support) → 컨텍스트 생성 → `SmartInitializingSingleton` 검사들(`SecretSourceValidator`, `StartupSafetyValidator`, `AuthenticationModeCompositionValidator`, `StartupRuleRunner`) → readiness UP.
|
||||
- 결과(E2): `DefaultCompositionBootTest`가 local·dev·prod에서 capability bean 0개, DataSource·Mongo·Kafka·Redis 연결 bean 0개로 기동함을 단언하고 이번 게이트에서 통과. prod에서 salt 없으면 실패하는 것도 단언. 이번 실험(E3)에서 `lazy-initialization=true`여도 secret·에러상세 검사가 돈다.
|
||||
- 잘못된 조합: `APP_IDEMPOTENCY_PROVIDER=redis`인데 모듈이 없으면 `IdempotencyAutoConfiguration.java:49-62`이 store 수를 세어 기동 실패. `APP_MULTI_INSTANCE_ENABLED=true`인데 lock provider가 없으면 `StartupSafetyValidator`가 종료 코드 72. 이해 가능한 오류로 거부된다.
|
||||
- 남는 것: 기본 조합이 선택 capability의 설정·볼륨·권한 문자열을 갖고 있다(07-08).
|
||||
|
||||
### 4.2 정상 쓰기 요청 — sample `POST /api/worklogs` (적용)
|
||||
|
||||
- 입력 신뢰: 외부 JSON. `@Valid` DTO, unknown field 거부(`spring.jackson…fail-on-unknown-properties: true`).
|
||||
- 인가 위치: 유스케이스 `@RequiresPermission("worklog:write")` — 실행본에서는 advisor가 없어 검사가 없다(07-03).
|
||||
- 규칙 소유: `WorkLog.create`(도메인), owner 필수는 `WorkLogOwner.of`.
|
||||
- 트랜잭션: `CreateWorkLogUseCase.handle` 안의 `tx.inWrite` 하나. 저장과 outbox append가 같은 트랜잭션(이중 쓰기 금지 예시로 적절).
|
||||
- 외부 부작용: 없음(outbox 행만). relay는 sample에서 꺼짐(`application.yml:234-237`).
|
||||
- 성공의 의미: 201 + ETag. 실행본에서는 주체가 없어 owner `null` → NPE → 500(07-03).
|
||||
- 오류 변환: 도메인 예외 → `DomainExceptionHandler`, 그 밖은 `GlobalExceptionHandler`.
|
||||
- 진단: `request_id`·`trace_id` MDC(web filter), JSON 로그(local·dev는 패턴 로그). span 없음(07-01).
|
||||
|
||||
### 4.3 다른 사용자 리소스 접근 — sample `DELETE /api/worklogs/{id}` (적용)
|
||||
|
||||
- 인증 없음 → 메서드 보안 없음 → `DeleteWorkLogUseCase`가 존재만 확인하고 삭제(07-03). 소유자 비교도 없다. 템플릿이 "객체 ID를 바꿔도 거부된다"를 보여 주는 예시는 fileserver(`FileAccessPolicyPort`, 다른 영역)에만 있고 sample에는 없다. 매뉴얼 재료로 7절에 적었다.
|
||||
|
||||
### 4.4 종료·재시작 (적용)
|
||||
|
||||
- 신호: Dockerfile `ENTRYPOINT ["java", …]` exec 형식이라 java가 PID 1로 SIGTERM을 받는다.
|
||||
- 신규 요청 차단: `server.shutdown: graceful`, `timeout-per-shutdown-phase: 30s`. 게이트 로그(mainCheck.log)에 "Graceful shutdown complete"가 찍힌다.
|
||||
- 진행 작업: async executor가 최대 19s 더 기다린다 → 예산표와 어긋남(07-07).
|
||||
- readiness: 종료 중 readiness 전환은 Boot 기본 동작에 맡긴다(별도 확인 안 함).
|
||||
- 메시지 확인: 기본 조합에 메시지 없음 — 적용 제외(10 영역).
|
||||
|
||||
### 4.5 적용 제외
|
||||
|
||||
| 시나리오 | 사유 |
|
||||
| --- | --- |
|
||||
| 중복·동시 요청 | 멱등성 실행 경로는 web·persistence·Redis 영역. 이 영역은 조립만: provider≠disabled면 store가 정확히 1개여야 기동(`IdempotencyAutoConfiguration.java:49-62`) — 충족 |
|
||||
| 외부 응답 지연·유실 | 기본 조합에 외부 호출 없음(08 영역) |
|
||||
| DB 오류·경쟁 | 기본 조합에 DB 없음(05 영역). 단 prod 검사 순서는 07-02 |
|
||||
| 메시지 중복·역순 | 10 영역 |
|
||||
| 신·구 버전 공존 | API·스키마는 02·05 영역 |
|
||||
| 여러 서버의 작업 실행 | 다중 인스턴스 검사는 lock provider 존재만 본다(`StartupSafetyValidator`). 스케줄러 소유권은 05·10 영역 |
|
||||
| 세션·토큰 갱신 경쟁 | 02 영역(redis-session 모드) |
|
||||
| 큰 입력·목록 조회 | 02 영역. sample batch 상한 1000은 `@Size`로 강제(`WorkLogController.java:177-183`) |
|
||||
|
||||
## 5. 41절 설계 선택 검토
|
||||
|
||||
### D1. capability = `runtimeOnly` 한 줄 + 모듈 자체 `AutoConfiguration.imports`, 기본 조합은 web-only
|
||||
|
||||
1. 필요: 파생 서비스가 쓰지 않는 기능(JPA·Redis·Kafka…)의 연결·설정·의존성을 지지 않고 시작해야 한다.
|
||||
2. 지킬 성질: 줄을 지우면 bean·설정·의존성이 함께 사라진다. 기본 조합은 외부 연결 없이 기동한다. 선택한 기능이 덜 설정되면 기동 실패.
|
||||
3. 현재 보장: `app-bootstrap/build.gradle:157-171` 주석 처리된 선택 줄, `DefaultCompositionBootTest`(E2, 이번 게이트 통과), `qualificationBootJar`로 전부 켠 조합을 compose lane에서 검증. 보장하지 않는 것: 설정 파일·이미지·compose의 capability 흔적(07-08), 권한 문자열.
|
||||
4. 대안: (a) 모든 모듈을 `implementation`으로 싣고 `enabled` 스위치로 끄기(이전 방식). (b) Gradle feature variant/플랫폼별 bootJar 여러 개. (c) 현재 방식.
|
||||
5. 득실: (a)는 끄는 것을 잊으면 연결을 시도하고, 의존성 표면이 크다 — 이전 리뷰가 이 이유로 기각. (b)는 조합 수만큼 산출물이 생겨 검증 비용이 커진다. (c)는 한 줄로 고르지만, "모듈만 자기를 안다"를 지키려면 권한·볼륨·profile 파일까지 모듈로 옮겨야 한다.
|
||||
6. 왜 이 선택: 소유자 결정(B안·web-only)과 일치하고 검증이 이미 붙어 있다. 확인한 조건에서 타당하다.
|
||||
7. 다시 볼 조건: 파생 서비스 대부분이 같은 3~4개 capability를 항상 켠다면, "표준 조합" 플랫폼 하나를 두는 편이 싸다.
|
||||
|
||||
### D2. 기동 검증 = `StartupRule` bean + support의 runner 하나 (`afterSingletonsInstantiated`)
|
||||
|
||||
1. 필요: 잘못된 설정을 첫 요청이 아니라 기동에서 막고, 종료 코드·로그 필드를 일정하게 한다.
|
||||
2. 지킬 성질: 위험한 값이 외부 시스템(DB·브로커)에 닿기 전에 거부한다. 위반은 phase별 종료 코드로 보고한다.
|
||||
3. 현재 보장: 규칙 어휘와 보고는 하나로 모였다(`StartupRule`, `StartupValidationContext`). 실행 시점은 모든 싱글턴 생성 뒤라, "닿기 전" 성질은 보장하지 않는다(07-02). bootstrap의 다른 검사(`SecretSourceValidator` 등)도 같은 시점이다.
|
||||
4. 대안: (a) 현재. (b) 환경만 보는 rule을 EPP/BFPP에서 먼저 실행, bean 상태를 보는 rule만 현재 시점. (c) 각 모듈이 자기 연결 bean 생성 직전에 자기 rule을 부른다.
|
||||
5. 득실: (a) 단순하지만 순서 위험. (b) 진입점이 둘이 되지만 rule 인터페이스는 하나, 현재 rule 전부가 `violations(Environment)`라 이동 비용이 작다. (c) 모듈마다 호출 위치를 기억해야 한다 — 숨은 규칙이 늘어난다.
|
||||
6. 판단: (b)가 현재 요구에 맞다. (a)를 유지하려면 "PROFILE_CHECK"라는 이름이 약속하는 시점을 문서로 낮춰야 하는데, 그건 위험을 숨기는 쪽이다.
|
||||
7. 다시 볼 조건: bean 상태가 필요한 rule이 다수가 되면 두 단계 구분을 phase 속성으로 표현한다.
|
||||
|
||||
### D3. 공용 런타임 배선을 `composition:service-runtime`으로 분리하고, sample은 bean 이름으로 actuator chain을 바꾼다
|
||||
|
||||
1. 필요: bootstrap과 sample이 같은 tracing·metrics·가명화·actuator 보안을 쓰되 복사하지 않는다(S6-#7).
|
||||
2. 지킬 성질: 두 조립 루트가 같은 구현을 쓴다. sample의 공개 정책이 production 기본을 바꾸지 않는다.
|
||||
3. 현재 보장: 두 루트가 `runtimeOnly project(':composition:service-runtime')`. sample은 `actuatorSecurityFilterChain` 이름의 bean으로 공용 chain을 밀어낸다(`ManagementSecurityConfig`의 `@ConditionalOnMissingBean(name=…)`). 보장하지 않는 것: 공용 모듈 안의 tracing이 실제로 동작하는지(07-01) — 분리는 결함도 함께 공유한다.
|
||||
4. 대안: (a) 현재. (b) 공용 배선을 support에 넣기. (c) 각 루트가 복사.
|
||||
5. 득실: (b)는 support가 Spring Boot actuator·security·OTel에 의존하게 돼 모든 capability가 그 무게를 진다. (c)는 이미 갈라진 전례가 있다(S6-#7).
|
||||
6. 판단: (a)가 타당하다. bean 이름으로 대체하는 방식은 문자열 계약이라, 이름이 바뀌면 sample이 조용히 공용 chain과 자기 chain을 둘 다 갖게 된다 — 이름을 상수로 공개하는 정도의 보강이 맞다.
|
||||
7. 다시 볼 조건: 세 번째 조립 루트(예: 배치 전용 앱)가 생기면 web 의존 부분(actuator chain)과 비-web 부분을 나눈다.
|
||||
|
||||
## 6. 리팩토링 후보
|
||||
|
||||
| 대상 | 무엇을 왜 | 보존 조건 |
|
||||
| --- | --- | --- |
|
||||
| `TracingConfig` 자체 Tracer | Boot tracing 모듈로 교체(07-01). 출력 없는 seam 제거 | enabled=false → Tracer 없음, `SpanErrorRecorder` NOOP 대체, prod 0.01 기본 샘플률, `trace_id` 일치 |
|
||||
| `TracingSettings.sampleRate` String | `Double`(nullable)로 바꿔 파싱 1회(S6-#17) | 빈 값 = profile 기본값, [0,1] 밖이면 ENV_VALIDATION 실패 |
|
||||
| `LoggingSettings` + logback env 직접 참조 | 한 출처로(07-06) | `APP_LOG_*` 키 이름·기본값, 마스킹, JSON 필드 |
|
||||
| `StartupRuleRunner` 단일 시점 | 환경 rule은 EPP/BFPP 단계로(07-02) | 종료 코드 71/72/78, `startup.phase`·`error.code` 필드, rule 단위 일괄 보고 |
|
||||
| `DurableOperationConfig` | `composition:*` 모듈로(07-08) | `@ConditionalOnBean` 3종 조건, 유스케이스가 bean이라 메서드 보안 프록시 적용 |
|
||||
| bootstrap `security.yml` 권한 매핑 | 각 capability `module-defaults`로(07-08) | 키(역할명)·값(권한) 그대로, bracket 키 표기 |
|
||||
| `Dockerfile` / `Dockerfile.sample` builder 단계 | 한 파일 + `ARG`(07-04) | 잠금 검증 단계, 레이어 순서, 비루트·읽기전용 루트 |
|
||||
| bootstrap 설정 record 바인딩 | `StrictSettingsBinder`로(07-10) | 현재 기본값과 오류 메시지의 env 키 이름 |
|
||||
|
||||
## 7. 기능 개발 패턴과 판단 지점 (매뉴얼 재료)
|
||||
|
||||
### 템플릿이 주는 틀
|
||||
|
||||
- 조립: capability는 `app-bootstrap/build.gradle`에서 한 줄. 새 capability는 자기 `AutoConfiguration.imports` + `config/module-defaults/<모듈>.yml` + README의 env 키.
|
||||
- 기동 검사: `StartupRule` bean 하나를 모듈에 둔다. 비밀값은 `RequiredProductionSecrets` bean.
|
||||
- 공용 런타임: tracing·metrics·가명화·actuator 보안은 `composition:service-runtime`이 준다. 파생 서비스는 손대지 않는다.
|
||||
- 예시: sample WorkLog(생성·조회·수정·삭제·batch, ETag, outbox). onboarding fixture(테스트 안).
|
||||
- 검증: `DefaultCompositionBootTest`(기본 조합), `qualificationBootJar`+compose lane(전부 켠 조합), `verifyEnvKeys`.
|
||||
|
||||
### 빠진 것
|
||||
|
||||
- 실행본에서 인가가 실제로 도는 예시(07-03)와 객체 소유자 검사 예시.
|
||||
- 트레이스가 실제로 나가는 경로(07-01).
|
||||
- 예시 배치 규칙 하나(07-09).
|
||||
- "새 설정 키를 추가할 때 고칠 곳" 목록: settings record, `module-defaults` yml, `docs/registries/env-keys.yaml`, `.env.example`(생성물), 모듈 README. 지금은 `verifyEnvKeys` 실패 메시지로 배운다.
|
||||
|
||||
### 개발자가 여기서 내려야 하는 판단
|
||||
|
||||
1. 이 기능은 production leaf에 둘 것인가, sample에 둘 것인가? (예시는 sample, 실제 기능은 `domain-core`/`application-core`/`adapter:*`.)
|
||||
2. 외부 연결이 필요한가? 필요하면 어떤 capability 줄을 켜는가, 그 capability README의 env 키를 채웠는가?
|
||||
3. 이 설정 값이 틀리면 언제 알아야 하는가? 기동 시점이면 settings record compact constructor 또는 `StartupRule`. prod에서만 금지면 `RuntimeProfileSnapshot.isProduction()` 분기.
|
||||
4. 그 검사가 외부 시스템에 닿기 전에 도는가? (07-02 — 지금은 개발자가 직접 확인해야 한다.)
|
||||
5. 이 유스케이스의 권한은 무엇이고, 객체 소유자 검사가 필요한가? 권한 문자열은 어느 설정 파일(모듈 기본값)에 매핑하는가?
|
||||
6. 응답·로그에 비밀·개인정보가 섞이는가? `user_principal`은 가명화되고, owner 원문은 응답에 넣지 않는다(sample 예시).
|
||||
7. 종료 중에 진행 작업이 끝나야 하는가? async executor 대기와 컨테이너 grace를 같이 본다(07-07).
|
||||
8. 기능을 지우면 무엇이 남는가? 권한 매핑·볼륨·compose 항목까지 모듈 안에 있는가(07-08)?
|
||||
|
||||
## 8. 28개 관점 판정표
|
||||
|
||||
기호: O 충족, P 부분, X 미충족, ? 미검증, - 적용 제외, > 다른 영역
|
||||
|
||||
| 번호 | 관점 | 판정 | 한 줄 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | P | 조립 코드는 작고 명확(main 31파일 1,505줄). 출력 없는 tracing 조립과 소비자 없는 `LoggingSettings`가 남음 |
|
||||
| 2 | 구조적 성숙도 | P | composition 모듈 분리·좁은 scan은 좋음. bootstrap이 capability 권한·볼륨·durable operation 조립을 가짐(07-08) |
|
||||
| 3 | 변경 용이성 | P | capability 추가·삭제는 한 줄. 새 기능 예시가 세 갈래(07-09) |
|
||||
| 4 | 인지 부하 | P | bootstrap `:test` 저장소 계약 테스트 45파일, sample posterimage 45클래스, 이력 주석 35줄 |
|
||||
| 5 | 위험 가시성 | X | 동작 안 하는 OTLP 설정(07-01), 실행본에서 꺼진 인가(07-03), 검사 순서(07-02)가 코드에서 안 보임 |
|
||||
| 6 | 실패 성숙도 | P | profile·secret·에러상세·멱등성 store 수·multi-instance 모두 fail-fast(E2·E3). prod audience 미검사(07-05), 검사 시점(07-02) |
|
||||
| 7 | 운영 성숙도 | P | health/liveness/readiness 분리, graceful shutdown, 관리 포트 분리. 종료 예산 불일치(07-07), 트레이스 없음 |
|
||||
| 8 | 디버깅 가능성 | P | `request_id`·`trace_id`·`user_principal` MDC, JSON 로그, 구조화 startup 실패 로그. 분산 span 없음 |
|
||||
| 9 | 유지보수 성숙도 | P | 주석·README drift 다수(07-11, L-2b, L-4b, S6-#10e) |
|
||||
| 10 | 테스트 성숙도 | P | 기본 조합 기동 테스트가 실제 위험을 잡음(E2). 트레이스 출력·sample 실행본 인가·Dockerfile.sample은 테스트 없음 |
|
||||
| 11 | 데이터 성숙도 | > | 05 영역. 단 prod 검사 순서가 마이그레이션 뒤인 문제는 07-02 |
|
||||
| 12 | 동시성 성숙도 | P | async executor는 큐 상한·거부 정책·MDC 전파가 있음. virtual thread 상한 의미 미검증(07-12) |
|
||||
| 13 | 확장성 | ? | 부하·다중 인스턴스 실측 없음 |
|
||||
| 14 | 성능 성숙도 | P | 기본 조합 기동 약 1.3s/회(`DefaultCompositionBootTest` 4회 5.4s, 부하 ~20), bootstrap `test` 321건 합 10.2s, systemTest 8건 14.2s. 메모리 512m·heap 75%. 부하 측정 없음 |
|
||||
| 15 | 보안 성숙도 | P | prod 에러상세 차단·secret 강제·관리 체인 분리·loggers 비노출. prod 빈 audience(07-05), sample 익명 삭제(07-03), 9001 전체 공개(07-13) |
|
||||
| 16 | 의존성 성숙도 | P | lockfile strict. `opentelemetry-exporter-otlp`가 실려 있으나 쓰이지 않음(07-01) |
|
||||
| 17 | API / Contract 성숙도 | > | 02 영역. sample README 엔드포인트 drift만 07-11 |
|
||||
| 18 | 배포 성숙도 | P | 비루트·읽기전용 루트·레이어 추출·HEALTHCHECK·digest 고정. `Dockerfile.sample` 빌드 불가(07-04) |
|
||||
| 19 | 설정 성숙도 | P | `app.*` 통일, 모듈 strict 바인딩, `verifyEnvKeys` OK(346 키). bootstrap 관대한 바인딩, 로그 설정 이중 출처, compose 미검사(07-06, 07-10) |
|
||||
| 20 | 개발자 경험 | P | 한 줄 선택·`bootRunH2`·`.env.example` 생성. sample 이미지·curl 예시가 동작 안 함 |
|
||||
| 21 | Guardrail 성숙도 | P | ArchUnit에 sample 포함, StartupRule, 방향 게이트. `@RequiresPermission`인데 advisor 없음을 막는 장치 없음 |
|
||||
| 22 | 추상화 성숙도 | O | `StartupRule`·`RequiredProductionSecrets`·`SecretSourceStrategy` 같은 확장점은 소비자가 있거나 의도된 확장점 |
|
||||
| 23 | 일관성 | P | durable operation만 bootstrap 조립, bootstrap만 관대한 바인딩, 예시 배치 세 갈래 |
|
||||
| 24 | 네이밍 / 의미 | P | `*Config`(일반 설정)와 `*AutoConfiguration`(imports 등록)이 섞여 이름으로 등록 방식을 알 수 없음(`DurableOperationConfig`는 imports 등록) |
|
||||
| 25 | 조직 확장성 | ? | 작성자 외 사용자의 기능 추가 증거 없음 |
|
||||
| 26 | Ownership 성숙도 | P | 모듈 README가 env 키를 소유. 권한 매핑·볼륨은 bootstrap이 소유(07-08) |
|
||||
| 27 | 삭제 가능성 | P | capability·sample 삭제 경로는 검증됨. 지운 capability의 설정 흔적이 bootstrap에 남음 |
|
||||
| 28 | 회복 가능성 | - | 기본 조합에 상태 저장소 없음. 마이그레이션 복구는 05 영역 |
|
||||
@@ -0,0 +1,389 @@
|
||||
# 08 빌드 · CI · 테스트 실행 체계 리뷰
|
||||
|
||||
- 영역: `src/build-logic`, `src/settings.gradle`, `src/build.gradle`, `src/gradle`(카탈로그·wrapper), `src/gradle.properties`,
|
||||
`src/config/architecture`, `.github/workflows/*`·`.github/actions/*`, `src/optional-platforms`의 빌드 부분,
|
||||
strict test lane과 보조 test suite, ArchUnit lane, Spotless·Checkstyle·Error Prone·SpotBugs 설정.
|
||||
- 기준 커밋: `main` `01a8a2a70`.
|
||||
- 리뷰 날짜: 2026-11-01.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 | `clean-architecture-backend-template`, Gradle 루트 `src/` |
|
||||
| 커밋·작업 상태 | `01a8a2a70`, 작업 트리 깨끗함. 실험은 scratchpad worktree(`wt-08`)에서만 했다 |
|
||||
| 목적과 지원 실행 구성 | 템플릿. PR 게이트 = `ci-quality-gates.yml`(`:ci :verifyDependencyLocks`, sample, optional-platforms, buf), main 단계 = `integration-main.yml`(`:mainCheck` 외 컨테이너 lane), 태그 = `release.yml` |
|
||||
| 규모·운영 목표 | 합의된 CI 시간 목표 없음. "PR 게이트는 분 단위"라는 주석만 있다(`integration-main.yml` 주석). 아래 시간은 측정값이지 목표 대비 판정이 아니다 |
|
||||
| 읽은 코드·구성 | build-logic main 전부(2,854줄), root `build.gradle`·`settings.gradle`·`gradle.properties`, `libs.versions.toml`, 15개 workflow, setup action, leaf `build.gradle` 중 app-bootstrap·web·persistence-jpa·persistence-mongo·sample-portfolio·httpclient·objectstorage·messaging-kafka, `modules.json`, Checkstyle·SpotBugs 설정, 테스트 소스 1,635개 파일(정규식 표본 조사) |
|
||||
| 실행한 것 | (1) 오케스트레이터 게이트 로그 읽기: `ci` rc=0 434초, `mainCheck` rc=1 162초. (2) worktree에서 `./gradlew ci mainCheck --dry-run`, `./gradlew integrationCheck --dry-run`(둘 다 rc=0, 시작 부하 8.22). (3) build cache 실험(아래 08-02). (4) `StrictTestLanePlugin` 변이 3개 + `StrictTestLaneConventionTest` 실행(부하 7.16, 18초, 18개 중 5개 실패 = 변이 3개 모두 잡힘). (5) ci 실행이 남긴 `build/test-results/**/*.xml` 984개 집계 |
|
||||
| 확인 못 한 것 | GitHub(이 저장소의 원격은 `git.learn.hyeonworks.com`)에서 workflow가 실제로 도는지. Docker Hub에서 MinIO 이미지가 사라진 시점·대체 이미지. SpotBugs 신뢰도 `HIGH` 제한이 실제로 놓치는 결함 수. 컴파일·정적분석 태스크별 시간(로그에 태스크 시간이 없고 프로파일을 돌리지 않았다) |
|
||||
| 이전 리뷰와 비교 | 2026-09-18 techlead `13-build-dependency-ci.md`, 2026-09-25 followup-status 「1차 O Build/CI」 「2차 BUILD · TEST」. 그때의 실행 결과는 증거로 쓰지 않고 현재 코드로 다시 확인했다 |
|
||||
|
||||
### 게이트 결과 요약
|
||||
|
||||
- `ci` rc=0, 434초(잠금 대기 포함). 663 태스크 중 643 실행, 캐시 적중 1(로컬 build cache가 16MB로 거의 비어 있었다). 시작 부하 9.15, 실행 중 20~31까지 올라갔다.
|
||||
- `mainCheck` rc=1, 162초. 실패는 `:adapter:outbound:objectstorage:objectStorageMinioContractTest`·`objectStorageMinioFaultTest` 두 lane이다. 원인은 `ContainerFetchException` — `minio/minio@sha256:4c4a48…`를 Docker Hub에서 받을 수 없다(오케스트레이터 확인: `alpine:3`은 받아지고 `minio/minio:latest`도 거부됨). 코드 결함이 아니라 고정한 외부 이미지 공급원이 사라진 것이다. 이미지 자체는 05 영역이 다루고, 이 문서는 게이트 반응만 본다(08-04).
|
||||
- 경고: 두 로그 모두 `--warning-mode=fail`에서 경고 없음. ci에서 건너뛴 테스트 8개는 모두 의도된 skip(`OptionalAdapterConditionalExecutionContractTest` 4, `NfsAmbiguityIntegrationTest` 3, `ProviderSandboxSmokeTest` 1).
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| O-3d (ignored-source 검사 테스트 0개) | 해결 | `src/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesFunctionalTest.java` 존재. ci 로그 `verifyNoIgnoredSourcePackages: OK — 4628 Java sources` |
|
||||
| O-5a (의존성 checksum 검증 없음) | 보류(결정 19) | `src/gradle/verification-metadata.xml` 없음. 결정대로 |
|
||||
| O-10a (httpclient sysprop 반복) | 남음 | `src/adapter/outbound/httpclient/build.gradle` 141~222행에 `httpclient.contract.transports`·`httpclient.http3.tests.enabled` 쌍이 6번 반복 |
|
||||
| O-10b (`user.timezone=UTC` 반복) | 남음 | `git grep -c user.timezone -- '*.gradle'` = 11개 파일 28번. `JavaConventionsPlugin`에 없음 |
|
||||
| O-11b (카탈로그 주석이 override 위치를 잘못 적음) | 남음 | `src/gradle/libs.versions.toml:27-31`은 `src/build.gradle`에 이유와 함께 있다고 적는다. 실제는 `src/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java:135-136`이고 이유 문장이 없다 |
|
||||
| O-11c (`netty.version` override가 효과 없음) | 남음 | `JavaConventionsPlugin.java:136` = `4.2.17.Final`. Boot 4.0.8 BOM(`spring-boot-dependencies-4.0.8.pom`)의 `netty.version`도 `4.2.17.Final`. `commons-lang3`는 BOM 3.19.0 → 3.20.0이라 효과 있음 |
|
||||
| O-11d (optional-platforms README 개수) | 해결 | `src/optional-platforms/README.md`에 개수 표기 없음 |
|
||||
| BUILD-바로할것-1b (runtime-membership 잔재 문구) | 바뀜(1곳 추가) | `.github/workflows/ci-quality-gates.yml:56`, `src/sample-portfolio/build.gradle:202`에 남음. 추가로 `src/config/architecture/README.md:12`가 "runtime membership은 build logic이 runtime classpath에서 도출한다"고 적지만 그 플러그인은 삭제됐다 |
|
||||
| BUILD-순수성-이름 | 남음 | `ArchitecturePlugin.java:65` 태스크 이름 `verifyApplicationCoreDependencyPurity`, 클래스 `VerifyApplicationCoreDependencyPurityTask`. 실제 대상은 domain-core·shared-contract·application-* |
|
||||
| BUILD-계획-B4-34 참고(app-bootstrap `check` → systemTest) | 남음 → 08-02로 | `src/app-bootstrap/build.gradle:90-92`. PR `ci`와 `mainCheck` 둘 다 같은 systemTest를 돌린다 |
|
||||
| BUILD-계획-B3 (변경 모듈만 실행) | 보류(결정 30) | 결정대로 전체 실행 |
|
||||
| P13-new-1 (plugin classpath 잠금) | 보류(결정 27) | 결정대로 |
|
||||
| NEW-1b (새 CI 잡이 실제로 돈 증거 없음) | 미검증 | 원격이 GitHub가 아니다(`origin` = `git.learn.hyeonworks.com`). 그 forge의 Actions 실행 기록은 확인하지 못했다 |
|
||||
| NEW-13e (집계에 묶이지 않은 lane) | 바뀜 | sample `posterImageMigrationTest`는 이제 돈다. 하지만 새로 확인한 미실행 lane 14개가 있다 → 08-01 |
|
||||
| TEST-F-1 (fake와 adapter 공유 계약 부족) | 남음 | application-*·domain-core main의 `public interface *Port` 83개. fake와 adapter가 같은 추상 계약을 상속하는 것은 `DurableOperationStoreContract`, `GrpcOperationLedgerContract`, `WorkLogRepositoryContract`, `OutboxLeaseFencingContract`, `DistributedLeaseContract` 등 소수 |
|
||||
| TEST-DisplayName (한국어로, 결정 5) | 남음 | `AGENTS.md:157`은 아직 "영어로 통일". 테스트 소스의 `@DisplayName` 2,444개 중 영어 2,272, 한국어 172. 규칙 문서와 소유자 결정이 서로 다르다 |
|
||||
| TEST-이행-4 (계층별 모범 모듈) | 남음 | 문장 3개 이상 테스트 3,514개 중 `// when`·`// then` 주석을 가진 것 610개(17%). sample-portfolio만 141/141(100%). `adapter/outbound/redis-sdk` 221개 중 0개(정규식 추정) |
|
||||
|
||||
## 3. 새 발견
|
||||
|
||||
### 08-01 — CI가 실행하지 않는 strict lane 14개
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 10, 21, 5, 11, 18 |
|
||||
| 근거 | `ci`·`mainCheck` dry-run 그래프와 15개 workflow의 `./gradlew` 인자를 대조했다. 어느 쪽에도 없는 lane: ① `:adapter:outbound:persistence-jpa`의 readiness lane 11개(`src/adapter/outbound/persistence-jpa/build.gradle:166-183`) — `postgresqlLifecycle`, `SecurityBaseline`, `Migration`, `Transaction`, `Aggregate`, `Query`, `Idempotency`, `FileserverMigration`, `FileserverMetadata`, `FileserverReclamation`, `NotificationSchemaActivation`. 이들은 `integrationCheck`(`src/build.gradle:100`)에만 들어가는데, `integrationCheck`를 실행하는 workflow는 없다(`integration-main.yml:96`은 `--dry-run`으로 저장 가능 여부만 본다). 그중 9개 클래스·57개 테스트에는 다른 lane이 고르는 `@Tag`도 없다. ② `:adapter:inbound:web:performanceTest`, `webJettyPerformanceTest`(`src/adapter/inbound/web/build.gradle:145,152`) — PERFORMANCE 집계는 어디에도 연결되지 않았다. `integration-main.yml:133`의 `web-load-abuse-and-shutdown` 잡은 이름과 달리 `:adapter:inbound:web:test`와 `webJettyCompatTest`만 돌린다. ③ `:sample-portfolio:systemTest`(`src/sample-portfolio/build.gradle:172`) — sample은 `leafPaths`에서 빠져 `systemTestCheck`에 없고, sample `check`(`:199-207`)도 이 lane을 부르지 않는다 |
|
||||
| 발생 조건 | 위 lane이 지키는 코드(JPA 멱등성 저장소, fileserver metadata·reclamation SQL, Flyway 경로, sample 전체 기동, Tomcat·Jetty 부하·종료)를 바꾸는 모든 PR과 main push |
|
||||
| 영향 | 실제 PostgreSQL에서만 드러나는 결함이 PR·main·release 어디서도 잡히지 않는다. `config/jpa/readiness-cards.yaml`은 이 lane들을 근거로 카드 상태를 `selected`·`implemented-candidate`로 적고, `src/build-logic/README.md:47`은 "readiness lanes that require every cited scenario and reject skips"가 삭제된 JPA evidence를 대신한다고 적는다. 둘 다 실행되지 않는 lane에 기대는 주장이다. `JpaReadinessRegistryTest`는 카드가 "존재하는 태스크"를 가리키는지만 보고, 그 태스크가 실행되는지는 보지 않는다 |
|
||||
| 심각도·우선순위 | High · P1. capability 완료 기준 5("실제 벤더로 도는 테스트")의 증거가 이 lane들이다. 같은 종류의 결함(H10, gRPC ledger lane)이 지난 리뷰에서 High였고, 그때 고친 방식(workflow에 이름을 하나씩 적기)이 같은 결함을 다시 만들었다 |
|
||||
| 확실성 | 직접 확인: dry-run 그래프, workflow 문자열, 클래스 태그. 추론: 이 lane이 지금 통과하는지는 모른다(돌리지 않았다) |
|
||||
| 결정의 근거 | 현재 선택은 "integration lane은 workflow가 이름으로 부른다"이다(`integration-main.yml:292` 주석: 카드 소속에 기대지 않고 이름으로 부른다). 이름 목록과 lane 목록이 따로 관리되니, 새 lane을 만들 때 workflow 한 줄을 빠뜨리면 아무도 모른다. `integration-main.yml:292` 주석은 "These six"라고 적지만 실제 단계는 5개다 |
|
||||
| 이해 비용 | lane을 추가하는 사람이 build.gradle·workflow·집계 태스크 세 곳을 알아야 한다. 이 규칙은 어디에도 강제돼 있지 않다 |
|
||||
| 최소 개선 방향 | (a) `integration-main.yml`에 `./gradlew :integrationCheck`(또는 lane별이 꼭 필요하면 `:adapter:outbound:persistence-jpa:integrationTestLaneCheck`) 한 단계를 둔다. (b) PERFORMANCE lane은 실행할 곳을 정하거나 `explicitOnly("이유")`로 바꿔 "부르지 않는다"를 코드에 드러낸다(gRPC `grpcPerformanceTest`처럼 문서로만 적지 않는다). (c) sample `systemTest`를 sample `check` 또는 `sampleWebContractCheck` 옆 main 단계에 연결한다. (d) 재발 방지: build-logic에 "explicitOnly가 아닌 모든 strict lane은 루트의 `ci`·`mainCheck`·`integrationCheck`·`performanceCheck` 중 하나에 도달한다"는 TestKit 테스트, 그리고 workflow가 그 네 집계를 모두 부른다는 테스트 하나 |
|
||||
| 대안 비교 | 현상 유지(이름 나열): 새 lane마다 누락 위험이 같다. 카테고리 집계 실행(제안): workflow는 집계 4개만 알면 된다. 단점은 한 잡이 길어지는 것 — lane별 단계가 필요하면 집계를 쪼개 부르되 "모든 lane이 어떤 집계에 속한다"는 검사로 묶는다. 텍스트 contains 테스트(`DeveloperExperienceContractTest.everyOptionalPlatformIntegrationLaneHasAnExecutingWorkflowCaller`)를 main 빌드에 복제: 주석 안의 문자열에도 통과하고 lane마다 테스트를 써야 해서 기각 |
|
||||
| 단순화의 보존 조건 | lane의 fail-closed 성질(아무것도 안 돌면 실패, `requires`, `rejectSkipped`)은 그대로 둔다. 변이 실험으로 이 장치는 테스트가 잘 지키고 있음을 확인했다 |
|
||||
| 비용·부작용 | main 단계 시간이 PostgreSQL lane 11개만큼 늘어난다(측정 안 함). 컨테이너 lane은 `exclusiveRealServerLane`으로 하나씩 돌기 때문에 합산 시간이 그대로 더해진다 |
|
||||
| 재검토 조건 | integration lane 수가 늘어 main 단계가 30분을 넘으면 집계를 잡 단위로 쪼갠다 |
|
||||
| 완료 기준 | 위 14개 lane이 어떤 workflow 실행 기록에 나온다. 새 lane을 집계 밖에 만들면 build-logic 테스트가 실패한다 |
|
||||
| 검증 방법 | `./gradlew ci mainCheck integrationCheck --dry-run`과 workflow 인자를 대조하는 테스트, 그리고 의도적으로 집계 밖 lane을 하나 만든 TestKit 변이 |
|
||||
|
||||
### 08-02 — strict lane은 build cache도 쓰지 않아서 바뀐 것이 없어도 매번 다시 돈다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(성능), 실험으로 확인 |
|
||||
| 관련 관점 | 14, 20, 9 |
|
||||
| 근거 | `StrictTestLanePlugin.java:221` `test.getOutputs().upToDateWhen(ignored -> false)`. 실험(scratchpad `cc08`, Gradle 9.0.0): `@CacheableTask`에 `upToDateWhen { false }`를 주고 출력을 지운 뒤 다시 실행하면 캐시 항목이 있어도 `executed`. 같은 태스크에서 그 한 줄만 빼면 `FROM-CACHE`. 즉 이 한 줄이 up-to-date 판정뿐 아니라 build cache 적재까지 막는다. ci에서 매번 다시 도는 hermetic lane: `architectureTest` 41초, app-bootstrap `systemTest` 14초, `mongoStableContractTest` 10초, `webSecurityBoundaryTest` 5초, `httpClientStableContractTest` 4초, `httpClientSecurityTest` 약 2초, `spring62ApiSurfaceScan` 1초 미만(테스트 JVM 구간, ci 로그 시점 기준). 합계 약 77초 + JVM 기동 7회. 추가로 app-bootstrap `check`가 `systemTestLaneCheck`에 의존하고(`src/app-bootstrap/build.gradle:90-92`) `mainCheck`의 `qualificationCheck`도 같은 lane을 부른다. main push에는 `ci-quality-gates`와 `integration-main`이 둘 다 돌기 때문에 같은 systemTest가 두 번 돈다(mainCheck 로그에서 20:42에 다시 실행됨, 8개 테스트) |
|
||||
| 발생 조건 | 모든 PR, main push, 로컬 `./gradlew <leaf>:check` 반복 실행 |
|
||||
| 영향 | PR 하나당 약 1~1.5분의 고정 비용. 문서만 고친 PR도 같다. 개발자가 `:adapter:outbound:persistence-mongo:check`를 두 번 연속 실행해도 465개 테스트가 다시 돈다 |
|
||||
| 심각도·우선순위 | Medium · P2. 정확성 문제는 아니지만 모든 PR에 반복되는 비용이고, 이 lane 수가 늘수록 커진다 |
|
||||
| 확실성 | 캐시 동작은 실험으로 확인(E3, 단일 태스크 실험). PR 단위 절감량은 ci 시점 측정값에서 계산한 추정 |
|
||||
| 결정의 근거 | 코드 주석에 이유가 없다. 추정되는 의도는 "lane은 실행됐다는 사실 자체가 증거"라는 것이다. 하지만 캐시된 결과도 그 입력으로 실행해서 `doLast` 검사(아무것도 안 돎·skip·required 누락)를 통과한 결과다. hermetic lane에서는 입력이 같으면 결과가 같다 |
|
||||
| 최소 개선 방향 | 카테고리로 나눈다: `TEST`·`ARCHITECTURE` lane은 `upToDateWhen(false)`를 빼서 캐시를 허용한다. 외부 이미지·네트워크·실제 시간에 기대는 `INTEGRATION`·`SYSTEM`·`PERFORMANCE`는 지금처럼 매번 돈다(이미지 태그가 입력으로 추적되지 않기 때문). app-bootstrap `check`→`systemTestLaneCheck` 연결은 지우거나, 남긴다면 `qualificationCheck`에서 app-bootstrap을 뺀다 |
|
||||
| 대안 비교 | 현상 유지: 단순하지만 고정 비용. 전부 캐시 허용: 컨테이너 lane은 이미지가 바뀌어도 캐시 적중할 수 있어 기각. `cacheIf { category == TEST }` 같은 명시 선언(제안과 같은 효과를 이름으로 드러냄)이 가장 읽기 쉽다 |
|
||||
| 단순화의 보존 조건 | lane이 실제로 실행될 때의 세 검사(0개 실행, skip, required 누락)는 그대로 둔다. `requires` 목록이 바뀌면 캐시 키도 바뀌어야 한다 — 현재 `filter.includeTestsMatching`은 Test 태스크 입력이라 키에 들어간다 |
|
||||
| 비용·부작용 | 캐시된 lane은 로그에 `FROM-CACHE`로만 나와 "이번에 돌았다"는 증거가 없다. release 같은 증거 수집 잡에서는 `--rerun-tasks`로 강제하면 된다 |
|
||||
| 재검토 조건 | build cache를 원격 캐시로 바꾸거나, lane이 외부 상태(파일·환경 변수)를 읽게 되면 그 lane은 캐시 대상에서 다시 뺀다 |
|
||||
| 완료 기준 | 코드 변경 없이 `./gradlew ci`를 두 번 돌리면 두 번째에 hermetic lane이 `FROM-CACHE` 또는 `UP-TO-DATE`. main push에서 app-bootstrap systemTest가 한 번만 돈다 |
|
||||
| 검증 방법 | build-logic TestKit: TEST 카테고리 lane을 두 번 실행해 두 번째 결과가 `UP_TO_DATE`/`FROM_CACHE`인지, INTEGRATION lane은 `SUCCESS`인지 단언 |
|
||||
|
||||
### 08-03 — app-bootstrap의 PR 테스트가 저장소 문서를 읽고, 저장소 전체를 입력으로 잡는다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(규칙 불일치) + 성능 비용 |
|
||||
| 관련 관점 | 23, 21, 14, 20 |
|
||||
| 근거 | `AGENTS.md`("저장소 문서와 대조하는 테스트는 `mainStage()` 레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다")와 `integration-main.yml` 주석("documentation-drift gates … are gone rather than demoted"). 그런데 app-bootstrap `src/test`의 15개 클래스가 저장소 파일을 읽는다(`ca.repository.root`·repository root 탐색). 예: `CapabilityStatusDocumentTest.java:25-35`는 `docs/capability-status.md` 본문에 특정 문자열이 있는지 단언한다. `DeveloperExperienceContractTest.java:280-284`는 `CLAUDE.md`에 `./gradlew :app-bootstrap:architectureTest` 문자열이 있는지 단언한다. 같은 클래스의 다른 테스트들은 workflow YAML 본문을 문자열로 검사한다. 태그가 없어서 PR `test`에서 돈다. 그리고 `src/app-bootstrap/build.gradle:321-334`가 모든 Test 태스크에 `docs/**`, `.github/**`, `infra/**`, `scripts/**`, 저장소의 모든 `*.md`·`**/*.gradle`을 입력으로 선언한다 |
|
||||
| 발생 조건 | `CLAUDE.md`·`docs/` 문구 수정, 어느 leaf든 `build.gradle` 수정, workflow 수정 |
|
||||
| 영향 | 문서 한 줄 수정이 PR 게이트를 실패시킬 수 있다(정책과 반대). 또 저장소의 어떤 문서·빌드 파일을 바꿔도 app-bootstrap `test`(321개, 약 11초), `architectureTest`, `systemTest`, `integrationTest`의 캐시가 모두 무효가 된다. 이 리뷰 문서를 추가하는 것만으로도 무효다 |
|
||||
| 심각도·우선순위 | Medium · P2. 피해는 PR 시간과 소음이지만, 템플릿이 스스로 정한 규칙을 가장 큰 leaf가 어기고 있어 파생 프로젝트가 그대로 복제한다 |
|
||||
| 확실성 | 규칙 위반은 직접 확인. 캐시 무효화는 Gradle 입력 선언에서 정적으로 도출(실행 측정 안 함) |
|
||||
| 결정의 근거 | O-4a 수정(입력 미선언으로 UP-TO-DATE 거짓)에서 온 것이다. 정확성을 위해 입력을 넓혔고, 그 넓은 입력을 문서를 읽지 않는 테스트에까지 적용했다 |
|
||||
| 최소 개선 방향 | 저장소를 읽는 15개 클래스를 `@Tag("document-contract")`(문서 대조) 또는 별도 lane으로 모으고, 그 lane에만 `repositoryContractInputs`를 준다. 문서 본문 문자열을 단언하는 테스트(`CapabilityStatusDocumentTest`, `DeveloperExperienceContractTest`의 CLAUDE.md 단언)는 mainStage로 옮기거나 지운다. workflow 구조 검사(서명 잡의 OIDC 권한 같은 보안 성질)는 YAML 파싱 테스트로 남기되 그 lane의 입력은 `.github/**`만 둔다 |
|
||||
| 대안 비교 | 현상 유지: 정확하지만 PR 소음과 캐시 무효. 입력을 좁히기만: 문서 대조 테스트가 여전히 PR에 남아 규칙 위반은 그대로. 태그로 분리(제안): 규칙과 입력 범위가 같이 맞는다 |
|
||||
| 단순화의 보존 조건 | O-4a의 성질(읽는 파일이 바뀌면 테스트가 다시 돈다)은 분리된 lane에서 유지한다 |
|
||||
| 비용·부작용 | 문서 대조가 main 단계로 가면 PR에서는 못 잡고 merge 후에 잡는다. 이것이 AGENTS.md가 이미 고른 방향이다 |
|
||||
| 재검토 조건 | 특정 문서 대조가 보안·릴리스 계약(예: OIDC 권한)이라 merge 전에 막아야 하면 그 테스트만 PR lane에 두고 이유를 주석에 적는다 |
|
||||
| 완료 기준 | app-bootstrap `src/test`에서 저장소 파일을 읽는 클래스가 모두 태그·lane으로 분리된다. `docs/**`만 바꾼 커밋에서 app-bootstrap `test`가 `UP-TO-DATE`다 |
|
||||
| 검증 방법 | `git grep -l 'ca.repository.root\|repositoryRoot' -- 'src/app-bootstrap/src/test'`가 태그 붙은 클래스만 나오는지, 문서만 바꾼 뒤 `:app-bootstrap:test`의 up-to-date 여부 |
|
||||
|
||||
### 08-04 — 외부 컨테이너 이미지가 사라지면 main 단계가 통째로 멈춘다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(게이트 반응) + 구조적 위험(이미지 관리) |
|
||||
| 관련 관점 | 16, 6, 18, 28, 9 |
|
||||
| 근거 | (1) 이번 mainCheck 실패: MinIO lane 2개가 `ContainerFetchException`(Docker Hub `minio/minio` 저장소를 받을 수 없음)으로 실패. lane은 skip하지 않고 실패했다 — 이건 맞는 반응이다. (2) 하지만 CI의 main 단계는 `./gradlew :mainCheck --warning-mode=fail --stacktrace`(`integration-main.yml:81`)로 `--continue`가 없다. Gradle은 첫 실패 뒤 남은 태스크를 시작하지 않으므로, 외부 이미지 하나가 사라지면 env 계약·public path·전송 lane·문서 대조 lane의 결과가 그날 하나도 나오지 않는다(오케스트레이터는 `--continue`로 돌려서 나머지가 통과함을 확인했다). (3) 이미지 참조가 테스트 소스에 흩어져 있다: MinIO digest가 `MinioManagedObjectContractTest.java:51-52`, `MinioManagedObjectFaultTest.java:37-39`, evidence JSON 2개에 따로 있고, compose(`docker-compose.infra.yml:183`)는 다른 태그를 쓴다. `postgres:16-alpine`은 11곳에 떠 있는 태그(digest 아님)로 있다. httpclient는 build.gradle에서 httpbin digest를 주지만(`src/adapter/outbound/httpclient/build.gradle:219-224`) 테스트 기본값은 `kennethreitz/httpbin:latest`(`FailureInjectionContractTest.java:40`)다. Testcontainers 이미지 치환(`hub.image.name.prefix`·`ImageNameSubstitutor`)이나 미러 설정은 없다. (4) 같은 MinIO lane이 `object-storage-qualification.yml`(PR 경로 필터 + 주간)과 objectstorage `mainCheck`(`src/adapter/outbound/objectstorage/build.gradle:123-124`) 두 곳에서 돈다 |
|
||||
| 발생 조건 | Docker Hub 저장소 삭제·이동, rate limit, 사내 네트워크에서 Docker Hub 차단 |
|
||||
| 영향 | main 단계 신호 전체가 외부 공급원 하나에 묶인다. 이미지를 바꾸려면 Java 소스 여러 곳을 같이 고쳐야 하고, 빠뜨린 곳은 그 lane이 돌 때까지 모른다. 파생 서비스가 사내 레지스트리를 쓰려면 소스를 고쳐야 한다 |
|
||||
| 심각도·우선순위 | Medium · P2. 지금 실제로 main 단계가 빨갛다. 데이터 피해는 없지만 다른 회귀를 가린다 |
|
||||
| 확실성 | 실패와 `--continue` 부재는 직접 확인. "남은 태스크가 시작되지 않는다"는 Gradle 기본 동작이고, 이번 실행이 `--continue`로 돌아 CI와 같은 조건의 재현은 하지 않았다 |
|
||||
| 결정의 근거 | 이미지를 digest로 고정한 것 자체는 좋은 선택이다(httpclient 주석이 이유를 적는다: 빨간 결과가 남의 이미지 push 때문이 아니게). 문제는 고정값을 한 곳에서 관리하지 않는 것과, 공급원이 사라졌을 때의 대응이 없는 것이다 |
|
||||
| 최소 개선 방향 | (a) `integration-main.yml`의 main-check 단계에 `--continue`를 붙여 실패한 lane 이름이 전부 나오게 한다. (b) 테스트용 이미지를 한 파일(예: `src/config/testing/container-images.properties`)에 모으고, 테스트는 시스템 프로퍼티로 받는다. 각 Test 태스크가 그 파일을 입력으로 선언한다. compose·evidence JSON도 같은 값을 쓰거나, 다르면 그 이유를 적는다. (c) Testcontainers `hub.image.name.prefix`를 CI 변수로 받을 수 있게 해 사내 미러로 돌릴 수 있게 한다. (d) MinIO lane 중복은 하나만 남긴다 |
|
||||
| 대안 비교 | 현상 유지: 이미지가 사라질 때마다 소스 여러 곳 수정. 공급원을 GHCR·Quay로 옮기기만: 같은 문제가 다른 공급원에서 반복. 사내 미러 의무화: 템플릿 기본값으로는 과하다 — 선택할 수 있게만 연다 |
|
||||
| 단순화의 보존 조건 | digest 고정과 "받지 못하면 skip이 아니라 실패"는 유지한다 |
|
||||
| 비용·부작용 | 이미지 목록 파일 하나와 읽는 헬퍼 하나가 생긴다. 이미지 갱신 PR이 그 파일 하나만 바꾸면 된다 |
|
||||
| 재검토 조건 | 이미지 수가 5개 이하로 줄거나, 모든 컨테이너 테스트가 한 leaf로 모이면 파일 대신 상수 클래스 하나로 충분하다 |
|
||||
| 완료 기준 | MinIO 이미지를 바꾸는 변경이 파일 1곳만 수정한다. main-check 잡이 실패해도 나머지 main lane 결과가 로그에 남는다 |
|
||||
| 검증 방법 | `git grep -n 'minio/minio'` 결과가 이미지 목록 파일 하나. 존재하지 않는 digest로 바꾼 브랜치에서 main-check가 MinIO 두 lane만 실패로 보고하는지 |
|
||||
|
||||
### 08-05 — registry에 없는 leaf 디렉터리는 조용히 빌드에서 빠진다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 21, 20, 25 |
|
||||
| 근거 | `ModuleRegistrySettingsInstaller.java`는 registry의 모듈만 `include`한다. `VerifyCleanArchitectureDependenciesTask`의 `declaredModules`도 settings가 포함한 프로젝트에서 나오므로, registry에 없는 디렉터리는 비교 대상이 되지 못한다. 현재는 미등록 `build.gradle`이 없다(`git ls-files '*build.gradle'`과 registry `source_path` 대조, build-logic·root·optional-platforms 제외) |
|
||||
| 발생 조건 | 개발자가 새 leaf 디렉터리와 `build.gradle`을 만들고 registry 등록을 빠뜨림 |
|
||||
| 영향 | 그 leaf는 컴파일도 테스트도 되지 않는데 `ci`는 초록이다. 직접 `:<path>:test`를 부르면 "project not found"로 드러나지만 `ci`만 보면 모른다 |
|
||||
| 심각도·우선순위 | Low · P3. 발생하면 금방 드러날 가능성이 높고 현재 사례는 없다 |
|
||||
| 결정의 근거 | 적용 제외 — 대안이 사실상 하나인 단순 guard 누락 |
|
||||
| 최소 개선 방향 | settings 플러그인에서 `src/**/build.gradle` 중 registry에도 included build 목록에도 없는 파일이 있으면 실패하거나, `verifyCleanArchitectureDependencies`에 같은 검사를 둔다 |
|
||||
| 완료 기준 | 미등록 `build.gradle`을 하나 만들면 `ci`가 실패한다 |
|
||||
| 검증 방법 | `ModuleRegistryTest` 또는 TestKit에 미등록 디렉터리 사례 추가 |
|
||||
|
||||
### 08-06 — 병렬·캐시 설정이 빌드와 lane 종류에 따라 다르게 적용된다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안(성능) |
|
||||
| 관련 관점 | 14, 23 |
|
||||
| 근거 | (1) `src/optional-platforms/`에 `gradle.properties`가 없다. `-p optional-platforms`로 돌리면 `src/gradle.properties`(parallel, caching, workers.max=4, jvmargs)가 적용되지 않는다. PR의 optional-platforms 잡과 release의 gRPC 잡이 직렬·캐시 없이 돈다. (2) `StrictTestLanePlugin.java:187-199`는 TEST가 아닌 모든 lane에 build 전체에서 1개짜리 `exclusiveRealServerLane`을 건다. 주석은 "서버나 컨테이너를 띄우는 lane"이라고 하지만 `ARCHITECTURE` lane(ArchUnit, 서버 없음)도 포함된다 |
|
||||
| 영향 | optional build 시간 미측정. ArchUnit lane(41초)이 서버 lane과 겹쳐 돌 수 없다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 결정의 근거 | 적용 제외 — 설정 누락·조건 범위 문제 |
|
||||
| 최소 개선 방향 | optional-platforms에 같은 `gradle.properties`를 두거나 `src/gradle.properties`를 가리키는 문장을 README에 적는다. 서비스 제한 조건을 `category != TEST && category != ARCHITECTURE`로 좁힌다 |
|
||||
| 완료 기준 | optional build 로그에 parallel 실행. ArchUnit lane이 다른 lane과 동시에 돌 수 있다 |
|
||||
| 검증 방법 | `-p optional-platforms ci --dry-run`의 `--parallel` 여부, build-logic TestKit |
|
||||
|
||||
### 08-07 — SpotBugs·FindSecBugs가 신뢰도 HIGH만 보고한다
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 미검증(설정 사실은 확인, 영향은 미측정) |
|
||||
| 관련 관점 | 15, 21 |
|
||||
| 근거 | `QualityConventionsPlugin.java` `spotBugs.getReportLevel().set(Confidence.HIGH)`. FindSecBugs의 다수 규칙(SQL·경로 주입 등)은 보통 신뢰도 MEDIUM으로 보고된다. `exclude.xml`에는 `<Match>` 9개 |
|
||||
| 영향 | 보안 정적분석이 돈다는 사실과 실제로 보는 범위가 다르다. 얼마나 놓치는지는 MEDIUM으로 한 번 돌려 봐야 안다 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 결정의 근거 | 코드에 이유가 없다. 오탐을 줄이려는 선택으로 보이지만 기록이 없다 |
|
||||
| 최소 개선 방향 | 한 번 `Confidence.MEDIUM`으로 `qualityCheck`를 돌려 결과 수를 본다. 결과에 따라 MEDIUM + 제외 목록, 또는 HIGH 유지 + 이유 주석 |
|
||||
| 완료 기준 | 설정 옆에 고른 신뢰도와 그 근거(측정한 결과 수)가 적혀 있다 |
|
||||
| 검증 방법 | MEDIUM 실행 결과 수 비교 |
|
||||
|
||||
## 4. 31절 시나리오 추적
|
||||
|
||||
이 영역은 요청을 처리하지 않는다. 그래서 요청 대신 "변경 하나"를 따라갔다.
|
||||
|
||||
### 선택 어댑터 제거·추가 (적용)
|
||||
|
||||
한 서비스가 JPA를 고르고, 다른 서비스가 JPA leaf 자체를 지운다고 가정했다.
|
||||
|
||||
```text
|
||||
app-bootstrap/build.gradle 주석 해제(runtimeOnly persistence-jpa)
|
||||
-> strict lock 불일치 -> resolveAndLockAll --write-locks (주석이 안내)
|
||||
-> modules.json app-bootstrap.allowed_dependencies에 이미 있음 -> 방향 게이트 통과
|
||||
-> systemTest가 main runtime graph로 기동 -> JPA가 켜진 기동을 검증
|
||||
```
|
||||
|
||||
| 항목 | 결과 |
|
||||
| --- | --- |
|
||||
| 입력의 신뢰 수준 | 개발자가 고친 build 파일. 잘못 고치면 strict lock과 방향 게이트가 막는다(M3) |
|
||||
| 권한 판단 위치 | `modules.json` `allowed_dependencies`가 유일한 허용 목록. app-bootstrap은 capability 11개를 모두 미리 허용한다 |
|
||||
| 규칙 소유 | registry(edge), `capabilityProjects` 목록(`app-bootstrap/build.gradle` 134~146행, ArchUnit 입력과 qualification jar), 주석 처리된 `runtimeOnly` 줄. capability 목록이 이 두 곳과 registry 세 곳에 있다 |
|
||||
| 성공의 의미 | `ci` 초록 = 컴파일·단위·ArchUnit·systemTest(현재 조립). 고른 capability의 실제 벤더 lane은 PR에 없고, JPA readiness lane은 어디서도 돌지 않는다(08-01) |
|
||||
| 오류 변환 | lock 불일치, 금지 edge 모두 Gradle 오류로 위치와 함께 나온다 |
|
||||
| 제거(leaf 자체 삭제) | 선택 해제는 한 줄이지만 leaf 삭제는 아니다. app-bootstrap `build.gradle`에 `persistence-jpa`가 9번(`testImplementation`, `integrationTestImplementation`, testFixtures, `capabilityProjects`, `bootRunH2Classpath` 등) 나오고, app-bootstrap 테스트 7개 파일이 persistence 타입을 import한다. 파생 프로젝트가 JPA leaf를 지우려면 이 테스트들도 정리해야 한다. AGENTS.md 기준 7("한 줄을 지우면 기능이 완전히 사라진다")은 선택 해제에 대한 말이고, leaf 삭제 비용은 문서에 없다 |
|
||||
|
||||
### 적용 제외
|
||||
|
||||
정상 쓰기, 중복·동시 요청, 외부 응답 지연, DB 오류, 메시지 중복, 세션·토큰, 다른 사용자 리소스, 큰 입력, 종료·재시작: 빌드·CI 영역에는 요청 경로가 없다. 각 영역 리뷰가 다룬다. "신·구 버전 공존"은 gRPC buf breaking 검사(`ci-quality-gates.yml` `grpc-proto-buf`)만 이 영역에 있고, 확인했다(PR·push에서 baseline 대비 `buf breaking`).
|
||||
|
||||
## 5. 41절 설계 선택 검토
|
||||
|
||||
### 5.1 integration lane을 workflow가 이름으로 부르는 방식
|
||||
|
||||
1. 필요한 것: 컨테이너가 필요한 lane은 PR이 아니라 main 단계에서 실패가 보이게 돌아야 한다.
|
||||
2. 지킬 성질: 선언한 strict lane은 어딘가에서 반드시 실행된다.
|
||||
3. 현재 보장: 없다. lane 자체는 "실행되면 fail-closed"를 잘 지킨다(변이 3개 모두 테스트가 잡음). 하지만 "실행되는가"는 workflow 문자열에 달려 있고, 검사는 optional build 하나에 대한 문자열 contains 테스트뿐이다.
|
||||
4. 대안: (a) 현상 유지, (b) 카테고리 집계를 workflow가 부르기, (c) 집계 + "모든 lane은 집계에 속한다" 검사.
|
||||
5. 비용: (a) 누락 재발(지금 14개). (b) 잡 하나가 길어진다. (c) build-logic 테스트 하나 추가.
|
||||
6. 현재 조건의 선택: (c). 집계는 이미 있고(`integrationCheck`), 부르지 않을 뿐이다.
|
||||
7. 바뀔 조건: lane별 실패를 따로 보고 싶으면 집계를 여러 잡으로 나누되, 검사(c)는 유지한다.
|
||||
|
||||
### 5.2 strict lane을 항상 다시 실행하는 방식(`upToDateWhen(false)`)
|
||||
|
||||
1. 필요한 것: lane이 통과했다는 것이 "지정한 테스트가 실제로 돌았다"는 뜻이어야 한다.
|
||||
2. 지킬 성질: 0개 실행·skip·required 누락이 성공으로 보고되지 않는다.
|
||||
3. 현재 보장: `doLast` 검사로 지킨다. 그런데 이 검사는 캐시된 결과에도 이미 한 번 적용된 상태다. `upToDateWhen(false)`는 이 성질에 더하는 것이 없고, 외부 상태에 기대는 lane에서만 의미가 있다.
|
||||
4. 대안: 현상 유지 / 카테고리별 캐시 허용 / 전부 캐시.
|
||||
5. 비용: 현상 유지는 PR당 약 77초 + JVM 7회(08-02). 전부 캐시는 이미지 태그 변화를 못 본다.
|
||||
6. 선택: 카테고리별. hermetic(TEST·ARCHITECTURE)만 캐시.
|
||||
7. 바뀔 조건: hermetic lane이 저장소 파일이나 환경 변수를 읽기 시작하면 입력 선언을 먼저 하고, 못 하면 캐시에서 뺀다.
|
||||
|
||||
### 5.3 저장소 대조 테스트를 어디서 돌리는가
|
||||
|
||||
1. 필요한 것: 빌드·workflow·문서의 일부 계약(OIDC 권한, Docker 단계 구조)은 회귀하면 안 된다.
|
||||
2. 지킬 성질: 계약 회귀를 잡되, 문서 문구 수정으로 PR이 막히지 않는다(AGENTS.md의 정책).
|
||||
3. 현재 보장: 정책은 3개 leaf만 따른다. app-bootstrap은 15개 클래스가 PR `test`에서 문서를 읽는다(08-03).
|
||||
4. 대안: 현상 유지 / 전부 main 단계 / 보안·릴리스 계약만 PR, 나머지 main.
|
||||
5. 비용: 현상 유지는 문서 수정 PR 소음과 캐시 무효. 전부 main은 OIDC 권한 회귀를 merge 후에 잡는다.
|
||||
6. 선택: 세 번째. 보안 계약은 이유 주석과 함께 PR에 남긴다.
|
||||
7. 바뀔 조건: 문서 대조 테스트가 거의 없어지면 lane 없이 태그 하나로 충분하다.
|
||||
|
||||
## 6. 리팩토링 후보
|
||||
|
||||
| 무엇 | 왜 | 보존할 동작·실패 계약 |
|
||||
| --- | --- | --- |
|
||||
| lane 도달성 검사 추가, workflow가 카테고리 집계를 부르게 | 08-01 재발 방지 | lane의 fail-closed 검사 3종, `explicitOnly` 이유 출력 |
|
||||
| hermetic lane 캐시 허용 | 08-02 | 실행 시 3종 검사. INTEGRATION·SYSTEM·PERFORMANCE는 매번 실행 |
|
||||
| app-bootstrap 저장소 대조 테스트 분리, 입력 범위 축소 | 08-03 | 읽는 파일이 바뀌면 그 lane은 다시 돈다(O-4a) |
|
||||
| 테스트 컨테이너 이미지 목록 한 파일로 | 08-04 | digest 고정, 받지 못하면 실패 |
|
||||
| `-Duser.timezone=UTC`를 `JavaConventionsPlugin`의 모든 Test 태스크로 | O-10b, 28번 반복 | UTC 고정. lane이 jvmArgs를 덮어쓰는 현재 구조(`test.setJvmArgs`)에서 사라지지 않게 `jvmArgumentProviders`나 `systemProperty`로 넣는다 |
|
||||
| httpclient 공통 sysprop을 `tasks.withType(Test).configureEach` 하나로 | O-10a | lane별 다른 값(`performance.assertions.enabled`, httpbin 이미지)은 그 lane에만 |
|
||||
| 순수성 태스크 이름 `verifyModuleDependencyPurity` 계열로 통일 | BUILD-순수성-이름 | 루트 alias 이름이 바뀌면 workflow·문서 호출부도 같이 |
|
||||
| `netty.version` override 삭제, `commons-lang3` override에 이유 주석, 카탈로그 주석 위치 수정 | O-11b·O-11c | 해석되는 버전이 바뀌지 않음을 lockfile diff 0으로 확인 |
|
||||
|
||||
## 7. 기능 개발 패턴과 판단 지점 (매뉴얼 재료)
|
||||
|
||||
### 템플릿이 주는 틀
|
||||
|
||||
- leaf 성격 선언: `ca.java-library` / `ca.spring-library` / `ca.platform-module` 중 하나. toolchain·lock·정적분석·Mockito agent·JUnit BOM이 따라온다.
|
||||
- 추가 테스트 소스: `testing { suites { xxx(JvmTestSuite) } }` + 같은 이름의 `strictTestLanes { lane('xxx') { integration() … } }`.
|
||||
- 아키텍처 경계: `modules.json`에 edge를 적으면 방향 게이트가 나머지를 막는다.
|
||||
- 모범 테스트: `sample-portfolio`(GWT 100%), 공유 계약 예시 `WorkLogRepositoryContract`·`DurableOperationStoreContract`.
|
||||
|
||||
### 빠진 것
|
||||
|
||||
- "새 leaf 추가" 순서를 한 곳에 적은 문서가 없다(registry → build.gradle → lock 생성 → capability면 app-bootstrap `capabilityProjects`·주석 줄 → README 3항목).
|
||||
- "새 lane을 어디서 돌릴지" 고르는 기준과 검사가 없다(08-01).
|
||||
- 테스트 컨테이너 이미지를 어디에 적는지 규칙이 없다(08-04).
|
||||
- application 포트 83개 중 공유 계약을 가진 것은 소수다. 새 포트를 만들 때 계약 클래스를 같이 만들라는 틀(예시 계약 + 빈 템플릿)은 sample에만 있다.
|
||||
|
||||
### 개발자가 내려야 하는 판단
|
||||
|
||||
1. 이 코드는 어느 leaf 소유인가 → `modules.json` `source_path`. 없는 leaf면 registry부터.
|
||||
2. 이 테스트는 어떤 lane인가 → 외부 프로세스 없음 = `test`. 문서·저장소 파일 대조 = `@Tag("document-contract")` + `mainStage()`. 컨테이너·실제 서버 = 별도 suite + `integration()`/`system()`. 측정 = `performance()`.
|
||||
3. 그 lane은 누가 실행하는가 → 지금은 사람이 workflow에 적어야 한다. 적지 않을 거면 `explicitOnly("이유")`.
|
||||
4. 테스트가 저장소 파일을 읽는가 → 그 파일을 그 Test 태스크의 `inputs`로 선언한다. 넓게 잡으면 캐시가 무효가 된다(08-03).
|
||||
5. 컨테이너 이미지는 digest로 고정했는가, 다른 테스트와 같은 값인가.
|
||||
6. 의존성을 바꿨는가 → `./gradlew resolveAndLockAll --write-locks`, lock diff 확인. BOM이 관리하는 버전은 카탈로그에 적지 않는다.
|
||||
7. 포트를 새로 만들었는가 → 포트 소유 모듈 testFixtures에 fake 하나와 추상 계약 하나, adapter 테스트가 같은 계약을 상속.
|
||||
|
||||
## 8. 테스트 실행 성능
|
||||
|
||||
측정 조건: 오케스트레이터 `ci` 1회, 같은 머신에서 다른 에이전트가 함께 돌아 부하 9~31. 로컬 build cache가 거의 비어 643/663 태스크가 실제 실행. 숫자는 이 조건의 한 번 측정이다.
|
||||
|
||||
| 항목 | 값 |
|
||||
| --- | --- |
|
||||
| `ci` 전체 | 434초(잠금 대기 포함), BUILD 7분 9초 |
|
||||
| ci가 실행한 Test 태스크 | 58개, 테스트 6,115개, skip 8 |
|
||||
| 테스트 클래스 시간 합 | 약 208초 |
|
||||
| Test 태스크 JVM 구간 합 | 약 257초(4 worker로 겹쳐 실행) |
|
||||
| 결론 | ci 시간의 대부분은 테스트가 아니라 컴파일(Error Prone 포함 55개)·SpotBugs 53개·Checkstyle 106개·Spotless 53개다. 태스크별 시간은 프로파일을 돌리지 않아 미측정 |
|
||||
|
||||
가장 느린 테스트 클래스(ci):
|
||||
|
||||
| 초 | leaf | 태스크 | 클래스 | 테스트 수 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 9.3 | persistence-jpa | test | PersistenceJpaCapabilityAssemblyTest | 5 |
|
||||
| 7.8 | app-bootstrap | systemTest | BootstrapCapabilityReachabilitySystemTest | 2 |
|
||||
| 6.6 | app-bootstrap | architectureTest | AdapterBoundaryArchitectureTest | 17 |
|
||||
| 5.9 | objectstorage | test | S3AsyncClientFactoryTest | 4 |
|
||||
| 5.4 | app-bootstrap | systemTest | DefaultCompositionBootTest | 4 |
|
||||
| 3.5 | objectstorage | test | ObjectStorageArchitectureTest | 1 |
|
||||
| 3.5 | messaging-kafka | test | KafkaCapabilityActivationTest | 4 |
|
||||
| 3.0 | cache-redis | test | RedisCapabilityActivationTest | 2 |
|
||||
| 2.9 | redis-runtime | test | RedisRuntimeAutoConfigurationTest | 20 |
|
||||
| 2.7 | graphql | test | GraphQlProductionClassesTest | 1 |
|
||||
| 2.5 | objectstorage | test | LocalDevObjectStorageRecoveryTest | 5 |
|
||||
| 2.5 | persistence-mongo | test | MongoCapabilityActivationTest | 4 |
|
||||
| 2.5 | web | test | SecurityModeWebContractTest | 5 |
|
||||
| 2.4 | notification-platform | test | ProviderCallbackIngressBridgeTest | 5 |
|
||||
| 2.4 | fileserver-platform | test | FileserverPlatformAutoConfigurationTest | 11 |
|
||||
| 2.4 | web | webSecurityBoundaryTest | CorsSecurityFilterIntegrationTest | 5 |
|
||||
| 2.2 | web-fileserver | test | MvcUploadExecutorSaturationTest | 5 |
|
||||
| 2.2 | cache-redis | test | RedisCapabilityCompositionTest | 9 |
|
||||
| 2.1 | idempotency | test | IdempotencyAutoConfigurationTest | 6 |
|
||||
| 2.1 | objectstorage | test | S3ProviderCompositionTest | 6 |
|
||||
|
||||
leaf·태스크별 합(상위): objectstorage `test` 19.4초(130), app-bootstrap `architectureTest` 17.1초(181, JVM 구간 41초 — ArchUnit 클래스 import가 클래스 시간 밖에서 쓰인다), persistence-jpa `test` 16.6초(502), app-bootstrap `systemTest` 14.2초(8), app-bootstrap `test` 10.2초(321), graphql `test` 9.7초(377).
|
||||
|
||||
Spring 컨텍스트:
|
||||
|
||||
- `@SpringBootTest`/`@WebMvcTest`/`@DataJpaTest` 사용 파일은 49개로 적고, 대부분 system·integration suite에 있다. `@DirtiesContext` 0개. `@MockitoBean` 6개 파일은 모두 sample-portfolio다(컨트롤러 wire 테스트마다 mock 조합이 달라 클래스마다 컨텍스트 캐시 미스가 난다. sample 테스트 합은 마지막 기록(9월 28일)에서 5.9초라 비용은 작다. 다만 adopter가 복사하는 원본이라 패턴이 퍼진다).
|
||||
- 가장 많이 쓰는 방식은 `ApplicationContextRunner` 109개 파일이다. 캐시가 없고 `run()`마다 작은 컨텍스트를 새로 만든다. ci에서 이 클래스 99개가 574개 테스트, 49.5초(테스트 시간의 26%)를 쓴다. 테스트당 약 86ms라 지금은 문제 없다. 가장 느린 20개 중 절반이 이 종류(조립·활성화 테스트)다.
|
||||
- JUnit 병렬 실행 설정(`junit-platform.properties`) 없음. app-bootstrap `test`만 `maxParallelForks = 2`.
|
||||
|
||||
Gradle 설정: `org.gradle.parallel=true`, `org.gradle.caching=true`, `workers.max=4`, configuration cache는 꺼져 있다(이유가 `src/gradle.properties`에 적혀 있고, `integration-main.yml` `configuration-cache` 잡이 저장 가능성을 매번 확인한다). optional-platforms는 이 설정을 받지 못한다(08-06). 강제 재실행 비용은 08-02.
|
||||
|
||||
## 9. 테스트 작성 규칙 표본 조사
|
||||
|
||||
방법: 테스트 소스(`testFixtures` 제외)의 `@Test`·`@ParameterizedTest` 메서드 6,943개를 정규식으로 읽었다. 문장 수는 깊이 0의 `;` 개수로 셌다. 추정치다.
|
||||
|
||||
| 규칙(AGENTS.md) | 결과 |
|
||||
| --- | --- |
|
||||
| 1. 행동 문장 이름 | 거의 지켜짐. `test` 접두·밑줄·대문자 시작 5개 |
|
||||
| 2. `@DisplayName` 언어 | 규칙은 영어, 소유자 결정 5는 한국어. 실제 영어 2,272 / 한국어 172. 최근 수정 파일(예: `DeveloperExperienceContractTest`, `JpaReadinessRegistryTest`)은 한국어, 같은 클래스 안에서도 섞인다 |
|
||||
| 3. GWT 주석, `// when` 하나 | 문장 3개 이상 3,514개 중 610개(17%)만 주석을 가짐. `// when` 2개 이상은 1개. 규칙은 "새로 쓰거나 고치는 테스트"에만 적용이라 위반으로 세지 않았다. 모범은 sample(100%)뿐이고 production leaf 중 최고는 support(53%) |
|
||||
| 5. 약한 단언만 있는 테스트 | 단언이 하나이고 그것이 `isNotNull`/`isPresent`/`doesNotThrowAnyException`인 테스트 125개 |
|
||||
| 예외 when 분리 | `assertThatThrownBy` 포함 1,528개, `catchThrowable` 227개 |
|
||||
| 6. 포트당 fake 하나, 공유 계약 | 포트 83개 중 fake와 adapter가 같은 추상 계약을 상속하는 것은 소수(2절 TEST-F-1) |
|
||||
|
||||
이 영역의 테스트가 위험을 잡는지: build-logic의 strict lane 장치에 변이 3개(0개 실행 검사 끄기, `rejectSkipped` 끄기, `explicitOnly` 필터 끄기)를 넣고 `StrictTestLaneConventionTest`를 돌렸다. 5개 테스트가 실패해 3개 변이를 모두 잡았다. 장치 자체의 테스트는 충분하다. 빠진 것은 "lane이 실행되는가"에 대한 검사다(08-01).
|
||||
|
||||
## 10. 28개 관점 판정표
|
||||
|
||||
| 번호 | 관점 | 판정 | 한 줄 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | O | build-logic은 작은 플러그인으로 나뉘고 TestKit 테스트가 있다(main 2,854줄) |
|
||||
| 2 | 구조적 성숙도 | O | registry 하나가 프로젝트 포함·방향·순수성의 근거이고 leaf별 태스크로 병렬 안전 |
|
||||
| 3 | 변경 용이성 | P | 선택 해제는 한 줄이지만 capability 목록이 registry·`capabilityProjects`·주석 줄 세 곳, lane 추가는 workflow까지 손대야 함 |
|
||||
| 4 | 인지 부하 | P | 주석은 이유를 잘 적지만 lane이 어디서 도는지 한눈에 볼 곳이 없다 |
|
||||
| 5 | 위험 가시성 | P | readiness 카드·README가 실행되지 않는 lane을 근거로 든다(08-01) |
|
||||
| 6 | 실패 성숙도 | P | lane은 fail-closed. 하지만 main 단계는 첫 실패에서 멈춘다(08-04) |
|
||||
| 7 | 운영 성숙도 | > | 배포·운영은 다른 영역. release 서명·SBOM은 확인만 함 |
|
||||
| 8 | 디버깅 가능성 | P | lane 실패 메시지가 구체적. 다만 main-check는 실패 하나 뒤 나머지 결과가 없다 |
|
||||
| 9 | 유지보수 성숙도 | P | 지난 Nit 다수 남음(O-10a·b, O-11b·c, 이름) |
|
||||
| 10 | 테스트 성숙도 | P | 장치 테스트는 강함(변이 3/3). 실제 벤더 lane 14개 미실행, GWT 17%, 공유 계약 소수 |
|
||||
| 11 | 데이터 성숙도 | > | 마이그레이션 검증 lane이 안 도는 것은 08-01로 연결, 데이터 자체는 05 영역 |
|
||||
| 12 | 동시성 성숙도 | - | 빌드 영역에 해당 없음(lane 직렬화 서비스만 확인) |
|
||||
| 13 | 확장성 | P | leaf·lane이 늘면 이름 나열 방식의 누락 위험이 비례해서 커진다 |
|
||||
| 14 | 성능 성숙도 | P | 테스트는 병목이 아님(클래스 합 208초). 강제 재실행 약 77초/PR, 중복 systemTest, optional build 설정 누락 |
|
||||
| 15 | 보안 성숙도 | P | action SHA 고정, wrapper 검증, Trivy+KEV, cosign 서명. SpotBugs는 HIGH만(08-07) |
|
||||
| 16 | 의존성 성숙도 | P | strict lock, 카탈로그, Renovate(보안만). 테스트 이미지 관리가 흩어짐(08-04), 효과 없는 override(O-11c) |
|
||||
| 17 | API / Contract 성숙도 | O | `ca.api-surface`가 PR `check`에서 돈다(결정 20), buf lint·breaking |
|
||||
| 18 | 배포 성숙도 | > | release.yml은 확인만, 배포 영역 |
|
||||
| 19 | 설정 성숙도 | O | `verifyEnvKeys`가 main 단계에서 돈다(결정 4). 빌드 설정값은 이유와 함께 `gradle.properties`에 있음 |
|
||||
| 20 | 개발자 경험 | P | leaf focused 명령이 단순. 문서 수정이 PR을 실패시킬 수 있고(08-03) hermetic lane이 캐시되지 않음 |
|
||||
| 21 | Guardrail 성숙도 | P | 방향·순수성·lock·ignored-source는 M3~M4. lane 도달성·미등록 leaf는 M0(08-01, 08-05) |
|
||||
| 22 | 추상화 성숙도 | O | `strictTestLanes` DSL 하나로 5개 구현을 대체했고 과하지 않다 |
|
||||
| 23 | 일관성 | P | document-contract 규칙을 3개 leaf만 따름(08-03), 이미지 고정 방식 혼재, upload-artifact v4·v7 혼재 |
|
||||
| 24 | 네이밍 / 의미 성숙도 | P | 순수성 태스크 이름, `web-load-abuse-and-shutdown` 잡 이름이 하는 일과 다름 |
|
||||
| 25 | 조직 확장성 | P | 새 기여자가 lane 실행 위치를 알 방법이 workflow 검색뿐 |
|
||||
| 26 | Ownership 성숙도 | ? | CODEOWNERS는 있으나 내용과 실제 리뷰 흐름은 확인 안 함 |
|
||||
| 27 | 삭제 가능성 | P | 선택 해제는 쉬움. leaf 삭제는 app-bootstrap 테스트·빌드 9곳 수정 필요(4절) |
|
||||
| 28 | 회복 가능성 | P | 외부 이미지가 사라졌을 때 미러·치환 경로가 없다(08-04) |
|
||||
|
||||
## 부록 — 실행 명령
|
||||
|
||||
```bash
|
||||
# 게이트 로그(오케스트레이터 실행, 읽기만)
|
||||
scratchpad/gates/{summary.txt,ci.log,mainCheck.log}
|
||||
|
||||
# 도달성 확인 (worktree wt-08, flock, 시작 부하 8.22)
|
||||
./gradlew ci mainCheck --dry-run --console=plain # rc=0
|
||||
./gradlew integrationCheck --dry-run --console=plain # rc=0
|
||||
|
||||
# build cache 실험 (scratchpad/cc08, Gradle 9.0.0)
|
||||
# upToDateWhen{false} + 출력 삭제 후 재실행 -> executed
|
||||
# 같은 태스크에서 그 줄 제거 -> FROM-CACHE
|
||||
|
||||
# 변이 실험 (worktree wt-08, 시작 부하 7.16, 18초)
|
||||
./gradlew -p build-logic test --tests 'dev.caskeleton.buildlogic.strictlane.StrictTestLaneConventionTest' --continue
|
||||
# 18개 중 5개 실패 = 변이 3개 모두 검출. 원복 확인(git status 깨끗)
|
||||
|
||||
# 테스트 시간 집계: build/test-results/**/TEST-*.xml (ci 실행 구간 20:33~20:41)
|
||||
```
|
||||
@@ -0,0 +1,556 @@
|
||||
# 09. 런타임 성능 실측 — 2026-11-01 성숙도 리뷰
|
||||
|
||||
이 문서는 코드 리뷰보다 측정 숫자를 앞에 둔다. 모든 숫자는 아래 「측정 조건」에서 나왔다. 같은 측정은 3회 반복했고, 표에는 중앙값을 적었다. 다른 세션이 같은 머신을 쓰고 있었으므로 측정 직전 load average를 함께 적었다. load average가 15를 넘은 회차는 표에 `(부하 높음)`으로 표시했다.
|
||||
|
||||
## 1. 범위 (36.1)
|
||||
|
||||
| 항목 | 기록 |
|
||||
| --- | --- |
|
||||
| 대상 | `clean-architecture-backend-template`, Gradle 루트 `src/` |
|
||||
| 커밋 | `main` `01a8a2a70`. 측정은 별도 worktree(`<scratchpad>/wt-09`)에서 했다. 메인 repo에서는 Gradle을 돌리지 않았다. |
|
||||
| 목적과 실행 구성 | (1) 기본 조합 `app-bootstrap` bootJar, `local` 프로필. (2) `sample-portfolio` bootJar + PostgreSQL 16(alpine, Docker, `--cpus 4 --memory 1g`), `local` 프로필. |
|
||||
| 규모 목표 | 템플릿에 명시된 지연·처리량 목표가 없다. 그래서 「좋다/나쁘다」 대신 요청당 비용(SQL 수, 지연, 처리량)과 그 비용이 데이터 수에 비례하는지를 판정 기준으로 썼다. |
|
||||
| 읽은 코드·설정 | `app-bootstrap/build.gradle`, `app-bootstrap/src/main/resources/{application.yml,application-local.yml,config/*.yml}`, `sample-portfolio/build.gradle`, `sample-portfolio/src/main/resources/application.yml`, `sample-portfolio` 의 web controller·use case·persistence adapter·entity·mapper·migration(V7), `adapter/outbound/persistence-jpa` 의 `SpringTransaction`·`module-defaults/persistence-jpa.yml`, `adapter/inbound/web` 의 `JwtDecoderConfig`·`PageParams`·`PresentationWebConfig`·필터 4종, `composition/service-runtime` 의 `ManagementSecurityConfig`, `Dockerfile` JVM 옵션 |
|
||||
| 실행한 측정 | 아래 「측정 명령」 절. bootJar 빌드 1회, 기동 3~4회씩, SQL 수 세기, 부하 측정 약 45회(워밍업 포함), 설정만 바꾼 실험 3종, JFR 2회, 동시 중복 생성 실험 3회 |
|
||||
| 확인 못 한 것 | 아래 「미검증」 절 |
|
||||
| 게이트 결과 | 오케스트레이터 실행: `ci` rc=0. `mainCheck` rc=1 — `objectStorageMinioContractTest`·`objectStorageMinioFaultTest`가 `minio/minio` 이미지 pull 실패(공급원 소멸)로 실패. 이 영역의 숫자와 무관하다. |
|
||||
| 이전 리뷰와 비교 | 이전 리뷰에는 성능 실측 영역이 없었다. 성능 관련 지난 발견(05-persistence-jpa의 N+1·Hikari 항목)만 2절에서 재확인했다. 지난 리뷰의 실행 숫자는 쓰지 않았다. |
|
||||
|
||||
### 측정 조건
|
||||
|
||||
| 항목 | 값 |
|
||||
| --- | --- |
|
||||
| 하드웨어 | 22 vCPU, RAM 30 GiB, Linux 7.0.0. 다른 세션(프론트 vitest, 게이트)이 같은 머신에서 돌았다. |
|
||||
| JVM | OpenJDK 21.0.12.1, `-Xmx1g -XX:+ExitOnOutOfMemoryError`, G1 기본. 컨테이너가 아니라 호스트에서 `java -jar`로 띄웠다. Dockerfile의 `MaxRAMPercentage=75`는 호스트에서 22 GiB 힙이 되므로 1 GiB 컨테이너에 가까운 `-Xmx1g`를 골랐다. |
|
||||
| DB | `postgres:16-alpine`, 127.0.0.1:25432, `--cpus 4 --memory 1g`, 튜닝 없음 |
|
||||
| 데이터 | `work_log` 10,000행(행마다 `tech_stack` 2행, `link` 1행, `content` 500자). `poster`는 측정 중 쌓여 23,071행까지 늘었다. |
|
||||
| 부하 도구 | `wrk`·`hey`·`ab` 미설치. JDK `HttpClient`로 만든 닫힌 루프 생성기(`perf/Load.java`). 동시성 N개 스레드가 응답을 받자마자 다음 요청을 보낸다. 측정 시간의 앞 20%는 워밍업으로 버린다. 부하 생성기가 같은 호스트에서 돈다. |
|
||||
| 캐시 | 애플리케이션 캐시 없음(샘플 기본값 `disabled`). PG 버퍼 캐시는 워밍업 뒤 상태. |
|
||||
|
||||
### 측정 명령 (다시 돌리는 법)
|
||||
|
||||
스크립트는 모두 `<scratchpad>/perf/`에 두고 썼다. 핵심 명령만 옮긴다. 무거운 실행은 전부 `flock <heavy.lock>`으로 감쌌다.
|
||||
|
||||
```bash
|
||||
# 0) worktree와 jar
|
||||
git -C <repo> worktree add <scratchpad>/wt-09 01a8a2a70
|
||||
cd <scratchpad>/wt-09/src
|
||||
flock <heavy.lock> ./gradlew :app-bootstrap:bootJar :sample-portfolio:bootJar --console=plain -q
|
||||
|
||||
# 1) jar 구성
|
||||
unzip -l app-bootstrap/build/libs/app-bootstrap-0.0.1-SNAPSHOT.jar | awk '$4 ~ /BOOT-INF\/lib\/.*\.jar$/'
|
||||
|
||||
# 2) 기동 측정 (run-app.sh: 백그라운드 기동 → "Started ... in" 대기 → 3초 뒤 RSS·heap·빈 수·스레드 수)
|
||||
# 빈 수는 spring.jmx.enabled=true + management.endpoints.jmx.exposure.include=beans 로 켜고
|
||||
# Attach API로 Beans MBean을 부르는 Beans.java 로 셌다(코드 변경 없음).
|
||||
java -Xmx1g -XX:+ExitOnOutOfMemoryError -Dspring.jmx.enabled=true \
|
||||
-Dmanagement.endpoints.jmx.exposure.include=beans -jar <jar>
|
||||
awk '/VmRSS/{print $2}' /proc/<pid>/status ; jcmd <pid> GC.heap_info ; java Beans.java <pid>
|
||||
|
||||
# 기본 조합
|
||||
SPRING_PROFILES_ACTIVE=local MANAGEMENT_SERVER_PORT=19001 ./run-app.sh boot-N <app-bootstrap jar>
|
||||
# 샘플
|
||||
docker run -d --name perf09-pg -e POSTGRES_DB=ca_skeleton -e POSTGRES_USER=ca_skeleton \
|
||||
-e POSTGRES_PASSWORD=ca_skeleton -p 127.0.0.1:25432:5432 --cpus 4 --memory 1g postgres:16-alpine
|
||||
APP_DATASOURCE_URL=jdbc:postgresql://127.0.0.1:25432/ca_skeleton APP_SERVER_PORT=18081 \
|
||||
MANAGEMENT_SERVER_PORT=19002 SPRING_PROFILES_ACTIVE=local ./run-app.sh sample-N <sample jar>
|
||||
|
||||
# 3) 요청당 SQL 수: PG 쪽에서 모든 문장을 로그로 남기고, 요청 하나 전후의 로그 줄을 센다(앱 설정 변경 없음)
|
||||
docker exec perf09-pg psql -U ca_skeleton -d ca_skeleton -c "alter system set log_statement='all'"
|
||||
docker exec perf09-pg psql -U ca_skeleton -d ca_skeleton -c "select pg_reload_conf()"
|
||||
./sqlcount.sh list20 "http://localhost:18081/api/worklogs" # LOG: statement|execute 줄 수
|
||||
# 측정 뒤 log_statement='none' 으로 되돌리고 부하 측정
|
||||
|
||||
# 4) 부하: java Load.java <METHOD> <URL> <동시성> <초> [body.json]
|
||||
java -Xmx512m Load.java GET http://localhost:18081/api/worklogs/<id> 16 15
|
||||
|
||||
# 5) 설정만 바꾼 실험
|
||||
java ... -Dspring.jpa.properties.hibernate.default_batch_fetch_size=100 -jar <sample jar>
|
||||
SPRING_THREADS_VIRTUAL_ENABLED=true ./run-app.sh sample-vt <sample jar>
|
||||
|
||||
# 6) JFR (부하 중 20초)
|
||||
jcmd <pid> JFR.start name=p settings=profile filename=getone.jfr duration=20s
|
||||
jfr print --events jdk.ExecutionSample getone.jfr # 상위 프레임 집계
|
||||
```
|
||||
|
||||
### 미검증
|
||||
|
||||
| 항목 | 이유 |
|
||||
| --- | --- |
|
||||
| `POST /api/worklogs`(대표 쓰기)와 `POST /api/worklogs:batchCreate`의 SQL 수·지연 | 단독 실행한 샘플에서 이 경로가 항상 500으로 끝난다(09-03). 대신 같은 outbox 패턴을 쓰는 `POST /api/posters`를 쟀다. |
|
||||
| async-profiler 기반 CPU flame graph | `asprof` 미설치. JFR(`jdk.ExecutionSample`)로 대신했다. |
|
||||
| 컨테이너 안(cgroup 1 GiB) 기동 시간·RSS | 이미지 빌드는 이 영역 범위 밖이고 base image pull이 필요하다. 호스트 `-Xmx1g`로 근사했다. |
|
||||
| 장시간(수십 분) 메모리·커넥션 누적 | 측정 창이 회차당 15~20초다. 누수 판정 근거가 없다. |
|
||||
| Redis·Kafka·Mongo 등 capability를 켠 조합 | 기본 조합과 샘플만 쟀다. |
|
||||
| 실제 IdP를 거친 JWT 검증 비용 | 샘플은 모든 경로를 `permitAll`로 연다. 기본 조합에는 JWT로 보호된 업무 엔드포인트가 없다. 토큰 없는 401 경로만 쟀다. |
|
||||
|
||||
## 2. 지난 발견 재확인
|
||||
|
||||
| ID (출처) | 내용 | 상태 | 근거 |
|
||||
| --- | --- | --- | --- |
|
||||
| 05-persistence-jpa 「N+1 구조적으로 불가」 | persistence-jpa leaf에 연관관계가 없어 N+1이 없다 | 바뀜 | leaf 안에서는 여전히 사실이다. 그러나 템플릿이 따라 하라고 내놓은 `sample-portfolio`의 목록 API가 N+1이다(09-01). 실측 SQL 46개/페이지(20건). |
|
||||
| 05-persistence-jpa M8 | `HibernateEnversHistoryReader.revisions`가 1+N | 해결 | `adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/envers/HibernateEnversHistoryReader.java:82` — 리비전 번호를 한 번에 읽고, 리비전별 `find()` 루프가 없다. |
|
||||
| 05-persistence-jpa H6 | 트랜잭션 포트가 `HikariDataSource`로 언랩을 강제 | 해결 | `persistence-jpa/src/main` 아래 `HikariDataSource` 참조 0건(grep). |
|
||||
| 05-persistence-jpa 「풀 env 조정 부분」 | `keepalive-time`·`leak-detection-threshold`·`validation-timeout`이 env 없이 하드코딩 | 남음 | `adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml:55,63,72`. 주석이 여전히 "UNSUPPORTED_IMPL_DECISION … delegated"라고 적는다. 성능 결함은 아니다. |
|
||||
| maintainability-review #16 | hikari `connection-timeout` 주석이 이력 서술 | 남음(Low) | `persistence-jpa.yml:28-38`. 같은 키를 샘플은 30000으로 덮는다(09-08). |
|
||||
|
||||
## 3. 측정 결과
|
||||
|
||||
### 3.1 아티팩트와 기동
|
||||
|
||||
| 항목 | 기본 조합 `app-bootstrap` | `sample-portfolio` |
|
||||
| --- | --- | --- |
|
||||
| bootJar 크기 | 41.4 MB | 99.0 MB |
|
||||
| `BOOT-INF/lib` jar 수 / 합계 | 114개 / 39.2 MiB | 203개 / 93.9 MiB |
|
||||
| 큰 의존성 | tomcat-embed-core 3.6 MB, spring-web 2.2, prometheus exposition 2.1, spring-security-config 2.1, **jackson-databind 3.1.5 1.9 + jackson-databind 2.21.5 1.7**, **kotlin-stdlib 1.8**(OTLP okhttp sender) | hibernate-core 14.5 MB, byte-buddy 9.0, s3 3.8, **h2 2.7**, aspectjweaver 2.2, netty 13개 |
|
||||
| 기동 `Started ... in` (3회) | 3.637 / 3.179 / 3.435 s → **중앙값 3.44 s** (4번째 회차 3.592) | 8.596(첫 회, Flyway 23개 적용) / 8.045 / 7.662 s → **중앙값 8.05 s** (VT 회차 7.607) |
|
||||
| JVM 시작부터 (`process running for`) | 3.55~4.07 s | 8.13~9.09 s |
|
||||
| 기동 3초 뒤 RSS | 499~512 MB | 511~558 MB |
|
||||
| heap used / Metaspace used | 109~115 MB / 55 MB | 98~112 MB / 106 MB |
|
||||
| 스프링 빈 수 | **407** | **603** |
|
||||
| 스레드 수 | 55~59 (VT 기본 on) | 79~81 (VT 기본 off) |
|
||||
| 직전 load average | 7.2~9.0 | 7.4~7.8 |
|
||||
|
||||
뒤 회차(3.4절 실험)에서 같은 샘플 jar는 load avg 4.7~19 사이에서 6.47~6.84 s(7회)로 떴다. 기동 시간은 머신 부하에 따라 ±20% 움직인다. 기본 조합은 마지막 회차에서도 3.436 s였다.
|
||||
|
||||
샘플 기동 로그에서 0.25초 넘는 공백은 다섯 곳이다(2회차): Spring Data 저장소 스캔 0.76 s, Tomcat 초기화 1.13 s, JPA 0.53 s, Hibernate 부팅 0.89 s, 나머지 빈 생성부터 Flyway 연결까지 2.34 s. 한 곳이 지배하지 않는다. 기동 시간은 템플릿 규모(빈 600개)에 비례하는 일반적인 값이다. 결함으로 보지 않는다.
|
||||
|
||||
### 3.2 요청당 SQL 수 (PG 문장 로그, 1회 요청)
|
||||
|
||||
| 요청 | SQL 문장 수 | 내역 |
|
||||
| --- | --- | --- |
|
||||
| `GET /api/worklogs` (size 20) | **46** | `SHOW TRANSACTION ISOLATION LEVEL` 1, `BEGIN READ ONLY` 1, 본문 select 1, `count(*)` 1, **tech_stack select 20, link select 20**, COMMIT 1, 빈 validation 1 |
|
||||
| `GET /api/worklogs?size=100&sort=periodStart,desc` | **206** | 위와 같고 lazy select가 200 |
|
||||
| `GET /api/worklogs?category=BACKEND` | 46 | 같은 모양 |
|
||||
| `GET /api/worklogs?page=490` (offset 9,800) | 46 | 같은 모양 |
|
||||
| `GET /api/worklogs/{id}` | 7 | SHOW 1, BEGIN 1, select 1, lazy 2, COMMIT 1, 빈 validation 1 |
|
||||
| `PATCH /api/worklogs/{id}` (title만) | 13 | select 3 + update 1 + **link delete 1·insert 1 + tech_stack delete 1·insert 2** + SHOW/BEGIN/COMMIT |
|
||||
| `DELETE /api/worklogs/{id}` | 9 | `count(*)`(existsById) + select + 컬렉션 delete 2 + 본문 delete |
|
||||
| `POST /api/posters` | 7 | SHOW, BEGIN, `upper(title)=upper(?)` 검사, insert poster, insert outbox_event, COMMIT |
|
||||
| `GET /api/posters` | 5 | |
|
||||
|
||||
동시 8개로 `GET /api/worklogs/{id}` 50회를 보낸 묶음에서도 `SHOW TRANSACTION ISOLATION LEVEL`은 정확히 50회였다. 즉 트랜잭션마다 1회다(09-05).
|
||||
|
||||
### 3.3 지연·처리량 (플랫폼 스레드, 샘플 기본값)
|
||||
|
||||
동시성 16, 15초(앞 3초 버림), 3회 중앙값. 모든 회차 오류 0, 상태 코드 전부 200/201.
|
||||
|
||||
| 요청 | rps (3회) | 중앙값 rps | p50 | p95 | p99 | load avg |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `GET /api/worklogs/{id}` | 5348 / 5521 / 5954 | **5521** | 2.70 ms | 4.29 ms | 5.93 ms | 8.6~15.5 |
|
||||
| `GET /api/worklogs` (20건) | 806 / 837 / 829 | **829** | 15.54 ms | 38.88 ms | 41.22 ms | 16.9~17.9 (부하 높음) |
|
||||
| `GET /api/worklogs?size=100` | 174 / 171 / 185 | **174** | 94.70 ms | 108.17 ms | 134.79 ms | 10.9~16.4 |
|
||||
| `POST /api/posters` | 671 / 373 / 432 | **432** | 22.55 ms | 70.22 ms | 74.11 ms | 8.3~10.7 |
|
||||
|
||||
동시성 64:
|
||||
|
||||
| 요청 | 스레드 | 중앙값 rps | p50 | p95 | p99 | load avg |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `GET /api/worklogs/{id}` | 플랫폼 | 5418 | 11.13 ms | 22.51 ms | 31.51 ms | 5.4~13.3 |
|
||||
| `GET /api/worklogs/{id}` | 가상(`SPRING_THREADS_VIRTUAL_ENABLED=true`) | 5325 | 11.55 ms | 19.97 ms | 24.60 ms | 19.0~22.4 (부하 높음) |
|
||||
|
||||
가상 스레드 동시성 16: `GET /{id}` 5702 rps(p50 2.71 ms), `GET /worklogs` 738 rps(3회 중 1회가 334 rps로 튐, load 23~25, 부하 높음 — 비교에 쓰지 않는다).
|
||||
|
||||
Hikari 지표(플랫폼 인스턴스, 동시 16·64 회차 누적): `hikaricp_connections_acquire_seconds` 평균 5.5 ms(2946 s / 536,852회), 최대 106 ms, `pending` 0, `timeout_total` 0, `max` 10.
|
||||
|
||||
읽는 법:
|
||||
|
||||
- 단건 조회는 동시 16과 64에서 처리량이 같다(5.4~5.5k rps). 동시성을 4배로 올리면 p50만 4배가 된다. 병목은 앱 스레드가 아니라 커넥션 10개와 DB 왕복이다. 그래서 가상 스레드를 켜도 처리량이 변하지 않았다.
|
||||
- 목록 20건은 단건보다 **처리량이 6.7배 낮다**. SQL 문장 수는 7 → 46으로 6.6배다. 숫자가 거의 같다. 목록 비용의 대부분이 N+1 왕복이다.
|
||||
- 목록 100건은 20건보다 처리량이 4.8배 낮다. SQL은 46 → 206으로 4.5배다. 페이지 크기에 선형이다.
|
||||
- `POST /api/posters` 처리량은 회차마다 떨어졌다(671 → 373 → 432). 같은 회차 동안 `poster` 행이 늘었다. 제목 중복 검사가 순차 스캔이라 행 수에 비례해 느려진다(09-02).
|
||||
|
||||
### 3.4 설정만 바꾼 실험
|
||||
|
||||
코드는 바꾸지 않았다. JVM 시스템 프로퍼티만 바꿨다.
|
||||
|
||||
**(a) `hibernate.default_batch_fetch_size=100`** (`-Dspring.jpa.properties.hibernate.default_batch_fetch_size=100`). 이 키는 `persistence-jpa.yml:150`에 env(`APP_JPA_HIBERNATE_DEFAULT_BATCH_FETCH_SIZE`)로 이미 열려 있고 기본값이 0이다.
|
||||
|
||||
| 요청 | SQL 수 (기본 → 실험) | rps (3회, 실험) | 중앙값 rps (기본 → 실험) | p50 (기본 → 실험) | p95 | load avg |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `GET /api/worklogs` (20건) | 46 → **8** | 2371 / 2415 / 2411 | 829 → **2411 (2.9배)** | 15.54 → 4.27 ms | 38.88 → 38.10 ms | 8.2~9.5 |
|
||||
| `GET /api/worklogs?size=100` | 206 → **8** | 465 / 530 / 527 | 174 → **527 (3.0배)** | 94.70 → 16.10 ms | 108.17 → 69.88 ms | 6.2~8.6 |
|
||||
| `GET /api/worklogs/{id}` | 7 → 7 | — | — | — | — | — |
|
||||
|
||||
같은 세션(load 12.7)에서 기본 설정으로 다시 잰 목록 20건은 847 rps, p50 15.42 ms였다. 위 「기본」 값과 같은 수준이다.
|
||||
|
||||
목록 20건의 p95(약 38 ms)와 p99(약 41 ms)는 SQL을 46 → 8로 줄여도 그대로였다. p50만 줄었다. 이 꼬리는 DB 왕복이 아닌 다른 원인이다. 응답이 큰 요청(목록)에서만 보이고 작은 응답(단건 p95 3~4 ms)에서는 보이지 않는다. TCP delayed ACK(리눅스 기본 40 ms)와 응답 분할 쓰기의 상호작용이 의심되지만 확인하지 않았다(미검증, 「다음 측정 후보」).
|
||||
|
||||
**(b) 관측(observation) 비용 A/B** — `management.observations.enable.spring.security=false` + `management.metrics.data.repository.autotime.enabled=false`. 끄면 `spring_security_*` 시계열 26개와 `spring_data_repository_*` 6개가 사라지는 것을 `/actuator/prometheus`로 확인했다. `GET /api/worklogs/{id}`, 동시 16, 15초, A·B를 번갈아 2회씩 두 묶음(A, B, A2, B2).
|
||||
|
||||
| 변형 | rps (4회) | 중앙값 | p50 | p95 | load avg |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| A 기본(관측 켬) | 6620 / 6512 / 6588 / 6700 | 6604 | 2.30~2.36 ms | 3.10~3.24 ms | 10.4~19.2 |
|
||||
| B 관측 끔 | 6755 / 6787 / 6849 / 7094 | 6818 (+3.2%) | 2.17~2.26 ms | 2.90~3.15 ms | 14.9~18.3 (부하 높음) |
|
||||
|
||||
차이는 3% 수준이다. 이 경로는 CPU가 아니라 커넥션·DB 왕복이 병목이라, 관측 비용은 처리량에 작게 나타난다. 결함으로 올리지 않았다. 다만 JFR에서 Micrometer 프레임이 CPU 표본의 16%를 차지했으므로(3.5절), CPU가 병목인 서비스에서는 더 크게 보일 수 있다.
|
||||
|
||||
**(c) 가상 스레드** — 3.3절. 처리량 차이 없음.
|
||||
|
||||
**(d) 기본 조합의 필터 체인 바닥값** — `app-bootstrap`, `local`, 공개 경로 `GET /api/healthcheck`와 토큰 없는 보호 경로(401). 동시 16, 15초, 3회. 이 수치가 「DB 없이 보안·관측·로깅 필터만 지나는 요청」의 비용이다.
|
||||
|
||||
| 요청 | rps (3회) | 중앙값 | p50 | p95 | p99 | load avg |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `GET /api/healthcheck` → 200 | 26521 / 27276 / 27130 | **27130** | 0.51 ms | 0.91 ms | 1.40 ms | 10.2~14.8 |
|
||||
| `GET /api/anything` 토큰 없음 → 401 | 26291 / 26670 / 26690 | **26670** | 0.52 ms | 0.95 ms | 1.42 ms | 15.3~16.3 (부하 높음) |
|
||||
|
||||
필터 체인 자체의 비용은 요청당 0.5 ms 안팎이다. 샘플 단건 조회(2.7 ms)의 대부분은 DB 쪽이다.
|
||||
|
||||
### 3.5 요청당 CPU (JFR)
|
||||
|
||||
`settings=profile`, 15초, 동시 16, 샘플 기본 설정(플랫폼 스레드). 같은 회차 처리량: 단건 4801 rps, 목록 20건 847 rps(load 9.6~12.7). JFR은 스택을 64프레임에서 자르므로 「스택에 포함」 비율은 바깥 프레임(Tomcat, 필터) 쪽이 실제보다 낮게 나온다.
|
||||
|
||||
| 요청 | 표본 수 | 스택에 포함된 비율 (상위) | 잎 프레임 소유자 (상위) |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET /api/worklogs/{id}` | 2146 | Tomcat 21%, **Micrometer 16%**, Spring MVC 14%, Hibernate 14%, Spring Security 9%, pgjdbc 6%, logback 5%, 앱 코드 4%, Jackson 3%, Hikari 3% | Tomcat 20%, Micrometer 16%, JDK 14%, Hibernate 12% |
|
||||
| `GET /api/worklogs` (20건) | 682 | **Hibernate 31%**, Micrometer 11%, Tomcat 10%, pgjdbc 9%, 앱 코드 7%, logback 6%, Jackson 5% | Hibernate 29%, JDK 12%, Tomcat 10% |
|
||||
|
||||
- 목록에서는 Hibernate가 CPU의 1/3이다. lazy 컬렉션 40개를 초기화하고 바인딩하는 비용이다(09-01).
|
||||
- 단건에서 Micrometer가 16%다. 가장 바깥 Micrometer 프레임은 `Meter$Id.equals`, `KeyValues.of`, `SimpleObservation.start/stop`, `MetricsTurboFilter.decide`(logback 이벤트마다 카운터)였다. Spring Security의 `ObservationFilterChainDecorator`가 보안 필터마다 observation을 열고 닫는 것이 보였다. (b)의 A/B에서 이 둘을 끄면 처리량이 3% 올랐다.
|
||||
- 앱 필터(`WebMvcRequestIdFilter`, `RequestLoggingFilter`, `CacheControlFilter`, `JsonBodyLimitFilter`)는 합쳐 2% 이하였다. 요청 본문을 통째로 버퍼링하는 필터는 없다(`JsonBodyLimitFilter`는 스트림을 감싼다).
|
||||
- 직렬화(Jackson) 비용은 3~5%로 작다.
|
||||
|
||||
로그량: 샘플은 요청마다 `RequestLoggingFilter`가 INFO 한 줄을 쓴다. 약 53.7만 요청에 콘솔 로그 112 MB(요청당 약 210 B)였다. 운영에서 로그 수집 비용으로 그대로 이어진다. 비용 기록이지 결함은 아니다.
|
||||
|
||||
## 4. 새 발견
|
||||
|
||||
요약: High 2, Medium 4, Low 5. P1 2, P2 4, P3 5. 경로는 모두 `src/` 기준이고 샘플 패키지 접두사 `sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/`는 `<S>/`로 줄였다.
|
||||
|
||||
| ID | 제목 | 성격 | 심각도·우선순위 | 다른 영역 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 09-01 | 샘플 목록 API가 N+1 — 페이지 20건에 SQL 46개 | 확인된 결함 | Medium · P2 | > 04 persistence, 01 feature pattern |
|
||||
| 09-02 | 포스터 제목 중복 규칙이 동시 요청에서 깨지고, 검사 쿼리가 순차 스캔 | 확인된 결함 | **High · P1** | > 04 persistence |
|
||||
| 09-03 | 단독 실행한 샘플에서 대표 쓰기 `POST /api/worklogs`가 항상 500 | 확인된 결함 | **High · P1** | > 07 bootstrap/sample, 02 inbound-web |
|
||||
| 09-04 | 단독 실행한 샘플에서 `/api/v3/api-docs`가 500 | 확인된 결함 | Medium · P2 | > 02 inbound-web |
|
||||
| 09-05 | 트랜잭션마다 `SHOW TRANSACTION ISOLATION LEVEL` 왕복 1회 | 확인된 결함(비용) | Low · P3 | > 04 persistence |
|
||||
| 09-06 | 제목 하나 고치는 PATCH가 컬렉션 테이블을 전부 지우고 다시 넣음 | 확인된 결함(비용) | Medium · P2 | > 04 persistence |
|
||||
| 09-07 | JDBC batch 기본 꺼짐 + 동기 `batchCreate` 1000건을 한 트랜잭션에서 처리 | 구조적 위험(미측정) | Medium · P2 | > 04 persistence |
|
||||
| 09-08 | 샘플의 런타임 기본값이 기본 조합과 다름(가상 스레드·풀 대기·로그 레벨) | 확인된 결함(일관성) | Low · P3 | > 07 bootstrap |
|
||||
| 09-09 | persistence-jpa가 H2 드라이버를 운영 아티팩트에 실어 보냄 | 개선 제안 | Low · P3 | > 04 persistence, 08 build |
|
||||
| 09-10 | `local` 프로필이 `server.port`를 8080으로 고정해 `APP_SERVER_PORT`를 무시 | 확인된 결함(DX) | Low · P3 | > 07 bootstrap |
|
||||
| 09-11 | 기본 조합 jar에 Jackson 2·3과 kotlin-stdlib가 함께 실림 | 개선 제안 | Low · P3 | > 08 build |
|
||||
|
||||
### 09-01. 샘플 목록 API가 N+1 — 페이지 20건에 SQL 46개
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 14 성능, 13 확장성, 5 위험 가시성, 23 일관성, 9 유지보수 |
|
||||
| 근거 | `<S>/adapter/outbound/persistence/repository/WorkLogRepositoryAdapter.java:79-80` — `findAll(pageRequest)` 뒤 `WorkLogPersistenceMapper::toDomain`. `<S>/adapter/outbound/persistence/mapper/WorkLogPersistenceMapper.java:50-51` — `getTechStack()`·`getLinks()`로 lazy 컬렉션 두 개를 건드린다. `<S>/adapter/outbound/persistence/entity/WorkLogEntity.java:52-60` — 두 `@ElementCollection(fetch = LAZY)`. 응답은 요약형인데(`WorkLogWebMapper.toSummary` — id·title·category·status·period만) 엔티티 전체(`content` 최대 10,000자 포함)와 컬렉션을 다 읽는다. 같은 모듈에 요약 전용 projection(`WorkLogJpaRepository.findRecentSummaryRows`, `WorkLogSummaryQueryPort`, `ListRecentWorkLogSummariesUseCase`)이 있지만 HTTP 목록은 그 길을 쓰지 않는다. `persistence-jpa.yml:150`의 `default_batch_fetch_size` 기본값은 0이다. |
|
||||
| 실행 결과 | PG 문장 로그: size 20 → 46문장, size 100 → 206문장(= 2N + 6). 처리량: 단건 5521 rps vs 목록 20건 829 rps vs 100건 174 rps. JFR: 목록 CPU의 31%가 Hibernate. 설정 한 줄(`default_batch_fetch_size=100`)로 8문장, 2411 rps(2.9배)·527 rps(3.0배). |
|
||||
| 발생 조건 | 목록 호출마다. 페이지 크기에 선형. 데이터 총량과는 무관(offset 9,800도 46문장). 상한 100이 있어 무한히 커지지는 않는다(`PageParams.MAX_SIZE`). |
|
||||
| 영향 | 같은 커넥션 풀(10개)에서 목록 처리량이 단건의 1/7로 떨어진다. 목록과 다른 요청이 섞이면 목록이 커넥션을 오래 잡아 다른 요청의 대기도 늘어난다. 템플릿을 복사한 서비스가 이 모양(`@ElementCollection` + 엔티티 전체 매핑 + 요약 응답)을 그대로 가져간다. |
|
||||
| 심각도·우선순위 | Medium · P2. 페이지 상한이 있어 자원 고갈로 번지지 않는다. 다만 샘플이 「따라 할 기준」이므로 복제 범위가 넓다. |
|
||||
| 확실성 | 직접 측정. 남은 가정 없음. |
|
||||
| 결정의 근거 | 기록된 의도: 엔티티 주석은 "CQRS-lite projection read … skipping aggregate hydration and lazy @ElementCollection joins"(`WorkLogJpaRepository.java:19-21`)라고 적는다. 즉 팀은 이 비용을 알고 projection을 만들었다. 그런데 HTTP 목록이 그 projection을 쓰지 않는다. 위험이 코드에 드러나지 않고 「어느 쿼리 경로를 쓰는지」를 기억해야 하는 상태다. |
|
||||
| 최소 개선 방향 | 목록 use case가 요약 projection을 쓰게 한다(필터·정렬·count를 projection 쿼리에 추가). |
|
||||
| 대안 비교 | (1) 현상 유지 — 비용 그대로. (2) `default_batch_fetch_size` 기본값을 50~100으로 — 한 줄, 모든 lazy 로딩이 IN 쿼리로 묶임(46 → 8 확인). 하지만 응답에 필요 없는 `content`와 컬렉션을 여전히 읽는다. (3) **요약 projection 사용**(고른 방법) — 응답에 필요한 열만 읽는다. SQL 3~4개(+count), 컬렉션 0. 이미 있는 코드를 재사용한다. (4) `@EntityGraph`/`join fetch` — 컬렉션 2개를 동시에 fetch join하면 곱집합과 페이지네이션 경고(HHH90003004)가 생긴다. 기각. 권장: (3)을 샘플에 적용하고, (2)를 persistence-jpa 기본값으로 켤지는 04 영역이 따로 판단한다. |
|
||||
| 단순화의 보존 조건 | 응답 JSON 모양(`WorkLogSummaryResponse`), `meta.page.total`, 정렬 허용 필드(`WorkLogWebMapper.SORT_FIELDS`), 카테고리 필터, 400 `SIZE_EXCEEDS_MAX`는 그대로여야 한다. OpenAPI 스냅샷이 바뀌지 않아야 한다. |
|
||||
| 비용·부작용 | projection 쿼리에 정렬·필터를 추가하는 코드 20~40줄. 도메인 `WorkLog`를 목록에 쓰지 않게 되므로 목록과 상세의 모델이 갈린다(이미 응답은 갈려 있다). |
|
||||
| 재검토 조건 | 목록 응답이 techStack·links를 포함하게 되면 (2) 또는 별도 IN 쿼리로 다시 비교한다. |
|
||||
| 완료 기준 | `GET /api/worklogs?size=100`의 SQL 문장 수가 페이지 크기와 무관한 상수(≤ 6)다. |
|
||||
| 검증 방법 | Testcontainers 통합 테스트에서 Hibernate statistics(`prepareStatementCount`)로 size 20과 100의 문장 수가 같은지 단언한다. 이 문서의 `sqlcount.sh` 절차로 재측정한다. |
|
||||
|
||||
### 09-02. 포스터 제목 중복 규칙이 동시 요청에서 깨지고, 검사 쿼리가 순차 스캔
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 12 동시성, 11 데이터, 14 성능, 5 위험 가시성, 21 Guardrail |
|
||||
| 근거 | `<S>/application/poster/CreatePosterUseCase.java:47-51` — 같은 트랜잭션 안에서 `existsByTitle` 확인 후 insert. `<S>/adapter/outbound/persistence/repository/PosterRepositoryAdapter.java:89-90` → `existsByTitleIgnoreCase` → SQL `where upper(title)=upper(?)`. `sample-portfolio/src/main/resources/db/sample-migration/V7__poster.sql:31` — `CREATE INDEX ix_poster_title ON poster (title)`: 유일 제약이 없고, `upper(title)` 식에는 쓸 수 없는 인덱스다. |
|
||||
| 실행 결과 | (a) 같은 제목으로 동시 16개 `POST /api/posters`를 3번: 응답 201 30개·409 18개, DB에는 제목마다 **10행**(`race-1`·`race-2`·`race-3` 각 10). (b) `EXPLAIN ANALYZE`: 23,071행에서 `Seq Scan on poster … Rows Removed by Filter: 23071`, 7.2 ms. (c) `POST /api/posters` 처리량이 행이 쌓이는 동안 671 → 373 → 432 rps로 떨어졌다. |
|
||||
| 발생 조건 | (a) 같은 제목 생성이 겹치면 READ COMMITTED에서 두 트랜잭션 모두 「없음」을 본다. 더블 클릭·재시도만으로 발생한다. (b) 생성 요청마다 테이블 전체를 읽는다. |
|
||||
| 영향 | 409 `POSTER_ALREADY_EXISTS`로 약속한 규칙이 지켜지지 않는다. 중복 행 각각에 `outbox_event`도 생긴다(같은 트랜잭션에서 append). 템플릿이 31절의 「중복·동시 요청」 시나리오를 보여 주는 바로 그 자리에서 잘못된 패턴(DB 제약 없는 check-then-insert)을 가르친다. 생성 비용이 행 수에 비례해 커진다. |
|
||||
| 심각도·우선순위 | High · P1. 계약 위반을 재현했다. 샘플이 복제 기준이므로 파생 서비스로 퍼진다. 샘플 안에서만 보면 Medium이지만 템플릿의 대표 예제라는 점에서 올렸다. |
|
||||
| 확실성 | 직접 재현. 다중 인스턴스가 아니라 단일 인스턴스에서도 재현된다. |
|
||||
| 결정의 근거 | 적용 제외 — 가이드 31절이 「DB 유일성 제약과 충돌 처리가 충분한지 먼저 본다」고 정한 경우이고, 다른 선택지(락·직렬화 격리)는 그보다 비싸다. |
|
||||
| 최소 개선 방향 | 마이그레이션 V9: `CREATE UNIQUE INDEX uq_poster_title_ci ON poster (upper(title))`(또는 `lower`). 어댑터가 유일 제약 위반(SQLSTATE 23505, 제약 이름)을 `PosterTitleAlreadyExistsException`으로 바꾼다. 사전 `exists` 검사는 빠른 실패용으로 남겨도 되고 빼도 된다. 같은 인덱스가 순차 스캔도 없앤다. 기존 `ix_poster_title`은 쓰는 곳을 확인한 뒤 정리한다. |
|
||||
| 완료 기준 | 같은 제목 동시 16개 생성에서 201이 정확히 1개, 나머지는 409이고 DB에 1행. `EXPLAIN`이 인덱스 스캔이다. |
|
||||
| 검증 방법 | Testcontainers PostgreSQL에서 `CountDownLatch`로 동시 생성 테스트. 마이그레이션 테스트에 기존 중복 데이터가 있을 때의 처리(실패 메시지)를 넣는다. |
|
||||
|
||||
### 09-03. 단독 실행한 샘플에서 대표 쓰기 `POST /api/worklogs`가 항상 500
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6 실패, 17 API 계약, 20 개발자 경험, 10 테스트, 8 디버깅 |
|
||||
| 근거 | `<S>/bootstrap/security/SamplePublicAccessSecurityConfig.java:24-27` — `securityMatcher("/**")` + `anyRequest().permitAll()`, `@Order(-100)`. 이 체인에는 resource server가 없어 Bearer 토큰도 읽지 않는다. `<S>/adapter/inbound/web/controller/WorkLogController.java:221-228` — 인증 주체가 없으면 owner `null`. `<S>/domain/worklog/WorkLogOwner.java:10` — `requireNonNull(value, "owner is required")` → `NullPointerException` → `GlobalExceptionHandler`가 500 `INTERNAL_ERROR`. 같은 이유로 `POST /api/worklogs:batchCreate`(`WorkLogController.java:167`)도 같다. |
|
||||
| 실행 결과 | `java -jar sample-portfolio.jar` + PostgreSQL에서 README 예시 본문으로 `POST /api/worklogs` → 500, 로그 `java.lang.NullPointerException: owner is required at WorkLogOwner.of(WorkLogOwner.java:10)`. 시스템 테스트(`systemTest`, `webSystemTest`)에는 이 경로를 실제 서버로 부르는 테스트가 없다(grep). |
|
||||
| 발생 조건 | `Dockerfile.sample`로 만든 데모 이미지와 `bootRun`처럼 샘플을 단독으로 띄우는 모든 경우. |
|
||||
| 영향 | 샘플의 대표 쓰기 흐름(검증·outbox·멱등성 시연)을 실제로 실행해 볼 수 없다. 인증 부재가 401이 아니라 500으로 보여 원인을 찾기 어렵다. README의 curl 예시는 경로도 틀렸다(`sample-portfolio/README.md:11,26,37,48`의 `/work-logs`, 실제 경로는 `/api/worklogs`). |
|
||||
| 심각도·우선순위 | High · P1. 템플릿이 배포 가능한 데모(`Dockerfile.sample`)로 내놓은 구성에서 대표 기능이 실패한다. 데이터 피해는 없다. |
|
||||
| 확실성 | 직접 재현. |
|
||||
| 결정의 근거 | 적용 제외 — 기대 동작(인증 없으면 401, 또는 데모용 고정 owner)이 둘 중 하나로 정해지기만 하면 되는 단순 결함이다. 어느 쪽을 고를지는 07 영역·소유자 판단이다. |
|
||||
| 최소 개선 방향 | 둘 중 하나. (1) 샘플 공개 체인이 쓰기 메서드는 JWT를 요구하도록 바꾸고 인증 없음을 401로 돌려준다. (2) 데모 프로필에서만 고정 owner(`demo`)를 넣는 `AuditContextPort`/owner 공급자를 둔다. 어느 쪽이든 owner 누락은 500이 아니라 4xx로 변환한다. README 경로를 고친다. |
|
||||
| 완료 기준 | 단독 실행한 샘플에서 README의 curl이 그대로 성공(또는 문서화된 401)한다. |
|
||||
| 검증 방법 | `webSystemTest`에 실제 서버로 `POST /api/worklogs`를 부르는 테스트를 하나 추가한다. |
|
||||
|
||||
### 09-04. 단독 실행한 샘플에서 `/api/v3/api-docs`가 500
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(원인은 추론) |
|
||||
| 관련 관점 | 17 API 계약, 10 테스트, 20 개발자 경험 |
|
||||
| 근거 | 실행 결과: `GET /v3/api-docs` → 404 `ROUTE_NOT_FOUND`, `GET /api/v3/api-docs` → 500, 로그 `ClassCastException: class dev.caskeleton.shared.response.Envelope cannot be cast to class [B`. `adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/config/PresentationWebConfig.java:24-25`가 springdoc 컨트롤러에도 `/api` 접두사를 붙인다. `adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeBodyAdvice.java:26-49`는 모든 컨트롤러에 적용되고, JSON 응답이면 `Envelope`로 감싼다. springdoc은 `byte[]`를 JSON 타입으로 돌려주므로 `ByteArrayHttpMessageConverter`가 `Envelope`를 받는다(추론). 스냅샷 테스트(`OpenApiSnapshotTest.java:43-51`)는 별도 슬라이스 앱으로 `/v3/api-docs`를 불러 이 조합을 보지 않는다. |
|
||||
| 영향 | 실제로 띄운 샘플에서 OpenAPI 문서를 받을 수 없다. 계약 스냅샷 테스트는 통과하므로 게이트는 초록이다. |
|
||||
| 심각도·우선순위 | Medium · P2. |
|
||||
| 결정의 근거 | 적용 제외 — 단순 결함. |
|
||||
| 최소 개선 방향 | `EnvelopeBodyAdvice.supports`가 `byte[]`/`String`/springdoc 컨트롤러를 제외하거나, springdoc 컨트롤러에 `@OwnsAbsoluteWebRoute` 같은 접두사 예외를 준다. |
|
||||
| 완료 기준·검증 | 전체 샘플 조합(`SamplePortfolioApplication`)을 띄우는 테스트에서 OpenAPI 문서 경로가 200이다. |
|
||||
|
||||
### 09-05. 트랜잭션마다 `SHOW TRANSACTION ISOLATION LEVEL` 왕복 1회
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(비용) |
|
||||
| 관련 관점 | 14 성능, 22 추상화 |
|
||||
| 근거 | `adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransaction.java:93` — 모든 템플릿에 `ISOLATION_READ_COMMITTED`를 명시. 기본값이 아닌 격리 수준이 지정되면 Spring이 트랜잭션 시작 때 `Connection.getTransactionIsolation()`을 부르고, pgjdbc는 이를 매번 서버 왕복(`SHOW TRANSACTION ISOLATION LEVEL`)으로 처리한다. |
|
||||
| 실행 결과 | 동시 8개 단건 조회 50회 → `SHOW TRANSACTION ISOLATION LEVEL` 정확히 50회. 단건 조회 1회의 DB 왕복 6개 중 1개다. |
|
||||
| 영향 | 모든 트랜잭션에 왕복 1회(로컬 DB에서 수십~수백 µs, 원격 DB면 RTT 1회)가 붙는다. 단건 조회 기준 DB 왕복의 약 17%. PostgreSQL 기본 격리 수준이 이미 READ COMMITTED이므로 얻는 것이 없다. |
|
||||
| 심각도·우선순위 | Low · P3. |
|
||||
| 결정의 근거 | 기록된 의도: "all pinned to READ_COMMITTED"(`SpringTransaction.java` 클래스 주석). DB 기본값이 바뀌어도 격리 수준이 흔들리지 않게 하려는 고정으로 읽힌다(추론). |
|
||||
| 대안 비교 | (1) 현상 유지 — 의도는 코드에 드러나지만 왕복 비용. (2) `ISOLATION_DEFAULT` + Hikari `transaction-isolation: TRANSACTION_READ_COMMITTED` — 커넥션을 만들 때 한 번만 설정, 트랜잭션마다 왕복 없음. 풀 설정이 격리 수준을 소유하게 되어 의도가 설정 파일로 옮겨간다. (3) `ISOLATION_DEFAULT` + 기동 시 `SHOW default_transaction_isolation` 검사 — 검사는 1회. 권장 (2). |
|
||||
| 단순화의 보존 조건 | 모든 `TransactionPort` 경로가 READ COMMITTED로 도는 것. `inNew` 30초 타임아웃과 읽기 전용 플래그는 그대로. |
|
||||
| 재검토 조건 | 모드별로 다른 격리 수준(예: 일부 쓰기에 REPEATABLE READ)이 필요해지면 (1)이 맞다. |
|
||||
| 완료 기준·검증 | PG 문장 로그(또는 `pg_stat_statements`)에서 단건 조회 1회당 `SHOW TRANSACTION ISOLATION LEVEL` 0회, 그리고 트랜잭션 안에서 `SHOW transaction_isolation`이 `read committed`인 통합 테스트. |
|
||||
|
||||
### 09-06. 제목 하나 고치는 PATCH가 컬렉션 테이블을 전부 지우고 다시 넣음
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(비용) |
|
||||
| 관련 관점 | 14 성능, 11 데이터, 12 동시성 |
|
||||
| 근거 | `<S>/adapter/outbound/persistence/repository/WorkLogRepositoryAdapter.java` `save` — 도메인 객체에서 새 엔티티를 만들고(`WorkLogPersistenceMapper.toEntity`) `jpa.save`(merge)한다. 새 `List` 인스턴스가 들어가므로 Hibernate가 컬렉션 전체를 교체로 본다. |
|
||||
| 실행 결과 | `PATCH {"title":"patched2"}` 1회 = 13문장: select 3, update 1, `delete from work_log_link` 1 + insert 1, `delete from work_log_tech_stack` 1 + insert 2. |
|
||||
| 영향 | 바뀌지 않은 자식 행도 매번 삭제·삽입된다. WAL·인덱스 갱신·락 범위가 커진다. 자식 행이 많을수록 커진다(행 수에 선형). 감사·CDC를 붙이면 가짜 변경 이벤트가 생긴다. |
|
||||
| 심각도·우선순위 | Medium · P2. |
|
||||
| 결정의 근거 | 기록된 의도: 도메인에 감사 필드를 두지 않고 어댑터에서 붙이기 위해 엔티티를 새로 만든다(README 참조 주석). 이 선택의 비용이 컬렉션 교체다. |
|
||||
| 대안 비교 | (1) 현상 유지. (2) 기존 관리 엔티티를 읽어 필드를 복사(`existing.apply(domain)`)하고 컬렉션은 내용이 다를 때만 `clear/addAll` — 변경 없는 컬렉션은 SQL 0. (3) 컬렉션을 JSON/배열 컬럼으로 — 스키마 변경. 권장 (2). |
|
||||
| 단순화의 보존 조건 | `@Version` 낙관적 잠금과 412 응답, `created_*` 보존·`updated_*` 갱신, ETag 값. |
|
||||
| 완료 기준·검증 | 제목만 바꾸는 PATCH의 SQL에 `delete from work_log_link`/`work_log_tech_stack`가 없다(Hibernate statistics 단언). |
|
||||
|
||||
### 09-07. JDBC batch 기본 꺼짐 + 동기 `batchCreate` 1000건을 한 트랜잭션에서 처리
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(미측정 — 09-03 때문에 실행 불가) |
|
||||
| 관련 관점 | 14 성능, 13 확장성, 12 동시성 |
|
||||
| 근거 | `adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml:147-150` — `batch_size` 0, `order_inserts` false. `<S>/adapter/inbound/web/controller/WorkLogController.java:178` — `MAX_BATCH_SIZE = 1000`, 「Sync = atomic」 한 트랜잭션. 항목마다 work_log insert 1 + tech_stack k + link m + outbox insert 1. |
|
||||
| 발생 조건 | 1000건 요청 1회 = 최소 약 3,000~5,000 왕복을 한 커넥션이 한 트랜잭션으로 잡는다. JSON 본문 상한(`JsonBodyLimitFilter`)이 크기를 막지만 건수 1000은 허용한다. |
|
||||
| 영향 | 요청 하나가 커넥션 1개를 수 초 잡는다. 풀이 10개이므로 동시에 몇 건만 와도 다른 요청이 `connection-timeout`(기본 5 s)까지 기다린다. |
|
||||
| 심각도·우선순위 | Medium · P2. 측정하지 못했으므로 High로 올리지 않았다. |
|
||||
| 최소 개선 방향 | (1) 샘플에서 `APP_JPA_HIBERNATE_BATCH_SIZE`·`ORDER_INSERTS`를 켜고 `HibernateJpaBatchExecutor`의 증명 방식을 따른다. (2) 동기 배치 상한을 100 정도로 낮추고 그 이상은 기존 비동기 operation(`OperationsController`)으로 보낸다. |
|
||||
| 완료 기준·검증 | 09-03을 고친 뒤 1000건 요청의 SQL 왕복 수와 커넥션 점유 시간을 측정해 문서화한다. |
|
||||
|
||||
### 09-08. 샘플의 런타임 기본값이 기본 조합과 다름
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(일관성) |
|
||||
| 관련 관점 | 23 일관성, 19 설정, 14 성능 |
|
||||
| 근거 | 가상 스레드: `app-bootstrap/src/main/resources/application.yml:54-57` `SPRING_THREADS_VIRTUAL_ENABLED:true` vs `sample-portfolio/src/main/resources/application.yml:69-71` `:false`. 풀 대기: `persistence-jpa.yml:38` `connection-timeout` 5000(주석: fail-fast 원칙) vs 샘플 `application.yml:36` 30000. 앱 로그 레벨: `app-bootstrap/.../config/observability.yml:108` INFO vs 샘플 `application.yml:139` DEBUG. 샘플 파일 머리말은 "Mirrors app-bootstrap/application.yml"이라고 적는다. |
|
||||
| 실행 결과 | 스레드 수 55~59(기본) vs 79~81(샘플). 가상 스레드 켜기/끄기의 처리량 차이는 없었다(3.3절, 커넥션 10개가 병목). |
|
||||
| 영향 | 샘플로 측정한 숫자(대기 시간, 스레드 수)가 기본 조합의 동작을 대표하지 않는다. 풀이 마른 상황에서 샘플은 30초를 기다리고 기본 조합은 5초에 실패한다. |
|
||||
| 심각도·우선순위 | Low · P3. |
|
||||
| 최소 개선 방향 | 샘플이 기본값을 덮어쓰는 키를 지우고 모듈 기본값을 따르게 한다. 다르게 둘 이유가 있으면 그 키 옆에 이유를 적는다. |
|
||||
| 완료 기준·검증 | 두 조합의 effective 값 비교 테스트(이미 있는 `ProfileSeparationContractTest` 계열에 키 목록 추가). |
|
||||
|
||||
### 09-09. persistence-jpa가 H2 드라이버를 운영 아티팩트에 실어 보냄
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안 |
|
||||
| 관련 관점 | 16 의존성, 15 보안, 18 배포 |
|
||||
| 근거 | `adapter/outbound/persistence-jpa/build.gradle:82` — `runtimeOnly 'com.h2database:h2'`. 실행 결과: 샘플 bootJar에 `BOOT-INF/lib/h2-2.4.240.jar`(2.7 MB). JPA를 켠 모든 서비스 jar에 같은 일이 생긴다. |
|
||||
| 영향 | 운영 이미지에 쓰지 않는 인메모리 DB 엔진이 들어간다. 크기 2.7 MB와 취약점 스캔 대상이 늘어난다. H2 콘솔 설정은 없다(`spring.h2.console` grep 0건, Boot 기본값 꺼짐). |
|
||||
| 심각도·우선순위 | Low · P3. |
|
||||
| 대안 비교 | (1) 현상 유지 — `bootRunH2` 편의. (2) H2를 `bootRunH2Classpath`·테스트 구성에만 둔다(`app-bootstrap/build.gradle`의 `bootRunH2`가 이미 별도 classpath를 만든다). 권장 (2). |
|
||||
| 완료 기준·검증 | `unzip -l` 결과 bootJar에 `h2-*.jar`가 없고 `bootRunH2`가 여전히 뜬다. |
|
||||
|
||||
### 09-10. `local` 프로필이 `server.port`를 8080으로 고정
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(DX) |
|
||||
| 관련 관점 | 20 개발자 경험, 19 설정 |
|
||||
| 근거 | `app-bootstrap/src/main/resources/application-local.yml:127` `port: 8080`. 실행 결과: `APP_SERVER_PORT=18080`을 줬는데 `Tomcat started on port 8080`. 파일 머리말은 「완전한 독립 설정」이라 의도된 모양이지만, 이 키만은 env를 받을 이유가 있다. |
|
||||
| 영향 | 같은 머신에서 두 서비스(또는 기본 조합과 샘플)를 동시에 띄우면 포트 충돌. env로 피할 수 없다. |
|
||||
| 심각도·우선순위 | Low · P3. |
|
||||
| 최소 개선 방향 | `port: ${APP_SERVER_PORT:8080}`. |
|
||||
|
||||
### 09-11. 기본 조합 jar에 Jackson 2·3과 kotlin-stdlib가 함께 실림
|
||||
|
||||
| 필드 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안 |
|
||||
| 관련 관점 | 16 의존성, 18 배포 |
|
||||
| 근거 | 기본 조합 `BOOT-INF/lib`: `jackson-databind-3.1.5`(1.9 MB)와 `jackson-databind-2.21.5`(1.7 MB)·`jackson-core-2.21.5`·`jackson-dataformat-yaml-2.21.5`·`jackson-datatype-jsr310-2.21.5`, `kotlin-stdlib-2.2.21`(1.8 MB)·`okhttp-jvm`·`okio-jvm`. 2 계열의 출처는 logstash encoder와 OTel 쪽으로 추정한다(미확인 — `dependencyInsight` 미실행). kotlin은 `opentelemetry-exporter-sender-okhttp`를 따라온다. |
|
||||
| 영향 | 기본 jar 39 MiB 중 약 5~6 MiB. 두 Jackson 계열의 보안 패치를 따로 추적해야 한다. |
|
||||
| 심각도·우선순위 | Low · P3. |
|
||||
| 최소 개선 방향 | `./gradlew :app-bootstrap:dependencyInsight --dependency com.fasterxml.jackson.core:jackson-databind`로 출처를 확인한다. OTLP sender를 JDK HttpClient 구현(`opentelemetry-exporter-sender-jdk`)으로 바꾸면 kotlin·okhttp가 빠진다. |
|
||||
|
||||
## 5. 31절 시나리오 추적
|
||||
|
||||
이 영역은 실측이므로, 실제로 요청을 보내 따라간 시나리오만 적는다.
|
||||
|
||||
### 5.1 큰 입력·목록 조회 — `GET /api/worklogs?size=100&sort=periodStart,desc`
|
||||
|
||||
```text
|
||||
HTTP → 보안 체인(샘플: permitAll) → 앱 필터 4개 → WorkLogController.list
|
||||
→ PageParams.of (size 1..100 검사) ← 상한 있음
|
||||
→ ListWorkLogsUseCase.handle → tx.inRead ← 트랜잭션 시작: SHOW ISOLATION + BEGIN READ ONLY
|
||||
→ WorkLogRepositoryAdapter.findPage
|
||||
→ select work_log … offset/limit ← 1
|
||||
→ select count(*) ← 1
|
||||
→ 행마다 tech_stack select, link select ← 200 (N+1)
|
||||
→ COMMIT
|
||||
→ toSummary (컬렉션 안 씀) → Envelope + meta.page → Jackson
|
||||
```
|
||||
|
||||
| 항목 | 결과 |
|
||||
| --- | --- |
|
||||
| 입력 신뢰 수준 | 외부 입력. `page`·`size`·`sort`·`category` 모두 컨트롤러 경계에서 검사(size ≤ 100, sort 문법·허용 필드, enum). |
|
||||
| 인가 위치 | 샘플은 없음(permitAll). |
|
||||
| 규칙 소유 | 페이지 상한은 web 어댑터 `PageParams`. |
|
||||
| 트랜잭션 | use case가 `inRead`로 연다. 읽기 전용, READ COMMITTED. |
|
||||
| 외부 부작용 | 없음. |
|
||||
| 성공의 의미 | 200, `meta.page.total` 포함. |
|
||||
| 오류 변환 | size 초과 → 400 `VALIDATION_FAILED`/`SIZE_EXCEEDS_MAX`, 정렬 문법 오류 → 400 `SORT_SYNTAX_INVALID`(실행으로 확인). |
|
||||
| 진단 정보 | 응답 `meta.requestId/traceId/correlationId`, 요청마다 INFO 로그 1줄. |
|
||||
| 판정 | 응답 크기와 페이지 크기는 제한된다. **호출 수는 페이지 크기에 비례**한다(206문장). 깊은 offset(page 490)도 허용되고 비용은 같았다(인덱스 없는 정렬 + offset 9,800 → `EXPLAIN` 12.8 ms). 데이터 총량이 늘면 `count(*)`와 offset 정렬이 함께 커진다. |
|
||||
|
||||
### 5.2 중복·동시 요청 — `POST /api/posters` 같은 제목 16개 동시
|
||||
|
||||
| 항목 | 결과 |
|
||||
| --- | --- |
|
||||
| 요청 식별 | 없음. 멱등성 키를 받지 않는다(샘플의 멱등성은 poster image 경로에만). |
|
||||
| DB 제약 | 제목에 유일 제약 없음(`V7__poster.sql:31`). |
|
||||
| 규칙 소유 | `CreatePosterUseCase`의 사전 `exists` 검사 하나. |
|
||||
| 트랜잭션 | `inWrite`, READ COMMITTED — 겹친 트랜잭션은 서로의 미커밋 insert를 못 본다. |
|
||||
| 외부 부작용 | 같은 트랜잭션의 `outbox_event` insert. 중복 행마다 이벤트도 중복. |
|
||||
| 결과 | 제목마다 10행. **계약 위반 재현**(09-02). |
|
||||
|
||||
### 5.3 정상 쓰기 요청 — `POST /api/worklogs`
|
||||
|
||||
실행 불가. 단독 실행에서 500(09-03). 대신 같은 모양(검사 → insert → outbox append, 한 트랜잭션)인 `POST /api/posters`를 쟀다: 7문장, 432 rps(행 증가 중), p50 22.6 ms.
|
||||
|
||||
### 적용 제외
|
||||
|
||||
| 시나리오 | 사유 |
|
||||
| --- | --- |
|
||||
| 외부 응답 지연·유실 | 샘플의 외부 호출(`RepoStatsPortClient.fetchRaw`)은 스텁이다. 요청 경로에 실제 동기 외부 호출이 없다. 05 영역(httpclient)이 다룬다. |
|
||||
| DB 오류·경쟁 | 09-02의 경쟁 외에는 이 영역에서 다루지 않았다(> 04). |
|
||||
| 메시지 중복·역순, 신·구 버전, 여러 서버 작업, 세션·토큰, 다른 사용자 리소스, 종료·재시작, 선택 어댑터 제거 | 성능 실측 범위 밖. 각 담당 영역(06, 07, 02, 04). |
|
||||
|
||||
## 6. 41절 설계 선택 검토
|
||||
|
||||
### 6.1 커넥션 풀 10개 + (기본 조합) 가상 스레드 on
|
||||
|
||||
| 질문 | 답 |
|
||||
| --- | --- |
|
||||
| 1. 무엇이 필요한가 | 요청 동시성이 커져도 DB 연결 수를 작게 유지하고, 풀이 마르면 오래 기다리지 않는 것. |
|
||||
| 2. 지킬 성질 | DB 커넥션 상한(10), 대기 상한(`connection-timeout` 5 s), REQUIRES_NEW 깊이를 고려한 최소 풀 크기(`persistence-jpa.yml:15-22` 주석의 공식). |
|
||||
| 3. 현재 보장 | 풀 크기·대기 시간은 설정으로 고정, `HikariPoolConstraintValidator`가 기동 때 값 관계를 검사한다. 가상 스레드를 켜면 Tomcat `threads.max: 200`이 더 이상 요청 동시성을 막지 않는다. 그러면 동시성 상한은 풀 대기열뿐이다. |
|
||||
| 4. 대안 | (a) 현상 유지. (b) 플랫폼 스레드(샘플 기본) — 스레드 200개가 상한. (c) 가상 스레드 + 앱 입구의 동시 실행 제한(web-advanced의 opt-in `VirtualThreadAdmissionGuard`). (d) 풀 크기를 CPU에 맞춰 키움. |
|
||||
| 5. 얻고 잃는 것 | 실측: 단건 조회 처리량은 (a)·(b) 모두 약 5.4k rps, 동시 16→64에서 p50만 2.7→11 ms. Hikari 평균 획득 대기 5.5 ms. 즉 지금 부하에서는 스레드 모델이 결과를 바꾸지 않는다. (a)는 블로킹 외부 호출이 섞일 때 스레드 고갈이 없다. 대신 폭주 시 대기가 풀 앞에 무한히 쌓이고 5 s 뒤 일괄 실패한다. (b)는 200에서 멈추고 나머지는 accept 큐(100)·커넥션(8192)에서 기다린다. |
|
||||
| 6. 왜 이 선택인가 | 기록된 의도는 "Java 21 virtual threads for Tomcat request handlers". 측정으로 보면 DB가 병목인 한 손해도 이득도 없다. 외부 HTTP 호출이 많은 서비스에서 이득이 생긴다. |
|
||||
| 7. 바뀔 조건 | 풀 대기(`hikaricp_connections_pending`)가 지속적으로 0보다 크면 (c)를 기본 경로로 고려한다. DB 왕복이 없는 CPU 위주 서비스면 차이 없음. |
|
||||
|
||||
판정: 선택은 타당하다. 다만 샘플이 반대 기본값을 써서(09-08) 템플릿이 하나의 답을 보여 주지 않는다.
|
||||
|
||||
### 6.2 `SpringTransaction`의 READ COMMITTED 명시
|
||||
|
||||
41.2 일곱 질문의 답은 09-05 표에 있다. 요약: 의도(격리 수준 고정)는 지킬 가치가 있지만, 같은 보장을 풀 설정(Hikari `transaction-isolation`)으로 옮기면 트랜잭션마다 왕복 1회가 없어진다. 모드별로 다른 격리 수준이 필요해지면 지금 방식이 맞다.
|
||||
|
||||
### 6.3 목록 조회가 도메인 집계를 통째로 읽기 (vs 요약 projection)
|
||||
|
||||
| 질문 | 답 |
|
||||
| --- | --- |
|
||||
| 1. 필요 | 페이지·정렬·필터가 되는 요약 목록. |
|
||||
| 2. 지킬 성질 | 응답 모양, 페이지 메타, 정렬 허용 필드. |
|
||||
| 3. 현재 보장 | 집계 전체를 읽어 요약으로 줄인다(09-01). 요약 projection은 따로 있지만 HTTP가 쓰지 않는다. |
|
||||
| 4. 대안 | 09-01 대안 비교 (1)~(4). |
|
||||
| 5. 비용 | 실측: 46문장 vs (batch fetch) 8문장, 829 vs 2411 rps. projection은 측정하지 않았지만 lazy 0개라 8문장보다 적다(추론). |
|
||||
| 6. 선택 이유 | 기록 없음. 같은 모듈에 projection이 있다는 사실은 의도가 projection 쪽이었음을 보여 준다. |
|
||||
| 7. 바뀔 조건 | 목록 응답이 컬렉션을 포함하게 되면 batch fetch가 낫다. |
|
||||
|
||||
## 7. 리팩토링 후보
|
||||
|
||||
| 대상 | 무엇을 왜 | 보존해야 할 동작·타입·실패 계약 |
|
||||
| --- | --- | --- |
|
||||
| `ListWorkLogsUseCase` + `WorkLogRepository.findPage` / `WorkLogSummaryQueryPort` | 목록 읽기 경로가 둘(집계형 `findPage`, 요약형 `findRecentSummaries`)로 갈라져 있다. HTTP 목록을 요약형 하나로 합치면 N+1이 사라지고 중복 경로가 하나 준다. | `WorkLogSummaryResponse` JSON, `meta.page`(number·size·total·sort), 정렬 필드 집합, 카테고리 필터, 400 코드. OpenAPI 스냅샷 불변. |
|
||||
| `WorkLogRepositoryAdapter.save` | 새 엔티티 merge → 관리 엔티티에 변경 적용. 컬렉션 재작성(09-06)과 adapter 안의 두 번째 `findById`가 없어진다. | `@Version` 충돌 시 412, 감사 필드 의미(created 보존, updated 갱신), 반환 도메인 객체의 version. |
|
||||
| `SpringTransaction.template` | 격리 수준 명시를 풀 설정으로 이동(09-05). | 모든 모드 READ COMMITTED, `inNew` 30 s, 읽기 전용, `inRootWrite` 중첩 거부. |
|
||||
| `CreatePosterUseCase` | 사전 검사 + DB 유일 제약 변환(09-02). | 409 `POSTER_ALREADY_EXISTS` 응답 모양, 대소문자 무시 비교 의미. |
|
||||
|
||||
## 8. 기능 개발 패턴과 판단 지점 (매뉴얼 재료)
|
||||
|
||||
### 템플릿이 주는 틀
|
||||
|
||||
- 페이지 파라미터 검사(`PageParams`, 상한 100)와 `meta.page` 응답 모양.
|
||||
- 요약 projection 예시(`WorkLogJpaRepository.findRecentSummaryRows` + `WorkLogSummaryQueryPort`).
|
||||
- JPA 성능 손잡이(`APP_JPA_HIBERNATE_BATCH_SIZE`, `…ORDER_INSERTS`, `…DEFAULT_BATCH_FETCH_SIZE`, `…GENERATE_STATISTICS`)와, batch가 실제로 일어났는지 증명하는 `HibernateJpaBatchExecutor`.
|
||||
- Hikari 풀 기본값과 값 관계 검사(`HikariPoolConstraintValidator`), Prometheus의 `hikaricp_*` 지표.
|
||||
- JFR·SQL 로그를 켤 수 있는 설정 경로(코드 변경 없이 이 문서의 모든 측정이 가능했다).
|
||||
|
||||
### 빠진 것
|
||||
|
||||
- 「요청 하나에 SQL이 몇 개인가」를 단언하는 테스트 틀이 없다. Hibernate statistics 손잡이는 있지만 그것으로 문장 수를 고정하는 예제 테스트가 없다. 그래서 09-01·09-06이 게이트를 통과했다.
|
||||
- 성능 기준선(숫자)이 없다. gRPC에는 performance lane이 있지만 HTTP·JPA 경로에는 없다.
|
||||
- 동시 생성 경쟁을 재현하는 테스트 예시가 없다(09-02).
|
||||
- 샘플을 단독으로 띄워 대표 요청을 한 바퀴 도는 스모크가 없다(09-03·09-04).
|
||||
|
||||
### 개발자가 여기서 내려야 하는 판단
|
||||
|
||||
1. **목록 응답이 집계 전체를 필요로 하는가?** 아니면 요약 projection으로 읽는다. 필요하면 컬렉션마다 batch fetch 또는 별도 IN 쿼리를 쓴다. `@ElementCollection`을 쓰면 「목록에서 몇 번 읽히는가」를 먼저 센다.
|
||||
2. **유일해야 하는 값인가?** 그렇다면 DB 유일 제약(대소문자 무시면 식 인덱스)을 먼저 만들고, 사전 검사는 친절한 오류용으로만 둔다.
|
||||
3. **수정 시 무엇을 다시 쓰는가?** 새 엔티티를 merge하면 컬렉션이 전부 다시 쓰인다. 관리 엔티티에 변경만 적용한다.
|
||||
4. **동기 배치의 상한은 몇인가?** 「한 트랜잭션에서 커넥션을 몇 초까지 잡아도 되는가」로 정한다. 넘으면 비동기 operation으로 보낸다. 배치를 쓰면 `batch_size`와 `order_inserts`를 켠다.
|
||||
5. **스레드 모델과 풀 크기**: 요청 경로에 블로킹 외부 호출이 있으면 가상 스레드가 이득이다. DB만 있으면 풀 크기와 쿼리 수가 처리량을 정한다. 풀 대기 지표(`hikaricp_connections_pending`, `acquire_seconds`)를 대시보드에 둔다.
|
||||
6. **새 엔드포인트의 SQL 수를 테스트로 고정할 것인가?** 목록·쓰기 경로에는 고정한다. 단건 조회는 선택.
|
||||
|
||||
### 다음 측정 후보
|
||||
|
||||
- 목록 응답 p95 ≈ 38 ms 고정 꼬리의 원인(TCP delayed ACK 의심) — `ss -ti`, `tcpdump`, 응답 크기별 분포로 확인.
|
||||
- 09-03 수정 뒤 `POST /api/worklogs`와 `batchCreate` 1000건의 SQL 수·커넥션 점유 시간.
|
||||
- 30분 이상 부하에서 heap·RSS·커넥션 추이.
|
||||
- 컨테이너(cgroup 1 GiB) 안 기동 시간과 RSS.
|
||||
|
||||
## 9. 28개 관점 판정표
|
||||
|
||||
기호: O 충족, P 부분, X 미충족, ? 미검증, - 적용 제외, > 다른 영역.
|
||||
|
||||
| 번호 | 관점 | 판정 | 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | > | 01·04 영역. 이 영역은 측정 경로의 코드만 읽었다. |
|
||||
| 2 | 구조적 성숙도 | > | 01 영역. |
|
||||
| 3 | 변경 용이성 | P | 성능 손잡이 대부분이 env로 열려 있어 코드 없이 바꿀 수 있었다. 목록 읽기 경로가 둘로 갈려 있다(09-01). |
|
||||
| 4 | 인지 부하 | P | 「어느 쿼리 경로가 HTTP에 쓰이는가」를 따라가야 비용을 안다. |
|
||||
| 5 | 위험 가시성 | X | N+1·컬렉션 재작성·중복 경쟁이 코드에 드러나지 않는다. 주석은 projection이 있다고 말하지만 실제 경로는 다르다(09-01, 09-02, 09-06). |
|
||||
| 6 | 실패 성숙도 | P | 페이지·정렬 오류는 깔끔한 400. 인증 부재가 500으로 새는 경로가 있다(09-03). |
|
||||
| 7 | 운영 성숙도 | P | Hikari·HTTP·보안 지표가 Prometheus에 있다. 성능 기준선이 없다. |
|
||||
| 8 | 디버깅 가능성 | O | requestId·traceId가 응답과 로그에 있다. 코드 수정 없이 SQL 로그·JFR·빈 수를 얻었다. |
|
||||
| 9 | 유지보수 성숙도 | P | 샘플 설정이 모듈 기본값을 말없이 덮는다(09-08). |
|
||||
| 10 | 테스트 성숙도 | X | 요청당 SQL 수, 동시 생성 경쟁, 단독 실행 샘플의 대표 쓰기·OpenAPI 경로를 잡는 테스트가 없다. 게이트는 초록인데 09-02·09-03·09-04가 실행으로 재현된다. |
|
||||
| 11 | 데이터 성숙도 | X | 제목 유일 규칙이 DB에 없다(09-02). |
|
||||
| 12 | 동시성 성숙도 | X | check-then-insert 경쟁 재현(09-02). |
|
||||
| 13 | 확장성 | P | 페이지 상한·풀 상한이 있다. 목록 비용이 페이지 크기에 선형, 포스터 생성 비용이 행 수에 선형(09-01, 09-02). |
|
||||
| 14 | 성능 성숙도 | P | 기동 3.4 s(기본)/6.5~8.0 s(샘플), 필터 체인 0.5 ms, 단건 2.7 ms는 양호. 목록 N+1, 트랜잭션마다 추가 왕복, 성능 기준선 부재. |
|
||||
| 15 | 보안 성숙도 | > | 02 영역. 측정 중 본 것: H2 jar 동봉(09-09), 샘플 전체 permitAll은 의도된 데모 구성. |
|
||||
| 16 | 의존성 성숙도 | P | Jackson 2·3 공존, kotlin·okhttp, H2 동봉(09-09, 09-11). |
|
||||
| 17 | API / Contract 성숙도 | P | 실제 서버의 `/api/v3/api-docs` 500, README 경로 불일치(09-03, 09-04). |
|
||||
| 18 | 배포 성숙도 | > | 08 영역. jar 크기만 측정(41.4 / 99.0 MB). |
|
||||
| 19 | 설정 성숙도 | P | env 손잡이는 충분하다. 샘플·local 프로필이 일부 키를 고정·덮어쓴다(09-08, 09-10). |
|
||||
| 20 | 개발자 경험 | P | 샘플 단독 실행 시 대표 쓰기 실패, local 포트 고정(09-03, 09-10). |
|
||||
| 21 | Guardrail 성숙도 | P | 풀 값 관계 검사와 batch 증명 장치는 있다. SQL 수·유일 제약 같은 성능·데이터 가드는 없다. |
|
||||
| 22 | 추상화 성숙도 | - | 성능 실측 범위 밖(09-05의 격리 수준 위치만 언급). |
|
||||
| 23 | 일관성 | P | 기본 조합과 샘플의 스레드·풀 대기·로그 기본값 불일치(09-08). |
|
||||
| 24 | 네이밍 / 의미 성숙도 | - | 범위 밖. |
|
||||
| 25 | 조직 확장성 | - | 범위 밖. |
|
||||
| 26 | Ownership 성숙도 | - | 범위 밖. |
|
||||
| 27 | 삭제 가능성 | - | 범위 밖(H2 분리는 09-09). |
|
||||
| 28 | 회복 가능성 | ? | 장시간·장애 조건 측정을 하지 않았다. |
|
||||
|
||||
## 정리 상태
|
||||
|
||||
측정에 쓴 프로세스(샘플·기본 조합 JVM)와 컨테이너 `perf09-pg`는 모두 내렸고, 이 측정에서만 받은 `postgres:16-alpine` 이미지도 지웠다. worktree `<scratchpad>/wt-09`는 `git worktree remove --force`로 지웠다. 측정 스크립트와 원시 출력(`Load.java`, `Beans.java`, `run-app.sh`, `sqlcount.sh`, `bench.sh`, `phase3.sh`, `phase4.sh`, `bench-*.txt`, `sql-*.txt`, `*.jfr`, `jfr-summary.txt`)은 세션 scratchpad의 `perf/`에 남아 있다. 이 문서의 「측정 명령」 절만으로 다시 만들 수 있다.
|
||||
@@ -0,0 +1,618 @@
|
||||
# 백엔드 성숙도 리뷰 — 2026-11-01
|
||||
|
||||
> 기준: `clean-architecture-frontend-template/docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(31절 Backend 시나리오). 기준 커밋: `main` `01a8a2a70`(리뷰 후속 Wave 1–3 머지 직후). repo 전체를 9개 영역으로 나눠 영역 에이전트가 병렬로 읽고 실험했다. 이 문서는 오케스트레이터가 결과를 모으고 High 발견을 코드에서 다시 확인한 것이다. 영역 문서는 리뷰 시점 기록이라 수정 후에도 고치지 않는다.
|
||||
|
||||
## 1. 사용 결정 (36.5-1)
|
||||
|
||||
| 용도 | 결정 | 막는 항목 |
|
||||
|---|---|---|
|
||||
| 기본 조합(web·observability·cores)으로 새 서비스 시작 | **조건부 사용 가능** | 02-03(JWT audience가 비면 검증 안 함), 07-01(트레이스가 나가지 않음), 07-02(prod 기동 검사가 마이그레이션 뒤에 돔), 04-01(커밋 중 끊김을 재시도 가능으로 응답) |
|
||||
| 짝 프론트 템플릿과 그대로 붙여 쓰기 | **사용 보류** | 02-02(Envelope의 null 필드를 프론트 strict 스키마가 거절), 02-01(처리 중 409의 클라이언트 행동이 계약에 없음) |
|
||||
| sample-portfolio를 새 기능의 따라 할 예시로 복제 | **사용 보류** | 07-03·09-03(실행 중 권한 검사 없음, 대표 쓰기 500), 09-02(중복 규칙이 DB 제약 없이 조회 후 insert), 04-09·09-01(목록 N+1), 01-02(onboarding fixture가 기동 실패 모양) |
|
||||
| 알림(notification) capability를 여러 인스턴스로 운영 | **사용 보류** | 05-01(발송 중 crash → 같은 알림 재발송), 04-02(정산 job 중복 처리) |
|
||||
| outbox relay + Kafka로 운영 | 사용 보류 | 06-01(재시도 가능한 거부를 즉시 DEAD, 같은 aggregate 뒤 이벤트까지 막힘), 06-03(broker 5분 정지로 대량 DEAD) |
|
||||
| Redis 멱등성·캐시 capability | 조건부 사용 가능 | 05-02(renew가 lease를 늘리지 못함 — 현재 호출자 없음), 05-03(revision 조건 무시) |
|
||||
| HTTP client capability | 조건부 사용 가능 | 05-05(4xx가 breaker를 연다), 05-06(전체 시간 예산이 진행 중 요청을 못 끊음) |
|
||||
| 파일 서버 capability | 조건부 사용 가능 | 05-07(copy가 디스크 수위·쿼터 우회), 05-08(소유자 검사를 지워도 테스트 통과) |
|
||||
| GraphQL 공개 | 사용 보류 | 03-01(복잡도 점수가 목록 크기를 놓침) |
|
||||
| gRPC operation ledger 채택 | 사용 보류 | 03-10(`IN_PROGRESS` 회수 없음), 03-11(설정만 있고 처리 코드 없음) |
|
||||
| 이 repo의 CI를 머지 차단 장치로 믿기 | 조건부 | 08-01(strict lane 14개를 어떤 workflow도 돌리지 않음), 05-09·08-04(MinIO 이미지 소멸로 mainCheck 빨강, main 단계가 첫 실패에서 멈춤) |
|
||||
|
||||
## 2. 차단 항목 — High와 P1 (36.5-3)
|
||||
|
||||
같은 결함을 두 영역이 적은 것은 하나로 합쳤다. "코드 확인"은 오케스트레이터가 해당 줄을 직접 읽었다는 뜻이다. "에이전트 실행"은 영역 에이전트가 worktree에서 실행해 재현했다는 뜻이다.
|
||||
|
||||
### 2.1 High (21건, 합친 뒤 19건)
|
||||
|
||||
| ID | 내용 | 재확인 |
|
||||
|---|---|---|
|
||||
| [05-01](05-outbound-capabilities.md) | 알림 attempt를 `notStarted()`(PROVEN, false)로 저장한 채 provider를 호출한다. 발송 중 워커가 죽으면 recovery가 "확실히 시작 안 함"으로 읽고 다시 큐에 넣는다 → 같은 알림 재발송 | 코드 확인: `DeliveryAttemptFactory.java:54-56` → `NotificationDispatchService.java:189-216`(갱신 없이 `submitOutsideTransaction`) → `LeaseRecoveryService.java:101-106` |
|
||||
| [04-02](04-persistence.md) | 알림 정산 job claim(`SELECT … FOR UPDATE SKIP LOCKED`)이 트랜잭션 없이 돈다. 잠금이 문장 끝에서 풀려 여러 인스턴스가 같은 job을 처리한다 | 코드 확인: `JdbcReconciliationJobStore.java:43-52,117-123`(`jdbc.query`만), `ReconciliationJobWorker.java:81`(트랜잭션 없음) |
|
||||
| [04-01](04-persistence.md) | 커밋 중 연결이 끊기면(`08*`) `DB_UNAVAILABLE`(retryable)로 답한다. 실제로는 커밋됐을 수 있어 재시도가 쓰기를 중복시킨다. ADR-JPA-003과 반대 | 코드 확인: `PersistenceExceptionTranslator.java:97-99`, `SpringTransaction.java:98-105`(커밋 단계 구분 없음) + 에이전트 실험 테스트 |
|
||||
| [06-01](06-messaging.md) | platform의 `retryable` 정보를 버리고 NOT_TRANSMITTED 거부를 `REJECTED_BEFORE_SEND`로 바꿔 즉시 DEAD. 종료 중·permit 부족도 DEAD가 되고 같은 aggregate 뒤 이벤트가 막힌다 | 코드 확인: `PlatformIntegrationEventPublishAdapter.java:140-151`, `PublishPendingOutboxEventsUseCase.java:149-153` + 에이전트 실행(`SHUTTING_DOWN retryable=true` → DEAD) |
|
||||
| [06-03](06-messaging.md) (P2) | 재시도 3회·30초 고정이라 broker가 약 5분 멈추면 대량 DEAD, 복구는 row마다 수동 SQL | 에이전트 계산(실측 없음) |
|
||||
| [05-02](05-outbound-capabilities.md) | Redis 멱등성 `renew()`가 `EXECUTING→EXECUTING` 전이라 Lua의 "이미 목표 상태" 분기에 걸려 항상 ALREADY, lease를 늘리지 않는다 | 코드 확인: `RedisIdempotencyStoreAdapter.java:183-190` + `IdempotencyScripts.java:101-108`. 현재 템플릿 안 호출자 없음(잠복) |
|
||||
| [05-03](05-outbound-capabilities.md) | 캐시 `ONLY_IF_SOURCE_REVISION_NEWER`가 `ALWAYS`로 떨어져 조건 없이 SET | 코드 확인: `RedisCacheRegionAdapter.java:262-266`(`presenceOf`는 ONLY_IF_ABSENT만 구분) |
|
||||
| [05-05](05-outbound-capabilities.md) | HTTP client: 404 같은 정상 4xx도 circuit breaker 실패로 센다 | 에이전트 코드 읽기(E1). 수정 단계에서 RED 테스트로 확인 |
|
||||
| [05-06](05-outbound-capabilities.md) | HTTP client: 전체 시간 예산이 진행 중 attempt를 끊지 못한다(소켓 read-idle만 있음) | 에이전트 코드 읽기(E1). 수정 단계에서 확인 |
|
||||
| [05-07](05-outbound-capabilities.md) | 파일 서버: copy가 디스크 수위 검사를 우회하고 쿼터는 기록만 한다 | 에이전트 코드 읽기(E1). 수정 단계에서 확인 |
|
||||
| [03-01](03-inbound-realtime-graphql-grpc.md) | GraphQL 복잡도 점수가 `first` 생략·변수 기본값·일반 list에서 하위 비용을 곱하지 않고 페이지 상한 검사도 건너뛴다(`first:20` 410점, 생략 40점) | 에이전트 실행(임시 테스트 재현) |
|
||||
| [03-10](03-inbound-realtime-graphql-grpc.md) | gRPC ledger `IN_PROGRESS` 행에 만료·회수가 없다. 소유자가 죽으면 key가 영구히 막힌다 | 코드 확인: `GrpcOperationLedgerRepository.java:76-92`(회수는 `FAILED_TERMINAL`만), `GrpcIdempotencyInterceptor.java:118-121`. 채택 전 차단(03-11) |
|
||||
| [02-01](02-inbound-web.md) | "처리 중" 응답은 `409 IDEMPOTENT_IN_FLIGHT`, `retryable=false`, `Retry-After` 없음. "같은 키로 재전송"이 백엔드 어디에도 없고 runbook·error-codes.yaml은 없는 헤더·polling을 말한다 | 에이전트 실행(`@WebMvcTest` 출력) + 문서 대조 |
|
||||
| [02-02](02-inbound-web.md) | 실제 Envelope에 `data:null`·`error:null`·`meta.page:null`이 항상 실린다. 짝 프론트 strict 스키마가 거절한다. 백엔드 `doesNotExist` 단언은 null도 통과시킨다 | 에이전트 실행(`@WebMvcTest` 출력) + 프론트 코드 읽기 |
|
||||
| [02-03](02-inbound-web.md) + [07-05](07-bootstrap-composition-config.md) | JWT audience가 비면(템플릿 기본값) 검증을 건너뛴다. env 레지스트리는 `required: true`. role은 모든 client의 `resource_access`에서 합친다 | 코드 확인: `SecuritySettings.java:35-42` |
|
||||
| [07-01](07-bootstrap-composition-config.md) | 자체 `Tracer`에 span processor·exporter가 없어 OTLP endpoint를 넣어도 아무것도 나가지 않는다 | 코드 확인: `TracingConfig.java:66-91`(`SdkTracerProvider`에 sampler만) + 에이전트 실행(exporter 0개) |
|
||||
| [07-02](07-bootstrap-composition-config.md) | prod 기동 검사(TLS·Flyway)가 `afterSingletonsInstantiated`에서 돌아 DB 연결·마이그레이션이 먼저 실행된다 | 코드 확인: `StartupRuleRunner.java:35`. PostgreSQL 실측 없음 |
|
||||
| [07-03](07-bootstrap-composition-config.md) + [09-03](09-performance-measurement.md) | 샘플이 `WebSecurityAutoConfiguration`을 통째로 빼면서 `MethodSecurityConfig`도 빠졌다. `@RequiresPermission`이 동작하지 않아 익명 삭제 가능, owner가 null이라 `POST /api/worklogs`는 항상 500 | 코드 확인: `SamplePortfolioApplication.java:31`, `WebSecurityAutoConfiguration.java:41-49` + 에이전트 실행(`java -jar`로 500 재현) |
|
||||
| [09-02](09-performance-measurement.md) | 포스터 제목 중복 규칙이 DB 유일 제약 없이 "조회 후 insert". 같은 제목 16개 동시 요청 3회 모두 10행씩 들어감. 검사 쿼리는 순차 스캔 | 에이전트 실행(동시 요청 실측) |
|
||||
| [08-01](08-build-ci-test.md) + [04-04](04-persistence.md) + [03-12](03-inbound-realtime-graphql-grpc.md) | CI가 한 번도 돌리지 않는 strict lane 14개(JPA 실 PostgreSQL 11, web 부하·종료 2, sample 전체 기동 1). `integration-main.yml:96`은 `integrationCheck --dry-run`만 한다. persistence-fileserver는 자기 테스트가 0개 | 에이전트 `--dry-run` 그래프와 workflow 15개 대조. 04 영역이 그중 4 lane을 직접 돌려 44건 통과 |
|
||||
|
||||
### 2.2 P1 (High 제외)
|
||||
|
||||
| ID | 심각도 | 내용 | 재확인 |
|
||||
|---|---|---|---|
|
||||
| [05-09](05-outbound-capabilities.md) + [08-04](08-build-ci-test.md) | Medium | MinIO 이미지(`minio/minio@sha256:4c4a48…`)를 받을 수 없어 mainCheck가 빨갛다. 이미지 참조가 네 곳에 복사돼 있고 main 단계는 `--continue` 없이 돌아 다른 lane 결과를 가린다 | 오케스트레이터 실행: Docker Hub `minio/minio` pull 거부, `alpine:3`는 성공, `quay.io/minio/minio`도 해당 digest·태그 없음 |
|
||||
| [04-03](04-persistence.md) | Medium | JPA 양방향 연관관계 금지(사용자 원칙)를 막는 장치가 없고 `docs/jpa/entity-mapping-guide.md:50-57`과 testFixtures 예제는 `mappedBy` 양방향을 가르친다. 운영 엔티티 28개는 지금 연관관계 0개 | 에이전트 전수 확인 |
|
||||
| [05-08](05-outbound-capabilities.md) | Medium | 파일 서버 copy·download의 소유자 검사를 지워도 442개 테스트가 전부 통과(소유자 결정 14의 회귀 방지 없음) | 에이전트 변이 실험 |
|
||||
| [06-02](06-messaging.md) | Medium | platform 종료 순서가 앱 outbox relay를 모른다 | 에이전트 코드 읽기 |
|
||||
|
||||
## 3. 확인된 강점 (36.5-2)
|
||||
|
||||
- **PR 게이트가 녹색이다.** `ci` rc=0(434초). leaf check(compile·test·Spotless·Checkstyle·Error Prone) 전체, `architectureCheck`(의존 방향·순수성·ArchUnit 181건), `qualityCheck`(SpotBugs·FindSecBugs)가 통과했다.
|
||||
- **지난 리뷰의 High/P1이 모두 닫혔다.** 9개 영역 모두 "남은 High/P1 없음"으로 재확인했다. 남은 것은 문서·테스트 규칙(W4·W5) 성격이다.
|
||||
- **JPA 엔티티는 사용자 원칙을 지킨다.** 운영 엔티티 28개에 연관관계 매핑이 하나도 없다(04 영역). 막는 장치만 없다(04-03).
|
||||
- **실 PostgreSQL lane은 돌리면 통과한다.** JPA 4 lane 44건(04), gRPC ledger 18건(03). 문제는 CI가 돌리지 않는다는 것(08-01)이다.
|
||||
- **테스트가 빠르다.** 테스트 결과 XML 984개 합계 약 208초, 가장 느린 클래스 9.3초(08 영역). ci 434초의 병목은 테스트 실행이 아니다.
|
||||
- **기본 조합이 가볍다.** bootJar 41.4 MB, 기동 중앙값 3.44초, 빈 407개. 필터 체인만 지나는 요청 27k rps(09 영역).
|
||||
- **변이 실험 대부분을 테스트가 잡는다.** strict lane 장치 3/3, GraphQL 구조 상한·STOMP destination, outbox offset 검사 등. 잡지 못한 것은 각 발견으로 적었다(05-08, 06-05, 01-03, 02-09).
|
||||
|
||||
## 4. 반복되는 원인 (36.5-4)
|
||||
|
||||
1. **결과 불명을 "확실함"으로 기록한다.** 05-01(시작 안 함 PROVEN으로 저장 후 호출), 04-01(커밋 중 끊김을 재시도 가능으로), 06-01(재시도 가능 거부를 확정 거부로), 05-17(Redis 연결 실패를 결과 불명으로 — 반대 방향). 결과 불명 처리를 정한 문서(ADR-JPA-003, 알림 evidence 모델)는 있지만 경계마다 다시 구현되며 갈라졌다.
|
||||
2. **중복·경쟁을 DB가 아니라 코드 순서로 막는다.** 09-02(조회 후 insert), 04-08(upsert), 04-02(트랜잭션 없는 SKIP LOCKED), 03-10(lease 없는 claim). 가이드 31절 "DB 유일성 제약과 충돌 처리가 충분한지 먼저 본다"에 해당한다.
|
||||
3. **샘플이 운영 경로와 다르게 조립된다.** 07-03·09-03(보안 자동 설정 통째 제외), 09-08(런타임 기본값 다름), 07-04(`Dockerfile.sample` 빌드 실패), 07-09·01-01(따라 할 예시가 세 갈래). 매뉴얼 재료가 될 예시가 실제로는 실행되지 않는다.
|
||||
4. **설정·이미지 참조·식별자 규칙이 여러 벌이다.** `TenantId` 3벌(01-03), 이벤트 ID 문법 5곳(01-07), SQLState 분류표 2벌(04-06), MinIO 이미지 참조 4곳(05-09), 로그 설정 2곳(07-06). 사용자 원칙 "갈라진 중복 복사본은 결함"에 정면으로 걸린다.
|
||||
5. **선언과 실행이 떨어져 있다.** strict lane을 선언하고 돌리지 않는다(08-01), 설정 키는 바인딩되지만 동작하지 않는다(05-15, 03-11), 레지스트리는 `required`인데 코드는 빈 값을 허용한다(02-03).
|
||||
|
||||
## 5. 결정이 필요한 것
|
||||
|
||||
> 2026-11-01 22:00 소유자 결정: 아래 다섯 항목 모두 권장안으로 정했다. 05-09의 대체 이미지 선택만 보류(이미지 참조 한 곳·pull 실패 메시지 구분·main 단계 `--continue`까지 진행).
|
||||
|
||||
| 항목 | 선택지 | 권고 | 승인자 |
|
||||
|---|---|---|---|
|
||||
| 02-01 처리 중 409 | (A) `retryable=true` + `Retry-After` + 계약 문서 고정 (B) `retryable=false` 유지, 문서만 (C) executor가 잠시 대기 후 replay (D) 키 조회 엔드포인트 | (A). 같은 키 재전송은 서버가 replay·in-flight·422로 안전하게 판정한다. 짝 프론트 분류기와 같이 바꾼다 | 템플릿 소유자(두 repo) |
|
||||
| 02-02 Envelope null 필드 | (A) 백엔드가 `@JsonInclude(NON_NULL)`로 생략 (B) 프론트 strict 완화 | (A). 프론트의 "unknown field 거절" 방어를 유지한다 | 템플릿 소유자(두 repo) |
|
||||
| 02-03 JWT audience·role 범위 | (A) audience 필수 + 자기 client role만 (B) prod에서만 필수 (C) 문서만 | (A). 기존 배포는 env 하나를 채워야 한다(호환성 깨짐) | 템플릿 소유자 |
|
||||
| 05-09 MinIO 이미지 공급원 | (a) 조직 레지스트리 미러 (b) 다른 공식 레지스트리 (c) 커뮤니티 재배포 이미지 (d) 다른 S3 구현 (e) lane 제외 | 원본 digest를 가진 곳이 없고(로컬·quay.io 모두 없음) 조직 레지스트리도 없어 (a)(b)는 지금 불가. 단기: 이미지 참조를 한 곳으로 모으고 pull 실패를 별도 메시지로 구분, 대체 이미지는 소유자가 고른다 | 템플릿 소유자 |
|
||||
| 07-01 트레이싱 | (A) 자체 Tracer를 지우고 Boot 4 tracing·OTLP 모듈로 (B) 자체 Tracer에 exporter 직접 연결 (C) 트레이싱 범위 제거 | (A) | 템플릿 소유자 |
|
||||
|
||||
## 6. 미검증 (36.5-5)
|
||||
|
||||
| 무엇 | 왜 | 확인하려면 |
|
||||
|---|---|---|
|
||||
| GitHub Actions 실제 실행 결과 | 원격이 `git.learn.hyeonworks.com`이고 외부 조회를 하지 않았다 | runner 결과 |
|
||||
| 미실행 strict lane 14개 중 10개의 현재 통과 여부 | 04 영역이 4 lane만 돌렸다 | `integrationCheck` 실행 |
|
||||
| MinIO 계약·fault lane | 이미지를 받을 수 없다 | 5절 결정 후 |
|
||||
| 실제 다중 인스턴스 경쟁(05-01, 04-02, 06-01) | 코드 경로와 단위 실험만 했다 | 2개 인스턴스 + 실 DB 통합 테스트(수정 단계 RED 테스트로 일부 대체) |
|
||||
| Redis·Toxiproxy·SES/SMTP·Kafka 실연 | 외부 서비스·컨테이너 lane을 돌리지 않았다 | 해당 lane |
|
||||
| 실제 SIGTERM 종료 순서(06-02, 07-07) | 측정하지 않았다 | 컨테이너에서 종료 실측 |
|
||||
| 실제 `docker build` | Dockerfile COPY 집합만 재현했다(`Dockerfile.sample` 실패) | 빌드 실행 |
|
||||
| 짝 프론트와의 결합 실행(02-01, 02-02) | 프론트는 코드만 읽었다 | 두 템플릿 통합 환경 |
|
||||
|
||||
## 7. 개선 순서 (36.5-6)
|
||||
|
||||
| 순서 | 대상 | 이유 | 완료 기준 |
|
||||
|---|---|---|---|
|
||||
| 1 | 05-01, 04-02, 04-01, 06-01, 05-02, 05-03, 05-05, 05-06, 05-07, 03-01, 03-10, 07-02, 07-03+09-03, 09-02 | High·P1 중 결정이 필요 없는 코드 결함. 각각 막는 테스트를 먼저 넣는다 | 각 영역 문서의 완료 기준. 수정 전 실패하는 테스트가 있어야 한다 |
|
||||
| 2 | 02-01, 02-02, 02-03+07-05, 07-01, 05-09+08-04 | 5절 결정 후 | 결정 내용대로 |
|
||||
| 3 | 08-01+04-04+03-12, 04-03, 05-08, 06-02, 06-03 | CI·회귀 방지 장치와 P1 Medium | lane이 workflow에서 돌고, 금지 규칙이 ArchUnit으로 막고, 변이가 잡힌다 |
|
||||
| 4 | 01-01, 01-02, 07-09, 01-05, 01-03, 01-07, 04-06 | 개발 매뉴얼(`docs/manual/`)과 기능 생성 명령의 재료. 예시 하나, 규칙 한 벌 | 생성 명령으로 만든 기능이 모든 게이트를 통과 |
|
||||
| 5 | 나머지 P2·P3 | 영역별 | 각 영역 문서 |
|
||||
|
||||
## 8. 재검토 조건 (36.5-7)
|
||||
|
||||
- 개선 순서 1·2가 끝나면 해당 영역만 다시 본다.
|
||||
- 개발 매뉴얼과 기능 생성 명령이 생기면 01·07 영역을 그 명령으로 만든 기능 기준으로 다시 본다.
|
||||
- MinIO 대체 공급원이 정해지면 objectstorage 벤더 증거를 다시 측정한다.
|
||||
- gRPC ledger나 Redis 멱등성 renew를 실제로 쓰는 경로가 생기면 03·05 영역을 다시 본다.
|
||||
|
||||
## 9. 리뷰 범위 (36.1)
|
||||
|
||||
- 기준 커밋 `01a8a2a70`. 게이트는 오케스트레이터가 한 번 실행했다(프론트 세션과 공유 잠금).
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하 |
|
||||
|---|---|---|---|
|
||||
| `ci` | rc=0 | 434초(잠금 대기 포함) | load 9.15 |
|
||||
| `mainCheck` | rc=1 — `objectStorageMinioContractTest`, `objectStorageMinioFaultTest`만 실패(이미지 pull 404). `sampleWebContractCheck`, sample `webSystemTest`, `verifyEnvKeys`, app-bootstrap `systemTest` 통과 | 162초 | load 20.68 |
|
||||
|
||||
- 영역 9개와 담당 leaf:
|
||||
|
||||
| 영역 | 범위 |
|
||||
|---|---|
|
||||
| [01](01-core-and-feature-pattern.md) core·기능 패턴 | `domain-core`, `shared-contract`, `application-core` + repo 전체 폴더 구조·리팩토링·새 기능 흐름 |
|
||||
| [02](02-inbound-web.md) inbound web | `adapter:inbound:web*`, `composition:idempotency` HTTP 계약 |
|
||||
| [03](03-inbound-realtime-graphql-grpc.md) realtime·graphql·grpc | `websocket`, `graphql`, `grpc` 어댑터 + `grpc:*`, `grpc-advanced:*` |
|
||||
| [04](04-persistence.md) persistence | `persistence-jpa`, `-mongo`, `-fileserver`, `-notification`, 마이그레이션 |
|
||||
| [05](05-outbound-capabilities.md) outbound capability | redis·cache·httpclient·objectstorage·notification·fileserver·identifier·support + `application-*` capability, composition |
|
||||
| [06](06-messaging.md) messaging | `messaging:*`, `adapter:outbound:messaging(-kafka)`, `composition:outbox-relay` |
|
||||
| [07](07-bootstrap-composition-config.md) bootstrap·설정 | `app-bootstrap`, `composition:service-runtime`, `sample-portfolio`, env 계약, Dockerfile, compose |
|
||||
| [08](08-build-ci-test.md) build·CI·테스트 | `build-logic`, settings, 루트 lifecycle, workflow 15개, 테스트 lane, 테스트 실행 시간 |
|
||||
| [09](09-performance-measurement.md) 성능 실측 | 기동·jar·SQL 수·처리량·JFR |
|
||||
|
||||
## 10. 이번 라운드 추가 렌즈 요약
|
||||
|
||||
- **성능(09).** bootJar 기본 41.4 MB / 샘플 99.0 MB. 기동 중앙값 3.44초(빈 407) / 8.05초(빈 603). 요청당 SQL: 목록 20건 46개, 100건 206개, 단건 7개, 제목만 바꾸는 PATCH 13개. 처리량: 단건 5,521 rps, 목록 20건 829 rps. `default_batch_fetch_size=100`만으로 목록 2.9배. 관측 기능 비용 약 3%, 가상 스레드는 차이 없음.
|
||||
- **테스트 성능(08).** 테스트 시간 합 약 208초. strict lane의 `upToDateWhen(false)`가 build cache 적재까지 막아 PR마다 약 77초가 매번 다시 돈다(08-02). PR `test`에 저장소 문서를 읽는 클래스 15개(08-03).
|
||||
- **폴더 구조·기능 패턴(01·07).** 새 기능을 두는 모양이 세 가지(core 안, `application-*` capability, sample 수직)이고 고르는 기준이 없다(01-01). 따라 할 예시도 세 갈래(07-09). 01 영역 문서 7절에 "새 도메인 하나 추가" 단계별 틀·빠진 것·판단 지점과 생성 명령 후보 목록이 있다 — 매뉴얼 재료.
|
||||
- **리팩토링 후보.** 각 영역 문서 6절. 공통: 식별자 문법·SQLState 표·이미지 참조를 한 곳으로(4절 원인 4).
|
||||
|
||||
## 11. 28개 관점 판정 (36.2)
|
||||
|
||||
영역별 기호: O 충족 · P 부분 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 종합은 평균하지 않는다. 한 영역이라도 X면 X다(35.7절).
|
||||
|
||||
| 관점 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 종합 |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 1 코드 성숙도 | O | P | P | P | P | P | P | O | > | P |
|
||||
| 2 구조적 성숙도 | P | O | P | P | O | P | P | O | > | P |
|
||||
| 3 변경 용이성 | P | P | P | P | P | P | P | P | P | P |
|
||||
| 4 인지 부하 | P | P | P | P | P | P | P | P | P | P |
|
||||
| 5 위험 가시성 | P | X | X | X | P | P | X | P | X | **X** |
|
||||
| 6 실패 성숙도 | P | P | P | X | P | X | P | P | P | **X** |
|
||||
| 7 운영 성숙도 | > | P | P | P | P | P | P | > | P | P |
|
||||
| 8 디버깅 가능성 | P | O | P | P | P | P | P | P | O | P |
|
||||
| 9 유지보수 성숙도 | P | P | P | P | P | P | P | P | P | P |
|
||||
| 10 테스트 성숙도 | P | P | P | P | P | P | P | P | X | **X** |
|
||||
| 11 데이터 성숙도 | P | - | P | P | P | P | > | > | X | **X** |
|
||||
| 12 동시성 성숙도 | P | P | P | P | P | P | P | - | X | **X** |
|
||||
| 13 확장성 | - | ? | X | P | ? | P | ? | P | P | **X** |
|
||||
| 14 성능 성숙도 | O | ? | P | P | P | ? | P | P | P | P |
|
||||
| 15 보안 성숙도 | P | X | P | O | P | O | P | P | > | **X** |
|
||||
| 16 의존성 성숙도 | O | O | O | O | P | P | P | P | P | P |
|
||||
| 17 API·계약 성숙도 | P | X | P | P | P | P | > | O | P | **X** |
|
||||
| 18 배포 성숙도 | > | > | P | ? | > | X | P | > | > | **X** |
|
||||
| 19 설정 성숙도 | - | P | P | P | P | P | P | O | P | P |
|
||||
| 20 개발자 경험 | X | P | P | P | P | P | P | P | P | **X** |
|
||||
| 21 Guardrail | P | P | P | P | P | P | P | P | P | P |
|
||||
| 22 추상화 성숙도 | P | O | P | P | P | P | O | O | - | P |
|
||||
| 23 일관성 | X | P | P | P | P | P | P | P | P | **X** |
|
||||
| 24 네이밍·의미 | P | P | P | P | P | P | P | P | - | P |
|
||||
| 25 조직 확장성 | P | P | - | P | ? | P | ? | P | - | P |
|
||||
| 26 Ownership | P | P | P | P | P | P | P | ? | - | P |
|
||||
| 27 삭제 가능성 | P | O | O | O | P | O | P | P | - | P |
|
||||
| 28 회복 가능성 | > | P | X | P | P | X | - | P | ? | **X** |
|
||||
|
||||
미충족(X)의 이유:
|
||||
- 5 위험 가시성 — 02-03(레지스트리 required, 코드는 빈 값 허용), 03-01, 04-01, 07-03, 09-03: 위험이 기본값·설정 뒤에 숨어 있다.
|
||||
- 6 실패 성숙도 — 04-01(커밋 중 끊김 오분류), 06-01·06-03(재시도 가능 실패를 DEAD로).
|
||||
- 10 테스트 성숙도 — 09 영역: 대표 쓰기 500·동시 중복을 테스트가 잡지 못한다. 05-08 변이 생존.
|
||||
- 11 데이터 성숙도 — 09-02: 중복 규칙에 DB 제약 없음.
|
||||
- 12 동시성 성숙도 — 09-02, 04-02(트랜잭션 없는 SKIP LOCKED).
|
||||
- 13 확장성 — 03-06·03-09: WebSocket·gRPC 연결·동시 호출 상한 없음.
|
||||
- 15 보안 성숙도 — 02-03(audience 기본 꺼짐, 타 client role 합침).
|
||||
- 17 API·계약 — 02-01, 02-02: 짝 프론트와 wire 계약 불일치.
|
||||
- 18 배포 성숙도 — 06 영역: 종료 순서가 relay를 모름(06-02), broker 실연 lane 없음(06-09).
|
||||
- 20 개발자 경험·23 일관성 — 01 영역: 새 기능 모양 세 갈래(01-01), 식별자·이름 규칙 여러 벌(01-03, 01-07, 01-12).
|
||||
- 28 회복 가능성 — 03-10(ledger 영구 잠김), 06-03(DEAD 복구 수작업).
|
||||
|
||||
## 12. 발견 색인
|
||||
|
||||
영역 문서에 36.3 양식으로 적힌 발견 **124건**: High 21 · Medium 67 · Low 36, P1 25 · P2 60 · P3 39.
|
||||
|
||||
> **정정 (2026-11-03 재리뷰)**: 처음 이 색인은 119건이었다. 06 영역 문서가 `NN-` 접두사로 쓰여 있었는데 오케스트레이터가 `NN-0x`만 `06-0x`로 바꿔 `NN-10`~`NN-14` 5건이 색인과 모든 수정 묶음에서 빠졌다. 13~16절의 "모든 발견 처리"는 이 5건에 대해 틀렸다. 5건은 `06-10`~`06-14`로 다시 매겨 아래 표에 넣었고, 재리뷰 수정(`../2026-11-03-rereview/README.md` 6절)에서 고쳤다. Critical 0. 두 영역이 같은 결함을 적은 묶음(07-03+09-03, 02-03+07-05, 08-01+04-04+03-12, 05-09+08-04, 04-09+09-01)은 색인에 각각 남기고 2절에서 합쳤다. 06·08 영역 문서는 원래 `NN-` 접두사로 적혀 있어 `06-`·`08-`로 바꿨다.
|
||||
|
||||
| ID | 심각도 | 우선순위 | 내용 |
|
||||
|---|---|---|---|
|
||||
| [02-01](02-inbound-web.md) | High | P1 | "처리 중" 409의 클라이언트 행동이 코드·문서·짝 계약에서 서로 다르다 |
|
||||
| [02-02](02-inbound-web.md) | High | P1 | 실제 Envelope JSON이 `data:null`·`error:null`·`meta.page`를 싣는데 짝 프론트 계약은 이를 거절한다 |
|
||||
| [02-03](02-inbound-web.md) | High | P1 | JWT audience 검증이 기본으로 꺼져 있고, 모든 client의 role을 합친다 |
|
||||
| [03-01](03-inbound-realtime-graphql-grpc.md) | High | P1 | GraphQL 복잡도 점수가 목록 크기를 놓친다 — 페이지 인자 생략·변수 기본값·일반 list 필드 |
|
||||
| [03-10](03-inbound-realtime-graphql-grpc.md) | High | P1 | operation ledger의 `IN_PROGRESS` claim에 만료·회수가 없다 — 소유자가 죽으면 그 key는 영구히 막힌다 |
|
||||
| [04-01](04-persistence.md) | High | P1 | 커밋 중 연결이 끊기면 "재시도 가능(DB_UNAVAILABLE)"으로 답한다 |
|
||||
| [04-02](04-persistence.md) | High | P1 | 다중 인스턴스에서 알림 정산 job이 중복 처리된다 |
|
||||
| [05-01](05-outbound-capabilities.md) | High | P1 | 알림 attempt를 "요청 시작 안 함(확정)"으로 저장한 채 provider를 호출한다 — 워커가 발송 중 죽으면 같은 알림이 다시 나간다 |
|
||||
| [05-02](05-outbound-capabilities.md) | High | P1 | Redis 멱등성 `renew()`가 처리 lease를 연장하지 못한다 |
|
||||
| [05-03](05-outbound-capabilities.md) | High | P1 | 캐시 `ONLY_IF_SOURCE_REVISION_NEWER`가 조건 없이 덮어쓴다 |
|
||||
| [05-05](05-outbound-capabilities.md) | High | P1 | HTTP client: 4xx 응답이 circuit breaker 실패로 집계된다 |
|
||||
| [05-06](05-outbound-capabilities.md) | High | P1 | HTTP client: 전체 시간 예산이 진행 중인 attempt를 끊지 못한다 |
|
||||
| [05-07](05-outbound-capabilities.md) | High | P1 | 파일 서버: copy가 디스크 수위 검사를 우회하고, 쿼터는 기록만 한다 |
|
||||
| [06-01](06-messaging.md) | High | P1 | 다시 시도하면 될 거부를 relay가 즉시 DEAD로 보낸다 |
|
||||
| [07-01](07-bootstrap-composition-config.md) | High | P1 | 트레이스가 어디로도 나가지 않는다 — OTLP endpoint를 설정해도 span을 만들지도 보내지도 않는다 |
|
||||
| [07-02](07-bootstrap-composition-config.md) | High | P1 | prod 기동 검사가 DB 연결과 Flyway 마이그레이션이 끝난 뒤에 돈다 |
|
||||
| [07-03](07-bootstrap-composition-config.md) | High | P1 | 실행 중인 샘플에서는 `@RequiresPermission`이 아무 일도 하지 않는다 — 익명 삭제 가능, 생성은 500 |
|
||||
| [08-01](08-build-ci-test.md) | High | P1 | CI가 실행하지 않는 strict lane 14개 |
|
||||
| [09-02](09-performance-measurement.md) | High | P1 | 포스터 제목 중복 규칙이 동시 요청에서 깨지고, 검사 쿼리가 순차 스캔 |
|
||||
| [09-03](09-performance-measurement.md) | High | P1 | 단독 실행한 샘플에서 대표 쓰기 `POST /api/worklogs`가 항상 500 |
|
||||
| [06-03](06-messaging.md) | High | P2 | broker가 몇 분만 멈춰도 row가 대량으로 DEAD가 되고 복구는 수작업이다 |
|
||||
| [04-03](04-persistence.md) | Medium | P1 | JPA 연관관계 원칙(양방향 금지)을 막는 장치가 없고, 템플릿 문서와 fixture는 반대로 가르친다 |
|
||||
| [04-04](04-persistence.md) | Medium | P1 | 실 PostgreSQL lane 9개(57개 테스트)가 어떤 게이트·workflow에서도 돌지 않는다. persistence-fileserver는 자기 테스트가 0개다 |
|
||||
| [05-08](05-outbound-capabilities.md) | Medium | P1 | 파일 서버: 소유자 검사를 지워도 테스트가 하나도 실패하지 않는다 |
|
||||
| [05-09](05-outbound-capabilities.md) | Medium | P1 | 객체 저장소: MinIO 이미지 공급원이 사라져 mainCheck가 빨갛다 |
|
||||
| [06-02](06-messaging.md) | Medium | P1 | platform 종료 순서가 앱 relay를 모른다 |
|
||||
| [01-01](01-core-and-feature-pattern.md) | Medium | P2 | 새 기능을 어느 leaf에 두는지 세 가지 모양이 있고, 고르는 기준이 없다 |
|
||||
| [01-02](01-core-and-feature-pattern.md) | Medium | P2 | onboarding fixture가 "새 기능의 계약 모양"으로 박아 둔 유스케이스가 실제로는 기동에 실패하는 모양이다 |
|
||||
| [01-03](01-core-and-feature-pattern.md) | Medium | P2 | `TenantId`가 3벌이고 받아들이는 문법이 셋 다 다르다 |
|
||||
| [01-04](01-core-and-feature-pattern.md) | Medium | P2 | `IllegalArgumentException` 하나가 "입력이 틀렸다"와 "서버 조립이 틀렸다"를 함께 뜻하고, web은 둘 다 로그 없이 400으로 바꾼다 |
|
||||
| [01-05](01-core-and-feature-pattern.md) | Medium | P2 | application-core가 소유한 포트 중 절반이 "fake와 실제 adapter가 같은 계약 테스트를 통과한다"는 규칙 밖에 있다 |
|
||||
| [02-04](02-inbound-web.md) | Medium | P2 | rate-limit 거부 본문이 실제 Tomcat에서 ISO-8859-1로 나가 한국어 문구가 깨진다 |
|
||||
| [02-05](02-inbound-web.md) | Medium | P2 | CORS에 노출 헤더가 없어 브라우저가 계약 헤더를 못 읽는다 |
|
||||
| [02-06](02-inbound-web.md) | Medium | P2 | `String`을 반환하는 컨트롤러는 `Accept: application/json`에서 500이 된다 |
|
||||
| [02-07](02-inbound-web.md) | Medium | P2 | web-advanced 예외 10종이 문서의 상태 대신 500으로 나간다 |
|
||||
| [03-02](03-inbound-realtime-graphql-grpc.md) | Medium | P2 | GraphQL 요청 deadline(10초)이 실행 중에는 강제되지 않는다 |
|
||||
| [03-03](03-inbound-realtime-graphql-grpc.md) | Medium | P2 | N+1을 막는 길이 adopter 기억에만 있다 |
|
||||
| [03-06](03-inbound-realtime-graphql-grpc.md) | Medium | P2 | WebSocket 연결 수·구독 수·연결 수명 상한이 없고, STOMP 전송 한도가 코드에 드러나지 않는다 |
|
||||
| [03-07](03-inbound-realtime-graphql-grpc.md) | Medium | P2 | `SerializedOutboundWriter`의 offer와 close가 겹치면 노드 버퍼 예산이 영구히 샌다 |
|
||||
| [03-08](03-inbound-realtime-graphql-grpc.md) | Medium | P2 | `PlatformWebSocketHandler.stop()` 뒤에 들어온 연결은 1001을 받지 못한다 |
|
||||
| [03-09](03-inbound-realtime-graphql-grpc.md) | Medium | P2 | gRPC 어댑터 서버가 io.grpc 기본값으로 뜬다 — deadline·동시 호출·executor·메시지 크기 상한이 없고, 플랫폼 한도는 testkit 서버에만 적용된다 |
|
||||
| [03-11](03-inbound-realtime-graphql-grpc.md) | Medium | P2 | `app.grpc.platform.operation-ledger-enabled`는 검증만 통과시키고 실제로 key를 처리하는 코드가 없다 |
|
||||
| [04-05](04-persistence.md) | Medium | P2 | `@Version` 충돌이 변환되지 않고 500 INTERNAL_ERROR로 나간다 |
|
||||
| [04-06](04-persistence.md) | Medium | P2 | SQLState 분류표가 두 벌이고 이미 갈라졌다 |
|
||||
| [04-07](04-persistence.md) | Medium | P2 | bulk UPDATE가 `@Version`을 올리지 않는다 |
|
||||
| [04-08](04-persistence.md) | Medium | P2 | upsert가 "찾고 없으면 넣기"라 동시 요청에서 깨진다 |
|
||||
| [04-09](04-persistence.md) | Medium | P2 | sample 목록 조회가 N+1이다(페이지당 최대 202쿼리) |
|
||||
| [04-10](04-persistence.md) | Medium | P2 | 기본 쓰기·읽기 트랜잭션에 시간 제한이 없다 |
|
||||
| [04-11](04-persistence.md) | Medium | P2 | Mongo 트랜잭션 본문의 일시 오류가 재시도되지 않는다 |
|
||||
| [04-12](04-persistence.md) | Medium | P2 | Mongo 기본 경로(URI만 준 배포)에 timeout·pool 제한이 없다 |
|
||||
| [04-13](04-persistence.md) | Medium | P2 | persistence adapter가 정책을 소유하고, claim 토큰을 프로세스 메모리에 둔다 |
|
||||
| [04-14](04-persistence.md) | Medium | P2 | notification·fileserver 영속 leaf가 테스트 규칙(공유 계약)을 따르지 않는다 |
|
||||
| [04-15](04-persistence.md) | Medium | P2 | Mongo 라이브러리를 파생 서비스가 쓸 경로와 예시가 없다 |
|
||||
| [05-04](05-outbound-capabilities.md) | Medium | P2 | 캐시 무효화와 느린 loader의 경합, stampede 보호 없음, 문서는 jitter를 주장 |
|
||||
| [05-10](05-outbound-capabilities.md) | Medium | P2 | 알림: collapse 미지원 예외가 try 밖에서 터져 끝없이 재시도된다 |
|
||||
| [05-11](05-outbound-capabilities.md) | Medium | P2 | 알림: SMTP 실패가 전부 "결과 불명"이 되어 재시도 없이 운영자 대기로 멈춘다 |
|
||||
| [05-12](05-outbound-capabilities.md) | Medium | P2 | 파일 서버: tus PATCH가 쓰기를 커밋한 뒤 `file:read`를 요구한다 |
|
||||
| [05-13](05-outbound-capabilities.md) | Medium | P2 | 파일 서버: 정리 worker가 기본으로 꺼져 있다 |
|
||||
| [05-14](05-outbound-capabilities.md) | Medium | P2 | HTTP client: 기본 설정에서 결과 불명 분류가 틀린 경로로 나간다 |
|
||||
| [05-15](05-outbound-capabilities.md) | Medium | P2 | HTTP client: 바인딩되지만 동작하지 않는 설정 키, 0 timeout 허용 |
|
||||
| [05-16](05-outbound-capabilities.md) | Medium | P2 | capability 완료 기준 5가 영역 전체에서 지켜지지 않는다 |
|
||||
| [05-17](05-outbound-capabilities.md) | Medium | P2 | Redis: 연결 실패를 "결과 불명"으로 보고하고, 시간 초과된 연결을 pool에 돌려준다 |
|
||||
| [05-20](05-outbound-capabilities.md) | Medium | P2 | SES 콜백: replay 창 5분이 장애 뒤 SNS 재전송을 버린다 |
|
||||
| [06-04](06-messaging.md) | Medium | P2 | aggregate 하나의 발행 속도가 poll 주기당 1건으로 묶인다 |
|
||||
| [06-05](06-messaging.md) | Medium | P2 | relay가 꺼져 있거나 실패하는 동안 outbox 지표가 갱신되지 않는다 |
|
||||
| [06-06](06-messaging.md) | Medium | P2 | application EventId 문법과 platform MessageId(UUID)가 다르다 |
|
||||
| [06-07](06-messaging.md) | Medium | P2 | 샘플이 aggregate 순서 번호를 벽시계로 만든다 |
|
||||
| [06-08](06-messaging.md) | Medium | P2 | 소비(consume)를 지원한다는 결정이 application 쪽 경로로 이어지지 않는다 |
|
||||
| [06-09](06-messaging.md) | Medium | P2 | 실제로 쓰는 발행 경로에는 broker 실연 테스트가 없고, broker 실연 lane은 어떤 기본 게이트에도 없다 |
|
||||
| [07-04](07-bootstrap-composition-config.md) | Medium | P2 | `Dockerfile.sample`은 빌드되지 않는다 |
|
||||
| [07-05](07-bootstrap-composition-config.md) | Medium | P2 | prod에서 JWT audience를 비워도 기동하고, 경고도 없이 audience 검사를 끈다 |
|
||||
| [07-06](07-bootstrap-composition-config.md) | Medium | P2 | 로그 설정이 두 군데에서 읽힌다 — `LoggingSettings`는 아무도 쓰지 않고, logback은 env 키를 직접 읽는다 |
|
||||
| [07-07](07-bootstrap-composition-config.md) | Medium | P2 | 종료 시간 예산표에 async executor 대기 19초가 빠져 있다 |
|
||||
| [07-08](07-bootstrap-composition-config.md) | Medium | P2 | 기본 조립 루트가 아직 선택 capability를 안다 (capability 기준 7 위반) |
|
||||
| [07-09](07-bootstrap-composition-config.md) | Medium | P2 | 새 기능을 만들 때 따라 할 예시가 세 갈래다 |
|
||||
| [08-02](08-build-ci-test.md) | Medium | P2 | strict lane은 build cache도 쓰지 않아서 바뀐 것이 없어도 매번 다시 돈다 |
|
||||
| [08-03](08-build-ci-test.md) | Medium | P2 | app-bootstrap의 PR 테스트가 저장소 문서를 읽고, 저장소 전체를 입력으로 잡는다 |
|
||||
| [08-04](08-build-ci-test.md) | Medium | P2 | 외부 컨테이너 이미지가 사라지면 main 단계가 통째로 멈춘다 |
|
||||
| [09-01](09-performance-measurement.md) | Medium | P2 | 샘플 목록 API가 N+1 — 페이지 20건에 SQL 46개 |
|
||||
| [09-04](09-performance-measurement.md) | Medium | P2 | 단독 실행한 샘플에서 `/api/v3/api-docs`가 500 |
|
||||
| [09-06](09-performance-measurement.md) | Medium | P2 | 제목 하나 고치는 PATCH가 컬렉션 테이블을 전부 지우고 다시 넣음 |
|
||||
| [09-07](09-performance-measurement.md) | Medium | P2 | JDBC batch 기본 꺼짐 + 동기 `batchCreate` 1000건을 한 트랜잭션에서 처리 |
|
||||
| [01-06](01-core-and-feature-pattern.md) | Medium | P3 | `@RequiresPermission`은 application 계약인데, 검사는 web leaf가 켜 주는 AOP에만 있다 |
|
||||
| [01-08](01-core-and-feature-pattern.md) | Medium | P3 | 장기 실행 작업(LRO) 공개 계약이 두 벌이다 |
|
||||
| [01-09](01-core-and-feature-pattern.md) | Medium | P3 | 통합 이벤트를 만드는 규칙(tenant 범위·순서·correlation)을 기능마다 다시 정한다 |
|
||||
| [02-08](02-inbound-web.md) | Low | P2 | Spring MVC 예외의 상태→코드 변환이 의미를 잃는다 |
|
||||
| [02-09](02-inbound-web.md) | Low | P2 | JSON 본문 상한의 두 갈래가 테스트로 묶여 있지 않고, JSON 아닌 본문은 상한이 없다 |
|
||||
| [01-07](01-core-and-feature-pattern.md) | Low | P3 | 이벤트 식별자 문법이 다섯 곳에 복사되어 있고 길이 상한이 둘로 갈린다 |
|
||||
| [01-10](01-core-and-feature-pattern.md) | Low | P3 | application-core 한 이름공간에 커널·플랫폼 기능·(파생 시) 업무 기능이 섞인다 |
|
||||
| [01-11](01-core-and-feature-pattern.md) | Low | P3 | 공용 다이제스트 헬퍼가 있는데 복사본이 남아 있고, 일부 leaf는 registry 때문에 복사가 강제된다 |
|
||||
| [01-12](01-core-and-feature-pattern.md) | Low | P3 | 이름 규칙의 정본 문서가 없고, 같은 역할에 이름이 여러 가지다 |
|
||||
| [01-13](01-core-and-feature-pattern.md) | Low | P3 | 참조 예시의 수정 유스케이스에 소유자 검사가 없다는 사실이 코드에 보이지 않는다 |
|
||||
| [01-14](01-core-and-feature-pattern.md) | Low | P3 | 작은 결함 묶음 (각각 독립, Low / P3) |
|
||||
| [02-10](02-inbound-web.md) | Low | P3 | `GlobalExceptionHandler`가 두 경로로 등록된다 |
|
||||
| [02-11](02-inbound-web.md) | Low | P3 | `X-Correlation-Id` 허용 문자·길이가 요청 ID 규칙·짝 계약과 다르다 |
|
||||
| [02-12](02-inbound-web.md) | Low | P3 | `Idempotency-Key` 헤더 검증이 컨트롤러마다 새로 쓰인다 |
|
||||
| [03-04](03-inbound-realtime-graphql-grpc.md) | Low | P3 | `GraphQlDataLoaderRequestRegistry`는 도달 불가인데 README가 요청 스코프 장치로 설명한다 |
|
||||
| [03-05](03-inbound-realtime-graphql-grpc.md) | Low | P3 | batch loader가 플랫폼 context 없이 불리면 `REQUEST_TIMEOUT`으로 나간다 |
|
||||
| [03-12](03-inbound-realtime-graphql-grpc.md) | Low | P3 | ledger PG lane은 main push·nightly에서만 돌고 PR·릴리스 게이트에 없다 |
|
||||
| [04-16](04-persistence.md) | Low | P3 | notification·fileserver leaf에 가까운 안내 문서가 없고 패키지가 평평하다 |
|
||||
| [04-17](04-persistence.md) | Low | P3 | 미리 정한 UUID + primitive `long` version이라 `save()`가 merge로 동작한다 |
|
||||
| [05-18](05-outbound-capabilities.md) | Low | P3 | 설정 prefix·바인딩 방식이 capability 기준 4와 다르다 |
|
||||
| [05-19](05-outbound-capabilities.md) | Low | P3 | bootstrap이 알림·파일 서버 권한 이름을 안다 |
|
||||
| [05-21](05-outbound-capabilities.md) | Low | P3 | identifier leaf: 이름·문서가 내용과 맞지 않는다 |
|
||||
| [05-22](05-outbound-capabilities.md) | Low | P3 | 파일 서버: finalize가 writer lease 없이 돈다 |
|
||||
| [05-23](05-outbound-capabilities.md) | Low | P3 | 작은 결함 묶음 (각각 독립, Low / P3) |
|
||||
| [07-10](07-bootstrap-composition-config.md) | Low | P3 | 설정 오타·죽은 키가 기동에서도 게이트에서도 안 잡히는 곳이 있다 |
|
||||
| [07-11](07-bootstrap-composition-config.md) | Low | P3 | 주석·문서가 현재 동작과 다르다 (이번에 새로 찾은 것) |
|
||||
| [07-12](07-bootstrap-composition-config.md) | Low | P3 | virtual thread를 켠 상태에서 `server.tomcat.threads.max`는 동시 처리 상한이 아니다 |
|
||||
| [07-13](07-bootstrap-composition-config.md) | Low | P3 | 기본 compose가 관리 포트 9001을 모든 인터페이스에 연다 |
|
||||
| [07-14](07-bootstrap-composition-config.md) | Low | P3 | 프로필 검증기가 main class 이름을 문자열로 비교한다 |
|
||||
| [08-05](08-build-ci-test.md) | Low | P3 | registry에 없는 leaf 디렉터리는 조용히 빌드에서 빠진다 |
|
||||
| [08-06](08-build-ci-test.md) | Low | P3 | 병렬·캐시 설정이 빌드와 lane 종류에 따라 다르게 적용된다 |
|
||||
| [08-07](08-build-ci-test.md) | Low | P3 | SpotBugs·FindSecBugs가 신뢰도 HIGH만 보고한다 |
|
||||
| [09-05](09-performance-measurement.md) | Low | P3 | 트랜잭션마다 `SHOW TRANSACTION ISOLATION LEVEL` 왕복 1회 |
|
||||
| [09-08](09-performance-measurement.md) | Low | P3 | 샘플의 런타임 기본값이 기본 조합과 다름 |
|
||||
| [09-09](09-performance-measurement.md) | Low | P3 | persistence-jpa가 H2 드라이버를 운영 아티팩트에 실어 보냄 |
|
||||
| [09-10](09-performance-measurement.md) | Low | P3 | `local` 프로필이 `server.port`를 8080으로 고정 |
|
||||
| [09-11](09-performance-measurement.md) | Low | P3 | 기본 조합 jar에 Jackson 2·3과 kotlin-stdlib가 함께 실림 |
|
||||
| [06-10](06-messaging.md) | Medium | P2 | 이벤트 payload 버전을 올리는 방법과 호환성 검사가 없다 (색인 누락 정정) |
|
||||
| [06-11](06-messaging.md) | Medium | P3 | outbox가 둘인데 문서와 주석은 하나처럼 말한다 (색인 누락 정정) |
|
||||
| [06-12](06-messaging.md) | Medium | P3 | 배치 크기와 lease 시간의 관계를 검사하지 않는다 (색인 누락 정정) |
|
||||
| [06-13](06-messaging.md) | Low | P3 | 이 영역 문서·주석의 낡은 설명 (색인 누락 정정) |
|
||||
| [06-14](06-messaging.md) | Low | P3 | DLQ 격리 레코드가 모든 원인을 `POISON_MESSAGE`로 적는다 (색인 누락 정정) |
|
||||
|
||||
## 13. 조치 현황 (개선 순서 1~3)
|
||||
|
||||
리뷰 뒤 같은 기준 커밋(`01a8a2a70`)에서 수정했다. 발견마다 수정 에이전트 하나가 별도 worktree에서 실패하는 테스트를 먼저 쓰고(RED) 고친 뒤(GREEN) 패치를 냈다. 오케스트레이터가 패치를 메인 작업 트리에 합쳤다. **커밋하지 않았다**(commit policy `human-only`). 영역 문서는 리뷰 시점 기록이라 고치지 않았다.
|
||||
|
||||
| ID | 상태 | GREEN (에이전트 worktree 실행) | RED (수정 전 실패) | 남은 것·결정 필요 |
|
||||
|---|---|---|---|---|
|
||||
| 05-01 | 충족 | application-notification 231 pass, PG BackgroundPass8/WorkerCrash6/Evidence5 pass | anAttemptLeftAsTheFactoryWroteItIsReconciledNotRequeued 등 3건 수정 전 실패 | 남음: WorkerCrashRecoveryContractTest 이름/설명 불일치, 05-10 원인 그대로 |
|
||||
| 07-02 | 충족 | support68/persistence-jpa503/app-bootstrap329/sample295 pass | aViolatedRuleFailsTheBootBeforeAnyOtherBeanIsCreated, aProdPlaintextDatabaseUrlFailsTheBootBeforeTheDataSourceExists | 남음: 빈이 필요한 검사(SecretSourceValidator 등)는 기존 시점, 실 PG systemTest 미실행 |
|
||||
| 04-01 | 충족 | persistence-jpa 519 pass, PG transaction IT 4 + jpaPlatformFailure 1 pass | connectionLossDuringCommitIsReportedAsCompletionUnknownNotRetryable, IT(57P01 미분류) | 남음: flush 실패와 COMMIT 실패 미구분(안전한 쪽), 08 접두어 두 곳(04-06), SPI 메서드 commitOutcomeUnknownStates() 추가(기본 구현) |
|
||||
| 03-01 | 충족 | graphql test 392 + systemTest 29 pass | 단위 15중 11 실패(410 vs 40 등), systemTest 거부 3건 | 결정 필요: 크기 선언 없는 일반 list를 20개로 계산(기존 깊은 쿼리 거부 가능), first·last 둘 다면 큰 쪽 |
|
||||
| 04-02 | 충족 | PG jpaPlatformContractTest 53 + schemaActivation 8 pass, leaf check 4개, architectureCheck pass | aClaimedJobIsNotHandedToAnotherInstance, twoConcurrentClaimsShareNoJob(40개 전부 겹침) | 결정 필요: 포트 claimDue 시그니처·ReconciliationJob.claimFence 변경(application-notification), lease는 기존 lease-duration 2분 재사용. 새 마이그레이션 V11 |
|
||||
| 02-03+07-05 | 충족 | web 278, app-bootstrap test 321, verifyEnvKeys OK, sample test·webSystemTest pass | 6건(기동 허용, 첫 값만 비교, 타 client role 합침) | 남음: sample application.yml:196 audience 미사용 설정, env 미설정 시 ${} 문자열 남는지 미확인, app-bootstrap systemTest 미실행. 호환성 깨짐: 기존 배포는 APP_SECURITY_JWT_AUDIENCE 필수 |
|
||||
| 09-02 | 충족 | sample check(test 295)+systemTest 3+integrationTest 55 pass, 동시성 3회 반복 pass | 16동시 생성에 DB 7행·outbox 7개 | 결정 필요: 마이그레이션 번호 V8_1(V9는 production과 합친 Flyway에서 충돌). 기존 중복 제목 있으면 마이그레이션 중단. 제목 변경 PATCH도 409 |
|
||||
| 06-01+06-03 | 충족 | application-core 222, outbound:messaging 38, messaging-kafka 84, runtime-core 30, composition·starter·persistence-jpa·testkit, RunbookCoverage, architectureCheck pass | 11건(REJECTED_BEFORE_SEND, DEAD, 10분 장애 20행 DEAD) | 결정 필요: vendored messaging leaf 2곳 수정, 예산 설정 키화 안 함(일시 실패가 예산을 쓰지 않음). 한계: attempt_count가 일시 실패도 셈. 위험: 진짜 인증 오류도 5분 간격 무한 재시도(runbook 기재). PG 통합 미실행 |
|
||||
| 07-03+09-03 | 충족 | web check 259+13, sample check 298·systemTest 8·webSystemTest 5, app-bootstrap 관련 test 15·IT 9, architectureCheck pass | 실서버+PG 5중 4 실패(익명 DELETE 204, demo-user DELETE 204, POST 500) | 결정 필요: 데모 계정 비밀번호=이름(README 공개), 익명 쓰기 401로 변경(export 포함). 남음: 기동 실패 rule 미구현, 09-04 api-docs 500은 다른 원인, qualityCheck 미실행 |
|
||||
| 02-01+02-02 | 충족 | shared-contract 260, web 279, architectureCheck, app-bootstrap registry 테스트 19 pass | 7건(키 집합에 error/data/results, retryable false·Retry-After 없음) | 방법: shared-contract는 stdlib-only라 web 어댑터 Jackson mixin으로 null 생략. IN_FLIGHT retryable=true, Retry-After 2초. 남음: gRPC trailer·GraphQL extension retryable도 true로 바뀜(테스트 없음), 프론트 분류기·계약 §4.1/§6 갱신 필요, CORS Retry-After 노출(02-05) |
|
||||
| 05-07+05-08 | 충족 | application-fileserver 272, composition 33, web-fileserver 142, architectureCheck pass; 05-08 변이(copy·prepare-download descriptor 제거) 새 테스트가 잡음 | 3건(수위 0.90 미거절, 쿼터 예약 없음, 실패 시 반환 없음) | 남음: 쿼터 상한 비교 없음(정책 결정 필요), 대상 namespace 허용 목록 없음, MOVE·READ_METADATA 소유자 테스트 없음 |
|
||||
| 05-05+05-06 | 충족 | httpclient check(test 293, stableContract 20, security 9, spring62 7), spring70 20, perf 5, deadline 3회 반복 pass | 404×200에 약 100번째부터 breaker 열림, 예산 1초인데 Apache 5.58초 성공·JDK 2.05초 | 결정 필요: profile별 breaker 설정 키 없음. 남음: RETURN_RESULT 정책 5xx는 breaker 성공 기록, Toxiproxy 케이스·streaming·http3 미포함 |
|
||||
| 05-02+05-03 | 충족 | cache-redis 143 + redis-runtime 49, 실 Redis redisTopologyTest 23 pass | fake 52중 7, 실 Redis 23중 3(renew ALREADY, 작은 revision RECORDED, ONLY_IF_OBSERVED INDETERMINATE) | 새 발견: ONLY_IF_OBSERVED가 application 계정 EVALSHA 권한 없어 실 Redis에서 INDETERMINATE → SCRIPT lane으로 이동해 수정. 결정 필요: revision 순서 규칙(10진 정수)을 포트(application-core)로 옮길지, cache 전용 배포의 script 권한 기동 probe, redis-runtime testFixtures 수정(leaf 경계) |
|
||||
| 04-03 | 충족 | persistence-jpa 507, jpaPlatformContractTest(PG) 15, sample check, app-bootstrap architectureTest, architectureCheck pass | 빈 조건에서 새 규칙 테스트 4 실패, 운영 패키지 임시 양방향 엔티티로 JpaProductionArchitectureTest 실패 확인 | 결정 필요: @JoinColumn 단방향 @OneToMany 허용(문서엔 예외), sample test 의존성·lockfile 변경. DisplayName은 AGENTS.md(영어) 따름 — 소유자 결정 5(한국어)와 AGENTS.md 불일치는 08 영역 기존 지적 |
|
||||
| 03-10 | 충족 | core-api 89, runtime 278, ledger-jpa 12, 실 PG integrationTest 30, 동시 재claim 5회 반복 pass | 계약 in-memory 4, PG 5, interceptor 4 실패 | 결정 필요: TTL을 설정 키 대신 interceptor 생성자 인자(starter가 interceptor 미조립 03-11), 넘겨받기는 ledger commit이 mutation과 같은 트랜잭션일 때만 안전(ADR 기재). 남음: COMMITTED 보존 기간 정리 없음 |
|
||||
| 05-09 | 부분 충족(결정 대기) | objectstorage check 136, architectureCheck pass, 실제 lane 2개는 'pinned image unavailable'로 실패(의도) | 7중 4(원 예외 그대로 등) | 남음: 대체 이미지 소유자 결정 필요, compose minio/mc도 Docker Hub |
|
||||
| 06-02 | 충족 | outbox-relay check 20, 종료 순서 테스트 3회 반복 pass | relayFinishesItsRunningCycleBeforeThePlatformClosesAdmission(회차 미기록 상태로 platform 정지) | 남음: 남은 claim lease 해제 없음(OutboxStorePort 메서드 필요), 테스트에 platform phase 값 MAX-1024 하드코딩 |
|
||||
| 07-01 | 충족 | service-runtime 98, shared-contract 260, web 273, app-bootstrap check 321 + systemTest 10, architectureCheck, verifyDependencyLocks, verifyEnvKeys pass | TracingExportSystemTest 로컬 수신기에 아무것도 안 옴→이후 trace id 불일치 | 결정 필요: shared-contract(ActiveTrace)·web 필터까지 범위 확장. 남음: sample 테스트 미실행(합친 뒤 게이트에서), lockfile 재생성 확인 |
|
||||
| 08-01+08-04+03-12 | 충족 | verifyStrictLaneStages(RED 44건→GREEN), build-logic 87, 14 lane Docker 실행 82 pass, spring70 20, webAdvanced 124, ledger 18, configuration-cache dry-run 5 lifecycle pass | verifyStrictLaneStages 44건 | 남음: integration-check 잡 실행 시간 미측정(timeout 240분), websocketNginx·messagingCertification·mongo lane 로컬 미실행, 다른 workflow '>-' 블록 --stacktrace 결함 22곳(미확인·미수정). 결정 필요: integration 잡 5개 대체, 중복 lane, CLAUDE.md/AGENTS.md에 performanceCheck 추가 |
|
||||
|
||||
### 13.1 합친 뒤 전체 게이트
|
||||
|
||||
19개 패치를 모두 합친 메인 작업 트리에서 오케스트레이터가 실행했다(프론트 세션과 공유 잠금).
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하 |
|
||||
|---|---|---|---|
|
||||
| `ci` | rc=0 | 397초 | load 22.19 |
|
||||
| `mainCheck` | rc=1 — `objectStorageMinioContractTest`, `objectStorageMinioFaultTest` 2건만 실패. 둘 다 이제 `PinnedImageUnavailableException: pinned image unavailable: minio/minio@sha256:4c4a48…`(05-09 의도대로). 새로 mainCheck에 들어간 `:sample-portfolio:systemTest` 포함 나머지 통과 | 118초 | load 18.97 |
|
||||
| `:verifyStrictLaneStages --dry-run` (새 PR 게이트, 08-01) | rc=0 | 45초 | load 8.81 |
|
||||
| `-p optional-platforms ci` (gRPC 플랫폼) | rc=0 | 71초 | load 8.99 |
|
||||
| `:integrationCheck` (컨테이너 lane 37개 전부) | rc=1 — MinIO lane 2개만 실패(위와 같은 이유). 나머지 35 lane 통과: JPA 실 PostgreSQL 11 lane, notification·sample·Redis·Mongo·websocket nginx·messaging certification 등. 04-01·04-02·09-02 수정이 실 DB에서 함께 통과 | 794초 | load 23.84 |
|
||||
|
||||
추가 실행(같은 합친 트리, 2026-11-01 23:32~23:45):
|
||||
|
||||
| 게이트 | 결과 | 시간 | 부하 |
|
||||
|---|---|---|---|
|
||||
| `-p optional-platforms integrationCheck` (gRPC ledger 실 PostgreSQL) | rc=0, 30건 통과 · skip 0 | 118초 | load 7.33 |
|
||||
| `:performanceCheck` (08-01로 신설) | rc=0 | 284초 | load 6.45 |
|
||||
| `:releaseCheck` | 인자 없이 rc=1 — `verifyReleaseProvenance: no source revision`(릴리스는 커밋 sha가 필요하다는 설계상 전제). `-PgitRevision=$(git rev-parse HEAD)`로 rc=0. 작업 트리가 미커밋이라 실제 릴리스 증거로는 쓸 수 없다 | 105초 | load 17.50 |
|
||||
|
||||
남은 빨강은 05-09 하나(대체 이미지 미정)다.
|
||||
|
||||
### 13.2 결정이 필요한 것 (수정 중 새로 생김)
|
||||
|
||||
| 항목 | 내용 | 권고 |
|
||||
|---|---|---|
|
||||
| 03-01 list 기본 크기 | 크기를 선언하지 않은 일반 list를 원소 20개로 계산한다. 이전에 통과하던 깊은 목록 쿼리가 거부될 수 있다 | 유지. 필요한 필드만 `estimatedListSize` 선언 |
|
||||
| 04-02 포트 변경 | `ReconciliationJobStorePort.claimDue`에 lease 인자, `ReconciliationJob.claimFence` 추가(application-notification) | 유지 |
|
||||
| 06-01 vendored 수정 | messaging runtime-core·kafka의 retryable 표시를 고쳤다. 예산 설정 키는 만들지 않았다. 진짜 인증 오류도 5분 간격 무한 재시도(runbook 기재) | 유지. 인증 오류 경보 임계는 운영에서 정한다 |
|
||||
| 07-03 데모 계정 | 샘플이 공개 데모 계정 HTTP Basic을 쓴다(비밀번호=계정 이름, README 공개). 익명 쓰기는 401 | 샘플 한정이라 유지. 운영 복제 금지를 README에 명시됨 |
|
||||
| 09-02 마이그레이션 번호 | `V8_1`(V9는 운영 마이그레이션과 합친 Flyway에서 충돌) | 유지. 샘플 번호 규칙을 매뉴얼에 적는다 |
|
||||
| 05-02/03 revision 규칙 | revision은 10진 정수만. 규칙을 포트(application-core)로 옮길지, cache 전용 배포의 script 권한 기동 확인 | 포트로 옮긴다(후속) |
|
||||
| 05-05 breaker 설정 키 | client별 breaker 설정 키 없음 | 후속 |
|
||||
| 05-07 쿼터 상한 | 쿼터는 기록만 하고 상한 비교 없음 | 정책 결정 필요 |
|
||||
| 03-10 TTL | 설정 키 대신 interceptor 생성자 인자(starter가 아직 조립 안 함, 03-11) | 03-11과 함께 |
|
||||
| 07-01 범위 | trace id를 맞추려고 shared-contract(`ActiveTrace`)·web 필터까지 바꿈 | 유지 |
|
||||
| 08-01 단계 | integration 잡 5개를 `:integrationCheck` 하나로, `performanceCheck` 신설. 루트 `CLAUDE.md`/`AGENTS.md` 단계 목록 미반영 | 유지하고 문서 반영 |
|
||||
| 04-03 DisplayName | 에이전트가 AGENTS.md(영어)를 따름. 소유자 결정 5(한국어)와 AGENTS.md 불일치(08 영역 기존 지적) | AGENTS.md를 소유자 결정에 맞춘다 |
|
||||
| 05-09 MinIO 대체 이미지 | 여전히 미정. lane 2개는 구분된 메시지로 실패 | 소유자 결정 |
|
||||
|
||||
|
||||
## 14. 2라운드 조치 현황 (남은 P2·P3, 1라운드 후속, 매뉴얼)
|
||||
|
||||
사용자가 2026-11-01 23:20에 "남은 작업까지 모두 완수"를 지시했다. 1라운드 수정을 합친 상태를 임시 클론(baseline)으로 고정하고, 영역별 11개 묶음 에이전트가 각자 클론에서 RED→GREEN으로 고쳤다. 오케스트레이터가 패치를 메인 작업 트리에 합쳤다(커밋 없음). 사용량 한도로 모든 에이전트가 00:20쯤 한 번 멈췄다가 재개했다.
|
||||
|
||||
| 묶음 | 상태 | 검증 (에이전트 클론) | 처리 내용 | 합칠 때 조치·결정 필요 |
|
||||
|---|---|---|---|---|
|
||||
| r2-10 | 완료 | scaffold 왕복(5 leaf check+architectureCheck) rc=0, verifyDependencyLocks rc=0, verifyStrictLaneStages rc=0 | 01-01·07-09 완료, 01-12 부분(정본은 r2-01), 생성 명령 scripts/new-feature.sh + verifyFeatureScaffold(mainCheck) | 결정: JPA adapter는 생성 안 함(서비스 전용 persistence leaf 기본), 생성 권한은 역할 매핑 전 403 |
|
||||
| r2-02 | 완료(02-09 부분) | web·web-advanced·web-fileserver·sample check, architectureCheck, web 300, webSecurityBoundary 15, web systemTest 16, app-bootstrap test 321, sample webSystemTest 5 | 02-04~02-12 RED 확인 후 수정 | 결정: 비JSON 본문 상한 없음(엔드포인트가 직접), 새 오류 코드는 leaf enum(http-contract.md §4), correlation ID 규칙 밖이면 서버가 교체, sample 키 오류 BAD_PARAMETER→IDEMPOTENCY_KEY_INVALID(프론트 반영 필요) |
|
||||
| r2-09 | 완료 | sample check 307, systemTest 14, integrationTest 58, webSystemTest 5, web check 274, architectureCheck pass (에이전트). 합칠 때 EnvelopeBodyAdvice 충돌(02-06 vs 09-04)을 오케스트레이터가 byte[]만 제외로 합침 → web check + SampleApiDocsSystemTest 재실행 | 09-01 SQL 46→6, rps 765→2528, 09-04, 09-06, 09-07, 01-13, 09-02 후속 | 결정: batchCreate 상한 1000·한 트랜잭션 유지(원격 DB면 100으로 낮출지), 관리자도 남의 기록 수정 불가 |
|
||||
| r2-01 | 10 완료·3 부분·01-10 못함 | leaf check 11개, architectureCheck 2회, sample webSystemTest·systemTest, PG lock IT (에이전트) | 01-02,04,06,07,08,09,12,13,14 완료 / 01-03 부분(notification TenantId 유지), 01-05 부분(Transaction·Idempotency 계약 키트 못함), 01-11 부분(edge 없는 4 leaf) / 01-10 못함(패키지 규칙 선행) | 합칠 때: sample PortfolioErrorCode 충돌 → r2-09의 WORKLOG_NOT_OWNER와 r2-01의 WORKLOG_INVALID·OPERATION_NOT_FOUND 수동 합침. UpdateWorkLogUseCase "소유자 검사 없음" Javadoc은 r2-09가 소유자 검사를 넣어 사실이 아니게 되어 제외. 결정: sample 이벤트 tenant 범위 global, 새 오류 코드 2개 |
|
||||
| r2-03 | 10건 완료 | graphql test 388·systemTest 34·API surface, websocket check 92·qualification 7·Tomcat IT, grpc adapter check 61·transport 29, grpc 4 leaf check·ledger PG IT 35, -p optional-platforms ci, verifyEnvKeys 352 keys | 03-02~03-09, 03-11, 03-10 후속 | 결정: gRPC 기본값(스레드 32·큐 256·동시 100·deadline 10s·drain 2s), ledger claimTtl 5m·보존 24h·purge 스케줄은 adopter, websocket max-connections 1000·초과 시 1013, GraphQL per-parent 경고 임계 10 |
|
||||
| r2-07 | 대부분 완료(07-08·09-11 부분) | leaf check 11개, architectureCheck, verifyDependencyLocks, verifyEnvKeys 346, app-bootstrap systemTest 11·IT 10, sample systemTest 8·webSystemTest 5·IT 55, 실제 docker build+healthy | 07-02 후속, 02-03 후속(${} 자리표시자 거부), 07-04, 07-06, 07-07, 07-10~14, 09-08, 09-10 완료 / 07-08 부분(fileserver 볼륨 미룸), 09-11 부분(Jackson 2 유지: logstash·springdoc 요구), 07-03 advisor 규칙은 r2-01과 중복이라 제외 | 합칠 때 sample application.yml을 r2-09 JDBC batch 설정과 context 1줄로 합침. 결정: 새 leaf composition:durable-operation 등록, logback이 app.logging.* 읽음, APP_CACHE_REDIS_TTL_JITTER deprecated |
|
||||
| r2-08 | 대부분 완료(08-07 측정만, TEST-F-1 못함) | build-logic 94, ci verifyDependencyLocks, verifyStrictLaneStages, documentContractTest 60, 컨테이너 lane 12, -p optional-platforms ci integrationCheck (에이전트) | 1R-a(workflow --stacktrace 22곳), 08-02, 08-03, 08-04(MinIO 제외), 08-05, 08-06, 1R-b·c(AGENTS/CLAUDE 단계·DisplayName 한국어), O-10·O-11 완료 / 08-07 MEDIUM 298건 측정·계획만 / TEST-F-1 못함(포트 83개) | 합칠 때 app-bootstrap build.gradle·DeveloperExperienceContractTest·StructuredLogFieldContractTest를 r2-07과 수동 병합, r2-07이 새로 만든 저장소 읽는 테스트 4개(Dockerfile·compose 3, SampleRuntimeDefaults)에 repository-contract 태그 부여 |
|
||||
| r2-05b | 10 완료·3 부분 | objectstorage check 148 + MinIO 계약 14·fault 1 통과(새 이미지 pgsty/minio digest), support·identifier·httpclient·redis-runtime·redis-sdk·cache-redis·application-core check, app-bootstrap test 321, architectureCheck, verifyEnvKeys, 실 Redis topology, httpclient Toxiproxy | 05-09 완료(MinIO 대체: pgsty/minio@sha256:b6bfe723…, Chainguard 기각), 05-16 objectstorage 완료(S3 어댑터 결함 2개 발견·수정), 05-23b·d·e·f·g, 05-21, 05-05/06/14, 05-02/03/04/17/18 완료 / 05-15 부분(support binder 2단계 키), 05-16 Redis·HTTP 부분 / objectstorage 계약 testFixtures 이동 못함 | 합칠 때 objectstorage build.gradle, httpclient FailureInjectionContractTest를 r2-08 이미지 일원화와 수동 병합. 결정: AGENTS.md 규칙 4에 Redis 예외 한 줄 필요, objectstorage provider type 하나 추가 |
|
||||
| r2-06 | v2(baseline2 위 재작업) 완료, 06-08 부분 | application-core 264, outbox-relay 30, durable-operation 3, persistence-jpa 526, messaging 41, starter 74, inbound messaging 4, identifier 12, web 305, sample 319, architectureCheck, verifyDependencyLocks, verifyStrictLaneStages, Kafka relay 2, PG lane 5(28) | 06-02·06-01 후속, 06-04~06-07, 06-09 완료, durable operation id v4→v7 결함 RED→GREEN / 06-08 최소 경로(실 Kafka+PG 중복 전달 lane 없음) | 합칠 때 identifier README·CLAUDE.md를 r2-05b 문서 재작성과 수동 병합. r2-01 AggregateOrder.ofOccurrence(벽시계)를 지우고 OutboxAggregateSequencePort로 일원화 — ofOccurrence 테스트 2개 삭제·first() 테스트 1개로 대체. 결정: V20/V21, 새 leaf adapter:inbound:messaging, V21 유일 인덱스는 기존 중복 있으면 마이그레이션 실패 |
|
||||
| r2-04 | 13 완료·04-14/04-16/04-04후반 부분 | persistence-jpa 557, sample test 299, app-bootstrap 321, architectureTest 183, fileserver·notification·mongo leaf check, architectureCheck, verifyEnvKeys, verifyDependencyLocks, 실 PG lane(transaction 7, platformFailure 5, platformContract 244, fileserver 47, migration·notification 13, sample IT 55) | 04-05,06,07,08,10,11,12,13,15,17, 09-05, 09-07, 09-09 완료 / 04-14 부분(notification 포트 10개 계약 미이동), 04-16 부분(notification 패키지 분할 못함), 04-04 후반 부분(fileserver test 0→3) / 04-03 sample DisplayName 1개 못 고침 | 새 실 PG 테스트 3개는 수정 전 실패를 실 PG로 확인 안 함(단위 테스트로 RED). 결정: 트랜잭션 제한 30초, batch 기본 50, H2 운영 jar에서 제거, 격리 수준을 Hikari에서 고정, 포트 시그니처 변경(fileserver claimDue·markAbandoned·claimToken), 마이그레이션 notification V12 |
|
||||
| r2-05a | **합치지 않음** | — | 알림·파일 서버 묶음(05-10~13, 05-19, 05-20, 05-22, 05-23 일부, 05-16 일부, 05-07 쿼터 상한 등). 마감까지 패치·검증 보고가 없었다. 클론 `round2/wt-r2-05a-notif-file`에 미검증 변경 86개 파일이 있다 | 다음 작업에서 이 클론을 baseline 최신 상태로 다시 올려 검증 후 합친다 |
|
||||
|
||||
### 14.1 합칠 때 생긴 충돌과 처리
|
||||
|
||||
- `EnvelopeBodyAdvice`(r2-02 02-06 ↔ r2-09 09-04): springdoc 3.0이 OpenAPI 문서를 `byte[]`로 돌려주는 것을 jar에서 확인하고, `byte[]`만 감싸지 않고 `String`은 02-06대로 감싸게 합쳤다. web check·`SampleApiDocsSystemTest` 통과.
|
||||
- sample `PortfolioErrorCode`(r2-01 ↔ r2-09): 두 쪽 코드 모두 넣었다. r2-01의 "UpdateWorkLogUseCase는 소유자 검사 없음" Javadoc은 r2-09가 소유자 검사를 넣어 거짓이 되므로 넣지 않았다.
|
||||
- sample `application.yml`(r2-07 ↔ r2-09): context 1줄로 합쳐 JDBC batch 설정과 설정 정리 둘 다 반영.
|
||||
- app-bootstrap `build.gradle`·계약 테스트 2개(r2-08 ↔ r2-07): lane 분리 블록으로 바꾸고 r2-07의 sample yml 입력을 살렸다. r2-07이 새로 만든 저장소 읽는 테스트 4개에 `repository-contract` 태그를 달았다(태그 없으면 08-03 규칙상 `test` lane에서 실패). 합친 뒤 `:app-bootstrap:check`·`documentContractTest` 통과.
|
||||
- r2-06은 10개 파일 충돌로 baseline2(그 시점 메인 상태) 위에서 다시 작업시켰다(v2). r2-01의 `AggregateOrder.ofOccurrence`(벽시계)를 지우고 `OutboxAggregateSequencePort`로 일원화했다.
|
||||
- objectstorage `build.gradle`·httpclient `FailureInjectionContractTest`(r2-05b ↔ r2-08 이미지 일원화), identifier README·CLAUDE.md(r2-05b ↔ r2-06): 수동 병합.
|
||||
- 매뉴얼(`docs/manual/`)이 가리키던 `DurableOperationConfig`는 r2-07이 `composition:durable-operation`의 `DurableOperationAutoConfiguration`으로 옮겨서 경로를 고쳤다. 매뉴얼이 인용한 `src/`·`docs/` 경로를 전수 검사해 템플릿 자리표시자(`<f>`) 외에 없는 경로가 없음을 확인했다.
|
||||
|
||||
### 14.2 합친 뒤 전체 게이트
|
||||
|
||||
r2-05a를 뺀 10개 묶음을 합친 메인 작업 트리에서 오케스트레이터가 실행했다(공유 잠금).
|
||||
|
||||
첫 실행(05:40)은 실패 3건이었다. 모두 합치는 과정에서 생긴 문제라 고쳤다.
|
||||
|
||||
| 실패 | 원인 | 조치 |
|
||||
|---|---|---|
|
||||
| `ci` `verifyCleanArchitectureDependencies` | 08-05의 새 검사가 git-ignore 대상인 IDE 출력 `bin/` 안의 복사된 build 스크립트(`grpc-codegen/bin/test/...`)를 잡았다 | `ModuleRegistry.unregisteredBuildScripts`가 `bin/`을 건너뛴다 |
|
||||
| `mainCheck` `verifyFeatureScaffold` | 작업 트리 복사가 지웠지만 미커밋인 추적 파일 26개에서 `tar` 실패 | `scripts/verify-feature-scaffold.sh`가 `git ls-files -d` 경로를 뺀다 |
|
||||
| sample `WorkLogStatementCostSystemTest` | 기대 202, 실제 8. 04-17(`Persistable`) 뒤 컬렉션 행도 owner를 넘어 묶여 표마다 50행씩(2+4+2) | 기대값 8로, 테스트 설명·sample README·`application.yml` 주석 수정. 202·400 회귀는 계속 잡는다 |
|
||||
| (확인 중 발견) build-logic `PlatformModuleConventionTest` 6건 | 08-04 뒤 `java-conventions`가 이미지 목록 파일을 요구하는데 TestKit fixture에 없음 | fixture가 빈 목록 파일을 쓴다 |
|
||||
|
||||
재실행 결과:
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하 |
|
||||
|---|---|---|---|
|
||||
| `ci` | rc=0 | 365초 | load 4.24 |
|
||||
| `mainCheck` (`verifyFeatureScaffold` 생성 왕복 포함) | rc=0 | 171초 | load 15.86 |
|
||||
| `:integrationCheck` (MinIO 계약·fault 포함 전 컨테이너 lane) | rc=0 | 697초 | load 11.23 |
|
||||
| `-p optional-platforms ci integrationCheck` | rc=0 | 51초 | — |
|
||||
|
||||
1라운드 끝까지 빨갛던 MinIO lane이 05-09 대체 이미지(`pgsty/minio` digest)로 통과한다. 이 시점 기준으로 빨간 게이트는 없다. `releaseCheck`·`performanceCheck`는 2라운드 뒤 다시 돌리지 않았다.
|
||||
|
||||
|
||||
|
||||
### 14.3 남은 것 (2026-11-02 06:15 기준)
|
||||
|
||||
**합치지 않은 묶음**
|
||||
- r2-05a(알림·파일 서버). 06:45에 패치(`round2/patches/r2-05a-notif-file.patch`, 103파일)가 왔지만 합치지 않았다. 이유: 메인 작업 트리에 6곳 충돌(r2-04가 같은 fileserver fake를 testFixtures로 옮김, `application-fileserver` build.gradle·lockfile, `applied-migrations.sha256`, `NotificationFixtures`), 알림 마이그레이션 `V12`가 r2-04의 `V12__notification_suppression_target_unique`와 번호 충돌, 05-11은 수정 뒤 GREEN 실행 없음. 07:30 마감 안에 합치고 전체 게이트를 다시 돌릴 시간이 없어 초록 상태를 유지했다.
|
||||
- 묶음 보고상 완료: 파일 서버 05-07 후속(쿼터 상한·대상 namespace·MOVE/READ_METADATA 소유자 테스트)·05-12·05-13·05-22·05-23a, 알림 05-10(+ `collapse_key` 미저장 결함 발견)·05-23c·05-01 후속 테스트 이름. 부분: 05-11(GREEN 미실행), 05-16 fileserver. 못 함: 05-19, 05-20, 05-16 notification.
|
||||
- 다음 작업: 최신 메인 위로 다시 올리고 마이그레이션을 `V13`으로 바꾼 뒤 05-11 GREEN과 전체 게이트를 확인하고 합친다.
|
||||
|
||||
**부분 완료·못 한 것 (묶음 보고 기준, 이유는 14절 표)**
|
||||
- 01-03(notification `TenantId` 유지), 01-05(트랜잭션·멱등성 포트 공유 계약), 01-10(패키지 이동), 01-11(edge 없는 4 leaf)
|
||||
- 02-09(JSON 아닌 본문 상한 — 엔드포인트가 직접 두도록 문서화)
|
||||
- 04-14(notification 포트 10개 계약), 04-16(notification 패키지 분할), 04-04 후반(persistence-fileserver 테스트 3개만), 04-03 sample `@DisplayName` 1개
|
||||
- 05-15(support binder 2단계 키), 05-16 Redis·HTTP 계약 상속, objectstorage 계약 testFixtures 이동
|
||||
- 06-08(실 Kafka+PG 중복 전달 lane 없음)
|
||||
- 07-08(fileserver 볼륨), 09-11(Jackson 2는 logstash·springdoc 요구로 유지)
|
||||
- 08-07(SpotBugs MEDIUM 298건 — 측정과 단계 계획만), TEST-F-1(공유 계약 없는 포트 정리)
|
||||
|
||||
**결정 필요** — 13.2 표와 14절 표의 "결정" 칸. 파생 서비스 동작을 바꾸는 것: JWT audience 필수, JDBC batch 기본 켜기·H2 제거·트랜잭션 30초·격리 수준 Hikari 고정, gRPC·WebSocket·GraphQL 새 한도 기본값, 새 leaf 2개(`composition:durable-operation`, `adapter:inbound:messaging`) 등록, 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002).
|
||||
|
||||
**짝 프론트가 맞출 것** — 처리 중 409 `retryable=true`+`Retry-After`, 키 재사용 `422 IDEMPOTENT_REQUEST_MISMATCH`, 키 형식 오류 `400 IDEMPOTENCY_KEY_INVALID`, Envelope null 필드 생략, 계약 §4.1·§6이 `docs/web/http-contract.md`를 가리키게.
|
||||
|
||||
**검증하지 않은 것** — 2라운드 뒤 `releaseCheck`·`performanceCheck`, GitHub Actions 실제 실행.
|
||||
|
||||
**커밋** — 하지 않았다(`human-only`). 1·2라운드 변경이 main 작업 트리에 미커밋으로 있다.
|
||||
|
||||
## 15. 결정 기록 (2026-11-03)
|
||||
|
||||
사용자가 "결정이 필요한 부분은 지금 바로 결정하고 남은 부분 전부 진행"을 지시했다. 13.2·14절·14.3의 결정 칸을 아래처럼 정했다. "유지"는 묶음이 고른 기본값을 그대로 확정한다는 뜻이다. "추가 작업"은 3라운드에서 코드로 반영한다.
|
||||
|
||||
| 항목 | 결정 | 이유 |
|
||||
|---|---|---|
|
||||
| JWT audience 필수, 자기 client role만 (02-03) | 유지 | 기본값이 닫힌 쪽이어야 한다. 기존 배포는 env 하나를 채우면 된다. 실패 메시지가 키 이름을 알려 준다 |
|
||||
| 처리 중 409 `retryable=true`+`Retry-After: 2`, Envelope null 생략 (02-01·02-02) | 유지 | 소유자 결정(11-01). 짝 프론트 변경은 프론트 세션에 넘긴다(아래) |
|
||||
| JSON 아닌 본문 상한 (02-09) | 유지 — 엔드포인트가 직접 둔다 | raw 업로드 경로가 모든 content type을 받아 전역 제외 목록은 경로 단위가 되고, 하나 빠지면 업로드가 깨진다. 문서와 필터 Javadoc에 이미 적었다 |
|
||||
| 새 오류 코드(`REQUEST_TIMEOUT`, `IDEMPOTENCY_KEY_INVALID`, web-advanced 10종)를 leaf enum으로 (02) | 유지 | 코드를 쓰는 leaf가 소유한다. 계약은 `docs/web/http-contract.md` §4 |
|
||||
| correlation ID 규칙 밖이면 서버가 새 값으로 교체 (02-11) | 유지 | 요청 ID와 같은 규칙이 로그 주입을 막는다 |
|
||||
| GraphQL 크기 미선언 list = 20, `first`·`last` 둘 다면 큰 쪽 (03-01), per-parent 경고 임계 10 (03-03) | 유지 | 기본 페이지 크기와 같다. 깊은 쿼리가 거부되면 필드에 `estimatedListSize`를 선언한다 |
|
||||
| gRPC 서버 기본값(스레드 32·큐 256·동시 100·deadline 10s·drain 2s), `ServerCallExecutorSupplier`(ExperimentalApi) 사용 (03-09) | 유지 | 플랫폼 값과 같다. 실험 API는 넘친 호출을 즉시 닫는 유일한 경로다. grpc 버전 올릴 때 확인 대상으로 README에 적혀 있다 |
|
||||
| ledger `claimTtl` 5m·보존 24h·purge 스케줄은 서비스 몫 (03-10·03-11) | 유지 | starter는 어느 replica가 돌릴지 모른다 |
|
||||
| WebSocket `max-connections` 1000, 초과 시 연결 후 1013 (03-06) | 유지 | handshake에서 세면 자리를 돌려줄 곳이 없다 |
|
||||
| 트랜잭션 제한 30초, JDBC batch 50 기본, H2 운영 jar 제거, 격리 수준 Hikari 고정, upsert `DO NOTHING` 후 갱신 (04) | 유지 | 30초는 Hikari 누수 경고·`inNew`와 맞췄다. batch는 샘플에서 왕복 400→8을 확인했다 |
|
||||
| 포트 시그니처 변경(04-02 `claimDue` lease·`claimFence`, fileserver `claimDue`·`markAbandoned`·`claimToken`) | 유지 | 소유권을 DB lease로 옮기는 데 필요하다 |
|
||||
| 마이그레이션 번호: postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002. r2-05a의 notification V12는 **V13**으로 | 유지/변경 | 스트림별 순번. 샘플은 운영 스트림과 합쳐 도는 테스트가 있어 V8_1 |
|
||||
| V21 유일 인덱스는 기존 중복이 있으면 마이그레이션 실패 | 유지 | 중복은 순서 보장 위반이라 조용히 넘기면 안 된다. runbook에 확인 쿼리를 둔다(추가 작업) |
|
||||
| relay: 재시도 가능 거부는 무한 재시도(5분 간격), 예산 설정 키 없음 (06-01·06-03) | 유지 | 일시 실패가 예산을 쓰지 않는다. 진짜 인증 오류는 경보로 잡는다(runbook) |
|
||||
| 새 leaf `composition:durable-operation`, `adapter:inbound:messaging` 등록 | 승인 | 조립 책임을 bootstrap에서 떼는 기존 방향(capability 기준 7)과 같다 |
|
||||
| logback이 `app.logging.*`을 읽음, `APP_CACHE_REDIS_TTL_JITTER` deprecated (07) | 유지 | 로그 설정을 한 곳에서 읽는다 |
|
||||
| sample 이벤트 tenant 범위 `global`, `WORKLOG_INVALID`·`OPERATION_NOT_FOUND` (01) | 유지 | 샘플은 tenant 개념이 없다 |
|
||||
| notification `TenantId` 통합 시점 (01-03) | 통합하지 않음 — 닫음 | 저장된 행을 읽으려고 느슨하게 둔 P19-new-1 결정이 유효하다. 차이와 이유는 그 타입 Javadoc에 있다 |
|
||||
| registry edge가 없어 복사본이 남은 leaf 4개 (01-11) | 템플릿 leaf는 `shared-contract` edge 추가 후 정본 사용, vendored(`messaging:*`·`grpc:*`)는 복사본 유지 + leaf CLAUDE.md에 이유 | vendored는 다른 제품이라 의존하면 안 된다(messaging 리뷰 MSG-023) — 추가 작업 |
|
||||
| 샘플 데모 계정(비밀번호=계정 이름, README 공개), 익명 쓰기 401 (07-03) | 유지 + **prod 프로필에서는 기동 거부** | 샘플을 복제해 운영에 올리는 위험을 코드로 막는다 — 추가 작업 |
|
||||
| 관리자도 남의 work log 수정 불가, `batchCreate` 상한 1000·한 트랜잭션 (09) | 유지 | 왕복이 8로 줄어 상한을 낮출 이유가 없어졌다 |
|
||||
| 생성 명령은 JPA adapter를 만들지 않음, 생성된 쓰기 API는 역할 매핑 전 403 (r2-10) | 유지 | 서비스 전용 persistence leaf가 기본이다. 닫힌 쪽이 안전하다 |
|
||||
| Redis 설정 prefix 예외 (05-18) | AGENTS.md capability 기준 4에 예외 한 줄 | 키를 바꾸면 운영 env가 깨진다 — 추가 작업 |
|
||||
| objectstorage provider type 하나 추가 (05-16) | 유지 | |
|
||||
| 파일 서버 쿼터: 상한 미설정=무제한, 동시 예약은 상한을 넘을 수 있음, 정리 worker 기본 켜짐 (r2-05a) | 유지 | 넘는 폭은 동시 업로드 수로 제한된다. 엄격 상한이 필요하면 DB 원자 갱신으로 바꾼다(문서화) |
|
||||
| MinIO 대체 이미지 `pgsty/minio` digest (05-09) | 유지 | 두 후보 실측 결과가 같았고 Chainguard는 태그·사용자·mc 문제 |
|
||||
| Jackson 2가 기본 jar에 남음 (09-11) | 유지 — 닫음 | logstash encoder와 springdoc이 요구한다 |
|
||||
| SpotBugs 신뢰도 (08-07) | **MEDIUM으로 내린다** | 298건을 분류해 진짜 결함은 고치고, 패턴 단위 제외는 이유를 단다 — 추가 작업 |
|
||||
| `@DisplayName` 언어 | 한국어(소유자 결정 5, AGENTS.md 반영됨) | |
|
||||
| 커밋 | 하지 않음 | 저장소 정책 `human-only`. 커밋 단위 계획만 만든다 |
|
||||
| 짝 프론트 계약 반영 | 프론트 세션에 넘긴다 | 다른 repo이고 그 세션이 작업 중이다 |
|
||||
|
||||
| 메시지 소비자의 decode 타입 등록 경로 (06-08 후속) | 핸들러 bean이 선언한 타입으로 decode 목록을 만든다. 서비스가 별도 등록 코드를 쓰지 않는다 | 등록을 빠뜨리면 메시지가 조용히 버려진다 — 위험을 코드로 막는다 |
|
||||
| `APP_FLYWAY_ENABLED`가 dev·prod에도 적용 (r3-F) | 유지 | profile 파일이 env 값을 덮어쓰던 것이 결함이었다 |
|
||||
|
||||
| notification INGEST_ONLY와 handoff (r3-I 발견) | INGEST_ONLY도 runtime 없이 route 이름을 accept 때 기록한다 | handoff는 accept 때 고정한 route로 나중에 배달된다는 계약이다. 지금은 둘이 모순이라 handoff lane이 기동하지 못한다 |
|
||||
| 선택 숫자 설정의 빈 env 값 (r3-I 발견) | 빈 값은 "미설정". 오타·모르는 키 거부는 그대로 | `.env.example`이 빈 값을 싣고 있어 그대로 쓰면 기동이 실패한다 |
|
||||
| notification `ConsentStorePort`·`NotificationInbox` 계약 (04-14) | 보류 — 닫음 | 이 fake를 쓰는 유스케이스 테스트가 없다. 소비자 없는 fake는 두 번째 복사본이 된다. inbox `@Version`은 실 PG 테스트가 본다 |
|
||||
|
||||
| compose `all-adapters`·`local-redis` lane의 Redis 익명 접근 경고 (r3-J 발견) | lane Redis에 ACL 계정을 주고 앱이 그 계정으로 붙는다(`infra/redis-sdk/acl` 재사용). "기동 WARN 없음" 검사는 그대로 둔다 | 경고 로그 수준을 낮추면 운영에서도 같은 위험이 가려진다. 개발 lane이 운영과 같은 인증 모양이어야 한다 |
|
||||
|
||||
### 15.1 3라운드 범위
|
||||
|
||||
| 묶음 | 내용 |
|
||||
|---|---|
|
||||
| r3-A 알림·파일 서버 | r2-05a 패치를 최신 main 위로 다시 올림(V13), 05-11 GREEN, 05-19, 05-20, 05-16 notification, 04-14 notification 포트 계약 10개, 04-16 notification 패키지 분할, 04-04 후반 persistence-fileserver 테스트 |
|
||||
| r3-B core 계약 | 01-05 트랜잭션·멱등성 포트 계약 키트(PG·Redis store 상속), 01-11 결정 반영, TEST-F-1 application-core 포트 공유 계약 |
|
||||
| r3-C outbound | 05-15 support binder 2단계 키, 05-16 Redis·HTTP 계약 상속(Testcontainers Redis lane), objectstorage 계약 testFixtures 이동 |
|
||||
| r3-D messaging | 06-08 실 Kafka+PG 중복 전달 lane, V21 중복 확인 쿼리 runbook |
|
||||
| r3-E build | 08-07 SpotBugs MEDIUM, AGENTS.md 기준 4 Redis 예외 |
|
||||
| r3-F bootstrap·sample | 07-08 fileserver 볼륨, 데모 계정 prod 기동 거부, 04-03 sample DisplayName |
|
||||
| r3-H 정리 | 3라운드에서 새로 나온 후속: 소비자 decode 타입 등록, inbox 마이그레이션 스트림 연결, inbox lane 변이 확인, web `SecuritySettings` strict 바인딩, `local-fileserver` compose lane DB, `ObjectStorageProviderContract` given/when/then |
|
||||
| r3-J 마지막 정리 | notification 포트 계약 나머지(lease·delivery·attempt·resolver 묶음·contact point), INGEST_ONLY route 기록, 빈 env 값, compose 4 lane 기동 |
|
||||
| r3-G (마지막, 단독) | 01-10 application-core 패키지 정리 — 전 leaf import를 바꾸므로 나머지를 합친 뒤 |
|
||||
| 마무리 | 전체 게이트(ci·mainCheck·integrationCheck·optional·performanceCheck·releaseCheck), 커밋 단위 계획, 프론트 인계 |
|
||||
|
||||
## 16. 3라운드 조치 현황 (2026-11-03)
|
||||
|
||||
15절 결정에 따라 남은 항목을 끝냈다. 묶음마다 그 시점의 메인 작업 트리를 담은 임시 클론(baseline3~7)에서 RED→GREEN으로 고치고 오케스트레이터가 합쳤다. 하위 에이전트는 쓰지 않았다(지난 라운드 사용량 한도). 커밋 없음.
|
||||
|
||||
| 묶음 | 상태 | 검증 (에이전트 클론) | 처리 내용 | 결정·합칠 때 조치·남은 것 |
|
||||
|---|---|---|---|---|
|
||||
| r3-c | 완료 | support·httpclient·cache-redis·objectstorage check, binder 사용 14 leaf test, 실 Redis lane 38, MinIO 14+1, Toxiproxy 4, architectureCheck, verifyDependencyLocks, verifyEnvKeys, verifyStrictLaneStages | 05-15 StrictSettingsBinder list 원소 하위 키 검사(httpclient 전용 guard 삭제), 05-16 Redis Testcontainers lane redisContainerContractTest, 05-16 HTTP BlockingTransportProviderContract(가짜·실엔진 상속), ObjectStorageProviderContract testFixtures 이동 | 남음: 옮긴 계약 클래스 given/when/then 미적용 |
|
||||
| r3-e | 완료 | qualityCheck(MEDIUM)·architectureCheck·고친 leaf 16 check 통과(sample spotless 1건 — 오케스트레이터가 1라운드 이후 직접 고친 WorkLogStatementCostSystemTest 형식, spotlessApply로 해결) | 08-07: 307건 중 46건 코드 수정(방어 복사 4곳 RED 5, final 21개, nullable getter 등), 261건 위치·패턴별 이유 단 제외. 05-18 AGENTS.md 기준 4 Redis 예외 | 결정: EI 제외는 필드 타입 기준(컬렉션·배열 등은 계속 검사), DTO는 복사 안 함 |
|
||||
| r3-f | 완료(AuthenticationModeSettings strict 못함) | sample test 324·systemTest 14·webSystemTest 5, app-bootstrap test 217·repositoryContract 68·documentContract 60·systemTest 11·architectureTest 185, persistence-jpa 558, verifyEnvKeys, architectureCheck, verifyDependencyLocks, compose 18 lane 일치, 실제 docker build·compose healthy·볼륨 소유권 확인 | 07-08 fileserver 볼륨 overlay 분리(one-shot chown), 데모 계정 prod 기동 거부(StartupRule), sample DisplayName, dev/prod JPA 키 정리(APP_FLYWAY_ENABLED가 dev·prod에도 적용 — 동작 변경), smoke 래퍼의 낡은 gRPC 끄기 키 수정 | 못 함: AuthenticationModeSettings strict(web SecuritySettings 쪽에서 해야), 발견: local-fileserver lane이 DB 없이 기동 실패(이전부터 있던 결함) |
|
||||
| r3-d | 완료(결정·후속 2건) | inbound messaging·messaging-kafka·persistence-jpa 558 check, 새 inbox 재전달 lane 2, Kafka relay 2, aggregate-sequence PG 4, runbook PG 5, architectureCheck, verifyDependencyLocks, documentContractTest, verifyStrictLaneStages | 06-08 실 Kafka+PG 중복 전달 lane(재전달 1회 처리, 실패 후 재처리) — 발견·수정: inbound/outbound messaging leaf가 같은 Gradle 좌표라 bridge가 빠지던 결함. V21 중복 확인 runbook + 쿼리를 runbook에서 읽어 실행하는 PG lane. 매뉴얼 소비자 절 | 후속: handler decode 타입 등록 경로 없음(결정 필요), inbox 마이그레이션 V1101이 서비스 스트림에 미연결, 변이 확인 미실행 |
|
||||
| r3-b | 완료(TEST-F-1 포트 2개 남음) | leaf check 9, architectureCheck, verifyDependencyLocks, verifyStrictLaneStages, 실 PG jpaPlatformContractTest 277·멱등성·outbox·트랜잭션 lane, 실 Redis standalone·cluster, fake 변이 6개 모두 계약이 잡음 | 01-05 트랜잭션 계약 13건(fake RED 6), 멱등성 계약에 renew 시간 케이스(PG RED 3), PG·Redis 상속. TEST-F-1 계약 5개 추가, 전수 표 docs/testing/TESTING_STRATEGY.md 9절. 발견·수정: JpaOutboxStore.append가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음. 01-11 템플릿 leaf 4개 shared-contract edge + 정본 헬퍼(출력 동일 고정), vendored 이유 family CLAUDE.md | 결정: PG 멱등성 이전 revision 응답 NOT_OWNER로 통일, CLAIMED 상태 renew 거부. 남음: OutboxMessagePublishPort·IntegrationEventPublishPort 계약(messaging), notification·fileserver 테스트 TransactionPort 구현 6개(r3-A 영역). 합칠 때 cache-redis build.gradle 주석 1곳 충돌(r3-C) 수동 반영 |
|
||||
| r3-h | 완료(후속 2건) | 건드린 10 leaf check, inbox lane 3, Kafka relay 2, MinIO 19, starter Kafka 6, app-bootstrap architecture·repositoryContract·documentContract·systemTest, sample test 325, architectureCheck, verifyEnvKeys 352, verifyDependencyLocks, verifyStrictLaneStages, compose 정적 18 lane·local-fileserver 실제 기동 healthy | 1 decode 목록을 handler 선언에서(RED: handler 0회), 2 inbox 마이그레이션 스트림(MessagingInboxSchemaStream), 3 변이 확인(중복 검사 제거 시 실패), 4 web SecuritySettings strict(AuthenticationModeSettings 삭제), 5 local-fileserver lane DB, 6 ObjectStorageProviderContract GWT, 7 발행 포트 2개 공유 계약 | 결정: web→support edge(ArchUnit 예외 StrictSettingsBinder 1개), decode·발행 codec 공유, messaging 마이그레이션 트리 전체 고정 목록. 남음: notification compose lane·all-adapters 실제 기동 미실행, relay 테스트의 직접 만든 publish fake 미교체. 합칠 때 TESTING_STRATEGY 9절 표를 오케스트레이터가 갱신 |
|
||||
| r3-a | 부분(04-14·04-16·04-04 후반 미착수) | notification·fileserver 10 leaf check, architectureCheck, verifyEnvKeys 354, verifyDependencyLocks, verifyStrictLaneStages, 실 PG jpaPlatformContract 245·Migration 45·fileserver 6/21/21·notification schema 8 | r2-05a 이식(V12→V13, 중복 fake 제거, angus-mail lock·스트림 버전 목록 결함 수정), 05-11 SMTP 분류(RED 5/6→GREEN), 05-19 모듈 기본값 고정 테스트, 05-20 SES replay 창 1h·인증서 실패 503+Retry-After(RED 4), 05-16 notification 계약 testFixtures 이동(콜백 계약은 이제 SES가 실행), TransactionPort 손구현 → DirectTransactionPort | 결정: replay 창 1h(SNS 재시도 상한 3600s), Retry-After 30, 인증서 실패는 로그만. 못 함: 04-14·04-16·04-04 후반(시간) |
|
||||
| r3-g | 완료 | ci(spotbugs 1건 제외 통과 — 원래 있던 결함), sample check, verifyFeatureScaffold(거절 3·생성 2), documentContractTest 60, API surface 5, verifyDependencyLocks | 01-10: SecretSourcePort·SecretReference → application.secret, CallBudget → application-objectstorage objectstorage.content, outbound 패키지 삭제. application-core/CLAUDE.md Package ownership 절(정본) + ArchUnit 2개(템플릿 이름 재사용 금지, 템플릿→기능 import 금지). new-feature.sh가 이미 있는 패키지 이름 거절 | 합친 뒤 오케스트레이터가 고침: JavaMailSenderSmtpDispatch BC_IMPOSSIBLE_INSTANCEOF 2건(r3-A SMTP 수정 + r3-E MEDIUM이 만나 생김 — Angus 예외 3종이 형제 타입이라 부정 조건이 불가능, 동작 같음). 한계: 템플릿 패키지 목록이 CLAUDE.md 표와 TemplatePackageOwnership 두 곳(권위는 클래스로 명시, 일치 검사 없음 — repo가 문서 대조 parser를 없앤 방침) |
|
||||
| r3-i | 대부분 완료(04-14 부분, compose 2 lane 실패) | leaf check 8, 실 PG jpaPlatformContract 303·fileserver 48·notification schema 8, architectureCheck, verifyEnvKeys, verifyDependencyLocks, verifyStrictLaneStages, 변이 6건 모두 걸림, compose ingest·serving 기동 | 04-14 notification 포트 5개 계약, 04-16 persistence-notification 패키지 분할, 04-04 후반 persistence-fileserver 테스트 3→34, relay 테스트 fake 교체, compose 기동으로 결함 3건 찾아 수정(콜백 본문 상한, SMTP lane timeout env, health가 꺼진 profile 감시) | 남음: 포트 계약 나머지, handoff lane(INGEST_ONLY route 모순), all-adapters lane(빈 namespace-limit) |
|
||||
| r3-j | 완료(all-adapters lane만 남음) | 건드린 leaf check 8, architectureCheck, verifyEnvKeys, verifyDependencyLocks, verifyStrictLaneStages, jpaPlatformContractTest 333, 변이 13건 모두 걸림, compose ingest·serving·handoff 기동 | 04-14 notification 포트 8개 계약+fake, side effect 규칙을 application으로, INGEST_ONLY route 기록(RED 3), 빈 env 값=미설정(RED 4), 발견·수정: httpclient 기본 난수 생성기가 slim JRE에 없어 기동 실패, 비운영 환경 평문 HTTP 프로필이 기동 검증에 막힘 | 남음: all-adapters lane '기동 WARN 없음' 검사가 Redis 익명 접근 경고 2줄로 실패(local-redis lane도 같은 설정) |
|
||||
| r3-k | 완료 | compose 정적 검사 18 lane(망가뜨린 6가지 모두 잡음), local-redis·all-adapters 실제 기동(healthy, WARN 0, smoke auth·graphql·notification), ACL 직접 확인, repositoryContractTest 68, documentContractTest 60, verifyEnvKeys | compose redis가 infra/redis-sdk ACL을 마운트해 --aclfile로 기동, healthcheck 인증, 계약 json·검사기 7번 규칙 | 결정: lane namespace prod(fixture 계정이 ~prod:* 만 허용), 비밀번호 env는 REDIS_LANE_*(APP_ 아님 — 코드가 읽지 않는 키) |
|
||||
| r3-l | 완료 | ci·mainCheck·-p optional-platforms ci 성공(에이전트) | httpclient PREDICTABLE_RANDOM 제외(retry jitter), gRPC USO 6건 진짜 결함 → private lock(RED: 외부 lock으로 tryAdmit 막힘), REDOS 4·CT·COMMAND_INJECTION·UNSAFE_HASH_EQUALS 위치별 제외(근거 실측·상한), notification evidence verifier가 상속 계약 테스트를 근거로 인정하게 수정 + manifest 근거 교체(내린 claim 없음) | |
|
||||
|
||||
### 16.1 합칠 때 오케스트레이터가 직접 고친 것
|
||||
|
||||
- `JavaMailSenderSmtpDispatch`의 `BC_IMPOSSIBLE_INSTANCEOF` 2건: r3-A(05-11 SMTP 분류)와 r3-E(SpotBugs MEDIUM)가 처음 한 트리에 만나 드러났다. Angus의 SMTP 예외 3종이 형제 타입이라 부정 조건이 항상 참이었다. 지우고 동작은 같다. notification check·spotbugsMain 통과.
|
||||
- r3-B의 cache-redis `build.gradle` 주석 1곳, r3-F의 `WorkLogStatementCostSystemTest`(같은 Spotless 수정이 이미 있음), r3-H 뒤 `TESTING_STRATEGY.md` 9절 표(발행 포트 2개 이동).
|
||||
- 그 밖의 패치는 그대로 붙었다. 2라운드(14.1절)보다 충돌이 적었던 것은 묶음마다 직전 메인 상태로 기준 클론을 새로 만들었기 때문이다.
|
||||
|
||||
### 16.2 최종 게이트
|
||||
|
||||
3라운드 묶음을 모두 합친 메인 작업 트리에서 오케스트레이터가 실행했다(2026-11-03 10:34~10:50, 공유 잠금).
|
||||
|
||||
중간 실행(09:50)에서 실패 3종이 나와 r3-L로 고쳤다: httpclient `PREDICTABLE_RANDOM`(r3-J 코드가 MEDIUM 기준을 만남), optional-platforms gRPC SpotBugs 13건(r3-E가 main 빌드만 판정 — `USO` 6건은 진짜 결함이라 private lock으로 고침), notification evidence manifest가 r3-J가 옮긴 PG 테스트를 가리킴.
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하 |
|
||||
|---|---|---|---|
|
||||
| `ci` | rc=0 | 51초 | load 8.02 |
|
||||
| `mainCheck` (`verifyFeatureScaffold` 왕복 포함) | rc=0 | 129초 | load 10.26 |
|
||||
| `:integrationCheck` (컨테이너 lane 전부, MinIO·Kafka inbox·Redis 컨테이너 lane 포함) | rc=0 | 768초 | load 4.18 |
|
||||
| `-p optional-platforms ci integrationCheck` | rc=0 | 11초(build cache) | load 2.43 |
|
||||
| `:performanceCheck` | rc=0 | 21초 | load 2.60 |
|
||||
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 3초 | load 2.35 |
|
||||
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane 일치 | — | — |
|
||||
|
||||
compose 실제 기동은 묶음 에이전트가 lane별로 확인했다: local-fileserver(r3-H), notification ingest·serving·handoff(r3-J), local-redis·all-adapters(r3-K, smoke auth·graphql·notification 포함).
|
||||
|
||||
`ci` 시간이 첫 리뷰 때 434초에서 51초로 줄었다. 08-02(strict lane build cache)와 같은 입력의 캐시 재사용 덕이다. 캐시 없이 처음 도는 시간은 재지 않았다.
|
||||
|
||||
### 16.3 남은 것
|
||||
|
||||
- **결정으로 닫은 것** (15절): notification `TenantId` 통합(01-03), JSON 아닌 본문 전역 상한(02-09), Jackson 2 제거(09-11), notification `ConsentStorePort`·`NotificationInbox` 계약(04-14 일부).
|
||||
- **검사로 막지 못하는 것**: 템플릿 패키지 목록이 `application-core/CLAUDE.md` 표와 `TemplatePackageOwnership` 두 곳에 있다(정본은 클래스, 일치 검사 없음). 템플릿이 새 패키지를 만들고 목록에 넣는 것을 잊어도 테스트가 잡지 못한다.
|
||||
- **이 환경에서 확인할 수 없는 것**: 실제 CI runner(원격 `git.learn.hyeonworks.com`)에서의 workflow 실행.
|
||||
- **커밋**: 하지 않았다(`human-only`). 커밋 단위 계획은 17절.
|
||||
- **짝 프론트**: 계약 변경 인계 문서를 프론트 세션 scratchpad `backend-contract-handoff.md`에 두었다.
|
||||
|
||||
|
||||
|
||||
## 17. 커밋 단위 계획
|
||||
|
||||
저장소 정책이 `human-only`라 커밋하지 않았다. 사람이 그대로 쓸 수 있는 커밋 자료(패치 세 개와 메시지)를
|
||||
repo 밖 `../clean-architecture-backend-template-commit-kit/`에 두었다.
|
||||
|
||||
2026-11-03 소유자 지시로 이 세 커밋을 브랜치 `refactor/maturity-review-2026-11`에 만들고 push했다:
|
||||
`34565130`(1), `1400dc15`(2), `5786126c`(3). 2026-11-05에 패치 세 개를 `01a8a2a70`에 차례로 적용한
|
||||
트리가 세 커밋의 트리와 각각 같음을 확인하고 자료 폴더를 지웠다. 아래는 그때의 계획 기록이다.
|
||||
|
||||
### 17.1 고른 단위와 이유
|
||||
|
||||
세 커밋으로 나눈다. 각 커밋의 트리는 이 리뷰 중에 실제로 존재했고 게이트를 돌린 상태다.
|
||||
|
||||
| 커밋 | 트리 | 그 트리에서 돌린 게이트 |
|
||||
|---|---|---|
|
||||
| 1. 리뷰 High·P1 결함 19건 | 1라운드를 합친 상태(13절) | `ci` 통과, `mainCheck`·`integrationCheck`는 MinIO 2 lane만 실패(이미지 소멸 — 2번 커밋에서 해결), optional·`performanceCheck`·`releaseCheck` 통과 |
|
||||
| 2. 남은 발견, 개발 매뉴얼, 기능 생성 명령 | 2라운드를 합친 상태(14절) | `ci`·`mainCheck`·`integrationCheck`·optional 통과 |
|
||||
| 3. 마지막 항목과 합친 뒤 드러난 결함 | 지금 상태(15·16절) | 16.2절 전부 통과 |
|
||||
|
||||
- 커밋 규칙(`design-docs/conventions/commit-and-pr.md`)은 "커밋 하나 = 논리적 변경 하나"와 PR 1,000줄 안팎을 권한다. 세 커밋은 각각 수만 줄이라 이 권고와 어긋난다.
|
||||
- 발견 하나씩 커밋하려면 라운드 사이에 손으로 합친 충돌(14.1·16.1절)을 커밋마다 다시 풀고 중간 트리마다 게이트를 다시 돌려야 한다. 그 중간 트리는 검증된 적이 없다. 검증된 경계에서만 나누는 쪽을 골랐다.
|
||||
- 리뷰어는 커밋 diff 대신 이 README의 13·14·16절 표(발견별 RED·GREEN·결정)를 따라가며 본다.
|
||||
|
||||
### 17.2 쓰는 법 (끝남)
|
||||
|
||||
자료 폴더의 스크립트가 별도 worktree에 새 브랜치를 만들고 패치 세 개를 차례로 적용해 커밋하는 방식이었다.
|
||||
위 세 커밋으로 끝났고 자료 폴더는 2026-11-05에 지웠다.
|
||||
@@ -0,0 +1,234 @@
|
||||
# 01 core·application·composition·매뉴얼 재리뷰 (2026-11-03)
|
||||
|
||||
경로는 저장소 루트 기준이다. `src/`가 앞에 붙는다.
|
||||
|
||||
## 범위
|
||||
|
||||
### 본 것
|
||||
|
||||
- 범위: `01a8a2a70..5786126c`(커밋 3개) 중 아래 pathspec. 365파일, +19,733 −3,474.
|
||||
```text
|
||||
src/domain-core src/shared-contract src/application-core src/application-notification
|
||||
src/application-fileserver src/application-objectstorage src/composition
|
||||
scripts/new-feature.sh scripts/verify-feature-scaffold.sh scripts/feature-scaffold docs/manual
|
||||
```
|
||||
- 요구사항: `docs/reviews/2026-11-01-maturity-review/README.md` 2·12·13·14·15·16절과
|
||||
`01-core-and-feature-pattern.md`(완료 기준).
|
||||
- 읽은 방식: diff가 커서 여러 번에 나눠 직접 읽었다.
|
||||
1. application-core main 전부(outbox·messaging.event·cache·operation·tenant·security·secret)와 testFixtures 계약 키트 전부.
|
||||
2. shared-contract main diff 전부와 README·CLAUDE.md 변경.
|
||||
3. 생성 명령(`new-feature.sh`, `verify-feature-scaffold.sh`)과 템플릿 29개 전부.
|
||||
4. 매뉴얼 13개 전부. 매뉴얼이 인용한 경로·클래스·규칙 이름이 실제로 있는지 스크립트로 전수 확인했다.
|
||||
5. application-notification main diff 전부. testFixtures는 계약 목록과 상속 관계 위주로 봤다.
|
||||
6. application-fileserver main diff 전부와 quota·move·cleanup 경로. 대응하는 persistence-fileserver 구현(`JpaFileQuota`, `JpaQuotaReclaim`)은 비교하려고 범위 밖에서 읽었다.
|
||||
7. composition: service-runtime(authorization·tracing), outbox-relay, durable-operation, fileserver-platform의 변경.
|
||||
- 범위 밖에서 확인용으로 읽은 것: `ApplicationBoundaryArchitectureTest`(D4·`@SystemInvoked`),
|
||||
`NamingConventionTest`·`TemplatePackageOwnership`, `DomainFeatureOnboardingContractTest`, `JpaOutboxStore.nextSequence`,
|
||||
`JsonIntegrationEventEncoder`, `GlobalExceptionHandler`, sample `WorkLogRepositoryContract`·`WorkLogReservedPayload`, `docs/testing/TESTING_STRATEGY.md` 9절.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → Critical/Important/Minor → Declined → Assessment), 읽지 않은 코드에 판정 금지, 실제 심각도로 분류 | 문서 양식 전체 |
|
||||
| `clean-architecture` | 의존 방향(안쪽만), 포트는 안쪽이 소유, 프레임워크는 바깥, composition root가 조립 | 생성 명령 출력의 계층별 의존, `@SystemInvoked`·권한 검사 위치, 계약 키트가 포트 소유 leaf에 있는지 |
|
||||
| `domain-driven-design` | 불변식은 aggregate 안, 저장소 인터페이스는 domain, 유비쿼터스 언어 | 생성 aggregate·`*Repository`·오류 코드 위치, 이벤트 tenant 범위 규칙 |
|
||||
| `codebase-design` | seam·adapter 용어, "어댑터 둘이면 진짜 seam", 인터페이스 = 호출자가 알아야 할 모든 것 | 포트 Javadoc이 약속한 것과 계약 키트가 실제로 검사하는 것의 차이, fake가 실제 adapter와 같은 interface를 지키는지 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
| 명령 | 결과 |
|
||||
| --- | --- |
|
||||
| `git diff --stat / --name-status 01a8a2a70..5786126c -- <pathspec>` | 365파일. A 180, M 148, D 12, R 25 |
|
||||
| `git worktree add <scratchpad>/rr-01 5786126c` | 실험용. 끝나고 `git worktree remove --force`로 지웠다 |
|
||||
| 변이 3개 적용 뒤 `flock … ./gradlew :application-core:test --tests TenantIdTest --tests IntegrationIdentityTest --tests InMemoryCacheRegionContractTest --continue` (load 17.4) | rc=1, 48건 중 2건 실패. M2(`TenantId` 문법에 `/` 허용) → `TenantIdTest [8] "acme/eu"` 실패(잡힘). M5(correlation 상한 128→200) → `IntegrationIdentityTest` 129자 거부 실패(잡힘). **M6(fake 캐시가 revision을 double로 비교) → 통과(살아남음)** |
|
||||
| 워크트리에서 `scripts/new-feature.sh Invoice --no-format` 후, 호출자 트랜잭션을 요구하는 저장소로 생성 계약을 상속하는 실험 테스트 1개 추가, `flock … ./gradlew :domain-core:test --tests 'dev.caskeleton.domain.invoice.*'` (load 13.4) | rc=1, 18건 중 2건 실패: 실험 테스트의 `aSavedInvoiceIsFoundByItsId`, `savingTheSameIdAgainReplacesTheStoredState`. 생성된 테스트는 전부 통과 |
|
||||
| 매뉴얼의 `` `src/…` `` `` `docs/…` `` 경로 존재 확인, 백틱 안 Java 식별자 109개 `git grep -w` | 없는 경로 0(glob 2개 제외), 없는 식별자 0(`V8_1` 파일명 접두어 제외) |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- `:app-bootstrap:architectureTest`, 실 PostgreSQL·Redis lane은 돌리지 않았다. 게이트 결과(README 16.2)를 믿었다.
|
||||
- application-notification test 디렉터리 약 60개 파일은 줄 단위로 다 읽지 않았다. 계약 상속 관계와 이름만 전수 확인했다.
|
||||
- composition:notification-platform, service-runtime tracing(07-01)은 diff를 훑기만 했다. 07 영역 판단에 맡긴다.
|
||||
- sample-portfolio는 범위 밖이다. 01-07·01-13·01-14 완료 기준에 필요한 줄만 읽었다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **트랜잭션 fake가 실제와 같은 규칙을 지킨다.** `DirectTransactionPort`가 롤백(`onRollback`), 참여 경계 실패 시 바깥 커밋 실패(doomed), 읽기 전용 표시를 갖는다(`application-core/src/testFixtures/java/dev/caskeleton/application/transaction/testkit/DirectTransactionPort.java:112-155`). 같은 `TransactionPortContract` 13건을 실 PostgreSQL의 `SpringTransactionContractTest`가 상속한다. 01-05의 핵심이 닫혔다.
|
||||
- **encoder fake가 서버 조립 오류를 실제와 같은 예외로 거부한다.** `FakeIntegrationEventEncoder.java:55-73`이 미등록 계약·목적지·payload 타입을 `IllegalStateException`으로 거부하고, `IntegrationEventEncoderContract`를 `JsonIntegrationEventEncoder`와 함께 상속한다. 01-04 결함이 단위 테스트에서 보이게 됐다.
|
||||
- **식별자 문법이 한 곳으로 모였다.** `IntegrationIdentity.java:17-31`이 문법과 상한 3개를 갖고 `EventId`·`IntegrationEventDraft`·`ValidatedIntegrationEvent`·`AggregateIdentity`가 쓴다. draft와 저장 이벤트의 correlation 상한이 128로 같아졌다. 변이 M5를 테스트가 잡는다(위 실행).
|
||||
- **relay 정지가 claim을 돌려준다.** `PublishPendingOutboxEventsUseCase.java:124-128,143-155`의 `release`와 `OutboxStorePort.releaseLease`·`markDeferred`가 생겼고, `OutboxLeaseFencingContract.java:161-213`이 in-memory와 PostgreSQL 둘 다에 같은 경우를 건다.
|
||||
- **05-01 수정이 정확하다.** 호출 전 행을 `undetermined()`로 쓴다(`application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DeliveryAttemptFactory.java:55-60`). collapse 불가 검사도 attempt 행을 만들기 전으로 옮겼다(`NotificationDispatchService.java:186-194`).
|
||||
- **권한 장치 부재를 기동에서 막는다.** `composition/service-runtime/.../authorization/PermissionEnforcementGuard.java:42-61`. 실제 web advisor의 pointcut이 class·method union이라(`MethodSecurityConfig.java:55-57`) `AopUtils.canApply` 판정과 맞는다. sample이 service-runtime과 web을 함께 띄워 실제 조합에서도 통과한다.
|
||||
- **생성 명령이 이름 목록 대신 실제 패키지 존재로 거절한다.** `scripts/new-feature.sh:89-105`. 목록이 갈라질 여지를 없앴다. 왕복 검사가 실제 Gradle 게이트를 돌리고 결과 XML까지 본다(`scripts/verify-feature-scaffold.sh:86-108`).
|
||||
- **패키지 소유 규칙이 양방향으로 검사된다.** `TemplatePackageOwnership` + 규칙 2개 + fixture 증명 테스트(`TemplatePackageOwnershipRuleTest`). 정본 표는 `application-core/CLAUDE.md:108-167` 한 곳이다.
|
||||
- **LRO 계약이 하나가 됐다.** shared-contract `operation` 패키지를 지우고 이유를 README에 남겼다(`shared-contract/README.md:298-304`).
|
||||
- **캐시 revision 순서가 포트 규칙이 됐다.** `CacheSourceRevisionOrder.java`가 길이→자리 비교로 2^53 이상도 맞게 비교하고, `CacheRecordMetadata`가 모든 provider에 같은 거부를 건다.
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| 01-01 | 닫힘 | 배치 기준표 `docs/manual/03-placement.md:21-50`, 생성 명령, `verifyFeatureScaffold`(mainCheck). 생성 결과의 계약 설계 결함은 RR-01-01 |
|
||||
| 01-02 | 닫힘 | fixture `CreateFeatureAggregateUseCase` non-final(`app-bootstrap/src/test/java/dev/caskeleton/onboarding/application/usecase/CreateFeatureAggregateUseCase.java:20`), `FeatureAggregateIdFactory extends IdFactory`. `DomainFeatureOnboardingContractTest.java:142-170`이 production ArchRule 전부(`RequiresPermissionProxyabilityTest` 포함)를 fixture에 적용. 변이는 직접 돌리지 않았다(E1) |
|
||||
| 01-03 | 결정으로 닫힘 | experimental `TenantId` 삭제, `git ls-files '*/main/*TenantId.java'` = 정본 + notification 1개. notification 쪽은 결정 15절과 Javadoc(`application-notification/.../api/TenantId.java:4-15`), 쓰기는 `WritableTenant`가 정본 문법 강제. 변이 M2 이제 잡힘(E2) |
|
||||
| 01-04 | 닫힘 | encoder의 미등록·목적지·타입 오류 → `IllegalStateException`(`adapter/outbound/support/.../JsonIntegrationEventEncoder.java:112-130`), web 400에 WARN 한 줄(`GlobalExceptionHandler.java:92-99`). 값 객체는 아직 IAE지만 WARN으로 흔적이 남는다. 매뉴얼 06장은 옛 동작을 적는다(RR-01-03) |
|
||||
| 01-05 | 닫힘(application-core) | `TESTING_STRATEGY.md` 9.1 표의 포트 전부가 계약 키트와 fake·실제 상속을 가진다(직접 grep 확인). `implements TransactionPort`는 main 1 + testFixtures 2(`DirectTransactions`는 위임 래퍼). 남은 빈틈: RR-01-04(fileserver), RR-01-06(키트가 포트 약속을 다 안 봄) |
|
||||
| 01-06 | 닫힘, 새 위험 있음 | 가드(`PermissionEnforcementGuard`) + relay `@SystemInvoked`. `@SystemInvoked`가 D4의 검사 없는 탈출구가 됐다(RR-01-02). 매뉴얼 07장이 "장치 없음"이라 적는다(RR-01-03) |
|
||||
| 01-07 | 부분 | 문법 상수 하나 + M5 잡힘. 그러나 `sample-portfolio/.../application/worklog/WorkLogReservedPayload.java:8-9`에 같은 문법·160 상한 복사본이 남아 완료 기준("main에 한 번만")을 못 채운다(RR-01-08) |
|
||||
| 01-08 | 닫힘 | `git grep shared.operation` 0건, README 기록 |
|
||||
| 01-09 | 닫힘(코드), 재발 방지 없음 | `new IntegrationEventDraft<>(`가 main에서 `IntegrationEventDrafts.java:59` 한 곳. 하지만 그것을 지키는 규칙이 없고 매뉴얼은 "헬퍼 아직 없음, 기능마다 다시 쓴다"고 가르친다(RR-01-03) |
|
||||
| 01-10 | 닫힘 | `outbound` 패키지 해체(`secret`, objectstorage `content.CallBudget`), 소유 표 + ArchUnit 2개 + 생성 명령 거절 |
|
||||
| 01-11 | 결정으로 닫힘 | 템플릿 leaf 4곳 정본 사용, 출력 고정 테스트(`SafeFileFingerprintTest`, `ObjectIdentityDigestOutputTest`). 남은 직접 구현은 vendored `messaging:*`·`grpc*`뿐(grep) |
|
||||
| 01-12 | 닫힘 | 이름 표 `application-core/CLAUDE.md:84-106`, `NamingConventionTest`가 그곳을 가리킴 |
|
||||
| 01-13 | 닫힘(범위 밖 확인) | sample `UpdateWorkLogUseCase`에 소유자 검사(r2-09) |
|
||||
| 01-14 | 닫힘 | README relay 설명 수정, 빈 패키지 3개 삭제, `*ValueTypesTest` 개명, `OutboxEventIdFactory`가 sample `application.event`로 이동, `TITLE_BLANK`→`WORKLOG_INVALID`(400) |
|
||||
| 05-01 | 닫힘 | 위 Strengths |
|
||||
| 05-07 (application 쪽) | 닫힘, 새 위험 있음 | copy가 admission·namespace 상한·예약을 거친다(`CopyFileApplicationUseCase.java:107-148`). move는 쿼터를 옮기지 않아 상한이 켜진 뒤 회계가 틀어진다(RR-01-05) |
|
||||
| 04-02 (application 쪽) | 닫힘 | `ReconciliationJobStorePort.claimDue(limit, now, lease)`, `ReconciliationJob.claimFence`. fake·PG가 `ReconciliationJobStoreContract` 공유 |
|
||||
| 06-01·06-03 (application 쪽) | 결정으로 닫힘 | `REJECTED_RETRYABLE`·`AMBIGUOUS`는 예산을 쓰지 않고 5분 상한 재시도(`PublishPendingOutboxEventsUseCase.java:181-193,236-260`, `OutboxBackoffPolicy.MAX_DELAY`). 결정 15절 |
|
||||
| 06-02 | 닫힘 | `OutboxRelayScheduler`가 `SmartLifecycle`(phase MAX), 정지 요청 → 진행 중 발행 마무리 → 나머지 release(`OutboxRelayScheduler.java:72-170`). 경쟁 조건을 읽어 봤고 문제를 찾지 못했다 |
|
||||
| 06-07 (application 쪽) | 닫힘 | `OutboxAggregateSequencePort` + `AggregateOrder.first()`, `ofOccurrence` 삭제. 계약 빈틈은 RR-01-06 |
|
||||
| 02-01 (application 쪽) | 닫힘 | `OperationalError.IDEMPOTENT_IN_FLIGHT` retryable=true, 예외 Javadoc 갱신 |
|
||||
| 05-02·05-03 (application 쪽) | 닫힘 | `CacheSourceRevisionOrder`, `CacheRecordMetadata` 검증. 계약에 2^53 이상 경우 없음(RR-01-06) |
|
||||
| TEST-F-1 (application-core) | 닫힘 | 9.1 표 + 9.2 의도 표 |
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-01-01 생성 명령이 만든 저장소 계약은 매뉴얼대로 만든 실제 adapter가 상속할 수 없다
|
||||
|
||||
- **위치**: `scripts/feature-scaffold/templates/src/domain-core/src/testFixtures/java/dev/caskeleton/domain/__feature__/testkit/__Feature__RepositoryContract.java.tmpl:26,31,48,51`
|
||||
- **무엇이 틀렸나**: 생성 계약은 `repository().save(...)`를 트랜잭션 없이 바로 부른다. 계약에 트랜잭션을 여는 자리(hook)가 없다. 그런데 매뉴얼 04장은 저장 adapter가 `CallerTransaction.require`로 호출자 트랜잭션을 요구하라고 가르친다(`docs/manual/04-persistence.md:15,66-72`). 그리고 그 adapter가 같은 계약을 상속하라고 한다(`04-persistence.md:30`, `08-testing.md:14`). 둘을 같이 지키면 계약 테스트가 실패한다. 생성 fake(`InMemory__Feature__Repository.java.tmpl:19`)도 트랜잭션을 보지 않아, 유스케이스가 `tx.inWrite` 밖에서 저장해도 fake 위 테스트는 통과한다.
|
||||
- **왜 중요한가**: 이 매뉴얼은 "새 기능의 예시는 생성 명령 출력 하나"라고 정했다(`docs/manual/README.md:53-63`). 생성물이 "fake와 실제가 같은 계약을 통과한다"는 규칙의 견본인데, 실제 adapter를 붙이는 첫 순간 그 규칙을 지킬 수 없다. 개발자는 계약을 고치거나(정답), adapter에서 `require`를 빼거나(트랜잭션 밖 저장이 조용히 커밋되는 원래 결함), 계약 상속을 포기한다. 같은 저장소의 다른 키트는 이미 hook을 가진다: sample `WorkLogRepositoryContract.java:50` `inTransaction(Supplier)`, `IdempotencyStoreContract.java:70`.
|
||||
- **발생 조건**: 생성된 기능에 매뉴얼 04장대로 JPA adapter를 붙이고 계약을 상속한다. 모든 파생 기능이 지나는 경로다.
|
||||
- **고치는 법**: 템플릿 계약에 `protected <T> T inTransaction(Supplier<T> work) { return work.get(); }`를 두고 모든 호출을 거치게 한다. domain-core는 `TransactionPort`를 볼 수 없으니 sample처럼 `Supplier` hook이면 된다. fake 쪽은 "트랜잭션 밖 save 거부"를 계약 경우로 넣을지 정한다(넣으려면 fake가 트랜잭션 표시를 받아야 한다).
|
||||
- **심각도·우선순위**: Medium / P2. 런타임 결함은 아니다. 템플릿이 복제시키는 테스트 설계 결함이다.
|
||||
- **증거**: E2. 워크트리에서 `Invoice`를 생성하고 호출자 트랜잭션을 요구하는 저장소로 생성 계약을 상속했다. `:domain-core:test` 18건 중 그 2건이 "requires an active caller transaction"으로 실패했다(트랜잭션 없이도 되는 `findById` 경우만 통과).
|
||||
|
||||
#### RR-01-02 `@SystemInvoked`가 D4 권한 규칙의 검사 없는 탈출구다
|
||||
|
||||
- **위치**: `app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:558-560`, `application-core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java:19-20`, `composition/service-runtime/.../authorization/PermissionEnforcementGuard.java:50`
|
||||
- **무엇이 틀렸나**: D4는 쓰기 유스케이스에 `@RequiresPermission`을 강제한다. `@SystemInvoked`가 붙으면 바로 `return`해 면제한다. 면제의 전제는 "bean이 아니고 전송에서 닿지 않는다"인데 이것은 Javadoc 문장뿐이다. ArchUnit에 "inbound adapter는 `@SystemInvoked` 클래스에 의존하지 않는다" 규칙이 없다. 기동 가드는 `@RequiresPermission`만 보므로 `@SystemInvoked` bean을 그냥 지나간다. AGENTS.md와 매뉴얼 07장은 이 표시를 언급하지 않는다.
|
||||
- **왜 중요한가**: 쓰기 유스케이스에 `@SystemInvoked(reason = "…")` 한 줄을 붙이고 `@Bean`으로 등록해 컨트롤러가 부르면, 권한 검사 없이 실행된다. 빌드·기동·테스트 어디서도 실패하지 않는다. 01-06이 막으려던 "조용한 인가 우회"를 다른 문으로 다시 연다. 사용자 원칙 "위험은 코드에 드러나야 한다"에 걸린다.
|
||||
- **발생 조건**: 개발자가 D4 실패를 끄려고 이 표시를 쓴다. 이름이 시스템 호출용으로 보여 막을 단서가 리뷰뿐이다.
|
||||
- **고치는 법**: (a) ArchUnit: `..adapter.inbound..`·`..bootstrap..`의 어떤 클래스도 `@SystemInvoked` 클래스에 의존하지 않는다(composition만 허용). (b) `PermissionEnforcementGuard`에 "`@SystemInvoked` 타입의 bean이 있으면 기동 실패"를 더한다. 둘 다 작다. (b)는 relay가 bean이 아닌 현재 구조와 맞는다.
|
||||
- **심각도·우선순위**: Medium / P2. 기본 조립에는 해당 bean이 없다. 생기면 권한 우회다.
|
||||
- **증거**: E1. 규칙 조건 코드와 가드 조건을 읽었다. 우회 조립을 띄워 보지는 않았다.
|
||||
|
||||
#### RR-01-03 매뉴얼이 이번 수정 뒤의 코드와 반대로 말하는 곳이 세 군데 있고, 01-09의 헬퍼를 지키는 장치가 없다
|
||||
|
||||
- **위치와 내용**:
|
||||
- `docs/manual/07-authorization.md:65-68` "web이 빠진 조립에서는 … 기동을 막는 장치는 아직 없다(리뷰 01-06)". 실제로는 `PermissionEnforcementGuard`가 있다. 같은 커밋 `1400dc15`에서 서로 다른 묶음이 만들었다.
|
||||
- `docs/manual/09-outbox-events.md:59-60` "이 규칙은 아직 기능마다 다시 쓴다 … application-core 헬퍼로 올리는 일은 리뷰 01-09 후속이다". 실제로는 `IntegrationEventDrafts`가 있고 sample과 durable operation이 쓴다. 매뉴얼은 그 이름을 한 번도 쓰지 않는다. `application-core/CLAUDE.md` 이벤트 타입 표(:72-74)와 README에도 없다.
|
||||
- `docs/manual/09-outbox-events.md:63-65` relay를 bean으로 만들지 않는 이유를 "권한 프록시가 매번 거부한다"로 적는다. 지금 relay는 `@SystemInvoked`라 권한 선언이 없다. bean이 되면 거부가 아니라 **검사 없이** 열린다(RR-01-02). 이유가 바뀌었다.
|
||||
- `docs/manual/06-errors.md:44-45` "web은 그것을 로그 없이 400으로 바꿔서". 지금은 WARN 한 줄을 남긴다(`GlobalExceptionHandler.java:97`).
|
||||
- **왜 중요한가**: 매뉴얼은 새 기능 작성자가 처음 읽는 문서이고 "매뉴얼과 정본이 다르면 정본이 맞다"는 규칙만으로는 독자가 차이를 알 수 없다. 특히 09장대로 하면 다음 기능이 `new IntegrationEventDraft<>(…)`를 직접 조립한다. 그것을 막는 규칙이 없으니 01-09가 고친 "기능마다 tenant·순서·correlation 규칙 재정의"가 그대로 돌아온다. 경로·식별자 전수 검사는 통과하므로(위 실행) 이 종류의 drift는 기계 검사로 안 잡힌다.
|
||||
- **고치는 법**: 네 문장을 고친다. 09장 "event id·correlation·순서" 절을 `IntegrationEventDrafts.draft(…)` 사용으로 바꾸고 `SINGLE_TENANT_SCOPE`·`IntegrationIdentity`를 소개한다. `application-core/CLAUDE.md` 표에 두 타입을 넣는다. ArchUnit 한 줄: `IntegrationEventDraft` 생성자 호출은 `IntegrationEventDrafts`(와 테스트)에서만.
|
||||
- **심각도·우선순위**: Medium / P2. 문서 불일치가 반복 결함(01-09)을 되살리는 경로라 Low보다 높게 본다.
|
||||
- **증거**: E1. 해당 줄과 코드를 대조했다. `git grep -l IntegrationEventDrafts -- src docs` = main 2·sample 1·test 1, docs 0.
|
||||
|
||||
#### RR-01-04 application-fileserver: 저장 포트 9개 중 7개는 공유 계약이 없고, 쿼터 fake는 실제와 다르게 답한다
|
||||
|
||||
- **위치**: `application-fileserver/build.gradle:12-17`, `application-fileserver/src/testFixtures/java/dev/caskeleton/application/fileserver/testkit/FakeFileQuotaService.java:17-20,43,57,63`, `adapter/outbound/persistence-fileserver/.../JpaFileQuota.java:62,74,91`, `docs/testing/TESTING_STRATEGY.md:192-193`
|
||||
- **무엇이 틀렸나**: persistence-fileserver가 구현하는 포트는 9개다(`CleanupQueuePort`, `ContentReferenceLedgerPort`, `FileMetadataPort`, `FileQuotaPort`, `QuotaCommitPort`, `QuotaReclaimPort`, `RecoveryQueuePort`, `StagingUploadLocatorPort`, `UploadSessionPort`). 계약 키트는 `FileMetadataPortContract`, `CleanupQueuePortContract` 둘뿐이다. 나머지는 fake가 testFixtures로 옮겨졌을 뿐 계약이 없다. 그런데 build.gradle 주석은 "fake 위에서 통과한 유스케이스 테스트는 persistence-fileserver JPA adapter가 지키는 동작에 대해 통과한 것"이라 적고, TESTING_STRATEGY 9절은 fileserver 포트를 `*PortContract`가 "맡는다"고 적는다. 실제로 갈라진 예: `FakeFileQuotaService`는 Javadoc에 "durable adapter와 같은 장부"라 쓰지만 (1) 시계가 없어 만료된 예약도 `usedBytes`에 센다(실제는 `sumReservedBytes(…, now)`로 뺀다), (2) 해제된 예약의 `commit`·`extend`를 조용히 받는다(실제는 `QUOTA_EXCEEDED`로 거부).
|
||||
- **왜 중요한가**: 05-07 수정으로 namespace 상한이 `usedBytes` 비교로 실제 거부를 하게 됐다. 그 판정에 쓰는 포트가 fake와 실제 사이에 묶여 있지 않다. 유스케이스 테스트가 녹색이어도 실제 상한 동작을 말해 주지 않는다. AGENTS.md 테스트 규칙 6과 capability 기준 5가 정확히 이것을 막으려는 규칙이다.
|
||||
- **발생 조건**: fileserver 유스케이스를 고치거나 쿼터 규칙을 바꾸고 fake 위 테스트로 검증한다.
|
||||
- **고치는 법**: 최소 `FileQuotaPortContract`(예약·연장·확정·해제·만료·`usedBytes`)를 만들어 fake와 `PostgreSqlFileserver…IntegrationTest`가 상속한다. fake에 `Clock`을 준다. 나머지 6개는 9.2처럼 "계약 없음, 이유" 표를 두거나 계약을 만든다. build.gradle 주석과 9절 문장을 사실대로 고친다.
|
||||
- **심각도·우선순위**: Medium / P2.
|
||||
- **증거**: E1. 두 구현을 나란히 읽었다. fake를 실 PG 테스트에 걸어 보지는 않았다.
|
||||
|
||||
#### RR-01-05 파일 이동이 쿼터를 옮기지 않아, 상한을 켠 배포에서 namespace 사용량이 양쪽으로 틀어진다
|
||||
|
||||
- **위치**: `application-fileserver/src/main/java/dev/caskeleton/application/fileserver/lifecycle/MoveFileApplicationUseCase.java:53-60`, `cleanup/DefaultCleanupService.java:311`, `adapter/outbound/persistence-fileserver/.../JpaQuotaReclaim.java:41-58`, `application-fileserver/.../quota/NamespaceQuota.java:19-25`
|
||||
- **무엇이 틀렸나**: copy는 대상 namespace에 예약·확정한다. move는 `metadataStore.relocate`만 하고 쿼터를 건드리지 않는다. 확정 사용량은 namespace별 예약 행의 합이라(`JpaFileQuota.committedBytes`) 파일이 B로 가도 사용량은 A에 남는다. 나중에 그 파일을 지우면 정리 서비스가 **현재** namespace B에서 회수한다. `JpaQuotaReclaim`은 B의 행에서 빼다가 모자라면 나머지를 버린다(바닥 0).
|
||||
- **왜 중요한가**: 결과는 세 가지다. B는 move로 상한을 검사 없이 넘는다. A는 없는 파일의 사용량을 영원히 들고 있어 언젠가 정상 업로드가 `QUOTA_EXCEEDED`가 된다. B의 장부는 다른 파일의 확정분까지 깎여 과소 집계된다. 05-07 이전에는 쿼터가 "기록만" 해서 틀려도 피해가 없었다. 결정 15절이 상한을 실제로 강제하게 만들면서 이 차이에 이빨이 생겼다. `NamespaceQuota`의 "Known limit"은 동시 예약 초과만 적고 move는 적지 않았다.
|
||||
- **발생 조건**: `APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`로 namespace를 둘 이상 열고 `APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT`을 설정한 배포에서 move를 쓴다. 기본값(대상 = 기본 namespace 하나, 상한 없음)에서는 생기지 않는다.
|
||||
- **고치는 법**: move를 한 트랜잭션 안에서 "B에 `requireRoom` + 예약·확정, A에서 같은 바이트 회수"로 바꾼다. 또는 상한이 설정된 동안 namespace를 바꾸는 move를 거부하고 그 사실을 `NamespaceQuota` Javadoc과 `fileserver.yml` 주석에 적는다. 어느 쪽이든 "move 뒤 A·B `usedBytes`" 단언을 계약 테스트에 넣는다(RR-01-04와 함께).
|
||||
- **심각도·우선순위**: Medium / P2. 데이터(쿼터 장부)가 조용히 틀어지지만 설정 두 개를 켠 배포에서만 생긴다.
|
||||
- **증거**: E1. 코드 경로를 읽었다. 실행 재현은 하지 않았다.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-01-06 계약 키트가 포트 Javadoc의 약속을 다 검사하지 않는다
|
||||
|
||||
- **위치·내용**:
|
||||
- `application-core/src/main/java/dev/caskeleton/application/cache/CacheSourceRevisionOrder.java:13-18`은 "float 파싱은 2^53 위를 구분 못 한다"며 공유 `CacheRegionContract`가 Redis Lua 복사본을 맞춰 준다고 적는다. 계약의 숫자 순서 경우는 `9` 대 `10`뿐이다(`CacheRegionContract.java:168-180`). **변이 M6(fake가 revision을 `Double.parseDouble`로 비교)이 `InMemoryCacheRegionContractTest`를 통과했다(E2).** Lua가 `tonumber`로 바뀌어도 계약은 못 잡는다(현재 Lua는 문자열 비교로 맞다).
|
||||
- `OutboxAggregateSequencePort.java:17-28`은 "계약이 모든 구현을 세 항목에 묶는다"고 적는다. 계약(`OutboxAggregateSequenceContract`)은 증가·독립 두 경우만 본다. "호출자 쓰기 트랜잭션 안에서만"과 "롤백된 번호는 다시 준다"는 없다. fake(`InMemoryOutboxAggregateSequences.java:14-16`)는 트랜잭션 밖 호출을 받고 롤백된 번호를 건너뛴다. JPA는 트랜잭션 밖을 거부한다(`JpaOutboxStore.java:116`).
|
||||
- `IdempotencyStoreContract.java:89,340-357`의 시간 경우는 fake에서 `elapse`가 no-op이라 공짜로 통과한다. 문서에 적혀 있지만, fake 위 유스케이스 테스트는 lease 만료·넘겨받기를 영영 볼 수 없다.
|
||||
- **고치는 법**: 계약에 `"9007199254740993"` 대 `"9007199254740992"` 경우, 트랜잭션 밖 `nextSequence` 거부 경우를 넣는다. 시간 경우는 fake에 시계를 주거나 `assumeTrue(hasClock())`로 건너뜀을 드러낸다. 포트 Javadoc의 "계약이 묶는다" 문장을 계약 범위에 맞춘다.
|
||||
- **심각도·우선순위**: Low / P3. **증거**: E2(M6), 나머지 E1.
|
||||
|
||||
#### RR-01-07 생성된 `<F>Config`가 `TransactionPort` 공급 자동 설정 순서를 적지 않는다
|
||||
|
||||
- **위치**: `scripts/feature-scaffold/templates/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/__feature__/__Feature__Config.java.tmpl:30-32`
|
||||
- **내용**: `@ConditionalOnBean({Repository, TransactionPort})`인데 `afterName`이 없다. `TransactionPort`는 `PersistenceJpaAutoConfiguration`이 만든다. 지금은 클래스 이름 알파벳 순서(`dev.caskeleton.adapter…` < `dev.caskeleton.bootstrap…`)로 우연히 먼저 처리된다. 같은 모양의 `DurableOperationAutoConfiguration.java:42-44`는 이름을 적었고, 매뉴얼 02장(:124)도 "안 적으면 조건이 그 bean을 못 본다"고 한다. 기능이 조용히 없어지는 실패라 찾기 어렵다.
|
||||
- **고치는 법**: 템플릿에 `@AutoConfiguration(afterName = "dev.caskeleton.adapter.outbound.persistence.autoconfigure.PersistenceJpaAutoConfiguration")`. 저장 adapter의 자동 설정 이름은 주석 안내대로 사람이 더한다.
|
||||
- **심각도·우선순위**: Low / P3. **증거**: E1.
|
||||
|
||||
#### RR-01-08 01-07 잔여 복사본
|
||||
|
||||
- **위치**: `sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogReservedPayload.java:8-9`
|
||||
- **내용**: `[A-Za-z0-9][A-Za-z0-9._:-]*`와 160 상한을 직접 갖는다. 같은 값이 `IntegrationIdentity.GRAMMAR`·`AGGREGATE_ID_MAX_LENGTH`다. 원래 리뷰의 다섯 곳 목록에 없던 여섯 번째 복사본이다.
|
||||
- **고치는 법**: `IntegrationIdentity.isCanonical(workLogId, AGGREGATE_ID_MAX_LENGTH)`.
|
||||
- **심각도·우선순위**: Low / P3. **증거**: E1(grep).
|
||||
|
||||
#### RR-01-09 이번에 고친 문서 옆에 남은 옛 서술
|
||||
|
||||
- **내용**: 같은 파일을 이번 범위에서 고치면서 01 영역 문서 2절의 "남음" 항목을 그대로 두었다.
|
||||
- `shared-contract/README.md:369` "1001번째 tenant부터 bucket folding이 자동 적용된다" — 구현 없음(A-5a).
|
||||
- `shared-contract/src/main/java/dev/caskeleton/shared/runtime/RuntimeEnvironment.java:33` "app-bootstrap's RuntimeProfileSnapshot" — 실제는 support leaf(A-2d).
|
||||
- `application-core/README.md:531-560` "알림 포트" 절이 application-notification의 `NotificationPort`를 설명하고, 그 아래 "Notification (값 객체)" 절 본문은 가명화 포트 설명이 섞여 있다(A-6a).
|
||||
- **심각도·우선순위**: Low / P3. **증거**: E1.
|
||||
|
||||
#### RR-01-10 왕복 검사가 생성 테스트 8개 중 4개만 "실행됨"을 확인한다
|
||||
|
||||
- **위치**: `scripts/verify-feature-scaffold.sh:96-101`
|
||||
- **내용**: `<F>Test`, `Create<F>UseCaseTest`, `<F>ControllerTest`, `<F>ConfigTest`의 결과 XML만 확인한다. `<F>IdTest`, `InMemory<F>RepositoryContractTest`, `Get<F>UseCaseTest`, `Uuid<F>IdFactoryTest`는 필터·태그 변경으로 실행되지 않아도 녹색이다. 스크립트 머리말이 막겠다고 한 "빈 녹색"이 절반 남는다.
|
||||
- **고치는 법**: 템플릿의 `src/test/**/*Test.java.tmpl` 목록에서 기대 XML을 만들어 전부 확인한다.
|
||||
- **심각도·우선순위**: Low / P3. **증거**: E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- SMTP provider adapter가 `ProviderAdapterContract`("every stable provider adapter")를 상속하지 않는 것 — 계약이 HTTP 모양이고 05 영역 판단이다. 파일 이동만 이번 범위다.
|
||||
- `JpaOutboxStore`의 첫 counter 생성 경쟁(두 생성자가 PK 충돌) — persistence-jpa, 04·06 영역.
|
||||
- `TracingSwitchImportFilter`가 Boot 4의 모든 tracing 자동 설정을 패키지 접두어로 덮는지 — 07 영역.
|
||||
- `TemplatePackageOwnershipRuleTest`가 "목록 ⊆ 실제"만 보고 반대 방향은 안 보는 것 — 새 템플릿 패키지를 목록에 안 넣으면 기능으로 분류되지만, 다른 템플릿 패키지가 import하면 규칙 2가 잡고 생성 명령은 디스크로 거절한다. 피해가 작아 제외.
|
||||
- durable operation 이벤트가 tenant가 있어도 `global` 범위로 나가는 것 — 코드 주석에 이유와 결정이 있다(`SubmitDurableOperationUseCase.java:145-147`).
|
||||
- namespace 상한의 동시 예약 초과 — 결정 15절, `NamespaceQuota` Javadoc에 명시.
|
||||
- relay가 진짜 인증 오류도 5분 간격으로 무한 재시도 — 결정 15절.
|
||||
- 서버가 만드는 값 객체(`ValidatedIntegrationEvent` 등)가 아직 IAE를 던지는 것 — WARN 로그로 흔적이 남아 01-04 목적은 달성. 따로 올리지 않는다.
|
||||
- `OutboxMetrics.refreshGauges`가 relay tick(최대 50 cycle)과 같은 스케줄러 스레드를 나눠 gauge 갱신이 늦을 수 있는 것 — 측정하지 않았다.
|
||||
- sample `POSTER_INVALID_STATE`가 상태 전이 위반을 400으로 내는 것 — sample, 범위 밖.
|
||||
|
||||
## 28개 관점 — 바뀐 관점만
|
||||
|
||||
01 영역 문서 8절 판정표 대비. 기호: O 충족, P 부분, X 미충족.
|
||||
|
||||
| # | 관점 | 이전 | 지금 | 한 줄 이유 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 2 | 구조적 성숙도 | P | O | 배치 기준표와 패키지 소유 규칙이 생기고 ArchUnit·생성 명령이 강제한다 |
|
||||
| 3 | 변경 용이성 | P | O | 식별자 문법·draft 규칙이 한 곳. 남은 sample 복사본 1곳(RR-01-08)은 Low |
|
||||
| 6 | 실패 성숙도 | P | O | 서버 조립 오류가 500+로그, relay 일시 거부가 DEAD 대신 재시도 |
|
||||
| 8 | 디버깅 가능성 | P | O | IAE 400에도 WARN 한 줄 |
|
||||
| 11 | 데이터 성숙도 | P | P | 이유가 바뀜: 이벤트 tenant 규칙은 하나가 됐고, 새로 move 쿼터 장부 drift(RR-01-05) |
|
||||
| 17 | API·계약 성숙도 | P | O | LRO 계약 한 벌, Envelope null 생략 |
|
||||
| 20 | 개발자 경험 | X | P | 매뉴얼·생성 명령·왕복 검사가 생겼다. 생성 계약이 실제 adapter를 못 받고(RR-01-01) 매뉴얼 일부가 코드와 반대(RR-01-03) |
|
||||
| 22 | 추상화 성숙도 | P | O | `IntegrationEventDrafts`로 10필드 생성자를 직접 다루지 않는다 |
|
||||
| 23 | 일관성 | X | P | TenantId·LRO·문법·이름 규칙이 정리됐다. 매뉴얼과 코드 불일치, sample 복사본이 남았다 |
|
||||
| 24 | 네이밍·의미 | P | O | 이름 규칙 정본 표, `*ValueTypesTest` 개명, 예외는 "따라 하지 말 것"으로 명시 |
|
||||
| 25 | 조직 확장성 | P | O | 기능 패키지가 템플릿 패키지와 섞이지 않게 생성 명령과 ArchUnit이 막는다 |
|
||||
| 27 | 삭제 가능성 | P | O | sample 전용 LRO 타입이 sample로 내려갔다 |
|
||||
|
||||
10 테스트·15 보안·21 Guardrail은 기호가 그대로 P다. 키트가 크게 늘었지만 RR-01-01·02·04·06이 남는다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge?** With fixes
|
||||
|
||||
**Reasoning:** 01 영역 발견 14건 중 12건이 닫히거나 결정으로 닫혔고, Critical·회귀는 없다. 다만 이번 수정이 새로 만든 탈출구(`@SystemInvoked`, RR-01-02)와, 따라 할 예시인 생성 계약이 실제 adapter를 못 받는 문제(RR-01-01), 매뉴얼이 고친 코드와 반대로 말하는 곳(RR-01-03)은 파생 서비스로 그대로 복제되므로 병합 전에 고치는 편이 싸다.
|
||||
@@ -0,0 +1,298 @@
|
||||
# 02 inbound 전송(HTTP·GraphQL·WebSocket·gRPC) 재리뷰 (2026-11-03)
|
||||
|
||||
리뷰 대상: Base `01a8a2a70` → Head `5786126c`, 영역 번호 02(slug `inbound-transports`). 원래 영역 문서는
|
||||
`docs/reviews/2026-11-01-maturity-review/02-inbound-web.md`, `03-inbound-realtime-graphql-grpc.md`다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
```text
|
||||
src/adapter/inbound src/grpc src/grpc-advanced docs/web
|
||||
docs/architecture/graphql-api-surface.txt docs/runbooks/grpc-platform-operations.md
|
||||
docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md
|
||||
```
|
||||
|
||||
`git diff --stat` 기준 188파일 +9,378 −614. 여러 번에 나눠 직접 읽었다(하위 에이전트 없음).
|
||||
|
||||
- 꼼꼼히 읽은 것: web main 전체 diff(인증·CORS·Envelope·오류 핸들러·멱등 키·rate limit·설정),
|
||||
`docs/web/http-contract.md` 전문, web README·runbook diff, web-advanced 오류 enum, web-fileserver CORS 기여,
|
||||
GraphQL 복잡도 scorer·calculator·deadline·per-parent instrumentation·interceptor 전문, WebSocket writer·handler·
|
||||
STOMP 연결 상한·구독 상한 전문, gRPC 어댑터 admission·deadline interceptor·runner·settings 전문, gRPC ledger
|
||||
port·JPA adapter·repository·entity·V002·interceptor·retention·starter 전문, ADR-GRPC-004·runbook diff.
|
||||
- 경로만 따라간 것: pathspec 밖이지만 판단에 필요한 `IdempotencyExecutor`(application-core),
|
||||
`OperationalError`·`Envelope` 계열(shared-contract), `docs/registries/error-codes.yaml`, `security.yml`,
|
||||
`IdempotencySettings`(composition:idempotency), spring-graphql 2.0.5 jar의 `BlockingHandlerMethodPredicate`(javap).
|
||||
- 훑기만 한 것: `src/adapter/inbound/messaging`(새 leaf, 06 영역 소관), web-notification 콜백 503(05-20),
|
||||
web-fileserver tus PATCH(05-12). 이 셋은 「Declined to judge」에 적었다.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿 — 계획 정렬(README 12~16절·영역 문서 완료 기준), 코드 품질, 아키텍처, 「Declined to judge」, 읽기 전용, 하위 에이전트 금지 | 발견마다 완료 기준을 코드로 대조, 수정 diff 자체의 결함 탐색 |
|
||||
| `api-and-interface-design` | 한 가지 오류 모양(Consistent Error Semantics), Hyrum's Law(관찰되는 wire 변화는 계약), Idempotency-Key 절(원자적 claim, 처리 중 중복에 대한 의도된 응답 409, 다른 본문 422, 결과 불명 3분류, 보존 기간 ≥ 재시도 경로) | `http-contract.md`와 실제 응답 대조(Tomcat 실행), 409/422/Retry-After, gRPC ledger claim·takeover·commit·purge 경쟁 |
|
||||
| `security-and-hardening` | STRIDE의 DoS(입력 크기·복잡도·연결 수 상한, timeout), CORS는 명시 목록, 인증/인가(JWT aud·role 범위), 오류 본문이 입력을 되돌려 쓰지 않음 | GraphQL 복잡도 우회, WebSocket·gRPC 한도와 종료, CORS 노출 헤더, JWT audience 필수·client role 범위, `/error` 본문의 path echo |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
모두 `git worktree add <scratchpad>/rr-02 5786126c`로 만든 worktree에서 `flock heavy.lock`으로 감싸 돌렸다.
|
||||
끝난 뒤 `git worktree remove --force`로 지웠다. 임시 테스트 원본은 scratchpad `rr-02-notes/probes/`에 남겼다.
|
||||
메인 체크아웃에는 이 문서 말고 바꾼 파일이 없다.
|
||||
|
||||
| 명령 | 실행 직전 load | 결과 |
|
||||
| --- | --- | --- |
|
||||
| `git diff --stat / git diff 01a8a2a70..5786126c -- <pathspec>` | — | 188파일 |
|
||||
| `./gradlew :adapter:inbound:graphql:test --tests '*Rr02UnionProbeTest'` (임시 테스트) | 6.14 | rc=0. `plainNested score=3368410`, `unionNested score=20`, `unionSingleNested score=20`, `unionPageOverMax score=20`(거부 안 됨), `unionFragmentSpread score=20`, `plainPageOverMax rejected=page size exceeds maximum` → RR-02-01 |
|
||||
| `./gradlew :adapter:inbound:web:test --tests '*Rr02ErrorDispatchProbeTest'` (임시 테스트, 실제 Tomcat) | 17.95 | rc=0. `GET /probe/item;x=1` → `400 {"success":true,"data":{"timestamp":…,"status":400,"error":"Bad Request","path":"/probe/item;x=1"},"meta":{…}}` → RR-02-02. 대조군 `/probe/item` 200 정상 Envelope, `/probe/missing` 404 `ROUTE_NOT_FOUND` 실패 Envelope |
|
||||
| `./gradlew -p optional-platforms :grpc:grpc-core-api:test --tests '*Rr02StaleOwnerProbeTest'` (임시 테스트, 공유 계약 fake) | 22.27 | rc=0. `bTookOver=true staleOwnerMarkFailed=accepted state=FAILED_TERMINAL cReclaimed=true` → RR-02-04 |
|
||||
| `javap` spring-graphql 2.0.5 `AnnotatedControllerDetectionSupport$BlockingHandlerMethodPredicate` | — | `CompletableFuture`를 돌려주는 resolver는 blocking으로 보지 않아 호출 스레드에서 돈다. per-parent instrumentation이 README 예시를 N+1로 오인하지 않는다(문제 없음 확인) |
|
||||
|
||||
게이트(ci·mainCheck·integrationCheck·optional·performanceCheck·releaseCheck)는 README 16.2대로 이미 통과했고
|
||||
다시 돌리지 않았다.
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 짝 프론트를 실제로 붙여 실행하지 않았다(프론트 분류기·strict 스키마의 반응은 판단하지 않음).
|
||||
- 기본 JWT 체인에서 `/error` 디스패치가 401로 바뀌는지는 코드로 추론만 했다(실행은 permit-all 체인으로 함).
|
||||
- gRPC ledger의 동시 commit 경쟁은 실 PostgreSQL로 재현하지 않았다(순차 경로만 fake로 실행).
|
||||
- Jetty·nginx WebSocket lane, gRPC Netty·fault lane, GraphQL systemTest는 다시 돌리지 않았다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **wire 모양을 원문 키로 단언한다.** `EnvelopeWireShapeTest.java:36-41,186-189`가 `doesNotExist`(null도 통과) 대신
|
||||
응답 원문의 키 집합을 비교한다. 02-02가 숨어 있던 바로 그 맹점을 막는다. Boot `JsonMapper`를 쓰는
|
||||
`@WebMvcTest`라 mix-in 등록 경로까지 함께 검증한다.
|
||||
- **JWT audience가 두 겹으로 닫혀 있다.** `SecuritySettings.java:62`(기동 거부), `JwtDecoderConfig.java:78`(검증기
|
||||
조립 거부), 미해결 `${…}` 자리표시자를 값으로 쓰지 않는 `SecuritySettings.java:87`. role은 audience client만
|
||||
읽는다(`JwtToAuthenticatedPrincipalConverter.java:94`). 다른 client role 무시 테스트가 있다.
|
||||
- **컨버터 밖 거부 응답의 writer가 하나다.** `EnvelopeResponseWriter.java:34-41`. Tomcat 기본 문자셋을 흉내 낸
|
||||
`RateLimitInterceptorTest`의 `ContainerDefaultCharsetResponse`가 02-04를 실제로 다시 잡는다(mock의 관대함에 기대지 않음).
|
||||
- **gRPC 과부하 거부가 "정상 close"다.** `GrpcCallAdmission.java:65-118`이 executor 선택 단계에서 permit을 정하고,
|
||||
거부된 호출은 handler 없이 `RESOURCE_EXHAUSTED`로 닫으며, permit은 `onComplete`/`onCancel`에서 한 번만 돌려준다.
|
||||
bounded pool reject가 스트림을 매달아 두는 io.grpc 동작을 정확히 피했다. 서버 deadline close도
|
||||
`GrpcServerDeadlineInterceptor.java:94-144`에서 직렬화했다.
|
||||
- **WebSocket 경쟁 두 건을 같은 lock 아래 재확인으로 닫았다.** `SerializedOutboundWriter.java:107`(close 뒤 offer
|
||||
예약 금지), `PlatformWebSocketHandler.java:93-124`(stop 전후 연결 1001), 큐 거부 시 구독 슬롯 반환
|
||||
`WebSocketInboundAuthorizationInterceptor.java:78`.
|
||||
- **ledger 회수·정리가 SQL 한 문장씩이다.** `GrpcOperationLedgerRepository.java:106-156` — takeover는 조건부 UPDATE,
|
||||
purge는 `FOR UPDATE SKIP LOCKED` 부분 질의 + 바깥 `state <> 'IN_PROGRESS'` 이중 조건, V002 부분 인덱스.
|
||||
- **GraphQL deadline이 값 하나다.** `GraphQlPlatformWebInterceptor.java:132-138`이 요청 context의 deadline으로
|
||||
timer를 걸고, 실행 스레드 모델별 한계를 테스트 두 개로 고정했다(README 「요청 deadline」).
|
||||
- **복잡도 scorer가 변수 기본값·포화 산술을 다룬다.** `GraphQlDocumentComplexityScorer.java:385-405`,
|
||||
`GraphQlComplexityCalculator.java:148`. 03-01 완료 기준의 네 쿼리는 모두 고쳐졌다.
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| 02-01 | 닫힘(백엔드) | `OperationalError.java:47` retryable=true, `RetryAfterAdvisor.java:19` 2초, `http-contract.md:73`, `runbook.md:41-44`, `error-codes.yaml:402-408`이 같은 문장. 짝 프론트 §6 반영은 15절 결정대로 프론트 세션 인계. 단 같은 표의 503 행이 거짓 → RR-02-03 |
|
||||
| 02-02 | 닫힘(MVC 경로) | `EnvelopeWireFormatConfig.java:33-38` mix-in, `EnvelopeWireShapeTest`. MVC 밖 `/error` 디스패치는 여전히 `success:true`+`data` → RR-02-02로 따로 |
|
||||
| 02-03 | 닫힘 | 위 Strengths 두 번째 항목. `.env.example:97` 빈 값은 기동 실패(15절 결정대로) |
|
||||
| 02-04 | 닫힘 | `EnvelopeResponseWriter.java:34-41`, `RateLimitInterceptor` reject가 이를 씀 |
|
||||
| 02-05 | 닫힘 | `CorsExposedHeaders.PLATFORM`, `SecurityConfig` 합집합, `FileserverHttpSurfaceConfiguration` 기여 bean, `CorsSecurityFilterIntegrationTest` 2건 |
|
||||
| 02-06 | 닫힘 | `EnvelopeBodyAdvice.java:77-80`(String 컨버터면 같은 mapper로 직렬화), `EnvelopeBodyAdviceTest` 3건 |
|
||||
| 02-07 | 닫힘 | `WebAdvancedError` enum + 10종 carrier, `WebAdvancedErrorMappingTest`, `RetryAfterHint` |
|
||||
| 02-08 | 닫힘 | `GlobalExceptionHandler.handleHandlerMethodValidationException`, 503→`REQUEST_TIMEOUT`, `TransportErrorHandlingTest` 2건 |
|
||||
| 02-09 | 결정으로 닫힘 | 15절(JSON 아닌 본문은 엔드포인트가 직접). 변이 ①② 대응 테스트 `JsonBodyLimitFilterTest` 2건 추가 |
|
||||
| 02-10 | 닫힘 | `WebAdapterAutoConfiguration` import 목록에서 제거, `WebMvcPlatformAutoConfigurationTest` 3건 |
|
||||
| 02-11 | 닫힘 | `WebMvcRequestIdFilter.resolveCorrelationId`가 요청 id 규칙으로 교체, 테스트 3건 |
|
||||
| 02-12 | 닫힘 | `IdempotencyKeyHeader`, sample `PosterImagePublicationController.java:64`, `FaultFixtureController.java:58` |
|
||||
| 03-01 | **부분** | 완료 기준 네 쿼리는 통과. 그러나 union 타입 필드 아래는 점수 0·page 상한 미검사(실행 확인) → RR-02-01 |
|
||||
| 03-02 | 닫힘(한계 문서화) | interceptor timer + `GraphQlDeadlineInstrumentation`, 두 실행 모델 테스트. 실행 중 resolver는 끊지 않음을 README가 명시 |
|
||||
| 03-03 | 닫힘 | README 절 + 컴파일되는 예시 `OrderCustomerBatchLoading`, `GraphQlPerParentFetchInstrumentation`, `GraphQlPerParentFetchTest` |
|
||||
| 03-04 | 닫힘 | registry 삭제, `graphql-api-surface.txt` 갱신 |
|
||||
| 03-05 | 닫힘 | `GraphQlPlatformContextMissingException`(INTERNAL + `PLATFORM_CONTEXT`) + WARN |
|
||||
| 03-06 | 닫힘 | STOMP 전송 한도 4개 키, `StompConnectionLimit`(1013), 세션당 구독 1, library handler `maxConnections` 필수. principal별 상한·토큰 재검증 없음은 README 한계로 명시 |
|
||||
| 03-07 | 닫힘 | `SerializedOutboundWriter.java:107` 재확인 + 결정적 경합 테스트 |
|
||||
| 03-08 | 닫힘 | `accepting` 플래그와 등록 뒤 재확인, `TomcatWebSocketShutdownIT` 재접속 케이스 |
|
||||
| 03-09 | 닫힘 | `GrpcServerSettings` 상한, fixed pool + admission, 서버 deadline, drain. `GrpcP1BoundaryWireTest` 1 MiB·deadline·과부하 케이스 |
|
||||
| 03-10 | 닫힘(완료 기준) | `reclaimStale`·purge·V002, 계약 테스트 fake·PG. 다만 takeover가 새 위험을 만들었다 → RR-02-04 |
|
||||
| 03-11 | **부분** | 옵션 (b)로 interceptor·retention을 조립하고 ledger bean이 없으면 기동 거부. 그래도 플래그만 켜면 검증기는 통과하고 key를 실제로 처리하는 호출자는 여전히 없다. 「소유자가 (b)를 골랐다」는 기록이 15절에 없다 → RR-02-07 |
|
||||
| 03-12 | > 08 영역 | `release.yml`은 이 pathspec 밖. README 13절 08-01+08-04+03-12 충족 |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-02-01 · union 타입 필드 아래는 복잡도 점수 0이고 page 상한 검사도 건너뛴다
|
||||
|
||||
- **위치**: `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlDocumentComplexityScorer.java:154-156`,
|
||||
`:250-260`, `:361-364`
|
||||
- **무엇이 틀렸나**: `fieldCost`는 자식 비용을 `fieldsContainer(definition.getType())`로 구한다. 필드 타입이
|
||||
union이면 `GraphQLUnionType`은 `GraphQLFieldsContainer`가 아니라 `null`이 된다. 그러면
|
||||
`selectionSetCost(… parent=null …)`가 첫 줄에서 0을 돌려준다. union 아래의 inline fragment·fragment spread는
|
||||
한 번도 방문되지 않는다. 그 안의 목록 곱셈도, `first`/`last` 상한 검사도 일어나지 않는다. 이 동작은 수정 전에도
|
||||
있었고, 03-01 수정이 건드리지 않았다. 스코어러 단위 테스트에도 union 케이스가 없다.
|
||||
- **왜 중요한가**: 검색 결과·피드처럼 union을 돌려주는 필드는 흔하다. 그런 필드가 하나라도 있으면
|
||||
`search { ... on Post { comments(first: 100000) { … } } }`가 점수 20으로 통과한다. 예산(기본 10,000)과 page 상한
|
||||
(기본 100)이 그 아래에서 꺼진다. resolver가 `GraphQlConnectionPolicy`를 직접 부르지 않으면 `first: 100000`이
|
||||
그대로 DB까지 간다. 03-01과 같은 결함 종류이고, README 1절의 "GraphQL 공개 — 사용 보류" 판단을 그대로 남긴다.
|
||||
- **고치는 법**: 부모가 union이어도 선택 집합은 내려간다. 직접 필드(union에는 `__typename`만 허용)만 건너뛰고,
|
||||
type condition이 있는 inline fragment·fragment spread는 그 타입으로 계속 점수를 매긴다. union 목록 필드 자체는
|
||||
지금처럼 `listCost`로 곱한다. scorer 테스트에 union·interface 각각 "중첩 목록 곱셈", "page 상한 초과 거부" 케이스를 넣는다.
|
||||
- **심각도·우선순위**: High · P1
|
||||
- **증거**: E2 — 임시 테스트(스키마 `search: [SearchResult!]!`, `union SearchResult = Item`).
|
||||
같은 4단 중첩이 일반 목록이면 3,368,410점, union 아래면 20점. union 아래 `paged(first: 100000)`은 20점으로 통과,
|
||||
같은 값을 일반 목록에 쓰면 `page size exceeds maximum`으로 거부.
|
||||
|
||||
#### RR-02-02 · 서블릿 오류 디스패치(`/error`) 응답이 `success:true` Envelope로 나간다
|
||||
|
||||
- **위치**: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeBodyAdvice.java:68-81`,
|
||||
`docs/web/http-contract.md:18-26,54-55`, `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/SecurityConfig.java:87-94`
|
||||
- **무엇이 틀렸나**: 컨트롤러 밖에서 생긴 오류(Spring Security firewall의 `RequestRejectedException`, 컨테이너
|
||||
`sendError`)는 서블릿 오류 디스패치로 Boot의 `BasicErrorController`에 간다. 그 컨트롤러가 돌려주는 `Map`을
|
||||
`EnvelopeBodyAdvice`가 그대로 `Envelope.ok(...)`로 감싼다. 결과는 HTTP 400인데 본문은
|
||||
`{"success":true,"data":{"timestamp":…,"status":400,"error":"Bad Request","path":"/probe/item;x=1"},"meta":{…}}`다.
|
||||
새 정본 `http-contract.md` 1절은 "실패 응답은 `success=false`, `error`, `meta`이고 `data` 키가 없다"고 약속하고,
|
||||
필터 체인 밖 오류는 "id 키가 빠질 수 있다"고만 적는다. `EnvelopeWireShapeTest`는 MockMvc라 오류 디스패치를 타지
|
||||
않아 이 경로를 못 본다. 기본 JWT 체인은 `/error`를 공개 경로에 두지 않으므로, 익명 오류 디스패치가 인증에 걸려
|
||||
원래 400 대신 401이 나갈 것으로 보인다(추론, 미실행). 샘플 체인은 GET을 모두 허용하므로 실행 결과와 같은
|
||||
`success:true` 모양이 나갈 것으로 보인다(추론).
|
||||
- **왜 중요한가**: `success`를 판별자로 쓰라는 계약을 클라이언트가 그대로 따르면 4xx를 성공으로 읽는다. 짝 프론트의
|
||||
strict 스키마는 상태 코드와 모양이 어긋난 응답을 계약 위반으로 처리한다. 본문의 `path`는 요청 경로 원문을
|
||||
되돌려 쓴다(02 영역 4.3이 404에서 막았다고 적은 것과 같은 종류). 기본 체인에서는 400이 401로 바뀌어 원인이
|
||||
인증 문제로 오진된다.
|
||||
- **고치는 법**: web leaf에 `ErrorController`(또는 `/error` 처리)를 두어 상태 코드를 `errorCodeFor`와 같은 표로
|
||||
코드에 매핑하고 `ErrorResponseFactory`로 실패 Envelope를 쓴다. `EnvelopeBodyAdvice`는 응답 status가 4xx·5xx면
|
||||
감싸지 않는다. 보안 체인에 `dispatcherTypeMatchers(DispatcherType.ERROR).permitAll()`을 더해 원래 status가 나가게
|
||||
한다. 실제 서버 테스트(오류 디스패치는 MockMvc로 재현되지 않는다)에 `;` 경로 케이스를 넣고 원문 키를 단언한다.
|
||||
- **심각도·우선순위**: Medium · P2 (동작은 수정 전부터 있었다. 새 정본 계약이 반대로 약속한다)
|
||||
- **증거**: E3 — 실제 Tomcat 임시 테스트(permit-all 체인 + `EnvelopeBodyAdvice` + `EnvelopeWireFormatConfig` +
|
||||
`WebMvcPlatformAutoConfiguration`). 기본 JWT 체인의 401 전환은 E1(코드 읽기).
|
||||
|
||||
#### RR-02-03 · 정본 계약이 `IDEMPOTENCY_UNAVAILABLE`을 "작업 실행 전에 거부"라고 적지만, complete 단계에서는 작업이 이미 돌았다
|
||||
|
||||
- **위치**: `docs/web/http-contract.md:94`, `src/adapter/inbound/web/README.md:243`,
|
||||
`src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyUnavailableException.java:7`,
|
||||
`src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:193,203,233`
|
||||
- **무엇이 틀렸나**: `runStarted`는 `action.run()`(193행)이 성공한 뒤 `complete`(203행)를 부른다. 저장소가
|
||||
`UNAVAILABLE`을 돌려주면 233행이 같은 `IdempotencyUnavailableException`을 던진다. 그런데 새 정본 표는 이 코드를
|
||||
"작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로만 적는다. 02 영역 문서 2절이 P6-new-2로 이미 지적했고
|
||||
결정 24는 "현재 동작 유지 + 문서화"였다. 이번에 만든 정본 문서가 그 거짓 문장을 다시 실었다.
|
||||
- **왜 중요한가**: 클라이언트는 이 문장을 보고 사용자에게 "적용되지 않았다"고 알린다. `inWrite` 안의 DB 효과는
|
||||
예외로 롤백되지만, action 안의 비트랜잭션 효과(외부 호출 등)는 이미 일어났다. 같은 키 재전송은 Redis 저장소에서
|
||||
claim이 `EXECUTING`으로 남아 있으면 409를 반복하다 lease 뒤 다른 판정을 받는다. "결과 불명"을 "확실히 안 함"으로
|
||||
기록하는 것은 README 4절의 반복 원인 1번과 같은 모양이다.
|
||||
- **고치는 법**: 최소한 정본 표·README 표·예외 Javadoc을 "claim 단계면 실행 전, complete 단계면 실행했을 수 있음
|
||||
(같은 트랜잭션의 DB 효과는 롤백)"으로 나눠 적는다. 더 낫게는 complete 단계에 별도 코드(예:
|
||||
`IDEMPOTENCY_COMPLETION_UNKNOWN`)를 주고 클라이언트 행동을 따로 정한다. `IdempotencyExecutorTest`에 "action 뒤
|
||||
complete UNAVAILABLE" 케이스를 넣어 어느 예외·코드가 나가는지 고정한다.
|
||||
- **심각도·우선순위**: Medium · P2
|
||||
- **증거**: E1 — 코드 경로(193→203→233)와 문서 대조
|
||||
|
||||
#### RR-02-04 · ledger에 시도(owner) 구분이 없어, takeover 뒤 옛 owner의 실패·완료 기록이 새 시도를 덮는다
|
||||
|
||||
- **위치**: `src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:75-101`,
|
||||
`GrpcOperationLedgerEntity.java:123-139`, `GrpcOperationLedgerRepository.java:106-123`,
|
||||
`src/grpc/grpc-runtime/src/main/java/dev/caskeleton/grpc/idempotency/GrpcIdempotencyInterceptor.java:182-202`,
|
||||
`docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md:61-69`
|
||||
- **무엇이 틀렸나**: takeover(`tryReclaimStale`)는 `claimed_at`만 바꾼다. `markCommitted`·`markFailed`는 identity만
|
||||
받고 "어느 시도의 기록인지"를 받지 않는다. 엔티티 검사는 `state == IN_PROGRESS` 하나다. 그래서 TTL(5분)을 넘긴
|
||||
옛 owner A가 나중에 `markFailed`를 부르면, B가 넘겨받아 실행 중인 claim이 `FAILED_TERMINAL`이 된다. 그다음 재시도
|
||||
C가 `reclaimFailed`로 다시 claim하면 B와 C가 동시에 실행된다. 또 JPA `markCommitted`는 `findById` → 상태 확인 →
|
||||
`save`라 행 잠금·`@Version`이 없다. 두 시도가 같은 순간 commit하면 둘 다 IN_PROGRESS를 읽고 둘 다 커밋한다.
|
||||
ADR은 "느린 owner의 commit"만 위험으로 적고, 옛 owner의 `markFailed` 덮어쓰기는 적지 않는다. 버린 대안 목록에도
|
||||
heartbeat 없는 fence(commit 시 claim 시각 비교)가 없다. 공유 계약 테스트에 "takeover 뒤 옛 owner의 기록" 케이스가 없다.
|
||||
- 같은 묶음의 작은 경쟁: purge가 지운 직후 같은 key의 claim은 `INSERT … ON CONFLICT`가 0을 받고 `findById`가 비어
|
||||
`IllegalStateException("… Retry the claim.")`을 던진다(`JpaGrpcOperationLedger.java:53-65`). `decide()`는 다시
|
||||
시도하지 않아 호출자는 내부 오류를 받는다. 보존 기간(24h)보다 오래된 key에서만 열리는 좁은 창이다.
|
||||
- **왜 중요한가**: 03-10 수정은 "key가 영구히 막힘"을 "TTL 뒤 넘겨받음"으로 바꿨다. 넘겨받는 순간이 바로 하류가
|
||||
멈춘 때라 옛 owner가 늦게 깨어나 기록하는 경우가 생긴다. 그때 기록이 새 시도를 덮어 같은 operation이 두 번
|
||||
돌 수 있다. 멱등성 ledger가 막으려던 결과다. 플랫폼이 아직 어디에도 채택되지 않아 지금 노출은 없다(채택 전 차단 항목).
|
||||
- **고치는 법**: claim·reclaimFailed·reclaimStale이 claim 토큰(그 시도의 `claimed_at`이나 attempt id)을 돌려주게
|
||||
한다. `markCommitted`·`markFailed`는 `UPDATE … WHERE state='IN_PROGRESS' AND claimed_at=:token`으로 바꿔 0행이면
|
||||
호출자가 롤백한다. 계약 테스트에 "takeover 뒤 옛 owner의 commit·fail은 거부", PG lane에 "동시 commit은 하나만"을
|
||||
더한다. ADR 버린 대안에 fence 안을 적거나 고른다. purge 경쟁은 claim이 행 소실을 보면 insert를 한 번 더 시도하게 한다.
|
||||
- **심각도·우선순위**: Medium · P2 (채택 전에 고친다)
|
||||
- **증거**: E2 — 공유 계약 fake로 순차 경로 실행: `bTookOver=true staleOwnerMarkFailed=accepted state=FAILED_TERMINAL cReclaimed=true`.
|
||||
JPA 동시 commit 경쟁은 E1(코드 읽기, 실 PG 미실행).
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-02-05 · `Retry-After: 2`를 "lease에 맞춰 다시 정하라"고 하지만 고칠 손잡이가 없다
|
||||
|
||||
- **위치**: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/RetryAfterAdvisor.java:14-19`,
|
||||
`docs/web/http-contract.md:80-83`, `src/composition/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencySettings.java:47-50`
|
||||
- **무엇이 틀렸나**: 정본은 "lease를 2초보다 짧게 설정한 서비스는 값을 다시 정한다"고 적는다. 그런데 2초는 web leaf의
|
||||
정적 표에 박혀 있고 설정 키가 없다. `IdempotencySettings`도 lease 하한을 2초 위로 막지 않는다.
|
||||
- **왜 중요한가**: 개발자가 따로 기억해야 하는 숨은 규칙이다. lease를 1초로 둔 서비스는 클라이언트를 lease 뒤에
|
||||
다시 오게 만든다.
|
||||
- **고치는 법**: `IdempotencySettings`에서 lease가 `IDEMPOTENT_IN_FLIGHT`의 Retry-After보다 길어야 기동하게 하거나,
|
||||
문장을 "lease를 2초 이하로 두지 않는다"로 바꾼다.
|
||||
- **심각도·우선순위**: Low · P3 · **증거**: E1
|
||||
|
||||
#### RR-02-06 · in-flight `retryable` 변경이 gRPC·GraphQL wire에도 나가는데 문서·테스트·호환성 표시가 없다
|
||||
|
||||
- **위치**: `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcStatusMapper.java:59-64`,
|
||||
`docs/registries/error-codes.yaml:404-414`
|
||||
- **무엇이 틀렸나**: `IDEMPOTENT_IN_FLIGHT`가 retryable=true가 되면서 gRPC trailer `error-retryable`(status ABORTED)와
|
||||
GraphQL extension `retryable`도 true로 바뀌었다. README 13절이 "테스트 없음"으로 남긴 상태 그대로다. registry는
|
||||
`compatibility_impact: none`이다. 같은 코드 이름 `REQUEST_TIMEOUT`이 web에서는 503·`TRANSIENT_DEPENDENCY`(이번에
|
||||
새로 만듦), GraphQL에서는 category `TIMEOUT`이다.
|
||||
- **왜 중요한가**: 관찰되는 wire 값이 바뀌면 소비자가 의존한다(Hyrum's Law). 클라이언트가 전송마다 다른 뜻을 배운다.
|
||||
- **고치는 법**: gRPC·GraphQL 매핑 테스트에 in-flight 케이스를 넣고 각 README에 한 줄 적는다. registry의
|
||||
`compatibility_impact`를 `behavior-change`로 고친다. web 쪽 timeout 코드 이름과 category를 GraphQL과 맞추거나 차이를 적는다.
|
||||
- **심각도·우선순위**: Low · P3 · **증거**: E1
|
||||
|
||||
#### RR-02-07 · 03-11: 플래그만 켜면 검증기는 통과하고, key를 처리하는 호출자는 여전히 adopter 몫이다
|
||||
|
||||
- **위치**: `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformStartupValidator.java:149-155`,
|
||||
`GrpcPlatformAutoConfiguration.java`(interceptor bean Javadoc "nothing calls this yet"), `src/grpc/CLAUDE.md:168`
|
||||
- **무엇이 틀렸나**: 검증기 문구는 "플래그가 false면 key가 받아들여지고 처리되지 않는다"고 한다. 플래그를 true로
|
||||
두면 결정 함수 bean은 생기지만 그것을 부르는 서버 단계가 없어도 기동한다. 원래 지적("운영자가 멱등 처리가 켜졌다고
|
||||
믿는다")이 좁아졌을 뿐 남는다. 또 `src/grpc/CLAUDE.md:168`의 "The owner chose (b)"는 리뷰 README 15절 결정 기록에 없다.
|
||||
- **고치는 법**: 15절(또는 ADR)에 (b) 결정과 이유를 기록한다. 검증기가 `IDEMPOTENCY` 단계 interceptor가 조립됐는지까지
|
||||
보거나, 문구를 "플래그는 결정 함수만 조립한다. 서버 단계 연결은 별도"로 고친다.
|
||||
- **심각도·우선순위**: Low · P3 · **증거**: E1
|
||||
|
||||
#### RR-02-08 · GraphQL 작은 불일치 두 건
|
||||
|
||||
- **위치**: `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlComplexityCalculator.java:124-127`
|
||||
대 `:56-60`, `context/GraphQlDeadline.java:11-22` 대 `README.md:298`
|
||||
- **무엇이 틀렸나**: ① `effectivePageSize(first, last)`는 둘 다 있으면 `first`를 고른다. 같은 클래스의
|
||||
`connectionCost`는 이번 수정으로 큰 쪽을 고른다. main 호출자는 없다. 갈라진 복사본이다. ② `GraphQlDeadline` Javadoc은
|
||||
"지금 읽는 곳은 이것뿐"이라며 셋을 나열하지만 이번에 추가한 `GraphQlDeadlineInstrumentation`이 빠졌다. README는 넷이다.
|
||||
- **고치는 법**: `effectivePageSize`를 지우거나 `connectionCost`와 같은 규칙으로 맞춘다. Javadoc 목록에 instrumentation을 넣는다.
|
||||
- **심각도·우선순위**: Low · P3 · **증거**: E1
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- 짝 프론트의 분류기·strict 스키마가 `retryable=true` 409와 `meta.page.sort: null`을 어떻게 받는지 — 다른 repo이고
|
||||
15절에서 프론트 세션에 인계했다.
|
||||
- `src/adapter/inbound/messaging`(inbox 자동 설정·마이그레이션 스트림) — 06 영역 발견(06-08)의 수정이다.
|
||||
`TransactionTemplate`에 timeout이 없다는 점만 눈에 띄었다.
|
||||
- web-notification 콜백 503+`Retry-After`(05-20)와 본문 상한 계산, web-fileserver tus PATCH(05-12) — 05 영역 소관.
|
||||
- Keycloak 기본 토큰의 `aud=account`를 audience로 넣는 운영 실수 — 코드는 설정한 값을 정확히 검사한다. 운영 문서 문제로 보고 판단하지 않았다.
|
||||
- `GlobalExceptionHandler`가 503 상태 전체를 `REQUEST_TIMEOUT`으로 읽는 것 — 지금 Spring MVC에서 503을 내는 예외가 async timeout 하나라 문제는 없다. 미래 Spring 변경 위험은 추측이라 올리지 않았다.
|
||||
- `PlatformWebSocketHandler`가 `final`이 되고 생성자 인자가 늘어난 API 변경 — 라이브러리 소비자가 템플릿 안에 없고 README가 새 시그니처를 적는다.
|
||||
- WebSocket 연결 상한 기본 1000 × send buffer 512 KiB = 최악 512 MiB — README가 노드 heap에 맞추라고 적었다. 실측하지 않았다.
|
||||
- GraphQL over WebSocket 구독에 interceptor timeout이 어떻게 걸리는지 — 이 템플릿에서 구독을 켜는 경로를 확인하지 못했다.
|
||||
- `DurableOperationController`의 id factory 교체 — 01·07 영역 결정(UUIDv7)의 일부다.
|
||||
|
||||
## 28개 관점 — 바뀐 관점만
|
||||
|
||||
| # | 관점 | 영역 | 이전 → 지금 | 이유 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 5 | 위험 가시성 | 02 | X → P | audience 필수·String·null 생략이 코드에 드러남. `/error` 모양(RR-02-02)과 503 문장(RR-02-03)이 남음 |
|
||||
| 5 | 위험 가시성 | 03 | X → P | deadline·STOMP 한도·ledger 플래그가 코드와 문서에 맞음. union 점수 구멍(RR-02-01)이 드러나지 않음 |
|
||||
| 7 | 운영 성숙도 | 03 | P → O | gRPC drain, WebSocket stop 뒤 1001, ledger 증가 runbook |
|
||||
| 8 | 디버깅 가능성 | 03 | P → O | batch context 누락이 `PLATFORM_CONTEXT`+WARN, per-parent N+1이 WARN+metric |
|
||||
| 13 | 확장성 | 03 | X → P | WebSocket 노드 연결·구독 상한, gRPC bounded pool+admission. principal별 상한은 없음(문서화) |
|
||||
| 15 | 보안 성숙도 | 02 | X → P | JWT audience 필수·client role 범위. `/error` 본문의 path echo와 상태 왜곡(RR-02-02) |
|
||||
| 17 | API·계약 | 02 | X → P | 정본 `http-contract.md`와 원문 키 테스트. `/error`·503 행이 계약과 어긋남(RR-02-02·03) |
|
||||
| 19 | 설정 성숙도 | 03 | P → O | STOMP·gRPC 한도가 검증되는 명시 키, ledger TTL·보존 키 |
|
||||
| 25 | 조직 확장성 | 02 | P → O | KEYED 헤더 추출이 `IdempotencyKeyHeader` 하나(02-12) |
|
||||
| 28 | 회복 가능성 | 03 | X → P | stale claim 회수·writer 예산 누수 해소. takeover 뒤 옛 owner 기록 fence 없음(RR-02-04) |
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? With fixes.** Critical은 없다. 02·03 발견 24건 중 21건이 닫혔고(결정으로 닫힘 1건 포함), 2건(03-01·03-11)은 부분, 1건(03-12)은 08 영역이다. RR-02-01(union 아래 복잡도 우회,
|
||||
High)이 GraphQL 공개 보류를 그대로 남기므로 GraphQL을 켜기 전에, RR-02-04는 gRPC ledger 채택 전에, RR-02-02·03은
|
||||
짝 프론트가 정본 계약을 따르기 전에 고쳐야 한다.
|
||||
@@ -0,0 +1,232 @@
|
||||
# 03 persistence 재리뷰 (2026-11-03)
|
||||
|
||||
## 범위
|
||||
|
||||
- 리뷰 범위: Base `01a8a2a70` → Head `5786126c`.
|
||||
- 본 pathspec: `src/adapter/outbound/persistence-jpa`, `persistence-mongo`, `persistence-fileserver`,
|
||||
`persistence-notification`, `docs/jpa`, `docs/mongodb`, `docs/architecture/jpa-api-surface.txt`,
|
||||
`docs/adr/ADR-JPA-003-completion-unknown.md`. 224파일, +8,176 −2,138.
|
||||
- 판단에 필요해서 pathspec 밖에서 읽은 것:
|
||||
- `application-core`: `AggregateOrder`, `OutboxAggregateSequenceContract`, `SubmitDurableOperationUseCase`, `PublishPendingOutboxEventsUseCase`의 트랜잭션 경계.
|
||||
- `adapter/outbound/messaging`: `PlatformIntegrationEventPublishAdapter`(순서 번호가 소비자에게 나가는 곳).
|
||||
- `application-notification` testFixtures: `OverlappingWrites`, `SuppressionStoreContract`, `ReconciliationJobStoreContract`.
|
||||
- `app-bootstrap`: `JpaProductionArchitectureTest`, `build.gradle`(ArchUnit 규칙이 보는 leaf 범위).
|
||||
- `docs/runbooks/outbox-dead-letter.md` §8, `docs/jpa/migration-guide.md`, `src/config/architecture/modules.json`.
|
||||
- 15절이 이 영역에 묶은 마이그레이션: grpc-ledger `V002`와 그 삭제 쿼리, sample `V8_1`과 `PosterRepositoryAdapter`.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
|---|---|---|
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항 정합, mock이 아닌 실제 동작 테스트, 마이그레이션 전략·하위 호환, Declined to judge, 심각도 보정 | 발견별 완료 기준 대조, 테스트가 단언하는 범위, 마이그레이션의 기존 데이터 영향 |
|
||||
| `jpa-patterns` | assigned id와 `Persistable`, 짧은 트랜잭션·readOnly, bulk UPDATE와 `@Version`, JDBC batch(`batch_size`, `order_inserts`), Flyway additive 마이그레이션 | 04-05·04-07·04-10·04-17·09-07. 연관관계는 **사용자 원칙(양방향 금지)을 스킬의 `mappedBy` 예시보다 우선**해서 규칙의 빈틈을 찾았다(RR-03-04) |
|
||||
| `supabase-postgres-best-practices` | `lock-skip-locked`(claim은 CTE + `FOR UPDATE SKIP LOCKED` + `UPDATE … RETURNING` 한 문장), `data-upsert`(check-then-insert 금지, `ON CONFLICT`), `schema-constraints`(제약 추가의 재실행 안전성), `lock-short-transactions`(트랜잭션 시간 제한), `query-partial-indexes`·인덱스 | 04-02·04-08·04-13의 claim·upsert, 새 counter(RR-03-01), V20·V21·V11~V13·V002의 잠금·재실행·기존 데이터 영향(RR-03-02·05) |
|
||||
|
||||
### 실행한 명령
|
||||
|
||||
모두 별도 worktree `scratchpad/rr-03`(@`5786126c`)에서 `flock heavy.lock`으로 감싸 실행했다. 끝난 뒤 `git worktree remove --force`로 지웠다. 메인 작업 트리는 바꾸지 않았다.
|
||||
|
||||
| 명령 | 실행 직전 부하 | 결과 |
|
||||
|---|---|---|
|
||||
| `./gradlew :adapter:outbound:persistence-jpa:test --tests '*RrScratchTest*'` (임시 테스트 1클래스·엔티티 3개 추가) | load 23.79 | rc=0, 3개 실행. 관찰은 RR-03-03·RR-03-04 |
|
||||
| `./gradlew :adapter:outbound:persistence-jpa:postgresqlOutboxAggregateSequenceIntegrationTest` (기존 클래스에 임시 메서드 2개 추가) | load 17.43 | rc=0, 6개 실행·skip 0. 관찰은 RR-03-01·RR-03-02 |
|
||||
|
||||
임시 테스트는 결과를 출력만 하고 실패시키지 않게 썼다. rc=0은 "결함 없음"이 아니다. 관찰값은 각 발견의 증거 칸에 적었다.
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- Mongo 컨테이너 lane(`MongoTransactionWriteConflictLaneTest`)은 직접 돌리지 않았다. 04-11은 코드로만 봤다.
|
||||
- 알림 정산 claim을 실제 2개 인스턴스로 돌리지 않았다. 공용 계약(`ReconciliationJobStoreContract`)을 읽었다.
|
||||
- V20의 CHECK 추가가 테이블을 한 번 읽는지 실측하지 않았다.
|
||||
- optional-platforms build(grpc-ledger)는 실행하지 않았다.
|
||||
- 전체 게이트는 README 16.2 결과를 그대로 썼다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **커밋 단계를 따로 분류한다.** `SpringTransaction.java:195-215`는 본문이 끝난 뒤 자기가 연 쓰기 트랜잭션을 커밋하는 동안 난 실패만 `translateCommitFailure`로 보낸다. 실 PostgreSQL 테스트가 `pg_terminate_backend`로 커밋 중 연결을 끊고 `DB_COMPLETION_UNKNOWN`·`retryable=false`를 단언한다(`PostgreSqlTransactionIntegrationTest.java:211-214`).
|
||||
- **SQLState 표가 한 벌이 됐다.** `PostgreSqlSqlStateErrorMapping.java:60-90`은 행을 직접 쓰지 않고 `PostgreSqlFailureClassifier` → `FailureCategory.operationalError()`에서 만든다. `SqlStateClassificationParityTest`가 두 경로의 결과를 모든 상태에 대해 비교한다.
|
||||
- **정산 job claim이 한 문장이다.** `JdbcReconciliationJobStore.java:56-72`는 CTE + `SKIP LOCKED` + `UPDATE … RETURNING`으로 lease와 fence를 같은 문장에서 쓴다. 이후 쓰기는 fence 조건이다. 같은 계약을 fake와 실 PG가 상속한다(`ReconciliationJobStoreContract.java:54,70`).
|
||||
- **upsert를 DB가 판정한다.** `JpaSuppressionStore.java:59-100`은 `ON CONFLICT DO NOTHING` 뒤 managed entity로 갱신한다. `OverlappingWrites.java:42`는 첫 트랜잭션을 열어 둔 채 두 번째를 시작해 경쟁을 운에 맡기지 않는다.
|
||||
- **계약 테스트가 실제 결함을 찾았다.** 선호 설정이 `jsonb` 열에 쉼표 문자열을 넣어 실 PG에서 항상 실패하던 것을 PG 계약 테스트가 드러냈고 고쳤다(`JpaPolicyStores.java:104`).
|
||||
- **bulk UPDATE 규칙이 운영 그래프에 걸린다.** `JpaVersionedBulkUpdateRule.java:51,78`은 `@Version` 엔티티 이름을 검사 대상 그래프에서 계산한다. `JpaProductionArchitectureTest.java:135`가 notification·fileserver를 포함한 운영 클래스에 적용한다.
|
||||
- **격리 수준 왕복 제거를 실측으로 고정했다.** 서버 기본값을 `repeatable read`로 둔 풀에서 `getTransactionIsolation()` 호출 0회와 `read committed` 실행을 함께 단언한다(`PostgreSqlTransactionIntegrationTest.java:322`).
|
||||
- **V21 runbook SQL을 실 PG에서 실행한다.** `PostgreSqlOutboxOrderKeyRunbookIntegrationTest`가 runbook 문서에서 SQL 블록을 읽어 돌린다. 문서가 lane의 입력으로 선언돼 있다(`persistence-jpa/build.gradle`).
|
||||
- **Mongo URI 경로 기본값의 순서가 맞다.** `MongoProfileClientSettingsAutoConfiguration.java:99`는 기본값을 가장 먼저 적용해 URI 값이 이긴다. 테스트가 Boot 표준 connection-string customizer와 함께 순서를 확인한다.
|
||||
- **V12가 남길 행의 규칙을 SQL 주석에 적었다.** 삭제 마이그레이션에 생존 규칙 4단계와 이유가 있다. 같은 규칙이 leaf `CLAUDE.md`에 적혀 있다.
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
|---|---|---|
|
||||
| 04-01 | 닫힘 | `SpringTransaction.java:195-215`, `PersistenceExceptionTranslator.java:157-182`, PG IT `:211-214`. 한계: IT는 `DataSourceTransactionManager`로 돈다. 운영은 `JpaTransactionManager`다. cause chain을 걷는 구현이라 같은 결과로 보지만 실행 확인은 안 했다 |
|
||||
| 04-02 | 닫힘 | `JdbcReconciliationJobStore.java:56-90`, 계약 `ReconciliationJobStoreContract.java:54,70`. 남은 것: RR-03-08 |
|
||||
| 04-03 | 부분 | 규칙(`SingleSidedAssociationCondition`), 가이드(`entity-mapping-guide.md:52-95`), 단방향 fixture는 들어왔다. `mappedBy` 없는 양방향이 규칙을 통과한다(RR-03-04, E3) |
|
||||
| 04-04 | 닫힘(이 영역 몫) | persistence-fileserver 테스트 4클래스(activation, caller transaction, `AssignedIdEntity`, claim SQL). 새 lane 2개가 `readinessLanes`에 등록됐다. workflow 실행은 08 영역 |
|
||||
| 04-05 | 닫힘 | `PersistenceExceptionTranslator.java:128-141`. PG IT `aVersionRaceLostAtCommitIsAnOptimisticConflict`가 `JpaTransactionManager`로 409 코드를 단언한다 |
|
||||
| 04-06 | 닫힘 | `PostgreSqlSqlStateErrorMapping.java:60-90`, `SqlStateClassificationParityTest`. 남은 이름 문제: RR-03-10 |
|
||||
| 04-07 | 닫힘 | `InboxItemJpaRepository`·`RecipientClaimSql.EXPIRE_OVERDUE`에 `version + 1`과 `clearAutomatically`. PG `InboxBulkReadVersionContractTest`·`RecipientExpiryVersionContractTest`. 한계: 규칙은 `@Modifying @Query`만 본다(Declined 참고) |
|
||||
| 04-08 | 닫힘 | `JpaSuppressionStore.java:59-100`, `JpaPolicyStores.Preferences.save`, V12, `SuppressionStoreContract.java:150`(실 PG 겹침) |
|
||||
| 04-09 | > | sample 영역. 이 리뷰에서 확인하지 않았다 |
|
||||
| 04-10 | 부분 | 쓰기·읽기 30초. JDBC 경로는 PG IT로 확인됐다. Hibernate 문장 직전 마감 초과는 분류되지 않는다(RR-03-03, E3) |
|
||||
| 04-11 | 닫힘(E1) | `SpringMongoTransactionSessionFactory.java:141-151`. 소항목(commit 재시도 대기 중 인터럽트)은 `MongoTransactionRetryCoordinator.java:150-156`. lane은 직접 돌리지 않았다 |
|
||||
| 04-12 | 닫힘 | `MongoUriOnlyClientDefaults`, customizer 순서(`:99`), `MongoUriOnlyClientDefaultsTest`, `mongo.yml` 주석 정정 |
|
||||
| 04-13 | 닫힘 | `JpaCleanupQueue`에 정책 상수·`heldClaims` 없음. lease는 인자, 토큰은 `CleanupItem`. claim 한 문장(`CleanupClaimSql`). PG `PostgreSqlFileserverReclamationIntegrationTest.java:174` |
|
||||
| 04-14 | 부분 + 결정으로 닫힘 | notification 포트 계약 대부분을 PG가 상속한다. `ConsentStorePort`·`NotificationInbox`는 15절 결정으로 닫았다. fileserver `*PortContract` 상속 |
|
||||
| 04-15 | 닫힘 | 테스트 소스 예시(`mongo/example`), `docs/mongodb/consumer-leaf-guide.md`. 가이드의 레지스트리 주장(app-bootstrap에 mongo edge가 이미 있음 등)을 `modules.json`과 대조해 맞음을 확인했다 |
|
||||
| 04-16 | 닫힘 | 두 leaf `CLAUDE.md`, notification `entity`·`repository` 분할. 부작용: RR-03-09 |
|
||||
| 04-17 | 닫힘 | `AssignedIdEntity`(`Persistable<UUID>`), `AssignedIdEntityTest` |
|
||||
| 09-02 | 닫힘(E1, 일부만 봄) | `V8_1`이 중복 사전 검사 뒤 `uq_poster_title_ci` 생성. adapter가 `saveAndFlush` 뒤 제약 이름으로 변환한다. 동시성 실측은 README 13절 기록 |
|
||||
| 09-05 | 닫힘 | 템플릿 `ISOLATION_DEFAULT` + Hikari `transaction-isolation` + 기동 검사. PG IT `:322` |
|
||||
| 09-07 | 닫힘 | `persistence-jpa.yml` batch 50·`order_inserts/updates` true, `ModuleDefaultJdbcBatchingTest` |
|
||||
| 09-09 | 닫힘 | `build.gradle`이 H2를 `testRuntimeOnly`로. lockfile의 `runtimeClasspath`에서 H2가 빠졌다 |
|
||||
| 05-01 | 닫힘(persistence 쪽) | `PostgreSqlNotificationBackgroundPassIntegrationTest`가 `DeliveryAttemptFactory`로 만든 행을 `LeaseRecoveryService`에 넣는다. 개명한 `WorkerCrashRecoveryContractTest` 테스트는 동어반복이다(RR-03-07) |
|
||||
| 06-07 | 부분 | 순서 번호를 DB counter로 바꿨다(`JpaOutboxStore.nextSequence`). 순서 키 유일 인덱스(V21)가 들어왔다. counter가 새 결함 두 개를 만들었다(RR-03-01, RR-03-02) |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-03-01 첫 counter 생성이 겹치면 정상 쓰기가 409로 거절된다
|
||||
|
||||
- **위치**: `persistence-jpa/.../outbox/jpa/JpaOutboxStore.java:114-124`, `OutboxEventJpaRepository.java:122-145`, Javadoc `JpaOutboxStore.java:108-112`.
|
||||
- **무엇이 틀렸나**: counter가 없으면 `UPDATE`가 0행을 돌려주고 `INSERT … SELECT`로 만든다. 두 트랜잭션이 같은 aggregate에서 동시에 0행을 보면 둘 다 INSERT한다. 두 번째는 첫 번째의 커밋을 기다린 뒤 PK 위반(23505)으로 실패한다. Javadoc은 "a rollback the caller retries"라고 쓰지만 재시도하는 호출자는 없다.
|
||||
- **증거**: 첫 트랜잭션이 `nextSequence` 뒤 커밋을 미루고, 두 번째가 같은 새 aggregate로 `nextSequence`를 불렀다. 첫째는 `1`. 둘째는 `PersistenceFailureException DB_UNIQUE_VIOLATION retryable=false`.
|
||||
- **왜 중요한가**:
|
||||
- 발생 조건: counter가 없는 aggregate에 쓰기 두 개가 겹칠 때. V21 배포 직후에는 기존 aggregate 전부가 counter가 없다.
|
||||
- 영향: 정상 요청이 재시도 불가 409로 거절되고 그 업무 쓰기 전체가 롤백된다.
|
||||
- 같은 leaf에 맞는 모양이 이미 있다: `JpaLiveEventReplay.java:41-48`의 `INSERT … ON CONFLICT (stream_id) DO UPDATE SET last_position = last_position + 1 RETURNING`. notification `CLAUDE.md`의 "Insert-or-update is decided by the database" 규칙과도 다르다. 같은 일을 하는 두 갈래 구현이다.
|
||||
- **고치는 법**: 한 문장으로 바꾼다.
|
||||
```sql
|
||||
INSERT INTO outbox_aggregate_sequence (tenant_scope, aggregate_type, aggregate_id, last_sequence)
|
||||
SELECT :t, :a, :i, COALESCE(MAX(e.aggregate_sequence), 0) + 1
|
||||
FROM outbox_event e WHERE e.tenant_scope = :t AND e.aggregate_type = :a AND e.aggregate_id = :i
|
||||
ON CONFLICT (tenant_scope, aggregate_type, aggregate_id)
|
||||
DO UPDATE SET last_sequence = outbox_aggregate_sequence.last_sequence + 1
|
||||
RETURNING last_sequence;
|
||||
```
|
||||
두 번째 쓰기는 첫째 커밋을 기다린 뒤 `DO UPDATE`로 2를 받는다. 행 잠금이라 커밋 순서도 그대로다. `OutboxAggregateSequenceContract`에 `OverlappingWrites` 같은 겹침 테스트를 더한다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3.
|
||||
|
||||
#### RR-03-02 V21 이행 뒤 aggregate 순서 번호가 이미 내보낸 번호보다 작아진다
|
||||
|
||||
- **위치**: seed `OutboxEventJpaRepository.java:130-145`(`COALESCE(MAX(e.aggregate_sequence), 0) + 1 FROM outbox_event`), V21 주석 `V21__outbox_aggregate_sequence.sql:8-11`, 소비자로 나가는 곳 `PlatformIntegrationEventPublishAdapter.java:102,124`, 계약 `AggregateOrder` Javadoc("consumers read it as 'which change came last'").
|
||||
- **무엇이 틀렸나**:
|
||||
- seed는 outbox에 남은 행만 본다.
|
||||
- `OutboxReaper`는 retention이 지난 PUBLISHED 행을 지운다.
|
||||
- 그래서 옛 벽시계 방식(epoch 마이크로초, 약 1.7×10¹⁵)으로 이미 발행한 aggregate도 counter가 1부터 시작한다.
|
||||
- rolling 배포 중 옛 인스턴스가 벽시계 번호를 계속 쓰면, 새 인스턴스의 counter(옛 최대+1부터)는 나중 커밋에 더 작은 번호를 준다.
|
||||
- V21 주석이 가리키는 `JpaOutboxAggregateSequences` 클래스는 없다(실제는 `JpaOutboxStore.nextSequence`).
|
||||
- **증거**: 번호 1,761,955,200,000,000인 행을 append하고 지운 뒤(reaper 흉내) `nextSequence` → `1`(E3). 소비자 영향은 추론이다. 템플릿 안에는 번호를 비교하는 소비자가 없다(E1).
|
||||
- **왜 중요한가**:
|
||||
- `AggregateOrder.ofOccurrence`는 삭제된 공개 API다. 쓰던 파생 서비스는 업데이트하면서 `nextSequence`로 옮겨야 한다.
|
||||
- 그 서비스의 소비자가 "마지막 번호보다 작으면 버린다"로 구현했다면 V21 이후 해당 aggregate의 이벤트를 모두 버린다.
|
||||
- runbook §8은 중복 키만 다루고 이 단절은 말하지 않는다.
|
||||
- V21 주석의 "rows numbered by the old clock scheme still come first"는 outbox 안에서만 참이다.
|
||||
- **고치는 법(대안)**:
|
||||
- (a) seed에 하한을 둔다. 다음 마이그레이션이 이행 시점 하한을 한 행 테이블에 기록하고, 새 counter는 `GREATEST(MAX, 하한) + 1`에서 시작한다. 벽시계를 쓴 적 없는 서비스는 하한 0. 코드로 막으므로 권한다.
|
||||
- (b) runbook에 "V21 전 모든 옛 writer 종료(mixed version 금지)"와 "소비자의 마지막 번호 초기화" 절차를 적는다.
|
||||
- (c) 계약 문서에 번호 단절을 명시하고 현상 유지.
|
||||
- V21 파일은 해시가 고정돼 주석을 고칠 수 없다. 정정은 다음 마이그레이션 주석이나 runbook에 둔다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3(seed 동작), E1(소비자 영향).
|
||||
|
||||
#### RR-03-03 JPA 경로에서 트랜잭션 마감 초과가 분류되지 않고 500이 된다
|
||||
|
||||
- **위치**: `PersistenceExceptionTranslator.java:128-141`(Spring `TransactionTimedOutException`만 본다), `SpringTransaction.java:121-126` Javadoc, `persistence-jpa/CLAUDE.md:237-238,305`, 테스트 `PostgreSqlTransactionIntegrationTest.java:273-290`(`DataSourceTransactionManager` + `JdbcTemplate`만).
|
||||
- **무엇이 틀렸나**: 마감이 지난 뒤 Hibernate가 다음 문장을 준비하면 Hibernate가 직접 `org.hibernate.TransactionException("Transaction timeout expired")`를 던진다. SQLState도 없고 Spring 타입도 아니다. 번역기는 비운다. web catch-all이 500 `INTERNAL_ERROR`로 답한다.
|
||||
- **증거**: H2 + `JpaTransactionManager` + `Timeouts(1s, 1s)`, 본문에서 1.3초 기다린 뒤 `persist`.
|
||||
- 본문 안 `flush` → `org.hibernate.TransactionException`, 번역 안 됨.
|
||||
- 커밋 시 flush → `JpaSystemException`(cause `TransactionException`), 번역 안 됨.
|
||||
- 이 예외는 JDBC 호출 전에 Hibernate가 만든다. 벤더와 무관하다.
|
||||
- **왜 중요한가**: 운영 조합은 `JpaTransactionManager`다. 문서와 Javadoc은 "마감이 지나면 `DB_QUERY_CANCELED`"를 약속하지만 주 경로에서는 500과 error 로그가 나간다. 테스트는 옆 경로(JDBC)만 본다. 롤백은 되므로 데이터 손상은 없다.
|
||||
- **고치는 법**: `SpringTransaction`이 시작 시각과 마감을 안다. 실패가 분류되지 않았고 실패 시점이 마감을 넘었으면 `DB_QUERY_CANCELED`로 분류한다. 예외 메시지를 읽지 않아도 된다. `JpaTransactionManager`로 같은 시나리오를 도는 PG 테스트를 하나 더한다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3.
|
||||
|
||||
#### RR-03-04 `mappedBy` 없는 양방향 연관관계가 금지 규칙을 통과한다
|
||||
|
||||
- **위치**: `testFixtures/.../arch/SingleSidedAssociationCondition.java:30,50`(`mappedBy` 속성만 본다), `docs/jpa/entity-mapping-guide.md:52,72,81`.
|
||||
- **무엇이 틀렸나**: 부모 `@OneToMany @JoinColumn(name = "parent_id")`와 자식 `@ManyToOne @JoinColumn(name = "parent_id", insertable = false, updatable = false)`는 한 FK를 두 필드가 가진 양방향이다. Hibernate 문서에 있는 `@JoinColumn` 양방향 모양이다. `mappedBy`가 없어 규칙은 위반 0을 낸다.
|
||||
- **증거**: 두 엔티티를 `ClassFileImporter`로 넣고 `associationsAreMappedFromOneSideOnly().check(...)` → 통과.
|
||||
- **왜 중요한가**: 사용자 원칙은 "양방향 금지"다. 가이드도 "one side only"라고 말한다. 가이드가 허용한 예외(단방향 `@OneToMany @JoinColumn`)에 자식 쪽 `@ManyToOne` 하나만 더하면 금지된 모양이 빌드를 통과한다. 읽기 전용 쪽은 같은 영속성 컨텍스트에서 바뀌지 않는다. 규칙 Javadoc이 막겠다는 "메모리와 DB 불일치"가 그대로 생긴다.
|
||||
- **고치는 법**: 규칙을 클래스 하나가 아니라 그래프로 본다. A의 연관이 B를 가리키고 B의 연관이 A를 가리키면 위반이다(같은 join column이든 `mappedBy`든). 최소한 `@ManyToOne`·`@OneToOne`에 `insertable = false, updatable = false`인 `@JoinColumn`이 있으면 위반으로 본다. 가이드 81행 문장을 실제 범위에 맞춘다. 위반 fixture로 red/green 테스트를 둔다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-03-05 V21 유일 인덱스를 잠금 아래 만들고, 고른 이유가 없다
|
||||
|
||||
- **위치**: `V21__outbox_aggregate_sequence.sql:26`, `docs/jpa/migration-guide.md:35-46`, 비교 대상 grpc-ledger `V002`.
|
||||
- **무엇**: 비동시 `CREATE UNIQUE INDEX`는 빌드 동안 `outbox_event`에 SHARE 잠금을 건다. 그동안 모든 append, 즉 outbox를 쓰는 업무 쓰기가 멈춘다. `lock_timeout`이 없어 잠금을 기다리는 동안 뒤 요청이 줄을 선다. migration-guide는 `CONCURRENTLY` + `executeInTransaction=false`를 정형으로 둔다. grpc `V002`는 비동시를 고른 이유를 적었다. V21에는 고른 방법·버린 대안이 없다. "중복이면 롤백"을 위해 트랜잭션 안을 골랐을 수 있지만 기록이 없다.
|
||||
- **고치는 법**: runbook §8에 한 줄을 더한다. "outbox가 크면 같은 정의를 `CREATE UNIQUE INDEX CONCURRENTLY`로 먼저 만든다. V21의 `IF NOT EXISTS`가 그것을 건너뛴다." 이유도 같이 적는다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-03-06 쓰는 곳 없는 `positional` helper가 두 벌이다
|
||||
|
||||
- **위치**: `persistence-fileserver/.../repository/CleanupClaimSql.java:53`(새로 복사), `persistence-notification/.../repository/RecipientClaimSql.java:80`.
|
||||
- **무엇**: 같은 정규식 helper다. 두 벌 모두 자기 단위 테스트 말고 호출자가 없다. 04-14로 bare `Connection` 테스트가 없어졌기 때문이다. `CleanupClaimSql.java:17-19` Javadoc은 "a test in this package that runs the identical text on a bare Connection"이라는 없는 소비자를 말한다.
|
||||
- **고치는 법**: 둘 다 지운다. 필요하면 persistence-jpa testFixtures 한 곳에 둔다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-03-07 테스트 이름이 단언보다 크다
|
||||
|
||||
- **위치**: `WorkerCrashRecoveryContractTest.java:94-112`, `CleanupClaimSqlTest.java:18,28`.
|
||||
- **무엇**:
|
||||
- `WorkerCrashRecoveryContractTest`의 개명 테스트는 "reconcile 대상이 된다"고 말한다. 실제로는 recovery를 돌리지 않는다. 방금 직접 insert한 evidence 값을 다시 읽어 같은지 본다. factory도 거치지 않는다.
|
||||
- 같은 클래스의 나머지 `@DisplayName` 5개는 영어다(소유자 결정 5는 한국어).
|
||||
- `CleanupClaimSqlTest`는 "잠그고 건너뛴다"를 문자열 `contains`로 단언한다.
|
||||
- 실제 동작은 `PostgreSqlNotificationBackgroundPassIntegrationTest`와 `PostgreSqlFileserverReclamationIntegrationTest.java:174`가 본다.
|
||||
- **고치는 법**: 이름을 단언 범위로 줄이거나, 동어반복 테스트를 지운다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-03-08 정산 job을 다시 claim해도 시도 횟수가 오르지 않는다
|
||||
|
||||
- **위치**: `JdbcReconciliationJobStore.java:56-72`(claim은 fence만 올린다), `:77`(`attempts`는 reschedule에서만 오른다).
|
||||
- **무엇**: 워커가 같은 job에서 매번 죽으면 lease(2분)마다 다시 claim된다. 시도 한도에 닿지 않는다. 같은 라운드의 fileserver reclaim은 시도 횟수를 올린다(`FileserverCleanupRepository.java:101`, "bounded by the same retry budget").
|
||||
- **고치는 법**: 만료된 lease를 다시 잡을 때 `attempts + 1`, 또는 `claim_fence`와 `attempts`의 차로 한도를 판단한다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-03-09 notification 엔티티의 변경 메서드가 public이 됐다
|
||||
|
||||
- **위치**: `persistence-notification/.../entity/DeliveryAttemptEntity.java:133,199,288`, `persistence-notification/CLAUDE.md:16`, 비교 `persistence-fileserver/.../entity/AssignedIdEntity.java:23`.
|
||||
- **무엇**: 04-16 패키지 분할로 생성자·`completeWith`·`claimSuppressionSideEffect` 등이 public이 됐다. "entity never leaves the leaf"는 글로만 있다. 같은 라운드의 fileserver는 "leaf's public surface is a ceiling"으로 반대로 했다. 두 leaf가 "같은 규칙"이라 했지만 공개 범위 규칙은 다르다.
|
||||
- **고치는 법**: `..notification.platform.entity..`를 leaf 밖에서 쓰지 못하게 ArchUnit 규칙을 둔다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-03-10 `FailureCategory.TRANSACTION_TIMEOUT`의 이름과 뜻이 다르다
|
||||
|
||||
- **위치**: `persistence-jpa/.../api/error/FailureCategory.java:46-52`.
|
||||
- **무엇**: 이 범주는 이제 25P03(idle 세션 종료)만 뜻하고 재시도 가능 코드로 간다. 실제 트랜잭션 시간 초과(Spring 마감)는 `QUERY_TIMEOUT`/`DB_QUERY_CANCELED`다. 이름만 보면 "트랜잭션 timeout은 재시도 가능"으로 읽힌다. 라이브러리 예외 `TransactionTimeoutException`도 같은 뜻이다.
|
||||
- **고치는 법**: 공개 API(`jpa-api-surface.txt`)라 이름 변경은 호환성 비용이 있다. 지금은 Javadoc 첫 문장에 "Spring 트랜잭션 timeout이 아니다"를 적고, 다음 호환성 깨짐 때 `IDLE_IN_TRANSACTION_TIMEOUT`으로 바꾼다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- V20의 `ADD COLUMN … CHECK`가 기존 행 검사를 위해 테이블을 한 번 읽는지 — 실측하지 않았다. outbox는 reaper로 크기가 묶여 있어 영향이 작을 것으로 본다.
|
||||
- V12 생존 규칙이 `scope`·`notification_category`를 보지 않는 것 — 중복은 같은 webhook 경쟁에서 생겨 두 행의 scope가 같을 것으로 보지만 실제 데이터로 확인하지 않았다. 키는 수정 전 finder와 같은 `(tenant, target, reason)`이다.
|
||||
- V11 배포 중 옛 인스턴스의 autocommit claim이 잠시 남는 것 — 배포 절차 문제이고 모든 인스턴스가 바뀌면 사라진다.
|
||||
- `JpaTransactionManager`에서 커밋 중 연결 단절 — cause chain을 걷는 구현이라 같은 결과로 보지만 실행하지 않았다(04-01 한계로 적음).
|
||||
- `afterCommit` 콜백 실패가 커밋 단계로 분류돼 "결과 불명"이 되는 경우 — 실제로는 커밋된 뒤라 안전한 쪽이다.
|
||||
- `JpaVersionedBulkUpdateRule`이 `JdbcTemplate` 문자열 SQL을 보지 않는 것 — 지금 `JdbcTemplate` UPDATE 대상(정산 job 등)에는 `@Version` 엔티티가 없어 위반이 없다.
|
||||
- 30초 기본 제한이 긴 작업을 끊는지 — outbox relay는 publish를 트랜잭션 밖에서 한다(`PublishPendingOutboxEventsUseCase.java:109,148,202,241,264`). 나머지 `inWrite` 호출처 약 50곳은 전수 확인하지 않았다.
|
||||
- `HikariPoolConstraintValidator`가 `"2"` 같은 숫자 표기를 거부하는 것 — 엄격한 쪽이라 결함으로 보지 않는다.
|
||||
- grpc-ledger `V002` — 읽기만 했다. 빈 테이블 전제와 `CONCURRENTLY` 수동 절차가 주석에 있고 삭제 쿼리 조건과 부분 인덱스 조건이 맞다.
|
||||
- 04-09·09-02의 sample 코드 — sample 영역이라 마이그레이션과 예외 변환만 봤다.
|
||||
|
||||
## 28개 관점 — 바뀐 관점만
|
||||
|
||||
| 관점 | 원래 | 지금 | 이유 |
|
||||
|---|---|---|---|
|
||||
| 5 위험 가시성 | X | P | claim 잠금·bulk version·`mappedBy` 양방향이 코드와 규칙으로 드러났다. 남음: 두-owner 양방향 통과(RR-03-04), 없는 재시도를 약속하는 Javadoc(RR-03-01) |
|
||||
| 6 실패 성숙도 | X | P | 커밋 결과 불명·버전 충돌·시간 제한이 처리됐다. 남음: Hibernate 마감 초과 500(RR-03-03), counter 경쟁 409(RR-03-01) |
|
||||
| 26 Ownership | P | O | 분리 leaf 두 곳에 가까운 `CLAUDE.md`가 생겼다. PG 테스트가 persistence-jpa에 남은 이유와 위치가 문서에 있다 |
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? With fixes.**
|
||||
|
||||
원래 High(04-01·04-02)와 P1(04-03·04-04)은 코드와 실 DB 테스트로 닫혔다(04-03은 빈틈 하나). 다만 06-07 수정으로 들어온 순서 번호 counter가 첫 생성 경쟁에서 정상 쓰기를 409로 거절하고(RR-03-01, E3) 이행 때 번호를 되돌리므로(RR-03-02, E3), 벽시계 번호를 쓰던 서비스에 배포하기 전에 두 건을 고친다. RR-03-03·04는 같은 묶음에서 고치는 것이 싸다.
|
||||
@@ -0,0 +1,210 @@
|
||||
# 04 outbound capability 재리뷰 (2026-11-03)
|
||||
|
||||
## 범위
|
||||
|
||||
- 리뷰 범위: Base `01a8a2a70` → Head `5786126c`. 경로는 `src/`를 생략한다.
|
||||
- 본 pathspec: `adapter/outbound/{support, identifier, redis-runtime, redis-sdk, cache-redis, httpclient, objectstorage, notification, fileserver}`, `docs/{httpclient, notification, fileserver}`, `infra/redis-sdk`, `infra/minio`. 238파일, +8,942 −1,682.
|
||||
- 발견 ID: 원 리뷰 `05-outbound-capabilities.md`의 05-01~05-23. 고친 코드가 pathspec 밖(`application-notification`, `application-fileserver`, `web-fileserver`, `persistence-fileserver`)에 있는 발견은 그 줄을 읽어 상태만 판정했다. 그 파일의 diff 전체는 다른 영역 몫이다.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 본 것 |
|
||||
|---|---|---|
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿(계획 정렬, 새 결함, Declined to judge, 읽기 전용, 하위 에이전트 금지) | 출력 양식 전체 |
|
||||
| `performance-optimization` | 연결 pool 고갈 신호, "pool을 키우기 전에 누가 연결을 잡는지 찾는다", timeout이 대기열을 숨기는지 | Redis SCRIPT lane 공유(RR-04-02), 실패 뒤 연결 폐기로 생기는 재연결, rate-limit 대기 상한 |
|
||||
| `observability-and-instrumentation` | 실패 원인이 신호에 맞게 남는지, health 상태 순서, 원인이 다른 실패를 같은 신호로 세지 않는지 | breaker가 호출자 deadline 중단을 상대 장애로 셈(RR-04-01), `DEGRADED` 순서, MinIO 공급 실패 메시지, JDK 스트림의 미분류 `IOException`(RR-04-03) |
|
||||
| `security-and-hardening` | 자원 남용 상한(DoS), 인가 회귀 방지, 비밀값, replay 창, 공급망 | 파일 서버 쿼터·소유자 검사(RR-04-04), SNS replay 창 1h, MinIO 커뮤니티 fork digest·mirror override, ACL probe |
|
||||
|
||||
### 실행한 명령
|
||||
|
||||
| 명령 | 결과 |
|
||||
|---|---|
|
||||
| `git diff --stat/--numstat 01a8a2a70..5786126c -- <pathspec>` | 238파일. leaf별 변경 규모 확인 |
|
||||
| `git worktree add <scratchpad>/rr-04 5786126c` 후 임시 테스트 3개를 넣고 `flock … ./gradlew :adapter:outbound:httpclient:test --tests '…Rr*ProbeTest' --console=plain -i` | 아래 세 줄. 모두 BUILD SUCCESSFUL |
|
||||
| `RrStreamingBodyProbeTest`: 헤더 즉시, 본문 30바이트를 100ms마다 1바이트(약 3초), 기본 timeout(response-header 2s, read-idle 3s, total 4s) | APACHE `bytesRead=30 elapsedMs=2994 COMPLETED`. **JDK `bytesRead=20 elapsedMs=2010 FAILED IOException: closed`** |
|
||||
| `RrDeadlineBreakerProbeTest`: 600ms 뒤 200을 주는 건강한 서버, breaker 창 5, 호출자 deadline 200ms로 5회 → 예산 넉넉한 호출 1회 | APACHE·JDK 모두 5회 `HttpDeadlineExceededException` 뒤 **`HttpCircuitOpenException`**, 서버 요청 수 5 |
|
||||
| `RrDeadlinePostProbeTest`: 비멱등 POST, 서버 800ms 지연, 호출자 deadline 300ms | APACHE·JDK 모두 `HttpAmbiguousExecutionException`, evidence `SENT_NO_RESPONSE` (기대대로) |
|
||||
| `javap -c` Spring 7.0.9 `JdkClientHttpRequest$TimeoutHandler`(Gradle cache jar) | timeout이 끝나면 응답 future를 취소하고 본문 stream을 닫는다. timer는 stream `close()`에서만 취소된다 |
|
||||
| `git worktree remove --force <scratchpad>/rr-04` | 임시 테스트와 함께 삭제 |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 전체 게이트는 다시 돌리지 않았다(README 16.2 결과를 읽기만 했다).
|
||||
- Redis 컨테이너 lane, Redis topology lane, MinIO 계약·fault lane, Toxiproxy lane, PostgreSQL lane은 실행하지 않았다.
|
||||
- SCRIPT lane 경합(RR-04-02)과 move 쿼터 우회(RR-04-04)는 코드와 설정 숫자로만 판정했다(E1).
|
||||
- 다중 인스턴스 경쟁, 실제 SES/SMTP 발송, TLS 소켓을 공용 타이머 스레드에서 닫을 때의 지연은 보지 않았다.
|
||||
- `application-*`, `web-fileserver`, `persistence-fileserver`의 diff 전체는 읽지 않았다. 발견 판정에 필요한 줄만 읽었다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- Redis 연결 실패가 "보내지 않음"으로 분류된다. 연결을 여는 단계의 실패를 `RedisLaneUnavailableException`으로 감싼다(`redis-runtime/.../RedisRuntimeOwner.java:245`). 대기가 끝난 lease는 pool에 돌려주지 않고 버린다(`cache-redis/.../SemanticRedisCall.java:146-155`).
|
||||
- renew가 자기 Lua 프로그램을 갖는다(`IdempotencyScripts.java:145-181`). 잃어버린 응답의 재시도는 "시작 revision + 요청 lease"가 같을 때만 `ALREADY`다. lease가 다르면 `OPERATION_CONFLICT`라 호출자가 갖지 않은 lease를 가졌다고 믿지 않는다.
|
||||
- revision 순서가 포트(`CacheRecordMetadata`)에서 정해지고, Lua 사본(`CacheScripts.java:56`)과 fake 사본을 `CacheRegionContract`가 fake와 실 Redis 양쪽에서 같은 표로 묶는다.
|
||||
- HTTP 결과 불명 판정이 재시도 규칙보다 먼저다(`DefaultRetryEligibilityEngine.java:32`). 비멱등 POST가 호출자 deadline으로 잘려도 `HttpAmbiguousExecutionException`이 난다(위 probe, E3).
|
||||
- Apache가 쓰기 시작 시점을 알린다(`SignallingRequestExecutor`). TLS·connect 실패가 더는 "보냈을 수 있음"이 되지 않는다. 401 토큰 갱신은 재시도가 허락될 때만 한다(`DefaultGenericHttpGateway.java:258`).
|
||||
- 설정 실수를 기동에서 막는다. 0 timeout(`ClientProfileValidator.java:138`), `max-attempts` 상한 5(`:265`), breaker 범위 검사, 동작 없던 키 6개 삭제, 이름 없는 예산도 profile 단위로 제한(`RestClientRuntimeFactory`).
|
||||
- MinIO 이미지 참조가 evidence 파일 한 곳이다. mirror override는 같은 digest만 받는다(`MinioQualificationImage.java`). compose 기본값을 테스트가 대조한다(`ComposeMinioImageMatchesEvidenceTest`). evidence의 측정 4줄을 lane이 매번 단언한다(`MinioManagedObjectContractTest.java:125,212`).
|
||||
- S3 mutation의 5xx를 `INDETERMINATE`로 바꿨다(`S3ProviderErrorMapper.java:69`). 쓰기 뒤 5xx를 "반영 안 됨 확정"으로 읽지 않는다.
|
||||
- SMTP 실패가 reply code·연결 거절·인증 실패로 나뉜다(`JavaMailSenderSmtpDispatch.java:68-104`). 근거가 없으면 보수적으로 "commit됨"을 유지한다.
|
||||
- module-defaults 파일명·키 중복이 기동을 멈춘다(`ModuleDefaultsEnvironmentPostProcessor.java:65,84`). strict binder가 list 원소 둘째 단계 이하 오타도 거부한다(`StrictSettingsBinder.java:281-389`). 낮은 우선순위 출처의 list 원소는 예전처럼 봐준다.
|
||||
- 파일 copy가 업로드와 같은 admission·쿼터 예약·대상 namespace 허용 목록을 거친다(`CopyFileApplicationUseCase.java:91-136`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
|---|---|---|
|
||||
| 05-01 | 닫힘 | factory가 `ProviderExecutionEvidence.undetermined()`로 행을 만든다(`DeliveryAttemptFactory.java:60`). requeue는 PROVEN+false만(`LeaseRecoveryService.java:101-144`) |
|
||||
| 05-02 | 닫힘 | 전용 `RENEW` Lua(`IdempotencyScripts.java:145-181`), `RedisIdempotencyStoreAdapter.java:185-210`. 실 Redis renew는 `LiveRedisSemanticPortsTest.java:452`가 mainCheck lane에서 본다. 계약 클래스 전체는 게이트 밖(RR-04-05) |
|
||||
| 05-03 | 닫힘 | `REPLACE_IF_REVISION_NEWER`(`CacheScripts.java:56`), 의도별 분기(`RedisCacheRegionAdapter.java:268-338`), `CacheRegionContract.java:151-195` |
|
||||
| 05-04 | 닫힘 | 무효화 marker(`RedisCacheRegionAdapter.java:356,409-425`), miss도 condition 반환, stampede 보호 없음 문서화, CLAUDE.md jitter 문장 삭제. 새 부작용은 RR-04-02 |
|
||||
| 05-05 | 닫힘 | `CircuitBreakerStatusPolicy`(5xx·408·429만), RETURN_RESULT 5xx 집계, profile별 breaker 키. 새 결함 RR-04-01 |
|
||||
| 05-06 | 닫힘 | `AttemptDeadline` scope, Apache cancel(`DeadlineAwareApacheRequestFactory.java:30`), JDK·Jetty 상한, Toxiproxy lane을 mainCheck에(`httpclient/build.gradle` mainCheck). JDK 스트리밍 본문 문제는 RR-04-03 |
|
||||
| 05-07 | 닫힘 | copy에 admission·쿼터·허용 목록(`CopyFileApplicationUseCase.java:91-136`), `namespace-limit` 신설. move 경로 우회는 RR-04-04 |
|
||||
| 05-08 | 닫힘 | `FakeFileAccessPolicy`가 descriptor 소유자를 검사(`FakeFileAccessPolicy.java:38-46`), copy·move 소유자 거부 테스트(`FileLifecycleUseCasesTest.java:321,434`) |
|
||||
| 05-09 | 결정으로 닫힘 | 15절 결정(`pgsty/minio` digest). 참조 한 곳, digest 고정 mirror override, `PinnedImageUnavailableException`, compose 대조 테스트 |
|
||||
| 05-10 | 닫힘 | collapse 검사가 attempt 전 `failBeforeAttempt` 경로(`NotificationDispatchService.java:186-191`) |
|
||||
| 05-11 | 닫힘 | SMTP 분류(`JavaMailSenderSmtpDispatch.java:76-104`), SES 사전 오류를 `ProviderCallNotStartedException`으로(`SesNotificationProviderAdapter.java:147-155`, `SesRequestMapper.java:93`). 작은 결함 RR-04-11 |
|
||||
| 05-12 | 닫힘 | PATCH가 append 결과로 응답, status 재조회 삭제(`TusController.java:183-198`) |
|
||||
| 05-13 | 닫힘 | cleanup 기본 on(`FileserverPlatformSettings.java` Cleanup, `fileserver.yml:101`), 끄면 WARN(`FileserverCleanupDisabledConfiguration.java:36`) |
|
||||
| 05-14 | 닫힘 | 결과 불명 우선(`DefaultRetryEligibilityEngine.java:32`), `RequestWriteSignal`, 더 구체적 evidence 유지(`BlockingAttemptExecutor` `withMoreSpecificEvidence`). probe로 POST deadline 중단도 확인(E3) |
|
||||
| 05-15 | 닫힘 | 키 6개 삭제, 0 timeout 거부, `max-attempts` 상한, 이름 없는 예산 제한, binder list 원소 검사 |
|
||||
| 05-16 | 부분 | 계약이 포트 소유 testFixtures로 이동(notification·fileserver·objectstorage·cache·idempotency), Redis 컨테이너 lane·Toxiproxy lane이 mainCheck에. 남음: `LiveRedisIdempotencyStoreContractTest`가 어느 게이트 lane에도 없음(RR-04-05), SES/SMTP 실제 벤더 테스트 없음(GreenMail 등 0건) |
|
||||
| 05-17 | 부분 | 연결 실패 → notSent, 실패 lease 폐기, rate-limit 대기 상한. 남음: 새 연결 열기는 caller deadline이 아니라 connect timeout 2s로 묶임(코드 주석에 명시, `RedisEdgeRateLimitAdapter.java:123-127`). 폐기가 SCRIPT lane 재연결을 늘린다(RR-04-02) |
|
||||
| 05-18 | 부분 | Redis prefix 예외는 결정으로 닫힘(`cache-redis/CLAUDE.md` 예외 절). notification `@Value` 기본값 중복은 남음: `NotificationCallbackMvcController.java:59`(`65251`), `NotificationSubmissionConfiguration.java:91`(`ko-KR`). 같은 값이 settings·yml에도 있다(세 벌) |
|
||||
| 05-19 | 닫힘 | 권한 매핑이 각 module-defaults로(`notification.yml:29-33`, `fileserver.yml:24-27`), `security.yml:32`에는 설명만 |
|
||||
| 05-20 | 닫힘 | replay 창 기본 1h(`SesCallbackAdapter.SNS_HTTP_RETRY_HORIZON`), 인증서 실패는 `CallbackVerificationUnavailableException` |
|
||||
| 05-21 | 부분 | README·CLAUDE.md 갱신, RFC 4231 벡터 테스트, 안 쓰는 edge 삭제. 합친 뒤 `package-info.java`가 다시 내용과 어긋남(RR-04-06) |
|
||||
| 05-22 | 닫힘 | finalize가 writer lease를 잡고 token으로 해제(`FinalizeUploadApplicationUseCase.java:56-62`) |
|
||||
| 05-23a | 닫힘 | 선언 길이 0이면 첫 바이트 거절(`LocalBlockingContentStore.java:146-147`) |
|
||||
| 05-23b | 닫힘 | mutation 5xx → `INDETERMINATE`, PUT 재시도 불가 이유 주석(`S3AsyncClientFactory.java:38-42`) |
|
||||
| 05-23c | 닫힘 | DROP 결과 저장(`NotificationSubmissionService.java:208,231`) |
|
||||
| 05-23d | 닫힘 | 파일명·키 중복 기동 실패(`ModuleDefaultsEnvironmentPostProcessor.java:60-93`) |
|
||||
| 05-23e | 닫힘(조건부) | `management.endpoint.health.status.order`(`cache-redis.yml:86`). 순서는 cache-redis가 싣고 상태는 redis-runtime이 낸다(RR-04-10) |
|
||||
| 05-23f | 닫힘 | dedup 기본 off, 켜면 조립 거부(`RateLimitPolicy.java:36-38`, `RedisEdgeRateLimitAdapter.java:76-89`) |
|
||||
| 05-23g | 닫힘 | 재시도 허락 뒤에만 토큰 갱신(`DefaultGenericHttpGateway.java:258-262`) |
|
||||
|
||||
회귀로 판정한 발견은 없다. 다만 수정이 새 결함을 만든 발견이 넷이다(05-04·05-17 → RR-04-02, 05-05+05-06 → RR-04-01, 05-06 → RR-04-03, 05-07 → RR-04-04).
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-04-01 호출자 deadline으로 끊은 시도를 breaker가 상대 장애로 센다
|
||||
|
||||
- 위치: `httpclient/.../resilience/AttemptResiliencePipeline.java:111-113`, `restclient/BlockingAttemptExecutor.java:114`(pipeline 호출), `:218-235`(`finish`), `apache/DeadlineAwareApacheRequestFactory.java:30`.
|
||||
- 무엇이 틀렸나: 05-06 수정으로 진행 중 시도가 deadline에서 취소된다. 취소된 시도는 엔진 예외로 pipeline을 빠져나간다. pipeline은 모든 예외를 `circuitBreaker.onError`로 기록한다. `finish()`가 결과를 `DEADLINE_EXCEEDED`로 바꾸는 것은 그 뒤다. 그래서 breaker는 "상대 장애"로 이미 셌다. `finish()` 주석 자신이 "deadline 중단을 transport 장애로 보고하면 건강한 상대를 오판한다"고 적는데, breaker에는 그 구분이 없다.
|
||||
- 왜 중요한가: `HttpOperation.deadline()`으로 남은 요청 시간을 넘기는 호출자가 있으면, 정상 응답 시간보다 예산이 짧은 호출이 쌓여 circuit이 열린다. 열리면 그 profile의 모든 호출이 기본 60초 동안 거절된다. 05-05와 같은 피해(상대는 정상인데 기능 전체가 멈춤)다. 05-06 전에는 응답이 늦게라도 도착해 성공으로 기록됐다. 이 수정이 만든 동작이다.
|
||||
- 증거: E3. `RrDeadlineBreakerProbeTest` — 600ms에 답하는 서버, 창 5, deadline 200ms 호출 5회 뒤 예산 넉넉한 호출이 Apache·JDK 모두 `HttpCircuitOpenException`. 서버는 요청 5개만 받았다.
|
||||
- 고치는 법: 시도 scope가 만료돼 끝난 실패는 breaker에 기록하지 않는다(Resilience4j `releasePermission()` 또는 ignore). 판정은 `AttemptDeadline.Scope.expired()`로 pipeline 안에서 한다. profile `total-call`로만 끝난 경우를 계속 실패로 셀지는 따로 정해 주석에 남긴다. 위 probe를 회귀 테스트로 둔다.
|
||||
- 가이드 심각도·우선순위: Medium / P1 (호출자가 deadline을 넘길 때만 도달, 도달하면 High와 같은 피해).
|
||||
|
||||
#### RR-04-02 캐시 조건부 쓰기가 멱등성·rate-limit·lease와 8개짜리 SCRIPT lane을 나눠 쓴다
|
||||
|
||||
- 위치: `cache-redis/.../cache/RedisCacheRegionAdapter.java:135-136,262-268`, `README.md:183-187`. lane 공유: `RedisIdempotencyStoreAdapter.java:88`, `RedisEdgeRateLimitAdapter.java:71`, `RedisDistributedLeaseAdapter.java:85`. 크기: `redis-runtime/.../RedisRuntimeSettings.java:458`(`maximum-script-connections` 8). 실패 lease 폐기: `SemanticRedisCall.java:146-155`.
|
||||
- 무엇이 틀렸나: 05-03·05-04 수정 뒤 write condition이 있는 기록은 모두 SCRIPT lane으로 간다. README가 권하는 정상 사용(조회가 준 condition으로 기록)이 곧 모든 캐시 채우기다. 그 lane은 pod당 연결 8개이고, 같은 lane에서 멱등성 claim과 요청 경로의 rate-limit이 돈다. lease는 호출마다 연결 하나를 독점한다. 또 05-17 수정으로 시간 초과(캐시 200ms)된 lease는 버려진다. 다음 호출은 새 연결을 연다. 새 연결은 caller deadline이 아니라 connect timeout 2s로 묶인다.
|
||||
- 왜 중요한가: Redis가 느려지거나 region 무효화로 미스가 몰리면 캐시 채우기가 8개 연결을 차지한다. 그동안 멱등성 claim은 최대 2s 기다리다 `UNAVAILABLE`로, rate-limit은 deadline까지 기다리다 실패 정책으로 간다. 시간 초과마다 연결을 닫고 다시 열어 느린 Redis에 재연결 부하가 더해진다. 캐시는 "끊겨도 되는" 기능인데 정확성 기능을 굶긴다. README·CLAUDE.md 어디에도 이 공유가 적혀 있지 않다. 개발자가 따로 기억해야 하는 숨은 위험이다.
|
||||
- 증거: E1(코드와 기본값). 실측하지 않았다.
|
||||
- 고치는 법: 셋 중 하나를 고르고 버린 대안을 README에 남긴다. (a) 캐시 전용 script lane(별도 permit), (b) 캐시 조건부 쓰기에 SCRIPT lane permit 상한을 따로 둔다(예: 8 중 2), (c) 캐시 계정에 해당 script 권한만 주고 REGULAR lane에서 돈다. 어느 쪽이든 lane 대기·거절 수를 lane별 metric으로 낸다. 시간 초과 lease 폐기는 유지하되 재연결 횟수를 metric으로 본다.
|
||||
- 가이드 심각도·우선순위: Medium / P2.
|
||||
|
||||
#### RR-04-03 JDK transport 스트리밍 본문이 response-header timeout(2s)에서 잘린다 — 문서와 반대
|
||||
|
||||
- 위치: `httpclient/.../jdk/DeadlineAwareJdkRequestFactory.java:41`, `restclient/BlockingStreamingGateway.java:76-82`, `README.md:42-44`, `docs/httpclient/configuration-reference.md:103-105`.
|
||||
- 무엇이 틀렸나: JDK factory는 Spring `JdkClientHttpRequest`의 read timeout을 `min(response-header, 남은 deadline)`으로 둔다. Spring 7.0.9의 이 timeout은 교환 전체에 걸린다. 끝나면 응답 future를 취소하고 본문 stream을 닫는다. timer는 stream을 닫을 때만 멈춘다. 그래서 스트리밍 다운로드는 헤더를 받은 뒤에도 2s(또는 남은 예산)에 끊긴다. 이번 diff가 추가한 문서는 "넘겨받은 뒤 본문은 gap마다 read-idle로만 묶인다, 긴 다운로드를 임의의 총 시간에서 자르지 않는다"고 적는다. Apache에서만 참이다. 끊길 때 호출자는 분류되지 않은 `IOException: closed`를 받는다.
|
||||
- 왜 중요한가: JDK profile로 2초 넘는 다운로드는 항상 실패한다. 오류도 `HttpClientException` 계층이 아니라 원인 분류·로그 필드가 없다. 길이가 2초 근처인 다운로드는 간헐적으로 실패해 원인을 찾기 어렵다.
|
||||
- 증거: E3. `RrStreamingBodyProbeTest` — Apache 30/30바이트 2,994ms 완료, JDK 20/30바이트 2,010ms `IOException: closed`. `javap`로 Spring `TimeoutHandler` 동작 확인. 기존 `StreamingSetupDeadlineTest`는 setup만 보고 본문 길이는 보지 않는다.
|
||||
- 고치는 법: (a) JDK 스트리밍 요청은 read timeout을 걸지 않고 setup은 `AttemptDeadline` abort(응답 future 취소)로 묶는다. 본문 gap은 JDK가 못 재므로 "JDK 스트리밍은 gap 상한 없음"을 문서에 적는다. (b) JDK profile의 스트리밍을 기동에서 거부한다. 어느 쪽이든 README·configuration-reference의 문장을 transport별로 고치고, 위 probe를 transport별 계약 테스트로 둔다. 본문 stream 실패는 stable 예외로 감싼다.
|
||||
- 가이드 심각도·우선순위: Medium / P2.
|
||||
|
||||
#### RR-04-04 파일 move가 namespace 쿼터 상한을 우회하고, 쿼터 장부를 어긋나게 한다
|
||||
|
||||
- 위치: `application-fileserver/.../lifecycle/MoveFileApplicationUseCase.java:36-60`(쿼터 의존 없음, `relocate`만), `cleanup/DefaultCleanupService.java:311`(삭제 때 현재 namespace에서 회수), `persistence-fileserver/.../JpaFileQuota.java:85-96`(사용량 = 예약 장부 합), `docs/fileserver/configuration.md:131-136`.
|
||||
- 무엇이 틀렸나: 쿼터 사용량은 namespace별 예약 장부의 합이다. move는 레코드의 namespace만 바꾸고 장부는 옮기지 않는다. 그래서 (1) 목적지 B는 옮겨 온 바이트를 세지 않는다. 상한 B를 꽉 채운 뒤에도 기본 namespace에 올리고 B로 옮기면 B가 상한을 넘는다. (2) 출발지 A는 떠난 파일을 계속 센다. (3) 옮긴 파일을 지우면 cleanup이 B 장부에서 회수한다. B의 다른 행이 깎이고(바닥 0), A는 영영 줄지 않는다.
|
||||
- 왜 중요한가: 이번 diff가 `namespace-limit`을 "한 namespace가 가질 수 있는 최대 바이트"로 문서화했다. `target-namespaces`와 `namespace-limit`을 함께 켜는 배포에서 그 약속이 깨진다. 시간이 지나면 A는 실제로 비었는데 `QUOTA_EXCEEDED`로 업로드를 거절하고, B는 상한을 넘는다. 05-07의 목적(쓰기 자원 남용 상한)이 move로 빠져나간다.
|
||||
- 증거: E1. `MoveFileApplicationUseCase` 생성자에 `FileQuotaPort`가 없다. 실행 재현은 하지 않았다.
|
||||
- 고치는 법: move를 한 트랜잭션에서 "B에 `requireRoom` + 예약·commit, A에서 같은 바이트 reclaim"으로 바꾼다. 또는 move를 같은 namespace 안의 이름 변경으로 좁히고 namespace 간 이동은 copy+delete로 하게 한다. 고른 쪽을 문서에 적고, "B 상한을 move로 넘을 수 없다"와 "옮긴 뒤 A 사용량이 준다" 테스트를 둔다.
|
||||
- 가이드 심각도·우선순위: Medium / P2 (두 설정을 함께 켤 때만 도달).
|
||||
|
||||
#### RR-04-05 Redis 멱등성 계약의 실서버 실행이 어느 게이트에도 없다
|
||||
|
||||
- 위치: `cache-redis/build.gradle:57-64`(topology lane에만), `:76-86`(`redisContainerContractTest`의 `requires`에 없음), `cache-redis/CLAUDE.md:131-137`.
|
||||
- 무엇이 틀렸나: `requires`는 lane이 돌릴 클래스를 거르는 필터다(`StrictTestLanePlugin.java:216-219`). 컨테이너 lane은 캐시·lease 계약, `LiveRedisSemanticPortsTest`, ACL probe만 돈다. `LiveRedisIdempotencyStoreContractTest`는 explicit-only topology lane에만 있다. r3-B(계약 추가)와 r3-C(컨테이너 lane 추가)가 따로 작업하고 합쳐진 틈으로 보인다.
|
||||
- 왜 중요한가: 05-02의 원인은 "fake가 Lua의 버그를 따라 함"이었다. fake에는 Lua 상태 기계의 Java 사본이 있다(`InMemorySemanticRedisCommands.java:284-322`). 지금 실서버로 게이트에서 확인되는 멱등성 경로는 claim 경합·서버 시간·renew 정상 경로 세 개뿐이다. stale handle의 `NOT_OWNER`, `CLAIMED` 상태 renew 거부, complete·markFailed·release 재시도 같은 계약 케이스는 fake 사본에서만 돈다. 두 사본이 갈라져도 ci·mainCheck·integrationCheck가 초록이다.
|
||||
- 증거: E1(빌드 파일과 lane 필터).
|
||||
- 고치는 법: `redisContainerContractTest`의 `requires`에 `LiveRedisIdempotencyStoreContractTest`를 넣고 CLAUDE.md 목록을 맞춘다. 계약이 실서버에서 1초 lease를 기다리므로 lane 시간이 늘어나는지 한 번 잰다.
|
||||
- 가이드 심각도·우선순위: Medium / P2.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-04-06 identifier leaf 문서가 합친 뒤 다시 내용과 어긋난다
|
||||
|
||||
- 위치: `identifier/src/main/java/.../package-info.java:2`, `identifier/CLAUDE.md:27-33`, `README.md` HmacUserPrincipalPseudonymizer 절.
|
||||
- 무엇: package-info는 "식별자 생성은 여기 없다"고 하는데 `UuidV7DurableOperationIdFactory`가 있다. CLAUDE.md Allowed에 `:domain-core`와 `uuid-creator`가 없다. README의 "checked exception을 `IllegalStateException`으로 감싼다"는 `HmacSha256` 위임 뒤 이 클래스 이야기가 아니다. 05-21 문서 수정(r2-05b)과 UUIDv7 추가(r2-06)가 따로 합쳐졌다.
|
||||
- 고치는 법: 세 문서를 지금 두 클래스·세 의존에 맞춘다.
|
||||
- 심각도·우선순위: Low / P3. 증거 E1.
|
||||
|
||||
#### RR-04-07 캐시 전용 ACL probe가 연결 중 끊김을 "권한 설정 오류"로 보고 기동을 멈춘다
|
||||
|
||||
- 위치: `cache-redis/.../capability/RedisSemanticScriptAclProbe.java:92-109,137`.
|
||||
- 무엇: "닿지 못함" 판정이 `RedisLaneUnavailableException`·`TimeoutException`뿐이다. 연결은 열렸지만 probe 중 끊김, Redis 재시작 중 `LOADING` 응답, Lettuce 재연결 중 거절은 `ExecutionException`이라 설정 오류로 간다. README는 "캐시 장애는 pod 기동을 멈추지 않는다"고 적는다.
|
||||
- 고치는 법: `NOPERM`·`NOSCRIPT` 같은 권한 응답만 치명으로 보고 나머지 실패는 경고로 낮춘다. 테스트로 `LOADING` 응답 케이스를 둔다.
|
||||
- 심각도·우선순위: Low / P3. 증거 E1.
|
||||
|
||||
#### RR-04-08 Redis renew가 lease만 늘리고 key TTL은 늘리지 않는다
|
||||
|
||||
- 위치: `IdempotencyScripts.java:177-180`(RENEW에 `PEXPIRE` 없음), claim의 `PEXPIRE ARGV[7]`(`:44,77`, replay TTL).
|
||||
- 무엇: renew로 lease를 replay TTL(`APP_IDEMPOTENCY_TTL`, 기본 24h, 짧게 둘 수 있음) 너머까지 늘리면 실행 중 key가 사라진다. 다음 요청은 새 claim(`ACQUIRED`)을 받아 같은 부작용을 다시 실행한다. PostgreSQL store에는 이 제약이 없어 두 구현의 계약이 다르다. 지금 템플릿 안 호출자는 없다.
|
||||
- 고치는 법: RENEW에서 `PTTL < 새 leaseUntil - now`이면 `PEXPIRE`를 늘리거나, renew 요청을 거부한다. 계약에 "renew한 lease는 replay TTL보다 오래 살 수 있다" 케이스를 둔다.
|
||||
- 심각도·우선순위: Low / P3. 증거 E1.
|
||||
|
||||
#### RR-04-09 startup rule을 일찍 만드는 전제("static, 의존 없음")를 막는 장치가 없다
|
||||
|
||||
- 위치: `support/.../startup/StartupRuleRunner.java:65-66`, `StartupRule.java` Javadoc.
|
||||
- 무엇: runner는 bean factory post-processor 단계에서 모든 rule bean을 `getBean`한다. 지금 rule은 모두 `static @Bean`이다. 파생 서비스가 non-static `@Bean` rule을 쓰면 그 설정 클래스와 생성자 의존(datasource 등)이 그 시점에 만들어진다. 07-02가 막은 "검사 전에 DB 연결"이 조용히 되살아난다. 규칙은 Javadoc에만 있다.
|
||||
- 고치는 법: runner가 rule의 bean definition에 `getFactoryBeanName() != null`(non-static factory method)이면 기동을 실패시킨다. 테스트 1건.
|
||||
- 심각도·우선순위: Low / P3. 증거 E1.
|
||||
|
||||
#### RR-04-10 `DEGRADED` 정렬 순서를 상태를 내지 않는 leaf가 싣는다
|
||||
|
||||
- 위치: `cache-redis/src/main/resources/config/module-defaults/cache-redis.yml:78-87`, `redis-runtime/.../RedisRuntimeAutoConfiguration.java:71-72,276-286`.
|
||||
- 무엇: `redisOptional`(`DEGRADED`)은 `app.redis.enabled=true`면 redis-runtime이 만든다. 순서 설정은 cache-redis에만 있다. redis-runtime을 `api`로 끌어오는 redis-sdk만 쓰는 조립에서는 05-23e가 그대로다.
|
||||
- 고치는 법: 순서 키를 redis-runtime 쪽 기본값으로 옮긴다. redis-runtime에는 module-defaults가 없으니 `EnvironmentPostProcessor` 또는 문서화된 예외로 둔다.
|
||||
- 심각도·우선순위: Low / P3. 증거 E1.
|
||||
|
||||
#### RR-04-11 SMTP reply code 범위가 2xx·3xx까지 "거절"로 받는다
|
||||
|
||||
- 위치: `notification/.../smtp/JavaMailSenderSmtpDispatch.java:115`.
|
||||
- 무엇: `200 <= code < 600`을 받는다. Angus `sendpartial` 경로의 `SMTPSendFailedException`은 마지막 성공 코드(250)를 싣는다. 이 값이 `SmtpFailureClassifier`에서 영구 거절로 기록된다. 지금은 수신자 1명이라 도달하기 어렵다(`SmtpMimeMessageFactory.java:69`).
|
||||
- 고치는 법: `400 <= code < 600`만 reply code로 쓴다. 그 밖은 보수적 경로로 보낸다.
|
||||
- 심각도·우선순위: Low / P3. 증거 E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- `AttemptDeadline`의 abort가 JVM 공용 `CompletableFuture` delay 스레드에서 Apache `cancel()`(소켓 닫기)을 돈다. TLS 소켓 닫기가 막히면 JVM 안 다른 timeout이 늦어질 수 있다. JDK·Apache 구현 확인과 실측이 필요해 판단하지 않았다.
|
||||
- `pgsty/minio`(커뮤니티 fork)를 qualification 기준으로 삼는 공급망 위험. 15절 소유자 결정이고, digest 고정과 같은 digest mirror override로 완화돼 있다.
|
||||
- SES replay 창 1h. 15절 결정이고 ledger 유일 제약이 중복을 막는다. 재전송 공격 면이 넓어진 정도는 판단하지 않았다.
|
||||
- `namespace-limit`의 동시 예약 초과 허용. 15절 결정이며 문서에 적혀 있다.
|
||||
- 시스템 env가 list 원소 하나를 덮으면 yml에 있던 같은 원소의 다른 필드가 조용히 사라지는 Spring의 list 통째 교체. 이번 diff 전부터 있던 동작이라 범위 밖으로 뒀다.
|
||||
- 캐시 `invalidate`의 GET→SET 비원자성. 코드 주석에 고른 이유(덮어써도 무효화 의미가 같음, REGULAR lane 권한)가 있다.
|
||||
- notification evidence verifier가 상위 계약 클래스를 따라가 테스트를 찾게 바뀐 것. 지정 root 밖은 따라가지 않아 fail-closed다. 문제 없다고 봤다.
|
||||
- `application-*`·`web-fileserver`·`persistence-fileserver` diff 중 발견 판정에 쓰지 않은 부분.
|
||||
|
||||
## 28개 관점 — 바뀐 관점만
|
||||
|
||||
| # | 관점 | 전 → 후 | 한 줄 이유 |
|
||||
|---|---|---|---|
|
||||
| 8 | 디버깅 가능성 | P → O | MinIO 공급 실패가 `PinnedImageUnavailableException`으로 구분되고, deadline 중단·evidence가 구체적으로 남는다. 예외: JDK 스트림의 미분류 `IOException`(RR-04-03) |
|
||||
| 12 | 동시성 성숙도 | P → O | 발송 중 crash 재발송(05-01), renew(05-02), finalize lease(05-22)가 닫혔다. 쿼터 동시 초과는 결정으로 문서화 |
|
||||
| 16 | 의존성 성숙도 | P → O | MinIO 공급원이 digest 고정 + mirror override로 복구됐고, Jackson 2는 결정으로 닫혔다 |
|
||||
| 27 | 삭제 가능성 | P → O | 권한 매핑이 각 모듈 기본값으로 옮겨져 모듈 한 줄을 지우면 함께 사라진다(05-19) |
|
||||
| 28 | 회복 가능성 | P → O | 증거 오기로 인한 재발송이 닫히고 정리 worker가 기본 on이다 |
|
||||
|
||||
1·6·11·14·15·17·21번은 기호는 P 그대로이고 이유가 바뀌었다. 원래 이유는 대부분 닫혔고, 새 이유는 각각 RR-04-03(17), RR-04-01(6), RR-04-04(11·15), RR-04-02(14), RR-04-05(21)다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge: With fixes.** 원 리뷰의 High·P1(05-01~05-09)은 모두 코드와 테스트로 닫혔고 회귀는 없다. 다만 05-06 수정이 breaker를 호출자 deadline으로 열게 만들었고(RR-04-01, E3), JDK 스트리밍이 문서와 반대로 잘린다(RR-04-03, E3). 이 둘과 RR-04-02·04·05는 파생 서비스가 HTTP client·Redis·파일 쿼터를 켜기 전에 고쳐야 한다.
|
||||
@@ -0,0 +1,252 @@
|
||||
# 05 messaging 재리뷰 (2026-11-03)
|
||||
|
||||
- 리뷰 범위: Base `01a8a2a70` → Head `5786126c`, 이 영역 pathspec 62파일(+3,798 −274).
|
||||
- 원래 발견: `docs/reviews/2026-11-01-maturity-review/06-messaging.md`(06-01~06-09, NN-10~NN-14).
|
||||
- 판정 기준: 리뷰 가이드 35절(심각도·우선순위·통제·증거), 36.3 양식, `AGENTS.md`·`CLAUDE.md`, `src/messaging/CLAUDE.md`, `src/adapter/inbound/messaging/CLAUDE.md`.
|
||||
|
||||
## 범위
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
`src/messaging`, `src/adapter/outbound/messaging`, `src/adapter/outbound/messaging-kafka`,
|
||||
`src/adapter/inbound/messaging`, `src/composition/outbox-relay`, `docs/messaging`,
|
||||
`docs/runbooks/outbox-dead-letter.md`, `docs/runbooks/outbox-publish-failed.md`,
|
||||
`docs/runbooks/migration-failed.md`, `docs/manual/09-outbox-events.md`.
|
||||
|
||||
발견을 확인하려고 pathspec 밖의 다음 코드도 읽었다. 이 파일들의 diff 전체를 리뷰한 것은 아니다.
|
||||
|
||||
- application-core: `application/outbox/**`(relay use case, outcome, backoff, `ClaimedOutboxEvent`, `OutboxStorePort`, `OutboxAggregateSequencePort`), `application/messaging/event/**`(`EventId`, `IntegrationIdentity`, `IntegrationEventDrafts`, `AggregateOrder`), `SubmitDurableOperationUseCase`.
|
||||
- persistence-jpa: `JpaOutboxStore`, `OutboxEventJpaRepository`, `V20`, `V21`.
|
||||
- support: `JsonIntegrationEventEncoder`(봉투·partition key).
|
||||
- sample: `PortfolioEventOutbox`, `OutboxEventIdFactory`.
|
||||
- `docs/registries/metrics.yaml` outbox 항목.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 본 것 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: Strengths → Issues(심각도별) → Assessment, Declined to judge, 읽기 전용, 하위 에이전트 금지 | 문서 구조 전체 |
|
||||
| `domain-driven-design` | Anti-Corruption Layer는 바깥 모델의 의미를 안쪽 어휘로 번역한다. 통합 이벤트의 식별자·순서는 소비자 계약이다. 경계 맥락은 서로의 모델을 알지 않는다 | bridge의 `retryable` 번역(06-01), event id ↔ `MessageId`(06-06), aggregate 순서 번호가 소비자에게 보이는 계약인지(06-07), vendored 제품이 앱을 아는지(MSG-023) |
|
||||
| `observability-and-instrumentation` | on-call 질문부터 정한다("이 행은 왜 계속 재시도하나", "인증 오류인가 종료 중 거부인가", "적체가 느는가"). 지표 label 집합은 고정한다. runbook의 첫 확인 절차가 실제로 동작해야 한다 | relay 실패 보고의 원인 정보, 게이지 갱신 경로, `outcome` label 값, DEAD runbook SQL |
|
||||
| `doubt-driven-development` | 결과 불명 판단을 주장(CLAIM)으로 적고 반증을 시도한다 | 아래 다섯 주장. 하위 에이전트 금지(브리프)라 새 맥락 리뷰어 대신 자기 반증으로 했다(축소 적용). 비대화 실행이라 교차 모델 검토는 건너뛰었다 |
|
||||
|
||||
반증을 시도한 주장과 결과:
|
||||
|
||||
1. "retryable 거부·결과 불명은 DEAD가 되지 않으니 안전하다" → 일부 반증. 끝나지 않는 행을 구분·처분할 수단이 없다(RR-05-03).
|
||||
2. "종료 중 claim된 행은 PUBLISHED 또는 lease 해제 상태로 남는다" → 반증 못 함. Spring 7.0.9 종료 순서와 맞는다(닫힘).
|
||||
3. "V21 카운터는 옛 벽시계 번호 뒤에서 시작한다" → 반증. 옛 행이 지워졌거나 identity가 바뀌면 1부터 다시 시작한다(RR-05-02, 실 PG 재현).
|
||||
4. "DEAD runbook 재발행 SQL로 행이 다시 발행된다" → 반증. `deferred_attempt_count`가 2 이상이면 행이 DEAD로 되돌아간다(RR-05-01, 실 PG 재현).
|
||||
5. "게이지가 relay와 무관한 자기 주기로 갱신된다" → 일부 반증. relay와 같은 단일 스레드에서 줄을 선다(RR-05-05).
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
| 명령 | 결과 |
|
||||
| --- | --- |
|
||||
| `git diff --stat 01a8a2a70..5786126c -- <pathspec>`, `git diff ...` | 62파일. 나눠서 전부 읽었다 |
|
||||
| `git worktree add <scratchpad>/rr-05 5786126c` 후 worktree에서만 `PostgreSqlOutboxClaimAndMaintenanceIntegrationTest`에 실험 메서드 2개 추가 | 메인 작업 트리는 건드리지 않았다. 끝나고 `git worktree remove --force` |
|
||||
| `flock <heavy.lock> ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest --tests '*PostgreSqlOutboxClaimAndMaintenanceIntegrationTest.rr05RunbookRedrive*'` | 실 PostgreSQL. 예상대로 실패. `claimed=[] status=DEAD counts={attempt_count=1, deferred_attempt_count=2}`, WARN `outbox claim moved a row it cannot read to DEAD`, 원인 `deferredAttemptCount must be between 0 and attemptCount (1), was 2` (29초) |
|
||||
| 같은 lane, `--tests '*rr05CounterSeed*'` | 통과(17초). `a(옛 행 남음)=1788000000000001`, `b(tenant scope 바뀜)=1`, `c(옛 행 지워짐)=1`, 옛 번호 `1788000000000000` |
|
||||
| `javap -c -p` spring-context 7.0.9 `SimpleAsyncTaskScheduler`, spring-boot-autoconfigure 4.0.8 `TaskSchedulingConfigurations$TaskSchedulerConfiguration` | virtual thread가 켜지면(템플릿 기본 `true`, `app-bootstrap/.../application.yml:58`) Boot가 `SimpleAsyncTaskScheduler`를 만든다. fixed-delay 작업은 `fixedDelayExecutor`(core pool 1)에서 돈다. `ContextClosedEvent`에서는 `shutdown()`(실행 중 작업은 계속)이다 |
|
||||
|
||||
게이트(`ci`·`mainCheck`·`integrationCheck` 등)는 README 16.2 기록을 따랐고 다시 돌리지 않았다.
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- Kafka lane(`messagingKafkaRelayIntegrationTest`, `messagingInboxRedeliveryIntegrationTest`)을 직접 실행하지 않았다. 코드와 README 16절 기록만 봤다.
|
||||
- 실제 SIGTERM 종료 순서, 다중 인스턴스 동시 기동, 처리량을 측정하지 않았다.
|
||||
- vendored admin·claim-check·schema·observability 내부, starter-kafka `KafkaConsumerRegistrar`는 이번 diff에 없어 보지 않았다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **종료 순서를 relay가 직접 소유한다.** `OutboxRelayScheduler`가 SmartLifecycle(phase `Integer.MAX_VALUE`)이 되어 platform admission(`MessagingShutdownLifecycle.PHASE`)보다 먼저 멈춘다(`composition/outbox-relay/.../OutboxRelayScheduler.java:40,150`). 진행 중 발행 하나만 끝내고 남은 claim은 `releaseLease`로 시도 횟수 없이 돌려준다(`application-core/.../PublishPendingOutboxEventsUseCase.java:123-127,143-155`). Spring 7.0.9의 `ContextClosedEvent → shutdown()` → lifecycle stop 순서와 맞는다.
|
||||
- **순서 테스트가 platform 상수를 직접 쓴다.** `OutboxRelayShutdownOrderTest`가 MAX-1024를 복사하지 않고 `MessagingShutdownLifecycle.PHASE`를 compile-only로 참조한다(`composition/outbox-relay/build.gradle:32-39`). platform phase가 바뀌면 테스트가 깨진다.
|
||||
- **ACL 번역이 정확해졌다.** bridge가 platform `retryable`을 `REJECTED_RETRYABLE`로 옮긴다(`PlatformIntegrationEventPublishAdapter.java:189`). AMBIGUOUS로 뭉개지 않은 이유(중복 경고 오염)가 README에 남아 있다.
|
||||
- **재전송 id가 바뀌지 않는다.** bridge가 대문자·축약 표기 UUID를 다른 id로 바꿔 보내지 않고 거부한다(`PlatformIntegrationEventPublishAdapter.java:154-163`). 소비자 중복 제거 키가 깨지는 경로를 막았다.
|
||||
- **시도 예산을 일시 실패와 분리했다.** `deferred_attempt_count`(V20)와 `budgetedAttemptCount()`(`ClaimedOutboxEvent.java:55`)로 예산은 분류되지 않은 예외에만 쓴다. 재시도 시각은 실패 시점 기준이다(`PublishPendingOutboxEventsUseCase.java:179,187,193`). V20은 기본값으로 기존 행을 다시 쓰지 않는다.
|
||||
- **소비 경로를 실제 의존성으로 검증한다.** `InboxRedeliveryIntegrationTest`는 앱 relay → Kafka → platform consumer → inbox+JPA 한 트랜잭션을 실 Kafka·PostgreSQL로 돌린다. offset 되감기와 실패 재처리 둘 다 본다. inbox 중복 검사를 지우는 변이를 잡았다는 기록도 있다.
|
||||
- **이 lane이 실제 결함을 찾았다.** inbound/outbound messaging leaf가 같은 Gradle 좌표라 bridge가 빠지던 문제를 group·jar 이름으로 고쳤다(`adapter/inbound/messaging/build.gradle:19-28`).
|
||||
- **decode 등록을 코드가 막는다.** handler 선언으로 decode 목록을 만들고, 같은 계약에 다른 class를 선언하면 기동을 막는다(`MessageContracts.java:61-85`). 서비스가 등록을 잊어 메시지가 조용히 DLQ로 가는 숨은 위험이 사라졌다.
|
||||
- **inbox 마이그레이션 위치를 고른 이유가 남아 있다.** primary location에 넣으면 V22가 out-of-order로 거부되는 이유와 explicit baseline을 쓴 이유가 코드 주석에 있다(`MessagingInboxSchemaStream.java:20-31`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| 06-01 | 닫힘 | retryable REJECTED → `REJECTED_RETRYABLE`(`PlatformIntegrationEventPublishAdapter.java:188-190`). relay는 `markDeferred`로 예산 없이 재시도(`PublishPendingOutboxEventsUseCase.java:189-194`). Kafka 인증·인가는 retryable(`KafkaPublishFailureClassifier.java:43,75-76`). `PUBLISH_RUNTIME_UNAVAILABLE`·`KAFKA_TRANSPORT_CLOSED`도 retryable(`DefaultMessagePublisher.java:266-276`, `KafkaMessagingTransport.java:121-131`). 남은 위험은 RR-05-03 |
|
||||
| 06-02 | 닫힘 | SmartLifecycle phase `MAX_VALUE`, `stop(Runnable)`이 진행 중 회차를 기다림(`OutboxRelayScheduler.java:150-162`). 남은 claim 해제(`OutboxStorePort.releaseLease`, `OutboxEventJpaRepository` `releaseLease`). 13절의 "lease 해제 없음"·"phase 하드코딩"도 해결 |
|
||||
| 06-03 | 닫힘 | AMBIGUOUS·retryable 거부는 예산을 쓰지 않음. 지연 상한 5분(`OutboxBackoffPolicy.MAX_DELAY`). runbook 차단 범위 조회가 현재 FIFO 키(`outbox-dead-letter.md:27`). 단 같은 runbook의 재발행 SQL이 V20과 어긋난다(RR-05-01) |
|
||||
| 06-04 | 닫힘 | 발행이 있으면 한 tick 안에서 다시 claim, 상한 50회차(`OutboxRelayScheduler.java:47,102-112`). README에 처리량 상한 숫자(`composition/outbox-relay/README.md` "한 tick이 claim 한 번이 아니다"). PG 카운트 테스트 대신 fake store 테스트(`OutboxRelaySchedulerDrainTest`) |
|
||||
| 06-05 | 닫힘 | 게이지 갱신을 `@Scheduled refreshGauges`로 분리(`OutboxMetrics.java:91-94`). relay 꺼짐 WARN(`OutboxRelayOffWarning`). 실제 스케줄러로 relay-off 게이지 값을 단언(`OutboxMetricsTest.java:40-66`). 단 relay와 같은 스레드를 쓴다(RR-05-05) |
|
||||
| 06-06 | 부분 | bridge는 정규 소문자 UUIDv7만 받게 엄격해졌다. 완료 기준인 "append(draft·encode) 시점 거부"는 없다. `EventId`는 여전히 `[A-Za-z0-9][A-Za-z0-9._:-]*`(`EventId.java:9`), durable operation digest 경로는 UUID가 아닌 id를 만든다(`SubmitDurableOperationUseCase.java:168-173`). bridge 주석·README도 "until it does"라고 미완을 인정한다(RR-05-04) |
|
||||
| 06-07 | 닫힘 | sample이 `OutboxAggregateSequencePort`로 번호를 받는다(`PortfolioEventOutbox.java` append). V21 유일 인덱스로 같은 번호 두 번 append를 거부. 업그레이드 연속성은 RR-05-02 |
|
||||
| 06-08 | 닫힘 | 새 leaf `adapter:inbound:messaging`(registry 등록), inbox 부품 조립, decode 목록 자동, V1101 별도 stream, 실 Kafka+PG 중복 전달 lane. application 소비 포트는 버린 대안으로 이유와 함께 기록(`adapter/inbound/messaging/README.md` "고른 방법과 버린 대안"). 예시 handler는 sample이 아니라 테스트에 있다 |
|
||||
| 06-09 | 닫힘 | `messagingKafkaRelayIntegrationTest`(strict lane, `integration()`, skip 거부)가 relay → bridge → 실 Kafka 레코드 바이트를 비교. `:integrationCheck`는 `.github/workflows/integration-main.yml`에서 main push·nightly로 돈다 |
|
||||
| NN-10~NN-14 | 미조치(색인 누락) | README 12절 색인에 06-01~06-09만 있다. NN-13은 부분(스케줄러·use case Javadoc은 고침, `OutboxLeaderElectionToken` 설명과 `CLAUDE.md` 부재는 남음). NN-10·11·12·14는 diff에 조치가 없다(RR-05-10) |
|
||||
|
||||
회귀로 판정한 발견: 없음. RR-05-01은 06-03 자체의 회귀가 아니라 V20이 같은 변경 안에서 runbook SQL을 낡게 만든 새 결함이다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-05-01 — DEAD runbook의 재발행 SQL이 `deferred_attempt_count`를 되돌리지 않아 행이 다시 DEAD가 된다
|
||||
|
||||
- 위치: `docs/runbooks/outbox-dead-letter.md:46,48`. 관련 코드는 `application-core/.../ClaimedOutboxEvent.java:35-41`, `persistence-jpa/.../JpaOutboxStore.java:150-155`.
|
||||
- 무엇이 틀렸나:
|
||||
- runbook SQL은 `attempt_count = 0`만 쓴다.
|
||||
- V20이 더한 `deferred_attempt_count`는 그대로 남는다.
|
||||
- 다음 claim에서 `attempt_count`는 1이 된다.
|
||||
- `ClaimedOutboxEvent`는 `deferredAttemptCount > attemptCount`이면 생성을 거부한다.
|
||||
- claim은 그 예외를 "읽을 수 없는 행"으로 보고 행을 다시 DEAD로 옮긴다.
|
||||
- 왜 중요한가:
|
||||
- 발생 조건: DEAD 행의 `deferred_attempt_count`가 2 이상이다. 장애 중 두 번 이상 미뤄진 뒤 확정 거부나 예산 소진으로 DEAD가 된 행이 해당한다. 운영자가 장애 뒤 일괄 재구동할 행이 바로 이런 행이다.
|
||||
- 영향: P1 incident의 유일한 복구 절차가 실패한다. aggregate는 계속 막힌다.
|
||||
- 탐지가 어렵다. 로그는 `outbox claim moved a row it cannot read to DEAD`라고 말해 원인을 행 손상으로 오해하게 한다. 이 경로는 failure reporter를 거치지 않아 `OUTBOX_DEAD_LETTER` 보고와 `outcome=DEAD` 카운터도 다시 나오지 않는다.
|
||||
- 증거: 실 PostgreSQL에서 runbook SQL을 그대로 실행해 재현했다. 결과는 `claimed=[]`, `status=DEAD`, `attempt_count=1`, `deferred_attempt_count=2`다.
|
||||
- 고치는 법:
|
||||
1. runbook §4 두 SQL에 `deferred_attempt_count = 0`을 넣는다.
|
||||
2. V21 확인 쿼리처럼 §4 SQL에 `runbook-sql` 표지를 달고, PG lane(`PostgreSqlOutboxOrderKeyRunbookIntegrationTest`와 같은 방식)이 runbook에서 읽어 실행하게 한다. "재발행한 행이 claim된다"를 단언한다.
|
||||
3. 선택: DB에 `CHECK (deferred_attempt_count <= attempt_count)`를 둔다. 잘못된 수동 SQL이 claim 때 조용히 DEAD가 되는 대신 UPDATE 시점에 바로 실패한다.
|
||||
- 가이드 심각도: Medium · 우선순위 P1 · 증거 E3(실 PG 재현) · 통제 M0(runbook SQL을 검사하는 장치 없음).
|
||||
|
||||
#### RR-05-02 — 새 aggregate 카운터가 1부터 시작해 소비자가 보는 순서 번호가 업그레이드 때 뒤로 간다
|
||||
|
||||
- 위치: `persistence-jpa/.../OutboxEventJpaRepository.java:137`(`COALESCE(MAX(e.aggregate_sequence), 0) + 1`), `JpaOutboxStore.java:114-124`, `V21__outbox_aggregate_sequence.sql:9-11`, `sample-portfolio/.../PortfolioEventOutbox.java:38`(scope가 `portfolio` → `global`).
|
||||
- 무엇이 틀렸나:
|
||||
- 카운터가 없는 aggregate의 첫 번호는 "지금 outbox에 남은 행"의 최댓값 + 1이다.
|
||||
- 옛 sample은 번호로 epoch 마이크로초(약 1.7×10^15)를 썼다.
|
||||
- reaper가 PUBLISHED 행을 7일 뒤 지운다. 7일 넘게 조용했던 aggregate는 남은 행이 없다. 그래서 다음 번호가 1이다.
|
||||
- sample은 같은 diff에서 tenant scope를 `portfolio`에서 `global`로 바꿨다. 옛 행은 다른 identity라 최댓값 계산에 들어가지 않는다. 모든 sample aggregate가 1부터 다시 시작한다.
|
||||
- scope는 Kafka partition key 해시에도 들어간다(`JsonIntegrationEventEncoder.java:258-264`). 배포 전에 남은 `portfolio` 미발행 행과 배포 뒤 `global` 행은 서로 막지 않고 다른 partition으로 간다.
|
||||
- 왜 중요한가:
|
||||
- `AggregateOrder` 문서는 소비자가 이 번호를 "어느 변경이 마지막인가"로 읽는다고 적는다(`AggregateOrder.java:7`). 봉투에도 `aggregate.sequence`로 실린다.
|
||||
- "마지막으로 본 번호보다 작으면 버린다"로 구현한 소비자는 업그레이드 뒤 그 aggregate의 이벤트를 모두 버린다. 템플릿이 권한 패턴이다.
|
||||
- V21 주석의 의도("rows numbered by the old clock scheme still come first")가 옛 행이 남아 있을 때만 성립한다. 포트 계약(`OutboxAggregateSequencePort` Javadoc "greater than any number an earlier outbox row carries")도 지워진 행은 다루지 않는다.
|
||||
- 증거: 실 PostgreSQL에서 `nextSequence`를 불렀다. 옛 행이 남은 경우 1788000000000001, scope가 바뀐 경우 1, 옛 행이 지워진 경우 1이다.
|
||||
- scope를 `global`로 바꾼 것은 15절 결정(r2-01)이다. 결정을 뒤집자는 것이 아니라, 그 결정과 V21이 합쳐져 생긴 업그레이드 위험이다.
|
||||
- 고치는 법:
|
||||
- 새 카운터의 시작값을 `GREATEST(COALESCE(MAX(e.aggregate_sequence), 0), <현재 epoch 마이크로초>) + 1`로 둔다. 번호는 양수이고 커지기만 하면 되므로 비용이 없다. 옛 벽시계 번호는 그 시각 이전 값이라 새 번호가 항상 뒤에 온다.
|
||||
- sample scope 변경은 "배포 전 `portfolio` 미발행 행을 비운다"는 절차를 sample README나 manual 09에 적는다. 또는 sample만 `portfolio`를 유지한다.
|
||||
- 파생 서비스가 벽시계 번호에서 포트로 옮길 때의 주의를 manual 09 "event id·correlation·순서" 절에 한 줄 적는다.
|
||||
- 가이드 심각도: Medium · 우선순위 P2 · 증거 E3(실 PG에서 번호 확인) · 소비자 쪽 피해는 E1(소비자 구현에 달림).
|
||||
|
||||
#### RR-05-03 — 끝나지 않는 재시도 행을 운영자가 구분하거나 처분할 수단이 없다
|
||||
|
||||
- 위치: `PlatformIntegrationEventPublishAdapter.java:188-190`, `application-core/.../OutboxPublishRefusedException.java:39-41`, `PublishPendingOutboxEventsUseCase.java:181-194`, `messaging-kafka/.../KafkaPublishFailureClassifier.java:55-63`, `docs/runbooks/outbox-publish-failed.md:43-45,60`.
|
||||
- 무엇이 틀렸나:
|
||||
- AMBIGUOUS와 `REJECTED_RETRYABLE`은 이제 예산을 쓰지 않는다. 그래서 끝 상태가 없다. 이것은 15절 결정이다.
|
||||
- 결정 기록과 runbook이 다루는 남은 위험은 "진짜 인증 오류" 하나다.
|
||||
- 실제로 영원히 재시도하는 행은 하나 더 있다. Kafka classifier가 이름을 모르는 브로커 거부는 기본값으로 AMBIGUOUS다. 예: topic의 timestamp 정책에 걸린 `InvalidTimestampException`, 없는 topic의 metadata 대기 시간 초과. 예전에는 3회 뒤 DEAD와 P1 경보로 끝났다. 지금은 5분 간격으로 끝없이 FAILED가 되고 그 aggregate를 막는다.
|
||||
- runbook은 원인을 "인증/인가면"으로 가르라고 한다. 그런데 bridge가 platform의 실패 code·category를 버리고 `REJECTED_RETRYABLE`만 넘긴다. relay 보고의 원인 문장은 "shutting down, saturated, transport closed or credentials refused" 넷을 한 문장에 묶는다. platform 발행 지표 label도 completion뿐이다(`DefaultMessagePublisher.java` `observe`). 그래서 앱 로그와 지표로는 원인을 가를 수 없다.
|
||||
- FAILED 행을 건너뛰는 절차가 없다. skip SQL은 `status = 'DEAD'`만 대상으로 한다(`outbox-dead-letter.md:51`). publish-failed runbook은 "즉시 수동 개입 불필요"라고 한다.
|
||||
- 영원히 재시도하는 행을 찾는 쿼리·지표가 없다. `deferred_attempt_count`가 있는데도 runbook이 쓰지 않는다.
|
||||
- 왜 중요한가:
|
||||
- 발생 조건: 레코드 하나에만 해당하는 영구 거부를 classifier가 모르는 경우, 또는 인증·ACL이 실제로 틀린 경우.
|
||||
- 영향: 그 aggregate의 뒤 이벤트가 무기한 멈춘다. `outbox.publisher.lag` 경보는 울린다. 하지만 운영자는 원인을 알 수 없고 처분 절차도 없다.
|
||||
- 사용자 판단 원칙 "위험은 코드에 드러나야 한다"에 걸린다. AMBIGUOUS 분기 주석(`PublishPendingOutboxEventsUseCase.java:182-186`)은 broker 정지만 말하고 이 경우를 말하지 않는다.
|
||||
- 고치는 법:
|
||||
1. bridge가 platform `FailureDescriptor.code()`를 잃지 않게 한다. 예: `OutboxPublishOutcome`은 그대로 두고 `publishForOutcome` 결과에 sanitized code를 함께 실어 relay 보고 필드(`error.reason` 등)로 남긴다. 번역 경계(ACL) 안에서 끝나는 변경이다.
|
||||
2. runbook에 "끝나지 않는 재시도" 절을 둔다. 확인 쿼리는 `status='FAILED' AND deferred_attempt_count >= N`이다. 처분은 원인 해소 또는 FAILED 행 skip(DEAD skip과 같은 승인 조건)이다.
|
||||
3. 선택: 결정을 유지하면서 상한을 하나 둔다. 예: `deferred_attempt_count`가 아주 크거나 행 나이가 기준을 넘으면 별도 경보를 낸다. 예산 키를 만들지 않는다는 결정과 충돌하지 않는다.
|
||||
4. 15절 결정 기록의 "남은 위험" 칸에 classifier 미분류 영구 거부를 더한다.
|
||||
- 가이드 심각도: Medium · 우선순위 P2 · 증거 E1 · 통제 M1(runbook이 인증 오류만 기술).
|
||||
|
||||
#### RR-05-04 — 06-06이 "완료"로 기록됐지만 완료 기준(append 시점 거부)이 채워지지 않았다
|
||||
|
||||
- 위치: `application-core/.../EventId.java:9`, `IntegrationIdentity.java:18`, `SubmitDurableOperationUseCase.java:168-173`, `PlatformIntegrationEventPublishAdapter.java:133-151`, `adapter/outbound/messaging/README.md:45-51`. README 14절 r2-06 행("06-04~06-07 ... 완료").
|
||||
- 무엇이 틀렸나:
|
||||
- application `EventId` 문법은 그대로 넓다.
|
||||
- bridge만 정규 소문자 UUIDv7로 더 좁아졌다. 두 계약의 차이는 오히려 커졌다.
|
||||
- `canonicalIdentity`는 문법 밖 operation id를 `operation-<sha256>`로 바꾼다. 이 id는 append를 통과하고 relay에서 DEAD가 된다.
|
||||
- bridge Javadoc과 README가 "append 쪽에서 먼저 실패해야 한다 — 별도 작업"이라고 적는다. 그런데 조치 현황은 완료다.
|
||||
- 왜 중요한가:
|
||||
- 지금은 HTTP가 서버에서 UUIDv7을 만들어 도달하지 않는다(`DurableOperationController.java:91`).
|
||||
- 새 inbound adapter, 클라이언트 지정 id, 다른 id 생성기를 쓰는 기능이 생기면 원래 06-06과 같다. 업무 트랜잭션은 커밋되고, 실패는 나중에 relay에서 DEAD로 나타나 aggregate를 막는다.
|
||||
- 상태 기록이 실제와 달라 후속 작업 목록에서 빠진다.
|
||||
- 고치는 법: 원래 권고 (a)를 따른다. `EventId`를 정규 소문자 UUIDv7로 좁힌다. 또는 encoder가 encode 단계에서 같은 검사를 한다. `canonicalIdentity`의 digest 경로는 UUIDv5/v7 파생으로 바꾸거나 없앤다. 조치 현황의 06-06을 "부분"으로 고친다.
|
||||
- 가이드 심각도: Medium · 우선순위 P2(원래 등급 유지) · 증거 E1 · 통제 M2(bridge에서만 강제).
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-05-05 — 게이지 갱신이 relay와 같은 단일 스레드에서 줄을 선다
|
||||
|
||||
- 위치: `composition/outbox-relay/.../OutboxMetrics.java:21-29,91-94`, `OutboxRelayScheduler.java:47,102-112`.
|
||||
- 무엇: Javadoc은 게이지가 "relay와 무관한 자기 주기"로 갱신된다고 적는다. 실제로는 fixed-delay `@Scheduled` 작업이 모두 한 스레드를 쓴다. virtual thread 켬(템플릿 기본)이면 `SimpleAsyncTaskScheduler.fixedDelayExecutor`(core 1)이고, 끄면 `ThreadPoolTaskScheduler` pool 1이다. relay tick은 이제 최대 50회차라 한 tick 동안 게이지·reaper가 기다린다.
|
||||
- 왜: broker가 느린데 발행은 성공할 때(예: 발행당 0.5초면 50×20×0.5초 ≈ 8분) 게이지가 갱신되지 않는다. 적체를 봐야 할 바로 그때다. relay-off·매 회차 실패 경우(06-05의 완료 기준)는 맞게 동작한다.
|
||||
- 고치는 법: tick 상한을 회차 수가 아니라 시간(예: poll 주기의 몇 배)으로 둔다. 또는 게이지를 Micrometer의 지연 조회 gauge나 별도 executor로 옮긴다. 최소한 Javadoc을 "relay tick 사이에 갱신"으로 고친다.
|
||||
- 심각도 Low · P3 · 증거 E1(Spring 7.0.9·Boot 4.0.8 바이트코드).
|
||||
|
||||
#### RR-05-06 — 새 결과 `RELEASED`가 지표 registry에 없다
|
||||
|
||||
- 위치: `docs/registries/metrics.yaml:353`(`allowed_values: [PUBLISHED, FAILED, DEAD, IN_FLIGHT, STALE]`), `OutboxMetrics.java:65`(Javadoc에 RELEASED 없음), `OutboxMessagePublishAdapter.java:16`("four-valued outcome", 지금은 다섯).
|
||||
- 무엇: relay는 종료 때 `outbox.publisher.published.total{outcome=RELEASED}`를 기록한다. registry 허용 값에는 없고, 실제로 나오지 않는 `IN_FLIGHT`는 남아 있다. `OutboxStatusRegistryContractTest`는 `outbox.pending.size` status만 비교해서 이 차이를 잡지 못한다.
|
||||
- 고치는 법: 허용 값을 `OutboxRelayResult.Outcome`과 맞추고, 같은 계약 테스트에 이 label도 비교하게 한다.
|
||||
- 심각도 Low · P3 · 증거 E1.
|
||||
|
||||
#### RR-05-07 — vendored 제품 안에 두 개의 재시도 규칙이 생겼고, 고른 이유가 제품 쪽에 없다
|
||||
|
||||
- 위치: `messaging-core-api/.../FailureDescriptor.java:57-75`, `messaging-kafka/.../KafkaPublishFailureClassifier.java:19-25,62-77`, `messaging-runtime-core/.../DefaultMessagePublisher.java:266-268`, `messaging-spring-boot-starter/.../MessagingShutdownLifecycle.java:33-38,121-127`.
|
||||
- 무엇:
|
||||
- platform의 category 기본 규칙은 "인증·인가 실패는 자동 재시도하지 않는다"이다(`defaultRetryable(AUTHENTICATION)=false`, Javadoc).
|
||||
- publish classifier는 이제 같은 category에 `retryable=true`를 붙인다. consumer 재시도 엔진은 두 값을 AND하므로 지금 동작은 안 바뀐다. 하지만 같은 제품이 같은 category를 두 의미로 쓴다.
|
||||
- vendored 주석 세 곳이 "the application's outbox relay", `composition:outbox-relay OutboxRelayScheduler`를 이름으로 부른다. `PHASE`는 앱 테스트를 위해 public이 됐다.
|
||||
- registry 간선은 그대로라 MSG-023의 의존 방향은 지켰다. 하지만 제품 문서가 소비자를 알게 됐다.
|
||||
- "bridge(ACL)에서 category를 보고 번역하고 vendored는 그대로 둔다"는 대안을 왜 버렸는지가 `src/messaging/CLAUDE.md`에 없다. 같은 파일의 digest 헬퍼 절(01-11)처럼 남기는 관례가 이미 있다.
|
||||
- 고치는 법: `FailureDescriptor` Javadoc에 "publish 거부의 retryable은 category 기본값과 다를 수 있다(인증·인가)"를 적는다. vendored 주석은 "a publisher that trusts the flag"처럼 소비자 이름 없이 쓴다. `src/messaging/CLAUDE.md`에 06-01 vendored 수정 목록과 ACL 대안을 버린 이유를 적는다.
|
||||
- 심각도 Low · P3 · 증거 E1.
|
||||
|
||||
#### RR-05-08 — `MessagingShutdownLifecycle`에 주인 없는 Javadoc이 남았다
|
||||
|
||||
- 위치: `messaging-spring-boot-starter/.../MessagingShutdownLifecycle.java:32`.
|
||||
- 무엇: `POLL` 필드의 Javadoc("How often the drain is re-checked")이 새 `PHASE` Javadoc 바로 위에 붙어 떨어져 있다. `POLL`(40행)에는 설명이 없어졌다.
|
||||
- 고치는 법: 32행 주석을 `POLL` 선언 위로 옮긴다.
|
||||
- 심각도 Low · P3 · 증거 E1.
|
||||
|
||||
#### RR-05-09 — 문서·주석이 이번 변경을 따라오지 못했다
|
||||
|
||||
- `V21__outbox_aggregate_sequence.sql:10`이 없는 클래스 `JpaOutboxAggregateSequences`를 가리킨다. 실제는 `JpaOutboxStore.nextSequence`다.
|
||||
- `docs/manual/09-outbox-events.md:59-60`은 "application-core 헬퍼로 올리는 일은 01-09 후속"이라고 한다. 같은 diff에 `IntegrationEventDrafts`가 이미 있다.
|
||||
- `OutboxRelayAutoConfiguration.java:96`과 README 트리의 "SKIP LOCKED 리더 선출" 설명이 남았다(NN-13).
|
||||
- `docs/runbooks/outbox-publish-failed.md`·`outbox-dead-letter.md` 머리말의 `last_updated: 2026-06-11`이 내용 변경 뒤에도 그대로다.
|
||||
- 고치는 법: 위치마다 현재 이름과 상태로 고친다.
|
||||
- 심각도 Low · P3 · 증거 E1.
|
||||
|
||||
#### RR-05-10 — 06 영역 발견 5건(NN-10~NN-14)이 조치 추적에서 빠졌다
|
||||
|
||||
- 위치: `docs/reviews/2026-11-01-maturity-review/README.md` 12절 색인(06-01~06-09만), 14·16절.
|
||||
- 무엇: 영역 문서는 14건(High 2·Medium 10·Low 2)을 적는다. 색인·조치 현황·남은 것 어디에도 NN-10(payload 버전 호환성, Medium/P2), NN-11(outbox 두 모델 문서, Medium/P3), NN-12(batch×deadline vs lease 미검사, Medium/P3), NN-13(낡은 설명, Low/P3), NN-14(DLQ 사유 한 값, Low/P3)이 없다. 코드도 NN-13 일부만 바뀌었다.
|
||||
- 고치는 법: 색인에 06-10~06-14로 올리고, 각 항목을 "남음" 또는 결정으로 닫는다.
|
||||
- 심각도 Low · P3 · 증거 E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- V21의 `CREATE UNIQUE INDEX`(CONCURRENTLY 아님)가 큰 `outbox_event`에서 쓰기를 막는 시간 — 표 크기를 모르고, 마이그레이션 잠금 정책은 04 영역 몫이다.
|
||||
- `MessagingInboxSchemaStream`의 `info()` → `baseline()` 사이 다중 인스턴스 동시 기동 경쟁 — Flyway가 같은 baseline marker면 건너뛴다고 보지만 실행으로 확인하지 않았다.
|
||||
- `PUBLISH_RUNTIME_UNAVAILABLE`을 retryable로 바꾼 것이 "그 broker의 runtime이 영영 없는" 설정 오류를 무한 재시도로 숨기는지 — 기동 검증이 그 조합을 막는지 추적하지 않았다.
|
||||
- `createAggregateSequence`의 PK 충돌로 실패한 쓰기 트랜잭션을 호출자가 재시도하는지·어떤 HTTP 응답이 되는지 — sample·persistence 영역 경로다.
|
||||
- relay가 레코드 timestamp를 `occurredAt`으로 보내서, 오래 밀린 행이 topic 보존·timestamp 정책에 걸리는 문제 — 기존 동작이고 broker 설정에 달린다. 무한 재시도와 겹치는 부분만 RR-05-03에 적었다.
|
||||
- relay를 끈 모든 인스턴스도 poll 주기마다 게이지 질의 2개를 돈다 — 부하는 작다고 보지만 재지 않았다.
|
||||
- `messagingCodecs`가 handler bean을 일찍 만들어 생기는 순환 의존 — Javadoc이 알리고 Spring이 기동에서 거부한다. 실제 순환 사례로 시험하지 않았다.
|
||||
- `OutboxRelayShutdownOrderTest`는 platform 대역(같은 phase)을 쓴다. 실제 `MessagingShutdownLifecycle` drain과 실제 SIGTERM은 확인하지 않았다.
|
||||
|
||||
## 28개 관점 — 바뀐 관점만
|
||||
|
||||
| 번호 | 관점 | 이전 → 지금 | 한 줄 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 2 | 구조적 성숙도 | P → O | 소비 경로에 application leaf(`adapter:inbound:messaging`)가 생겼다. application 소비 포트는 이유를 남기고 버렸다 |
|
||||
| 6 | 실패 성숙도 | X → P | 일시 거부·종료·짧은 장애가 더는 DEAD가 되지 않는다. 끝나지 않는 재시도 행의 처분 수단이 없다(RR-05-03) |
|
||||
| 13 | 확장성 | P → O | aggregate 하나가 poll 주기에 묶이지 않는다(tick당 최대 50회차) |
|
||||
| 18 | 배포 성숙도 | X → P | 종료 순서를 relay가 소유하고 앱 경로 실연 lane이 main·nightly 게이트에 있다. 업그레이드 때 순서 번호가 1로 돌아간다(RR-05-02) |
|
||||
| 22 | 추상화 성숙도 | P → O | outcome 어휘가 platform의 "지금만 거부"를 담는다(`REJECTED_RETRYABLE`) |
|
||||
| 25 | 조직 확장성 | P → O | 소비 기능을 registry 간선을 새로 만들지 않고 정해진 leaf에 둔다 |
|
||||
| 28 | 회복 가능성 | X → P | broker 장애 뒤 자동 재개된다. DEAD 수동 재구동 SQL은 일부 행에서 실패한다(RR-05-01) |
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? With fixes.**
|
||||
|
||||
06-01~06-05·06-07~06-09의 수정은 코드와 테스트로 확인했고, 종료 순서와 재시도 분리는 설계대로 동작한다. 다만 DEAD runbook 재발행 SQL(RR-05-01)은 실 PG에서 실패가 재현됐고 고치기 쉬우므로 먼저 고친다. 업그레이드 때 순서 번호가 1로 돌아가는 문제(RR-05-02)는 파생 서비스가 이 변경을 받기 전에 시작값이나 절차를 정한다.
|
||||
@@ -0,0 +1,283 @@
|
||||
# 06 bootstrap·build·CI 재리뷰 (2026-11-03)
|
||||
|
||||
리뷰 대상: Base `01a8a2a70` → Head `5786126c`, 영역 번호 06(slug `bootstrap-build-ci`). 원래 영역 문서는
|
||||
`docs/reviews/2026-11-01-maturity-review/07-bootstrap-composition-config.md`,
|
||||
`08-build-ci-test.md`, `09-performance-measurement.md`(샘플 쪽)다. 경로는 저장소 루트 기준이다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
```text
|
||||
src/app-bootstrap src/sample-portfolio src/build-logic src/build.gradle src/settings.gradle src/gradle
|
||||
src/gradle.properties src/optional-platforms src/config src/Dockerfile src/Dockerfile.sample
|
||||
src/.env.example .github docker-compose*.yml infra/postgres infra/fileserver
|
||||
scripts/run-compose-runtime-smoke.sh scripts/verify-compose-profile-contracts.sh AGENTS.md CLAUDE.md
|
||||
docs/registries docs/testing docs/capability-status.md
|
||||
```
|
||||
|
||||
`git diff --stat` 기준 259파일 +8,251 −2,008. 하위 에이전트 없이 여러 번에 나눠 직접 읽었다.
|
||||
|
||||
- 전부 읽은 것: build-logic main diff 전체(`StrictLaneStagesPlugin`, `WorkflowGradleInvocations`,
|
||||
`StrictTestLanePlugin`, `JavaConventionsPlugin`, `QualityConventionsPlugin`, `ModuleRegistry`,
|
||||
`ArchitecturePlugin`, `ConfigContractPlugin`·`EnvContractVerifier`), 루트 `build.gradle`, optional-platforms의
|
||||
`settings.gradle`·`gradle.properties`·`build.gradle`, workflow diff 전체(`integration-main.yml` 전문,
|
||||
`ci-quality-gates.yml`, `release.yml`), `config/spotbugs/exclude.xml` 전문, `container-images.properties`,
|
||||
compose 파일·`compose-profile-contracts.json`·검사 스크립트 diff, app-bootstrap main diff 전체와
|
||||
`build.gradle` 전문, sample main diff 전체와 `application.yml` 전문, AGENTS.md·CLAUDE.md diff.
|
||||
- 표본으로 읽은 것: repository-contract 태그 16개 클래스가 읽는 파일 목록(입력 선언과 대조), 새 system·integration
|
||||
테스트의 단언부, `env-keys.yaml` diff 앞부분, `docs/testing/TESTING_STRATEGY.md` 9절, `docs/capability-status.md` diff.
|
||||
- pathspec 밖에서 확인용으로 읽은 것: support `StartupRuleRunner`·`StartupRule`·`StartupRuleAutoConfiguration`,
|
||||
persistence-jpa `JpaStartupAutoConfiguration`의 rule bean 선언, `grpc/grpc-testkit/build.gradle`,
|
||||
objectstorage `build.gradle`, SpotBugs 제외 표본 확인용 `JdbcOutboxRepository`·`MessageHeaders`·`AuthorizationPrincipal`.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → severity별 Issues → Declined → Assessment), "테스트가 mock이 아닌 실제 동작을 보는가", "읽지 않은 코드에 좋다고 하지 않는다" | 새 system 테스트가 실제 서버·실 PostgreSQL·실 OTLP 수신기를 쓰는지 확인. 의심 가는 것은 worktree에서 실행해 확인 |
|
||||
| `ci-cd-and-automation` | "No gate can be skipped", Red flag "CI failures ignored or silenced", 캐시 최적화가 결과를 바꾸면 안 된다, CI 설정 안 비밀값 | strict lane 단계 연결(`verifyStrictLaneStages`), `--continue`, build cache가 실패해야 할 lane을 녹색으로 돌려주는지, Redis lane fixture 비밀번호 |
|
||||
| `refactor` | 동작 보존, 중복 코드, 죽은 코드 | 샘플을 그대로 복제해도 안전한가 — 죽은 설정 블록, 두 갈래 충돌 변환, 같은 lane 중복 실행 |
|
||||
| `documentation-and-adrs` | "Rules files are current and accurate", "Known gotchas documented inline", 결정에 이유가 남아 있는가 | AGENTS.md·CLAUDE.md·build-logic README·capability-status·env 레지스트리를 코드와 대조. 숨은 제약이 Javadoc에만 있는지 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
worktree `scratchpad/rr-06`(HEAD `5786126c`)에서 `flock heavy.lock`으로 감싸 실행했다. 시작 부하 6~23. 끝난 뒤
|
||||
`git worktree remove --force`로 지웠다. 메인 체크아웃은 건드리지 않았다.
|
||||
|
||||
| # | 명령 | 결과 |
|
||||
| --- | --- | --- |
|
||||
| 1 | `MessagingEnvelopeSchemaResourceTest`에 `@Disabled` 테스트 1개 추가, `shared-contract/build.gradle`의 `rejectSkipped = false` → `./gradlew :shared-contract:messagingSharedSchemaQualificationTest` | SUCCESS, 결과 XML `skipped="1"` |
|
||||
| 1-b | 같은 lane에서 `rejectSkipped = true`로만 바꾸고 같은 명령 | **`UP-TO-DATE`, BUILD SUCCESSFUL** |
|
||||
| 1-c | `--rerun` | FAILED: "forbids skipped tests but observed 1 skipped test(s)" |
|
||||
| 1-d | lane 결과 폴더를 지우고 다시 실행 | **`FROM-CACHE`, BUILD SUCCESSFUL** |
|
||||
| 2 | support test에 probe 추가: JavaBean `@ConfigurationProperties("probe")` + non-static `@Bean StartupRule probeRule(ProbeSettings)`, `probe.name=bound` → `./gradlew :adapter:outbound:support:test --tests '*RR06EarlyRuleProbeTest*'` | runner 없음: `name=bound`. runner 있음: 기동 성공, **`name=null`**, 경고 없음. rule이 null을 위반으로 보면 "probe.name is missing"으로 기동 실패. 설정을 생성자 주입하는 변형은 "No default constructor found" |
|
||||
| 3 | `./gradlew :sample-portfolio:spotbugsMain`(현재 exclude) | BugInstance 0 |
|
||||
| 3-b | exclude에서 EI 패턴 1과 `~.*SecurityConfig` CSRF Match를 빼고 sample·application-core·domain-core·shared-contract·web·app-bootstrap·service-runtime·support `spotbugsMain --continue` | EI 23건 전부 협력 객체(리포지토리·유스케이스·`EntityManager`·예외 cause·`BeanFactory`). CSRF 4건: web `SecurityConfig`, `ManagementSecurityConfig`, `SampleManagementSecurityConfig`, `SampleDemoSecurityConfig` |
|
||||
| 4 | `./gradlew :verifyStrictLaneStages --dry-run` | "every strict lane is in an executed stage" |
|
||||
| 4-b | `integration-main.yml`의 `:integrationCheck` 줄에 `-x :adapter:outbound:persistence-jpa:postgresqlIdempotencyIntegrationTest` 추가 후 같은 명령 | **여전히 통과** |
|
||||
|
||||
돌리지 않은 것: `ci`·`mainCheck`·`integrationCheck` 전체(README 16.2의 오케스트레이터 실행을 근거로 삼았다),
|
||||
`docker build`, compose 실제 기동, GitHub Actions 실행.
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 실제 CI runner에서의 workflow 실행과 `gradle/actions/setup-gradle`의 캐시 복원 범위. RR-06-02의 CI 전파는 action 설정
|
||||
(`cache-read-only`)에서 추론했다.
|
||||
- app-bootstrap document-contract 21개 클래스 본문, `env-keys.yaml` diff 뒷부분(키 이름·주석만 훑음).
|
||||
- sample posterimage 경로(application 클래스 45개)는 diff 표본만 봤다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **lane 도달성을 Gradle 자신의 계획으로 판정한다.** `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java:104-145`.
|
||||
문자열 contains가 아니라 `--dry-run` task graph를 읽는다. `--dry-run`·`-p` 명령은 실행으로 세지 않는다. TestKit 6건과 reader 테스트 8건이 있다.
|
||||
- **YAML folded block의 빈 줄 결함(22곳)을 검사로 고정했다.** `WorkflowGradleInvocations.java:95-131`, workflow 5개 diff.
|
||||
- **캐시 허용을 lane 범주로 나누고 이유를 코드에 적었다.** `StrictTestLanePlugin.java:223-231, 307-333`. `StrictTestLaneConventionTest`가 FROM_CACHE와 SUCCESS를 TestKit으로 단언한다.
|
||||
- **저장소를 읽는 테스트를 두 lane으로 나눴다.** `src/app-bootstrap/build.gradle:316-387`. 저장소 루트를 두 lane에만 준다. 그래서 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다. repository-contract 16개 클래스가 읽는 파일을 표본 대조했고 모두 선언된 입력 안에 있었다.
|
||||
- **기동 rule이 DB 연결·마이그레이션 전에 돈다.** `src/adapter/outbound/support/.../startup/StartupRuleRunner.java:51-67`(BFPP). `StartupRuleRunnerTest`가 "다른 빈이 하나도 만들어지기 전"을 단언한다.
|
||||
- **트레이스 수출을 실제 수신기로 검증한다.** `src/app-bootstrap/src/systemTest/.../TracingExportSystemTest.java:40-92`. OTLP 본문 바이트 안에서 응답의 trace id를 찾는다. mock이 아니다.
|
||||
- **샘플 인가를 실행본 그대로 검증한다.** `SampleWorkLogAuthorizationSystemTest`는 `SamplePortfolioApplication` 전체를 RANDOM_PORT + 실 PostgreSQL로 띄워 401·403·204·201을 확인한다.
|
||||
- **SQL 비용을 실제 서버에서 숫자로 고정한다.** `src/sample-portfolio/src/systemTest/.../WorkLogStatementCostSystemTest.java:85-131`(목록 20·100건 모두 2문장, batch 100건 8왕복, 제목 PATCH 시 컬렉션 쓰기 0).
|
||||
- **중복 규칙을 DB가 지킨다.** `src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql`은 기존 중복이 있으면 이유와 함께 실패한다. adapter는 제약 이름이 일치할 때만 409로 바꾼다(`PosterRepositoryAdapter.java:72-91`).
|
||||
- **SpotBugs 제외에 이유가 붙어 있고 넓은 패턴은 필드 타입으로 좁혔다.** `src/config/spotbugs/exclude.xml:94-149`. 실험 3-b에서 EI 패턴 1을 빼고 8개 leaf를 돌렸다. 나온 EI 23건은 모두 협력 객체였다. 이 패턴이 진짜 결함을 가린 표본은 찾지 못했다.
|
||||
- **Redis lane이 운영과 같은 인증 모양이다.** `docker-compose.infra.yml:140-180`이 ACL 파일을 그대로 마운트한다. `scripts/verify-compose-profile-contracts.sh` check 7이 계정·비밀번호·key pattern을 실제 마운트 파일과 대조한다.
|
||||
- **복사본이 갈라지면 실패한다.** `src/optional-platforms/settings.gradle:23-36`이 `gradle.properties` 두 벌의 동일성을 검사한다.
|
||||
- **미등록 leaf를 잡는다.** `ModuleRegistry.unregisteredBuildScripts`(`ModuleRegistry.java:189-246`) + `VerifyCleanArchitectureDependenciesTask`.
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
상태: 닫힘 / 부분 / 회귀 / 결정으로 닫힘. `>`는 다른 영역 소관.
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| 07-01 | 닫힘 | Boot tracing 모듈로 교체. `TracingExportSystemTest.java:58-92`가 실제 OTLP 수신과 trace id 일치를 본다. endpoint가 비면 exporter bean 0개(`:95-108`) |
|
||||
| 07-02 | 닫힘(새 위험 RR-06-01) | `StartupRuleRunner.java:51-67` BFPP. `SecretSourceValidator`·`StartupSafetyValidator`가 rule로 옮겼다. rule을 static으로 선언해야 한다는 제약은 강제되지 않는다 |
|
||||
| 07-03 | 닫힘 | `SampleDemoSecurityConfig.java:33-86` + 메서드 보안 유지(`SamplePortfolioApplication.java:31`). 실서버 테스트 `SampleWorkLogAuthorizationSystemTest` |
|
||||
| 07-04 | 닫힘(대안 검증) | `Dockerfile.sample:56-63`에 `gradle.properties`·`build-logic/`. `DeveloperExperienceContractTest.java:384-401`이 두 Dockerfile 의존성 단계 COPY 줄 동일성을 단언. 실제 `docker build`는 이번에 다시 돌리지 않았다 |
|
||||
| 07-05 | 닫힘(02-03과 묶음) | audience 필수. `application.yml:45-47` 주석 갱신. 본체는 02 영역 |
|
||||
| 07-06 | 닫힘 | `logback-spring.xml:21-60`이 `app.logging.*`을 읽는다. `LoggingSettings` 삭제. `LoggingConfigurationRule`·`LoggingSettingsSourceSystemTest` |
|
||||
| 07-07 | 닫힘(잔여 RR-06-08) | compose `stop_grace_period: 60s`(`docker-compose.yml:88`), `AWAIT_TERMINATION_SECONDS` 공개 상수, 합계 단언 테스트. drain 30초는 테스트에 리터럴로 남음 |
|
||||
| 07-08 | 부분(RR-06-10) | durable-operation 모듈 분리, 권한 매핑 모듈 이동, fileserver 볼륨 overlay, dev/prod 프로필 정리 완료. 원래 항목 (6) `ConfigContractPlugin.java:24`가 redis-runtime을 이름으로 아는 것은 그대로 |
|
||||
| 07-09 | 닫힘(01 영역과 공유) | AGENTS.md 기능 개발 프로토콜에 "sample은 배치 예시가 아니다" 추가, `scripts/new-feature.sh`·`verifyFeatureScaffold`(mainCheck). 표본만 확인 |
|
||||
| 07-10 | 부분(RR-06-06, RR-06-07) | bootstrap 설정 strict 바인딩(`AsyncExecutorSettings`·`RuntimeSafetySettings`·`BootstrapSettings`·`SecretSourceSettings`), compose·logback이 `verifyEnvKeys` 입력. sample yml 죽은 블록과 smoke 래퍼·lane json의 키는 남음 |
|
||||
| 07-11 | 닫힘(새 drift RR-06-11) | 지목된 줄은 모두 고침. 같은 종류의 새 drift가 생김 |
|
||||
| 07-12 | 닫힘(문서) | `config/server.yml:15-22` 주석. 실측은 없음(주석이 그렇게 말함) |
|
||||
| 07-13 | 닫힘 | `docker-compose.yml:61`, `docker-compose.dev.yml:67` loopback. `DeveloperExperienceContractTest.java:428-` 단언 |
|
||||
| 07-14 | 닫힘 | `RuntimeEnvironmentProfileValidator.java:86` class literal |
|
||||
| 08-01 | 부분(RR-06-03, RR-06-04) | main build는 닫힘: `integration-check`·`performance-check` 잡(`integration-main.yml:165-212`), sample systemTest가 mainCheck(`src/build.gradle:192`), `verifyStrictLaneStages`가 PR 게이트. optional-platforms build는 검사 밖이고 `grpcPerformanceTest`가 여전히 어디서도 돌지 않는다 |
|
||||
| 08-02 | 닫힘(새 위험 RR-06-02) | `StrictTestLanePlugin.java:223-231`. app-bootstrap이 `systemTestCheck`에서 빠짐(`src/build.gradle:124-131`). lane 정책(`rejectSkipped`)이 캐시 키에 없다 |
|
||||
| 08-03 | 닫힘 | `app-bootstrap/build.gradle:316-387`, `test`가 `repository-contract` 제외 |
|
||||
| 08-04 | 부분(RR-06-09) | main-check `--continue`(`integration-main.yml:85`), 이미지 목록 한 파일(MinIO는 결정으로 objectstorage 소유), mirror prefix 안내. 원래 (d) MinIO lane 중복은 오히려 늘었다 |
|
||||
| 08-05 | 닫힘 | `ModuleRegistry.java:189-246`, `VerifyCleanArchitectureDependenciesTask.java:65-72`, `ModuleRegistryTest` |
|
||||
| 08-06 | 닫힘 | optional `gradle.properties` + 동일성 검사, ARCHITECTURE lane이 실서버 슬롯을 잡지 않음(`StrictTestLanePlugin.java:187-201`) |
|
||||
| 08-07 | 결정으로 닫힘(잔여 RR-06-05) | MEDIUM으로 내림, 제외마다 이유. sample은 어떤 단계도 분석하지 않는다 |
|
||||
| 09-01 | 닫힘 | 목록이 요약 projection을 쓴다. `WorkLogStatementCostSystemTest.java:85-94` |
|
||||
| 09-02 | 닫힘 | `V8_1` 유일 인덱스 + adapter 변환 + `CreatePosterConcurrencyIntegrationTest`(integrationCheck) |
|
||||
| 09-03 | 닫힘 | 07-03과 같은 수정 |
|
||||
| 09-04 | 닫힘 | `SampleApiDocsSystemTest`(sample systemTest, mainCheck) |
|
||||
| 09-05 | > 04 | persistence-jpa 소관 |
|
||||
| 09-06 | 닫힘 | `WorkLogRepositoryAdapter.java:56-71` 관리 엔티티 갱신, `WorkLogEntity.replaceState`. 테스트 `:97-108` |
|
||||
| 09-07 | 닫힘 | sample `application.yml:61-71` batch 50 + order_inserts. 테스트 `:120-131`(8왕복) |
|
||||
| 09-08 | 부분(RR-06-06) | `SampleRuntimeDefaultsContractTest`는 키 3개만 본다. sample yml 머리말의 "읽는 설정만"은 사실이 아니다 |
|
||||
| 09-09 | > 04 | persistence-jpa 소관 |
|
||||
| 09-10 | 닫힘 | `application-local.yml:118` `${APP_SERVER_PORT:8080}` |
|
||||
| 09-11 | 결정으로 닫힘 | 15절: Jackson 2 유지 |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-06-01 · 기동 rule을 static이 아닌 `@Bean`으로 선언하면 설정이 조용히 바인딩되지 않는다
|
||||
|
||||
- **위치**: `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:51-67`(pathspec 밖, 07-02 수정), 제약 설명은 `StartupRule.java:12-22`와 `src/app-bootstrap/CLAUDE.md:88-90`뿐. 같은 방식으로 기대는 곳: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceConfig.java:33-35`(`RequiredProductionSecrets`를 rule 실행 때 꺼냄).
|
||||
- **무엇이 틀렸나**: runner가 `BeanFactoryPostProcessor`가 되면서 rule bean은 어떤 `BeanPostProcessor`보다 먼저 만들어진다. rule을 non-static `@Bean` 메서드로 선언하고 설정 bean을 인자로 받으면, 그 설정 bean도 BPP 없이 먼저 만들어진다. JavaBean 방식 `@ConfigurationProperties`의 바인딩은 BPP가 하므로 값이 들어가지 않는다. singleton이라 앱이 끝날 때까지 그 상태로 남는다.
|
||||
- **증거 (E3)**: 실험 2. 같은 설정(`probe.name=bound`)으로 runner가 없으면 `bound`, runner가 있으면 `null`이었다. 기동은 성공했고 경고는 없었다. 생성자 주입 변형은 "No default constructor found"라는 엉뚱한 메시지로 실패했다.
|
||||
- **왜 중요한가**: 이 제약은 Javadoc과 CLAUDE.md 한 줄에만 있다. 새 capability 작성자가 흔한 모양(설정 bean을 받는 `@Bean` 메서드)으로 rule을 쓰면, 그 rule은 기본값을 검사한다. 같은 설정 bean을 쓰는 다른 코드도 기본값으로 동작한다. 사용자 원칙 "개발자가 따로 기억해야 하는 숨은 위험은 결함"에 해당한다. 템플릿 자신도 CLAUDE.md의 "parameterless"를 지키지 않는다(`StartupSafetyValidator(ListableBeanFactory)`, `SecretSourceValidator(ObjectProvider)`). 현재 선언 13곳은 모두 static이라 지금 터지는 곳은 없다.
|
||||
- **고치는 법**: runner가 rule을 꺼내기 전에 정의를 검사해 거절한다. `beanFactory.getBeanDefinition(name)`이 `AnnotatedBeanDefinition`이면 `getFactoryMethodMetadata().isStatic()`과 인자 타입(`Environment`·`ListableBeanFactory`·`ObjectProvider`만 허용)을 확인하고, 아니면 이름을 대며 기동을 실패시킨다. 더 단순한 대안은 rule 생성 전후 `getSingletonCount()`를 비교해 rule 말고 다른 singleton이 생겼으면 실패시키는 것이다. 둘 다 위 probe를 RED 테스트로 쓸 수 있다. `RequiredProductionSecrets`에도 같은 검사를 건다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2.
|
||||
|
||||
#### RR-06-02 · build cache가 지금의 lane 정책이라면 실패했을 결과를 녹색으로 돌려준다
|
||||
|
||||
- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLanePlugin.java:223-231`(캐시 허용), `:277`(`isRejectSkipped()`는 `doLast`에서만 읽는다). CI 전파 경로: `.github/actions/setup-gradle-java/action.yml`(`cache-read-only: github.ref != main`).
|
||||
- **무엇이 틀렸나**: 08-02 수정으로 TEST·ARCHITECTURE lane은 up-to-date와 build cache를 쓴다. 그런데 `rejectSkipped`는 task 입력이 아니다. lane이 skip을 포함한 채 통과해 캐시에 들어간 뒤 `rejectSkipped = true`로 바꾸면, 입력이 같아서 이전 결과를 그대로 쓴다. `doLast` 검사는 돌지 않는다.
|
||||
- **증거 (E3)**: 실험 1. `rejectSkipped`를 true로 바꾼 직후 `UP-TO-DATE` 성공, 결과 폴더를 지우면 `FROM-CACHE` 성공. `--rerun`에서만 "forbids skipped tests"로 실패했다. 실패한 실행은 캐시에 저장되지 않으므로 녹색 항목이 계속 남는다.
|
||||
- **왜 중요한가**: 정책을 강화하는 PR이 자기 효과를 보지 못하고 merge된다. main에서 저장한 캐시를 PR이 읽으므로(action 설정 기준, 실측 아님) CI에서도 같다. 테스트 클래스가 바뀔 때까지 강화가 적용되지 않는다. ci-cd 스킬의 "CI failures silenced"에 해당한다. 같은 변경으로 release 증거 잡(`release.yml` `webAdvancedTest`, gRPC 3 lane)도 캐시 결과를 증거로 올릴 수 있게 됐다. 원래 08-02 권고는 증거 잡에 `--rerun-tasks`였다.
|
||||
- **고치는 법**: lane 정책을 입력으로 등록한다. `test.getInputs().property("strictLane.rejectSkipped", lane.isRejectSkipped())`, 그리고 `requires` 목록과 `explicitOnly` 여부도 같은 방식으로. TestKit에 "정책만 바꾼 두 번째 실행은 SUCCESS가 아니라 다시 실행한다"를 추가한다. release 증거 잡은 `--rerun-tasks`를 붙이거나 그 lane을 `doNotCacheIf`로 뺀다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2.
|
||||
|
||||
#### RR-06-03 · `verifyStrictLaneStages`는 optional-platforms build를 보지 않는다 — `grpcPerformanceTest`가 여전히 어디서도 돌지 않는다
|
||||
|
||||
- **위치**: `StrictLaneStagesPlugin.java:129-137`(`root.getAllprojects()` — main build만), `src/optional-platforms/build.gradle:1-3`(`ca.strict-lane-stages` 미적용, `performanceCheck` 없음), `src/grpc/grpc-testkit/build.gradle:27-32`(`performance()`, `explicitOnly` 아님). 문서: `AGENTS.md:79-83`, `CLAUDE.md:40-42`, `src/build-logic/README.md:19`.
|
||||
- **무엇이 틀렸나**: 문서는 "`explicitOnly`가 아닌 모든 strict lane"을 검사한다고 말한다. 실제로는 main build의 lane만 본다. optional build의 `grpcPerformanceTest`는 performance lane인데 어느 workflow도 부르지 않는다(release.yml은 다른 3 lane만 이름으로 부른다). 08-01이 찾은 모양 그대로다.
|
||||
- **증거 (E2·E1)**: 실험 4에서 검사가 "every strict lane is in an executed stage"로 통과했다. 같은 시점에 `grpcPerformanceTest`를 부르는 run 줄은 workflow 15개에 없다(`grep`). optional build의 lane 연결은 아직 문자열 contains 테스트(`DeveloperExperienceContractTest.java:360-381`) 하나에 기댄다 — 원래 08-01이 기각한 방식이다.
|
||||
- **왜 중요한가**: lane을 추가하는 사람은 "검사가 막아 준다"고 믿는다. optional build에서는 그 믿음이 틀린다. 지금 1개 lane이 그 상태다.
|
||||
- **고치는 법**: optional build 루트에도 `ca.strict-lane-stages`를 적용하고 stage를 `ci`·`integrationCheck`·(신설) `performanceCheck` 또는 `explicitOnly`로 선언한다. workflow 쪽은 `-p optional-platforms <stage>`를 그 build의 실행으로 세도록 reader에 build 디렉터리 인자를 준다. `grpcPerformanceTest`는 주석의 의도대로 `explicitOnly("a measurement on a shared runner is a flaky test; run by name")`로 바꾼다. 문서의 "모든"을 범위에 맞게 고친다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-06-04 · stage 검사는 `-x` 제외·job 조건·`continue-on-error`를 보지 않는다
|
||||
|
||||
- **위치**: `WorkflowGradleInvocations.java:59-64`(`executesInStartBuild`), `:239-240`(`-x` 값을 건너뛰기만 함).
|
||||
- **무엇이 틀렸나**: run 줄에 stage 이름만 있으면 실행으로 센다. `-x <lane>`으로 lane을 빼도, job이 `continue-on-error: true`나 `if:`로 막혀 있어도 통과한다.
|
||||
- **증거 (E3)**: 실험 4-b. `:integrationCheck`에 `-x :adapter:outbound:persistence-jpa:postgresqlIdempotencyIntegrationTest`를 붙여도 통과했다. 그 lane은 integrationCheck에만 있으므로 어디서도 돌지 않게 된다. 지금 workflow에는 이런 줄이 없다.
|
||||
- **고치는 법**: `-x` 값을 모아 plan에서 빼고 판정한다. `continue-on-error: true` job의 명령은 실행으로 세지 않는다. 둘 다 reader 단위 테스트 1건씩.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E3.
|
||||
|
||||
#### RR-06-05 · sample은 SpotBugs를 한 번도 거치지 않는데 exclude에는 sample 항목이 있다. CSRF 제외 이유가 sample 데모 체인에는 맞지 않는다
|
||||
|
||||
- **위치**: `src/build.gradle:85-93`(`qualityCheck`는 `leafPaths` = sample 제외, `runOnCheck=false`), `src/config/spotbugs/exclude.xml:24-27`(`~.*SecurityConfig`), `:335`(sample `PosterImageUploadIntent`), `QualityConventionsPlugin.java:99-101`("A new finding fails qualityCheck").
|
||||
- **무엇이 틀렸나**: (1) 어떤 단계도 sample의 `spotbugsMain`을 부르지 않는다. 그래서 sample의 새 코드는 분석되지 않는다. exclude의 sample 항목은 닿지 않는 규칙이다. (2) `~.*SecurityConfig` 제외의 이유는 "stateless JWT, no ambient cookie auth"다. 새 `SampleDemoSecurityConfig`는 HTTP Basic이다. 브라우저는 Basic 자격 증명을 기억해 같은 origin 요청에 자동으로 붙인다. 이유가 이 클래스에는 거짓이다.
|
||||
- **증거 (E3)**: 실험 3·3-b. 현재 exclude로 0건, Match를 빼면 `SampleDemoSecurityConfig`에 `SPRING_CSRF_PROTECTION_DISABLED`.
|
||||
- **왜 중요한가**: 데모 계정 비밀번호가 공개이고 prod는 기동을 거부하므로 sample 자체의 피해는 없다. 문제는 복제되는 예시다. dev에서 실제 계정으로 이 체인을 복제하면 CSRF가 열린다. 그리고 그 사실을 알려 줄 도구가 sample에서는 꺼져 있다.
|
||||
- **고치는 법**: sample job에 `:sample-portfolio:qualityCheck`를 넣거나 sample 항목을 지운다. CSRF Match는 클래스 이름 목록으로 좁히고, `SampleDemoSecurityConfig`는 이유("공개 데모 계정, prod 거부")를 단 별도 Match로 둔다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E3.
|
||||
|
||||
#### RR-06-06 · sample `application.yml` 머리말은 "읽는 설정만"이라고 말하지만 읽는 곳이 없는 블록이 남아 있다
|
||||
|
||||
- **위치**: `src/sample-portfolio/src/main/resources/application.yml:3`(머리말), `:210-211`(`app.messaging.broker`), `:212-216`(`app.notification.*`), `:217-235`(`app.outbound.http.*` 17키).
|
||||
- **무엇이 틀렸나**: `app.outbound.http.*`는 저장소 어디에도 읽는 코드가 없다(`src/README.md:357`이 "canonical 설정이 아니다"라고 적는다). messaging·notification 모듈은 sample의 classpath에 없다(`sample-portfolio/build.gradle:66-88`). sample yml은 `verifyEnvKeys`의 설정 파일 입력도 아니다(`ConfigContractPlugin.java:26-45`).
|
||||
- **왜 중요한가**: sample은 가장 먼저 복제된다. 복제한 사람은 이 키로 HTTP 타임아웃·재시도를 조정한다고 믿는다. 07-10의 (3)과 09-08이 노린 결함이다.
|
||||
- **고치는 법**: 세 블록을 지운다. `SampleRuntimeDefaultsContractTest`에 "sample yml의 `app.*` 최상위 키는 sample classpath의 설정 prefix 중 하나"를 단언하거나, sample yml을 `verifyEnvKeys` 설정 입력에 넣는다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E1.
|
||||
|
||||
#### RR-06-07 · compose lane 계약 json과 smoke 래퍼의 `APP_*` 키는 env 계약 검사 밖이다
|
||||
|
||||
- **위치**: `scripts/run-compose-runtime-smoke.sh:41-53`(`CAPABILITIES_OFF`), `src/config/runtime/compose-profile-contracts.json`(각 lane `activationEnv`), `ConfigContractPlugin.java:46-57`(compose yml·logback만 operator 파일).
|
||||
- **무엇이 틀렸나**: r3-f가 손으로 찾은 `CASKELETON_GRPC_ENABLED`(아무도 읽지 않는 키)와 같은 결함이 다시 생겨도 게이트가 모른다. 고친 키 `APP_GRPC_SERVER_ENABLED`와 기존 `APP_OBJECTSTORAGE_ENABLED`는 relaxed binding으로 동작하지만 레지스트리에 없다.
|
||||
- **고치는 법**: `verifyEnvKeys`의 operator 입력에 lane json의 `activationEnv` 키와 스크립트의 `CAPABILITIES_OFF`를 더한다. 레지스트리에 없는 capability 끄기 키는 등록한다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E1.
|
||||
|
||||
#### RR-06-08 · 종료 예산의 web drain 30초가 테스트에 리터럴로 있고, runbook은 옛 예산을 말한다
|
||||
|
||||
- **위치**: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java:410`(`webDrainSeconds = 30`), `docs/runbooks/job-timeout.md:51`(pathspec 밖, "shutdown 예산(20s) vs k8s 30s").
|
||||
- **무엇이 틀렸나**: drain은 `APP_SERVER_SHUTDOWN_TIMEOUT`으로 바뀌는 값이다. 레지스트리 기본값이 바뀌어도 테스트는 30으로 계산한다. 원래 완료 기준 "숫자는 한 곳"을 채우지 못했다. runbook의 20초는 이제 30+19초다. k8s grace 30초면 async 대기 중 SIGKILL이다.
|
||||
- **고치는 법**: 테스트가 `env-keys.yaml`의 `APP_SERVER_SHUTDOWN_TIMEOUT` 기본값을 읽는다. runbook 문장을 49초 + preStop 기준으로 고친다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E1.
|
||||
|
||||
#### RR-06-09 · MinIO lane이 main push마다 두 잡에서 돈다
|
||||
|
||||
- **위치**: `src/adapter/outbound/objectstorage/build.gradle:162`(leaf `mainCheck` → MinIO 2 lane), 같은 lane이 `integration()`이라 `:integrationCheck`에도 들어간다. `integration-main.yml:67-85`와 `:165-176`이 같은 push에서 병렬로 돈다. PR 경로 필터 workflow `object-storage-qualification.yml:36,46`도 있다.
|
||||
- **무엇이 틀렸나**: 원래 08-04 (d) "중복은 하나만"이 처리되지 않았다. 08-01 수정 뒤 실행 위치가 세 곳이 됐다.
|
||||
- **고치는 법**: objectstorage `mainCheck`의 의존을 지운다. 컨테이너 lane은 integrationCheck가 소유한다는 규칙과도 맞는다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E1.
|
||||
|
||||
#### RR-06-10 · env 계약 태스크가 여전히 특정 leaf를 안다 (07-08 항목 6)
|
||||
|
||||
- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/config/ConfigContractPlugin.java:24`(`dependsOn(':adapter:outbound:redis-runtime:compileJava')`), `:58-62`(그 leaf의 metadata 경로).
|
||||
- **무엇이 틀렸나**: capability 기준 7("이 모듈을 아는 곳은 모듈 자신뿐")의 남은 한 곳이다. redis-runtime을 지우거나 옮기면 `verifyEnvKeys`가 깨진다. 14·16절 어디에도 이 항목의 처리나 보류 이유가 없다.
|
||||
- **고치는 법**: metadata를 내보내는 leaf가 자기 산출물을 등록하는 방식(예: 각 leaf의 `spring-configuration-metadata.json`을 configuration으로 노출하고 app-bootstrap이 runtime classpath에서 모음)으로 바꾸거나, 보류 이유를 결정 기록에 남긴다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E1.
|
||||
|
||||
#### RR-06-11 · 이번 수정 뒤 새로 어긋난 문서·주석
|
||||
|
||||
- **무엇이 틀렸나** (모두 E1):
|
||||
- `src/build-logic/README.md:64` "a lane never reports up-to-date" — 08-02 뒤 TEST·ARCHITECTURE lane은 up-to-date다.
|
||||
- `src/grpc/grpc-testkit/build.gradle:7-9` "none of them can serve an up-to-date result" — 같은 이유로 거짓(pathspec 밖).
|
||||
- `CLAUDE.md:134-137`, `AGENTS.md:205` — mainCheck 구성에 `:sample-portfolio:systemTest`와 `verifyFeatureScaffold`가 빠져 있다(`src/build.gradle:192,197`).
|
||||
- `src/app-bootstrap/src/main/resources/config/runtime.yml:22`, `config/observability.yml:114` — "@ConfigurationProperties로 바인딩"이라고 말한다. 이제 `StrictSettingsBinder`이고, `app.logging`은 settings record가 없다.
|
||||
- `src/sample-portfolio/.../bootstrap/management/SampleManagementSecurityConfig.java:24` "order 0으로 main chain보다 먼저" — 데모 체인은 `@Order(-100)`에 `/**`라 먼저 매칭된다. actuator 체인은 닿지 않는다(이전부터 있던 상태지만 이번 diff가 이 흐름을 바꿨다).
|
||||
- `docs/capability-status.md:34` — "`postgresqlIdempotencyIntegrationTest`, but no workflow runs it"는 이제 거짓이다(integrationCheck). 같은 행의 `IdempotencyProviderSelectionConfig`·`SampleIdempotencyConfig`는 main 소스에 없다.
|
||||
- `src/sample-portfolio/build.gradle:199` — jvmArgs를 지운 뒤 "Pin UTC" 주석만 남았다.
|
||||
- **고치는 법**: 위 줄을 코드에 맞춘다. 문서 대조 parser를 두지 않는 방침이므로 이번 리뷰 목록으로 처리한다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E1.
|
||||
|
||||
#### RR-06-12 · 샘플의 "DB가 지키는 유일 규칙" 예시가 계약을 산문으로만 두고, 두 흐름이 충돌을 다르게 바꾼다
|
||||
|
||||
- **위치**: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/domain/poster/PosterRepository.java:8-13`(domain 포트 Javadoc이 application 예외를 약속), `PosterRepositoryAdapter.java:6,72-91`(adapter가 `application.poster.PosterTitleAlreadyExistsException`을 던짐), 비교: `WorkLogRepositoryAdapter.java:63-66`(Spring `ObjectOptimisticLockingFailureException`을 그대로 던짐).
|
||||
- **무엇이 틀렸나**: domain 포트의 계약이 application 타입을 가리킨다. 코드로는 표현할 수 없어 Javadoc에만 있다. PosterRepository에는 fake도 공유 계약도 없어(단위 테스트는 Mockito mock) 이 약속을 실제 adapter만 지킨다. 같은 sample 안에서 WorkLog는 프레임워크 예외를, Poster는 application 예외를 adapter가 던진다.
|
||||
- **왜 중요한가**: 이 sample은 09-02 수정의 따라 할 예시다. 복제하는 사람은 두 모양 중 하나를 고른다. AGENTS.md 테스트 규칙(fake와 adapter가 한 계약을 상속)도 이 포트에는 적용되지 않았다.
|
||||
- **고치는 법**: 포트 옆(domain)에 `DuplicatePosterTitleException` 같은 타입을 두고 use case가 application 예외로 바꾸거나, 포트가 결과 타입을 돌려주게 한다. `PosterRepositoryContract`(fake + adapter)에 "같은 제목 두 번째 save는 거절"을 둔다. 매뉴얼에 충돌 변환 위치를 하나로 적는다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- `AuthenticationModeCompositionConfig`가 여전히 `SmartInitializingSingleton`(모든 singleton 뒤)이다 — 빈 이름만 보므로 rule로 옮길 수 있지만, 바뀌는 것은 Redis 연결 하나라 피해가 작고 CLAUDE.md "빈이 필요한 검사는 빈으로 남는다"와 맞아 판단을 미룬다.
|
||||
- Redis lane이 `APP_REDIS_NAMESPACE_ENVIRONMENT=prod`(local 프로필)를 쓴다 — 15절 결정(r3-K)이다. 새 위험은 문서화돼 있어 뒤집지 않았다.
|
||||
- `performance-check` 잡의 `GRADLE_OPTS=-Dorg.gradle.project.performance.assertions.enabled=true`가 daemon까지 전달되는지 — 실행하지 않았다.
|
||||
- `configuration-cache` 잡이 `performanceCheck`를 저장 가능성 검사에 넣지 않은 것 — 영향을 측정하지 않았다.
|
||||
- `exclude.xml` CT group 1이 `@Configuration(proxyBeanMethods = false)` 클래스까지 덮는다. 이유("CGLIB 서브클래스")는 그 클래스에는 맞지 않는다. 다만 finalizer 공격 위험이 사실상 없어 결함으로 세지 않았다.
|
||||
- `UNSAFE_HASH_EQUALS`의 `PostgreSqlIdempotencyStore` 제외 — 멱등 키가 주체별로 범위가 나뉘는지에 따라 판단이 달라진다. 02·04 영역 소관이라 미뤘다.
|
||||
- `JdbcOutboxRepository.transition`이 `failureCode == null`이고 `now != null`이면 timestamp를 `last_failure_code` 자리에 묶는다 — SQL 주입 제외 표본을 보다 발견했다. messaging 영역(05) 소관이고 이번 diff가 아니다.
|
||||
- sample 관리 포트에서 데모 체인이 GET을 모두 허용해 health 상세가 Basic 인증 시 보인다 — 공개 데모 계정이라 의미 있는 노출이 아니다.
|
||||
- `.env.example`이 `APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=true` 등 기본값을 바꾼 것 — 05 영역 결정(15절)이다.
|
||||
|
||||
## 28개 관점 — 바뀐 관점만
|
||||
|
||||
원래 판정은 07 영역(`07-…md` 8절), 08 영역(`08-…md` 10절), 09 영역(README 11절)의 값이다.
|
||||
|
||||
| 관점 | 영역 | 이전 → 지금 | 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| 2 구조적 성숙도 | 07 | P → O | durable operation·권한 매핑·볼륨이 모듈로 이동. 남은 것은 build-logic 한 곳(RR-06-10) |
|
||||
| 5 위험 가시성 | 07 | X → P | 트레이스·인가·검사 순서가 고쳐지고 테스트로 보인다. rule static 제약은 숨어 있다(RR-06-01) |
|
||||
| 5 위험 가시성 | 08 | P → P | 단계 검사가 생겼지만 optional build와 `-x`는 안 보인다(RR-06-03·04) |
|
||||
| 5 위험 가시성 | 09 | X → P | 동시 중복·대표 쓰기·N+1이 실서버 테스트로 보인다. sample SpotBugs는 꺼져 있다(RR-06-05) |
|
||||
| 6 실패 성숙도 | 08 | P → O | main-check `--continue`, 이미지 실패는 실패로 남는다 |
|
||||
| 7 운영 성숙도 | 07 | P → O | span 수출, 종료 예산 합계 검사, 관리 포트 loopback. runbook drift는 Minor(RR-06-08) |
|
||||
| 10 테스트 성숙도 | 09 | X → P | 실서버·실 PG 테스트가 대표 위험을 잡는다. Poster 포트는 공유 계약이 없다(RR-06-12) |
|
||||
| 10 테스트 성숙도 | 08 | P → P | lane이 실제로 돈다. 캐시가 강화된 정책을 건너뛴다(RR-06-02) |
|
||||
| 11 데이터 성숙도 | 09 | X → O | 유일 인덱스 + 기존 중복 시 마이그레이션 실패 |
|
||||
| 12 동시성 성숙도 | 09 | X → O | 16 동시 생성에서 1행(동시성 integration 테스트) |
|
||||
| 13 확장성 | 08 | P → P | main build는 lane 추가가 workflow를 몰라도 된다. optional build는 아직 이름 나열 |
|
||||
| 14 성능 성숙도 | 08 | P → O | hermetic lane 캐시, 중복 systemTest 제거. `ci` 434→51초(캐시 있는 측정) |
|
||||
| 16 의존성 성숙도 | 08 | P → O | 테스트 이미지 한 파일·digest, mirror prefix, 효과 없는 netty override 삭제 |
|
||||
| 18 배포 성숙도 | 07 | P → O | `Dockerfile.sample` COPY 동일성 검사, 기본 이미지에서 VOLUME 제거, fileserver overlay |
|
||||
| 19 설정 성숙도 | 07 | P → P | bootstrap strict 바인딩·로그 단일 출처는 됨. sample yml 죽은 키, lane 키 미검사(RR-06-06·07) |
|
||||
| 20 개발자 경험 | 08 | P → O | 문서만 바꾼 커밋이 app-bootstrap `test`를 무효화하지 않는다 |
|
||||
| 21 Guardrail 성숙도 | 07 | P → P | `@RequiresPermission` 실행본 검증은 생겼고, rule 선언 제약은 장치가 없다(RR-06-01) |
|
||||
| 21 Guardrail 성숙도 | 08 | P → P | lane 도달성 M3(main build), optional build M0 |
|
||||
| 26 Ownership | 07 | P → O | 권한 매핑·볼륨을 capability가 소유 |
|
||||
| 27 삭제 가능성 | 07 | P → O | capability 한 줄을 지우면 bootstrap·compose·이미지에 흔적이 없다(주석 제외) |
|
||||
| 28 회복 가능성 | 08 | P → O | 이미지 공급원이 사라지면 mirror prefix로 돌릴 수 있고, 다른 결과를 가리지 않는다 |
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? With fixes.**
|
||||
|
||||
원래 07·08·09 발견은 대부분 코드와 실제 실행 테스트로 닫혔고 회귀는 없다. 다만 07-02·08-02 수정이 새 숨은 위험 두 개(rule 조기 생성, 캐시가 강화된 lane 정책을 건너뜀)를 만들었고, 08-01의 재발 방지 검사가 optional build를 덮지 못하므로 RR-06-01~03은 merge 전에 고치거나 결정 기록으로 받아들이는 것이 맞다.
|
||||
@@ -0,0 +1,214 @@
|
||||
# 07 보안 재리뷰 (2026-11-03)
|
||||
|
||||
## 범위
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
브랜치 전체 `01a8a2a70..5786126c` 중 보안에 닿는 변경만 봤다. 영역이 여러 leaf에 걸쳐 있어서 파일 단위로 골랐다.
|
||||
|
||||
- 인증·인가: `src/adapter/inbound/web/src/main/java/**/{auth,authz,settings,mvc/autoconfigure}/`, `src/composition/service-runtime/**/authorization/`, `src/application-core/**/security/`, `src/app-bootstrap/**/{security,runtime}/`, `src/app-bootstrap/src/main/resources/{config/security.yml,application*.yml}`, `src/sample-portfolio/**/bootstrap/security/`, `src/sample-portfolio/**/{controller,application/worklog}/`, `src/adapter/outbound/support/**/startup/`
|
||||
- 파일 서버 소유자·대상: `src/application-fileserver/**/{lifecycle,upload}/`, `src/application-fileserver/src/testFixtures/**/FakeFileAccessPolicy.java`, `src/adapter/outbound/fileserver/**/RoleBasedFileAccessPolicy.java`, `src/adapter/inbound/web-fileserver/src/main/`
|
||||
- 입력 상한: `src/adapter/inbound/graphql/**/cost/`, `src/adapter/inbound/web/**/mvc/filter/`, `src/adapter/inbound/websocket/**/stomp/`, `src/adapter/inbound/grpc/**/GrpcServer*.java`, `src/grpc/grpc-runtime/**/idempotency/`
|
||||
- 헤더: `CorsExposedHeaders.java`, `SecurityConfig.java`, `WebMvcRequestIdFilter.java`, `IdempotencyKeyHeader.java`, `InvalidIdempotencyKeyException.java`
|
||||
- 비밀값·compose: `SecretSource*.java`, `src/application-core/**/secret/`, `docker-compose*.yml`, `infra/redis-sdk/acl/`, `infra/fileserver/compose/`, `src/.env.example`, `src/config/runtime/compose-profile-contracts.json`
|
||||
- SES 콜백: `src/adapter/outbound/notification/**/{callback,provider/ses,autoconfigure/NotificationCallbackProviderConfig.java,security/AesGcmCallbackPayloadProtection.java}`, `src/adapter/inbound/web-notification/**/callback/`, `src/composition/notification-platform/**/ProviderCallbackIngressBridge.java`
|
||||
- 의존성·공급망: 모든 `gradle.lockfile`, `src/gradle/libs.versions.toml`, `JavaConventionsPlugin.java`, `src/adapter/outbound/objectstorage/src/test/**/MinioQualificationImage.java`, `minio-provider-evidence.json`
|
||||
- 정적 분석: `src/config/spotbugs/exclude.xml`, `QualityConventionsPlugin.java`
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
|---|---|---|
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → severity별 Issues → Declined to judge → Assessment), 읽기 전용, 하위 에이전트 금지 | 이 문서의 형식. 칭찬은 읽은 줄에만 붙였다 |
|
||||
| `security-and-hardening` | 신뢰 경계마다 STRIDE, Always/Never 목록(비밀값 커밋 금지, CORS `*` 금지, 입력 상한), 공급망 4단계(lockfile·새 의존성·출처) | 아래 경계 표, CORS 노출 목록, 비밀값 fixture, lockfile 좌표 비교, MinIO 이미지 출처 |
|
||||
| `security-review` | 발견마다 공격 경로와 신뢰도, 거짓 양성 걸러내기(DoS·하드닝 부족·테스트 전용 파일 제외) | 하위 작업 분할 지시는 brief의 "하위 에이전트 금지"를 따라 쓰지 않고, 걸러내기 기준만 직접 적용했다. 그래서 High로 올릴 만한 직접 악용 경로는 없었고, 남은 발견은 개발자·운영자 행동이 조건인 Medium·Low다 |
|
||||
|
||||
신뢰 경계와 STRIDE로 본 것:
|
||||
|
||||
| 경계 | 들어오는 것 | 본 위협 |
|
||||
|---|---|---|
|
||||
| HTTP API (JWT·세션) | bearer token, 헤더, 본문 | S(다른 client 토큰), E(role 범위, 권한 검사 누락), D(본문 상한) |
|
||||
| 샘플 HTTP Basic | 공개 데모 계정 | S·E(운영 복제) |
|
||||
| SES/SNS 콜백 | 서명된 SNS envelope | S(인증서 URL), T, R(감사), replay |
|
||||
| WebSocket·gRPC·GraphQL | 프레임, 메시지, 쿼리 | D(크기·연결·복잡도) |
|
||||
| 설정·env·compose | env 값, ACL 파일 | T·I(fixture 비밀번호, 오타 키) |
|
||||
| 공급망 | Maven 좌표, 컨테이너 이미지 | T(새 라이브러리, 커뮤니티 이미지) |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
- `git diff --stat` / `git diff 01a8a2a70..5786126c -- <위 pathspec>`: 읽기.
|
||||
- lockfile 좌표 비교(base·head의 모든 `gradle.lockfile`을 합쳐 `group:artifact:version` 집합 차이): 새 좌표 4개, 지운 좌표 0개. 넷 다 1차 공급자 것이다(`spring-boot-micrometer-tracing`, `spring-boot-micrometer-tracing-opentelemetry`, `spring-boot-opentelemetry` 4.0.8, `opentelemetry-exporter-sender-jdk` 1.55.0). `io.netty:*`는 base와 같은 4.2.17.Final이다.
|
||||
- 별도 worktree(`scratchpad/rr-07`, 5786126c)에 probe 테스트 2개를 넣고 실행:
|
||||
`flock .../heavy.lock ./gradlew :composition:service-runtime:test --tests '*Rr07SystemInvokedProbeTest' :sample-portfolio:test --tests '*Rr07DemoGuardProbeTest' --console=plain -i`
|
||||
→ `BUILD SUCCESSFUL in 16s`(실행 직전 load 27.65). 출력은 RR-07-01, RR-07-02 증거에 적었다. worktree는 `git worktree remove --force`로 지웠다.
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 실제 IdP(Keycloak) 토큰으로 audience·role 범위를 확인하지 않았다. 단위 테스트와 코드만 읽었다.
|
||||
- 게이트(ci·mainCheck·integrationCheck)는 다시 돌리지 않았다. README 16.2 결과를 그대로 둔다.
|
||||
- compose lane(`local-redis`, `all-adapters`, notification)을 직접 띄우지 않았다.
|
||||
- 의존성 CVE 데이터베이스 대조(OSV·dependency-check)는 하지 않았다. 새 좌표가 1차 공급자 것뿐이라는 것까지만 확인했다.
|
||||
- 보안과 관계없는 나머지 diff(성능·메시징 재시도·JPA 매핑 등)는 보지 않았다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **JWT audience가 닫힌 기본값이 됐다.** `SecuritySettings.java:44`가 풀리지 않은 `${...}` 자리표시자를 "값 없음"으로 읽는다. `SecuritySettings.java:62`가 JWT 모드에서 빈 audience를 기동 거부한다. `JwtDecoderConfig.java:77-88`도 빈 목록이면 예외를 던져 두 번째 방어선이 된다. 목록 중 하나만 맞으면 통과한다(`JwtDecoderConfig.java:106-116`).
|
||||
- **role 범위가 자기 client로 좁혀졌다.** `JwtToAuthenticatedPrincipalConverter.java:92-100`은 audience로 설정한 client의 `resource_access`만 읽는다. "다른 client role은 권한이 되지 않는다" 테스트가 있다(`JwtToAuthenticatedPrincipalConverterTest.java:81-82`).
|
||||
- **`app.security`가 엄격 바인딩이다.** 오타 키와 아무 설정도 아닌 `APP_SECURITY_*` env가 기동을 막는다(`SecuritySettingsTest.java:59-79`). 같은 prefix를 느슨하게 두 번 바인딩하던 `AuthenticationModeSettings`가 지워졌다.
|
||||
- **메서드 보안이 인증 체인과 분리됐다.** `WebMethodSecurityAutoConfiguration`이 따로 있어서 JWT 체인을 빼도 `@RequiresPermission`이 남는다. web 어댑터가 없는 조립은 `PermissionEnforcementGuard.java:41-61`이 기동 실패로 막는다.
|
||||
- **샘플 권한이 실서버로 검증된다.** `SampleWorkLogAuthorizationSystemTest`가 실제 PostgreSQL과 RANDOM_PORT 서버로 익명 401, 권한 없는 삭제 403, 권한 있는 삭제 204, 남의 기록 수정 403을 본다. mock이 아니다.
|
||||
- **prod 기동 규칙이 DB 연결 전에 돈다.** `StartupRuleRunner`가 BeanFactoryPostProcessor가 됐다. `SecretSourceValidator`, TLS `verify-full`, H2 금지, 데모 계정 거부가 datasource·Flyway보다 먼저 돈다. 기여 bean은 모두 `static`이다(`JpaStartupAutoConfiguration.java:163`, `RedisCapabilityConfig.java:91`).
|
||||
- **SNS 인증서 실패가 "거절"이 아니라 "다시 보내라"다.** `NotificationCallbackMvcController.java:124`가 503과 `Retry-After`를 준다. replay 창은 근거가 있는 상수다(`SesCallbackAdapter.java:49`, SNS HTTP 재시도 상한 3600초). 중복은 `(provider_profile_id, event_fingerprint)` 유일 인덱스가 막는다.
|
||||
- **전송 상한이 코드에 드러났다.** gRPC는 메시지 1 MiB·메타데이터 8 KiB·연결당 동시 호출·고정 크기 executor·기본 deadline을 builder에 건다(`GrpcServerRunner.java:99-110`). WebSocket은 메시지·버퍼·첫 메시지 시간·노드 연결 수(`WebSocketConfig.java:72-78`)와 세션당 구독 1개를 건다. session id가 없으면 구독을 받지 않는다(`WebSocketInboundAuthorizationInterceptor.java:92-96`).
|
||||
- **GraphQL 점수가 우회 경로를 막는다.** 변수 기본값, 스키마 인자 기본값, 크기 없는 list, 중첩 list 곱셈을 모두 계산하고, 범위 밖 정수는 최대값으로 읽어 거부한다(`GraphQlDocumentComplexityScorer.java:262-327`).
|
||||
- **헤더 처리가 한 규칙이다.** correlation ID는 요청 ID와 같은 문법이고 틀리면 고치지 않고 새로 만든다(`WebMvcRequestIdFilter.java:189`). `Idempotency-Key`는 응답에 되돌려 쓰지 않는다(`InvalidIdempotencyKeyException.java`). CORS 노출 목록은 코드가 소유하고 `*`를 거부한다(`CorsExposedHeaders.java:27-47`).
|
||||
- **compose 관리 포트가 loopback이다.** `docker-compose.yml:61`, `docker-compose.dev.yml`. compose Redis는 `default` 사용자를 끄고 ACL 계정으로만 붙는다.
|
||||
- **SpotBugs MEDIUM의 보안 제외가 위치 단위다.** 표본으로 확인했다. `JdbcOutboxRepository`의 SET 절은 모두 문자열 리터럴이고 값은 바인딩이다. `IdempotencyCapabilityGuard`의 SQL은 상수다. `GraphQlRequestBodyLimitFilter.reject`는 고정 본문을 쓴다. `SnsSignatureVerifier`의 호스트 정규식은 선형이다. `ContentType`은 정규식 전에 160자로 자른다.
|
||||
- **MinIO 이미지가 digest로만 바뀐다.** 운영자 override도 같은 digest가 아니면 거부한다(`MinioQualificationImage.java:73`). compose 기본값과 evidence가 다르면 `ComposeMinioImageMatchesEvidenceTest`가 실패한다. 기각한 후보와 이유가 evidence 파일에 남아 있다.
|
||||
- **파일 서버 소유자 회귀가 이제 잡힌다.** fake 정책이 소유자 규칙을 지키므로 05-08 변이(descriptor 제거)가 use case 테스트에서 죽는다. copy·move 대상 namespace는 허용 목록이다(`CopyFileApplicationUseCase.java:96`, `MoveFileApplicationUseCase.java:53`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
|---|---|---|
|
||||
| 02-03 | 닫힘 | `SecuritySettings.java:44,62`, `JwtDecoderConfig.java:77-88`, `JwtToAuthenticatedPrincipalConverter.java:92-100`. 완료 기준 2개(빈 audience 기동 실패, 다른 client role 무시) 모두 테스트가 있다 |
|
||||
| 07-05 | 닫힘 | 02-03과 같은 코드. 결정 A대로 prod만이 아니라 JWT 모드 전체에서 거부한다 |
|
||||
| 07-03 | 닫힘 | `SamplePortfolioApplication`이 JWT 체인만 빼고 `WebMethodSecurityAutoConfiguration`은 남긴다. 실서버 테스트가 403·204를 본다. 결정이 만든 새 위험은 RR-07-02 |
|
||||
| 09-03 | 닫힘 | 익명 생성이 500이 아니라 401(`SampleWorkLogAuthorizationSystemTest`) |
|
||||
| 01-06 | 닫힘, 새 결함 1 | 완료 기준 2개(web 없는 조립 기동 실패, relay의 장식용 권한 선언 제거)는 채웠다. 대신 들어온 `@SystemInvoked` 면제가 코드로 묶여 있지 않다 → RR-07-01 |
|
||||
| 05-08 | 닫힘 | `FakeFileAccessPolicy.java:45-50`, `DownloadUseCasesTest.java:91,110`, `FileLifecycleUseCasesTest.java:340`. 규칙이 두 벌이다 → RR-07-06 |
|
||||
| 05-12 | 닫힘 | `TusController.java:185`가 status 재조회(`file:read`) 없이 append 결과로 판단한다. 자동 finalize도 `file:upload`와 소유자 검사를 거친다 |
|
||||
| 05-07 (대상·쿼터) | 결정으로 닫힘 | `TargetNamespacePolicy`(기본은 업로드 기본 namespace 하나). 동시 예약이 상한을 넘을 수 있는 것은 15절 결정 |
|
||||
| 05-20 | 닫힘 | 창 1시간(`SesCallbackAdapter.java:49`), 인증서 실패 503(`ProviderCallbackIngressBridge.java:82`). 분류·중복 방지에 작은 틈 → RR-07-03, RR-07-07 |
|
||||
| 05-09 | 결정으로 닫힘 | `pgsty/minio` digest 고정, 참조 한 곳(evidence), override digest 검사 |
|
||||
| 03-01 | 닫힘 | `GraphQlDocumentComplexityScorer.java:262-295`, `PageVariables`(:385-) |
|
||||
| 03-06 | 닫힘 | `StompConnectionLimit`, `WebSocketInboundAuthorizationInterceptor.java:55`, `WebSocketConfig.java:72-78` |
|
||||
| 03-09 | 닫힘 | `GrpcServerRunner.java:99-110`, `GrpcServerSettings` 기본값 |
|
||||
| 02-05 | 닫힘 | `SecurityConfig.corsConfigurationSource`가 `CorsExposedHeaders` 합집합을 노출, fileserver가 tus 헤더를 기여 |
|
||||
| 02-09 | 결정으로 닫힘 | JSON 두 갈래를 테스트가 고정(`JsonBodyLimitFilterTest.java:47-77`). JSON 아닌 본문은 엔드포인트 몫(15절) |
|
||||
| 02-11 | 닫힘 | `WebMvcRequestIdFilter.java:189` |
|
||||
| 02-12 | 닫힘 | `IdempotencyKeyHeader`, 유일한 운영 KEYED 컨트롤러가 사용(`PosterImagePublicationController.java:64`) |
|
||||
| 07-10 (보안 prefix) | 닫힘 | `SecuritySettings.bind`, `SecretSourceSettings.bind`. 다른 prefix는 이 영역 밖이라 보지 않았다 |
|
||||
| 07-13 | 닫힘 | `docker-compose.yml:61`, `docker-compose.dev.yml` |
|
||||
| 08-07 | 닫힘 | `QualityConventionsPlugin`에 MEDIUM과 측정 수, 제외마다 이유. 이유가 맞지 않게 된 기존 제외 1건 → RR-07-05 |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-07-01 `@SystemInvoked`의 권한 검사 면제 조건이 Javadoc에만 있다
|
||||
|
||||
- 위치: `src/application-core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java:19-20`, `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:558`, `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java:41-61`
|
||||
- 무엇이 틀렸나: ArchUnit D4는 쓰기 유스케이스에 `@RequiresPermission`을 요구한다. 클래스에 `@SystemInvoked`가 붙으면 이 검사를 건너뛴다(:558). 면제의 전제는 "transport가 닿는 Spring 빈이 되면 안 된다"인데, 이 문장은 Javadoc(:19-20)과 `application-core/CLAUDE.md`에만 있다. 기동 검사(`PermissionEnforcementGuard`)는 `@RequiresPermission`이 붙은 빈만 본다. `@SystemInvoked` 빈은 보지 않는다.
|
||||
- 왜 중요한가: D4가 실패하면 개발자(또는 에이전트)가 가장 쉽게 고르는 해법이 `@SystemInvoked(reason = "...")` 한 줄이다. 그 유스케이스를 컨트롤러가 부르면 모든 게이트가 통과한다.
|
||||
- 누가: 그 서비스의 인증된 사용자 누구나(role 무관).
|
||||
- 무엇으로: `@SystemInvoked`가 붙은 채 빈으로 등록된 쓰기 엔드포인트.
|
||||
- 무엇을 얻나: role→permission 검사 없이 쓰기를 실행한다(권한 상승). 사용자 원칙 "개발자가 따로 기억해야 하는 숨은 위험은 결함"에 해당한다.
|
||||
- 고치는 법: `PermissionEnforcementGuard`가 이미 모든 빈 정의를 훑는다. 같은 루프에서 클래스에 `@SystemInvoked`가 있으면 기동을 실패시킨다. 메시지는 "system-invoked use case must be constructed by its composition, not registered as a bean". 아래 probe를 RED 테스트로 쓴다. 보조로 ArchUnit "inbound adapter는 `@SystemInvoked` 클래스에 의존하지 않는다"를 둘 수 있다.
|
||||
- 가이드 심각도·우선순위: Medium · P2. 개발자 실수가 조건이라 High가 아니다.
|
||||
- 증거: E3. worktree에서 `@SystemInvoked` 클래스를 빈으로 등록하고 `PermissionEnforcementConfig`와 함께 띄웠다. 출력 `RR07 systemInvokedBean failed=false`(기동 성공).
|
||||
|
||||
#### RR-07-02 데모 계정 거부가 정확히 `prod`일 때만 걸리고, 샘플에는 프로필 검증기가 없다
|
||||
|
||||
- 위치: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/security/SampleDemoAccountsProductionGuard.java:44-46`, `src/sample-portfolio/src/main/resources/application.yml:30`(`${SPRING_PROFILES_ACTIVE:local}`), `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/RuntimeEnvironmentProfileValidator.java:84-86`, `src/config/architecture/modules.json:387-390`, `src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/bootstrap/security/SampleDemoAccountsProductionGuardTest.java:70`
|
||||
- 무엇이 틀렸나: 15절 결정의 이유는 "샘플을 복제해 운영에 올리는 위험을 코드로 막는다"이다. 구현은 금지 목록 방식이다. `RuntimeEnvironment.fromProfile`은 정확히 `prod`만 production으로 읽는다. 앱의 "환경 프로필 정확히 하나" 검사는 main class가 `CaSkeletonApplication`일 때만 돈다(:84-86). 샘플은 app-bootstrap에 의존하지 않아서 이 검사가 아예 없다(modules.json). 그래서 프로필 없음(yml 기본 `local`로 바뀜), `production`, `staging`으로 띄우면 데모 계정이 열린 채 기동한다. `Dockerfile.sample`도 프로필을 정하지 않는다. 테스트가 "프로필 없음이면 허용"을 고정해 둔다(:70).
|
||||
- 왜 중요한가:
|
||||
- 누가: 그 배포에 네트워크로 닿는 누구나.
|
||||
- 무엇으로: README에 공개된 `demo-admin` / `demo-admin` HTTP Basic.
|
||||
- 무엇을 얻나: admin role(`worklog:close` 삭제 등). 샘플을 베낀 서비스라면 그 서비스가 `admin`에 매핑한 권한 전부.
|
||||
결정 자체(prod 거부)는 그대로 지켰다. 문제는 결정이 막으려던 경로(복제 후 운영 배포)가 `prod`라는 이름 하나에만 걸려 있다는 것이다.
|
||||
- 고치는 법: 결정을 넓히는 방향이라 뒤집지 않는다.
|
||||
1. 거부 조건을 허용 목록으로 바꾼다. `local`·`dev`·`test` 중 정확히 하나가 명시적으로 켜져 있을 때만 데모 계정을 허용한다.
|
||||
2. 샘플 yml의 `SPRING_PROFILES_ACTIVE:local` 기본값을 지운다. 기본값이 남아 있으면 1번만으로는 "프로필 없음"이 `local`로 바뀌어 통과한다. 대안은 데모 계정을 `app.sample.demo-accounts.enabled` 같은 명시 키로 켜고 이미지 기본값을 false로 두는 것이다.
|
||||
3. `theDemoAccountsAreAllowedWithNoProfileAtAll`을 반대 단언으로 바꾸고 `production`·`staging` 케이스를 더한다.
|
||||
- 가이드 심각도·우선순위: Medium · P2.
|
||||
- 증거: E3. worktree probe에서 `violations()` 결과: `production` 0건, `staging` 0건, `prd` 0건, `PROD ` 1건.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-07-03 SNS 인증서 URL의 HTTP 4xx를 "검증 불가(503)"로 분류해서 위조 콜백이 거절도 감사도 되지 않는다
|
||||
|
||||
- 위치: `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationCallbackProviderConfig.java:74-77`, `src/composition/notification-platform/src/main/java/dev/caskeleton/composition/notification/ProviderCallbackIngressBridge.java:82-92`
|
||||
- 무엇이 틀렸나: 진짜 SNS 메시지의 `SigningCertURL`은 존재하는 인증서를 가리킨다. 호스트·경로 검사를 통과한 URL이 404·403을 주면 그 envelope은 위조다. 지금은 2xx가 아닌 모든 응답이 IOException·인터럽트와 같은 "일시 장애"로 묶인다. 결과는 503과 `Retry-After`이고, `securityAudit.callbackSignatureRejected`에 남지 않는다(WARNING 로그만). 주석은 "Not a security event"라고 단정한다.
|
||||
- 왜 중요한가:
|
||||
- 누가: 콜백 URL과 구독 topic ARN을 아는 외부인.
|
||||
- 무엇으로: 허용 topic, 현재 `Timestamp`, `https://sns.<region>.amazonaws.com/SimpleNotificationService-<없는 id>.pem`을 넣은 envelope.
|
||||
- 무엇을 얻나: 이벤트는 기록되지 않아 데이터 변조는 없다. 얻는 것은 서명 위조 시도가 감사 기록에서 빠지는 것(R)이다. 이전(500)에도 감사되지 않아서 회귀는 아니다.
|
||||
- 고치는 법: 4xx는 `IllegalArgumentException`("SNS 서명 인증서가 아님") 쪽으로 보내 invalid + 감사로 처리한다. IOException·5xx·인터럽트만 `CallbackVerificationUnavailableException`으로 둔다.
|
||||
- 가이드 심각도·우선순위: Low · P3.
|
||||
- 증거: E1(코드 읽기).
|
||||
|
||||
#### RR-07-04 Redis ACL fixture 파일이 "배포가 싣는 파일"로 소개되는데 공개 비밀번호의 `+@all` 계정을 담고 있다
|
||||
|
||||
- 위치: `infra/redis-sdk/acl/all-accounts.acl:8`(`ca-skeleton-cluster-bootstrap on >fixture-bootstrap ~* &* +@all`), `infra/redis-sdk/acl/README.md:23`, `docker-compose.infra.yml:140`, `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java:33`
|
||||
- 무엇이 틀렸나: README 표(:23)는 이 파일을 "the four accounts concatenated … this is what a deployment loads"라고 쓴다. 실제 파일은 8줄이고 superuser 1개가 들어 있다. 이번 브랜치가 compose 주석(:140)에 "with the accounts a deployment loads"를 새로 썼다. README 11-13행은 반대로 "배포는 파일 전체를 바꾼다"고 쓴다. prod 비밀 검사는 `__LOCAL_DEV_` 접두만 거부하고 `fixture-*` 값은 모른다. 이번 브랜치는 lane에서 앱을 fixture 비밀번호와 namespace `prod`로 붙이기 시작했다.
|
||||
- 왜 중요한가:
|
||||
- 누가: 이 파일을 그대로 운영 Redis에 올린 배포에서, Redis에 닿는 누구나(같은 클러스터의 다른 pod 등).
|
||||
- 무엇으로: `AUTH ca-skeleton-cluster-bootstrap fixture-bootstrap`.
|
||||
- 무엇을 얻나: 모든 키 읽기·삭제, `CONFIG`·`MODULE`을 포함한 서버 장악.
|
||||
운영자가 fixture를 복사해야 성립하므로 Low다.
|
||||
- 고치는 법: README 표와 compose 주석을 "lane이 싣는 fixture. 배포는 같은 모양의 파일을 비밀 저장소 비밀번호로 새로 만든다"로 고친다. 계정 수를 실제와 맞춘다. prod `SecretSourceValidator`가 `fixture-` 접두 값도 sentinel처럼 거부한다.
|
||||
- 가이드 심각도·우선순위: Low · P3.
|
||||
- 증거: E1.
|
||||
|
||||
#### RR-07-05 CSRF 제외 규칙의 이유가 새 샘플 보안 설정에는 맞지 않는다
|
||||
|
||||
- 위치: `src/config/spotbugs/exclude.xml:19-27`, `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/security/SampleDemoSecurityConfig.java:71-73`
|
||||
- 무엇이 틀렸나: `SPRING_CSRF_PROTECTION_DISABLED`를 `~.*SecurityConfig` 패턴으로 제외한다. 이유는 "stateless JWT bearer, ambient cookie auth 없음"이다. 새 `SampleDemoSecurityConfig`가 이름 패턴에 걸린다. 이 클래스는 CSRF를 끄고 HTTP Basic을 쓴다. HTTP Basic은 브라우저가 한 번 받은 자격을 자동으로 붙이는 수단이라 이유가 성립하지 않는다. 08-07이 정한 규칙("A pattern-wide Match needs a reason that holds for every class it can ever match", `QualityConventionsPlugin`)과 어긋난다.
|
||||
- 왜 중요한가: 지금 실제 영향은 없다. 401이 `WWW-Authenticate: Bearer`라 브라우저가 Basic 자격을 저장하지 않고, 계정도 공개다. 다만 샘플을 베낀 서비스가 실제 Basic 계정을 넣으면 CSRF 경고가 조용히 사라진다.
|
||||
- 고치는 법: 매치를 정확한 클래스 이름으로 좁힌다. 샘플용 Match를 따로 두고 "공개 계정이라 CSRF가 지킬 자격이 없다"는 이유를 단다.
|
||||
- 가이드 심각도·우선순위: Low · P3.
|
||||
- 증거: E1.
|
||||
|
||||
#### RR-07-06 파일 소유자 규칙이 fake와 실제 정책에 두 벌 있고 공유 계약이 없다
|
||||
|
||||
- 위치: `src/application-fileserver/src/testFixtures/java/dev/caskeleton/application/fileserver/testkit/FakeFileAccessPolicy.java:45-50`, `src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/security/RoleBasedFileAccessPolicy.java:74-91`
|
||||
- 무엇이 틀렸나: 05-08 변이를 잡는 장치는 fake가 실제 정책의 소유자 규칙을 베낀 것이다. 둘을 묶는 `FileAccessPolicyPort` 계약 테스트가 없다(`docs/testing/TESTING_STRATEGY.md` 9절에도 없음). 비교 방식도 다르다. fake는 `owner == subject.asOwner()` 하나로 비교하고, 실제 정책은 principalId와 tenant를 따로 비교한다.
|
||||
- 왜 중요한가: 실제 정책이 바뀌면(예: 관리자 우회 추가) fake는 그대로 남는다. use case 테스트는 운영과 다른 소유자 규칙을 검증하게 된다. 다른 사용자 파일 접근(IDOR) 회귀를 막는 장치가 갈라진 복사본에 기대고 있다.
|
||||
- 고치는 법: application-fileserver testFixtures에 `FileAccessPolicyPortContract`를 둔다. 케이스는 남의 파일 거부, 다른 tenant 거부, 소유자 없는 파일 거부, descriptor 없음은 역할만 확인. fake와 `RoleBasedFileAccessPolicyTest`가 상속한다(AGENTS.md의 공유 계약 규칙).
|
||||
- 가이드 심각도·우선순위: Low · P3.
|
||||
- 증거: E1.
|
||||
|
||||
#### RR-07-07 replay 창 1시간의 중복 방지가 fingerprint 키 회전에 깨지고, Javadoc은 다른 유일 키를 말한다
|
||||
|
||||
- 위치: `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/ses/SesCallbackAdapter.java:36-40`, `SesEventNormalizer.java:78`, `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/security/AesGcmCallbackPayloadProtection.java:130`, `src/adapter/outbound/persistence-notification/src/main/resources/db/migration/jpa/notification-platform/V1__notification_platform_core.sql:174-179`
|
||||
- 무엇이 틀렸나: Javadoc은 "ledger가 `(provider_profile_id, provider_event_id)`로 유일하다"고 쓴다. SES 이벤트는 `provider_event_id`가 항상 비어 있다(:78). 실제로 막는 것은 `(provider_profile_id, event_fingerprint)` 유일 인덱스다. fingerprint는 현재 활성 HMAC 키로 만든다(:130). 키를 회전하면 같은 콜백이 다른 fingerprint가 된다.
|
||||
- 왜 중요한가: 창이 5분에서 1시간으로 12배 늘었다. 회전 전에 받은 콜백을 SNS가(또는 그 메시지를 가진 사람이) 회전 뒤 다시 보내면 두 번 기록된다. 서명이 필요해서 위조는 아니다. 같은 bounce·complaint·delivery가 두 행이 된다.
|
||||
- 고치는 법: Javadoc을 실제 인덱스로 고친다. SES 콜백은 서명 문자열에 포함된 SNS `MessageId`를 `provider_event_id`로 넣는다. 그러면 키와 무관한 유일성이 생긴다.
|
||||
- 가이드 심각도·우선순위: Low · P3.
|
||||
- 증거: E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- Keycloak은 사용자가 어떤 client의 role을 가지면 그 client를 `aud`에 넣는다. 그래서 다른 client(`azp`)가 받은 토큰도 이 서비스 audience를 담을 수 있다. `azp` 검사는 02-03 결정 범위 밖이고 IdP 설정에 달려 있어 판단을 미룬다.
|
||||
- `realm_access.roles`와 최상위 `roles` claim은 client 구분 없이 읽는다. realm role은 15절 결정으로 유지됐다. 최상위 `roles`는 IdP mapper 설정에 달려 있다.
|
||||
- `PermissionEnforcementGuard`는 pointcut이 맞는 아무 advisor나 "강제한다"로 인정한다. Javadoc이 이 한계를 적었고, 지금 템플릿에는 `@RequiresPermission` 빈에 맞는 다른 advisor bean이 없다.
|
||||
- 들어온 `traceparent`가 trace id와 sampled 플래그를 정한다(Boot 기본 ParentBased 샘플러). 기존 설계이고, 영향이 비용·로그 상관 쪽이라 보안 결함으로 보지 않았다.
|
||||
- `pgsty/minio`는 커뮤니티 fork이고 서명 검증(cosign 등)이 없다. digest 고정과 테스트·로컬 전용이라는 점, 소유자 결정(15절)을 보고 판단을 미룬다.
|
||||
- 의존성 CVE 대조는 도구를 돌리지 않아 판단하지 않았다.
|
||||
- fileserver 저장소 초기화 컨테이너가 root로 `chown`만 한다(`network_mode: none`, `read_only`). capability를 더 줄일 수 있지만 하드닝 제안이라 발견으로 올리지 않았다.
|
||||
- 파일 쿼터 동시 예약이 상한을 넘을 수 있는 것은 15절 결정이다.
|
||||
- HTTP client의 `PLAINTEXT_FALLBACK_FORBIDDEN`이 비운영에서 풀린 것은 설정 문서와 `ClientProfileValidator`의 prod 검사(:246)와 일치해서 결함으로 보지 않았다.
|
||||
|
||||
## 28개 관점 — 바뀐 관점만
|
||||
|
||||
README 11절 종합 판정 대비, 보안 범위 안에서 바뀐 것만 적는다.
|
||||
|
||||
| 관점 | 전 | 후 | 이유 |
|
||||
|---|---|---|---|
|
||||
| 5 위험 가시성 | X | P | 빈 audience가 기동 거부로 드러난다. `@SystemInvoked` 조건(RR-07-01)과 데모 거부 범위(RR-07-02)는 아직 코드 밖에 있다 |
|
||||
| 10 테스트 성숙도 | X | P | 05-08 변이가 죽고, 샘플 권한을 실서버로 본다. 소유자 규칙의 공유 계약은 없다(RR-07-06) |
|
||||
| 13 확장성 | X | P | WebSocket 연결·구독, gRPC 동시 호출·메시지 크기 상한이 생겼다. principal별 상한은 서비스 몫으로 문서화됐다 |
|
||||
| 15 보안 성숙도 | X | P | 02-03이 닫혔다. Medium 2건(RR-07-01, RR-07-02)이 남았다 |
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? With fixes**
|
||||
|
||||
Critical·High는 없고 보안 영역의 원래 발견은 모두 닫히거나 결정으로 닫혔다. 남은 Important 2건은 권한 검사를 비켜 가는 경로(`@SystemInvoked` 빈, `prod`가 아닌 이름의 데모 배포)를 코드가 막지 못하는 것이고, 각각 기동 검사 한 군데를 고치면 된다.
|
||||
@@ -0,0 +1,405 @@
|
||||
# 재리뷰 — 2026-11-03
|
||||
|
||||
> 대상: 브랜치 `refactor/maturity-review-2026-11`, `01a8a2a70..5786126c`(커밋 3개, 1,323파일 +60k −9.6k). 2026-11-01 성숙도 리뷰(`../2026-11-01-maturity-review/README.md`)의 수정 전체를 다시 봤다.
|
||||
> 방법: `superpowers:requesting-code-review`의 리뷰어 템플릿으로 영역 리뷰어 6명과 보안 리뷰어 1명(`security-auditor`)을 띄웠다. 리뷰어마다 영역 스킬을 불러 그 기준을 적용했다(각 문서 "범위" 절). 읽기 전용, 하위 에이전트 금지, 의심 결함은 별도 worktree의 임시 테스트로 확인.
|
||||
|
||||
## 1. 결론
|
||||
|
||||
- **Critical 0, 회귀 0.** 원래 리뷰의 High·P1 수정은 모든 영역에서 닫혔다고 판정됐다.
|
||||
- **모든 영역 판정: With fixes.** 수정이 새로 만든 결함과 덜 끝난 완료 기준이 있다. Important 27건(중복을 빼면 22건), Minor 41건.
|
||||
- **정정 — 원래 리뷰의 발견 수는 119건이 아니라 124건이다.** 06 영역 문서의 `NN-10`~`NN-14` 5건이 색인에 들어가지 않아 어떤 수정 묶음에도 배정되지 않았다(오케스트레이터가 `NN-0x`만 `06-0x`로 바꾼 실수). 원래 README 14.3·16절의 "모든 발견 처리"는 이 5건에 대해 틀렸다. 이번 수정에서 `06-10`~`06-14`로 다시 매기고 처리한다.
|
||||
|
||||
## 2. 영역별
|
||||
|
||||
| 문서 | 리뷰 스킬 | Important | Minor | 판정 | 부분으로 판정한 원래 발견 |
|
||||
|---|---|---|---|---|---|
|
||||
| [01 core·application](01-core-application.md) | clean-architecture, domain-driven-design, codebase-design | 5 | 5 | With fixes | 01-07 |
|
||||
| [02 inbound](02-inbound-transports.md) | api-and-interface-design, security-and-hardening | 4 | 4 | With fixes | 03-01, 03-11 |
|
||||
| [03 persistence](03-persistence.md) | jpa-patterns, supabase-postgres-best-practices | 4 | 6 | With fixes | 04-03, 04-10, 06-07 |
|
||||
| [04 outbound](04-outbound-capabilities.md) | performance-optimization, observability-and-instrumentation, security-and-hardening | 5 | 6 | With fixes | 05-16, 05-17, 05-18, 05-21 |
|
||||
| [05 messaging](05-messaging.md) | domain-driven-design, observability-and-instrumentation, doubt-driven-development | 4 | 6 | With fixes | 06-06, 06-10~14(미조치) |
|
||||
| [06 bootstrap·build·CI](06-bootstrap-build-ci.md) | ci-cd-and-automation, refactor, documentation-and-adrs | 3 | 9 | With fixes | 07-08, 07-10, 08-01, 08-04 |
|
||||
| [07 보안](07-security.md) | security-and-hardening, security-review | 2 | 5 | With fixes | — |
|
||||
|
||||
## 3. Important (중복 묶음)
|
||||
|
||||
| 묶음 | ID | 내용 | 증거 |
|
||||
|---|---|---|---|
|
||||
| 권한 탈출구 | RR-01-02 = RR-07-01 | `@SystemInvoked`가 쓰기 유스케이스 권한 선언 규칙을 면제하는데, "bean 금지"는 주석뿐 | 탐침 테스트(bean으로 기동됨) |
|
||||
| 데모 계정 | RR-07-02 | 거부가 정확히 `prod`에서만. 프로필 없음·`production`·`staging`이면 `demo-admin` 로그인 가능 | 탐침 테스트 |
|
||||
| 순서 번호 | RR-03-01 | counter 첫 생성이 겹치면 두 번째 쓰기가 409 | 실 PG |
|
||||
| 순서 번호 | RR-03-02 = RR-05-02 | counter가 없으면 1부터 시작 → 옛 벽시계 번호(~1.7e15)보다 작아져 소비자 순서가 뒤로 감 | 실 PG |
|
||||
| 트랜잭션 | RR-03-03 | JPA 경로에서 트랜잭션 마감 초과가 미분류 500 | H2 재현 |
|
||||
| JPA 규칙 | RR-03-04 | `mappedBy` 없이 양쪽 매핑한 양방향이 금지 규칙 통과 | 임시 fixture |
|
||||
| GraphQL | RR-02-01 | union 아래 복잡도 0·page 상한 미검사(03-01 부분) | 임시 테스트 |
|
||||
| wire 계약 | RR-02-02 | 서블릿 `/error` 디스패치가 `success:true` + 요청 경로 원문 | 실 Tomcat |
|
||||
| wire 계약 | RR-02-03 | `IDEMPOTENCY_UNAVAILABLE` 503을 "실행 전 거부"라 적지만 complete 단계에선 작업이 이미 돎 | 코드 |
|
||||
| gRPC ledger | RR-02-04 | 시도(owner) 구분이 없어 takeover 뒤 옛 owner 기록이 새 시도를 덮음 | 계약 fake |
|
||||
| HTTP client | RR-04-01 | 호출자 deadline으로 끊은 시도를 breaker가 상대 장애로 셈 | 임시 테스트 |
|
||||
| HTTP client | RR-04-03 | JDK 스트리밍 본문이 2초 response-header timeout에서 잘림(문서와 반대) | 임시 테스트 |
|
||||
| Redis | RR-04-02 | 캐시 조건부 쓰기가 멱등성·rate-limit·lease와 8개짜리 SCRIPT lane 공유 | 코드·기본값 |
|
||||
| Redis | RR-04-05 | Redis 멱등성 계약의 실서버 실행이 어느 게이트에도 없음 | 코드 |
|
||||
| 파일 쿼터 | RR-01-05 = RR-04-04 | move가 namespace 쿼터를 옮기지 않아 상한 우회·장부 어긋남 | 코드 |
|
||||
| 파일 계약 | RR-01-04 (+RR-07-06) | fileserver 저장 포트 9개 중 7개 공유 계약 없음, 쿼터 fake가 실제와 다름, 소유자 규칙 두 벌 | 코드 |
|
||||
| 생성 명령 | RR-01-01 | 생성된 저장소 계약에 트랜잭션 hook이 없어 매뉴얼대로 만든 adapter가 상속 불가 | 생성 후 실험 |
|
||||
| 매뉴얼 | RR-01-03 | 매뉴얼 3곳이 수정 뒤 코드와 반대, `IntegrationEventDrafts`를 지키는 장치 없음 | 코드 대조 |
|
||||
| outbox 운영 | RR-05-01 | DEAD 재발행 SQL이 `deferred_attempt_count`를 안 되돌려 다시 DEAD | 실 PG |
|
||||
| outbox 운영 | RR-05-03 | 끝나지 않는 재시도 행을 구분·처분할 수단 없음, bridge가 원인 코드를 버림 | 코드 |
|
||||
| 이벤트 ID | RR-05-04 | 06-06 완료 기준(append 시점 거부) 미충족 | 코드 |
|
||||
| 기동 rule | RR-06-01 (≈RR-04-09) | 기동 rule을 non-static `@Bean`으로 쓰면 설정 bean이 조용히 바인딩 안 됨 | 탐침 테스트 |
|
||||
| build cache | RR-06-02 | `rejectSkipped`가 캐시 입력이 아니라 실패해야 할 lane이 FROM-CACHE 통과 | 실행 |
|
||||
| CI | RR-06-03 | `verifyStrictLaneStages`가 optional-platforms를 안 봄 — `grpcPerformanceTest` 미실행 | 실행 |
|
||||
|
||||
Minor 41건은 각 문서에 있다.
|
||||
|
||||
## 4. 결정 (2026-11-03, 사용자 위임)
|
||||
|
||||
| 항목 | 결정 | 이유 |
|
||||
|---|---|---|
|
||||
| 순서 번호 seed (RR-03-02) | counter가 없으면 전역 floor부터 시작한다. floor는 V21 적용 시각의 마이크로초(옛 벽시계 번호의 상한)로 마이그레이션이 한 번 기록한다. V21은 남은 행이 있는 aggregate의 counter를 그 최대값으로 미리 만든다 | 정리(reaper)로 행이 사라진 aggregate도 소비자가 본 번호보다 작게 시작하지 않는다. 새 aggregate의 첫 번호가 커지는 비용은 순서 보장보다 작다 |
|
||||
| 데모 계정 (RR-07-02) | 거부 목록(`prod`)이 아니라 허용 목록: `local`·`test`·`demo` 프로필이 명시적으로 켜졌을 때만 데모 계정을 만든다 | 프로필 이름이 하나 다르면 열리는 구조가 사용자 원칙("위험은 코드에 드러나야")과 반대다 |
|
||||
| `@SystemInvoked` (RR-01-02) | 기동 시 `@SystemInvoked` 유스케이스가 bean으로 등록돼 있으면 실패, ArchUnit으로 inbound adapter가 직접 부르지 못하게 한다 | 주석뿐인 규칙을 코드로 |
|
||||
| 멱등성 complete 단계 실패 (RR-02-03) | complete 단계의 저장소 실패는 "결과 불명"으로 따로 알린다(실행 전 503과 구분). 같은 키 재전송 시 서버가 replay·in-flight·회복 필요로 판정한다는 것을 계약에 적는다 | 클라이언트가 "실행 안 됨"으로 믿고 새 키로 다시 보내는 위험을 막는다 |
|
||||
| Redis SCRIPT lane (RR-04-02) | 캐시 조건부 쓰기는 멱등성·lease와 다른 연결 예산을 쓴다 | 캐시는 성능 기능이고 멱등성·lease는 정합성 기능이다. 캐시 부하가 정합성을 굶기면 안 된다 |
|
||||
| build cache와 lane 정책 (RR-06-02) | lane 정책 값(`rejectSkipped` 등)을 모두 캐시 입력으로 | 정책을 바꿨는데 옛 결과가 통과하면 게이트가 아니다 |
|
||||
| 끝나지 않는 재시도 (RR-05-03) | bridge가 원인 코드를 행에 남기고, 오래 재시도 중인 행 수·나이를 지표로 내고, runbook에 park(수동 보류)·재개 절차와 테스트된 SQL을 둔다 | 무한 재시도(15절 결정)를 유지하되 운영자가 보고 멈출 수 있어야 한다 |
|
||||
|
||||
## 5. 다음
|
||||
|
||||
위 Important 전부, Minor 41건, 06-10~14를 영역별 수정 묶음으로 고친다. 각 묶음은 `5786126c`에서 만든 worktree에서 RED→GREEN, 오케스트레이터가 합쳐 전체 게이트 후 커밋·push한다. 결과는 이 문서 6절.
|
||||
|
||||
## 6. 수정 결과 (2026-11-03)
|
||||
|
||||
영역별 수정 묶음 7개가 `5786126c`(r4-G는 A·B·C·D·F를 합친 임시 기준)에서 `test-driven-development` 스킬 절차로 RED→GREEN 했고, 오케스트레이터가 합쳤다. 하위 에이전트 없음.
|
||||
|
||||
| 묶음 | 상태 | 검증 (에이전트) | 처리 내용 | 결정·합칠 때 조치·남은 것 |
|
||||
|---|---|---|---|---|
|
||||
| r4-a | 완료 | leaf check 9, cache-redis test, architectureCheck, jpaPlatformContractTest fileserver 47, outbox sequence PG, verifyFeatureScaffold, 소유자 규칙 변이 잡힘 | RR-01-02=RR-07-01 @SystemInvoked bean 기동 실패+ArchUnit, RR-01-01·07·10 생성 명령, RR-01-03·09 매뉴얼·IntegrationEventDrafts ArchUnit, RR-01-04+RR-07-06 fileserver 계약 6개·fake 정합·소유자 정본 FileAccessSubject.owns(RED 17), RR-01-05=RR-04-04 move 쿼터(RED 2), RR-01-06 순서 계약 보강, RR-01-08 | 합칠 때 매뉴얼 09장·OutboxAggregateSequenceContract를 r4-c와 수동 병합(r4-a 새 케이스는 첫 번호 기준 상대값이라 floor와 충돌 없음). 결정: 만료·미해제 예약 확정은 받음, move는 복사 후 삭제 안 씀 |
|
||||
| r4-b | 완료(sample 데모 체인 한 줄은 r4-f로) | leaf check 6, graphql·web systemTest, webJettyCompat, -p optional-platforms ci integrationCheck(ledger PG 41), architectureCheck, verifyEnvKeys, documentContractTest, verifyPublicPathSnapshot, 영향 모듈 test | RR-02-01 union 복잡도, RR-02-02 EnvelopeErrorController+ERROR 디스패치만 허용(JWT 체인 401→400), RR-02-03 IDEMPOTENCY_COMPLETION_UNKNOWN(503 재시도 가능), RR-02-04 GrpcClaimToken·claim_attempt·V003(옛 owner commit 거부·실패 무시, 조건부 commit), RR-02-05 Retry-After 상수·lease 이하면 기동 실패, RR-02-06~08 | 결정: 새 코드 503(code로 구분), 시도 번호는 카운터, ERROR 디스패치 허용(보안 정책 변경) |
|
||||
| r4-c | 완료 | leaf check 5, notification test, sample·app-bootstrap architectureTest, architectureCheck, 실 PG jpaPlatformContract 334·Migration 45·Failure 6·V21·runbook·트랜잭션 lane 등 skip 0 | RR-03-01 counter ON CONFLICT(RED 실 PG), RR-03-02=RR-05-02 V21 floor 테이블+counter 미리 생성+행 최대값 하한(RED 3), RR-03-05 lock_timeout 5s·무효 인덱스 거부·CONCURRENTLY 절차 runbook, RR-03-03 마감 초과 분류(H2+실 PG), RR-03-04 양쪽 매핑 양방향 금지, RR-03-06~10 | 결정: V21 직접 수정(아직 어디에도 미적용 — 적용한 개발 DB는 재생성), H2 호환 위해 다문장 counter, 계약 '1부터'→'첫 번호부터 1씩'(JPA 첫 번호 ≈1.7e15) |
|
||||
| r4-d | 완료(RR-04-02 지표·RR-07-04 운영 거부 남음) | leaf check 6, Redis container 52·topology standalone, Toxiproxy 4, spring70 compat, perf, notification 문서·환경 계약, PG 멱등성 계약 14, verifyEnvKeys, architectureCheck, verifyStrictLaneStages, compose 정적 18 | RR-04-01 호출자 deadline은 breaker 미집계(RED), RR-04-03 JDK 스트리밍 read-idle(RED), RR-04-02 CacheScriptLane(기본 4), RR-04-05 lane 연결, RR-04-06~08·10·11, RR-07-03 SNS 4xx 거절+감사(RED), RR-07-04 ACL 파일 이름 lane-fixture-accounts.acl, RR-07-07 SNS MessageId 기준 | 결정: total-call이 끊은 시도는 실패로 셈, 캐시 lane 4. 남음: lane별 지표(meter registry 없음), 운영 SecretSourceValidator가 fixture- 값 거부 |
|
||||
| r4-e | 완료 | 건드린 leaf 13 check, Kafka relay·inbox, outbox PG 6·migration·jpaPlatformContract, architectureCheck, verifyDependencyLocks, verifyStrictLaneStages, documentContractTest | RR-05-01 재발행 SQL deferred 초기화+runbook SQL lane(RED 실 PG), RR-05-03 last_failure_code(V22)·오래 재시도 게이지·PARKED·runbook SQL(RED 4), RR-05-04 draft가 비UUIDv7 거부, RR-05-05~09, 06-10 schema 버전 해시 고정, 06-11~14 | 합칠 때 4곳 수동 병합: OrderKeyRunbook IT를 공용 OutboxRunbookSql로 + V22 추가로 latest가 22가 되어 'V21 적용' 단언을 applied 목록 기준으로, sha256에 V22, application-core README, 매뉴얼 09. 결정: PARKED는 DDL 없이, 발행 포트·저장소 포트 시그니처 변경(파생 서비스 깨짐), 오래 재시도 기준 10회, DB CHECK 제약 안 넣음. 남음: 2026-11-01 README 색인 정정(오케스트레이터), V21 주석의 없는 클래스명 |
|
||||
| r4-f | 완료 | build-logic 107, ci, app-bootstrap documentContract·systemTest, sample check·webSystemTest·integrationTest·posterImageMigration, -p optional-platforms ci, 두 빌드 verifyStrictLaneStages, verifyEnvKeys, compose 정적 | RR-06-01=RR-04-09 규칙 생성 중 다른 singleton 생기면 기동 실패(RED), RR-06-02 lane 정책을 Test 입력으로(RED), RR-06-03·04 optional 빌드 단계 검사·-x/continue-on-error/if 해석(RED), RR-07-02 데모 계정 허용 목록 local·test·demo(RED 6), RR-06-05+07-05 CSRF 제외 축소·sample qualityCheck, RR-06-06~12, RR-02-02 샘플 체인 ERROR 디스패치 허용 | 남음: cache-redis 컨테이너 lane main 단계 중복 실행. 결정: release job --rerun-tasks 안 넣음 |
|
||||
| r4-g | 완료 | redis-runtime 64·redis-sdk 310·cache-redis 192·app-bootstrap test 222·systemTest 11·documentContract 60, redisContainerContract 53, topology standalone, verifyEnvKeys, architectureCheck, verifyDependencyLocks, verifyStrictLaneStages | RR-04-02 redis.lane.* 지표 6개(RED 10), RR-07-04 prod에서 fixture- 값 거부(RED), cache-redis 컨테이너 lane main 중복 제거 | 합친 뒤 오케스트레이터: r4-g가 찾은 '레지스트리의 redis.capability.* 6개를 아무 코드도 내보내지 않음' → 레지스트리에서 빼고 incident runbook을 redis.lane.* 기준으로, cache-redis README에 미구현 지표로 기록. 남음(의도): httpclient failure injection lane main 2회(05-06/05-16 결정) |
|
||||
|
||||
### 6.1 합칠 때 오케스트레이터가 고친 것
|
||||
|
||||
- 수동 병합: 매뉴얼 09장(r4-A·r4-C·r4-E), `OutboxAggregateSequenceContract`(r4-A·r4-C), `PostgreSqlOutboxOrderKeyRunbookIntegrationTest`(r4-C·r4-E — 공용 `OutboxRunbookSql`로, V22가 생겨 "V21 적용" 단언을 적용 목록 기준으로), `applied-migrations.sha256`(V22), application-core README.
|
||||
- r4-G가 찾은 거짓 선언: `docs/registries/metrics.yaml`의 `redis.capability.*` 6개를 어떤 코드도 내보내지 않았고 incident runbook이 그것을 보라고 했다. 레지스트리에서 빼고 runbook을 실제로 나오는 `redis.lane.*` 기준으로 고쳤다. 원래 설계는 cache-redis README 「아직 내보내지 않는 지표」.
|
||||
- 최종 게이트에서 드러난 2건: (1) sample `CreatePosterConcurrencyIntegrationTest`가 v4 event id를 써서 RR-05-04 이후 16건 모두 거부 → 운영과 같은 `UuidOutboxEventIdFactory`로. (2) `EnvelopeErrorController`의 `@RequestMapping`이 FindSecBugs `SPRING_CSRF_UNRESTRICTED_REQUEST_MAPPING` → 오류 디스패치 전용(보안 체인이 ERROR dispatch만 허용)이라 그 메서드에만 이유를 단 제외.
|
||||
- 원래 리뷰 README 12절 색인에 06-10~06-14를 넣고 발견 수를 124건으로 정정했다.
|
||||
|
||||
## 7. 게이트 (2026-11-03, 합친 메인 작업 트리, 공유 잠금)
|
||||
|
||||
첫 실행(22:27)은 `ci`(FindSecBugs 1건)와 `integrationCheck`(sample 동시 생성 테스트)가 실패했고 6.1절대로 고쳤다. 재실행 결과:
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하 |
|
||||
|---|---|---|---|
|
||||
| `ci` | rc=0 | 215초 | load 8.27 |
|
||||
| `:integrationCheck` | rc=0 | 1,647초(부하 높음) | load 29.15 |
|
||||
| `mainCheck` | rc=0 | 260초 | load 35.16 |
|
||||
| `-p optional-platforms ci integrationCheck performanceCheck` | rc=0 | 62초 | load 16.51 (첫 실행, 두 수정과 무관) |
|
||||
| `:performanceCheck` | rc=0 | 25초 | load 20.55 (첫 실행) |
|
||||
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 4초 | 첫 실행 |
|
||||
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 첫 실행 |
|
||||
|
||||
## 8. 남은 것
|
||||
|
||||
- **의도적으로 둔 것**: httpclient failure-injection lane이 main 단계에서 두 번 돈다(원래 리뷰 05-06·05-16 결정). capability 단위 Redis 지표(`redis.capability.*`)는 설계만 있고 구현하지 않았다(새 기능 범위, cache-redis README).
|
||||
- **소유자 확인이 필요한 결정**: 4절 표, 그리고 묶음이 기본값으로 정한 것(6절 "결정" 칸) — 특히 서블릿 오류 디스패치 허용(보안 정책), 데모 계정 허용 목록, V21을 V22 없이 직접 수정(이 브랜치의 V21을 적용한 개발 DB는 재생성), 발행·저장소 포트 시그니처 변경, `IDEMPOTENCY_COMPLETION_UNKNOWN` 신설, prod에서 `fixture-` 값 거부.
|
||||
- **짝 프론트**: `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, 결과 불명)을 인계 문서에 더했다.
|
||||
- **이 환경에서 확인할 수 없는 것**: 실제 CI runner 실행.
|
||||
|
||||
|
||||
## 9. 2차 재리뷰 (수정 커밋 `bbe944bd`만, 2026-11-04)
|
||||
|
||||
1차 재리뷰 수정(`bbe944bd`, 406파일)을 리뷰어 4명이 같은 템플릿·스킬 방식으로 다시 봤다(`round2/01~04-*.md`). 저장소 전체가 아니라 이 커밋만 본 이유: 원래 리뷰와 1차 재리뷰가 전 영역을 이미 봤고, 위험은 "수정이 새 결함을 만든다"는 반복 패턴이다.
|
||||
|
||||
| 문서 | Important | Minor | 이번 라운드가 새로 만든 Important | 회귀 |
|
||||
|---|---|---|---|---|
|
||||
| [round2/01 core·inbound](round2/01-core-app-inbound.md) | 2 | 5 | RR-01-12 | 0 |
|
||||
| [round2/02 persistence·messaging](round2/02-persistence-messaging.md) | 1 | 7 | RR-02-09 | 0 |
|
||||
| [round2/03 outbound](round2/03-outbound.md) | 1 | 7 | 없음 | 0 |
|
||||
| [round2/04 bootstrap·build·sample](round2/04-bootstrap-build-sample.md) | 3 | 3 | RR2-04-01, RR2-04-02 | 0 |
|
||||
|
||||
Important 7건:
|
||||
- RR-01-11 — `http-contract.md`는 결과 불명 503 뒤 같은 키 재전송이 lease 뒤 500으로 막힌다고 적었지만, Redis store는 lease가 지난 EXECUTING을 넘겨받아 작업을 다시 실행한다(실 Redis 확인). RR-02-03 부분.
|
||||
- RR-01-12 — 새 `@SystemInvoked` 규칙 두 개가 매뉴얼 09장의 이벤트 소비 handler → 쓰기 use case 경로를 막는다.
|
||||
- RR-03-11 — Redis claim이 key TTL을 replay TTL로 둬서, replay TTL < processing lease인 배포에서 lease 도중 key가 사라져 같은 키가 두 번 실행된다(실 Redis Lua 확인). RR-04-08 부분.
|
||||
- RR-02-09 — V22가 `outbox_event`에 가장 강한 잠금을 걸면서 `lock_timeout`이 없다(실 PG16: 19초 대기, 그동안 읽기·쓰기 막힘).
|
||||
- RR2-04-01 — prod `fixture-` 거부가 비밀이 아닌 값(`HOSTNAME` 등)까지 막는다.
|
||||
- RR2-04-02 — 데모 허용 목록의 `test`·`demo` 프로필로 sample이 뜨지 않는다(이미지 실행 문서대로 하면 기동 거부).
|
||||
- RR2-04-03 — 기동 rule runner에 검사 없는 면제 경로가 남아 `@Value` 필드·JavaBean 설정이 조용히 null(RR-06-01 부분).
|
||||
|
||||
### 9.1 결정 (3차 수정용, 2026-11-04)
|
||||
|
||||
| 항목 | 결정 | 이유 |
|
||||
|---|---|---|
|
||||
| RR-01-11 결과 불명 뒤 재전송 | 두 멱등성 store(PostgreSQL·Redis)가 같은 공유 계약을 따른다: lease가 지난 실행 중 기록은 작업을 다시 돌리지 않고 "회복 필요"로 답한다. 계약 문서와 코드를 맞춘다 | 결과 불명인 작업을 서버가 몰래 다시 실행하면 이번 계약의 목적(중복 효과 방지)이 무너진다 |
|
||||
| RR-03-11 Redis key TTL | claim·renew 모두 key TTL ≥ max(replay TTL, processing lease). 설정 검사도 둔다 | lease가 남아 있는 동안 key가 사라지면 안 된다 |
|
||||
| RR-01-12 소비 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked` use case에 닿지 못한다. 시스템이 부르는 inbound(메시지 소비자·스케줄러)는 명시적 표시로 허용하고, 매뉴얼 09장 경로를 실제 테스트로 고정한다 | 규칙의 목적은 "사용자 요청이 권한 검사 없이 쓰기에 닿지 않게"다. 시스템 경로까지 막으면 매뉴얼이 거짓이 된다 |
|
||||
| RR2-04-01 fixture 값 거부 범위 | 비밀로 분류된 키(`docs/registries/secrets-classification.yaml`)만 검사한다 | 운영 hostname·이름은 비밀이 아니다 |
|
||||
| RR2-04-02 데모 프로필 | 허용 목록의 각 프로필은 sample이 실제로 뜨는 프로필이어야 한다. 뜨게 고치거나, 독립 실행용이 아니면 목록에서 뺀다. 문서·Dockerfile과 맞춘다 | 허용한 프로필로 뜨지 않으면 허용 목록이 거짓이다 |
|
||||
| RR-02-09 V22 잠금 | V21과 같은 `SET LOCAL lock_timeout`과 같은 모양의 lane 테스트 | 같은 커밋 안의 두 마이그레이션이 다른 규칙을 따르면 안 된다 |
|
||||
|
||||
멈추는 기준: 3차 수정 뒤 그 diff만 보는 확인 리뷰에서 새 Important가 0이면 멈춘다.
|
||||
|
||||
## 10. 3차 수정 결과 (2026-11-04)
|
||||
|
||||
9.1절 결정대로 2차 재리뷰 발견 29건(Important 7, Minor 22)을 영역 묶음 4개가 `ecc74b7d`에서 `test-driven-development` 스킬 절차로 RED→GREEN 했다. 오케스트레이터가 합쳤다. 하위 에이전트 없음.
|
||||
|
||||
| 묶음 | 발견 | 상태 | 검증 (에이전트) | 처리 내용 | 결정 |
|
||||
|---|---|---|---|---|---|
|
||||
| r5-a 멱등성·outbound | RR-01-11, RR-03-11~18 | 완료 | leaf check 9, Redis 컨테이너 계약, PG 멱등성 계약 19/19, `postgresqlIdempotencyIntegrationTest` 8/8, architectureCheck, verifyEnvKeys, documentContractTest, topology standalone·cluster | RR-01-11 Redis CLAIM이 lease 지난 EXECUTING을 ABANDONED로 바꾸고 `RECOVERY_REQUIRED`로 답한다(PG와 같음, RED 실 Redis), 공유 계약에 시간 케이스 5개. RR-03-11 두 store의 기록 수명을 lease + replay TTL로(claim·takeover·renew), `replay-ttl < processing-lease`면 기동 실패(RED 실 Redis·PG). RR-03-12 skip을 read 단위로(RED). RR-03-13 read마다 걸던 타이머를 스트림당 watchdog 하나로(read당 2.6–3.1µs → 25–32ns). RR-03-14 본문 실패를 `IOException` 하위 `HttpBodyReadException`으로(RED). RR-03-15 시스템 속성 목록을 Spring과 비교(RED). RR-03-16 breaker 맹점 문서. RR-03-17 listener 첫 실패 WARN(RED). RR-03-18 문서 | lease가 지난 실행은 abandon해서, 늦게 끝난 첫 시도의 결과도 기록하지 않는다(9.1절 "다시 돌리지 않는다"와 같은 방향, PG 동작 유지). cluster topology 첫 실행의 캐시 테스트 2건 실패는 재실행·기준 커밋에서 재현 안 됨 |
|
||||
| r5-b core·inbound | RR-01-12~17 | 완료 | application-core·fileserver·web·graphql·grpc·inbound messaging·service-runtime check, app-bootstrap architectureTest, architectureCheck, verifyDependencyLocks, inbox Kafka+PG, gRPC ledger PG 44, jpaPlatformContract | RR-01-12 새 표시 `@SystemCaller(reason)`: 메시지 handler·scheduler가 `@SystemInvoked` use case를 생성자에서 `new`로 만든다. ArchUnit `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`·`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, 매뉴얼 09장 경로를 `SystemInvokedConsumePathTest`로 고정. RR-01-13 `/error` status 접기를 문서·`EnvelopeErrorControllerTest`로. RR-01-14 `GraphQlClientPolicy`의 page 규칙 복사본 삭제. RR-01-15 ledger `release(identity, claimToken)`(RED 2). RR-01-16 `DirectTransactionPort`가 스레드별 트랜잭션(RED). RR-01-17 쿼터 롤백 계약 케이스(RED) | scheduler 패키지도 `@SystemCaller` 허용, `/error`는 코드 표에 없는 status를 class 코드로 접는다, release도 claim token으로 막는다 |
|
||||
| r5-c persistence·messaging | RR-02-09~16 | 완료 | persistence-jpa(587)·persistence-notification·starter-kafka·outbox-relay·application-core·sample check, 실 PG lane 11개, `-p optional-platforms integrationCheck`, architectureCheck, documentContractTest, verifyStrictLaneStages | RR-02-09 V20·V22·알림 V11~V13·sample V8_1·grpc V002·V003에 `SET LOCAL lock_timeout = '5s'`, 텍스트 검사기 `LockWaitMigrationInspector`(testkit)와 실 PG lane `postgresqlMigrationLockWaitIntegrationTest`(RED 9). RR-02-10 scope를 바꾸는 배포는 rolling 금지 문서. RR-02-11 모르는 상태 값은 집계에서 빼고 WARN 1회(RED). RR-02-12 claim이 DEAD로 옮길 때 `last_failure_code`를 쓰고 `outbox.pending.size{status=DEAD} > 0` p1 경보(RED 단위·실 PG). RR-02-13 Javadoc. RR-02-14 runbook 숫자를 상수와 비교하는 document-contract lane. RR-02-15 메시지·가이드·fixture. RR-02-16 header 테스트, 업그레이드 안내 B-39 | 브리프에 없던 V20·V8_1도 같은 근거(아직 어디에도 미적용)로 수정. 규칙 이전에 배포된 마이그레이션 24개는 고칠 수 없어 동결 목록(줄기만 함). DEAD 원인 코드는 claim의 row lock 아래 flush |
|
||||
| r5-d bootstrap·build·sample | RR2-04-01~06 | 완료 | support·app-bootstrap·sample·objectstorage check, app-bootstrap systemTest·documentContractTest, sample systemTest·webSystemTest, `-p build-logic check`, 두 빌드 verifyStrictLaneStages, verifyEnvKeys, compose 18 lane, `docker build`와 실제 기동(프로필 없음 exit 71, `demo` 8초 ready) | RR2-04-01 prod `fixture-` 검사는 비밀값만(레지스트리 `secret` 행, 모듈 기여 비밀, `secret://…/<VAR>` 대상)(RED). RR2-04-02 sample `application.yml`이 `local`·`test`·`demo`에서 object storage를 끔(RED 9). RR2-04-03 rule·비밀 목록 bean에 주입 멤버·`@ConfigurationProperties`가 있으면 모든 프로필에서 기동 실패(RED 4). RR2-04-04 축약 `-x`, `workflow_dispatch` 전용 workflow, `working-directory`+`-p`, `uses:`의 `with: run:`(RED 7). RR2-04-05 lane json의 `APP_` 밖 키 거부, `property:` 행은 설정 metadata에 있을 때만 읽힘(RED 2). RR2-04-06 문서 | 리뷰어 제안 "static @Bean 선언 강제" 대신 bean이 실제로 필요로 하는 것을 본다(선언 강제는 문제없는 등록을 막고 `@Value` 필드는 통과시킨다). `workflowProjectDirectory` 설정을 없애고 저장소 구조로 정한다 — `working-directory` 없이 `./gradlew`를 부르는 workflow 명령은 실행으로 세지 않는다(B-36). `ca.spring-config`의 `compileJava`가 `processResources` 뒤에 돈다 |
|
||||
|
||||
### 10.1 합칠 때 오케스트레이터가 한 것
|
||||
|
||||
- 업그레이드 안내 `docs/upgrade/2026-11-maturity-review.md`를 세 방향(r5-b·r5-c·r5-d)에서 손으로 합쳤다. B-14·B-15는 r5-d, B-16은 r5-b, B-39는 r5-c.
|
||||
- RR-01-17의 남은 절반(이 수정 전에 move된 파일의 장부)을 직접 마무리했다. `docs/fileserver/operations.md` 「Namespace quota drift」에 차이를 찾는 쿼리와 namespace 하나를 다시 계산하는 SQL을 적었다. 실 PostgreSQL 16에 V1 스키마와 move 전 상태(출발 +100, 도착 −100, 삭제된 파일, 진행 중 예약)를 넣고 돌려, 차이 2행 → 0행, `RESERVED` 행은 그대로인 것을 확인했다. 업그레이드 안내 4절의 "재계산 SQL은 아직 없다"를 이 절로 바꿨다.
|
||||
- 프론트 인계 문서에 이번 계약 변화(같은 키 재전송은 작업을 다시 돌리지 않음, `replay-ttl` 24h, `/error` status 접기)를 더했다.
|
||||
|
||||
### 10.2 게이트 (2026-11-04, 합친 메인 작업 트리, 공유 잠금)
|
||||
|
||||
첫 실행에서 모두 통과했다.
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|
||||
|---|---|---|---|
|
||||
| `ci` | rc=0 | 6분 22초 | 7.75 |
|
||||
| `verifyStrictLaneStages --dry-run` (주 빌드 / `-p optional-platforms`) | rc=0 / rc=0 | 10초 / 3초 | 16.51 / 15.10 |
|
||||
| `mainCheck` | rc=0 | 3분 6초 | 14.37 |
|
||||
| `:integrationCheck` | rc=0 | 14분 22초 | 15.03 |
|
||||
| `-p optional-platforms ci integrationCheck performanceCheck` | rc=0 | 1분 3초 | 1.88 |
|
||||
| `:performanceCheck` | rc=0 | 22초 | 9.69 |
|
||||
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 3초 | 7.63 |
|
||||
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | 4초 | 7.82 |
|
||||
|
||||
`integrationCheck`는 입력이 없는 lane 4개(`redisTopologyTest` 3개, `objectStorageAwsQualificationTest`)를 이름을 대며 뺐다(설계대로). 이 절과 `docs/fileserver/operations.md`·업그레이드 안내 문구는 `ci`가 도는 동안 고쳤다. 그 뒤의 `mainCheck`(document-contract lane 포함)는 고친 문서로 돌았다.
|
||||
|
||||
### 10.3 남은 것
|
||||
|
||||
- `spotbugsTestFixtures`: 게이트 밖이고 `ecc74b7d`에서도 실패한다. r5-c의 새 검사기(`LockWaitMigrationInspector`)가 정규식 ReDoS 경고 8건을 더했다(입력은 저장소 마이그레이션 파일뿐).
|
||||
- 실제 CI runner 실행: Gitea repo의 Actions가 꺼져 있어(`has_actions: false`) workflow가 돈 적이 없다. 켜는 것은 소유자 일이다.
|
||||
- 소유자 확인이 필요한 기본값: 10절 "결정" 칸 — 특히 lease 뒤 늦게 끝난 첫 시도의 결과를 버리는 것, workflow 명령에 `working-directory`가 필요해진 것.
|
||||
- 다음: 이 수정 커밋만 보는 확인 리뷰. 새 Important가 0이면 멈춘다(9.1절).
|
||||
|
||||
## 11. 3차 확인 리뷰 (수정 커밋 `1885bf8d`만, 2026-11-04)
|
||||
|
||||
3차 수정 커밋만 리뷰어 4명이 같은 템플릿·스킬 방식으로 봤다(`round3/01~04-*.md`). 심각도 기준(Important = 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자에게 틀린 조치를 시키는 문서)을 지침에 적었다.
|
||||
|
||||
| 문서 | Important | Minor | 2차 발견 재확인 | 회귀 |
|
||||
|---|---|---|---|---|
|
||||
| [round3/01 core·inbound](round3/01-core-app-inbound.md) | 0 | 4 | RR-01-11~17 닫힘 | 0 |
|
||||
| [round3/02 persistence·messaging](round3/02-persistence-messaging.md) | 0 | 5 | RR-02-09~16 닫힘(RR-02-10은 결정으로) | 0 |
|
||||
| [round3/03 outbound](round3/03-outbound.md) | 0 | 5 | RR-01-11, RR-03-11~18 닫힘 | 0 |
|
||||
| [round3/04 bootstrap·build·sample](round3/04-bootstrap-build-sample.md) | 0 | 5 | RR2-04-01~06 닫힘 | 0 |
|
||||
|
||||
**9.1절 멈춤 기준을 채웠다**: 새 Important 0, 회귀 0. 리뷰어가 실행으로 확인한 것: `@SystemCaller` 위반 fixture가 실제로 실패, Redis Lua(abandon·늦은 complete 거부·기록 TTL), Flyway 안의 `SET LOCAL lock_timeout`(V22에서 그 줄을 지우면 lane 실패), 고친 마이그레이션 9개가 main `01a8a2a70`과 파생 서비스에 없음, 쿼터 SQL(실 PG), workflow 해석(축약 `-x`).
|
||||
|
||||
Minor 19건 중 동작에 닿는 것:
|
||||
- RR3-03-01 — JDK read-idle watchdog이 공용 `ForkJoinPool`에서 돌아, 공용 풀이 막히면 timeout이 늦다(300ms 설정이 2,699ms). 기본 transport(Apache)는 영향 없음.
|
||||
- RR3-04-02 — 붙여 쓴 `-x<task>`를 `verifyStrictLaneStages`가 읽지 않아 거짓 통과(이전부터).
|
||||
- RR3-01-01 — `@SystemCaller` 규칙이 직접 의존만 본다. 같은 leaf 안에서 컨트롤러가 그 bean을 주입받으면 통과.
|
||||
- RR3-04-01·03 — 인터페이스 타입 `static @Bean` 뒤의 `@Value` 비밀 목록, 코드가 든 Redis 계정 참조가 사전·`fixture-` 검사를 지난다(둘 다 이름을 대는 기동 실패이거나 비밀 아닌 경로).
|
||||
- RR3-02-01·03·04 — 잠금 대기 검사기가 FK·trigger·`REINDEX`·`lock_timeout = 0`·소수 버전·gRPC ledger tree를 못 본다.
|
||||
|
||||
### 11.1 결정
|
||||
|
||||
리뷰 반복은 여기서 멈춘다. Minor 19건은 사용자 지시("남은 부분 전부 진행")에 따라 마지막 정리 라운드(r6)로 고친다. r6의 멈춤 기준: 전체 게이트 통과 + r6 diff 확인 리뷰 1회에서 Important가 나오면 그것만 고치고, Minor는 남은 것으로 기록하고 더 돌지 않는다.
|
||||
|
||||
## 12. 마지막 정리 라운드 r6 (Minor 19건, 2026-11-04)
|
||||
|
||||
11.1절 결정대로 3차 확인 리뷰의 Minor 19건을 영역 묶음 4개가 `339cf8fd`에서 `test-driven-development` 절차로 고쳤다. 맡은 Minor 밖은 고치지 않고 보고만 하게 했다.
|
||||
|
||||
| 묶음 | 발견 | 상태 | 검증 (에이전트) | 처리 내용 | 결정·남은 것 |
|
||||
|---|---|---|---|---|---|
|
||||
| r6-a core·inbound | RR3-01-01~04 | 완료 | application-core·service-runtime·inbound messaging·app-bootstrap check(systemTest 포함), architectureTest 208, architectureCheck, 실 PG16 | RR3-01-01 `@SystemCaller` 안의 중첩 클래스도 검사, 새 규칙 `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(사용자 전송 → `@SystemCaller`를 직접·중간 클래스 경유 모두 거부, RED 3). RR3-01-02 전송 타입 목록에 `jakarta.ws.rs..`·`graphql..`(RED JAX-RS)와 "목록 방식" 문서. RR3-01-03 쿼터 보정 SQL이 COMMITTED 행 `reserved_bytes`를 0으로(RED 실 PG). RR3-01-04 scheduler·handler·예약 작업 세 경로를 매뉴얼 07장 표로 정본화하고 Javadoc·README·가드 문구를 맞춤 | 새 규칙은 직접 의존이 아니라 이어지는 의존 전체를 본다(중간 클래스 하나로 다시 열리지 않게, 실행 5.7초). 남음: `graphql..` 항목은 fixture 없음(graphql-java가 architectureTest classpath에 없다) |
|
||||
| r6-b persistence·messaging | RR3-02-01~05 | 완료 | persistence-jpa check 611, sample check 339, `-p optional-platforms` grpc ledger check·integrationTest 46, `postgresqlMigrationLockWaitIntegrationTest` 5/5, outbox runbook lane, documentContractTest 62, architectureCheck | RR3-02-01 검사기가 `REFERENCES`·trigger·비동시 `REINDEX`·`REFRESH MATERIALIZED VIEW`·`CLUSTER`·`VACUUM FULL`을 잡고, `lock_timeout` 0·`DEFAULT`·`RESET`과 비트랜잭션(`.sql.conf executeInTransaction=false`) `SET LOCAL`을 상한으로 치지 않음(RED 19). 새로 걸린 배포 파일 5개는 내용 그대로 동결 목록에(main과 blob 같음). RR3-02-02 원인 세션을 `pg_locks`로 찾는 runbook 조회(실 PG). RR3-02-03 버전 판정을 testkit `VersionedMigrationFiles` 하나로(RED `V22_1`·`V22.2`). RR3-02-04 grpc ledger IT가 tree 전체 검사(RED). RR3-02-05 연관 규칙 메시지(RED 2) | grpc는 optional 빌드라 testkit을 못 써 실 PG IT로 검사(버전 정규식 한 벌 더). 남음: `spotbugsTestFixtures`(게이트 밖) ReDoS 경고 8→15 |
|
||||
| r6-c outbound·멱등성 | RR3-03-01~05 | 완료 | 6개 leaf check, architectureCheck, verifyEnvKeys, redisContainerContractTest 59/59, PG 멱등성 계약 20/20, httpclient 성능 5·장애 주입 4, documentContractTest 62, repositoryContractTest 69 | RR3-03-01 watchdog을 전용 데몬 스레드(`httpclient-jdk-read-idle`)로, close 시 작업 취소(RED 공용 풀 포화 시 300ms 설정이 5,995ms → 수정 후 300ms, read당 비용 21–24ns 그대로). RR3-03-02 `failure-retention` 수명 문서. RR3-03-03 회복 필요 예외 메시지 끝에 scope digest(RED 3), runbook에 Redis·PG 기록 조회와 ABANDONED만 지우는 절차(실 Redis 7.4·PG 16). RR3-03-04 옛 표현. RR3-03-05 INSPECT가 `leaseUntil`을 돌려줌(RED 실 Redis) | `failure-retention ≥ replay-ttl` 기동 검사는 넣지 않음(지금 뜨는 설정을 깨지 않게, 문서만 — 소유자 판단). 본 것: gRPC는 carrier 실패를 로그에 남기지 않아 digest를 찾을 수 없다 |
|
||||
| r6-d bootstrap·build | RR3-04-01~05 | 완료(RR3-04-03은 문서) | `-p build-logic check`, support·redis-sdk·sample·app-bootstrap check, verifyEnvKeys, 두 빌드 verifyStrictLaneStages, systemTest 11, documentContractTest 62, `SampleDemoProfilesStartupSystemTest` 3 | RR3-04-01 규칙을 돌리기 전에 비밀 목록 bean을 만들어 실제 클래스를 검사(모든 프로필, RED). RR3-04-02 붙여 쓴 `-x<task>`·`-p<dir>`(RED). RR3-04-03 코드가 든 Redis 계정 참조는 조립하는 쪽이 `static RequiredProductionSecrets` bean을 두는 방법을 문서로. RR3-04-04 "선언된 property" 계산을 classpath 기준 하나로(RED). RR3-04-05 주석 | RR3-04-03 코드 수정은 redis-sdk에 새 의존 edge가 필요하거나 G-7c 결정을 되돌려야 해서 하지 않음. 남음: `-mx` 같은 짧은 플래그 묶음은 읽지 않음, 바뀐 기동 실패 문구에 맞추던 로그 매처 |
|
||||
|
||||
합칠 때 오케스트레이터: 업그레이드 안내 B-14·B-15(r6-d)와 B-16(r6-a)을 손으로 합쳤고, r6-c가 남긴 동작 변경 두 줄(JDK watchdog 스레드, 회복 필요 메시지의 scope digest·INSPECT `leaseUntil`)을 5절에 더했다.
|
||||
|
||||
### 12.1 게이트 (2026-11-04, 합친 메인 작업 트리, 공유 잠금)
|
||||
|
||||
첫 실행에서 모두 통과했다.
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|
||||
|---|---|---|---|
|
||||
| `ci` | rc=0 | 6분 22초 | 2.31 |
|
||||
| `verifyStrictLaneStages --dry-run` (주 빌드 / `-p optional-platforms`) | rc=0 / rc=0 | 11초 / 3초 | 16.09 / 14.51 |
|
||||
| `mainCheck` | rc=0 | 3분 10초 | 13.90 |
|
||||
| `:integrationCheck` | rc=0 | 14분 27초 | 10.98 |
|
||||
| `-p optional-platforms ci integrationCheck performanceCheck` | rc=0 | 1분 | 2.32 |
|
||||
| `:performanceCheck` | rc=0 | 22초 | 9.95 |
|
||||
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 3초 | 7.81 |
|
||||
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 8.31 |
|
||||
|
||||
다음: 이 커밋만 보는 확인 리뷰 1회. Important가 나오면 그것만 고치고, Minor는 남은 것으로 기록한다(11.1절).
|
||||
|
||||
## 13. r6 확인 리뷰와 종료 (2026-11-04)
|
||||
|
||||
정리 커밋 `f40c03c6` 전체를 리뷰어 1명이 4개 영역으로 나눠 봤다([round4/review.md](round4/review.md)). Critical 0, **Important 0**, 회귀 0, Minor 7. 3차 확인 리뷰 Minor 19건 중 18건 닫힘, RR3-04-03은 결정으로 닫힘. 리뷰어가 확인한 것: 동결 목록에 더한 5개 파일이 main `01a8a2a70`과 같은 blob, 새 ArchUnit 규칙 탐침 5개, 잠금 대기 검사기 입력 16개.
|
||||
|
||||
11.1절 결정대로 리뷰·수정 반복을 여기서 끝낸다. 아래 Minor 7건은 고치지 않고 남긴다.
|
||||
|
||||
| ID | 내용 | 영향 |
|
||||
|---|---|---|
|
||||
| RR4-01-01 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 controller가 시스템 호출자를 인터페이스·`Runnable`로 주입받으면 못 본다. 문서는 `ObjectProvider`를 못 잡는다고 적었지만 실제로는 잡는다 | 같은 leaf 안에서만 생기는 경로(leaf 사이는 의존 방향 게이트가 막는다). 문서 문장 정정 필요 |
|
||||
| RR4-01-02 | 웹 타입을 쓰는 `@Configuration`이 handler를 bean으로 등록하면 사용자 전송으로 잡힌다(거짓 양성) | 빌드가 실패하는 쪽. 설정을 나누면 된다 |
|
||||
| RR4-02-01 | 검사기가 Flyway가 스스로 트랜잭션 밖에서 돌리는 문장을 모른다(`VACUUM FULL` + `SET LOCAL`이 통과) | 그런 마이그레이션은 Flyway에서 실패하므로 운영 잠금까지는 안 간다 |
|
||||
| RR4-03-01 | watchdog RED 테스트가 공용 풀 병렬도 1인 머신에서는 옛 코드도 통과시킨다 | 이 환경(병렬도 > 1)에서는 RED가 실제로 실패했다 |
|
||||
| RR4-03-02 | runbook의 Redis 기록 삭제가 "확인 뒤 지우기" 두 명령이다(사이에 상태가 바뀔 수 있음) | 운영자가 수동으로 쓰는 절차. 원자 스크립트로 바꾸면 닫힌다 |
|
||||
| RR4-03-03 | (이전부터) gRPC는 회복 필요 실패를 로그에 남기지 않아 digest 찾기를 따라 할 수 없다 | gRPC는 optional 빌드 |
|
||||
| RR4-03-04 | watchdog 스레드는 한 번 생기면 프로세스 끝까지 남는다. 수명이 Javadoc에 없다 | 데몬 스레드 하나 |
|
||||
|
||||
### 13.1 이 리뷰 전체에서 남은 것
|
||||
|
||||
- **소유자 일**: Gitea repo의 Actions와 runner를 켠다(`has_actions: false` — workflow가 한 번도 돈 적 없다). 브랜치 `refactor/maturity-review-2026-11`의 PR·main 병합을 정한다(아직 PR 없음). 기본값으로 정한 결정을 확인한다: 4·9.1·10·12절 "결정" 칸 — 특히 lease 뒤 늦게 끝난 첫 시도의 결과를 버리는 것, workflow 명령에 `working-directory`가 필요해진 것, `failure-retention ≥ replay-ttl` 기동 검사를 넣지 않은 것.
|
||||
- ~~**게이트 밖**: `spotbugsTestFixtures`는 `01a8a2a70`부터 실패하던 task이고, 잠금 대기 검사기의 정규식 경고가 15건이다.~~ → 14절에서 고쳤다.
|
||||
- **Minor**: 위 7건.
|
||||
|
||||
## 14. 실패한 채 방치된 테스트 코드 정적 분석 (2026-11-04)
|
||||
|
||||
13.1절의 "게이트 밖" 항목을 사용자가 고치라고 했다. 조사해 보니 `spotbugsTestFixtures` 하나가 아니었다.
|
||||
|
||||
- **무엇이 있었나**: `qualityCheck`는 `spotbugsMain`(운영 코드)만 돈다. main 밖 source set(test, testFixtures, integrationTest, systemTest, architectureTest 등)의 SpotBugs 태스크 111개(main 빌드 100, optional 11)는 어느 게이트에도 없었다. 전부 돌려 보니 **53개가 실패**, 발견 300건이었다. 그중 2개는 분석 classpath에 없는 클래스 때문에 분석 자체가 불완전했다.
|
||||
- **원인**: 태스크는 플러그인이 source set마다 자동으로 만들지만, 게이트는 main만 묶었다. 아무도 돌리지 않으니 깨진 것을 아무도 못 봤다.
|
||||
|
||||
고친 것:
|
||||
1. **게이트에 넣었다**: leaf마다 `testQualityCheck`(main·jmh 밖 SpotBugs 전부). main 빌드는 `mainCheck`(`qualificationCheck`), optional 빌드는 `ci`(main 단계가 없고 11개라 짧다). PR 게이트 `ci`에 넣지 않은 이유: 테스트 코드는 배포되지 않고, 전체 실행이 `ci`만큼 걸린다.
|
||||
2. **테스트용 제외 목록** `src/config/spotbugs/exclude-test.xml`: 패턴 전체 제외는 이유가 모든 테스트 클래스에 성립하는 것만 — FindSecBugs 보안 범주(입력을 테스트가 쓴다), 내부 상태 노출(fake는 상태를 일부러 보여 준다), 생성자 예외(finalizer 공격 대상이 아니다), 반환값 null 역참조(NPE가 곧 테스트 실패), 아키텍처 위반 fixture 패키지(결함이 목적). 나머지는 클래스·메서드로 좁힌 Match에 이유를 달았다(30건).
|
||||
3. **코드로 고친 것 24건**: `CountDownLatch.await(timeout)` 반환값을 버려 시간 초과에도 다음 단계로 가던 동시성 테스트 7건(이제 단언), 공유 변수 비원자 쓰기·불일치 동기화 8건, 만료 없는 키에서 NPE가 나던 Redis fake `fingerprint`, 닫지 않던 `Statement`, `SQLException`을 삼키던 upsert 테스트 등. 아무도 쓰지 않던 web-fileserver 테스트 helper 2개(`CountingDataBuffer*`, 쓰던 테스트가 `6d27356e`에서 지워짐)는 지웠다.
|
||||
4. **분석 classpath**: 모든 SpotBugs 태스크가 그 source set의 runtime classpath를 aux로 받고, 분석이 불완전하면 실패한다(운영 코드에만 있던 검사). 처음 구현은 SpotBugs 플러그인이 나중에 생긴 source set의 태스크를 등록하면서 classpath를 덮어써 testFixtures에 닿지 않았다. 수정 에이전트가 찾았고, 설정을 평가 뒤에 등록하게 고쳤다(그 에이전트가 우회로 넣은 `testFixturesCompileOnly` 의존성은 되돌렸다).
|
||||
|
||||
파생 서비스 영향: 자기 테스트 코드의 SpotBugs 발견이 `mainCheck`를 막는다(업그레이드 안내 B-40, 반드시 할 일 14).
|
||||
|
||||
### 14.1 게이트 (2026-11-04, 공유 잠금, 첫 실행 모두 통과)
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|
||||
|---|---|---|---|
|
||||
| `ci` | rc=0 | 6분 34초 | 4.17 |
|
||||
| `verifyStrictLaneStages --dry-run` (주 빌드 / optional) | rc=0 / rc=0 | 11초 / 3초 | 15.00 / 13.96 |
|
||||
| `mainCheck` (이제 `testQualityCheck` 100개 포함) | rc=0 | 8분 33초 (전에는 3분 10초) | 13.96 |
|
||||
| `:integrationCheck` | rc=0 | 14분 30초 | 12.52 |
|
||||
| `-p optional-platforms ci integrationCheck performanceCheck` (`ci`가 `testQualityCheck` 포함) | rc=0 | 1분 32초 | 2.25 |
|
||||
| `:performanceCheck` | rc=0 | 22초 | 15.94 |
|
||||
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 3초 | 12.77 |
|
||||
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 12.23 |
|
||||
|
||||
고친 테스트의 컨테이너 lane은 수정 에이전트가 고친 클래스만 따로 돌렸다(`jpaPlatformContractTest` 9, `jpaPlatformFailureTest` 2, `postgresqlDistributedLockIntegrationTest` 6, `posterImageMigrationTest` 10, redis-sdk standalone `redisTopologyTest` 14). `mainCheck`가 5분 넘게 길어진 것은 이 단계의 비용이다.
|
||||
|
||||
## 15. 소유자 결정 반영 r8 (2026-11-04)
|
||||
|
||||
PR #1을 만든 뒤 사용자가 묶음이 기본값으로 정한 세 가지를 다시 물었다. 따져 본 결과와 소유자 결정:
|
||||
|
||||
| # | 기본값 | 다시 따져 본 것 | 소유자 결정 |
|
||||
|---|---|---|---|
|
||||
| ① | lease가 지난 실행을 다음 claim이 포기(ABANDONED)로 표시해, 늦게 끝난 첫 시도의 결과를 버린다 | "기존 PostgreSQL이 그렇게 한다"는 것 말고 근거가 없었다. executor가 lease를 갱신하지 않아 30s 넘는 정상 요청도 해당된다. "늦은 완료는 기록"도 다시 실행하지 않으므로 똑같이 안전하고, 첫 요청은 자기 결과를 받는다 | **늦은 완료는 기록한다** |
|
||||
| ② | `verifyStrictLaneStages`가 workflow 명령의 빌드를 `working-directory` + `-p`로만 정한다 | 빌드 도구 내부 결정이고 틀려도 거짓 실패 쪽이다. 다만 `cd src && ./gradlew`를 세지 않아 파생 서비스에서 거짓 실패가 난다 | **같은 셸의 `cd <상대 경로>`도 따라간다** |
|
||||
| ③ | `failure-retention < replay-ttl`을 기동에서 막지 않는다(주석 경고뿐) | 효과 불명 실패의 중복 방지 기간이 조용히 짧아진다. "위험은 코드에 드러나야 한다"에 어긋나고, `replay-ttl < lease` 기동 실패와 같은 종류다 | **기동을 실패시킨다** |
|
||||
|
||||
| 묶음 | 상태 | 검증 (에이전트) | 처리 내용 | 결정·남은 것 |
|
||||
|---|---|---|---|---|
|
||||
| r8-a 멱등성 | 완료 | application-core·composition:idempotency·persistence-jpa·cache-redis·redis-runtime `check`·`testQualityCheck`, PG 멱등성 계약 25/25, `postgresqlIdempotencyIntegrationTest` 8/8, `redisContainerContractTest` 64/64, architectureCheck, verifyEnvKeys, documentContractTest | ① lease 지난 EXECUTING을 claim이 만나면 기록을 바꾸지 않고 `RecoveryRequired`(PG `abandonExpiredExecution` 삭제, Redis CLAIM·command fake 같게). 주인의 늦은 `complete`·`markFailed`는 기록, 다음 claim은 재생(RED 실 PG 5·실 Redis 6·fake 2·PG 통합 1). 공유 계약의 "늦은 complete 거절" 케이스를 반대로, 시간 케이스 6개 추가. ③ `IdempotencySettings`가 `failure-retention < replay-ttl`이면 기동 실패(RED 2) | `renew`: 이미 끝난 lease는 두 저장소 모두 거절(Redis만 받던 것을 PG에 맞춤). `inspect`: lease 지난 남의 실행은 `ABANDONED`로 보고. runbook: lease가 지났어도 `EXECUTING` 기록은 지우지 않는다(지우면 늦은 완료가 사라지고 같은 키가 다시 실행된다). 오케스트레이터가 `http-contract.md` 표의 `IDEMPOTENCY_RECOVERY_REQUIRED` 행("재전송도 안전하지 않다")을 이 동작에 맞게 고쳤다. 남음: CLAIMED → 실행 시작에서 PG는 lease를 보고 Redis는 보지 않는다(새로 본 것, 고치지 않음) |
|
||||
| r8-b workflow `cd` | 완료 | `-p build-logic check javadoc` 131, 두 빌드 verifyStrictLaneStages, 실제 workflow 15개의 명령 65개가 이전 판독과 같음, workflow 13개를 `cd` 모양으로 바꾼 실험(통과)과 `cd "$GITHUB_WORKSPACE/src"` 실험(이유를 대며 실패) | ② `working-directory` → 같은 셸의 최상위 `cd <상대 경로>`(혼자 한 줄, `;`, `&&`) → `-p` 순서로 빌드를 정한다(RED 단위 3·TestKit 2). 읽을 수 없는 이동(`$VAR`, `-`, `~`, 절대 경로, `pushd`, 서브셸·조건문 안, `||`·`|`) 뒤의 명령은 이유를 대며 세지 않는다 | 남음(이전부터, 고치지 않음): 실패를 막지 못하는 명령도 실행으로 센다 — `./gradlew ci || true`, `./gradlew ci | tee log`, `if ./gradlew ci; then`. 거짓 통과다 |
|
||||
|
||||
### 15.1 게이트 (2026-11-04, 공유 잠금, 첫 실행 모두 통과)
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|
||||
|---|---|---|---|
|
||||
| `ci` | rc=0 | 6분 26초 | 3.17 |
|
||||
| `verifyStrictLaneStages --dry-run` (주 빌드 / optional) | rc=0 / rc=0 | 10초 / 3초 | 12.86 / 10.84 |
|
||||
| `mainCheck` | rc=0 | 8분 20초 | 10.84 |
|
||||
| `:integrationCheck` | rc=0 | 14분 52초 | 10.34 |
|
||||
| `-p optional-platforms ci integrationCheck performanceCheck` | rc=0 | 1분 46초 | 4.01 |
|
||||
| `:performanceCheck` | rc=0 | 27초 | 22.93 |
|
||||
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 4초 | 20.00 |
|
||||
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 18.72 |
|
||||
|
||||
### 15.2 확인 리뷰 (`70fb80bf`만)
|
||||
|
||||
리뷰어 1명([round5/review.md](round5/review.md)): Critical 0, **Important 0**, 회귀 0, Minor 9(7건은 이 커밋, 2건은 이전부터). 결정 ①②③이 코드·공유 계약·문서에 결정대로 들어갔고, lease가 지난 `EXECUTING`을 다시 실행하는 경로는 남지 않았으며, PostgreSQL과 Redis가 같은 판정을 한다.
|
||||
|
||||
Minor 중 RR5-01-01(`IDEMPOTENCY_RECOVERY_REQUIRED`의 클라이언트 안내가 `http-contract.md` 표·매뉴얼 05 표·runbook에서 서로 다름 — 표는 "새 키 금지", runbook은 "효과가 없으면 새 키")은 오케스트레이터가 이번 커밋에서 만든 모순이라 바로 고쳤다: 세 문서와 프론트 인계 문서를 "자동 재시도 안 함, 같은 키 재전송은 안전(서버가 판정하고 다시 돌리지 않음), 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키"로 맞췄다. 나머지 Minor 8건은 11.1절 결정대로 기록만 한다(round5/review.md) — 그중 RR5-02-01은 heredoc·호출하지 않은 함수·여러 줄 문자열 안의 `cd`도 따라간다는 것으로, 이 repo에서는 그 step이 실패해 조용한 거짓 통과는 아니다.
|
||||
|
||||
## 16. 남은 결함 전부 수정 r9 (2026-11-05)
|
||||
|
||||
소유자 지시: "보고할 때 남은 문제가 없어야 한다." 11.1절의 "Minor는 기록만" 결정을 거두고, 리뷰가 찾고 기록만 했던 것(13절 Minor 7건, 15.2절 Minor 8건, 10·12·15절 "남음", 원래 리뷰 16.3절)을 영역 묶음 4개가 `c508b1ba`에서 고쳤다. 고치다 새로 찾은 영역 안의 결함도 고쳤다.
|
||||
|
||||
| 묶음 | 항목 | 처리 | 검증 (에이전트) | 결정 |
|
||||
|---|---|---|---|---|
|
||||
| r9-a core·inbound | RR4-01-01, RR4-01-02, `graphql..` fixture, 원래 리뷰 16.3, RR4-03-03 | 규칙 대상을 `@SystemCaller`와 그 프로젝트 상위 타입으로 넓히고 `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(프로젝트 밖 타입 구현 금지)를 더했다(RED). `@Configuration`·`@AutoConfiguration`은 사용자 전송이 아니다(RED 2). graphql-java를 architectureTest 컴파일 전용으로 넣어 `graphql..` 항목을 fixture로 증명. 템플릿 패키지 목록: `application-core/CLAUDE.md` 표를 정본으로, `TemplatePackageOwnership`과 소유 leaf를 대조하는 문서 대조 테스트(RED 3). shared-contract `ServerFailureLog`로 web·GraphQL·gRPC·STOMP가 같은 실패 로그 줄을 쓴다(RED gRPC 4·GraphQL 2). 새로 찾아 고친 것: gRPC가 `INTERNAL_ERROR` 실패를 아무 데도 남기지 않음, STOMP가 persistence 실패의 SQL 원인까지 로그에 씀 | 9 leaf `check`·`qualityCheck`·`testQualityCheck`, architectureTest 216, documentContractTest 65, architectureCheck, verifyDependencyLocks, `-p optional-platforms ci`, 전송 qualification lane, systemTest | 규칙으로 막을 수 없는 길(bean 이름 조회, 설정이 함수로 감싸 넘김)과 그 길을 막는 다른 방어를 매뉴얼 07에 적었다. 목록에 넣지 않은 새 템플릿 패키지는 기능 패키지와 구별할 수 없다(한계로 문서화) |
|
||||
| r9-b 멱등성·outbound | README 15 남음(CLAIMED → 시작의 lease), RR5-01-02~05, RR5-03-01, RR4-03-01·02·04 | 두 저장소 모두 lease가 지난 CLAIMED의 시작을 `LEASE_EXPIRED`로 거절하고 executor는 503 `IDEMPOTENCY_UNAVAILABLE`(실행 안 됨)로 답한다(RED 실 Redis·실 PG). renew·start 결과 값마다 Javadoc. 포트 Javadoc "먼저 온 보고 하나". 늦은 실패 뒤 다음 claim까지 보는 계약 4건. PostgreSQL 기본 사용 모양(쓰기 트랜잭션 안의 executor)에서는 lease 지난 EXECUTING이 남에게 보이지 않는다는 사실을 문서에 저장소별로. TTL 관계(lease ≤ replay-ttl ≤ failure-retention) 안내. watchdog RED 테스트를 공용 풀 병렬도와 무관하게, runbook의 Redis 기록 삭제를 `EVALSHA` 한 번으로(실 Redis·실 ACL에서 runbook 블록 그대로 실행), watchdog 스레드는 60초 유휴 뒤 끝나고 요청 스레드의 thread-local·class loader를 물려받지 않는다(RED) | 6 leaf `check`·`testQualityCheck`, `redisContainerContractTest` 72, PG 계약 31, `postgresqlIdempotencyIntegrationTest` 10, `httpClientPerformanceTest` 5, architectureCheck, verifyEnvKeys, documentContractTest | 애플리케이션 Redis 계정은 ACL이 `EVAL`을 막아 runbook은 `SCRIPT LOAD`+`EVALSHA`. 시작 거절은 아무것도 실행되지 않았으므로 503 |
|
||||
| r9-c persistence | RR4-02-01, gRPC 버전 정규식 복사본, V21 주석 | 잠금 대기 검사기가 Flyway 11.14.1이 스스로 트랜잭션 밖에서 돌리는 문장 목록을 쓰고(실 PG 21개 판정 일치), `VACUUM FULL`은 마이그레이션에서 거부(RED 25). 버전 판정 정본 `VersionedMigrationFiles` 하나를 grpc 빌드가 Sync 태스크로 가져와 컴파일하고 복사본을 지웠다(RED 2). V21 주석은 `bbe944bd`에서 이미 고쳐져 있었다. 새로 찾아 고친 것: 가이드의 "CONCURRENTLY는 Flyway가 트랜잭션으로 감싼다" 오류 | persistence-jpa `check` 647, sample `check` 339, `postgresqlMigrationLockWaitIntegrationTest` 28, optional grpc ledger `check`·`integrationTest` 46, architectureCheck 두 빌드, documentContractTest | 버린 대안: 원본 디렉터리를 소스 루트로 직접 추가(Spotless가 프로젝트 밖 파일 거부), 주 빌드 의존, 대조 테스트(정의가 둘로 남음) |
|
||||
| r9-d build-logic | README 15 남음 + RR5-02-02, RR5-02-01, RR5-02-03, `-mx`, httpclient 장애 주입 lane 두 번 실행 | `ShellScript`가 run 스크립트를 bash 문법으로 읽는다. 실패를 막지 못하는 명령(`|| true`, pipefail 없는 `| tee`, `!`, `&`, `echo`, `if`·`while` 조건, 함수 본문, `set +e`, `shell: pwsh`)은 이유를 대며 세지 않는다(RED). heredoc·여러 줄 문자열 안의 `cd`는 데이터(RED). 실패 메시지가 다른 빌드로 읽힌 명령·dry-run·안 센 이유를 보여 준다(RED). 짧은 플래그 묶음은 Gradle 9.0 파서대로(TestKit으로 Gradle 동작 고정). 장애 주입 lane을 `mainCheck`에서 뺐다(`integrationCheck`가 main에서 돌아 두 번 돌릴 근거가 사라졌다). 새로 찾아 고친 것: `$(( ))` 파싱, `help --task ci`, `${{ }}` 안 공백, `-x=b` | `-p build-logic check javadoc` 146, 두 빌드 verifyStrictLaneStages, 실제 workflow 판독 전후 같음, 변형 실험 8, run 스크립트 253개 파싱 실패 0 | 서브셸·`eval`·`source` 안의 `cd` 뒤 명령과 `|| exit 1`은 세지 않는다(거짓 실패 쪽) |
|
||||
|
||||
합칠 때 오케스트레이터: 업그레이드 안내를 r9-a·r9-b와 손으로 합쳤다(5절에 세 묶음이 각자 더한 행을 모두 살림, B-41은 r9-b).
|
||||
|
||||
### 16.1 합친 뒤 게이트에서 드러난 것
|
||||
|
||||
첫 `ci`가 httpclient `ClientRuntimeRegistryTest.closingTheRegistryReleasesEveryGenerationAndLeavesNoThread` 하나로 실패했다(부하 16, r9 변경과 무관한 기존 코드). 원인 둘:
|
||||
- `ClientRuntimeRegistry.close()`는 drain scheduler의 `awaitTermination`만 기다렸다. 실행기는 worker 스레드 안에서 종료를 알린 뒤 그 스레드가 끝나므로, 부하가 높으면 `close()`가 돌아왔을 때 스레드가 아직 살아 있다. "스레드를 남기지 않는다"는 약속이 타이밍에 기댔다.
|
||||
- 런타임 하나가 닫기를 거부하면 `close()`가 scheduler를 멈추기 전에 예외를 던져 drain 스레드가 계속 살았다.
|
||||
|
||||
고친 것: scheduler가 만든 스레드를 기억해 `close()`가 종료를 기다린 뒤 그 스레드를 join한다(마감 안에 안 끝나면 실패). 런타임이 닫기를 거부해도 scheduler를 먼저 멈추고 예외는 그 뒤에 던진다. RED: 새 테스트 `aRuntimeThatRefusesToCloseStillLeavesNoDrainThread`가 옛 코드에서 실패(기존 테스트도 함께 실패). GREEN: httpclient `check`·`testQualityCheck`·`httpClientFailureInjectionTest`·`httpClientPerformanceTest`, 그 테스트 클래스 5회 반복 통과.
|
||||
|
||||
### 16.2 게이트 (2026-11-05, 공유 잠금)
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|
||||
|---|---|---|---|
|
||||
| `ci` 첫 실행 | 실패 — httpclient `ClientRuntimeRegistryTest` 1건(16.1절) | 8분 48초 | 16.28 |
|
||||
| `ci` 재실행(16.1절 수정 뒤) | rc=0 | 1분 22초(나머지 캐시) | 17.54 |
|
||||
| `verifyStrictLaneStages --dry-run` (주 빌드 / optional) | rc=0 / rc=0 | 19초 / 4초 | 20.30 / 18.13 |
|
||||
| `mainCheck` | rc=0 | 10분 59초 | 17.48 |
|
||||
| `:integrationCheck` | rc=0 | 20분 11초 | 14.92 |
|
||||
| `-p optional-platforms ci integrationCheck performanceCheck` | rc=0 | 2분 16초 | 15.57 |
|
||||
| `:performanceCheck` | rc=0 | 36초 | 24.43 |
|
||||
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 5초 | 19.00 |
|
||||
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 18.44 |
|
||||
|
||||
`mainCheck`·`integrationCheck`는 16.1절 수정 전 트리에서 돌았다. 그 수정은 httpclient만 바꿔서 httpclient `check`·`testQualityCheck`·`httpClientFailureInjectionTest`·`httpClientPerformanceTest`를 따로 다시 돌렸다(통과).
|
||||
|
||||
## 17. r9 확인 리뷰 round6과 수정 r10 (2026-11-05)
|
||||
|
||||
`45d2a478`(r9)을 영역 4개로 나눠 리뷰했다(`round6/01~04`). 결함 25건(Important 2, Minor 23). 01의 RR6-01-07과 02의 RR6-02-03은 같은 runbook 문장이라 한 번 고쳤다. 영역 묶음 4개가 `45d2a478`에서 고쳤고, 고치다 새로 찾은 결함도 고쳤다.
|
||||
|
||||
| 묶음 | 리뷰 결과 | 처리 | 결정 |
|
||||
|---|---|---|---|
|
||||
| r10-01 core·inbound | Important 1(RR6-01-01 회귀), Minor 8 | 설정·그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다(A1 `RouterFunction`·A2 `DataFetcher` 위반 fixture, A5 허용 fixture). `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 예외를 빼고 record·enum은 언어가 주는 상위 타입만 허용(`Runnable`을 구현한 record는 여전히 잡힘). gRPC는 `isCancelled()`일 때만 로그를 건너뛰고, 던진 raw status는 로그에 붙이지 않는다. `ServerFailureLog.refusedArgument`로 네 전송이 IAE를 같은 WARN 한 줄로 남긴다(GraphQL·gRPC 동작 변경). runbook 문구, GraphQL carrier 테스트. 이전부터의 `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`를 `dev.caskeleton.shared..` 대상·정확한 12개 목록으로 고치고 "KNOWN DEFECT" 주석을 지웠다(업그레이드 B-42) | 요청 처리기 타입 목록은 리뷰어 예보다 넓게(설정에 중첩된 `@RestController`도 잡힘) |
|
||||
| r10-02 멱등성·outbound | Minor 5 | 같은 attempt로 다시 claim하면 lease가 지난 `CLAIMED`와 `FAILED_RETRYABLE`을 넘겨받는다(Redis·PG·command fake·in-memory fake). 새로 찾아 고친 것: 옛 revision을 든 늦은 시작이 Redis에서 `ALREADY`를 받아 이중 실행됨 → 기록 revision이 핸들 revision + 1일 때만 `ALREADY`. PG의 다른 핸들 시작 답을 Redis와 같게(`NOT_OWNER`/`NOT_CLAIMED`). 같은 attempt의 `FAILED_RETRYABLE`·`ABANDONED` 답이 저장소마다 달랐던 것, in-memory fake가 fingerprint 검사 전에 기록을 넘겨준 것. command fake 위 계약이 시계를 움직인다(skip 17 → 0), fixture에 key TTL, 계약과 겹친 adapter 손 사본 20건 삭제. 503 뜻을 web README·인계 표에, 매뉴얼 05 첫 문장을 저장소별로 | RR6-02-01은 (a)안: 문서와 503 `retryable`이 약속하는 동작에 코드를 맞춘다. 같은 attempt를 두 호출이 **동시에** 쓰는 것은 attempt 정의(한 번의 순차 송신·재시도) 밖이라 저장소가 가려내지 않는다 — 결함이 아니라 호출자 계약으로 Javadoc·매뉴얼 05에 적었다 |
|
||||
| r10-03 persistence | Important 1(RR6-03-01, 이전부터), Minor 4 | Flyway PostgreSQL 잠금을 세션 수준으로: module-defaults `spring.flyway.postgresql.transactional-lock: false`, 직접 만드는 Flyway는 `FlywaySchemaPolicy.configure()` 하나로(messaging은 persistence-jpa에 의존할 수 없어 같은 값 사본 + 대조 테스트), 직접 `Flyway.configure()`를 부르면 실패하는 ArchUnit 규칙, 실 PG IT(옛 설정 30초 정지 4/4 → 1.2초). 검사기의 `E'…\'…'` 판독과 중첩 주석, `PostgreSQLParser` 트랜잭션 밖 패턴을 PR `ci`에서 고정, IT 대조 목록 +6, ledger Spotless에서 Sync 사본 제외, "Flyway는 늘 트랜잭션으로 감싼다" 설명 정정. 새로 찾아 고친 것: 동시 인덱스 검사기가 `UNIQUE`·`REINDEX (CONCURRENTLY)`를 못 찾음 | RR6-03-01은 session-level 잠금(Flyway가 이 문제로 둔 공식 옵션). 버린 대안: CIC를 마이그레이션에서 금지하고 운영 절차로(큰 테이블 인덱스 추가가 번거로워짐). 전제: Hikari 직접 연결 — transaction-mode PgBouncer 뒤에서는 세션 잠금이 깨진다(가이드에 적음) |
|
||||
| r10-04 build-logic | Minor 6 | 작업 없이 끝나는 Gradle 옵션(`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 포함)을 세지 않는다. `GradleCommandLineTest`가 판독기 옵션 표를 실행 중인 Gradle `--help`와 대조(9.2.0으로 돌리면 `task-graph`로 실패). 조건부 `exit 0`·`exec`·`set -n`·함수 안 exit·EXIT/ERR trap 뒤 명령, Windows일 수 있는 `runs-on`의 기본 셸, 요청형 trigger만 있는 workflow, 세는 호출자가 없는 `workflow_call`, 조건부 job을 `needs`로 기다리는 job을 세지 않는다. 세지 않는 이유를 셋(실패를 막지 못함 / 돌지 않을 수 있음 / 판독기가 읽지 않음)으로 나눠 메시지와 문서 5곳에 같은 말로 | 이 repo workflow에서 세는 명령 48개는 수정 전후 같다 |
|
||||
|
||||
합칠 때: 네 묶음 모두 `45d2a478` 기준이고 충돌 없이 적용됐다(92파일). 업그레이드 안내의 새 행 번호는 겹치지 않는다.
|
||||
|
||||
### 17.1 검증 위치 변경
|
||||
|
||||
2026-11-05 소유자 지시: 노트북에서 Gradle·Docker를 돌리지 않는다. 지시 전에 각 묶음이 로컬에서 RED·GREEN과 leaf `check`를 돌렸고, 지시 뒤의 변경(01의 A5 fixture 재작성, 03의 동시 인덱스 검사기 GREEN)과 합친 트리 전체는 desktop(`~/workspace/clean-architecture-backend-template`)에서 git pull 뒤 검증한다. 결과는 17.2절.
|
||||
|
||||
### 17.2 게이트 (2026-11-05, desktop)
|
||||
|
||||
대상 `2c692554`. desktop(12코어·31GB)에서 다른 빌드 없이 차례로 돌렸다. PR workflow가 같이 돌리는 `verifyDependencyLocks`·sample `check`·`--warning-mode=fail`도 넣었다. 모든 게이트가 첫 실행에서 통과해 고친 것은 없다(17.3절 없음).
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|
||||
|---|---|---|---|
|
||||
| `:ci :verifyDependencyLocks --warning-mode=fail` | rc=0 | 5분 42초 | 2.65 |
|
||||
| `:sample-portfolio:check :sample-portfolio:qualityCheck` | rc=0 | 32초 | 11.79 |
|
||||
| `verifyStrictLaneStages --dry-run` (주 빌드 / optional) | rc=0 / rc=0 | 10초 / 3초 | 9.49 / 8.41 |
|
||||
| `:mainCheck --warning-mode=fail` | rc=0 | 8분 8초 | 8.05 |
|
||||
| `:integrationCheck` | rc=0 | 17분 10초 | 8.92 |
|
||||
| `-p optional-platforms ci integrationCheck performanceCheck` | rc=0 | 1분 27초 | 1.09 |
|
||||
| `:performanceCheck` | rc=0 | 26초 | 9.30 |
|
||||
| `:releaseCheck -PgitRevision=2c692554cb02b237b41f064a81ab7897d2cdcae6` | rc=0 | 3초 | 7.76 |
|
||||
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | 4초 | 7.62 |
|
||||
| `-p build-logic check javadoc` (게이트 전) | rc=0, 테스트 162 | 47초 | 1.49 |
|
||||
|
||||
17.1절의 미확인 항목:
|
||||
|
||||
- RED, 01 A5 최종 fixture: desktop 임시 worktree(`45d2a478`에 r10-01의 `ArchitectureViolationFixtureTest`와 새 fixture 7개만 얹음)에서 `ArchitectureViolationFixtureTest`가 예상한 6건으로 실패했다 — A1 `RouterFunction`·A2 `DataFetcher`(위반 0건), async timeout으로 바꾼 A5(`$1`이 handler에 의존), 중첩 record·enum·예외, record handler, `Runnable` record(잡히지만 메시지가 `Runnable`만 대지 않음). 가드 `aRequestHandlerNestedInAConfigurationThatCallsASystemCallerIsCaught`는 통과. worktree는 지웠다.
|
||||
- RED, 02 경로 1(넘겨받기 전 핸들의 늦은 시작): `2c692554`에서 TRANSITION 시작 revision 검사만 되돌리면(command fake와 Lua 둘 다) command fake 계약과 실 Redis 계약이 37개 중 같은 2건으로 실패했다 — `aLateStartThroughTheHandleBeforeTheTakeoverIsRefusedAsAStaleOwner` "expected NOT_OWNER but was ALREADY_STARTED_SAME_OPERATION", `theSameAttemptStartingAnExecutionItAlreadyStartedIsToldItIsNotClaimed` "expected NOT_CLAIMED but was ALREADY_STARTED_SAME_OPERATION". 되돌린 것은 지웠다.
|
||||
- GREEN: 03 동시 인덱스 검사기(`ConcurrentIndexMigrationInspectorTest`)와 손 포맷(persistence-jpa `spotlessCheck`), 01 `architectureTest` 228·`spotbugsArchitectureTest`(A5 최종본), optional ledger `check`를 게이트 전에 따로 돌렸다(1분 50초, rc=0).
|
||||
- 게이트 안에서 확인한 보고서 항목: `:app-bootstrap:documentContractTest` 65, `verifyEnvKeys`, `verifyJpaApiSurface`, `redisContainerContractTest` 78, `jpaPlatformContractTest` 407, `jpaPlatformMigrationTest` 45, 새 lane `postgresqlConcurrentIndexMigrationIntegrationTest` 4(`integrationCheck`에서 실행), `postgresqlMigrationLockWaitIntegrationTest` 36, `postgresqlNotificationSchemaActivationIntegrationTest` 8, `postgresqlIdempotencyIntegrationTest` 10, `messagingInboxRedeliveryIntegrationTest` 3, app-bootstrap `integrationTest` 10(`PostgreSqlIdempotencyProviderIntegrationTest` 포함), sample `integrationTest` 63(`SampleIdempotencyReplayIntegrationTest`·`SampleMigrationStreamIsolationTest` 포함), ledger `integrationTest` 46. 모두 실패 0. in-memory fake 계약의 skip 19는 시간 케이스(설계).
|
||||
- 다시 돌리지 않은 것: 각 묶음이 로컬에서 이미 확인한 RED(01의 gRPC·STOMP·GraphQL·shared-contract·shared 규칙, 02 표, 03, 04). r10-03 보고서가 적은 `:adapter:outbound:persistence-jpa:documentContractTest`는 없는 태스크다(그 lane은 app-bootstrap에만 있다).
|
||||
@@ -0,0 +1,314 @@
|
||||
# 01 core·application·inbound 재리뷰 (2026-11-03, 2차)
|
||||
|
||||
경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
- 리뷰 범위: Base `7ef8d0b4` → Head `bbe944bd`(커밋 1개) 중 아래 pathspec. 152파일, +5,757 −692.
|
||||
```text
|
||||
src/domain-core src/shared-contract src/application-core src/application-fileserver
|
||||
src/application-objectstorage src/composition src/adapter/inbound src/grpc src/grpc-advanced
|
||||
scripts docs/manual docs/web
|
||||
```
|
||||
- 맡은 1차 재리뷰 발견: RR-01-01~10, RR-02-01~08, RR-07-01, RR-07-06, RR-04-04(=RR-01-05).
|
||||
- 이 문서의 새 발견 ID는 `RR-01-11`부터다. 1차의 `RR-01-01~10`과 겹치지 않게 이어 붙였다.
|
||||
- 읽은 방식: diff가 커서 여러 번에 나눠 직접 읽었다(하위 에이전트 없음).
|
||||
1. application-core main diff 전부(멱등성 executor·예외, `IntegrationEventDraft`·`IntegrationIdentity`,
|
||||
`SubmitDurableOperationUseCase`, outbox 포트·relay·`OutboxPublishAttempt`, `SystemInvoked`).
|
||||
2. application-core testFixtures 중 멱등성 저장소 계약, outbox 순서 계약·fake, `OverlappingWrites`,
|
||||
`DirectTransactionPort`, 캐시 계약 추가분.
|
||||
3. composition: service-runtime(`PermissionEnforcementGuard`), outbox-relay(조립·지표·설정),
|
||||
idempotency(`IdempotencySettings`), fileserver-platform(move 조립).
|
||||
4. web main diff 전부(`EnvelopeErrorController`, `HttpStatusErrorCodes`, `EnvelopeBodyAdvice`,
|
||||
`SecurityConfig`, `WebMvcPlatformAutoConfiguration`, `RetryAfterAdvisor`)와 새 시스템 테스트·testkit.
|
||||
5. GraphQL scorer diff와 새 union·interface 테스트. 같은 leaf의 page 크기 계산 복사본을 grep으로 전수 확인.
|
||||
6. gRPC: `GrpcClaimToken`, 포트, JPA adapter·repository·entity·V003, in-memory fake, 공유 계약 diff,
|
||||
interceptor·decision, 기동 검증기.
|
||||
7. application-fileserver: move use case, `FileAccessSubject.owns`, 새 계약 6개의 케이스 목록과 상속 관계,
|
||||
쿼터 fake.
|
||||
8. 생성 명령 템플릿·탐침·`verify-feature-scaffold.sh` diff, 매뉴얼 04·05·06·07·09 diff, `docs/web/http-contract.md` diff.
|
||||
- 범위 밖에서 확인용으로 읽은 것: `ApplicationBoundaryArchitectureTest`(D4·새 ArchUnit 2개),
|
||||
`RequiresPermissionAuthorizationManager`, `adapter/inbound/messaging/README.md`·통합 테스트의 handler 모양,
|
||||
Redis 멱등성 Lua(`IdempotencyScripts.java`)와 adapter, `PostgreSqlIdempotencyStore`와 그 PG 테스트,
|
||||
`JpaFileQuota`·`JpaQuotaReclaim`(호출자 트랜잭션 요구 여부), `docs/registries/error-codes.yaml` diff,
|
||||
ADR-GRPC-004 diff.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → Critical/Important/Minor → Declined → Assessment), 실제 심각도로 분류, 읽지 않은 코드에 판정 금지 | 문서 양식 전체. 발견마다 "고치는 법"과 4절 결정을 코드로 대조 |
|
||||
| `clean-architecture` | 의존은 안쪽으로, 포트는 안쪽이 소유, composition root(Main)가 조립, 경계에서 framework 격리 | `@SystemInvoked` 조립 규칙이 시스템 호출자(relay·이벤트 소비자)를 composition에서 조립할 수 있게 두는지, web leaf가 application-core 상수를 읽는 방향, 계약 키트 위치 |
|
||||
| `api-and-interface-design` | 일관된 오류 의미, Hyrum's Law(관찰되는 동작이 계약), 멱등 키의 세 결과(성공·실패·불명)와 in-flight 중복 처리, 계약과 구현의 일치 | `IDEMPOTENCY_COMPLETION_UNKNOWN`이 약속한 재전송 판정을 저장소 구현이 지키는지, `/error` 응답 status·모양, gRPC·GraphQL wire 변경 표시 |
|
||||
| `security-and-hardening` | 인가는 모든 요청에서, 오류 본문에 내부 정보 금지, 자원 상한(DoS), 숨은 우회 경로 | ERROR 디스패치 허용이 새 노출을 만드는지, `@SystemInvoked` 우회 경로, GraphQL union 아래 page 상한, 파일 move 쿼터 우회 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
| 명령 | 결과 |
|
||||
| --- | --- |
|
||||
| `git diff --stat / --shortstat 7ef8d0b4..bbe944bd -- <pathspec>` | 152파일 +5,757 −692 |
|
||||
| `git grep`으로 `@SystemInvoked` 사용처, `new PublishPendingOutboxEventsUseCase`, `effectivePageSize`, `sendError(`, `SecurityFilterChain`, `extends <각 fileserver 계약>` 전수 확인 | 아래 표·발견의 근거 |
|
||||
| `git worktree add --detach <scratchpad>/rr2-01 bbe944bd` 후 `IdempotencyStoreContract`에 탐침 메서드 1개 추가, `flock … ./gradlew :adapter:outbound:cache-redis:redisContainerContractTest --console=plain -i` | 첫 실행은 탐침의 Error Prone `ReturnValueIgnored`로 컴파일 실패(탐침 코드 문제). 고친 뒤 `BUILD SUCCESSFUL in 44s`, 출력 `RR2-PROBE … duringLease=InProgress afterLease=TakenOverClaimed`(RR-01-11) |
|
||||
| `git worktree remove --force <scratchpad>/rr2-01` | 탐침과 함께 삭제 |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 전체 게이트는 다시 돌리지 않았다. 재리뷰 README 7절 결과를 읽기만 했다.
|
||||
- gRPC ledger의 PG lane(`JpaGrpcOperationLedgerContractIT`)은 다시 돌리지 않았다. 동시 commit 경쟁은 그 lane이
|
||||
7절 게이트(`-p optional-platforms … integrationCheck`)에서 통과했다는 기록과 SQL을 읽은 것에 기댄다.
|
||||
- Jetty의 오류 디스패치, 관리 포트를 따로 둔 배포의 오류 처리는 보지 않았다.
|
||||
- application-core의 outbox·messaging 변경(RR-05-xx, 06-10~14)은 diff를 읽었지만 판정은 05 영역 리뷰어 몫으로 두었다
|
||||
(「Declined to judge」).
|
||||
- sample-portfolio(데모 체인의 ERROR 디스패치 허용, `WorkLogReservedPayload`)는 pathspec 밖이라 grep으로 수정 여부만 봤다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- `@SystemInvoked` 빈은 advisor가 있어도 기동을 멈춘다. 검사가 advisor 검사보다 먼저다
|
||||
(`src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java:57-70`). 테스트가 "advisor가 있어도
|
||||
실패"를 고정한다(`PermissionEnforcementGuardTest.aSystemInvokedUseCaseRegisteredAsABeanFailsStartupEvenWithAnAdvisor`).
|
||||
- relay는 여전히 `new`로 조립돼 scheduler에만 들어간다(`src/composition/outbox-relay/.../OutboxRelayAutoConfiguration.java:80`).
|
||||
새 기동 차단이 relay를 막지 않는다.
|
||||
- gRPC ledger의 모든 전이가 `claim_attempt`를 조건에 넣은 UPDATE 한 문장이다
|
||||
(`GrpcOperationLedgerRepository.java` `tryReclaimFailed`·`tryReclaimStale`·`tryMarkCommitted`·`tryMarkFailed`).
|
||||
load-check-save가 사라졌다. 공유 계약에 "옛 owner의 실패 무시"(`GrpcOperationLedgerContract.java:439`)와
|
||||
"동시 commit은 하나만"(`:515`)이 들어가 fake와 PG adapter가 같이 받는다.
|
||||
- claim이 "충돌인데 행이 없음"을 보면 insert를 한 번 더 한다(`JpaGrpcOperationLedger.java:49-62`). 1차의 purge 경쟁이 닫혔다.
|
||||
- GraphQL scorer가 `GraphQLCompositeType`으로 내려간다(`GraphQlDocumentComplexityScorer.java:154,232,265`). union과
|
||||
interface 각각 "중첩 list 곱셈"과 "page 상한 거부"를 테스트한다(`GraphQlDocumentComplexityScorerTest.java:299` 등).
|
||||
- `/error` 응답이 요청에서 아무것도 싣지 않는다(`EnvelopeErrorController.java:60-71`). 실제 Tomcat에서 방화벽 거부
|
||||
경로를 단언하고, 기본 JWT 체인에서 "오류 디스패치는 원래 400, `/error` 직접 호출은 401"을 둘 다 확인한다
|
||||
(`JwtChainErrorDispatchIT`).
|
||||
- status → code 표가 한 곳이다(`HttpStatusErrorCodes.java:18`). 예외 처리기와 오류 컨트롤러가 같은 표를 쓴다.
|
||||
- move의 쿼터 이동이 relocate와 같은 트랜잭션이다(`MoveFileApplicationUseCase.java:92-109`). JPA 쪽 세 포트가 모두
|
||||
호출자 트랜잭션을 요구하므로(`JpaFileQuota.java:39,58,71`, `JpaQuotaReclaim.java:42`) 버전 충돌이면 쿼터도 롤백된다.
|
||||
- 생성 계약에 `inTransaction` hook이 생겼고(`__Feature__RepositoryContract.java.tmpl:41`), 왕복 검사가 "호출자
|
||||
트랜잭션 밖이면 거부하는 저장소"로 계약을 한 번 더 돌린다(`scripts/verify-feature-scaffold.sh:140-161`). 확인할
|
||||
결과 XML 목록도 템플릿에서 만든다(`:102`).
|
||||
- Retry-After 2초가 상수 하나이고(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`), lease가 그 이하면 기동이 실패한다
|
||||
(`IdempotencySettings.java:57`).
|
||||
- 파일 소유자 규칙이 `FileAccessSubject.owns` 하나다(`FileAccessSubject.java:63`). fake와 `RoleBasedFileAccessPolicy`가
|
||||
둘 다 부르고, `FileAccessPolicyPortContract`를 둘 다 상속한다.
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| RR-01-01 | 닫힘 | 템플릿 계약의 모든 호출이 `inTransaction`을 거친다(`__Feature__RepositoryContract.java.tmpl:41` 이하). 탐침 `CallerTransaction__Feature__RepositoryContractTest.java.tmpl`이 트랜잭션 요구 저장소로 계약을 통과시키고, `verify-feature-scaffold.sh:140-161`이 그 결과 XML을 확인한다. 매뉴얼 04장 4단계에 hook 사용을 적었다 |
|
||||
| RR-01-02 = RR-07-01 | 닫힘(결정대로) | 4절 결정 두 가지가 다 들어갔다: 빈이면 기동 실패(`PermissionEnforcementGuard.java:57-70`), inbound adapter 의존 금지 ArchUnit(`ApplicationBoundaryArchitectureTest.java:455-467`). 결정이 만든 새 위험 → RR-01-12 |
|
||||
| RR-01-03 | 닫힘 | 07장(`docs/manual/07-authorization.md:65-89`), 09장(`docs/manual/09-outbox-events.md:56-87`), 06장(`:44-46`) 문장이 코드와 맞다. `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`(`ApplicationBoundaryArchitectureTest.java:475`), `application-core/CLAUDE.md` 표에 두 타입 |
|
||||
| RR-01-04 (+RR-07-06) | 닫힘 | 저장 포트 9개 모두 계약이 있고 fake와 PG 테스트가 각각 상속한다(`extends` grep: ContentReferenceLedger·FileQuotaLedger·RecoveryQueue·StagingUploadLocator·UploadSession·FileMetadata·CleanupQueue). `FileQuotaLedgerContract`가 만료·해제 뒤 확정·연장 거부를 같은 표로 본다. build.gradle 주석도 사실대로 고쳤다 |
|
||||
| RR-01-05 = RR-04-04 | 닫힘 | `MoveFileApplicationUseCase.java:100-109`가 대상 `requireRoom` → 예약·확정 → 출발 회수를 relocate와 한 트랜잭션에서 한다. 테스트 두 개(`FileLifecycleUseCasesTest.java:467,485`). 남은 작은 틈 → RR-01-17 |
|
||||
| RR-01-06 | 닫힘 | 2^53 경우(`CacheRegionContract`), 트랜잭션 밖 거부·롤백 번호 재사용(`OutboxAggregateSequenceContract`), 시간 경우는 시계 없으면 abort(`IdempotencyStoreContract.java:94`). 새로 넣은 겹침 경우의 fake 실행 방식 → RR-01-16 |
|
||||
| RR-01-07 | 닫힘 | `__Feature__Config.java.tmpl:36` `afterName = PersistenceJpaAutoConfiguration` |
|
||||
| RR-01-08 | 닫힘(범위 밖 grep) | `sample-portfolio/.../WorkLogReservedPayload.java:15`가 `IntegrationIdentity.isCanonical`을 부른다 |
|
||||
| RR-01-09 | 닫힘 | `shared-contract/README.md:369-370`, `RuntimeEnvironment.java:32-33`, application-core README 알림 절 정리 |
|
||||
| RR-01-10 | 닫힘 | `verify-feature-scaffold.sh:102-127`이 템플릿의 `*Test.java.tmpl` 전부에서 결과 XML 경로를 만들고 `tests="0"`도 거부한다 |
|
||||
| RR-02-01 | 닫힘 | 위 Strengths. union·interface 아래 곱셈·page 상한 테스트 4개 |
|
||||
| RR-02-02 | 닫힘 | `EnvelopeErrorController` + `SecurityConfig.java:91` ERROR 디스패치만 허용 + `EnvelopeBodyAdvice`가 4xx·5xx를 감싸지 않음. 실 Tomcat·JWT 체인 테스트. 문서와 다른 작은 점 → RR-01-13 |
|
||||
| RR-02-03 | 부분 | 코드 분기(`IdempotencyExecutor.java:251,286`)와 테스트는 들어갔다. 그러나 이 코드를 실제로 내는 저장소는 Redis뿐이고, Redis는 lease가 지난 EXECUTING 기록을 넘겨받아 작업을 다시 돌린다. 계약 문서가 약속한 "lease 뒤 500 RECOVERY_REQUIRED"가 지켜지지 않는다 → RR-01-11 |
|
||||
| RR-02-04 | 닫힘 | 토큰·V003·조건부 UPDATE·계약 케이스(Strengths). `release`만 토큰 밖에 남았다 → RR-01-15 |
|
||||
| RR-02-05 | 닫힘 | `IdempotencySettings.java:57`, `RetryAfterAdvisor`가 같은 상수를 읽는다 |
|
||||
| RR-02-06 | 닫힘 | `GrpcStatusMapperTest`·`GraphQlWireErrorMapperTest` 케이스, 두 README, registry `compatibility_impact: behavior-change` |
|
||||
| RR-02-07 | 닫힘 | 검증기 문구(`GrpcPlatformStartupValidator.java` keyed-method 메시지), ADR-GRPC-004 "(b)" 기록, `src/grpc/CLAUDE.md:168` |
|
||||
| RR-02-08 | 부분 | ② Javadoc은 고쳤다(`GraphQlDeadline.java:17-19`). ① calculator의 복사본은 지웠지만 같은 규칙의 세 번째 복사본이 `GraphQlClientPolicy.java:101`에 남았다 → RR-01-14 |
|
||||
| RR-07-01 | 닫힘(결정대로) | = RR-01-02 |
|
||||
| RR-07-06 | 닫힘 | `FileAccessSubject.owns` 한 곳, `FileAccessPolicyPortContract`를 `FakeFileAccessPolicyContractTest`와 `RoleBasedFileAccessPolicyContractTest`가 상속 |
|
||||
| RR-04-04 | 닫힘 | = RR-01-05 |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-01-11 · `IDEMPOTENCY_COMPLETION_UNKNOWN` 뒤 "같은 키 재전송은 안전" 약속을 Redis 저장소가 지키지 않는다 — lease가 지나면 작업을 다시 돌린다
|
||||
|
||||
- **위치**: `docs/web/http-contract.md:108-114`, `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyCompletionUnknownException.java:16-17`,
|
||||
`src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java:50`(주석), `docs/registries/error-codes.yaml:448-450`(주석),
|
||||
`src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java:71-79`,
|
||||
`src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:136-137`
|
||||
- **무엇이 틀렸나**:
|
||||
- 새 계약은 "결과 불명 503을 받으면 같은 키로 다시 보내라. 서버가 판정한다 — 기록됐으면 재생, lease 안이면 409,
|
||||
lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`"라고 적는다(`http-contract.md:111-113`, 예외 Javadoc `:16-17`).
|
||||
- 이 예외는 `complete`가 `UNAVAILABLE`을 돌려줄 때만 난다. `UNAVAILABLE`을 돌려주는 저장소는 Redis뿐이다
|
||||
(`RedisIdempotencyStoreAdapter.java:248,251` — lane이 보내기 전에 거절). PostgreSQL 저장소에는 `UNAVAILABLE` 결과가
|
||||
아예 없다(`PostgreSqlIdempotencyStore`에서 grep 0건). 즉 결과 불명은 실제로 Redis 배포에서만 생긴다.
|
||||
- 그때 Redis 기록은 `EXECUTING`으로 남는다(complete가 보내지지 않았다). 그런데 Redis CLAIM 스크립트는 상태를 가리지
|
||||
않고 lease가 끝난 기록을 넘겨준다: `if state == 'FAILED_RETRYABLE' or (leaseUntil ~= nil and leaseUntil <= nowMillis)`
|
||||
→ `TAKEN_OVER`(`IdempotencyScripts.java:71-79`). executor는 `TakenOverClaimed`를 받으면 `startAndRun`으로 작업을 다시
|
||||
돌린다(`IdempotencyExecutor.java:136-137`).
|
||||
- PostgreSQL은 반대다. lease가 지난 `EXECUTING`은 `ABANDONED`로 바꾸고 `RecoveryRequired`를 준다
|
||||
(`PostgreSqlIdempotencyStore.java:153-155`, 테스트 이름 `expiredExecutingRecordRequiresReconciliationAndIsNeverBlindlyTakenOver`).
|
||||
공유 `IdempotencyStoreContract`는 이 경우를 묶지 않는다("expiry and take-over … stay with each store's own tests", `:34-35`).
|
||||
그래서 두 저장소가 갈라진 채 게이트를 통과한다.
|
||||
- **왜 중요한가**:
|
||||
- 4절 결정이 막으려던 것은 "결과 불명을 '안 됨'으로 믿고 다시 실행"이다. 새 코드는 클라이언트에게 "같은 키면 안전"이라고
|
||||
말하는데, 이 코드가 나는 유일한 저장소에서 같은 키 재전송이 lease(기본 30초) 뒤 작업을 다시 실행한다.
|
||||
- 발생 조건: `provider=redis` + complete 단계에서 lane이 포화·종료 중 + action이 트랜잭션 밖 효과(외부 호출·메일)를 가짐 +
|
||||
클라이언트가 계약대로 30초 넘게 재시도. 결과: 외부 효과가 두 번 일어난다. 클라이언트는 "같은 키라 안전"이라고 믿었으므로
|
||||
이상을 알아챌 근거가 없다.
|
||||
- DB만 쓰는 action이고 `execute`가 `tx.inWrite` 안이면(sample `PublishPosterImageUseCase.java:109-118`) DB 효과는 롤백되므로
|
||||
다시 돌리는 것이 오히려 맞다. 하지만 그것도 계약 문장("500 RECOVERY_REQUIRED")과 다르다. 어느 쪽이든 문서가 틀렸다.
|
||||
- 사용자 원칙: 위험이 코드에 드러나야 한다. 지금은 두 저장소의 차이가 각자의 테스트에만 있고, 계약 문서는 PG 쪽만 말한다.
|
||||
- **고치는 법**: 4절 결정 문장("lease 뒤 회복 필요")을 기준으로 맞춘다.
|
||||
1. Redis CLAIM 스크립트: `state == 'EXECUTING'`이고 lease가 끝났으면 `ABANDONED`로 바꾸고 `RECOVERY_REQUIRED`를 돌려준다.
|
||||
lease 만료 넘겨받기는 `CLAIMED`(실행 전)와 `FAILED_RETRYABLE`만 한다. PG와 같은 규칙이다.
|
||||
2. `IdempotencyStoreContract`에 시간 경우 하나: "실행 시작 뒤 lease가 지나면 다른 claim은 `RecoveryRequired`".
|
||||
in-memory는 abort되고 Live Redis·PG lane이 실제로 돈다(아래 탐침이 그 모양이다).
|
||||
3. 예외 Javadoc의 "Effects inside the action's own transaction roll back"을 "`execute`를 쓰기 트랜잭션 안에서 부른 경우"로
|
||||
좁힌다. action이 자기 트랜잭션을 따로 커밋하면 DB 효과도 남는다.
|
||||
- Redis 스크립트 변경은 04 영역 파일이다. 계약 문서·계약 테스트·Javadoc은 이 영역이다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2 (Redis 배포·complete 단계 lane 거절·외부 효과가 겹칠 때만. 기본 조립은 멱등성 비활성)
|
||||
- **증거**: E3 — 아래 탐침. 코드 경로는 E1.
|
||||
- 탐침: worktree에서 `IdempotencyStoreContract`에 메서드 하나를 넣었다. claim(lease 1s) → `markExecutionStarted` →
|
||||
다른 attempt로 claim(lease 안) → `elapse(2s)` → 다른 attempt로 claim. `LiveRedisIdempotencyStoreContractTest`(Testcontainers
|
||||
Redis, 실제 서버 시계)로 `redisContainerContractTest` lane을 돌렸다.
|
||||
- 출력: `RR2-PROBE LiveRedisIdempotencyStoreContractTest duringLease=InProgress afterLease=TakenOverClaimed`,
|
||||
`BUILD SUCCESSFUL in 44s`. lease 안에서는 409가 되고, lease 뒤에는 계약이 말한 `RecoveryRequired`가 아니라
|
||||
`TakenOverClaimed`다 — executor는 이것을 받으면 작업을 다시 돌린다.
|
||||
- PG 쪽 반대 동작은 기존 테스트 `PostgreSqlIdempotencyIntegrationTest.java:164`가 고정한다(E2, 다시 돌리지 않음).
|
||||
|
||||
#### RR-01-12 · 새 `@SystemInvoked` 규칙 둘이 매뉴얼 09장의 이벤트 소비 경로(쓰기 use case 호출)를 막는다 — 규칙을 지키는 방법이 문서에 없다
|
||||
|
||||
- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:455-467`,
|
||||
`src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java:57-70`,
|
||||
`docs/manual/09-outbox-events.md:115-117`, `docs/manual/07-authorization.md:65-89`, `src/adapter/inbound/messaging/README.md:32,95`
|
||||
- **무엇이 틀렸나**:
|
||||
- 매뉴얼 09장 4단계는 소비 handler(`MessageHandler<T>`)를 `adapter:inbound:messaging`에 두고 "delivery 하나를 use case 호출
|
||||
하나로 바꾸라, use case는 평소처럼 `tx.inWrite`로 쓴다"고 가르친다. 소유자 결정 10(Kafka 소비)의 정식 경로다.
|
||||
- 그 use case는 쓰기다(`WRITE_REPOSITORY`). 지금 쓰기 use case가 고를 수 있는 길은 셋인데, 소비 handler에서는 셋 다 막힌다.
|
||||
1. `@RequiresPermission` + bean: 소비 스레드에는 `Authentication`이 없다. `RequiresPermissionAuthorizationManager.java:56`이
|
||||
`auth == null`이면 거부한다. 메시지는 재시도 후 DLQ로 간다.
|
||||
2. `@SystemInvoked`(07장이 말하는 "시스템이 부르는 쓰기"): bean이면 이번 라운드의 가드가 기동을 막는다. handler가 그
|
||||
클래스에 의존하면 이번 라운드의 ArchUnit이 막는다 — 규칙이 `..adapter.inbound..` 전체를 대상으로 하므로
|
||||
`dev.caskeleton.adapter.inbound.messaging`도 들어간다(`:458`).
|
||||
3. 표시 없음: D4(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)가 빌드를 막는다.
|
||||
- 남는 길은 "handler가 구체 클래스 대신 `CommandUseCase<C,R>` 같은 인터페이스에 의존하고, composition이 `new`로 만든
|
||||
`@SystemInvoked` use case를 handler bean에 넣는다"뿐이다. 이 방법은 07장·09장·messaging README·ArchUnit 메시지 어디에도
|
||||
없다. ArchUnit 메시지는 "scheduler에 넘긴다"고만 한다. 게다가 messaging README는 handler를 app-bootstrap에서 등록하는
|
||||
안을 버렸다(`:95`).
|
||||
- 이번 라운드 전에는 `@SystemInvoked` use case를 bean으로 만들어 handler에 넣는 길이 있었다(그래서 RR-01-02가 위험했다).
|
||||
그 문을 닫으면서 정당한 시스템 호출자 하나(소비자)의 길을 문서 없이 함께 닫았다.
|
||||
- **왜 중요한가**:
|
||||
- 첫 소비자를 붙이는 파생 서비스는 매뉴얼대로 하면 기동·빌드·런타임 중 하나에서 반드시 실패한다.
|
||||
- 실패를 끄는 가장 쉬운 우회가 위험하다. `repositoryAccess`를 낮춰 D4를 피하면 권한 표시 없는 쓰기 use case가 bean으로
|
||||
생기고, 컨트롤러도 그것을 주입받을 수 있다. RR-01-02가 막으려던 "검사 없는 쓰기"가 다른 문으로 돌아온다.
|
||||
- 사용자 원칙: 선택지가 여럿이면 고른 방법·버린 대안·이유가 남아야 하고, 개발자가 따로 기억해야 하는 규칙은 결함이다.
|
||||
- **고치는 법**: 둘 중 하나를 고르고 기록한다.
|
||||
- (a) 경로를 문서로 고정: 09장 4단계와 07장 「시스템이 부르는 쓰기」에 "소비 handler는 use case를 인터페이스(또는
|
||||
application-core가 소유한 함수형 포트)로 받고, `@SystemInvoked` use case는 소비 조립(composition)이 `new`로 만들어
|
||||
handler bean에 넣는다"를 적는다. 예시 조립 하나(`InboxRedeliveryIntegrationTest`의 handler 모양을 그 방식으로)와
|
||||
ArchUnit 메시지에 "scheduler 또는 소비 handler"를 넣는다.
|
||||
- (b) 규칙을 좁힘: ArchUnit 대상에서 `..adapter.inbound.messaging..`을 빼고, 대신 "messaging inbound는 HTTP·gRPC·GraphQL·
|
||||
WebSocket 패키지에 의존하지 않는다"로 노출 경로를 막는다. 가드는 그대로 둔다(소비 handler가 use case를 `new`로 만들면 bean이
|
||||
아니다).
|
||||
- 어느 쪽이든 07장 "지금 이해하면 되는 것"의 "시스템만 부르는 쓰기" 줄에 소비자를 넣는다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2 (런타임 결함이 아니라 매뉴얼이 가르치는 경로와 새 규칙의 충돌. 템플릿에 소비자는 아직 없다)
|
||||
- **증거**: E1 — 규칙 대상 패키지(`:458`), 가드 조건(`:57`), 인가 관리자의 무인증 거부(`:56`), 매뉴얼 4단계(`:115-117`)를 대조했다.
|
||||
ArchUnit을 fixture로 돌려 보지는 않았다.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-01-13 · `/error` 응답이 표에 없는 status를 400·500으로 바꾸는데, 정본은 "원래 status가 그대로 나간다"고 적는다
|
||||
|
||||
- **위치**: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/EnvelopeErrorController.java:65-70`,
|
||||
`HttpStatusErrorCodes.java:32-35`, `EnvelopeResponseWriter.java:37`, `docs/web/http-contract.md:59`
|
||||
- **무엇이 틀렸나**: 오류 컨트롤러는 디스패치 status를 `HttpStatusErrorCodes`로 코드에 바꾼 뒤 그 코드의 status를 다시 쓴다.
|
||||
표에 없는 4xx(408·409·410·422 등)는 `BAD_PARAMETER` 400, 표에 없는 5xx(501·502·504)는 `INTERNAL_ERROR` 500이 된다.
|
||||
Boot 기본 컨트롤러는 원래 status를 그대로 냈다. 지금 main 코드에 `sendError`는 없어서(grep 0건) 나오는 경우는 컨테이너·
|
||||
라이브러리가 낸 오류뿐이다.
|
||||
- **왜 중요한가**: 정본 1절의 "원래 status가 그대로"는 표에 있는 status에서만 참이다. 필터를 더하는 서비스가 `sendError(409)`를
|
||||
쓰면 400으로 바뀌어 클라이언트 분기가 틀어진다.
|
||||
- **고치는 법**: 문장을 "표에 있는 status는 그대로, 그 밖은 400·500으로 접힌다"로 고치거나, 오류 컨트롤러가 status는 원래 값을
|
||||
두고 code만 표로 고르게 한다(`EnvelopeResponseWriter`에 status를 따로 받는 overload).
|
||||
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1
|
||||
|
||||
#### RR-01-14 · page 크기 규칙의 세 번째 복사본이 남았다(RR-02-08 ① 부분)
|
||||
|
||||
- **위치**: `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/policy/GraphQlClientPolicy.java:101-107`
|
||||
- **무엇이 틀렸나**: 지운 `GraphQlComplexityCalculator.effectivePageSize`와 같은 "둘 다 있으면 `first`" 규칙이 public 메서드로
|
||||
`GraphQlClientPolicy`에 있다. 상한 검사도 없다. main 호출자는 없고 테스트(`GraphQlClientPolicyTest.java:45-47`)만 부른다.
|
||||
실제 점수는 `connectionCost`(큰 쪽), 실제 resolver 쪽은 `GraphQlConnectionPolicy.effectivePageSize`(방향 섞임 거부)다.
|
||||
- **왜 중요한가**: 갈라진 복사본이다. adopter가 이름만 보고 이것을 resolver에서 부르면 상한 없는 page를 받는다.
|
||||
- **고치는 법**: 지우고 테스트를 `GraphQlConnectionPolicy` 쪽으로 옮긴다.
|
||||
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1(grep)
|
||||
|
||||
#### RR-01-15 · gRPC ledger `release`는 토큰 밖에 있고, 행이 지워지면 시도 번호가 1로 돌아간다
|
||||
|
||||
- **위치**: `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationLedger.java:143`,
|
||||
`src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:204-207`,
|
||||
`GrpcOperationLedgerRepository.java:48`, `GrpcClaimToken.java:14-15`
|
||||
- **무엇이 틀렸나**: 다른 전이는 모두 토큰을 받는데 `release(identity)`는 토큰 없이 `deleteById`한다. 지운 뒤 새 claim은
|
||||
`claim_attempt = 1`로 시작한다. 그래서 `GrpcClaimToken` Javadoc의 "두 시도는 같은 값을 나눠 갖지 않는다"는 release·purge 뒤에는
|
||||
거짓이다. 옛 attempt 1 owner가 그때 살아 있으면 새 attempt 1의 claim에 commit·실패를 기록할 수 있다(ABA).
|
||||
- **왜 중요한가**: 지금 main에 `release` 호출자는 없고, purge는 24h 지난 완료 행만 지우므로 실제 창은 아주 좁다. 다만 포트에
|
||||
"토큰 없는 파괴 연산"이 남아 있고 Javadoc이 반대로 말한다.
|
||||
- **고치는 법**: `release(identity, claimToken)`으로 바꿔 `DELETE … WHERE claim_attempt = :token AND state = 'IN_PROGRESS'`로 하거나,
|
||||
포트에서 지운다. Javadoc 문장을 "같은 행이 살아 있는 동안"으로 좁힌다.
|
||||
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1
|
||||
|
||||
#### RR-01-16 · 새 "첫 쓰기 두 개가 겹침" 계약 케이스가 fake에서는 겹치지 않는다
|
||||
|
||||
- **위치**: `src/application-core/src/testFixtures/java/dev/caskeleton/application/outbox/testkit/OutboxAggregateSequenceContract.java:71-83`,
|
||||
`src/application-core/src/testFixtures/java/dev/caskeleton/application/transaction/testkit/DirectTransactionPort.java:47,115-118`
|
||||
- **무엇이 틀렸나**: `OverlappingWrites`는 두 스레드에서 트랜잭션을 연다. in-memory 계약 테스트의 `DirectTransactionPort`는
|
||||
스레드를 구분하지 않는 필드 하나(`current`)로 "열린 트랜잭션"을 기억한다. 둘째 스레드는 첫 스레드의 트랜잭션이 열려 있는 것을
|
||||
보고 거기에 join한다(`:117`). fake에서는 "겹친 두 트랜잭션"이 아니라 "한 트랜잭션 안의 두 호출"을 검사한다. `ArrayList`도
|
||||
두 스레드가 같이 고친다.
|
||||
- **왜 중요한가**: 실제 대상인 PG에서는 의미대로 돈다. fake에서는 녹색이 아무것도 말하지 않고, 경쟁 상태가 있는 테스트 코드라
|
||||
드물게 흔들릴 수 있다.
|
||||
- **고치는 법**: `DirectTransactionPort`의 `current`를 `ThreadLocal`로 바꾸거나, fake 계약 테스트에서 이 케이스를 순차 실행으로
|
||||
바꾸고 그렇게 적는다.
|
||||
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1
|
||||
|
||||
#### RR-01-17 · move의 "거절되면 아무것도 바뀌지 않는다"는 쓰기 전 거절에서만 테스트된다
|
||||
|
||||
- **위치**: `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/lifecycle/MoveFileApplicationUseCase.java:38-40,92-109`,
|
||||
`FileLifecycleUseCasesTest.java:485`
|
||||
- **무엇이 틀렸나**: 테스트는 `requireRoom`에서 거절되는 경우(아직 아무것도 안 씀)만 본다. 쿼터를 옮긴 뒤 `relocate`가 버전 충돌로
|
||||
실패하는 경우의 롤백은 JPA 포트들이 호출자 트랜잭션에 합류한다는 사실에만 기댄다. 쿼터 fake는 롤백을 모르므로 use case 테스트로는
|
||||
볼 수 없고, PG lane에도 move 케이스가 없다. 또 이번 수정 전에 move된 파일은 여전히 출발 namespace에 잡혀 있고, 그 파일을 지우면
|
||||
지금 namespace에서 회수한다. 이 과거 데이터의 처리 방법이 어디에도 없다.
|
||||
- **왜 중요한가**: 지금 코드는 맞다(E1). 나중에 누가 quota 포트 하나를 `inNew`로 바꾸면 잡을 테스트가 없다.
|
||||
- **고치는 법**: persistence-fileserver PG lane에 "move 중 버전 충돌 → 양쪽 사용량 그대로" 하나. `NamespaceQuota` 또는 fileserver
|
||||
runbook에 "수정 전 move된 파일은 장부가 틀릴 수 있다, 재계산 SQL"을 한 줄.
|
||||
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- application-core outbox 변경(`OutboxPublishAttempt`, `last_failure_code`, `PARKED`, `longRetries`, 포트 시그니처 변경): diff는 읽었고
|
||||
눈에 띄는 결함은 없었다. RR-05-xx·06-10~14의 닫힘 판정은 05 영역 리뷰어 몫이다.
|
||||
- `SubmitDurableOperationUseCase`의 파생 UUIDv7 event id: 클라이언트가 고른 operation id가 남의 파생 id와 같으면 inbox가 두 이벤트를
|
||||
같은 것으로 본다. 옛 `operation-<sha256>` 방식에도 같은 성질이 있었고 남의 operation id를 알아야 하므로 이번 라운드 결함으로 보지 않았다.
|
||||
- `PermissionEnforcementGuard`가 못 보는 경우(lazy·prototype bean의 선언 타입이 인터페이스, `registerSingleton`, 람다 wrapper):
|
||||
일부러 우회해야 생기는 경우라 판정하지 않았다.
|
||||
- ERROR 디스패치 허용의 새 노출: 컨테이너 오류 페이지가 `/error` 하나이고 컨트롤러가 요청 값을 쓰지 않으며, 다른 체인
|
||||
(actuator·알림 콜백)은 `/error`와 맞지 않는다. 새 노출은 찾지 못했다. Jetty와 관리 포트 분리 배포는 보지 않았다.
|
||||
- V003의 `CHECK` 제약은 `NOT VALID` 없이 붙어 테이블 전체를 검사한다. 마이그레이션 주석대로 플랫폼이 아직 어디에도 채택되지 않아
|
||||
판정하지 않았다.
|
||||
- 필터가 던진 예외의 오류 디스패치가 span 오류 기록을 남기지 않는 것(예외 처리기는 남긴다): 1차 이전부터 같았다.
|
||||
|
||||
## 수렴 판단
|
||||
|
||||
**이 라운드가 만든 새 Important가 있다: 2건.**
|
||||
|
||||
- RR-01-11: 이번 라운드가 새로 쓴 계약 문장(같은 키 재전송 판정)이 그 코드를 실제로 내는 유일한 저장소(Redis)와 반대다. 원인인
|
||||
Redis 동작은 이전부터 있었지만, 그 위에 "안전"이라는 약속을 이번에 얹었다.
|
||||
- RR-01-12: 이번 라운드의 `@SystemInvoked` 규칙 둘이 매뉴얼의 이벤트 소비 경로를 문서 없이 막는다.
|
||||
|
||||
둘 다 기본 조립(멱등성 비활성, 소비자 없음)에서는 동작하지 않는 경로라 Critical·High는 아니다. 고치는 범위도 작다(Redis 스크립트 한
|
||||
분기 + 계약 케이스 하나 + 문서, 그리고 매뉴얼 두 장과 ArchUnit 메시지). 그래도 둘 다 "계약·매뉴얼대로 한 사람이 틀린 결과를 받는다"는
|
||||
종류라 다음 수정 라운드가 필요하다. Minor 5건은 같은 라운드에 묶을 수 있다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? With fixes**
|
||||
|
||||
맡은 1차 발견은 중복(RR-07-01=RR-01-02, RR-04-04=RR-01-05)을 빼면 19건이다. 17건이 닫혔고 2건이 부분이며 회귀는 없다. RR-02-03은 결과 불명 계약이 Redis 저장소와 맞지 않아 부분이고(RR-01-11),
|
||||
`@SystemInvoked` 규칙은 결정대로 들어갔지만 소비자 경로를 막는 새 Important를 만들었다(RR-01-12).
|
||||
@@ -0,0 +1,246 @@
|
||||
# 02 persistence·messaging 재리뷰 (2026-11-03, 2차)
|
||||
|
||||
경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
- 리뷰 범위: Base `7ef8d0b4` → Head `bbe944bd`(커밋 1개) 중 아래 pathspec. 90파일, +2,924 −454.
|
||||
```text
|
||||
src/adapter/outbound/persistence-jpa src/adapter/outbound/persistence-mongo
|
||||
src/adapter/outbound/persistence-fileserver src/adapter/outbound/persistence-notification
|
||||
src/messaging src/adapter/outbound/messaging src/adapter/outbound/messaging-kafka
|
||||
src/adapter/inbound/messaging src/application-notification docs/runbooks docs/messaging docs/jpa
|
||||
docs/reviews/2026-11-01-maturity-review/06-messaging.md
|
||||
```
|
||||
`persistence-mongo`와 `adapter/inbound/messaging`은 이 커밋에 바뀐 파일이 없다.
|
||||
- 맡은 1차 재리뷰 발견: RR-03-01~10, RR-05-01~10, 06-10~06-14.
|
||||
- 새 발견 ID는 `RR-02-09`부터다. 1차의 `RR-02-01~08`은 inbound 영역의 발견이라 겹치지 않게 이어 붙였다.
|
||||
- 읽은 방식: 하위 에이전트 없이 여러 번에 나눠 직접 읽었다.
|
||||
1. persistence-jpa main 전부(`JpaOutboxStore`, `OutboxEventJpaRepository`, floor entity, `OutboxEventEntity`,
|
||||
`SpringTransaction`, `PersistenceExceptionTranslator`, V21·V22)와 build.gradle.
|
||||
2. persistence-jpa 테스트: `PostgreSqlOutboxOrderKeyRunbookIntegrationTest`, `PostgreSqlOutboxDispositionRunbookIntegrationTest`,
|
||||
`OutboxRunbookSql`, `PostgreSqlOutboxAggregateSequenceIntegrationTest`, `SpringTransactionDeadlineTest`,
|
||||
`PostgreSqlTransactionIntegrationTest` 추가분, `JpaOutboxStoreTest`, 아키텍처 규칙·fixture.
|
||||
3. runbook 두 개(`outbox-dead-letter.md`, `outbox-publish-failed.md`) 전문과 나머지 runbook diff.
|
||||
4. messaging bridge·relay 포트 diff, vendored messaging diff 전부(`KafkaConsumerRegistrar`,
|
||||
`KafkaQuarantinePublisher`, `KafkaDeadLetterQuarantine`, `FailureDescriptor`, `MessagingShutdownLifecycle`),
|
||||
`KafkaConsumerRegistrarTest` 추가분.
|
||||
5. notification·fileserver persistence diff, `ReconciliationJobWorker`(시도 한도가 실제로 걸리는지).
|
||||
- 판단에 필요해서 pathspec 밖에서 읽은 것(전체 diff 리뷰는 아님): application-core의 `OutboxPublishAttempt`,
|
||||
`PublishPendingOutboxEventsUseCase`, `OutboxEventStatus`, `OutboxAggregateSequencePort`, `IntegrationEventDraft`,
|
||||
`IntegrationIdentity`, `SubmitDurableOperationUseCase`, `ReleasedPayloadSchemaContract`, `OutboxAggregateSequenceContract`,
|
||||
`OverlappingWrites`; composition의 `OutboxSettings`, `OutboxRelayAutoConfiguration`, `OutboxMetrics`;
|
||||
`DefaultMessagePublisher`의 기한 처리, `KafkaMessagingAutoConfiguration`의 producer 설정, `docs/registries/metrics.yaml`
|
||||
outbox 항목, `docs/manual/09-outbox-events.md`.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
|---|---|---|
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항 정합, mock이 아닌 실제 동작 테스트, 마이그레이션 전략·하위 호환, Declined to judge, 심각도 보정, 읽지 않은 코드를 칭찬하지 않기 | 발견마다 "고치는 법"·4절 결정 대조, 테스트가 실제 DB·실제 문서를 쓰는지, V21·V22의 배포 경로 |
|
||||
| `jpa-patterns` | Flyway 마이그레이션은 additive·재실행 가능, Hibernate는 validate만, 짧은 트랜잭션, 연관관계 규칙(사용자 원칙 "양방향 금지"를 스킬의 `mappedBy` 예시보다 우선) | V21·V22, `insertable/updatable=false` 필드의 실제 SELECT 동작(RR-02-13), `SingleSidedAssociationCondition`의 그래프 판정(RR-02-15), 트랜잭션 마감 분류 |
|
||||
| `supabase-postgres-best-practices` | `lock-short-transactions`(DDL은 `lock_timeout`으로 잠금 대기를 묶는다), `data-upsert`(`ON CONFLICT`로 경쟁을 DB가 판정), `lock-skip-locked`, `schema-constraints`(제약·상태 값의 재실행 안전성) | V21 `lock_timeout`·무효 인덱스 거부·floor, V22의 잠금 대기(RR-02-09, 실 PG), counter `ON CONFLICT DO NOTHING` 경쟁, PARKED를 DDL 없이 둔 결정의 영향(RR-02-11) |
|
||||
| `doubt-driven-development` | 주장(CLAIM)을 적고 반증을 시도한다 | 아래 7개 주장. 브리프가 하위 에이전트를 금지해 새 맥락 리뷰어 대신 자기 반증(축소 적용)으로 했다. 비대화 실행이라 교차 모델 검토는 건너뛰었다 |
|
||||
|
||||
반증을 시도한 주장과 결과:
|
||||
|
||||
1. "V21은 실패해도 다시 돌리면 된다" → 반증 못 함. 한 트랜잭션이라 lock_timeout·중복·무효 인덱스 실패 모두 V20에 남고, floor는 다시 돌 때의 시각으로 다시 기록된다. 해당 lane 테스트 3개가 확인한다.
|
||||
2. "rolling 배포 중 옛 인스턴스의 벽시계 번호 뒤에 새 번호가 온다" → **일부 반증**. 같은 identity면 맞다. tenant scope가 바뀌는 배포에서는 옛 scope 행을 보지 못해 새 번호가 더 작다(RR-02-10, 실 PG).
|
||||
3. "counter 첫 생성 경쟁에서 두 쓰기 모두 성공한다" → 반증 못 함. PG(공용 계약의 겹침 테스트)와 H2 PostgreSQL 모드(직접 실험) 둘 다 맞다.
|
||||
4. "이번 라운드의 마이그레이션은 잠금 대기가 묶여 있다" → **반증**. V21은 5초로 묶었지만 같은 커밋의 V22는 ACCESS EXCLUSIVE를 상한 없이 기다리고, 그동안 outbox 읽기·쓰기가 모두 멈춘다(RR-02-09, 실 PG).
|
||||
5. "runbook SQL은 lane이 문서에서 읽어 실 PG로 돌린다" → 반증 못 함. 두 lane이 system property로 문서 경로를 받고 문서를 Gradle 입력으로 선언한다. 표지 없는 SQL은 돌지 않는다(Declined 참고).
|
||||
6. "draft의 UUIDv7 거부는 기존 데이터·재시도를 막지 않는다" → 반증 못 함. draft는 새 이벤트에만 쓰이고, 저장된 행 복원은 draft를 거치지 않는다. durable operation 재시도는 같은 UUIDv7을 다시 만든다.
|
||||
7. "PARKED는 DDL 없이 안전하다" → **일부 반증**. 새 버전에서는 맞다. 옛 버전(배포 중·롤백 후)은 상태 이름을 몰라 `outbox.pending.size` 게이지 전체가 꺼진다(RR-02-11, 코드).
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
메인 작업 트리·index·HEAD는 바꾸지 않았다. Gradle은 돌리지 않았다. 실험은 scratchpad에 마이그레이션 파일을 복사해서 했다.
|
||||
|
||||
| 명령 | 실행 직전 부하 | 결과 |
|
||||
|---|---|---|
|
||||
| `git diff --stat 7ef8d0b4..bbe944bd -- <pathspec>`, `git diff ...` | — | 90파일. 나눠서 전부 읽었다 |
|
||||
| `java -cp h2-2.4.240.jar H2Check.java` (scratchpad, `nextSequence`의 세 문장을 그대로 H2 `MODE=PostgreSQL`에서 실행) | — | `first=1 second=2 third=3`, 이미 있는 counter에 생성 문장 → `0`. 두 연결 겹침: 첫째가 생성 후 커밋 보류, 둘째 `next=2`, 최종 `2`. 커밋에 적힌 "H2가 `ON CONFLICT DO NOTHING`을 받는다"를 확인 |
|
||||
| `flock heavy.lock scratchpad/rr2-02/exp.sh` (postgres:16-alpine, 컨테이너 안 psql로 HEAD의 V1~V21 적용 후 실험) | load 16.65 | rc=0. 첫 시도는 다른 작업이 잠금을 잡고 있어 대기 중 시간 초과(rc=124)였고 재실행했다 |
|
||||
| └ EXP1: 세션 A가 `outbox_event`를 읽은 트랜잭션을 20초 열어 둠 → 세션 B가 V22 실행 → 세션 C·D가 3초 제한으로 읽기·쓰기 | | `pg_locks`: A `AccessShareLock` granted, V22 `AccessExclusiveLock` 대기. C 읽기 `canceling statement due to statement timeout`(3.09초), D 쓰기 같은 오류(3.20초). **V22는 19.1초 기다린 뒤 rc=0** |
|
||||
| └ EXP2: floor 뒤 30초에 옛 버전이 `portfolio` scope로 쓴 행(번호 floor+30,000,000) → 새 버전이 같은 aggregate를 `global` scope로 `nextSequence` 문장 실행 | | floor=1793718324464623, 옛 행=1793718354464623, **새 번호=1793718324464624(옛 행보다 작음)** |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- Gradle lane을 직접 돌리지 않았다. `postgresqlOutboxDispositionRunbookIntegrationTest`·`postgresqlOutboxOrderKeyRunbookIntegrationTest`·
|
||||
`postgresqlOutboxAggregateSequenceIntegrationTest`·Kafka relay lane·`KafkaConsumerRegistrarTest`의 통과는 재리뷰 README 7절 게이트 기록을 따랐다.
|
||||
- persistence-jpa에 새로 들어온 fileserver PG 계약 테스트(`FileserverPostgreSqlStack`, `PostgreSqlFileQuotaLedgerContractTest` 등)는
|
||||
RR-01-04 몫이라 stack만 읽었다. 계약 케이스 목록은 01 영역 리뷰가 본다.
|
||||
- 실제 Kafka·SIGTERM·다중 인스턴스 동시 기동은 실행하지 않았다.
|
||||
- idempotency·redis·grpc·job-timeout runbook diff는 다른 영역 발견의 문서라 이 영역 코드와 모순이 없는지만 봤다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **counter 첫 생성 경쟁을 DB가 판정한다.** `JpaOutboxStore.java:125-139`는 `UPDATE` → `INSERT … ON CONFLICT DO NOTHING` → 다시 `UPDATE`다. 두 번째 쓰기는 첫째의 커밋을 기다렸다가 증가만 한다. 공용 계약 `OutboxAggregateSequenceContract.java:71`이 `OverlappingWrites`로 겹침을 운에 맡기지 않고 만들고, PG 테스트가 상속한다. H2 개발 경로도 직접 실험으로 같은 결과였다.
|
||||
- **번호가 뒤로 가지 않게 두 겹으로 막았다.** 새 counter는 floor와 남은 행 최대값 중 큰 값 다음에서 시작한다(`OutboxEventJpaRepository.java:164`). 기존 counter의 증가도 그 aggregate의 가장 큰 행 아래로 내려가지 않는다(`:140`). 롤백 후 재배포처럼 옛 번호가 다시 섞여도 다음 번호가 그 뒤에 온다.
|
||||
- **V21의 실패 경로를 실 PG로 고정했다.** 잠금 대기 초과(`PostgreSqlOutboxOrderKeyRunbookIntegrationTest.java:227`), 실패한 CONCURRENTLY가 남긴 무효 인덱스 거부(`:263`), runbook대로 미리 만든 인덱스 재사용(`:298`), counter 선생성(`:185`)이 있다. 각 테스트가 "DB가 V20에 남는다"를 함께 단언한다.
|
||||
- **runbook SQL이 문서 그대로 실행된다.** `OutboxRunbookSql`이 `<!-- runbook-sql: id -->` 블록을 문서에서 읽고, 두 lane이 문서를 Gradle 입력으로 선언한다(`persistence-jpa/build.gradle:252-260`). 재발행 테스트(`PostgreSqlOutboxDispositionRunbookIntegrationTest.java:63`)는 옛 SQL이면 실패하는 RED가 성립한다. "다음 claim이 그 행을 가져가는가"로 결과를 본다.
|
||||
- **PARKED가 순서를 지키는지 실제로 본다.** 보류 행 뒤의 행이 claim되지 않음을 단언한다(`PostgreSqlOutboxDispositionRunbookIntegrationTest.java:149`).
|
||||
- **마감 초과 분류를 자기가 연 트랜잭션으로 좁혔다.** `SpringTransaction.java:201-232`는 이 호출이 시작한 트랜잭션이고 마감이 지났고 다른 분류가 없을 때만 `translateAfterDeadline`을 부른다. 운영 조합(`JpaTransactionManager`)의 실 PG 테스트(`PostgreSqlTransactionIntegrationTest.java:305`)와 "업무 예외는 그대로" 테스트(`SpringTransactionDeadlineTest.java:113`)가 있다.
|
||||
- **ACL이 원인 코드를 잃지 않는다.** bridge가 platform 코드를 그대로 옮기고, 문법 밖이면 platform의 category 이름으로 바꾼다(`PlatformIntegrationEventPublishAdapter.java:205-233`). 메시지가 아니라 이름만 옮긴다.
|
||||
- **06-12 검사가 값이 만나는 곳에 있다.** 발행 포트만 아는 최악 시간과 설정이 relay 조립에서 만난다(`OutboxRelayAutoConfiguration.java:76`, `OutboxSettings.java:80`). Kafka `max.block.ms`를 같은 기본 기한으로 묶은 설정과 계산이 맞다.
|
||||
- **정산 job의 버려진 claim이 시도로 셈된다.** `JdbcReconciliationJobStore.java:74`, 그리고 worker가 provider를 부르기 전에 한도를 본다(`ReconciliationJobWorker.java:111`). 매번 죽는 job도 끝난다.
|
||||
- **격리 분류가 재시도 경로에서도 유지된다.** 읽을 수 없는 레코드는 첫 격리 쓰기가 실패해도 DESERIALIZATION으로 남는다(`KafkaConsumerRegistrar.java:351,357`, 테스트 `anUndecodableRecordStaysDeserializationWhenItsQuarantineIsRetried`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
|---|---|---|
|
||||
| RR-03-01 | 닫힘 | `JpaOutboxStore.java:132-137`, `OutboxEventJpaRepository.java:169`. PG 겹침 계약 `OutboxAggregateSequenceContract.java:71`. H2 경로는 이 리뷰의 직접 실험으로 확인(E3) |
|
||||
| RR-03-02 = RR-05-02 | 결정으로 닫힘(잔여 RR-02-10) | V21 floor(`V21:54-56`)·counter 선생성(`:58-65`), 생성 `GREATEST(MAX, floor)`, 증가 `GREATEST(last, MAX)`. PG 테스트 reaper·scope 변경·rolling(`PostgreSqlOutboxAggregateSequenceIntegrationTest.java:108,126`). manual 09에 첫 번호 안내. scope가 바뀌는 배포의 rolling 구간은 막지 못한다(RR-02-10, E3) |
|
||||
| RR-03-03 | 닫힘 | `SpringTransaction.java:209,220`, `PersistenceExceptionTranslator.java:159-179`. H2 본문 flush·커밋 flush, 실 PG `JpaTransactionManager` 테스트 |
|
||||
| RR-03-04 | 닫힘(잔여 RR-02-15) | `SingleSidedAssociationCondition.java:84-117` 그래프 판정, fixture `JoinColumnParentEntity`·`JoinColumnChildEntity`, 가이드 `entity-mapping-guide.md:75-91`. 서로 다른 두 FK를 양방향으로 오판한다(Minor) |
|
||||
| RR-03-05 | 닫힘 | `V21:28-34` `lock_timeout 5s`, `:73-93` 고른 이유·무효 인덱스 거부, runbook §8 Step 0, lane 테스트 3개. 같은 커밋의 V22가 같은 종류의 빈틈을 새로 만들었다(RR-02-09) |
|
||||
| RR-03-06 | 닫힘 | 두 `positional` helper와 그 테스트 삭제, Javadoc 정정(`CleanupClaimSql.java:17-19`) |
|
||||
| RR-03-07 | 닫힘 | `WorkerCrashRecoveryContractTest` 이름·`as()`를 단언 범위로 줄이고 한국어 DisplayName, `CleanupClaimSqlTest` 이름을 "문장 텍스트"로 |
|
||||
| RR-03-08 | 닫힘 | `JdbcReconciliationJobStore.java:74`, 한도 판정 `ReconciliationJobWorker.java:111`, 계약 `ReconciliationJobStoreContract` 추가분 |
|
||||
| RR-03-09 | 닫힘 | `JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`, `JpaProductionArchitectureTest`가 notification·fileserver에 적용, red/green fixture(`OrderEntityReader`) |
|
||||
| RR-03-10 | 결정으로 닫힘 | `FailureCategory.java` Javadoc 첫 문장 "Not a transaction timeout", 이름 변경은 다음 호환성 깨짐 때로 기록 |
|
||||
| RR-05-01 | 닫힘 | runbook §4 두 SQL에 `deferred_attempt_count = 0`, `runbook-sql` 표지와 실 PG lane, claim의 WARN이 `ATTEMPT_COUNTERS_INCONSISTENT`로 원인을 말함(`JpaOutboxStore.java:166-177`). CHECK 제약은 결정으로 넣지 않음 |
|
||||
| RR-05-03 | 결정으로 닫힘(잔여 RR-02-11·12·14) | `OutboxPublishAttempt`, V22 `last_failure_code`, 실패 로그 `error.reason`, `outbox.retry.long.size/age` 게이지·registry·경보, PARKED와 runbook §4.1 SQL 4개(실 PG lane) |
|
||||
| RR-05-04 | 닫힘 | `IntegrationEventDraft`가 비UUIDv7 event id·causation id 거부, durable operation은 결정적 UUIDv7 파생(`SubmitDurableOperationUseCase.java:177-193`), bridge 주석·README의 "until it does" 제거 |
|
||||
| RR-05-05 | 닫힘 | 게이지가 자기 스레드(`OutboxMetrics` SmartLifecycle, `outbox-gauges`)에서 poll 주기로 갱신 |
|
||||
| RR-05-06 | 닫힘 | registry `outcome` 허용 값에 RELEASED, IN_FLIGHT 제거, `OutboxStatusRegistryContractTest`가 outcome label도 비교 |
|
||||
| RR-05-07 | 닫힘 | `FailureDescriptor` Javadoc, vendored 주석에서 소비자 이름 제거, `src/messaging/CLAUDE.md`에 수정 목록과 버린 대안 |
|
||||
| RR-05-08 | 닫힘 | `MessagingShutdownLifecycle.java` POLL Javadoc 위치 복구. 같은 모양의 떨어진 Javadoc이 `OutboxEventEntity`에 새로 생겼다(RR-02-13) |
|
||||
| RR-05-09 | 닫힘 | V21 주석의 클래스명, manual 09 문단, leader election 토큰 삭제, runbook `last_updated` |
|
||||
| RR-05-10 | 닫힘 | 2026-11-01 README 12절 색인에 06-10~06-14와 정정 문단 |
|
||||
| 06-10 | 닫힘(다른 방법, 이유 기록) | 출시한 schema 버전 해시 고정(`ReleasedPayloadSchemaContract`, application-core·sample 적용), manual 09 6단계. 버전 간 diff를 하지 않는 이유를 Javadoc에 적었다 |
|
||||
| 06-11 | 닫힘 | `outbox-inbox.md` 머리말과 두 모델 상태 대응표, `configuration-reference.md` 문장 정정 |
|
||||
| 06-12 | 닫힘 | `batch-size × longestAttempt ≥ in-flight-timeout`이면 기동 실패. 최악 시간 = 기본 기한 5초 × 2(Kafka `max.block.ms`) |
|
||||
| 06-13 | 닫힘 | 낡은 문장 정정, `OutboxLeaderElectionToken` 삭제, `composition:outbox-relay`·`messaging-kafka` CLAUDE.md 신설 |
|
||||
| 06-14 | 닫힘(잔여 RR-02-16) | 읽을 수 없는 레코드 DESERIALIZATION, 예산 소진은 실패의 category 또는 POISON_MESSAGE. 테스트는 SPI 인자를 단언하고 header 쓰기는 테스트가 없다 |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-02-09 — V22가 `outbox_event`의 ACCESS EXCLUSIVE 잠금을 상한 없이 기다려, 그동안 outbox 읽기·쓰기가 모두 멈춘다
|
||||
|
||||
- **위치**: `src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V22__outbox_event_last_failure_code.sql:20-21`. 비교: 같은 커밋의 `V21__outbox_aggregate_sequence.sql:28-34`, `docs/runbooks/outbox-dead-letter.md:119-122`.
|
||||
- **무엇이 틀렸나**:
|
||||
- V22는 `ALTER TABLE outbox_event ADD COLUMN`이다. 이 문장은 ACCESS EXCLUSIVE 잠금을 잡는다.
|
||||
- 열려 있는 트랜잭션 하나가 `outbox_event`를 읽기만 했어도 V22는 그 트랜잭션이 끝날 때까지 기다린다.
|
||||
- 기다리는 동안 뒤에 오는 모든 읽기·쓰기가 V22 뒤에 줄을 선다. ACCESS EXCLUSIVE는 읽기와도 충돌한다.
|
||||
- V22에는 `lock_timeout`이 없다. 같은 커밋이 RR-03-05를 고치며 V21에 "Without a bound, the migration queues behind any open outbox write and every outbox write after it queues behind the migration"이라고 적고 5초 상한을 넣었다. 그 규칙이 바로 다음 마이그레이션에 빠졌다.
|
||||
- **증거(E3, 실 PG 16)**: 세션 A가 `outbox_event`를 읽은 트랜잭션을 20초 열어 두었다. V22는 19.1초 기다린 뒤 적용됐다. 그동안 `pg_locks`에 V22의 `AccessExclusiveLock`이 granted=false로 있었다. 3초 제한을 건 일반 읽기(`SELECT count(*)`)와 일반 쓰기(`UPDATE`)가 둘 다 `canceling statement due to statement timeout`으로 끝났다.
|
||||
- **왜 중요한가**:
|
||||
- 발생 조건: V21 이하 DB를 올리는 첫 배포. Flyway는 기본으로 기동 때 돈다(`persistence-jpa.yml` `flyway.enabled: ${APP_FLYWAY_ENABLED:true}`). 옛 버전이 트래픽을 받는 rolling 배포 중이다.
|
||||
- 영향: 기다리는 시간만큼 outbox를 쓰는 모든 업무 쓰기, relay claim, 모든 인스턴스의 게이지 갱신이 멈춘다. 멈춘 요청은 Hikari 연결을 쥔 채 기다리므로 outbox와 무관한 요청도 연결을 못 받을 수 있다.
|
||||
- 기다리는 시간은 그 순간 가장 오래 열린, `outbox_event`를 건드린 트랜잭션의 남은 시간이다. 앱 트랜잭션은 30초 마감이 있다. 운영자가 runbook 조회를 `BEGIN` 안에서 하고 둔 psql 세션, 백업·분석 질의처럼 앱 밖의 세션에는 상한이 없다.
|
||||
- 1차의 RR-03-05(같은 종류, V21)는 Low였다. 이것을 Medium으로 올린 이유: (1) ACCESS EXCLUSIVE는 SHARE와 달리 읽기까지 막아 relay와 게이지도 선다. (2) 이 라운드가 규칙과 이유를 V21·runbook에 적고 바로 옆 파일에서 어겼다 — 사용자 원칙 "위험은 코드에 드러나야 한다"에 걸리고, 같은 정책의 갈라진 복사본이다.
|
||||
- **고치는 법**:
|
||||
1. V22 맨 앞에 `SET LOCAL lock_timeout = '5s';`와 이유 한 줄을 둔다. V22도 아직 어디에도 적용되지 않았으니 V21처럼 직접 고치고 `applied-migrations.sha256`을 갱신한다.
|
||||
2. `PostgreSqlOutboxOrderKeyRunbookIntegrationTest.v21GivesUpOnALock…`와 같은 테스트를 V22에 둔다. "읽기 트랜잭션이 잡고 있으면 V22는 실패하고 DB는 V21에 남는다".
|
||||
3. 다음 마이그레이션이 같은 빈틈을 다시 만들지 않게 `docs/jpa/migration-guide.md`에 "운영 중인 테이블에 잠금을 거는 DDL은 `SET LOCAL lock_timeout`을 둔다"를 적는다. 가능하면 마이그레이션 테스트가 `ALTER TABLE`/`CREATE INDEX`(비동시)가 있는 파일에 `lock_timeout`이 있는지 검사한다.
|
||||
4. runbook §8에 V22 실패 시 동작(롤백, V21에 남음, 새 버전 기동 실패)을 한 줄 더한다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2. **증거**: E3. **통제**: V22에 대해 M0(V21은 M3).
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-02-10 — tenant scope가 바뀌는 배포의 rolling 구간에서는 새 번호가 옛 버전이 막 쓴 번호보다 작다
|
||||
|
||||
- **위치**: `docs/runbooks/outbox-dead-letter.md:124-131`, `src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxAggregateSequencePort.java:29-31`, `OutboxEventJpaRepository.java:140-169`.
|
||||
- **무엇이 틀렸나**:
|
||||
- floor는 V21이 돈 순간의 값이다. rolling 중 옛 버전은 그 뒤에도 벽시계 번호(초당 10⁶씩 커짐)를 쓴다.
|
||||
- 새 버전의 `GREATEST(…, MAX(행))`는 같은 identity의 행만 본다.
|
||||
- 샘플처럼 scope를 바꾸면 옛 버전은 `portfolio`로, 새 버전은 `global`로 쓴다. 새 번호는 floor+1부터라 옛 버전이 방금 쓴 번호보다 작다.
|
||||
- runbook 124행은 rolling 중 새 번호가 "그 행 뒤에" 온다고 말한다. 포트 계약은 "written under an identity that has since changed" 행보다도 크다고 약속한다. 두 문장이 이 경우에 틀린다.
|
||||
- runbook 128행의 대응은 "배포 전에 옛 scope 미발행 행 확인"뿐이다. 배포 중에 옛 버전이 새로 쓰는 행은 다루지 않는다.
|
||||
- **증거(E3)**: 실 PG에서 floor+30초 번호의 `portfolio` 행 뒤에 `global` scope로 `nextSequence` 문장을 돌리자 floor+1이 나왔다.
|
||||
- **왜 중요한가**: scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한 소비자는 rolling 구간의 새 이벤트를 버린다. 발생은 scope를 바꾸는 배포(현재는 샘플)에 한정된다.
|
||||
- **고치는 법**: runbook §8에 "scope를 바꾸는 배포는 옛 writer를 모두 멈춘 뒤(혼합 버전 금지) 한다"를 적는다. 포트 Javadoc의 그 구절을 "배포 전에 쓰인 행"으로 좁힌다. 또는 샘플만 옛 scope를 유지한다.
|
||||
- Low · P3 · E3.
|
||||
|
||||
#### RR-02-11 — PARKED 행이 하나라도 있으면 옛 버전 인스턴스의 `outbox.pending.size` 게이지가 통째로 꺼진다
|
||||
|
||||
- **위치**: `JpaOutboxStore.java:264`(`OutboxEventStatus.valueOf`), 옛 버전 같은 줄(`7ef8d0b4`·`origin/main`의 `countByStatus`), `V22__outbox_event_last_failure_code.sql:16-19`(PARKED는 DDL 없음).
|
||||
- **무엇이 틀렸나**: `countByStatus`는 DB의 상태 문자열을 enum `valueOf`로 바꾼다. PARKED를 모르는 옛 버전은 `IllegalArgumentException`을 던지고, 게이지 갱신은 그 상태 하나가 아니라 전체가 실패한다(WARN). rolling 배포 중의 옛 인스턴스와, 운영자가 행을 보류한 뒤 롤백한 버전이 해당한다. DB CHECK가 없으니(결정) 수동 SQL 오타 상태값도 같은 일을 일으킨다.
|
||||
- **왜 중요한가**: 보류는 장애 중에 하는 일이고, 장애 중 롤백은 흔하다. 그때 `PENDING size growing` 경보의 입력이 사라진다. 결정(DDL 없음·CHECK 없음)을 뒤집자는 것이 아니라 그 결정이 만든 호환성 위험이다.
|
||||
- **고치는 법**: `countByStatus`가 모르는 상태를 건너뛰거나 `UNKNOWN`으로 모아 세게 한다(새 버전부터라도 이후 상태 추가에 대비). runbook §4.1 Step 2에 "롤백한 버전은 PARKED를 모른다 — 게이지가 꺼지므로 롤백 전에 resume 또는 skip"을 적는다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-02-12 — claim이 DEAD로 옮긴 행은 `last_failure_code`가 낡은 값으로 남고 DEAD 경보도 울리지 않는다
|
||||
|
||||
- **위치**: `JpaOutboxStore.java:166-189`, `OutboxEventEntity.java:70`(`updatable = false`), `docs/runbooks/outbox-dead-letter.md` §1·§2 Step 1.
|
||||
- **무엇이 틀렸나**:
|
||||
- claim 때의 DEAD 전이(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 entity flush로 쓴다. `lastFailureCode`는 읽기 전용이라 이 경로는 원인 코드를 행에 쓰지 못한다. 행에는 이전 재시도의 코드(예: `KAFKA_AUTHENTICATIONEXCEPTION`)가 그대로 남는다.
|
||||
- 이 경로는 relay 결과를 거치지 않아 `outbox.publisher.published.total{outcome=DEAD}`가 오르지 않는다. runbook §1의 경보 조건이 이 카운터다. `outbox.pending.size{status=DEAD}`에는 경보가 없다.
|
||||
- **왜 중요한가**: 운영자가 `SELECT … WHERE status='DEAD'`로 보면 원인을 잘못 읽는다. 경보도 없어 WARN 로그를 찾지 않으면 모른다. 카운터 공백은 1차 RR-05-01이 적은 기존 문제이고, 낡은 원인 코드는 V22가 새로 만든 부분이다.
|
||||
- **고치는 법**: claim의 DEAD 전이를 조건부 UPDATE로 바꿔 `last_failure_code`에 `error.reason`과 같은 값을 쓴다. `outbox.pending.size{status=DEAD} > 0`을 경보 조건에 더하거나 claim DEAD도 카운터에 센다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-02-13 — `OutboxEventEntity`에 주인 없는 Javadoc이 생겼고, 새 필드 주석이 사실과 다르다
|
||||
|
||||
- **위치**: `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/jpa/entity/OutboxEventEntity.java:60-74`.
|
||||
- **무엇이 틀렸나**:
|
||||
- `nextAttemptAt`의 Javadoc("Dual-purpose per status …", 60행)이 새 필드의 Javadoc 바로 위로 떨어졌다. `nextAttemptAt`(74행)에는 설명이 없어졌다. 이 커밋이 RR-05-08로 고친 것과 같은 모양이다.
|
||||
- 새 필드 주석은 append·claim이 "need the column on a database that has not run V22 yet"가 아니라고 말한다. `insertable/updatable = false`는 INSERT·UPDATE에서만 빠진다. Hibernate는 SELECT에 이 열을 넣으므로 claim은 V22 없는 DB에서 실패한다.
|
||||
- **고치는 법**: 60행 주석을 `nextAttemptAt` 위로 옮긴다. 새 필드 주석의 V22 문장을 "INSERT와 flush는 이 열을 쓰지 않는다"로 줄인다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-02-14 — "오래 재시도" 기준 10이 세 곳에 따로 적혀 있고 서로 묶여 있지 않다
|
||||
|
||||
- **위치**: `src/composition/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxMetrics.java:52`, `docs/runbooks/outbox-publish-failed.md:97`, `src/composition/outbox-relay/README.md:118`.
|
||||
- **무엇이 틀렸나**: 게이지는 상수를, runbook SQL은 리터럴 `10`을 쓴다. runbook은 "같은 기준(`OutboxMetrics.LONG_RETRY_DEFERRED_CLAIMS`)으로 센다"고 말하지만 이를 확인하는 테스트가 없다. runbook lane의 테스트 데이터(12와 1)는 상수가 2~12 사이로 바뀌어도 통과한다.
|
||||
- **왜 중요한가**: 상수만 바꾸면 경보가 센 행과 runbook 조회가 보여 주는 행이 달라진다. 사용자 원칙의 "갈라진 복사본"이다.
|
||||
- **고치는 법**: 문서 계약 테스트(`document-contract`)가 runbook 블록의 숫자와 상수를 비교한다. 또는 disposition lane이 경계값(기준-1, 기준)으로 runbook 조회와 `longRetries`를 같이 단언한다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-02-15 — 서로 다른 두 FK로 서로를 가리키는 두 엔티티를 양방향 쌍으로 오판한다
|
||||
|
||||
- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/arch/SingleSidedAssociationCondition.java:84-117`, `docs/jpa/entity-mapping-guide.md:84-91`.
|
||||
- **무엇이 틀렸나**: 규칙은 A의 연관이 B를, B의 연관이 A를 가리키면 위반으로 본다. `Order.@OneToOne latestInvoice`와 `Invoice.@ManyToOne order`처럼 FK가 둘인 두 단방향 링크도 걸린다. 메시지는 "two fields map one link"라고 하지만 링크가 둘이다. 같은 클래스 안의 두 링크(manager·mentor)는 예외로 두면서 두 클래스 사이의 같은 모양은 예외가 없다.
|
||||
- **왜 중요한가**: 금지 쪽으로 틀린 것이라 데이터 위험은 없다. 개발자가 정당한 모델을 바꾸거나 규칙을 끄는 쪽으로 밀린다. 이유를 말하는 메시지가 틀리면 규칙을 믿지 않게 된다.
|
||||
- **고치는 법**: 같은 join column을 두 쪽이 매핑하는지(`@JoinColumn` 이름 비교, 또는 `@OneToMany`↔`@ManyToOne`·`@ManyToMany`↔`@ManyToMany` 짝)로 좁힌다. 아니면 가이드와 메시지를 "서로 가리키는 연관은 FK가 달라도 금지"로 고쳐 의도를 적는다. 어느 쪽이든 그 모양의 fixture를 둔다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR-02-16 — 06-14의 header 쓰기는 테스트가 없고, 공개 SPI 시그니처 변경이 깨지는 변경 목록에 없다
|
||||
|
||||
- **위치**: `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaDeadLetterQuarantine.java:42-52`, `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java:36`, 재리뷰 README 8절.
|
||||
- **무엇이 틀렸나**:
|
||||
- 06-14 완료 기준은 "두 경로가 다른 header 값을 남긴다"다. 새 테스트는 registrar가 SPI에 넘기는 category만 본다. category를 `msg.failure-category` header로 쓰는 `KafkaDeadLetterQuarantine`에는 테스트가 없다.
|
||||
- `KafkaQuarantinePublisher.quarantine`에 인자가 하나 늘었다. 파생 서비스가 이 public SPI를 구현했다면 컴파일이 깨진다. README 8절의 "소유자 확인이 필요한 결정"은 발행·저장소 포트 변경만 적는다.
|
||||
- **고치는 법**: `KafkaDeadLetterQuarantine` 단위 테스트에서 두 category의 header 바이트를 단언한다. 깨지는 변경 목록에 SPI 변경을 더한다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- `ValidatedIntegrationEvent`는 public record라 draft를 거치지 않고 만들면 UUIDv7 검사를 건너뛴다 — 운영 코드의 생성처는 encoder와 저장 행 복원 둘뿐이고, 테스트의 v4 id는 의도된 것이다.
|
||||
- 06-12의 최악 시간에 platform admission 대기(최대 남은 기한)가 들어 있지 않다 — relay는 한 번에 하나씩 보내고, 템플릿에는 같은 destination에 직접 발행하는 다른 publisher가 없다.
|
||||
- 06-12 검사는 `<`라 행마다의 DB 쓰기 시간을 위한 여유가 없다 — 기본값(200초 대 300초)에서는 여유가 크다.
|
||||
- `translateAfterDeadline`은 원인 사슬 전체를 본다. 마감이 지난 뒤 `DataAccessException`을 cause로 감싼 업무 예외는 `DB_QUERY_CANCELED`로 바뀐다 — 그렇게 감싸는 코드를 찾지 못했다(`PosterRepositoryAdapter`는 cause를 넘기지 않는다).
|
||||
- 두 aggregate를 서로 다른 순서로 쓰는 두 트랜잭션의 counter 행 교착 — 1400dc15부터 있던 성질이고 이번 수정이 바꾸지 않았다.
|
||||
- REPEATABLE READ에서 `ON CONFLICT DO NOTHING`은 직렬화 실패를 낸다 — 템플릿은 풀에서 READ COMMITTED를 강제하고 기동 검사가 있다(09-05).
|
||||
- 옛 인스턴스의 시계가 DB보다 느려 floor 아래 번호를 쓰는 경우 — 옛 벽시계 방식이 보장하지 않던 것이고 runbook이 그렇게 적는다.
|
||||
- V21의 `IF NOT EXISTS`는 같은 이름의 "다른 열" 유효 유일 인덱스를 받아들인다 — runbook 문장을 그대로 쓰면 생기지 않는다.
|
||||
- runbook의 표지 없는 SQL(§2 차단 범위 조회, §8 scope 확인, `DROP INDEX CONCURRENTLY`)은 lane이 돌리지 않는다 — runbook 문장이 시험되는 범위를 정확히 적는다. 모든 `runbook-sql` 표지가 어느 테스트에서 쓰이는지 검사하는 장치는 없다.
|
||||
- runbook lane이 문서 절대 경로를 `systemProperty`로 받아 build cache가 다른 경로에서 재사용되지 않는다 — 기존 lane과 같은 방식이고 정확성 문제는 아니다.
|
||||
- idempotency runbook의 "action 자신의 트랜잭션 안 효과는 롤백된다" — 호출자가 executor를 트랜잭션으로 감쌀 때 참이다(샘플은 감싼다). inbound 영역 몫이다.
|
||||
- 06-10이 버전 간 schema diff 대신 출시 버전 불변을 고른 것 — 이유가 Javadoc에 있고, 새 버전은 소비자가 먼저 읽는 절차(application-core README)를 따른다.
|
||||
|
||||
## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가
|
||||
|
||||
**있다. 1건(RR-02-09).** 이 라운드에서 새로 들어온 V22가 V21에 넣은 잠금 대기 상한을 빠뜨렸다. 실 PG에서 읽기·쓰기가 모두 막히는 것을 확인했다.
|
||||
|
||||
고치는 범위는 좁다. V22 한 줄, 같은 모양의 lane 테스트 하나, migration-guide 규칙 한 줄이다. 맡은 1차 발견 25건(RR-03 10건, RR-05 10건, 06-10~14)은 모두 닫혔거나 결정으로 닫혔고 회귀는 없다. 새 Minor 7건 중 6건은 이번 수정이 만든 잔여·문서 불일치이고, 데이터 손상으로 이어지는 것은 없다.
|
||||
|
||||
그래서 이 영역은 전체 재리뷰 라운드가 아니라 RR-02-09만 고치고 그 lane을 돌리는 좁은 수정으로 수렴할 수 있다고 본다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? With fixes.**
|
||||
|
||||
순서 번호·runbook SQL·원인 코드·PARKED·마감 분류는 결정대로 구현됐고 실제 PG·문서 원문으로 검증된다. 다만 같은 커밋의 V22가 outbox 테이블 잠금을 상한 없이 기다려 배포 중 outbox 읽기·쓰기를 멈출 수 있으므로(RR-02-09, E3), V22에 `lock_timeout`과 그 테스트를 넣은 뒤 병합한다.
|
||||
@@ -0,0 +1,268 @@
|
||||
# 03 outbound 재리뷰 (2026-11-03)
|
||||
|
||||
> 2차 재리뷰. 대상은 재리뷰 수정 커밋 `bbe944bd`(Base `7ef8d0b4`)의 outbound capability 영역이다.
|
||||
> 경로는 따로 적지 않으면 `src/adapter/outbound/`를 생략한다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
- `src/adapter/outbound/{support, identifier, redis-runtime, redis-sdk, cache-redis, httpclient, objectstorage, notification, fileserver}`,
|
||||
`docs/httpclient`, `docs/notification`, `docs/registries/metrics.yaml`, `infra/redis-sdk`.
|
||||
`git diff --stat 7ef8d0b4..bbe944bd -- <pathspec>` 기준 78파일, +2,750 −364. diff 전체를 읽었다.
|
||||
- 재확인한 1차 발견: RR-04-01·02·03·05~11(RR-04-04 제외), RR-07-03, RR-07-04, RR-07-07.
|
||||
- pathspec 밖 파일은 판정에 필요한 줄만 읽었다: `application-core` `IdempotencyExecutor`·`IdempotencyClaimRequest`,
|
||||
`composition/idempotency` `IdempotencySettings`·`idempotency.yml`, `persistence-notification` `JpaProviderEventLedger`,
|
||||
`persistence-jpa` 멱등성 claim SQL·reaper, `app-bootstrap` `SecretSourceValidator`, `docs/runbooks/redis-capability-incident.md`,
|
||||
`docker-compose.infra.yml`, `.github/workflows/object-storage-qualification.yml`.
|
||||
- 이 문서의 새 발견 ID는 `RR-03-11`부터다. 1차의 `RR-03-01~10`(그때 03 영역은 persistence)과 겹치지 않게 이어서 매겼다.
|
||||
01 영역 2차 리뷰어(`RR-01-11~`)와 같은 방식이다.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항(1차 "고치는 법"·4절 결정) 대비 정렬, Critical/Important/Minor, 읽은 코드에만 판정 | 출력 양식 전체, 발견 재확인 표 |
|
||||
| `performance-optimization` | "추정 말고 잰다", 바꾼 뒤 다시 잰다, 측정이 잡음 안이면 문제로 올리지 않는다 | JDK read-idle 타이머의 read당 비용과 JVM 전체 상한(측정해 Minor로), lane 대기 Timer의 borrow당 등록 비용(측정 결과 무시할 수준이라 기각), 캐시 전용 lane의 연결 예산 |
|
||||
| `observability-and-instrumentation` | 태그는 닫힌 작은 집합, 지표가 on-call 질문에 답하는가, 계측 실패가 결과를 바꾸지 않되 보이는가, runbook이 실제 신호를 가리키는가 | `redis.lane.*` 태그·histogram 버킷, listener 실패 격리·로그 수준, opened 지표의 뜻, 레지스트리·runbook과 코드의 일치 |
|
||||
| `security-and-hardening` | trust boundary마다 "누가 이 값을 썼나", STRIDE의 R(감사)·D(자원), 공개 비밀값, 서명 범위 | SNS 인증서 4xx를 위조로 보는 근거, `MessageId`가 서명 문자열 안인지, `fixture-` 비밀 거부, ACL fixture 표기 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
checkout은 바꾸지 않았다. Gradle과 worktree는 쓰지 않았다. 탐침은 `git show bbe944bd:<path>`로 꺼낸 사본을 scratchpad에서
|
||||
컴파일했고, Redis는 버리는 컨테이너 하나로 돌렸다.
|
||||
|
||||
| 명령 | 결과 |
|
||||
| --- | --- |
|
||||
| `git diff --stat` / `git diff 7ef8d0b4..bbe944bd -- <pathspec>` | 78파일 |
|
||||
| `javap java.io.FilterInputStream`, `javap java.io.InputStream`, `javap --module java.net.http 'jdk.internal.net.http.ResponseSubscribers$HttpResponseInputStream'` | `FilterInputStream`은 `transferTo`·`readAllBytes`를 재정의하지 않는다 → 감시되는 `read(byte[],int,int)`를 지난다. JDK 응답 stream은 `skip`을 재정의하지 않는다 → `InputStream.skip`이 `read`를 여러 번 부른다 |
|
||||
| `javap -c` Spring 7.0.9 `JdkClientHttpRequest`(Gradle cache) | `disallowedHeaders()`가 `jdk.httpclient.allowRestrictedHeaders`를 읽는다 |
|
||||
| `SkipProbe` — `bbe944bd`의 `ReadIdleInputStream`, 100ms마다 1바이트 주는 stream 30바이트, read-idle 1s | `readAllBytes`: 30바이트 3,018ms 성공. **`skip(30)`: 1,001ms에 `SocketTimeoutException`**(공백은 모두 100ms) |
|
||||
| `Bench` — `guarded()`와 같은 `completeOnTimeout` 걸기 + `cancel` 반복 | 1스레드 3.9~4.6µs/회. 8·32스레드에서 JVM 전체 0.35~0.51M회/초에서 멈춘다. 측정 당시 load average 14~22(22코어) |
|
||||
| `TimerBench` — Micrometer 1.16.7 `SimpleMeterRegistry` | borrow마다 `Timer.builder(..).register(..).record(..)` 152~241ns, 미리 만든 Timer `record` 64ns. Redis 왕복(100µs 이상)에 비해 무시할 수준 → 발견으로 올리지 않음 |
|
||||
| `docker run redis:7.4`(로컬 이미지 `b6b6e3dc0c09`, 고정 digest와 같은 id) + `bbe944bd`의 CLAIM Lua를 `redis-cli EVAL` | owner A claim(lease 3000ms, replay TTL 1000ms) → `ACQUIRED`, `PTTL 996`. 1.3s 뒤 `EXISTS 0`. owner B claim → **`ACQUIRED`**. A의 lease는 1.7s 남아 있었다 |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- Gradle 테스트와 게이트는 다시 돌리지 않았다(재리뷰 README 7절을 읽기만 했다).
|
||||
- Redis 컨테이너 lane·topology lane, MinIO·Toxiproxy lane은 돌리지 않았다. 캐시 전용 배포의 ACL probe가 실제 Redis의
|
||||
거절 메시지(`NOPERM …`)를 맞게 분류하는지는 합성 메시지 테스트로만 확인됐다.
|
||||
- 실제 AWS SNS 인증서 호스트가 없는 인증서에 주는 status, VPC endpoint 경유 동작은 확인하지 못했다.
|
||||
- JDK HTTP/2 스트리밍, TLS 소켓을 JVM 공용 delay 스레드에서 닫을 때의 지연은 보지 않았다.
|
||||
- PostgreSQL 멱등성 저장소(claim SQL, reaper)는 RR-03-11의 범위를 가늠하려고 읽기만 했다.
|
||||
- `app-bootstrap` `SecretSourceValidator`는 RR-07-04 판정에 필요한 diff만 읽었다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- breaker가 deadline 출처를 구분한다. `Deadline.Source`(`httpclient/.../resilience/Deadline.java:28`)를 계산기가 정하고, 같으면
|
||||
profile 쪽으로 기운다(`DeadlineCalculator.java:24-26`). 호출자 deadline으로 끝난 시도는 `releasePermission()`으로 permit만
|
||||
돌려준다(`AttemptResiliencePipeline.java:136-137`). 회귀 테스트가 두 transport × 두 출처를 실제 서버로 본다
|
||||
(`CircuitBreakerStatusAccountingTest.java:178,221`).
|
||||
- JDK 스트리밍이 setup 전용 scope를 따로 연다(`AttemptDeadline.openStreamSetup`, `BlockingStreamingGateway.java:86`). 그래서
|
||||
setup 상한과 본문 gap 상한이 섞이지 않는다. 테스트는 헤더 timeout·전체 예산보다 긴 본문과 read-idle보다 긴 공백을 두
|
||||
transport에서 모두 본다(`StreamingBodyLifetimeTest`).
|
||||
- 캐시 전용 lane의 결정이 코드에 남아 있다. 버린 대안 둘과 이유가 `CacheScriptLane.java:20-24`와 README
|
||||
「Why the cache has its own script lane」(`cache-redis/README.md:192`)에 있다. lane 분리를 SCRIPT 1개를 잡은 상태로
|
||||
증명하는 테스트가 있다(`RedisCacheRegionAdapterTest.java:442`).
|
||||
- lane 지표가 닫힌 이름만 태그로 쓴다. 거절·폐기 counter는 기동 때 0으로 미리 만든다(`RedisLaneMetrics.java:89-108`).
|
||||
listener는 lock 밖에서 부르고, 실패해도 borrow를 깨지 않는다(`RedisRuntimeOwner.java:350-356`, 테스트
|
||||
`RedisLaneMetricsTest.java:277`).
|
||||
- renew의 TTL 연장이 같은 Lua 안에 있어 원자적이다(`IdempotencyScripts.java:186-189`). 공유 계약에 실제 시간이 흐르는 경우가
|
||||
생겼고(`IdempotencyStoreContract.java:373`), 시계를 못 움직이는 저장소는 통과 대신 abort로 보고된다.
|
||||
- ACL probe가 "거절"을 허용 목록으로 판정한다(`RedisSemanticScriptAclProbe.java:124-145`). 끊김·`LOADING`·`BUSY`는 기동을
|
||||
막지 않고, 읽은 값이 틀린 경우는 막는다. 둘 다 테스트가 있다.
|
||||
- `MessageId`는 서명 검증을 통과한 envelope에서만 읽는다(`SesCallbackAdapter.java:126-129`). ledger가 두 유일 인덱스를 모두
|
||||
먼저 조회하고 `ON CONFLICT DO NOTHING`을 대상 없이 쓴다(`JpaProviderEventLedger.java:237`). 그래서 event id가 새로 생겨도
|
||||
제약 위반 예외가 아니라 중복으로 답한다.
|
||||
- SNS 인증서 4xx 중 408·429를 장애 쪽에 남겼다(`NotificationCallbackProviderConfig.java:93`). 검증기는
|
||||
`IllegalArgumentException`을 서명 실패로 바꾼다(`SnsSignatureVerifier.java:89`).
|
||||
- 기동 rule이 앞당긴 bean을 이름으로 보고한다(`StartupRuleRunner.java:66-81`). 정적·무인자 `RequiredProductionSecrets`만
|
||||
예외로 두고, 그 이유가 Javadoc에 있다.
|
||||
- 파일 소유자 규칙이 한 벌이 됐다(`RoleBasedFileAccessPolicy.java:78`의 `subject.owns`). 운영 policy가 fake와 같은 계약을
|
||||
상속한다(`RoleBasedFileAccessPolicyContractTest`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| RR-04-01 | 닫힘 | `BlockingAttemptExecutor.java:156` `deadline.setByCaller() && scope.expired()` → `AttemptResiliencePipeline.java:136-137` `releasePermission()`. total-call로 끊긴 시도는 계속 센다(결정). 두 transport 회귀 테스트. 남은 문서 공백은 RR-03-16 |
|
||||
| RR-04-02 | 닫힘(4절 결정대로) | 캐시 조건부 쓰기가 `CacheScriptLane.CACHE_SCRIPT`(기본 4)로(`RedisCacheRegionAdapter.java:138`, `RedisCacheConfig.java:74-79`). 기여 조건이 캐시 region bean과 같다(`:37`, `:74`). lane별 대기·거절·재연결 지표(`RedisLaneMetrics`). 문서 표류는 RR-03-17 |
|
||||
| RR-04-03 | 닫힘 | `DeadlineAwareJdkRequestFactory.java:49` → `JdkStreamingClientHttpRequest`, 본문은 `ReadIdleInputStream`, 실패는 `ClassifiedBodyInputStream`. 두 transport 테스트. 새 Minor 넷: RR-03-12(skip), RR-03-13(read당 타이머 비용), RR-03-14(unchecked 예외), RR-03-15(헤더 목록 사본) |
|
||||
| RR-04-05 | 닫힘 | `cache-redis/build.gradle:89` `requires`에 `LiveRedisIdempotencyStoreContractTest`. CLAUDE.md 목록도 맞췄다. 결과적으로 lane은 `integrationCheck`에서만 돈다(mainCheck 중복 제거). README 목록 누락은 RR-03-18 |
|
||||
| RR-04-06 | 닫힘 | `package-info.java`, `identifier/CLAUDE.md` Allowed 4개, README가 `build.gradle`과 `modules.json`(`domain-core, application-core, shared-contract`)에 맞는다 |
|
||||
| RR-04-07 | 닫힘 | `RedisSemanticScriptAclProbe.java:124-145` 허용 목록 판정, `LOADING`·끊김·`BUSY` 테스트. 실제 서버 메시지로는 미확인(못 본 것) |
|
||||
| RR-04-08 | **부분** | renew는 고쳤다(`IdempotencyScripts.java:186-189`, 계약 `:373`). claim·takeover는 여전히 key TTL을 replay TTL로 둔다(`:44,77`). replay TTL < processing lease면 lease 중에 key가 사라진다 → RR-03-11(E3) |
|
||||
| RR-04-09 | 닫힘 | `StartupRuleRunner.java:66-81,103-131`(RR-06-01과 같은 수정), 테스트 3건(non-static 규칙, 비정적 secrets, 정적 secrets 허용) |
|
||||
| RR-04-10 | 닫힘 | 순서 키가 `redis-runtime/.../module-defaults/redis-runtime.yml`로 옮겨졌고 cache-redis에서는 빠졌다(중복 키면 기동 실패라 한 곳뿐). `RedisRuntimeHealthStatusOrderTest` |
|
||||
| RR-04-11 | 닫힘 | `JavaMailSenderSmtpDispatch.java:120` `400 <= code < 600`, 테스트 |
|
||||
| RR-07-03 | 닫힘 | 4xx(408·429 제외) → `IllegalArgumentException` → 서명 실패 → 거절·감사. 5xx·408·429·IO → 503. `SnsCertificateFetchTest`. 4xx가 SNS 자신의 답이라는 가정은 Declined to judge |
|
||||
| RR-07-04 | 닫힘 | 파일 이름 `lane-fixture-accounts.acl`, `acl/README.md`가 "배포 파일 아님"과 계정 구성을 실제대로 적는다, compose 4개·`docker-compose.infra.yml` 주석, `SecretSourceValidator`가 prod에서 `fixture-` 값 거부. 프로필 범위는 Declined to judge |
|
||||
| RR-07-07 | 닫힘 | SES 이벤트의 `provider_event_id` = SNS `MessageId`(`SesEventNormalizer.normalize(payload, id)`), Javadoc이 실제 인덱스를 적는다. fingerprint는 event id를 입력으로 쓰지 않아 배포 경계의 재전송도 중복으로 잡힌다(`AesGcmCallbackPayloadProtection.java:112-124`) |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR-03-11 · replay TTL이 processing lease보다 짧으면 Redis 멱등성 key가 lease 도중 사라져, 같은 키의 두 번째 요청이 작업을 다시 돌린다 (RR-04-08 부분)
|
||||
|
||||
- **위치**: `cache-redis/.../idempotency/IdempotencyScripts.java:44`(claim `PEXPIRE ARGV[7]` = replay TTL), `:77`(takeover도 같음),
|
||||
`:186-189`(renew만 늘림). 설정: `src/composition/idempotency/.../IdempotencySettings.java:57,65`(lease와 replay TTL을 따로만 검사),
|
||||
`src/application-core/.../IdempotencyClaimRequest.java:23-24`(관계 검사 없음), `idempotency.yml`의 `replay-ttl: ${APP_IDEMPOTENCY_TTL:24h}`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 이번 수정은 "key TTL이 lease보다 먼저 끝나면 실행 중에 key가 사라져 같은 부작용이 다시 돈다"를 renew 경로에서만 막았다.
|
||||
수정 Javadoc 자신이 원인을 "Claim sets it to the replay TTL, which may be shorter than a lease"라고 적는다.
|
||||
- claim은 여전히 key TTL을 replay TTL로 둔다. replay TTL이 processing lease보다 짧은 설정은 거부되지 않는다.
|
||||
`processing-lease`는 `IN_FLIGHT_RETRY_AFTER`보다 길어야 한다는 검사만 있고, `replay-ttl`은 72h 상한만 있다.
|
||||
- 그 설정에서 action이 replay TTL보다 오래 걸리면 key가 lease 도중 사라진다. 다음 claim은 `ACQUIRED`를 받고 executor는
|
||||
작업을 처음부터 돌린다(`IdempotencyExecutor.java:132-133`). 첫 실행은 아직 진행 중이다.
|
||||
- **왜 중요한가**:
|
||||
- 멱등성이 막으려는 바로 그 피해다. 외부 호출·메일 같은 트랜잭션 밖 효과가 두 번 일어난다. 두 실행이 동시에 돈다.
|
||||
- 발생 조건: `provider=redis` + `APP_IDEMPOTENCY_TTL` < `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s) + action이 replay TTL보다
|
||||
오래 걸림 + 그동안 같은 키 재전송. 변수 이름이 `..._TTL`이고 env 레지스트리 설명도 "완료 응답을 재생하는 시간"뿐이라,
|
||||
"짧은 재생 창"을 원해 10s를 넣는 설정은 그럴듯하다. 두 값의 관계는 어디에도 적혀 있지 않다. 사용자 원칙의 "숨은 위험"이다.
|
||||
- 탐지가 어렵다. 두 번째 요청은 정상 `ACQUIRED` 경로라 로그·지표에 이상이 없다.
|
||||
- RR-01-11(만료된 `EXECUTING`을 `RECOVERY_REQUIRED`로)을 고쳐도 이 경로는 남는다. 기록이 lease가 끝나기 전에, 또는 renew 뒤
|
||||
lease와 같은 순간에 사라지므로 "만료된 EXECUTING"을 볼 기록이 없다. renew가 TTL을 lease와 정확히 같게 두기 때문이다(`:187-188`).
|
||||
- PostgreSQL 저장소도 claim에서 `expires_at = now + replay TTL`을 쓰고 reaper가 상태와 lease를 보지 않고 지운다
|
||||
(`IdempotencyClaimGateway.java:44`, `IdempotencyRecordJpaRepository.java:22-24`, E1). reaper 주기만큼 늦을 뿐 같은 원인으로 보인다.
|
||||
- **고치는 법**:
|
||||
1. 설정에서 막는다(두 저장소를 한 번에): `IdempotencySettings`가 `replay-ttl < processing-lease`이면 기동 실패. env 레지스트리와
|
||||
`idempotency.yml` 주석에 관계를 적는다. 고른 방법·버린 대안을 Javadoc에 남긴다.
|
||||
2. 저장소도 스스로 지킨다: Redis claim·takeover·renew가 key TTL을 `max(replay TTL, lease + 여유)`로 둔다. 여유는 RR-01-11의
|
||||
만료 처리가 기록을 볼 수 있을 만큼(예: replay TTL)이다. "lease와 정확히 같은 TTL"은 피한다.
|
||||
3. 계약에 시간 경우 하나: "replay TTL보다 긴 lease로 claim하면 lease 안의 다른 claim은 `InProgress`". Live Redis·PG lane이 실제로 돈다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2. 피해는 High급(업무 중복 실행)이지만 비기본 설정에서만 도달한다. 기본 조립은 멱등성 비활성.
|
||||
- **증거**: E3 — `redis:7.4` 컨테이너에서 `bbe944bd`의 CLAIM Lua를 직접 실행. lease 3000ms·replay TTL 1000ms claim → 1.3s 뒤
|
||||
key 없음 → 다른 owner claim `ACQUIRED`(A의 lease 1.7s 남음). 설정 경로(`IdempotencySettings`→executor→claim)는 E1.
|
||||
이번 라운드가 만든 결함은 아니다. 1차 RR-04-08이 renew만 짚었고, 같은 원인의 claim 경로가 남았다.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR-03-12 · JDK `ReadIdleInputStream.skip`이 gap이 아니라 skip 전체 시간을 read-idle로 묶는다
|
||||
|
||||
- **위치**: `httpclient/.../jdk/ReadIdleInputStream.java:49-51`(`skip`을 `guarded` 한 번으로), `:53-57`.
|
||||
- **무엇**: JDK 응답 stream은 `skip`을 재정의하지 않는다. 그래서 `InputStream.skip`이 안에서 `read`를 여러 번 부른다. 타이머는
|
||||
그 묶음 전체에 한 번 걸린다. 데이터가 꾸준히 와도 큰 `skip`이 read-idle보다 오래 걸리면 거짓 `SocketTimeoutException`이 나고
|
||||
stream이 닫힌다. 문서는 "본문은 gap마다 read-idle로만 묶인다"고 적는다. `skipNBytes`도 `skip`을 쓴다.
|
||||
- **고치는 법**: `skip`을 직접 구현한다. 작은 버퍼로 `read`를 반복하고, 각 `read`만 `guarded`로 감싼다. 위 탐침을 단위 테스트로 둔다.
|
||||
- **심각도·우선순위**: Low · P3(JDK transport + 스트리밍 + skip 사용에서만). **증거**: E3 — `SkipProbe`: 공백 100ms, read-idle 1s에서
|
||||
`readAllBytes`는 30바이트 성공, `skip(30)`은 1,001ms에 `SocketTimeoutException`.
|
||||
|
||||
#### RR-03-13 · JDK 스트리밍의 read마다 JVM 공용 delay 스케줄러에 타이머를 걸고 지운다
|
||||
|
||||
- **위치**: `httpclient/.../jdk/ReadIdleInputStream.java:53-69`.
|
||||
- **무엇**: `read` 한 번마다 `CompletableFuture.completeOnTimeout`으로 JVM에 하나뿐인 delay 스케줄러 큐에 작업을 넣고 지운다.
|
||||
지울 때 큐의 맨 앞이 바뀌면 그 스레드를 깨운다. 측정: 1스레드 read당 3.9~4.6µs, 여러 스레드에서는 JVM 전체 약 0.5M회/초에서
|
||||
멈춘다. 같은 큐를 `AttemptDeadline`과 Spring JDK 요청 timeout도 쓴다. 16KB read라면 영향이 작다(1GB에 약 0.2초 CPU). 1바이트씩
|
||||
읽는 소비자(`DataInputStream` 등)는 JVM 전체 약 0.5MB/초가 상한이 된다. Apache는 소켓 timeout이라 이 비용이 없다.
|
||||
- **고치는 법**: stream마다 "마지막 진행 시각"(volatile `nanoTime`)만 read에서 갱신한다. 타이머는 read-idle 주기로 한 번 걸고,
|
||||
깨어났을 때 진행이 없으면 닫고 있으면 다시 건다. 전용 `ScheduledExecutorService`를 transport가 하나 갖는 방법도 있다. 고른 방법을
|
||||
주석에 남기고, 위 측정을 전후로 다시 잰다.
|
||||
- **심각도·우선순위**: Low · P3(기본 transport는 Apache). **증거**: E3 — `Bench`(load average 14~22에서 측정, 수치는 크기 정도로만 읽는다).
|
||||
|
||||
#### RR-03-14 · 스트리밍 본문 `InputStream.read`가 이제 unchecked `HttpClientException`을 던지는데, 공개 타입에 적혀 있지 않다
|
||||
|
||||
- **위치**: `httpclient/.../restclient/ClassifiedBodyInputStream.java:34,43,52,61`, `api/result/BlockingStreamingResponse.java`(`body()` Javadoc),
|
||||
`api/error/HttpClientException.java:12`(`extends RuntimeException`).
|
||||
- **무엇**: 이전에는 본문 실패가 `IOException`이었다. 이제는 `HttpResponseTimeoutException`·`HttpResponseTruncatedException`
|
||||
(RuntimeException)이다. 두 transport 모두다(Apache도 바뀌었다). `catch (IOException)`으로 부분 파일을 지우거나 재시도하는 소비자
|
||||
코드는 이 예외를 놓친다. `InputStream` 계약상 `read`가 던지는 것은 `IOException`이다. README와 configuration-reference에는
|
||||
적혔지만 소비자가 보는 `BlockingStreamingResponse.body()`에는 없다.
|
||||
- **고치는 법**: (a) `IOException`을 상속한 본문 예외(예: `HttpBodyReadException`)를 두고 분류된 `HttpClientException`을 cause·accessor로
|
||||
싣는다. 또는 (b) 지금 방식을 유지하되 `body()` Javadoc과 README에 "read는 unchecked `HttpClientException`을 던진다,
|
||||
`IOException` catch로는 잡히지 않는다"를 적는다. 고른 쪽과 이유를 남긴다.
|
||||
- **심각도·우선순위**: Low · P3(템플릿 안 운영 소비자 없음, 파생 서비스의 기존 catch가 영향). **증거**: E1.
|
||||
|
||||
#### RR-03-15 · JDK 스트리밍 요청이 Spring의 금지 헤더 목록을 사본으로 갖고, 원본과 갈라졌다
|
||||
|
||||
- **위치**: `httpclient/.../jdk/JdkStreamingClientHttpRequest.java:44,89,123-127`.
|
||||
- **무엇**: 사본은 다섯 이름을 고정으로 둔다. Spring 7.0.9 `JdkClientHttpRequest.disallowedHeaders()`는
|
||||
`jdk.httpclient.allowRestrictedHeaders` 시스템 속성을 읽어 허용된 이름을 뺀다. 그 속성을 켠 배포에서 같은 profile의 일반 호출은
|
||||
`Host` 등을 보내고 스트리밍 호출은 조용히 버린다. 사용자 원칙의 "갈라진 중복 복사본"이다.
|
||||
- **고치는 법**: 같은 시스템 속성을 읽는다. 또는 사본을 둔 이유와 원본 위치를 주석에 적고, 두 목록이 같은지 보는 테스트를 둔다.
|
||||
- **심각도·우선순위**: Low · P3. **증거**: E1(`javap -c`로 Spring 쪽 확인).
|
||||
|
||||
#### RR-03-16 · 호출자 예산이 stage timeout보다 짧은 profile에서는 죽은 상대를 breaker가 보지 못한다 — 문서에 없다
|
||||
|
||||
- **위치**: `httpclient/.../restclient/BlockingAttemptExecutor.java:156`, `resilience/AttemptResiliencePipeline.java:26-29`(Javadoc),
|
||||
`docs/httpclient/configuration-reference.md` "Two deadlines" 표.
|
||||
- **무엇**:
|
||||
- 코드는 "호출자 deadline이 profile보다 이르고, 실패 시점에 scope가 만료됐으면" 기록하지 않는다.
|
||||
- Javadoc은 "상대가 profile 한도 안에서 답하던 중"인 시도라고 적는다. 코드는 그 조건을 보지 않는다.
|
||||
- 결과: 모든 호출자가 connect·response-header timeout(기본 2s)보다 짧은 예산을 넘기면, 블랙홀이 된 상대(패킷 버림)의 시도는 하나도
|
||||
breaker에 기록되지 않는다. circuit이 열리지 않아 모든 호출이 자기 예산을 끝까지 기다린다.
|
||||
- connect 거절 같은 즉시 실패는 계속 센다.
|
||||
- **고치는 법**: 이 맹점을 configuration-reference 표와 Javadoc에 적는다("호출자 예산이 stage timeout보다 짧으면 hang하는 상대는
|
||||
breaker가 못 본다. 그런 profile은 stage timeout을 호출자 예산보다 짧게 둔다"). Javadoc의 조건 문장을 코드에 맞춘다.
|
||||
- **심각도·우선순위**: Low · P3(결정의 부작용 기록). **증거**: E1.
|
||||
|
||||
#### RR-03-17 · Redis 관측 문서가 지금 나오는 신호와 어긋난다
|
||||
|
||||
- **위치**: `docs/runbooks/redis-capability-incident.md:50,60-63,64-67,74`, `cache-redis/README.md:218`,
|
||||
`docs/registries/metrics.yaml`의 `redis.lane.acquire.wait.seconds` 행, `redis-runtime/.../RedisRuntimeOwner.java:354`.
|
||||
- **무엇**:
|
||||
- runbook의 Detection 절은 "`redis.capability.*`는 내보내지 않는다"로 고쳤다. 그런데 같은 문서의 다른 줄은 그 지표가 있는 것처럼
|
||||
남았다. "semantic operation 계측은 … 결과를 기록한다", "앞선 success 표본과 이 실패를 두 operation으로 합산하지 않는다",
|
||||
"이 meter와 단일-process lifecycle test는…", "reconnect, cache source-load, session repository error 지표의 변화를 함께 본다"
|
||||
(cache source-load·session 지표를 내는 코드가 없다). 레지스트리에서 뺀 `redis.capability.*`의 이름을 직접 부르는 곳은 없다
|
||||
(`git grep` 결과 README 「아직 내보내지 않는 지표」와 runbook 해명 줄뿐).
|
||||
- README는 `opened`를 "warm-up 뒤에는 모두 재연결"이라고 적는다. routed lease(Cluster `TRANSACTION`)는 borrow마다 새로 열고
|
||||
pool에 돌려주지 않으며 `discarded`로도 세지 않는다(`RedisRuntimeOwner.java:265-267`, 반환 시 `discarded == null`). 그 lane에서는
|
||||
정상 동작이 재연결 급증처럼 보인다.
|
||||
- 레지스트리는 대기 timer를 `percentiles: [0.5,0.9,0.95,0.99]`, `histogram_buckets: slo_driven`으로 적는다. 코드는 SLO 경계 없이
|
||||
`publishPercentileHistogram()`만 쓴다(`RedisLaneMetrics.java:117`). p99 경보는 histogram으로 계산되니 동작은 맞고, 표기만 다르다.
|
||||
- listener 실패는 DEBUG로만 남는다(`RedisRuntimeOwner.java:354`). 결과를 바꾸지 않는 것은 맞다. 다만 registry 충돌 등으로
|
||||
지표가 통째로 사라져도 운영 로그에는 흔적이 없다.
|
||||
- **고치는 법**: runbook의 남은 줄을 "설계(미구현)"로 옮기거나 지운다. README에 "routed lease는 매번 연다"를 적거나 routed 열기를
|
||||
다른 reason으로 센다. 레지스트리 행을 코드에 맞춘다. listener 실패는 처음 한 번 WARN으로 남긴다.
|
||||
- **심각도·우선순위**: Low · P3. **증거**: E1.
|
||||
|
||||
#### RR-03-18 · lane의 자리·구성을 바꾼 뒤 옛 문장이 남은 문서
|
||||
|
||||
- **위치**: `objectstorage/README.md:108`("(in `mainCheck`)"), `.github/workflows/object-storage-qualification.yml:4`
|
||||
("they run in its `mainCheck` on main and here"), `cache-redis/README.md:337-338`. 원인 변경: `objectstorage/build.gradle:158-162`
|
||||
(mainCheck 의존 삭제), `cache-redis/build.gradle:89`(멱등성 계약 추가).
|
||||
- **무엇**:
|
||||
- build는 MinIO lane을 `integrationCheck`에만 둔다. 두 문서는 leaf `mainCheck`가 돌린다고 적는다. cache-redis의 같은 변경은
|
||||
README·CLAUDE.md를 함께 고쳤다(`cache-redis/README.md:339-340`).
|
||||
- cache-redis README는 컨테이너 lane이 "cache-region and lease port contracts"를 돈다고 적는다. RR-04-05로 멱등성 계약이
|
||||
더해졌는데 README에는 없다. CLAUDE.md(`:131-139`)는 맞다.
|
||||
- 같은 종류의 사소한 것: `SesEventNormalizer.java:58-59` 주석이 "is keyed / by / the active"로 잘못 줄바꿈됐다.
|
||||
- **고치는 법**: MinIO 두 문장을 "`integrationCheck`(main push·nightly)와 이 workflow"로 고친다. cache-redis README의 계약 목록에
|
||||
멱등성 계약을 넣는다.
|
||||
- **심각도·우선순위**: Low · P3. **증거**: E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- SNS 인증서 URL의 4xx를 "SNS가 없다고 답했다 = 위조"로 보는 가정. 호스트 검사를 통과해도 TLS를 가로채는 egress 장비나
|
||||
private DNS를 켠 SNS VPC endpoint가 답할 수 있다. 그 경로에서 정상 콜백이 400으로 영구 거절되고(SNS는 4xx에 재전송을 멈춘다)
|
||||
감사 로그가 위조로 찬다. 명시 proxy의 CONNECT 실패는 JDK가 `IOException`으로 주므로 503 쪽이다. AWS가 없는 인증서·VPC endpoint
|
||||
경유에 어떤 status를 주는지 확인하지 못해 판단을 미룬다. 확인할 것: 운영과 같은 네트워크에서 존재하지 않는 `.pem`을 받아 보기.
|
||||
- `SecretSourceValidator`의 `fixture-` 거부가 `isProduction()`(prod 프로필)에서만 돈다. 프로필 없음·`staging`은 그대로 기동한다.
|
||||
기존 sentinel 검사와 같은 범위이고, RR-07-02가 문제 삼은 "거부 목록이 prod 하나" 구조와 닮았다. pathspec 밖(app-bootstrap)이라 07 영역에 넘긴다.
|
||||
- PostgreSQL 멱등성 reaper가 `expires_at`만 보고 진행 중 기록도 지우는 것(RR-03-11 근거로 읽음). persistence 영역의 판단이 필요하다.
|
||||
- 캐시 전용 배포에서 advanced 계정 비밀번호가 틀리면(`WRONGPASS`) 연결 단계 실패라 "장애"로 WARN 후 기동한다. 이번 diff 전부터의
|
||||
동작이다. 설정 오류로 볼지는 판단하지 않았다.
|
||||
- `CACHE_SCRIPT`가 pod당 advanced 계정 연결을 최대 4개 늘린다(SCRIPT 8 + 4). Redis `maxclients`와 ACL 계정별 연결 예산에 주는 영향은 판단하지 않았다.
|
||||
- read-idle 타이머가 만료되면 JDK 공용 delay 스레드에서 `in.close()`를 부른다. JDK 응답 stream의 close는 구독 취소라 막히지 않는다고
|
||||
보지만, HTTP/2·TLS에서 재 보지 않았다(1차 Declined와 같은 질문).
|
||||
- lane 대기 Timer를 borrow마다 builder로 등록하는 비용. 측정 결과 152~241ns로 Redis 왕복 대비 무시할 수준이라 발견으로 올리지 않았다.
|
||||
|
||||
## 수렴 판단
|
||||
|
||||
- **이 라운드가 만든 새 Important 이상: 없음.** 수정 diff가 새로 만든 결함은 모두 Minor다(RR-03-12~18). 그중 실행으로 확인한 것은
|
||||
RR-03-12(E3)와 RR-03-13(E3)이고, 둘 다 기본이 아닌 JDK transport의 스트리밍에만 닿는다.
|
||||
- **남은 Important 1건은 덜 닫힌 1차 발견이다.** RR-03-11은 RR-04-08과 같은 원인의 claim 경로다. 이번 라운드가 만든 것이 아니라
|
||||
1차가 renew만 짚어 남은 것이다. 고치는 비용은 설정 검사 몇 줄이다. RR-01-11의 수정과 TTL 규칙을 함께 정해야 한다.
|
||||
- 따라서 이 영역만 보면 수정 라운드는 수렴했다. 다음 라운드가 필요하다면 RR-03-11(및 RR-01-11과의 묶음) 때문이다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge: With fixes.** 1차 발견 13건 중 12건이 코드와 실제 서버 테스트로 닫혔고, 회귀와 이 라운드가 만든 새 Important는 없다.
|
||||
다만 RR-04-08의 claim 경로가 남아 있어(RR-03-11, E3) replay TTL을 processing lease보다 짧게 둔 Redis 배포에서 멱등 작업이 두 번 돈다.
|
||||
@@ -0,0 +1,306 @@
|
||||
# 04 bootstrap·build·sample 재리뷰 (2026-11-03)
|
||||
|
||||
리뷰 대상: Base `7ef8d0b4` → Head `bbe944bd`(재리뷰 수정 커밋), 영역 번호 04(slug `bootstrap-build-sample`).
|
||||
1차 재리뷰 발견 중 이 영역이 맡은 것: RR-06-01~12, RR-07-02, RR-07-05, RR-04-09. 경로는 저장소 루트 기준이다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
```text
|
||||
src/app-bootstrap src/sample-portfolio src/build-logic src/build.gradle src/settings.gradle src/gradle
|
||||
src/gradle.properties src/optional-platforms src/config src/.env.example .github docker-compose*.yml
|
||||
infra/postgres infra/fileserver AGENTS.md CLAUDE.md docs/registries docs/capability-status.md docs/testing
|
||||
```
|
||||
|
||||
`git diff --stat` 기준 83파일 +2,159 −413. 하위 에이전트 없이 여러 번에 나눠 직접 읽었다.
|
||||
|
||||
- 전부 읽은 것: build-logic main diff 전체(`StrictLaneStagesPlugin`, `WorkflowGradleInvocations`,
|
||||
`StrictTestLanePlugin`, `ConfigContractPlugin`, `ConfigurationMetadataClasspath`, `EnvContractVerifier`,
|
||||
`VerifyEnvKeysTask`)와 그 테스트 diff, workflow diff 3개, `src/optional-platforms/build.gradle`,
|
||||
`src/config/spotbugs/exclude.xml` diff, app-bootstrap main·test·architectureTest diff, sample main diff 전체와
|
||||
`application.yml` 전문, sample 보안 테스트 diff, AGENTS.md·CLAUDE.md·`docs/capability-status.md`·
|
||||
`src/build-logic/README.md`·`src/app-bootstrap/README.md`·`CLAUDE.md` diff, `.env.example` diff.
|
||||
- 표본으로 읽은 것: `docs/registries/env-keys.yaml`·`error-codes.yaml`·`secrets-classification.yaml` diff,
|
||||
`metrics.yaml` diff(키 이름만), `docs/testing/TESTING_STRATEGY.md` diff, `OutboxStatusRegistryContractTest` diff.
|
||||
- pathspec 밖에서 확인용으로 읽은 것: `src/adapter/outbound/support/.../startup/StartupRuleRunner.java`·
|
||||
`StartupRule.java`·`RequiredProductionSecrets.java`와 그 테스트 diff(RR-06-01 수정 본체),
|
||||
`src/Dockerfile.sample`, `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`,
|
||||
`src/adapter/outbound/objectstorage/build.gradle`·`ObjectStorageAutoConfiguration.java`,
|
||||
`src/grpc/grpc-testkit/build.gradle`·`GrpcPerformanceLaneTest.java`, `docs/runbooks/job-timeout.md` diff,
|
||||
`scripts/run-compose-runtime-smoke.sh`, `infra/redis-sdk/acl/*.acl`.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → severity별 Issues → Declined → Assessment), "spec이 말하지 않은 동작은 합리적인 사용자의 기대로 판단", 읽기 전용, 의심 결함은 별도 worktree에서 확인 | 수정이 1차 발견의 "고치는 법"을 채웠는지, 수정이 만든 새 결함. 의심 5건을 worktree 실험으로 확인 |
|
||||
| `ci-cd-and-automation` | "No gate can be skipped", Red flag "CI failures ignored or silenced", 캐시 최적화가 결과를 바꾸면 안 된다 | `verifyStrictLaneStages`의 workflow 해석(`-x`·`continue-on-error`·`if:`·`-p`)이 실제 Gradle 계획과 같은지, lane 정책 입력이 캐시 재사용을 불필요하게 깨는지, optional 빌드 단계 연결 |
|
||||
| `security-and-hardening` | 비밀값은 환경에서, 기본값은 닫힘, 오류 메시지는 내부를 드러내지 않음, CSRF는 ambient 자격이 있을 때 의미가 있다 | 데모 계정 허용 목록·기본 프로필 제거, prod `fixture-` 거부 범위, SpotBugs CSRF 제외 축소와 `EnvelopeErrorController` 제외의 근거 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
worktree `scratchpad/rr2-04`(HEAD `bbe944bd`)에서 Gradle을 `flock heavy.lock`으로 감싸 실행했다. 시작 부하 6~40.
|
||||
probe 파일은 worktree에만 만들었고, 끝난 뒤 `git worktree remove --force`로 지웠다. 메인 체크아웃은 건드리지 않았다.
|
||||
|
||||
| # | 명령 | 결과 |
|
||||
| --- | --- | --- |
|
||||
| 1 | build-logic에 reader probe 추가 → `./gradlew -p build-logic test --tests '*RR2WorkflowProbeTest*' --tests '*StrictLaneStagesFunctionalTest.rr2*'` | rc=0. `on: workflow_dispatch`만 있는 workflow의 `:integrationCheck`는 실행으로 셈(`reason=null`). `working-directory: src/optional-platforms` + `../gradlew ci`는 main 빌드 `ci` 실행으로 셈. job `if: ${{ !cancelled() && !failure() }}`는 안 셈. `with: run:`(action 입력)은 실행으로 셈. TestKit: `:integrationCheck -x databaseL --dry-run` 계획에서 Gradle은 `:leaf:databaseLane`을 뺐는데, 같은 줄을 가진 workflow로 `verifyStrictLaneStages`는 **"every strict lane is in an executed stage"로 통과** |
|
||||
| 2 | support·app-bootstrap·sample에 probe 추가 → `./gradlew :adapter:outbound:support:test --tests '*RR2ProbeTest*' :app-bootstrap:test --tests '*RR2FixturePrefixProbeTest*' :sample-portfolio:test --tests '*RR2DemoProfile*' --continue` | rc=1(의도한 실패 14건). 아래 2-a~2-e |
|
||||
| 2-a | support: JavaBean `@ConfigurationProperties("probe2")`가 `RequiredProductionSecrets`를 구현, static 규칙이 `ObjectProvider<RequiredProductionSecrets>.orderedStream()`으로 읽음, `probe2.name=bound` | runner 없음: `name=bound`. runner 있음: **기동 성공, `name=null`**, 경고 없음 |
|
||||
| 2-b | support: `@Import`한 `StartupRule` 클래스에 `@Value("${probe3.mode}")` 필드, `probe3.mode=strict` | **기동 성공, 규칙이 본 값 `null`, 기동 뒤 bean 필드도 `null`** |
|
||||
| 2-c | support: raw `FactoryBean` 컴포넌트(생성자 의존 1개) + 같은 static 규칙 | 기동 성공(오탐 없음). 규칙 없는 대조군도 성공 |
|
||||
| 2-d | app-bootstrap: prod 프로필, `HOSTNAME=fixture-api-6d5f7c9b8-x2k4q`(시스템 환경 소스), `spring.application.name=fixture-service`, `app.messaging.topic=fixture-updates` | 세 이름 모두 위반: `'fixture-' repository fixture password (public, infra/redis-sdk/acl) is configured for HOSTNAME` 등 |
|
||||
| 2-e | sample: `SampleDemoSecurityConfigTest`를 복사해 `app.object-storage.enabled=false`만 빼고 프로필을 `demo`·`test`·`local`로 | `local` 7건 통과. `demo`·`test` 각 7건 **전부 실패**: `Error creating bean with name 'objectStorageCapability' ... object-storage binding is incomplete or invalid` |
|
||||
| 3 | `./gradlew :sample-portfolio:qualityCheck` | rc=0 (PR sample job이 새로 부르는 태스크) |
|
||||
| 4 | `./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run`, `./gradlew :verifyStrictLaneStages --dry-run` | 둘 다 rc=0 |
|
||||
| 4-b | worktree의 `integration-main.yml` optional performance 줄에 `-x grpcPerformanceT` 추가 → 같은 optional 검사, 그리고 `./gradlew -p optional-platforms performanceCheck -x grpcPerformanceT --dry-run` | 검사는 **통과**. 실제 계획에는 `:grpc:grpc-testkit:grpcPerformanceTest`가 없고 `performanceTestLaneCheck`만 있다 — RR-06-03이 닫은 lane이 다시 어디서도 돌지 않는데 검사가 모른다 |
|
||||
|
||||
돌리지 않은 것: `ci`·`mainCheck`·`integrationCheck` 전체(README 7절 오케스트레이터 실행을 근거로 삼았다), `docker build`·
|
||||
`docker run`(Dockerfile.sample은 정적 확인), compose 실제 기동, GitHub Actions 실행.
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 실제 CI runner에서의 workflow 실행, `gradle/actions/setup-gradle`의 캐시 복원 범위.
|
||||
- `docs/registries/metrics.yaml`의 새 `redis.lane.*` 행과 코드가 내보내는 이름의 대조(03·04 outbound 영역 소관).
|
||||
- `env-keys.yaml`에 새로 넣은 행 중 `APP_CACHE_REDIS_MAXIMUM_SCRIPT_CONNECTIONS` 외 다른 영역 행의 의미.
|
||||
- architectureTest의 새 ArchUnit 규칙 2개의 적용 범위(01 core 영역 소관). 실패 fixture가 있다는 것까지만 봤다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **기동 규칙이 앞당긴 bean을 이제 실제로 잡는다.** `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:64-83,100-131`.
|
||||
1차 probe와 같은 모양(설정 bean을 받는 non-static `@Bean` 규칙)이 `probeRule`·`probe-dev.caskeleton`을 대며 기동 실패한다
|
||||
(`StartupRuleRunnerTest.java` 새 테스트 3건). 같은 수정 때문에 기존 테스트 설정 2곳이 static으로 바뀌었다
|
||||
(`ErrorDetailExposureSafetyValidatorTest.java:71`, `RuntimeNumericBoundsValidatorTest.java:81`). 검사가 장식이 아니라는 증거다.
|
||||
- **정상 구성에서 오탐하지 않는다.** 실험 2-c에서 생성자 의존이 있는 raw `FactoryBean`이 있어도 규칙이 `RequiredProductionSecrets`를
|
||||
읽는 동안 다른 singleton이 생기지 않았다. 템플릿의 모든 조립(app-bootstrap·sample·qualification)은 README 7절 게이트에서 기동했다.
|
||||
- **lane 정책이 캐시 입력이 됐고, 바뀌지 않은 lane의 캐시는 그대로 쓴다.** `StrictTestLanePlugin.java:227-240`.
|
||||
정책만 바꾼 두 번째 실행이 "forbids skipped tests"로 실패하는 TestKit(`StrictTestLaneConventionTest.java:549-583`)과,
|
||||
정책을 그대로 둔 hermetic lane이 여전히 `FROM_CACHE`인 기존 TestKit(`:505-547`)이 둘 다 HEAD에서 통과한다. 입력은 모두
|
||||
상수 값(Boolean·String·List)이라 머신 간 캐시 키가 갈라지지 않는다.
|
||||
- **optional 빌드가 자기 lane 도달성을 스스로 검사한다.** `src/optional-platforms/build.gradle:1-7,55-83`,
|
||||
`StrictLaneStagesExtension.java:19-25`. 실험 4에서 `grpcPerformanceTest`가 `-p optional-platforms performanceCheck`로 덮인다.
|
||||
`performanceCheck`·`releaseCheck` 집계로 바뀌어 lane을 더해도 workflow를 고칠 필요가 없다(`release.yml:135`).
|
||||
- **`-x` 경로 지정·`continue-on-error`·비상태 `if:`를 Gradle 계획 위에서 판정한다.** `StrictLaneStagesPlugin.java:120-183`.
|
||||
전체 경로 `-x`는 lane과 그 아래 의존을 계획에서 잘라 낸다. TestKit 4건(`StrictLaneStagesFunctionalTest.java:189-316`).
|
||||
- **env 계약이 leaf 이름을 모른다.** `ConfigContractPlugin.java:21-66`, `VerifyEnvKeysTask.java:50-118`,
|
||||
`src/app-bootstrap/build.gradle:483-488`. metadata classpath가 비면 실패한다(`VerifyEnvKeysTask.java:67-71`).
|
||||
- **CSRF 제외가 클래스 이름으로 좁혀졌고 sample이 처음으로 분석된다.** `src/config/spotbugs/exclude.xml:19-50`,
|
||||
`.github/workflows/ci-quality-gates.yml:73`. 실험 3에서 `:sample-portfolio:qualityCheck`가 통과한다.
|
||||
- **데모 계정 허용 목록이 섞인 프로필도 거부한다.** `SampleDemoAccountsProductionGuard.java:51-65`.
|
||||
`local,prod`·`test,staging`·프로필 없음이 거부되는 테스트가 있다(`SampleDemoAccountsProductionGuardTest.java:70-94`).
|
||||
- **Poster 포트의 충돌 규칙이 코드로 묶였다.** domain 예외(`domain/poster/PosterTitleAlreadyExistsException.java`)와
|
||||
`PosterRepositoryContract`를 in-memory fake와 실 PostgreSQL adapter(`integrationTest` source set)가 함께 상속한다.
|
||||
- **종료 예산의 web drain을 compose가 실제로 주는 값에서 읽는다.** `DeveloperExperienceContractTest.java:412-418,632-639`.
|
||||
runbook도 49초 기준으로 고쳤다(`docs/runbooks/job-timeout.md:51-54`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
상태: 닫힘 / 부분 / 회귀 / 결정으로 닫힘. `>`는 다른 영역 소관.
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| RR-06-01 | 부분 | 1차 probe 모양(non-static `@Bean` 규칙이 설정 bean을 받음)은 기동 실패로 잡힌다(`StartupRuleRunner.java:100-131`). 그러나 새로 생긴 singleton이 `StartupRule`·`RequiredProductionSecrets` 타입이면 묻지 않고 허용한다(`:108-109`). 그 bean 자신이 BPP 없이 만들어지는 경우 — 필드 주입 컴포넌트 규칙, JavaBean 설정 클래스가 비밀 목록을 겸함 — 는 여전히 조용히 바인딩되지 않는다(실험 2-a·2-b) → RR2-04-03 |
|
||||
| RR-06-02 | 닫힘 | `StrictTestLanePlugin.java:227-240` 정책 5개를 입력으로. TestKit `:549-583`. release job `--rerun-tasks`는 결정으로 넣지 않음(README 6절 r4-f) |
|
||||
| RR-06-03 | 닫힘(잔여 RR2-04-04) | `src/optional-platforms/build.gradle:1-7,55-83`, `ci-quality-gates.yml:83-87`, `integration-main.yml:206-211`. 실험 4 통과. 다만 축약 `-x`로 같은 lane을 빼도 검사는 모른다(실험 4-b) |
|
||||
| RR-06-04 | 부분 → RR2-04-04 | 지목한 세 가지(`-x` 전체 경로, `continue-on-error`, 비상태 `if:`)는 닫힘(`WorkflowGradleInvocations.java:236-307`). 축약 `-x`, `on:` 트리거, `working-directory`는 여전히 안 본다(실험 1·4-b) |
|
||||
| RR-06-05 | 닫힘 | sample PR job에 `:sample-portfolio:qualityCheck`(`ci-quality-gates.yml:73`), CSRF Match FQCN화(`exclude.xml:19-50`). 실험 3 통과 |
|
||||
| RR-06-06 | 닫힘 | 죽은 블록 3개 삭제(`sample application.yml`), `SampleRuntimeDefaultsContractTest.java:83-176`이 `app.*` 최상위 묶음마다 sample classpath의 읽는 코드를 요구. 하위 키까지는 보지 않는다(고치는 법이 요구한 수준) |
|
||||
| RR-06-07 | 부분 → RR2-04-05 | lane json·smoke 래퍼의 `APP_*` 키는 이제 등록·읽힘 검사 대상(`ConfigContractPlugin.java:45-62`, `EnvContractVerifier.java:44,216-224`). 1차 발견을 낳은 `CASKELETON_GRPC_ENABLED` 같은 비-`APP_` 키는 여전히 아무 검사도 받지 않는다 |
|
||||
| RR-06-08 | 닫힘 | `DeveloperExperienceContractTest.java:412-418`, `docs/runbooks/job-timeout.md:51-54` |
|
||||
| RR-06-09 | 닫힘 | `src/adapter/outbound/objectstorage/build.gradle:158-162` mainCheck 의존 삭제 |
|
||||
| RR-06-10 | 닫힘 | `ConfigContractPlugin.java`에서 redis-runtime 경로·`dependsOn` 삭제, `ConfigurationMetadataClasspath`, `app-bootstrap/build.gradle:483-488` |
|
||||
| RR-06-11 | 닫힘(새 drift RR2-04-06) | 지목한 7곳 모두 고침(build-logic README:64, grpc-testkit 주석, CLAUDE.md·AGENTS.md mainCheck, runtime.yml·observability.yml, SampleManagementSecurityConfig:24-29, capability-status idempotency 행, sample build.gradle). 이번 수정이 같은 종류의 새 drift를 만들었다 |
|
||||
| RR-06-12 | 닫힘 | domain 예외 + `PosterRepositoryContract`(fake·PG adapter 상속), `PosterRepository.java:12-23`, `WorkLogRepository.java:11-17`이 두 갈래의 이유를 적음 |
|
||||
| RR-07-02 | 결정으로 닫힘(새 결함 RR2-04-02) | 허용 목록 `local`·`test`·`demo`(`SampleDemoAccountsProductionGuard.java:30,51-65`), yml 기본 프로필 삭제(`application.yml:29-32`), bootRun만 `local`을 넘김(`sample-portfolio/build.gradle:248-254`). 결정대로 구현됐다. 그런데 허용한 `test`·`demo`로는 sample이 기동하지 않고, 이미지 실행 문서가 깨졌다 |
|
||||
| RR-07-05 | 닫힘 | `exclude.xml:19-50`. sample 데모 체인은 별도 Match와 이유 |
|
||||
| RR-04-09 | 닫힘 | non-static `@Bean` 규칙은 그 설정 클래스를 만들므로 이름을 대며 실패한다(`StartupRuleRunnerTest` 새 테스트 1·2). 남은 경로는 RR2-04-03 |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
#### RR2-04-01 · prod의 `fixture-` 거부가 모든 설정값을 보아서, 비밀이 아닌 정당한 값으로 운영 기동이 막힌다 (이번 라운드가 만든 결함)
|
||||
|
||||
- **위치**: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java:48,51-54,113-140`.
|
||||
문서: `src/app-bootstrap/README.md:132-136`, `docs/registries/secrets-classification.yaml:13-15`.
|
||||
- **무엇이 틀렸나**: prod 프로필이면 모든 property source의 모든 값을 훑어 `fixture-`로 시작하면 기동을 거부한다.
|
||||
OS 환경 변수도 포함한다. `fixture-`는 이 저장소의 lane 비밀번호 접두사이기 전에 평범한 영어 단어다.
|
||||
거부 대상은 비밀번호가 아니라 "그 접두사로 시작하는 모든 문자열"이다.
|
||||
- **증거 (E3)**: 실험 2-d. prod에서 `HOSTNAME=fixture-api-6d5f7c9b8-x2k4q`, `spring.application.name=fixture-service`,
|
||||
`app.messaging.topic=fixture-updates`가 모두 위반이 됐다. 메시지는 셋 다 "repository fixture password (public,
|
||||
infra/redis-sdk/acl)"라고 말한다.
|
||||
- **왜 중요한가**:
|
||||
- 발생 조건: Kubernetes는 pod 이름을 `HOSTNAME`으로 넣는다. Deployment 이름이 `fixture-`로 시작하면(경기 일정
|
||||
"fixture" 도메인, 테스트 데이터 서비스 등) 모든 pod가 이 값을 가진다. 앱 이름·topic·bucket·key prefix도 같다.
|
||||
- 발견 시점: 검사는 prod 프로필에서만 돈다. dev·staging은 통과하고 첫 운영 배포가 crash loop가 된다.
|
||||
- 우회 수단: 없다. 이름을 바꾸거나 이 클래스를 고쳐야 한다. README는 "설정값이면 이름을 바꾼다"고 적지만,
|
||||
운영자가 `HOSTNAME`을 설정값으로 떠올릴 이유가 없다.
|
||||
- 막으려던 것은 공개된 lane 비밀번호 7개다(`infra/redis-sdk/acl/lane-fixture-accounts.acl`의 `fixture-admin`·
|
||||
`fixture-advanced`·`fixture-application`·`fixture-bootstrap`·`fixture-raw`·`fixture-replication`·`fixture-sentinel`).
|
||||
정확한 값 목록으로도 같은 사고를 막을 수 있어서, 넓은 접두사 일치가 얻는 것은 없다.
|
||||
- **고치는 법**: 결정(prod에서 lane fixture 비밀번호 거부)은 그대로 두고 범위만 좁힌다.
|
||||
1. 접두사가 아니라 저장소가 공개한 값 집합과 정확히 같을 때만 거부한다. 값 목록은 ACL fixture 파일에서 한 번만
|
||||
정의하고, 그 파일과 목록이 같은지 테스트로 묶는다.
|
||||
2. 또는 검사 대상을 비밀값으로 좁힌다: 레지스트리에서 `secret`으로 분류된 키와, `secret://…@environment/<VAR>`
|
||||
참조가 가리키는 변수.
|
||||
3. 메시지는 "lane fixture 비밀번호와 같은 값"이라고 말하고, `HOSTNAME`·`spring.application.name` 같은 값이 통과하는
|
||||
테스트를 둔다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2. 운영에서만 드러나는 기동 실패이고, 원인이 된 값이 정당하다.
|
||||
- **증거 등급**: E3(실험 2-d), prod 전용 경로는 E1(`SecretSourceValidator.java:98`).
|
||||
|
||||
#### RR2-04-02 · 허용 목록의 `test`·`demo`로는 sample이 기동하지 않고, sample 이미지의 실행 문서가 깨졌다 (이번 라운드가 만든 결함)
|
||||
|
||||
- **위치**: `src/sample-portfolio/src/main/resources/application.yml:215-227`(object storage를 끄는 것은 `local` 문서뿐),
|
||||
`SampleDemoAccountsProductionGuard.java:30,44`(remedy가 "local (or test or demo)"를 권함),
|
||||
`src/sample-portfolio/README.md:54-57`(jar·이미지는 "`local`(또는 `test`·`demo`)"), `src/Dockerfile.sample:7-9,14-17`
|
||||
(pathspec 밖), `src/sample-portfolio/src/systemTest/resources/application-test.yml:176-177`(테스트만 object storage를 끔).
|
||||
- **무엇이 틀렸나**:
|
||||
1. object storage 모듈은 classpath에 있으면 켜진다. sample main 설정은 `local` 프로필에서만 끈다.
|
||||
`test`·`demo`로 jar나 이미지를 띄우면 목적지 없는 object storage가 기동을 막는다. `demo` 프로필 문서는 아예 없다.
|
||||
2. `Dockerfile.sample`의 실행 예시는 프로필을 주지 않는다. 이제 그 명령은 종료 코드 71로 끝난다. 머리말의
|
||||
"필요한 외부 의존은 PostgreSQL 하나"도 틀렸다.
|
||||
3. 게이트가 이를 못 본 이유: sample의 모든 Spring 테스트는 `local`이거나, `test` 프로필에 테스트 리소스
|
||||
`application-test.yml`이 object storage를 끈다. 실제 jar의 `test`·`demo`를 띄우는 테스트는 없다.
|
||||
- **증거 (E3)**: 실험 2-e. 같은 slice를 `demo`·`test`로 띄우면 14건 모두 `objectStorageCapability ... object-storage binding
|
||||
is incomplete or invalid`로 실패했고, `local`은 7건 통과했다. 이번 diff의 `SampleDemoSecurityConfigTest.java:57-59`도
|
||||
같은 이유로 `app.object-storage.enabled=false`를 손으로 더했다(주석이 그렇게 말한다).
|
||||
- **왜 중요한가**: sample은 도입자가 가장 먼저 띄우고 복제하는 실행 경로다(가이드 35.3: 템플릿에서는 개발자 경험의
|
||||
실행 경로가 도입 차단 항목이 될 수 있다). 결정이 `demo` 프로필을 새로 허용했지만 그 프로필로는 아무것도 뜨지
|
||||
않는다. 이미지 사용자는 문서대로 하면 거부되고, 거부 메시지가 권하는 두 번째·세 번째 선택지에서 다시
|
||||
프로필과 무관해 보이는 object storage 오류를 만난다. 보안 결함은 아니다(실패는 닫힌 쪽이다).
|
||||
- **고치는 법**:
|
||||
1. sample의 lean demo 기본값(object storage off 등)을 `local` 문서가 아니라 기본 문서에 두거나, 세 데모 프로필
|
||||
모두에 같은 문서를 둔다(`on-profile: local | test | demo`).
|
||||
2. `Dockerfile.sample` 실행 예시에 `-e SPRING_PROFILES_ACTIVE=demo`(또는 `local`)를 넣고, 머리말을 고친다.
|
||||
이미지에 기본 프로필을 굽지 않는 것은 결정대로 둔다.
|
||||
3. 회귀 방지: 허용 목록의 각 프로필로 `SamplePortfolioApplication`을 테스트 리소스 없이 띄우는 테스트 하나
|
||||
(`DEMO_PROFILES`를 파라미터로).
|
||||
- **가이드 심각도·우선순위**: Medium · P2.
|
||||
- **증거 등급**: E3(실험 2-e), Dockerfile 부분은 E1.
|
||||
|
||||
#### RR2-04-03 · 기동 규칙 검사가 `StartupRule`·`RequiredProductionSecrets` 타입이면 묻지 않고 통과시켜, RR-06-01과 같은 "조용히 바인딩 안 됨"이 남는다 (RR-06-01 부분)
|
||||
|
||||
- **위치**: `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:104-110`
|
||||
(타입 면제), `:44-49`(Javadoc "the two kinds that are declared static and argument-free"), `src/app-bootstrap/CLAUDE.md:88-92`,
|
||||
prod 전용 경로 `SecretSourceValidator.java:98,142-147`·`SecretSourceConfig.java:31-35`.
|
||||
- **무엇이 틀렸나**: 검사는 "규칙을 만들거나 돌리는 동안 새로 생긴 singleton"을 본다. 그 singleton이 규칙이나 비밀 목록
|
||||
자신이면 무조건 허용한다. Javadoc은 이 두 종류가 static·인자 없음으로 선언된다고 말하지만, 그 사실은 검사하지 않는다.
|
||||
그래서 bean 자신이 BPP 없이 만들어지는 모양은 빠져나간다.
|
||||
- JavaBean `@ConfigurationProperties` 클래스가 `RequiredProductionSecrets`를 겸하면 바인딩되지 않는다.
|
||||
- `@Component` 규칙의 `@Value` 필드·`@Autowired` 필드는 주입되지 않는다(생성자 `@Value`는 된다).
|
||||
둘 다 다른 singleton을 만들지 않으므로 검사가 볼 것이 없다.
|
||||
- **증거 (E3)**: 실험 2-a. runner가 없으면 `name=bound`, runner가 있으면 기동 성공·`name=null`·경고 없음.
|
||||
실험 2-b. 규칙이 본 값과 기동 뒤 bean의 필드가 모두 `null`, 기동 성공.
|
||||
- **왜 중요한가**:
|
||||
- `RequiredProductionSecrets`는 `SecretSourceValidator`가 prod에서만 꺼낸다(`SecretSourceValidator.java:98`). 그래서 2-a
|
||||
모양은 dev·test·staging에서는 정상 바인딩되고 prod에서만 기본값으로 돈다. 그 설정 bean을 쓰는 런타임 코드도
|
||||
prod에서만 기본값을 본다.
|
||||
- 2-b 모양은 Spring에서 가장 흔한 컴포넌트 작성법이다. 규칙이 항상 `null`을 보면 그 안전 검사가 조용히 꺼진다.
|
||||
- 1차 발견의 핵심은 "개발자가 기억해야 하는 숨은 제약"이었다. 수정 뒤 문서(`StartupRuleRunner` Javadoc, app-bootstrap
|
||||
CLAUDE.md)는 "runner가 막아 준다"고 읽히지만, 이 두 모양은 막지 못한다. 지금 템플릿의 규칙·비밀 목록 선언은
|
||||
모두 static `@Bean`이라 터지는 곳은 없다.
|
||||
- **고치는 법**: 1차 리뷰의 첫째 안을 면제 대상에만 적용한다. 새로 생긴 singleton이 규칙·비밀 목록 타입이면
|
||||
`beanFactory.getBeanDefinition(name)`이 `AnnotatedBeanDefinition`이고 `getFactoryMethodMetadata()`가 static이며 매개변수가
|
||||
`Environment`·`ListableBeanFactory`·`ObjectProvider`뿐일 때만 허용한다. 그 밖(컴포넌트 스캔·`@Import`·
|
||||
`@EnableConfigurationProperties`로 등록된 클래스)은 이름을 대며 실패시킨다. 실험 2-a·2-b를 RED 테스트로 쓴다.
|
||||
- **가이드 심각도·우선순위**: Medium · P2(1차 RR-06-01과 같은 근거·같은 등급).
|
||||
- **증거 등급**: E3(실험 2-a·2-b), prod 전용 경로는 E1.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR2-04-04 · `verifyStrictLaneStages`의 workflow 해석에 남은 틈 — 축약 `-x`, `on:` 트리거, `working-directory`
|
||||
|
||||
- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java:102-110`
|
||||
(`excludes`: 전체 이름만 비교), `:197-230`(트리거·`working-directory`를 읽지 않음), `:236-278`.
|
||||
- **무엇이 틀렸나**:
|
||||
1. Gradle은 `-x`에 축약 이름(camel-case)을 받는다. reader는 이름이 정확히 같을 때만 제외로 본다.
|
||||
2. `if: github.event_name == 'workflow_dispatch'`는 "실행 아님"으로 거부하면서, 같은 뜻의 `on: workflow_dispatch`만 있는
|
||||
workflow는 실행으로 센다.
|
||||
3. `working-directory: src/optional-platforms` + `../gradlew ci`를 main 빌드의 `ci` 실행으로 센다. optional 빌드에는 안 센다.
|
||||
4. `uses:` 단계의 `with: run:` 입력을 실행으로 센다(이전부터).
|
||||
- **증거 (E3)**: 실험 1과 4-b. 실제 `integration-main.yml`에 `-x grpcPerformanceT`를 넣으면 Gradle 계획에서
|
||||
`grpcPerformanceTest`가 빠지는데 optional 검사는 통과한다. 지금 workflow에는 이런 줄이 없다.
|
||||
- **왜 중요한가**: 검사는 "lane이 실제로 돈다"를 증명한다고 문서(AGENTS.md:79-86, CLAUDE.md:40-44)에 적혀 있다.
|
||||
축약 `-x`는 사람이 터미널에서 흔히 쓰는 형태라 workflow로 그대로 옮겨질 수 있다. 그러면 RR-06-03이 막은 상태가
|
||||
조용히 돌아온다.
|
||||
- **고치는 법**: `-x` 판정을 문자열 비교가 아니라 Gradle에 맡긴다. 각 실행 명령의 `-x` 값을 `--dry-run` 계획을
|
||||
다시 만들 때 `StartParameter.excludedTaskNames`로 넘기거나, 계획의 태스크 이름에 Gradle과 같은 camel-case 일치를
|
||||
적용한다. 트리거가 `workflow_dispatch`뿐인 workflow는 `if:`와 같은 이유로 세지 않는다. `working-directory`가
|
||||
있으면 그 경로를 `-p`처럼 읽는다. 각각 reader 단위 테스트 1건.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E3.
|
||||
|
||||
#### RR2-04-05 · lane 활성화 키 검사가 `APP_` 키만 봐서, RR-06-07을 낳은 비-`APP_` 키는 여전히 아무도 안 본다 (RR-06-07 부분)
|
||||
|
||||
- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/config/EnvContractVerifier.java:44`(`JSON_KEY`는
|
||||
`"APP_…"`만), `:225-233`(레지스트리 행에 `property:`가 있으면 "읽힘"), `ConfigContractPlugin.java:45-49`(주석),
|
||||
`EnvContractVerifierTest.java:236-253`.
|
||||
- **무엇이 틀렸나**: 1차 발견의 실제 사례는 `CASKELETON_GRPC_ENABLED`, 즉 `APP_`가 아닌 아무도 읽지 않는 키였다.
|
||||
새 검사는 그 키를 패턴에서부터 건너뛴다. 새 테스트 fixture에 이 키가 들어 있지만 단언하지 않는다. plugin 주석은
|
||||
"이 태스크가 아니라 손으로 찾았다"를 들어 이제는 잡힌다고 읽힌다. 또 레지스트리 행에 `property:`만 있으면 그 property가
|
||||
실제로 있는지(`app.redis.` 밖) 보지 않고 "읽힘"으로 친다.
|
||||
- **왜 중요한가**: compose lane에 오타 난 비-`APP_` 스위치를 넣어도 lane은 다른 이유로 녹색일 수 있다. 1차 결함과 같은 모양이다.
|
||||
- **고치는 법**: lane json의 `activationEnv` 키 중 `APP_`·`SPRING_`·`MANAGEMENT_`·`SERVER_`·`REDIS_LANE_`(문서화된 비밀번호
|
||||
변수) 같은 허용 접두사 밖의 키를 거부한다. fixture의 `CASKELETON_GRPC_ENABLED`를 실패로 단언한다. `property:` 행은
|
||||
qualification classpath metadata에서 그 이름을 찾는다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E1(테스트 본문으로 확인).
|
||||
|
||||
#### RR2-04-06 · 이번 수정이 새로 만든 문서·주석 불일치
|
||||
|
||||
- **무엇이 틀렸나** (모두 E1):
|
||||
- `docs/capability-status.md:42` gRPC transport 행: "`ca-skeleton.grpc.server.enabled` (no `APP_*` row)". 이번 diff가
|
||||
`APP_GRPC_SERVER_ENABLED`(property `app.grpc.server.enabled`, `GrpcServerSettings.java:27`)를 등록했다. object storage 행만 고쳤다.
|
||||
- `src/.env.example:297-299`: "Explicit offs for two more capabilities"라고 쓰고 값은 `true`다.
|
||||
- `src/config/spotbugs/exclude.xml:474-478`: "Only DispatcherType.ERROR reaches it ... meets the normal chain (and its CSRF
|
||||
rules)". 인증된 직접 요청도 이 메서드에 닿고(`EnvelopeErrorController.java:35-37`가 그렇게 말한다), JWT 체인은 CSRF를 끈다.
|
||||
제외가 성립하는 진짜 이유는 "상태를 바꾸지 않고 고정된 실패 envelope만 쓴다"이다. 결론은 맞고 근거 문장이 틀렸다.
|
||||
- `src/Dockerfile.sample:7-9,14-17`: RR2-04-02 참조.
|
||||
- `StartupRuleRunner.java:44-49`, `src/app-bootstrap/CLAUDE.md:88-92`: RR2-04-03 참조.
|
||||
- **고치는 법**: 위 줄을 코드에 맞춘다. exclude 이유는 "부작용 없음, 직접 요청은 인증 체인을 거친다"로 바꾼다.
|
||||
- **심각도·우선순위·증거**: Low · P3 · E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- 데모 허용 목록에 `test`가 있는 것 — 회사마다 외부에 열린 공유 "test" 환경이 있을 수 있다. 4절 결정이라 뒤집지 않는다.
|
||||
- release job이 `--rerun-tasks` 없이 캐시 결과를 증거로 올리는 것 — README 6절 r4-f 결정. 이유는 문서에 없지만, tag 필터가
|
||||
task 입력이라 "tag가 무언가를 고른다"는 증거 의미는 캐시로도 유지된다.
|
||||
- job·단계의 비상태 `if:`(`github.event_name == 'push'`, `!cancelled() && !failure()`)를 실행으로 세지 않는 것 — 정상
|
||||
workflow를 거부할 수 있지만 닫힌 쪽 실패이고 메시지가 이유를 말한다. 결함으로 세지 않았다.
|
||||
- `verifyEnvKeys`가 이제 모든 capability jar를 만든다(qualification classpath) — mainCheck 비용 증가를 측정하지 않았다.
|
||||
- lane 입력 중 `tag`·`mainStage`는 판정에 쓰이지 않거나 이미 다른 입력에 들어 있다 — 캐시를 불필요하게 깨는 경우는
|
||||
그 값을 바꿀 때뿐이라 해가 없다.
|
||||
- IDE에서 `SamplePortfolioApplication`을 프로필 없이 바로 실행하면 거부된다 — 결정의 직접 결과이고 메시지가 해결책을 말한다.
|
||||
- sample 관리 포트에서 데모 체인이 모든 GET을 허용 — 이전부터의 상태(1차 06 Declined).
|
||||
- 새 ArchUnit 규칙 2개(`INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`, `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`)의
|
||||
범위 — 01 영역 소관.
|
||||
- `metrics.yaml`의 `redis.lane.*`·`outbox.retry.long.*` 행과 코드의 일치 — 03·04·05 영역 소관.
|
||||
- `SampleRuntimeDefaultsContractTest`가 `app.*` 최상위 묶음만 보는 것 — RR-06-06 고치는 법이 요구한 수준이다.
|
||||
|
||||
## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가
|
||||
|
||||
**있다. 2건이다.**
|
||||
|
||||
- RR2-04-01: RR-07-04 수정(prod `fixture-` 거부)이 모든 설정값을 보아서, 정당한 값(예: Kubernetes pod 이름 `HOSTNAME`)으로
|
||||
운영 기동만 막힌다.
|
||||
- RR2-04-02: RR-07-02 결정 구현(허용 목록·기본 프로필 삭제)이 허용한 `test`·`demo`로는 sample이 뜨지 않고, sample 이미지
|
||||
실행 문서가 깨졌다.
|
||||
|
||||
그 밖에 1차 Important 하나가 덜 닫혔다. RR-06-01(RR2-04-03)은 1차 probe 모양은 막았지만, 규칙·비밀 목록 bean 자신이
|
||||
바인딩되지 않는 모양은 여전히 조용하다.
|
||||
|
||||
세 건 모두 고치는 범위가 작다. 정확한 값 목록 하나, yml 문서 하나와 Dockerfile 주석, runner의 면제 조건 하나다.
|
||||
다음 수정 라운드는 필요하다. 다만 이 영역에서 구조를 다시 바꿀 일은 아니다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? With fixes.**
|
||||
|
||||
RR-06-02·03·05~12, RR-07-05, RR-04-09는 코드와 실행으로 닫혔고 회귀는 없다. 다만 이번 라운드의 보안·데모 수정이 새
|
||||
Medium 2건(운영에서만 터지는 `fixture-` 오거부, 허용한 데모 프로필로 sample이 뜨지 않음)을 만들었다. RR-06-01도 면제
|
||||
경로가 남았다. 셋 다 merge 전에 고치는 것이 맞다.
|
||||
@@ -0,0 +1,245 @@
|
||||
# 01 core·app·inbound·fileserver 3차 확인 리뷰 (2026-11-04)
|
||||
|
||||
경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
- 리뷰 범위: Base `ecc74b7d` → Head `1885bf8d`(커밋 1개) 중 아래 pathspec. 57파일, +1,700 −199.
|
||||
```text
|
||||
src/application-core src/application-fileserver src/adapter/inbound src/grpc src/composition/service-runtime
|
||||
src/app-bootstrap/src/architectureTest docs/manual/07-authorization.md docs/manual/09-outbox-events.md
|
||||
docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md docs/web/http-contract.md
|
||||
docs/fileserver/operations.md docs/messaging/outbox-inbox.md
|
||||
```
|
||||
- 맡은 2차 재리뷰 발견: RR-01-12~17. RR-01-11은 03 리뷰어가 주로 보고, 이 문서는 `http-contract.md` 문구와 코드가
|
||||
맞는지만 본다.
|
||||
- 나눠 맡은 것: gRPC ledger 마이그레이션의 `lock_timeout`(V002·V003, `GrpcOperationLedgerMigrationLockWaitIT`)은 02 리뷰어 몫이다.
|
||||
`application-core` 멱등성 변경은 계약(포트 Javadoc·공유 계약 케이스·executor 분기)만 봤다.
|
||||
- 이 문서의 새 발견 ID는 `RR3-01-`로 시작한다.
|
||||
- 읽은 방식: 하위 에이전트 없이 diff를 묶음별로 직접 읽었다.
|
||||
1. `@SystemCaller`·`@SystemInvoked`, ArchUnit 두 규칙과 fixture 6개, `PermissionEnforcementGuard`와 테스트,
|
||||
`SystemInvokedConsumePathTest`, `InboxRedeliveryIntegrationTest` diff, 매뉴얼 07·09, messaging README·CLAUDE.md.
|
||||
2. `EnvelopeErrorController`·`HttpStatusErrorCodes`·새 `EnvelopeErrorControllerTest`, `http-contract.md` 두 절.
|
||||
3. `GraphQlClientPolicy` 삭제분과 옮긴 테스트.
|
||||
4. gRPC ledger `release` — 포트, JPA adapter, repository 쿼리, fake, 공유 계약 3케이스, ADR, `GrpcClaimToken` Javadoc.
|
||||
5. `DirectTransactionPort` 전체와 `TransactionPortContract` 새 케이스, `OverlappingWrites`.
|
||||
6. 멱등성 포트 Javadoc, `IdempotencyStoreContract` 시간 케이스 5개, `IdempotencyExecutor` claim·complete 분기.
|
||||
7. `FileQuotaLedgerContract` 롤백 케이스, `FakeFileQuotaService.inTransaction`, `operations.md` 「Namespace quota drift」.
|
||||
- 범위 밖에서 확인용으로 읽은 것:
|
||||
- 쿼터 장부 규칙: `DefaultCleanupService`(reclaim 조건·`isReclaimable`), `FinalizeUploadApplicationUseCase.commitReady`,
|
||||
`CopyFileApplicationUseCase.publish`, `DefaultFileReconciliationService`, `MoveFileApplicationUseCase`, `FileState` 전이표.
|
||||
- 쿼터 영속: `JpaFileQuota`, `JpaQuotaReclaim`, `FileserverQuotaRepository`, fileserver 마이그레이션 V1~V5.
|
||||
- 멱등성: Redis `IdempotencyScripts.CLAIM`.
|
||||
- 의존 경계: `modules.json`의 inbound leaf 간선, `adapter/inbound/messaging/gradle.lockfile`, `app-bootstrap/build.gradle`의
|
||||
architectureTest classpath.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → Critical/Important/Minor → Declined → Assessment), 실제 심각도로 분류, 읽지 않은 코드에 판정 금지, 하위 에이전트 금지 | 문서 양식 전체. 발견마다 round2 "고치는 법"과 9.1절·10절 결정을 코드로 대조 |
|
||||
| `clean-architecture` | 의존은 안쪽으로, 경계는 다형성(포트)으로, composition root가 조립, framework는 바깥 원 | `@SystemCaller`가 application-core에 있는 방향, handler가 use case를 `new`로 만드는 조립 위치, 소비 경로가 web·messaging leaf 간선(`modules.json`)을 넘지 않는지 |
|
||||
| `security-and-hardening` | 인가는 모든 요청에서, 신뢰 경계 지도, 숨은 우회 경로(STRIDE의 권한 상승) | 사용자 전송이 `@SystemInvoked` 쓰기에 닿는 경로를 직접 의존·중첩 클래스·한 단계 건너 호출로 나눠 탐침, 전송 타입 목록의 빈칸 |
|
||||
| `api-and-interface-design` | 계약이 먼저, 일관된 오류 의미(status와 `error.code`), Hyrum's Law, 멱등 키의 세 결과와 in-flight 처리 | `/error` status 접기의 문서·코드 일치, 결과 불명 뒤 같은 키 재전송 판정이 Redis CLAIM과 executor에서 문서대로인지, ledger `release` 포트 시그니처 변경의 호환성 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
| 명령 | 결과 |
|
||||
| --- | --- |
|
||||
| `git diff --stat ecc74b7d..1885bf8d -- <pathspec>` / `git diff …` | 57파일 +1,700 −199 |
|
||||
| `git grep`으로 `effectivePageSize`, 옛 규칙 이름 `INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`, `.release(`·`deleteById`, `reservedBytes` 읽는 곳, `FileState.*` 전이 전수 | 복사본·옛 이름·다른 `release` 호출자 0건. `reservedBytes` 합산은 `status = 'RESERVED'` 쿼리 하나뿐 |
|
||||
| `git worktree add --detach <scratchpad>/rr3-01 1885bf8d` 후 architectureTest에 탐침 테스트 1개와 탐침 클래스 2개 추가, `flock … ./gradlew :app-bootstrap:architectureTest --tests 'dev.caskeleton.bootstrap.architecture.Rr3SystemCallerProbeTest' --console=plain -i` | `BUILD SUCCESSFUL in 14s`. 출력은 아래 표(RR3-01-01 증거) |
|
||||
| `flock … docker run postgres:16-alpine` + `psql` — V1의 `fs_file`·`fs_quota_reservation`과 V5의 `fs_file` 변경을 만들고, 문서의 두 SQL 블록을 문서 그대로 `psql -v namespace=…`로 실행 | 보정 전 drift 2행(`ns-a +140`, `ns-b −140`) → 두 namespace 보정 → 0행. `RESERVED` 999 행은 그대로. 보정 뒤 newest-first reclaim 한 번 → drift 0행 유지. 넣은 행의 `reserved_bytes`가 180(RR3-01-03) |
|
||||
| `git worktree remove --force <scratchpad>/rr3-01`, 컨테이너 `docker rm -f` | 탐침과 함께 삭제. 이 체크아웃은 clean |
|
||||
|
||||
탐침 출력(`RR3-PROBE` 줄 그대로):
|
||||
|
||||
| 탐침 | 가져온 클래스 | `ONLY_SYSTEM_CALLERS_…` 위반 | `SYSTEM_CALLERS_ARE_…` 위반 |
|
||||
| --- | --- | --- | --- |
|
||||
| existing-fixture-web-marked | `SystemCallerControllerFixture` + use case | false | **true** |
|
||||
| existing-fixture-rest-in-messaging | `SystemCallerRestControllerFixture` + use case | false | **true** |
|
||||
| controller-calls-system-caller | `@RestController`가 `SystemCallerHandlerFixture`를 주입받아 `handle()` 호출 + handler + use case | false | false |
|
||||
| nested-endpoint-in-system-caller | `..adapter.inbound.scheduler..`의 `@SystemCaller` 클래스 + 그 안의 `@RestController` nested 클래스(`@PostMapping`에서 use case 호출) + use case | false | false |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 전체 게이트는 다시 돌리지 않았다. 재리뷰 README 10.2절 결과를 읽기만 했다.
|
||||
- `SystemInvokedConsumePathTest`, `InboxRedeliveryIntegrationTest`, gRPC ledger PG lane, `SpringTransactionContractTest`,
|
||||
`PostgreSqlFileQuotaLedgerContractTest`, Redis·PG 멱등성 lane은 다시 돌리지 않았다. 10절의 r5-a·r5-b 검증 기록에 기댄다.
|
||||
- JAX-RS·graphql-java `DataFetcher`로 만든 탐침은 돌리지 않았다. app-bootstrap architectureTest의 컴파일 classpath에 그
|
||||
라이브러리가 없다. RR3-01-02는 규칙 코드를 읽은 것(E1)이다.
|
||||
- 쿼터 SQL은 손으로 만든 시나리오 하나로 돌렸다. 실제 앱이 만든 데이터로 돌린 것은 아니다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- 표시 검사가 실제로 실패한다. 기존 위반 fixture 두 개(`SystemCallerControllerFixture`, `SystemCallerRestControllerFixture`)를
|
||||
탐침에서 따로 돌려 `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS` 위반을 확인했다. 표시 없는 handler(`:214`),
|
||||
web 패키지 표시(`:232`), messaging 패키지의 HTTP endpoint(`:241`)를 각각 단언한다
|
||||
(`src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java`).
|
||||
- 패키지 쪽은 허용 목록이다(`ApplicationBoundaryArchitectureTest.java:456-457`). 새 inbound 패키지는 규칙을 고치지 않아도 표시를
|
||||
달 수 없다.
|
||||
- 기동 가드는 예외를 늘리지 않았다(`PermissionEnforcementGuard.java:69`). 버린 대안("handler만 주입받으면 허용")과 이유가 README에
|
||||
남았다(`src/adapter/inbound/messaging/README.md:104-116`).
|
||||
- 소비 경로가 단위·실제 lane 둘 다로 고정됐다. 단위는 가드 아래 기동과 use case bean 거부다(`SystemInvokedConsumePathTest.java:83,128`).
|
||||
실제 lane은 Kafka+PG `ProjectionHandler`가 같은 모양이다.
|
||||
- `/error`의 status 접기를 문서·Javadoc·테스트가 같은 말로 적는다. 버린 대안도 Javadoc에 있다(`EnvelopeErrorController.java` 클래스 Javadoc,
|
||||
`docs/web/http-contract.md:63-68`, `EnvelopeErrorControllerTest` 8케이스).
|
||||
- ledger `release`가 다른 전이와 같은 조건부 한 문장이다(`GrpcOperationLedgerRepository.java:243-249`). fake와 PG가 공유 계약
|
||||
3케이스를 같이 받는다(`GrpcOperationLedgerContract.java:438,452,470`). "삭제 뒤 attempt 1부터"라는 한계를 Javadoc과 ADR에 적었다.
|
||||
- `DirectTransactionPort`가 스레드별 트랜잭션이다(`DirectTransactionPort.java:56`). 같은 모양의 계약 케이스를 fake와 Spring 어댑터가
|
||||
둘 다 받는다(`TransactionPortContract.java:311`). 이제 `OverlappingWrites`가 fake에서도 두 트랜잭션을 연다.
|
||||
- 쿼터 롤백 계약은 reserve·commit·reclaim을 한 호출자 트랜잭션에서 실패시키고 양쪽 scope를 본다(`FileQuotaLedgerContract.java:320`).
|
||||
`inTransaction`을 abstract로 바꿔 구현마다 실제 롤백을 고르게 했다.
|
||||
- 결과 불명 계약 문구가 코드와 맞는다. CLAIM은 lease가 지난 `EXECUTING`을 `ABANDONED`로 바꾸고 `RECOVERY_REQUIRED`를 준다
|
||||
(`IdempotencyScripts.java:89-93`). 늦게 끝난 holder의 complete는 `NOT_OWNER`이고 executor는 이것을 500으로 바꾼다
|
||||
(`IdempotencyExecutor.java:256`). 공유 계약이 둘 다 묶는다(`IdempotencyStoreContract.java:449,466`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| RR-01-11 (문구만) | 닫힘 | `http-contract.md:119-127`의 "다시 돌리지 않는다·lease 뒤 500·늦은 완료도 500"이 Redis CLAIM(`IdempotencyScripts.java:89-93`), executor complete 분기(`IdempotencyExecutor.java:256`), 공유 계약(`IdempotencyStoreContract.java:449,466`)과 맞다. 예외 Javadoc의 롤백 범위도 "쓰기 트랜잭션 안에서 부른 경우"로 좁혔다(`IdempotencyCompletionUnknownException.java:11-16`). 저장소 구현의 닫힘 판정은 03 몫 |
|
||||
| RR-01-12 | 닫힘(결정대로) | 9.1절 결정이 다 들어갔다. 사용자 전송만 막고 시스템 호출자는 표시로 허용한다(`ApplicationBoundaryArchitectureTest.java:515,539`, `SystemCaller.java`). 매뉴얼 09장 4단계는 테스트로 고정했다(`SystemInvokedConsumePathTest`, `InboxRedeliveryIntegrationTest`). 위반 fixture 실패는 탐침으로 재확인했다. 남은 틈 → RR3-01-01, 02, 04 |
|
||||
| RR-01-13 | 닫힘 | "표에 있는 status만 그대로, 나머지는 class 코드로 접힌다"를 정본과 Javadoc에 적었다(`http-contract.md:63-68`). 실제 표(`HttpStatusErrorCodes.java:20-35`)와 문서의 status 목록이 같다. 파라미터 테스트 8케이스 |
|
||||
| RR-01-14 | 닫힘 | `GraphQlClientPolicy.effectivePageSize` 삭제. 같은 규칙의 다른 복사본은 `GraphQlConnectionPolicy.java:35` 하나뿐이다(grep). 옮긴 테스트(`GraphQlConnectionAssemblerTest` backward 케이스), 업그레이드 안내 B-10 |
|
||||
| RR-01-15 | 닫힘 | `release(identity, claimToken)`은 `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` 한 문장이다(`GrpcOperationLedgerRepository.java:243-249`, `JpaGrpcOperationLedger.java:204`). fake도 같은 조건이다(`InMemoryOperationLedger.java:159`). 계약 3케이스. Javadoc은 "한 행 안에서만"으로 좁혔다(`GrpcClaimToken.java`). main 호출자는 없다(grep) |
|
||||
| RR-01-16 | 닫힘 | `Map<Thread, Transaction>`(`DirectTransactionPort.java:56`)과 계약 케이스(`TransactionPortContract.java:311`). fake와 `SpringTransactionContractTest`(PG)가 상속한다 |
|
||||
| RR-01-17 | 닫힘 | 롤백 계약 케이스는 fake와 `PostgreSqlFileQuotaLedgerContractTest`가 받는다(`FileQuotaLedgerContract.java:320`). 재계산 SQL은 `operations.md` 「Namespace quota drift」에 있다. SQL은 코드의 장부 규칙과 맞는다 — publish와 commit이 한 트랜잭션, 정리 reclaim과 `DELETED` 전이가 한 트랜잭션, `REJECTED`·`EXPIRED`는 `published_at`이 없다. 실 PG16에서 확인했다. 작은 틈 → RR3-01-03 |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR3-01-01 · `@SystemCaller` 규칙은 표시된 클래스의 직접 의존만 본다 — 사용자 전송이 그 bean을 부르거나 그 안에 중첩되면 두 규칙 모두 통과한다
|
||||
|
||||
- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:490-503`(`ARE_SYSTEM_CALLERS`),
|
||||
`:515-527`(`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`), `:539-555`(`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, `.areAnnotatedWith` `:542`),
|
||||
`src/application-core/src/main/java/dev/caskeleton/application/security/SystemCaller.java:23-25`, `docs/manual/07-authorization.md:74`
|
||||
- **무엇이 틀렸나**:
|
||||
- (a) 한 단계 건너 호출. `@RestController`가 `@SystemCaller` handler·job bean을 주입받아 메서드를 부른다. 그 컨트롤러는
|
||||
`@SystemInvoked` 클래스에 직접 의존하지 않으므로 첫 규칙을 통과한다. 표시가 없으므로 둘째 규칙의 대상도 아니다.
|
||||
- (b) 중첩 클래스. 첫 규칙은 `@SystemCaller` 안에 중첩된 클래스를 면제한다(`ARE_SYSTEM_CALLERS`). 둘째 규칙은 표시가 직접 붙은
|
||||
클래스만 검사한다(`:542`). 그래서 표시된 job 안의 `@RestController` nested 클래스는 사용자 전송 타입에 의존해도 아무 규칙에도
|
||||
걸리지 않는다. 면제하는 집합과 검사하는 집합이 다르다.
|
||||
- 문서는 더 강하게 말한다. `SystemCaller.java:25` "nothing but this adapter holds it", 매뉴얼 07장 `:74` "사용자 요청 ─▶ web… ──✗──▶
|
||||
@SystemInvoked (빌드 실패)".
|
||||
- **왜 중요한가**:
|
||||
- 발생 조건: 사용자 전송과 `@SystemCaller`가 같은 Gradle leaf에 있어야 한다. 그 leaf의 컴파일 classpath에 web 타입도 있어야 한다.
|
||||
- 등록된 leaf에서는 막힌다. `adapter:inbound:messaging`의 compileClasspath에는 spring-web이 없다(`gradle.lockfile:240`은 test 쪽만).
|
||||
`adapter:inbound:web`은 messaging leaf에 의존할 수 없다(`modules.json` allowed_dependencies).
|
||||
- `..adapter.inbound.scheduler..`는 등록된 leaf가 없다. 서비스가 이것을 자기 feature leaf에 두면 조건이 선다. sample-portfolio처럼
|
||||
`adapter.inbound.web`과 같은 leaf다.
|
||||
- 영향: "지금 실행" 같은 관리 endpoint가 job bean을 부르면 권한 검사 없는 쓰기가 사용자 요청으로 돈다. 이 템플릿은 인가를 use case에
|
||||
두므로 컨트롤러에는 권한 검사가 없다. 인증만 있으면 누구나 부를 수 있다. 빌드는 아무 신호도 내지 않는다.
|
||||
- 일부는 이전부터다. 한 leaf 안에서 조립 모듈이 만든 scheduler bean을 컨트롤러가 주입받는 길은 지난 라운드에도 있었다. 이번
|
||||
라운드는 시스템 호출자를 inbound 패키지의 bean으로 두는 길을 문서화된 정식 경로로 만들었고, 그 위에 "빌드 실패"를 적었다.
|
||||
- Minor로 둔 이유(경계): 컨트롤러가 job을 부르는 코드가 눈에 보인다. 등록된 leaf 사이에서는 direction gate가 막는다. endpoint는 여전히
|
||||
인증을 요구한다. (b)는 일부러 만들지 않으면 생기지 않는 모양이다.
|
||||
- **고치는 법**:
|
||||
1. 둘째 규칙의 대상을 `.that(ARE_SYSTEM_CALLERS)`로 바꾼다. 면제한 중첩 클래스도 같은 검사를 받는다.
|
||||
2. 규칙 하나를 더한다. 사용자 전송 클래스는 `@SystemCaller` 클래스에 의존하지 않는다. 사용자 전송 클래스는 사용자 전송 패키지에
|
||||
있거나 `ARE_USER_TRANSPORT_TYPES`에 의존하는 클래스다. handler를 등록하는 같은 leaf의 `@Configuration`은 막지 않아야 하므로
|
||||
"inbound 전체" 대신 이 범위로 한다.
|
||||
3. 위 탐침 두 개를 위반 fixture로 넣는다.
|
||||
4. 규칙을 더하지 않는다면, 매뉴얼 07장 `:74`와 `SystemCaller.java:25`에 "한 단계 의존만 본다"를 적는다.
|
||||
- **가이드 심각도·우선순위**: Low · P3 (경계: 같은 leaf 조건이 서면 Medium)
|
||||
- **증거**: E3 — 범위 절 탐침 표의 `controller-calls-system-caller`, `nested-endpoint-in-system-caller` 두 줄. 둘 다 두 규칙 모두 위반 없음.
|
||||
|
||||
#### RR3-01-02 · 사용자 전송 "타입" 검사는 나열 목록이다 — README가 버린 대안의 이유가 이 절반에 그대로 남는다
|
||||
|
||||
- **위치**: `ApplicationBoundaryArchitectureTest.java:466-483`(`ARE_USER_TRANSPORT_TYPES`), `src/adapter/inbound/messaging/README.md:115-116`,
|
||||
`docs/manual/07-authorization.md:89-90`
|
||||
- **무엇이 틀렸나**:
|
||||
- README는 "사용자 전송 패키지만 나열해 금지"를 버렸다. 이유는 "나중에 새 전송이 생기면 조용히 열린다"이다. 매뉴얼 07장도
|
||||
"새 전송이 생겨도 따로 고치지 않아도 막힌다"고 적는다.
|
||||
- 규칙의 패키지 쪽은 허용 목록이라 이 말이 맞다. 그러나 "시스템 패키지 안에 놓인 전송 endpoint"를 잡는 타입 쪽은 나열 목록이다
|
||||
(Spring web·GraphQL·STOMP·gRPC·servlet·`jakarta.websocket`).
|
||||
- 목록에 없는 전송이 있다. JAX-RS(`jakarta.ws.rs`), graphql-java `DataFetcher`(`graphql.schema`), DGS 등이다. 이런 endpoint를
|
||||
messaging·scheduler 패키지에 두고 표시를 달면 통과한다.
|
||||
- **왜 중요한가**: 문서가 약속한 성질("새 전송도 자동으로 막힌다")이 규칙의 절반에서만 참이다. 그 프레임워크가 시스템 호출자
|
||||
leaf의 classpath에 있어야 하므로 발생 조건은 좁다.
|
||||
- **고치는 법**: 두 문서에 "패키지는 허용 목록, 전송 타입은 목록이고 새 전송 라이브러리를 들이면 여기에 더한다"를 적는다.
|
||||
`jakarta.ws.rs..`와 `graphql..`(graphql-java)는 지금 목록에 더한다.
|
||||
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1(규칙 코드와 문서 대조)
|
||||
|
||||
#### RR3-01-03 · 쿼터 보정 SQL이 COMMITTED 행에 `reserved_bytes = held`를 쓴다 — 코드는 확정 행의 예약 바이트를 0으로 둔다
|
||||
|
||||
- **위치**: `docs/fileserver/operations.md:183-187`, 비교 대상 `src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/repository/FileserverQuotaRepository.java`
|
||||
`commit` 쿼리(`q.reservedBytes = 0`), 서술 `operations.md:135-136`
|
||||
- **무엇이 틀렸나**:
|
||||
- INSERT 값이 `held, held`라서 `reserved_bytes`와 `committed_bytes`가 둘 다 재계산 값이다. 코드의 commit은 COMMITTED로 바꾸면서
|
||||
`reserved_bytes`를 0으로 둔다. 코드가 만들지 않는 행 모양이다.
|
||||
- 실 PG에서 보정 뒤 `ns-b | COMMITTED | 180 | 180`이 나왔다.
|
||||
- 서술 `:135-136` "reclaim stops at zero and leaves the old booking behind"는 도착 namespace에 다른 파일의 booking이 없을 때만 맞다.
|
||||
있으면 reclaim이 그 파일들의 booking을 newest-first로 깎는다. PG 시나리오에서 `ns-b`의 두 행이 30→0, 50→40이 됐다.
|
||||
drift 쿼리가 이것도 잡으므로 조치는 맞다.
|
||||
- **왜 중요한가**:
|
||||
- 지금 enforcement는 영향이 없다. `sumReservedBytes`가 `status = 'RESERVED'`만 합산한다(grep 결과 다른 읽는 곳 없음).
|
||||
- 그러나 status 없이 `reserved_bytes`를 합산하는 운영 쿼리·대시보드는 보정한 namespace 크기만큼 부풀린다. 운영자가 손으로 넣는
|
||||
행이 코드 규칙과 갈라지는 것이라 나중에 원인을 찾기 어렵다.
|
||||
- **고치는 법**: INSERT 값을 `0, held`로 바꾼다. `:135-136`은 "도착 namespace에서 회수하므로, 그쪽 다른 파일의 booking을 깎거나
|
||||
0에서 멈춘다"로 고친다.
|
||||
- **가이드 심각도·우선순위**: Low · P3
|
||||
- **증거**: E3 — 실 PostgreSQL 16에 문서의 두 SQL을 그대로 실행했다(범위 절). drift 계산과 보정 결과는 맞고, 넣은 행의
|
||||
`reserved_bytes`만 코드와 다르다.
|
||||
|
||||
#### RR3-01-04 · scheduler 쪽 `@SystemCaller` 경로를 문서마다 다르게 적는다
|
||||
|
||||
- **위치**: 허용 쪽 — `ApplicationBoundaryArchitectureTest.java:456-457`, `SystemCaller.java:10-11`, `SystemInvoked.java:20-22`,
|
||||
`docs/manual/07-authorization.md:87`. 부정 쪽 — `docs/manual/07-authorization.md:75,105-106`, `src/application-core/CLAUDE.md:205-206`,
|
||||
업그레이드 안내 B-16 "해야 할 일" 칸
|
||||
- **무엇이 틀렸나**:
|
||||
- 규칙과 두 Javadoc은 `..adapter.inbound.scheduler..`의 `@SystemCaller` scheduled job을 허용한다. README 10절 "결정" 칸의
|
||||
"scheduler 패키지도 `@SystemCaller` 허용"이다.
|
||||
- 매뉴얼 07장은 다르게 적는다. 흐름도는 scheduler를 "조립 모듈이 new로 넘김" 하나로 그린다. 「지금 이해하면 되는 것」은
|
||||
"부르는 쪽은 스케줄러 조립이나 `@SystemCaller` 메시지 handler뿐이다"라고 적는다.
|
||||
- application-core CLAUDE.md와 B-16도 scheduler는 composition으로만 적는다.
|
||||
- **왜 중요한가**: 두 갈래 설명이다. scheduler 패키지에 대한 작업 순서·위치(등록 leaf 없음)·예시가 어디에도 없다. RR3-01-01의
|
||||
조건이 서는 곳이 바로 이 패키지다.
|
||||
- **고치는 법**: 하나를 고른다.
|
||||
- 허용을 유지하면: 07장 흐름도와 「지금 이해하면 되는 것」, CLAUDE.md, B-16에 세 번째 경로를 넣는다. 어느 leaf에
|
||||
두는지와 RR3-01-01의 주의도 적는다.
|
||||
- 쓰지 않을 거면: `SYSTEM_DRIVEN_INBOUND_PACKAGES`에서 scheduler를 빼고 Javadoc을 맞춘다.
|
||||
- **가이드 심각도·우선순위**: Low · P3 · **증거**: E1
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- gRPC ledger V002·V003 `SET LOCAL lock_timeout`과 `GrpcOperationLedgerMigrationLockWaitIT`: 02 리뷰어 몫으로 나눠 맡았다.
|
||||
- Redis·PG 멱등성 store의 기록 수명(lease + replay TTL)과 설정 검사: 03 리뷰어 몫이다. CLAIM 스크립트는 계약 문구 대조에 필요한 만큼만 읽었다.
|
||||
- `FakeFileQuotaService.inTransaction`은 `DirectTransactionPort.onRollback`과 따로 도는 두 번째 롤백 장치다. use case 테스트(fake +
|
||||
`DirectTransactionPort`)에서는 여전히 쿼터가 롤백되지 않는다. 이번 라운드의 목표(포트가 `inNew`로 옮겨가면 잡기)는 계약 케이스가
|
||||
채운다. use case 테스트가 롤백 뒤 쿼터를 단언하는 곳도 없어서 판정하지 않았다.
|
||||
- `/error`에서 408·409·422가 400 `BAD_PARAMETER`로 접히는 것: 클라이언트가 보는 동작 변화지만, 버린 대안과 함께 Javadoc·정본에 결정으로 적혔다.
|
||||
- `release`가 끝난 기록(`FAILED_TERMINAL` 등)을 지우지 못해 그 키를 다른 요청에 풀어 줄 길이 purge뿐인 것: ADR-GRPC-004에 버린 대안과 함께 적혔다.
|
||||
- optional-platforms 빌드(`grpc:*`)가 ArchUnit import에 없는 것: `app-bootstrap/build.gradle` 주석에 소유자 결정으로 적힌 이전부터의 범위다.
|
||||
- `PermissionEnforcementGuard`가 선언 타입이 인터페이스인 bean을 못 보는 것: 2차 재리뷰가 이미 판정을 미뤘고 이번 diff가 바꾸지 않았다.
|
||||
|
||||
## 수렴 판단
|
||||
|
||||
**이 영역에서 이번 라운드가 만든 새 Important 이상은 없다.**
|
||||
|
||||
- 2차 재리뷰 발견 RR-01-12~17은 모두 닫혔다. RR-01-11의 `http-contract.md` 문구도 코드와 맞는다. 회귀는 없다.
|
||||
- 새 발견은 Minor 4건이다. 셋(RR3-01-01, 02, 04)은 `@SystemCaller` 규칙의 범위와 문서 표현이다. 하나(RR3-01-03)는 보정 SQL의 행
|
||||
모양이다.
|
||||
- 가장 무거운 것은 RR3-01-01이다. 같은 leaf에 사용자 전송과 시스템 호출자를 둔 서비스에서만 서는 경계 사례라 Minor로 뒀다.
|
||||
다음 정리 때 규칙 한 줄(중첩 클래스 검사)과 규칙 하나(전송 → 시스템 호출자 의존 금지)로 닫을 수 있다.
|
||||
- 이 영역만 보면 다음 수정 라운드가 필요하다는 근거는 없다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? Yes**
|
||||
|
||||
9.1절 결정과 round2 "고치는 법"이 코드·계약 테스트·문서에 들어갔다. 실 PG와 ArchUnit 탐침으로 확인한 결과 머지를 막는 결함은 없다.
|
||||
남은 Minor 4건은 규칙 범위와 문서 표현이라 다음 정리 묶음에서 고치면 된다.
|
||||
@@ -0,0 +1,240 @@
|
||||
# 02 persistence·messaging 3차 확인 리뷰 (2026-11-04)
|
||||
|
||||
경로는 저장소 루트 기준이다. 코드 경로는 `src/`가 앞에 붙는다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
- 리뷰 범위: Base `ecc74b7d` → Head `1885bf8d`(커밋 1개, 3차 수정 묶음 r5-c) 중 아래 pathspec. 48파일, +1,719 −134.
|
||||
```text
|
||||
src/adapter/outbound/persistence-jpa src/adapter/outbound/persistence-notification src/composition/outbox-relay
|
||||
src/messaging src/sample-portfolio/src/main/resources/db src/sample-portfolio/src/test
|
||||
src/grpc/grpc-operation-ledger-jpa/src/main/resources src/grpc/grpc-operation-ledger-jpa/src/integrationTest
|
||||
docs/jpa docs/runbooks/migration-failed.md docs/runbooks/outbox-dead-letter.md docs/runbooks/outbox-publish-failed.md
|
||||
docs/manual/04-persistence.md docs/manual/09-outbox-events.md docs/registries/metrics.yaml
|
||||
docs/upgrade/2026-11-maturity-review.md
|
||||
```
|
||||
- 맡은 2차 재리뷰 발견: `round2/02-persistence-messaging.md`의 RR-02-09~16.
|
||||
- 새 발견 ID는 `RR3-02-01`부터다.
|
||||
- 이 pathspec 안이지만 다른 리뷰어 몫이라 결함 판정을 하지 않은 것: persistence-jpa의 PostgreSQL 멱등성 store 변경
|
||||
(`IdempotencyClaimGateway`, `IdempotencyTransitionGateway`, `PostgreSqlIdempotencyStoreContractTest`, README 「만료」 문단 — 03),
|
||||
`docs/manual/09-outbox-events.md`의 `@SystemCaller` 소비 경로 절(01), `SampleDemoSecurityConfigTest`(04),
|
||||
`JpaGrpcOperationLedgerContractIT`의 `release(identity, claimToken)`(01), metrics.yaml의 Redis lane 항목(03).
|
||||
- 읽은 방식: 하위 에이전트 없이 여러 번에 나눠 직접 읽었다.
|
||||
1. 마이그레이션 8개 diff 전부와 `applied-migrations.sha256`, `git log`로 각 파일이 main(`01a8a2a70`)에 있었는지.
|
||||
2. `LockWaitMigrationInspector` 전문, `MigrationLockWaitTest`·`MigrationTrees`·`AppliedMigrationImmutabilityTest` diff,
|
||||
`SampleMigrationLockWaitTest`, `LockWaitMigrationInspectorTest` 케이스, `ConcurrentIndexMigrationInspector`와 그 사용처.
|
||||
3. `PostgreSqlMigrationLockWaitIntegrationTest`, `GrpcOperationLedgerMigrationLockWaitIT`, `GrpcOperationLedgerMigrations` diff.
|
||||
4. `JpaOutboxStore`·`OutboxEventEntity` diff와 claim 경로(`PostgreSqlOutboxClaimRepository`의 `FOR UPDATE SKIP LOCKED`,
|
||||
`OutboxEventJpaRepository`의 fenced UPDATE), entity를 바꾸는 다른 경로가 있는지(grep: claim만 있다).
|
||||
5. `OutboxMetrics`의 게이지 갱신, `countLongRetries` JPQL, `OutboxLongRetryRunbookContractTest`와 그 lane 설정.
|
||||
6. `SingleSidedAssociationCondition` diff와 새 fixture, `KafkaDeadLetterQuarantine`과 새 테스트.
|
||||
7. runbook 세 개·migration-guide·entity-mapping-guide·manual 04·09·metrics.yaml·upgrade 문서의 이 영역 diff,
|
||||
운영자가 쓰는 `infra/postgres/apply-capability-streams.sh`(Flyway CLI 기본 트랜잭션인지).
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
|---|---|---|
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항(9.1절 결정·round2 「고치는 법」) 정합, 테스트가 mock이 아닌 실제 동작을 보는지, 마이그레이션 전략·하위 호환, Declined to judge, 심각도 보정, 읽지 않은 코드를 칭찬하지 않기 | 발견 8건의 닫힘 여부, 새 lane이 RED가 되는지 직접 확인, 이미 적용된 파일을 고쳤는지 git 이력으로 확인 |
|
||||
| `jpa-patterns` | Flyway가 스키마를 소유하고 Hibernate는 validate만, 짧은 트랜잭션, entity 갱신의 실제 SQL(전체 열 UPDATE), 연관관계 규칙(사용자 원칙 "양방향 금지") | `last_failure_code`를 `updatable`로 바꾼 뒤의 claim flush가 다른 relay·fenced UPDATE와 겹칠 때(RR-02-12), `why()` 메시지가 join column·join table 구조와 맞는지(RR-02-15·RR3-02-05) |
|
||||
| `supabase-postgres-best-practices` | `lock-short-transactions`(DDL 잠금 대기는 `lock_timeout`으로 묶는다), `lock-skip-locked`(claim은 잠긴 행을 건너뛴다), `schema-foreign-key-indexes`(FK가 부모 표를 잠근다), `monitor-*`(`pg_stat_activity`·`pg_locks`로 원인 세션 찾기) | `SET LOCAL`이 Flyway 트랜잭션 안에서 걸리는지(실 PG lane, RED 확인), 트랜잭션 밖이면 무효인지(실 PG), 검사기가 못 잡는 잠금 문장(실 PG), runbook의 원인 세션 조회가 원인을 가려내는지(실 PG) |
|
||||
| `observability-and-instrumentation` | 경보는 증상 기반·실행 가능·runbook 연결, 지표 label 집합이 작고 고정, 모르는 값은 조용히 버리지 말고 이름을 남긴다 | `outbox.pending.size{status=DEAD} > 0` p1 경보(해소 경로가 있는지 — 재발행·skip 모두 DEAD를 벗어난다), 모르는 상태 값 WARN 1회, lag 게이지가 그 행을 여전히 세는지 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
메인 작업 트리·index·HEAD는 바꾸지 않았다(끝에 `git status --short` 빈 출력). 실행은 scratchpad에서 했다.
|
||||
|
||||
| 명령 | 실행 직전 부하(1분) | 결과 |
|
||||
|---|---|---|
|
||||
| `git diff --stat ecc74b7d..1885bf8d -- <pathspec>`, `git diff ...` | — | 48파일. 나눠서 전부 읽었다 |
|
||||
| `git log --follow`·`git cat-file -e 01a8a2a70:<path>` (고친 마이그레이션 9개) | — | 9개 모두 main에 없다. 처음 들어온 커밋은 `34565130`·`1400dc15`·`5786126c`·`bbe944bd`, 모두 이 브랜치에만 있다(`git branch -a --contains`: 이 브랜치와 그 origin 추적 브랜치). 파생 서비스 `tech-log-backend`에는 네 커밋 모두 없다 |
|
||||
| 동결 목록 24개 각각 `git ls-tree 01a8a2a70` | — | 24개 모두 main에 있다 |
|
||||
| `sha256sum` V20·V22·알림 V11~V13 vs `applied-migrations.sha256` | — | 5개 모두 일치 |
|
||||
| `javac`+`java Probe` (scratchpad, `LockWaitMigrationInspector`를 `git show 1885bf8d:`로 꺼내 컴파일) | — | FK가 있는 `CREATE TABLE`, `CREATE TRIGGER`, `DROP TRIGGER`, `REINDEX TABLE` → `[]`(못 잡음). `SET LOCAL lock_timeout = 0` → 상한으로 인정. 열 이름 `lock` → 오탐. 대조군 `ALTER TABLE` → 잡음 |
|
||||
| `flock heavy.lock exp.sh` (postgres:16-alpine, 컨테이너 안 psql) | 2.24 | rc=0. **EXP1**: `parent`에 쓴 트랜잭션을 12초 열어 둠 → `CREATE TABLE child (... REFERENCES parent)`가 `ShareRowExclusiveLock` granted=false로 11.09초 기다림, 그동안 3초 제한의 `INSERT INTO parent`가 `canceling statement due to statement timeout`(3.06초). **EXP2**: 트랜잭션 밖 `SET LOCAL lock_timeout`은 `WARNING: SET LOCAL can only be used in transaction blocks` |
|
||||
| `flock heavy.lock exp2.sh` (같은 이미지) | 2.4 근처 | rc=0. `outbox_event`를 읽은 뒤 다른 문장을 하나 더 하고 idle in transaction인 세션(93)과, 다른 표만 읽은 보고 세션(91)을 열어 둠 → 상한 있는 `ALTER TABLE`은 `canceling statement due to lock timeout`. runbook 조회(`pg_stat_activity WHERE xact_start < now() - 5s`)는 **91·93 둘 다** 내고 93의 `query`는 `SELECT 1 AS later_statement`. `pg_locks`의 `relation = 'outbox_event'::regclass`는 93만 낸다 |
|
||||
| worktree `git worktree add --detach <scratchpad>/rr3-02 1885bf8d` 후 `flock heavy.lock ./gradlew :adapter:outbound:persistence-jpa:postgresqlMigrationLockWaitIntegrationTest :adapter:outbound:persistence-jpa:test --tests '*MigrationLockWaitTest' --tests '*LockWaitMigrationInspectorTest' --console=plain` | 3.19 | rc=0, 35초. lane 5/5(V20·V22·알림 V11·V12·V13 각각 5.25~5.60초 — 상한 5초에서 끝남), `MigrationLockWaitTest` 2/2, `LockWaitMigrationInspectorTest` 16/16 |
|
||||
| 같은 worktree에서 V22의 `SET LOCAL` 줄을 지우고 같은 lane | — | **rc=1, V22 케이스만 FAILED**(5개 중 1개). lane이 상한 누락을 실제로 잡는다(RED 확인). 파일 되돌린 뒤 `git worktree remove --force` |
|
||||
| `java Re.java` (scratchpad) | — | `V22_1__x.sql`: `MigrationTrees` 정규식 false, sample 정규식 true |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 알림·sample·grpc 마이그레이션의 실 PG 실행은 게이트 기록(재리뷰 README 10.2)과 위 lane 5개를 따랐다. sample V8_1은 실 PG
|
||||
잠금 대기 테스트가 없고 텍스트 검사만 있다(Declined 참고).
|
||||
- `GrpcOperationLedgerMigrationLockWaitIT`는 직접 돌리지 않았다(`-p optional-platforms integrationCheck` 게이트 기록을 따름).
|
||||
이 테스트는 Flyway가 아니라 JDBC로 한 트랜잭션에 파일 전체를 실행한다.
|
||||
- claim DEAD 전이와 옛 lease 소유자의 fenced UPDATE 경쟁은 실행하지 않았다. PostgreSQL READ COMMITTED의 `FOR UPDATE`
|
||||
재검사 규칙과 코드 경로로 판단했다(E1).
|
||||
- 실제 Kafka broker, 다중 인스턴스 동시 기동은 실행하지 않았다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **이미 배포된 파일과 아닌 파일을 git 이력으로 갈랐다.** 고친 9개는 모두 main에 없고, 동결 목록 24개는 모두 main에
|
||||
있다(위 명령). 각 파일 머리말이 "branch not merged, recreate the dev DB"를 적고, 업그레이드 안내 표 9행과 4.2절이 같은
|
||||
조치를 말한다(`docs/upgrade/2026-11-maturity-review.md:30,141-147`).
|
||||
- **잠금 상한이 실제 Flyway 실행에서 걸리는 것을 RED까지 확인할 수 있다.** `PostgreSqlMigrationLockWaitIntegrationTest.java:59-111`은
|
||||
진짜 `Flyway.migrate()`를 읽기 트랜잭션 뒤에서 돌리고, 상한이 없으면 15초 뒤 적용되어 실패하는 모양이다. 이 리뷰에서
|
||||
V22의 상한을 지우자 그 케이스만 실패했다.
|
||||
- **규칙이 다음 파일로 이어진다.** `MigrationLockWaitTest.java:60-91`은 새 파일을 거부하고, 동결 목록의 파일이 더는 걸리지
|
||||
않으면 그것도 실패한다(목록이 조용히 남아 다음 파일을 숨기지 못한다). 목록 갱신 대상 tree는 `MigrationTrees` 하나로
|
||||
합쳐 immutability 검사와 같은 목록을 쓴다.
|
||||
- **claim DEAD의 원인 코드를 row lock 아래에서 쓴다.** `JpaOutboxStore.java:206-214`. claim이 `FOR UPDATE SKIP LOCKED`로 잡은
|
||||
행만 바꾸고(`PostgreSqlOutboxClaimRepository.java:39`), 토큰을 먼저 올리므로 옛 lease 소유자의 fenced UPDATE는 잠금을
|
||||
기다린 뒤 0행이 된다. entity를 바꾸는 경로는 claim 하나뿐이라 `updatable`로 바꿔도 잠금 없이 낡은 값을 덮는 경로가 없다.
|
||||
실 PG 테스트가 결과를 행에서 읽는다(`PostgreSqlOutboxDispositionRunbookIntegrationTest.java:84-100`).
|
||||
- **DEAD 경보에 해소 경로가 있다.** `metrics.yaml:396`의 `DEAD > 0`은 runbook §4의 재발행·skip이 모두 행을 DEAD 밖으로
|
||||
옮기므로 계속 울리는 경보가 되지 않는다.
|
||||
- **모르는 상태 값이 게이지 전체를 끄지 않는다.** `JpaOutboxStore.java:281-300`. 이름과 행 수를 WARN 한 번으로 남기고,
|
||||
그 행은 `outbox.publisher.lag`(`status <> 'PUBLISHED'`)에는 계속 잡힌다.
|
||||
- **runbook 숫자와 상수를 문서 입력이 선언된 main 단계 lane으로 묶었다.** `OutboxLongRetryRunbookContractTest`와
|
||||
`src/composition/outbox-relay/build.gradle:45-61`. 블록이 사라지거나 비교 연산자가 바뀌어도 빈 목록이라 실패한다.
|
||||
- **header 테스트가 실제 바이트를 본다.** `KafkaDeadLetterQuarantineTest`는 `MockProducer`가 받은 레코드의 header 값을 읽고,
|
||||
이전 hop의 낡은 category를 지우는지도 본다.
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
|---|---|---|
|
||||
| RR-02-09 | 닫힘 | 8개 파일 첫 문장 `SET LOCAL lock_timeout = '5s'`(V20:27, V22:32, 알림 V11:25·V12:29·V13:22, V8_1:28, grpc V002:25·V003:27). 실 PG lane `postgresqlMigrationLockWaitIntegrationTest` 5/5, V22 상한을 지우면 RED(이 리뷰 실행, E2·E3). 텍스트 검사 `MigrationLockWaitTest`·`SampleMigrationLockWaitTest`. 가이드 `migration-guide.md:35-61`, runbook `outbox-dead-letter.md` §8·`migration-failed.md:43-49`. 잔여: 검사기 범위(RR3-02-01), 원인 세션 조회(RR3-02-02), 소수 버전(RR3-02-03), grpc tree(RR3-02-04) — 모두 Minor |
|
||||
| RR-02-10 | 결정으로 닫힘 | 9.1절 밖이지만 round2 「고치는 법」의 문서 방향. `JpaOutboxStore.java` nextSequence Javadoc, 포트 `OutboxAggregateSequencePort.java:29-37`, runbook `outbox-dead-letter.md:139-145`, manual 09 73-78행 |
|
||||
| RR-02-11 | 닫힘 | `JpaOutboxStore.java:281-309`, 단위 테스트 2개(아는 상태는 그대로 셈, WARN 1회), runbook `outbox-publish-failed.md:118-122`(롤백 전 보류 해제) |
|
||||
| RR-02-12 | 닫힘 | `OutboxEventEntity.java:69`(`updatable` 허용), `JpaOutboxStore.java:206-214`, 단위 테스트, 실 PG 테스트(행의 `last_failure_code`가 `ATTEMPT_COUNTERS_INCONSISTENT`), `metrics.yaml:396` p1, runbook §1·§2 Step 1 |
|
||||
| RR-02-13 | 닫힘 | `OutboxEventEntity.java:59-73`: `nextAttemptAt` Javadoc 제자리, V22 관련 틀린 문장 삭제 |
|
||||
| RR-02-14 | 닫힘 | `OutboxLongRetryRunbookContractTest`, lane `outboxRelayDocumentContractTest`(`mainStage`, runbook을 input으로), runbook 89-90행 안내. JPQL도 `>=`로 같다(`OutboxEventJpaRepository` `countLongRetries`) |
|
||||
| RR-02-15 | 닫힘(메시지·가이드 방향) | `SingleSidedAssociationCondition.java:130-138` `why()`, fixture `MutualForeignKey*Entity`, 테스트가 "two fields map one link"가 **없음**까지 단언, 가이드 `entity-mapping-guide.md:84-97`. 잔여: to-many 쌍의 메시지(RR3-02-05, Minor) |
|
||||
| RR-02-16 | 닫힘 | `KafkaDeadLetterQuarantineTest`(두 category의 header 바이트), 업그레이드 안내 B-39(`docs/upgrade/2026-11-maturity-review.md:61`) |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR3-02-01 — 잠금 대기 검사기가 FK·trigger·`REINDEX`를 못 잡고, `lock_timeout = 0`과 트랜잭션 밖 `SET LOCAL`을 상한으로 인정한다
|
||||
|
||||
- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/migration/LockWaitMigrationInspector.java:43-58`,
|
||||
`docs/jpa/migration-guide.md:51-52`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 가이드는 검사기가 "names every statement that locks an existing table before the bound"라고 말한다.
|
||||
- 검사기의 목록에는 `CREATE TABLE ... REFERENCES <기존 표>`가 없다. 이 문장은 부모 표에 `SHARE ROW EXCLUSIVE`를 건다. 그 잠금은 쓰기와 충돌한다.
|
||||
- `CREATE TRIGGER`·`DROP TRIGGER`·`REINDEX`(비동시)·`REFRESH MATERIALIZED VIEW`(비동시)도 목록에 없다.
|
||||
- `BOUND`는 값을 보지 않는다. `SET LOCAL lock_timeout = 0`(상한 없음)도 상한으로 센다.
|
||||
- 검사기는 `.sql.conf`를 읽지 않는다. `executeInTransaction=false` 마이그레이션에서 `SET LOCAL`은 경고만 내고 효과가 없다.
|
||||
그 모양을 막는 `ConcurrentIndexMigrationInspector.requireIsolatedStatement`는 저장소 tree에 적용되지 않는다(사용처가 합성 입력 테스트뿐).
|
||||
- `CREATE TABLE IF NOT EXISTS`로 "만든" 표는 이미 있던 표여도(adopt 경로) 그 뒤 `ALTER TABLE`이 면제된다.
|
||||
- **증거(E3)**:
|
||||
- 검사기를 컴파일해 돌렸다. FK가 있는 `CREATE TABLE`, `CREATE TRIGGER`, `DROP TRIGGER`, `REINDEX TABLE`이 모두 `[]`이었다.
|
||||
- 실 PG 16에서 부모 표에 쓴 트랜잭션을 열어 두었다. `CREATE TABLE child (... REFERENCES parent)`가 11.09초 기다렸다.
|
||||
그동안 3초 제한의 `INSERT INTO parent`가 statement timeout으로 끝났다. RR-02-09와 같은 종류의 멈춤이다.
|
||||
- 트랜잭션 밖 `SET LOCAL lock_timeout`은 `WARNING: SET LOCAL can only be used in transaction blocks`였다.
|
||||
- **왜 중요한가**:
|
||||
- 발생 조건: 서비스가 기존 업무 표를 가리키는 새 표를 만든다. 흔한 마이그레이션이다. 검사는 통과하고 상한은 없다.
|
||||
- 영향: 배포 때 그 부모 표에 열린 쓰기가 있으면 부모 표의 쓰기가 마이그레이션 뒤에 줄을 선다.
|
||||
- Minor로 둔 이유: 지금 저장소의 규칙 이후 마이그레이션 9개는 모두 첫 문장에 상한이 있어 이 빈틈에 걸리는 파일이 없다.
|
||||
검사기 Javadoc은 자기 목록과 "not a proof"를 적는다. 틀린 것은 가이드의 "every" 문장과 앞으로의 파일에 대한 보호 범위다.
|
||||
- **고치는 법**:
|
||||
1. 목록에 `REFERENCES`(새 표·`ALTER TABLE` 모두, 대상은 참조되는 표), `CREATE/DROP TRIGGER ... ON`, 비동시 `REINDEX`·`REFRESH MATERIALIZED VIEW`·`CLUSTER`·`VACUUM FULL`을 더한다.
|
||||
2. `BOUND`가 0이 아닌 값만 인정하게 한다.
|
||||
3. `executeInTransaction=false`인 파일은 `SET LOCAL`을 상한으로 세지 않는다. 또는 `requireIsolatedStatement`를 저장소 tree 전체에 돌린다.
|
||||
4. 가이드 문장을 "목록의 문장을 찾는다"로 줄이고 목록을 적는다.
|
||||
- Low · P3 · E3. **통제**: 목록 안의 문장은 M3, 목록 밖은 M1(가이드 문장만).
|
||||
|
||||
#### RR3-02-02 — runbook의 원인 세션 조회가 원인을 가려내지 못한다
|
||||
|
||||
- **위치**: `docs/runbooks/migration-failed.md:46-49`, `docs/runbooks/outbox-dead-letter.md:133`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 두 runbook은 "그 표를 건드린 열린 트랜잭션"이 원인이라고 말하고 `pg_stat_activity WHERE xact_start < now() - 5s`를 준 뒤 "End it"이라고 한다.
|
||||
- 이 조회는 표를 가리지 않는다. 5초 넘게 열린 모든 트랜잭션이 나온다.
|
||||
- idle in transaction 세션의 `query` 열은 **마지막** 문장이다. 원인 세션이 표를 읽은 뒤 다른 문장을 실행했으면 그 표 이름이 보이지 않는다.
|
||||
- **증거(E3, 실 PG 16)**: 원인 세션(93)과 다른 표만 읽은 보고 세션(91)을 열어 두었다. 상한 있는 `ALTER TABLE`이 lock timeout으로 실패했다.
|
||||
runbook 조회는 두 세션을 모두 냈다. 93의 `query`는 `SELECT 1 AS later_statement`였다.
|
||||
`pg_locks`를 `relation = 'outbox_event'::regclass`로 거른 조회는 93만 냈다.
|
||||
- **왜 중요한가**: 운영자가 원인을 못 고르면 다시 배포해도 같은 실패를 한다. 목록을 모두 끝내면 무관한 트랜잭션(보고·배치)이 롤백된다.
|
||||
Minor로 둔 이유: 지시("원인을 끝낸다") 자체는 맞고, 원인은 목록 안에 있다. 상한 덕분에 운영자가 찾는 동안 서비스가 멈추지 않는다.
|
||||
- **고치는 법**: 두 runbook의 조회를 표 이름으로 거른 `pg_locks` 조인으로 바꾼다.
|
||||
`SELECT DISTINCT a.pid, a.state, a.xact_start, a.query FROM pg_locks l JOIN pg_stat_activity a USING (pid) WHERE l.relation = '<table>'::regclass AND a.pid <> pg_backend_pid();`
|
||||
`query`는 마지막 문장일 뿐이라는 한 줄을 붙인다.
|
||||
- Low · P3 · E3.
|
||||
|
||||
#### RR3-02-03 — 운영 tree 검사가 소수 버전 마이그레이션(`V22_1__`)을 건너뛴다
|
||||
|
||||
- **위치**: `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/MigrationTrees.java:58`,
|
||||
비교: `src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SampleMigrationLockWaitTest.java:58`, `docs/manual/04-persistence.md:126`.
|
||||
- **무엇이 틀렸나**:
|
||||
- `MigrationTrees`는 `V\d+__.+\.sql`만 마이그레이션으로 본다. `V22_1__x.sql`은 빠진다(실행 확인).
|
||||
- 같은 커밋의 sample 검사는 `V[0-9_]+__`로 소수 버전을 센다. "versioned migration"의 정의가 두 벌로 갈렸다.
|
||||
- manual 04는 "같은 스트림 안에서 두 버전 사이에 끼워야 하면 소수 버전을 쓴다"고 안내한다. 운영 tree에 그런 파일을 두면 잠금 규칙과 checksum 고정 둘 다 받지 않는다.
|
||||
- **왜 중요한가**: 사용자 원칙의 "갈라진 복사본"이다. 발생은 소수 버전을 운영 tree에 쓰는 경우로 드물다.
|
||||
checksum 쪽 빈틈은 이 커밋 이전부터 있었다(정규식은 `AppliedMigrationImmutabilityTest`에서 옮겨 왔다). 잠금 규칙 쪽은 이 커밋이 물려받았다.
|
||||
- **고치는 법**: `MigrationTrees`와 sample 검사가 정규식 하나(`V[0-9_]+__.+\.sql`, 필요하면 `.` 포함)를 함께 쓴다. 소수 버전 fixture로 두 검사를 한 번씩 고정한다.
|
||||
- Low · P3 · E2. 이 커밋 이전부터(checksum 쪽) + 이 커밋이 물려받음(잠금 쪽).
|
||||
|
||||
#### RR3-02-04 — gRPC ledger tree에는 잠금 규칙 검사가 없다
|
||||
|
||||
- **위치**: `src/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java:50-55`,
|
||||
`docs/jpa/migration-guide.md:52-55`.
|
||||
- **무엇이 틀렸나**:
|
||||
- `MigrationTrees.ROOTS`에 `db/migration/grpc`가 없다. 텍스트 검사기를 이 tree에 돌리는 테스트도 없다.
|
||||
- IT는 V002·V003 이름을 박아 두고 그 두 파일만 실 PG로 본다. 다음 `V004__`가 상한 없이 들어와도 모든 테스트가 통과한다.
|
||||
- 가이드는 검사 대상을 "이 leaf DB에 도는 모든 tree"와 "서비스 스트림"으로 말한다. 템플릿이 가진 grpc tree는 어느 쪽에도 없다.
|
||||
- **왜 중요한가**: RR-02-09의 원인("한 파일에 적은 규칙은 다음 파일의 규칙이 아니다")이 이 tree에는 그대로 남는다. ledger는 아직 어디에도 채택되지 않아 지금 피해는 없다.
|
||||
- **고치는 법**: `GrpcOperationLedgerMigrations.IN_ORDER` 전체에 텍스트 검사를 돌리는 테스트를 하나 둔다. 등록상 testkit 의존이 막히면 `SampleMigrationLockWaitTest`처럼 검사를 그 leaf 테스트에 둔다. 또는 IT가 이름 목록 대신 V001 이후 전체를 매개변수로 받는다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
#### RR3-02-05 — to-many 쌍에서 연관 규칙 메시지가 여전히 "한 링크"라고 틀리게 말한다
|
||||
|
||||
- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/arch/SingleSidedAssociationCondition.java:125-138`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 새 `why()`는 annotation 모양만 본다. `@ManyToMany` 둘, 또는 `@JoinColumn` 없는 `@OneToMany`와 `@ManyToOne`이면 "two fields map one link, and the read-only one does not follow"라고 한다.
|
||||
- `mappedBy`가 없으면 두 `@ManyToMany`는 둘 다 소유 쪽이다. 기본 join table도 둘(`A_B`, `B_A`)이라 링크가 둘이고 읽기 전용 쪽이 없다.
|
||||
- `@JoinColumn` 없는 `@OneToMany`는 join table을 쓰고 `@ManyToOne`은 FK 열을 쓴다. 이것도 링크 둘이다.
|
||||
- 이 커밋의 Javadoc이 "two many-to-many collections, map one link from both ends"라고 새로 적었다.
|
||||
- **왜 중요한가**: 거부 자체는 맞아 데이터 위험은 없다. RR-02-15가 지적한 "이유를 말하는 메시지가 틀리면 규칙을 믿지 않는다"가 이 두 모양에 남는다. `mappedBy`를 잊는 흔한 실수가 바로 두 번째 모양이다.
|
||||
- **고치는 법**: `why()`가 join column 이름(또는 join table 유무)을 보고 "같은 열을 두 쪽이 매핑"일 때만 "one link"라고 한다. 아니면 두 to-many 모양에 맞는 문장("두 저장소가 따로 써져 서로 어긋난다")을 둔다. 각 모양의 fixture를 하나씩 둔다.
|
||||
- Low · P3 · E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- 배포 도구가 실패한 pod를 자동 재시작하면 원인이 남아 있는 동안 시도마다 최대 5초씩 줄이 선다 — 배포 토폴로지(ArgoCD 등)가 저장소에 없고, 시도당 상한은 지켜진다.
|
||||
- `lock_timeout`은 잠금 대기 하나마다 걸린다. V12처럼 문장이 여럿이면 전체 대기는 5초를 넘을 수 있다 — 각 대기와 각 줄서기는 5초로 묶이고, 문서의 "5초" 요약은 운영 판단을 바꾸지 않는다.
|
||||
- runbook §1의 "alert payload 필수 field(`event_id` 등)"를 게이지 기반 두 번째 조건은 채울 수 없다 — runbook `status: stub`이고, §2 Step 1이 WARN과 SQL로 행을 찾게 한다.
|
||||
- runbook·README 산문의 "10번"은 document-contract lane이 보지 않는다 — 운영자가 실행하는 것은 SQL 블록이고 그것은 묶였다.
|
||||
- 검사기가 열 이름 `lock`을 `LOCK TABLE`로 오탐한다 — 엄격한 쪽으로 틀리고, 지금 저장소에 해당 파일이 없다.
|
||||
- `reportedUnknownStatuses`는 비우지 않아 사라졌다 다시 나타난 모르는 상태를 다시 알리지 않는다 — 결정("WARN 한 번")대로다.
|
||||
- sample V8_1은 실 PG 잠금 대기 테스트가 없다 — 같은 `SET LOCAL` 모양이 다른 5개 파일에서 실 PG로 확인됐고, 텍스트 검사가 있다.
|
||||
- `GrpcOperationLedgerMigrationLockWaitIT`는 Flyway 대신 JDBC 한 트랜잭션으로 실행한다 — Flyway의 기본 실행(트랜잭션 하나)과 `SET LOCAL`의 효과가 같다. 운영자 경로 `apply-capability-streams.sh`도 Flyway CLI 기본(트랜잭션)이다.
|
||||
- `spotbugsTestFixtures`의 ReDoS 경고 8건 — 입력이 저장소 마이그레이션 파일뿐이다(재리뷰 README 10.3에 기록됨).
|
||||
- pathspec 안의 다른 영역 변경(멱등성 store, manual 09 `@SystemCaller` 절, `SampleDemoSecurityConfigTest`, ledger `release` 시그니처, Redis lane 지표 항목) — 01·03·04 리뷰어 몫이다.
|
||||
|
||||
## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가
|
||||
|
||||
**없다.**
|
||||
|
||||
- 맡은 2차 발견 8건(RR-02-09~16)은 모두 닫혔다(RR-02-10은 결정으로). 회귀는 없다.
|
||||
- RR-02-09의 핵심 주장 두 가지를 실행으로 확인했다.
|
||||
- `SET LOCAL lock_timeout`은 실제 Flyway 실행에서 5초에 걸린다. V22의 상한을 지우면 lane이 실패한다.
|
||||
- 고친 9개 파일은 어느 배포에도 적용되지 않았다. 9개 모두 main과 파생 서비스에 없다.
|
||||
- 브리프가 물은 세 가지에 대한 답:
|
||||
- **이미 적용된 파일을 바꿨는가**: 아니다. 동결 목록 24개는 모두 main에 있다.
|
||||
- **비트랜잭션 마이그레이션과 섞이면**: `SET LOCAL`은 효과가 없다. 지금 그런 파일은 없다. 검사기가 이 경우를 모른다(RR3-02-01).
|
||||
- **DEAD 전이의 entity flush**: claim의 `FOR UPDATE` 아래에서만 일어나고 entity를 바꾸는 다른 경로가 없어 맞다.
|
||||
- 새 Minor 5건은 모두 앞으로의 파일·문서 정밀도에 관한 것이다. 지금 코드에서 틀린 동작이나 데이터 손상을 만들지 않는다.
|
||||
|
||||
이 영역은 멈추는 기준(새 Important 0)을 채운다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? Yes.**
|
||||
|
||||
9.1절 결정(V21과 같은 `SET LOCAL lock_timeout`, 같은 모양의 실 PG lane)이 8개 파일에 구현됐다. lane이 상한 누락을 실제로 잡는 것도 확인했다.
|
||||
남은 5건은 Minor다. 검사기 범위와 runbook 조회 정밀도는 다음 정리 때 고치면 된다.
|
||||
@@ -0,0 +1,227 @@
|
||||
# 03 outbound·멱등성 3차 확인 리뷰 (2026-11-04)
|
||||
|
||||
> 3차 확인 리뷰. 대상은 3차 수정 커밋 `1885bf8d`(Base `ecc74b7d`)의 수정 묶음 r5-a(멱등성·outbound)다.
|
||||
> 경로는 따로 적지 않으면 `src/adapter/outbound/`를 생략한다. 새 발견 ID 접두어는 `RR3-03-`이다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
```
|
||||
src/adapter/outbound/httpclient src/adapter/outbound/cache-redis src/adapter/outbound/redis-runtime
|
||||
src/adapter/outbound/notification src/composition/idempotency src/shared-contract src/application-core
|
||||
src/adapter/outbound/persistence-jpa/src/main/java/.../persistence/idempotency
|
||||
src/adapter/outbound/persistence-jpa/src/test src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest
|
||||
src/adapter/inbound/web docs/httpclient docs/manual/05-idempotency.md docs/web/http-contract.md
|
||||
docs/runbooks/redis-capability-incident.md docs/registries/env-keys.yaml docs/registries/metrics.yaml
|
||||
```
|
||||
|
||||
- `git diff --stat ecc74b7d..1885bf8d -- <pathspec>` 기준 59파일, +1,854 −207.
|
||||
- 끝까지 읽은 diff: 멱등성(Redis Lua·adapter·fake 사본, PG claim·transition gateway, 공유 계약, executor·결과 타입 Javadoc,
|
||||
설정 검사·yml·README), httpclient(watchdog, `HttpBodyReadException`, 헤더 목록, breaker Javadoc, 문서), redis-runtime(listener WARN),
|
||||
notification(주석), Redis runbook·README·metrics 레지스트리, env 레지스트리, http-contract, 매뉴얼 05.
|
||||
- 같은 pathspec이지만 다른 묶음(r5-b·r5-c)의 변경은 판정하지 않았다: `EnvelopeErrorController`, `SystemCaller`·`SystemInvoked`,
|
||||
`DirectTransactionPort`·`TransactionPortContract`, outbox port Javadoc, persistence-jpa 마이그레이션 잠금 테스트·outbox 테스트·ArchUnit fixture.
|
||||
- 판정에 필요해 pathspec 밖에서 읽은 것: `PostgreSqlIdempotencyStore`(claim 분기), `IdempotencyReaper`·`IdempotencyRecordJpaRepository`,
|
||||
`IdempotencyAutoConfiguration`, `BlockingStreamingGateway`, `CountingBoundedInputStream`, `cache-redis/build.gradle`·`persistence-jpa/build.gradle`의 lane 정의,
|
||||
`docs/runbooks/idempotency-unavailable.md`, `docs/upgrade/2026-11-maturity-review.md` B-24·B-30, `objectstorage/README.md`·`object-storage-qualification.yml`(RR-03-18 확인용).
|
||||
- 재확인한 2차 발견: `round2/03-outbound.md`의 RR-03-11~18, `round2/01-core-app-inbound.md`의 RR-01-11.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 요구사항(round2 "고치는 법"·9.1절 결정) 대비 정렬, Critical/Important/Minor, 읽기 전용, 하위 에이전트 없음, 판단을 미룬 것을 한 줄씩 남김 | 출력 양식 전체, 발견 재확인 표, Declined to judge |
|
||||
| `api-and-interface-design` | 멱등성 키 점검표: claim이 한 번의 원자 연산인가, 진행 중 중복에 고른 답(409)이 있는가, 성공·실패·불명 세 결과, "키 보존 기간이 가장 긴 재전송 경로보다 길어야 한다". 인터페이스 쪽은 Hyrum의 법칙(`InputStream.read`의 `IOException` 계약) | Redis Lua·PG SQL의 abandon·takeover 분기와 수명, 늦은 complete, 문서가 약속한 기억 기간(RR3-03-02), `HttpBodyReadException`의 형태 |
|
||||
| `performance-optimization` | 추정 말고 잰다, 고친 뒤 같은 방법으로 다시 잰다, 숫자 없이 문제로 올리지 않는다 | watchdog의 read당 비용(전후 측정), 공용 풀 포화 때 timeout 시각(측정, RR3-03-01), lifetime 연장이 Redis·PG 저장량에 주는 영향(+lease, 무시할 수준이라 발견 아님) |
|
||||
| `observability-and-instrumentation` | on-call 질문에 신호가 답하는가("어느 키가 회복 필요인가"), runbook이 실제 신호를 가리키는가, 계측 실패가 보이되 결과를 바꾸지 않는가, 레지스트리와 코드의 일치 | listener 첫 실패 WARN, Redis runbook·metrics 행, 멱등성 runbook의 회복 절차(RR3-03-03) |
|
||||
| `doubt-driven-development` | 비자명한 주장마다 CLAIM을 적고 반대 논증으로 깨 보려 한다. 하위 에이전트 대신 직접 반대 논증을 썼다(브리프 지시). 비대화형이라 cross-model 검토는 건너뛰었다 | 아래 「반대 논증」 4건 |
|
||||
|
||||
### 반대 논증 (doubt-driven, 직접 작성)
|
||||
|
||||
| CLAIM | 반대 논증 | 결과 |
|
||||
| --- | --- | --- |
|
||||
| Redis와 PG가 "lease 지난 EXECUTING → 회복 필요, 다시 안 돌림"을 같이 지킨다 | Redis TRANSITION은 "이미 목표 상태"를 revision보다 먼저 본다. 늦은 holder의 complete가 ABANDONED 기록에서 `ALREADY`를 받아 성공으로 끝날 수 있지 않나? 같은 owner token이 남아 있다 | 깨지지 않음. 목표가 COMPLETED이고 상태가 ABANDONED라 `ALREADY`가 아니고, revision이 1 올라 `NOT_OWNER`다(실 Redis 탐침 B). `markFailed(ABANDONED)`만 `ALREADY`를 받는데 상태가 같아 무해하다(Declined) |
|
||||
| 기록 수명 lease + replay TTL이 claim·takeover·renew 모두에서 지켜진다 | start 전이가 lease나 TTL을 다시 정하면 어긋난다. 옛 기록(`afterLease` 없음)의 renew는 `nil` 산술로 Lua 오류가 나지 않나? | 깨지지 않음. start는 lease·TTL을 건드리지 않는다(Redis `Transition(..., "", "")`, PG `START_SQL`). `HGET` 없음은 Lua `false`라 `or '0'`이 받는다(탐침 D: PTTL 9938) |
|
||||
| 시간 케이스가 세 구현에서 실제로 돈다 | abort가 통과로 보이거나, PG lane이 Docker 없이 skip으로 통과할 수 있다 | 깨지지 않음. Live Redis lane은 `rejectSkipped = true`, PG는 `JpaPlatformContractSupport`가 Docker 없으면 던진다. 게이트 보고서에서 두 클래스 19/19, skip 0, 시간 케이스 약 2초(실제 sleep) |
|
||||
| watchdog이 idle을 틀리게 판정하지 않는다 | 타이머가 공용 풀로 옮겨 가 늦게 깨면? 일찍 닫을 수는? | 일찍 닫지는 않는다(깰 때 시작 시각과 다시 비교). **늦게 깰 수는 있다** → RR3-03-01(E3) |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
checkout·index·HEAD는 바꾸지 않았다. worktree와 Gradle은 쓰지 않았다(게이트 결과는 읽기만). 탐침은
|
||||
`git show 1885bf8d:<path>`로 꺼낸 사본을 scratchpad에서 돌렸다.
|
||||
|
||||
| 명령 | 결과 |
|
||||
| --- | --- |
|
||||
| `git diff --stat` / `git diff ecc74b7d..1885bf8d -- <pathspec>` | 59파일 |
|
||||
| `docker run --rm redis:7.4`(로컬 이미지 `b6b6e3dc0c09`, 고정 digest와 같은 id) + HEAD의 CLAIM·TRANSITION·RENEW Lua를 `redis-cli EVAL` | A: lease 3000·replay 1000 claim → `PTTL 3943`. B: A가 start → 1.2s 뒤 B claim → `RECOVERY_REQUIRED`, `state ABANDONED`, `PTTL 576`. A의 늦은 complete → `NOT_OWNER`, 늦은 `FAILED_RETRYABLE` → `NOT_OWNER`, 늦은 `ABANDONED` → `ALREADY`. C claim → `RECOVERY_REQUIRED`. 기록 수명 뒤 `EXISTS 0`, D claim → `ACQUIRED`. C: lease 1000·replay 5000 → renew 10000 → `PTTL 14952`. D: `afterLease` 없는 옛 기록 renew 10000 → `PTTL 9938` |
|
||||
| `javac` + `PerReadBench` — `ecc74b7d`의 read별 타이머 vs HEAD의 watchdog, 끝없는 1바이트 stream, read-idle 3s | 3회: 옛 1,490~2,533ns/read, 새 24.6~25.3ns/read (load average 3.6) |
|
||||
| `javac` + `StarveProbe` — 멈춘 stream 한 번 read, read-idle 300ms, 공용 `ForkJoinPool`을 블로킹 작업 2배수로 3초 채움 | 평소: 옛 303ms(`CompletableFutureDelayScheduler`가 닫음), 새 302ms(`ForkJoinPool.commonPool-worker-1`이 닫음). **공용 풀 포화: 옛 300ms, 새 2,699ms**. `-XX:ActiveProcessorCount=2`(공용 풀 병렬도 1): 새 300ms, 닫는 스레드가 매번 새 스레드(`Thread-1`, `Thread-3`) |
|
||||
| `javac` + `SelfProbe` — JDK 본문처럼 `ArrayBlockingQueue.take`로 멈춘 read 42개를 공용 풀 작업으로 실행(병렬도 21) | 가장 늦은 timeout 306ms. 공용 풀 안의 멈춘 read 자체로는 막히지 않는다(아래 javap) |
|
||||
| `javap -c` `ResponseSubscribers$HttpResponseInputStream`, `AbstractQueuedSynchronizer$ConditionObject`, `CompletableFuture` | JDK 본문은 `ArrayBlockingQueue.take`로 기다린다. `ConditionObject.await`는 `ForkJoinPool.managedBlock`을 불러 공용 풀이 보충 스레드를 만든다. `delayedExecutor(delay, unit)`의 실행기는 `ASYNC_POOL`(병렬도 > 1이면 공용 풀, 아니면 작업마다 새 스레드) |
|
||||
| 게이트 JUnit 보고서 읽기(main 작업 트리 `build/test-results`, 시각 2026-11-03T16:34Z·16:35Z, 커밋 01:47 KST 직전) | `LiveRedisIdempotencyStoreContractTest` 19 tests, skipped 0. `PostgreSqlIdempotencyStoreContractTest` 19 tests, skipped 0. 새 시간 케이스 5개가 두 클래스 모두에서 1.5~2.3초 걸림 |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- Gradle 테스트·게이트를 다시 돌리지 않았다(README 10.2절과 보고서만 읽었다).
|
||||
- Redis Cluster·Sentinel topology lane, 장애 조치 중 `TIME`이 바뀌는 경우.
|
||||
- JDK HTTP/2·TLS에서 공용 풀 스레드가 본문 stream을 닫을 때의 지연.
|
||||
- PG 저장소를 여러 인스턴스·여러 트랜잭션 모양(유스케이스 트랜잭션 안 vs 호출마다 트랜잭션)으로 돌리는 경우. 아래 Declined.
|
||||
- `failure-retention`이 짧을 때의 실제 동작은 코드로만 확인했다(E1).
|
||||
|
||||
## Strengths
|
||||
|
||||
- Redis CLAIM이 "lease 지난 EXECUTING"과 "실행 전 CLAIMED·재시도 가능 실패"를 따로 다룬다(`cache-redis/.../idempotency/IdempotencyScripts.java:87-105`).
|
||||
분기 순서(fingerprint → COMPLETED → ABANDONED → 같은 owner → lease)가 PG와 같다(`persistence-jpa/.../PostgreSqlIdempotencyStore.java:131-159`).
|
||||
실 Redis에서 늦은 complete·늦은 retryable 표시가 모두 `NOT_OWNER`로 막히는 것을 확인했다(탐침 B).
|
||||
- 기록 수명 규칙이 두 저장소에서 같은 식이다. Redis는 `leaseMillis + afterLease`(`IdempotencyScripts.java:61,102`), PG는
|
||||
`recordLifetimeMillis`(`IdempotencyClaimGateway.java:173-175`)를 insert와 reset 둘 다에 쓴다. renew도 같은 여유를 유지한다
|
||||
(`IdempotencyScripts.java:213-218`, `IdempotencyTransitionGateway.java:54-57`). PG `RENEW_SQL`의 오른쪽이 갱신 전 행을 읽는다는
|
||||
사실을 주석에 적었다. 옛 기록(`afterLease` 없음)도 처리한다(탐침 D).
|
||||
- 공유 계약에 시간 케이스 5개가 생겼고(`application-core/.../testkit/IdempotencyStoreContract.java:431,449,466,484,501`), 두 실 저장소에서
|
||||
실제로 돈다. PG 쪽 `elapse`가 배포와 같은 Spring Data reaper를 돌린다(`PostgreSqlIdempotencyStoreContractTest.java:122-131`).
|
||||
그래서 "reaper가 진행 중 행을 지운다"는 PG 쪽 RR-03-11 경로도 테스트가 본다. Redis lane은 `rejectSkipped = true`다
|
||||
(`cache-redis/build.gradle:81-92`).
|
||||
- 설정 검사를 한 곳에 두고, 포트(`IdempotencyClaimRequest`)에 두지 않은 이유를 남겼다(`IdempotencySettings.java:67-80`,
|
||||
`composition/idempotency/README.md`). env 레지스트리·`.env.example`·업그레이드 안내 B-24가 같은 규칙을 적는다.
|
||||
- watchdog은 일찍 닫지 않는다. 깰 때마다 지금 read의 시작 시각과 비교하고, 닫기 직전에 시작 시각을 한 번 더 읽는다
|
||||
(`httpclient/.../jdk/ReadIdleInputStream.java:123-131`). 무장 해제와 재무장 사이의 경쟁을 volatile 두 개로 막았다(`:134-140`).
|
||||
비용 주장(read당 µs → 수십 ns)을 다시 재서 맞았다(`PerReadBench`).
|
||||
- `HttpBodyReadException`이 `InputStream` 계약(`IOException`)을 지키면서 분류된 실패를 `failure()`로 싣는다. 버린 대안(문서만 고치기)과
|
||||
이유가 Javadoc에 있다(`httpclient/.../api/error/HttpBodyReadException.java:17-20`).
|
||||
- 금지 헤더 사본을 Spring 원본과 반사로 비교하는 테스트가 있다(`JdkStreamingRestrictedHeadersTest`). Spring이 바뀌면 테스트가 깨진다.
|
||||
- listener 첫 실패만 WARN으로 남기고 나머지는 DEBUG다(`redis-runtime/.../RedisRuntimeOwner.java:357-369`). 로그 수를 세는 테스트가 있다
|
||||
(`RedisLaneMetricsTest.aFailingListenerIsReportedAtWarnOnlyTheFirstTime`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| RR-01-11 | 닫힘 | 고치는 법 1: `IdempotencyScripts.java:89-95` EXECUTING+lease 만료 → `ABANDONED`·`RECOVERY_REQUIRED`, takeover는 `CLAIMED`·`FAILED_RETRYABLE`만(`:96`). fake 사본도 같다(`InMemorySemanticRedisCommands.java:226-243`). 2: 계약 `:449`(회복 필요), `:466`(늦은 complete 거부)이 Live Redis·PG에서 돌았다(보고서). 3: `IdempotencyCompletionUnknownException` Javadoc을 "쓰기 트랜잭션 안에서 부른 경우"로 좁혔다. 같은 문장의 runbook 사본은 남았다 → RR3-03-03 |
|
||||
| RR-03-11 | 닫힘(9.1절 결정대로) | 설정: `IdempotencySettings.java:73` `replay-ttl < processing-lease`면 기동 실패, 테스트 2건. 저장소: Redis claim·takeover·renew(`IdempotencyScripts.java:61,102,213-218`), PG insert·reset·renew(`IdempotencyClaimGateway.java:133,162`, `IdempotencyTransitionGateway.java:54-57`). 계약 `:484`(replay TTL < lease), `:501`(같을 때)이 두 실 저장소에서 돌았다. 실 Redis 탐침 A·C |
|
||||
| RR-03-12 | 닫힘 | `ReadIdleInputStream.java:72-87` skip을 감시되는 read 반복으로. 테스트 `aSkipLongerThanReadIdleOverASteadyBodySucceeds` |
|
||||
| RR-03-13 | 닫힘 | stream당 watchdog 하나(`ReadIdleInputStream.java:95-141`). 재측정: 1.5~2.5µs → 25ns. 대신 timeout 동작이 공용 풀로 옮겨 갔다 → 새 Minor RR3-03-01. 문서의 "per-read timer" 표현은 남았다 → RR3-03-04 |
|
||||
| RR-03-14 | 닫힘 | 고치는 법 (a)를 골랐다: `HttpBodyReadException extends IOException`, `ClassifiedBodyInputStream.java:37,46,55,64`, `BlockingStreamingResponse.body()` Javadoc, README·configuration-reference·operations. 테스트 `StreamingBodyLifetimeTest:76` 두 transport |
|
||||
| RR-03-15 | 닫힘 | `JdkStreamingClientHttpRequest.java:136-144`가 같은 시스템 속성을 읽는다. 값 4가지로 Spring 원본과 비교하는 테스트 |
|
||||
| RR-03-16 | 닫힘 | 맹점을 Javadoc(`AttemptResiliencePipeline.java:26-33`)과 configuration-reference "Two deadlines" 아래 문단에 적었다. Javadoc의 조건 문장을 코드에 맞췄다 |
|
||||
| RR-03-17 | 닫힘 | runbook에서 미구현 지표 문장 정리(`redis-capability-incident.md:50-52,62-66`), README `opened` 설명(`cache-redis/README.md:218`), 레지스트리 histogram 표기(`metrics.yaml:553-560`), listener 첫 실패 WARN(`RedisRuntimeOwner.java:361`) |
|
||||
| RR-03-18 | 닫힘 | `objectstorage/README.md:109-111`, `object-storage-qualification.yml:3-5`가 `integrationCheck`를 적는다. `cache-redis/README.md:349-351`에 멱등성 계약. `SesEventNormalizer.java:57-59` 주석 줄바꿈 |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR3-03-01 · JDK read-idle timeout이 이제 공용 `ForkJoinPool`에서 돈다 — 공용 풀이 막히면 timeout이 늦게 난다 (이번 라운드)
|
||||
|
||||
- **위치**: `httpclient/.../jdk/ReadIdleInputStream.java:113-117`(`CompletableFuture.delayedExecutor(left, NANOSECONDS).execute(this::watch)`),
|
||||
`:143-150`(`idle()`이 `in.close()`).
|
||||
- **무엇이 틀렸나**:
|
||||
- `delayedExecutor(delay, unit)`는 시간이 되면 작업을 `ASYNC_POOL`에 넘긴다. 병렬도가 1보다 크면 공용 `ForkJoinPool`이다.
|
||||
- 옛 코드는 `completeOnTimeout(...).thenRun(this::idle)`이라 JDK delay 스레드에서 바로 닫았다. 새 코드는 공용 풀 작업이 비어야 닫는다.
|
||||
- Javadoc은 "one scheduled task per read-idle"까지만 적고 어느 스레드에서 도는지는 적지 않는다.
|
||||
- **왜 중요한가**:
|
||||
- 발생 조건: JDK transport(기본은 Apache) + 스트리밍 다운로드 + 같은 JVM의 공용 풀이 보충 스레드를 만들지 않는 블로킹 작업
|
||||
(소켓·JDBC 호출, `CountDownLatch`, `Thread.sleep`)으로 차 있음. 파생 서비스의 `CompletableFuture.supplyAsync(blockingCall)`(executor 생략)이 흔한 원인이다.
|
||||
템플릿 main 코드에는 그런 사용이 없다(grep).
|
||||
- 영향: 멈춘 서버의 본문 read가 read-idle이 아니라 공용 풀이 빌 때까지 기다린다. 측정에서 300ms 설정이 2,699ms에 끝났다.
|
||||
공용 풀 작업이 끝없이 막혀 있으면 RR-04-03 이전처럼 스레드가 무기한 묶인다. 일찍 닫는 일은 없다(깰 때 시작 시각과 다시 비교).
|
||||
- 공용 풀 안에서 JDK 본문을 읽다 멈춘 경우는 문제없다. JDK 본문의 `ArrayBlockingQueue.take`가 `managedBlock`으로 보충 스레드를 만든다(SelfProbe 306ms).
|
||||
- 병렬도가 1 이하(CPU 1~2개 pod)면 깰 때마다 새 platform 스레드를 만든다. stream당 read-idle마다 1개라 비용은 작다.
|
||||
- **고치는 법**: `watch()`는 O(1)이라 delay 스레드에서 돌려도 된다. `CompletableFuture.delayedExecutor(left, NANOSECONDS, Runnable::run)`로
|
||||
옛 코드와 같은 스레드에서 판정하게 한다. 닫기(`in.close()`)를 delay 스레드에 두기 싫으면(round2 Declined의 HTTP/2·TLS 질문) transport가 가진
|
||||
작은 daemon 실행기로 닫기만 넘긴다. 고른 쪽과 이유를 Javadoc에 적고, 공용 풀을 채운 상태에서 timeout 시각을 보는 테스트를 둔다(위 StarveProbe 모양).
|
||||
- **가이드 심각도·우선순위**: Low · P3. 비기본 transport와 외부 원인(공용 풀 포화)이 겹쳐야 하고, 늦어질 뿐 데이터 피해는 없다.
|
||||
경계: 공용 풀이 영구히 막히는 다른 결함과 겹치면 무기한 대기라 Medium에 닿을 수 있다. 그 조건은 이 커밋 밖의 결함이 있어야 해서 낮은 쪽으로 뒀다.
|
||||
- **증거**: E3 — `StarveProbe`(HEAD 코드 그대로 컴파일): 공용 풀 포화 때 옛 300ms, 새 2,699ms. 닫는 스레드 이름으로 실행 위치 확인. `javap`로 `ASYNC_POOL` 확인.
|
||||
|
||||
#### RR3-03-02 · "서버가 기억하는 기간" 문서가 실패한 시도의 수명(`failure-retention`)을 빠뜨렸다 (이번 라운드)
|
||||
|
||||
- **위치**: `docs/web/http-contract.md:125-127`, `docs/manual/05-idempotency.md:59`, `src/shared-contract/.../OperationalError.java:50`.
|
||||
실제 동작: `RedisIdempotencyStoreAdapter.java:271-277`(markFailed가 key TTL을 retention으로), PG `IdempotencyTransitionGateway` `FAIL_SQL`
|
||||
(`expires_at = now + retention`), `IdempotencySettings.java:81-85`(failure-retention은 양수·30d 이하만 검사).
|
||||
- **무엇이 틀렸나**:
|
||||
- 새 문장은 "끝나지 않은 시도의 기록은 claim부터 processing lease + `replay-ttl` 동안 남는다"고 적는다.
|
||||
- executor가 실패로 표시한 시도(action이 던짐·`EffectUnknown` → `ABANDONED`, `RetryableNoEffect` → `FAILED_RETRYABLE`)는 표시한 때부터
|
||||
`failure-retention` 동안 남는다. 두 저장소 모두 그렇다.
|
||||
- `OperationalError` 주석 "a resend with the same key never runs it again"은 기한 없이 단정한다. http-contract 본문은 기한 뒤 새 요청이 된다고 바르게 적는다.
|
||||
- **왜 중요한가**: 기본값(둘 다 24h)에서는 차이가 30초뿐이다. 운영자가 `APP_IDEMPOTENCY_FAILURE_RETENTION`을 `replay-ttl`보다 짧게 두면, 효과 불명으로
|
||||
포기한 기록이 문서가 말한 기간보다 먼저 사라지고 같은 키 재전송이 작업을 다시 돌린다. 스킬 기준 "키 보존 기간은 가장 긴 재전송 경로보다 길어야 한다"에 걸리는
|
||||
설정인데 문서가 그 변수를 언급하지 않는다.
|
||||
- **고치는 법**: 기억 기간 문단에 세 번째 줄을 더한다("실패로 표시된 시도는 표시부터 `failure-retention`"). env 레지스트리의 `APP_IDEMPOTENCY_FAILURE_RETENTION`에
|
||||
같은 관계를 적는다. `OperationalError` 주석에 "기록이 남아 있는 동안"을 붙인다. failure-retention ≥ replay-ttl을 기동 검사로 할지는 소유자 결정이다.
|
||||
- **가이드 심각도·우선순위**: Low · P3(비기본 설정, 문서 정확도). **증거**: E1.
|
||||
|
||||
#### RR3-03-03 · 멱등성 runbook의 회복 필요 절차가 이번 계약과 어긋나고, 따라 할 수 없다 (일부 이번 라운드, 일부 이전부터)
|
||||
|
||||
- **위치**: `docs/runbooks/idempotency-unavailable.md:20-22,33-34,43-45`, `application-core/.../IdempotencyExecutor.java:123-126,348-350`
|
||||
(`recovery(...)` 메시지에 scope digest가 없다. `diagnostic(scope)`(`:344`)은 in-flight·mismatch에만 쓰인다).
|
||||
- **무엇이 틀렸나**:
|
||||
- (a, 이번 라운드) RR-01-11 고치는 법 3은 "Effects inside the action's own transaction roll back"을 "쓰기 트랜잭션 안에서 부른 경우"로 좁히라고 했다.
|
||||
예외 Javadoc과 http-contract는 좁혔다. runbook의 같은 문장 "Effects in the action's own transaction rolled back"은 그대로다. 갈라진 사본이다.
|
||||
- (b, 이전부터) runbook은 `IDEMPOTENCY_RECOVERY_REQUIRED`에서 "실패한 요청의 서버 로그 줄에서 scope digest를 찾으라"고 한다.
|
||||
`IdempotencyRecoveryRequiredException`의 메시지는 "claim requires reconciliation" 같은 고정 문구라 digest가 없다.
|
||||
- (c, 이전부터) "record를 complete하거나 release하라"고 하지만 그 일을 하는 도구·명령·SQL이 없다.
|
||||
- **왜 중요한가**: 이번 라운드로 Redis 배포에서 lease가 지난 실행은 모두 회복 필요로 끝난다(9.1절 결정). 그 답을 받은 요청을 다루는 운영 절차가 첫 단계에서 막힌다.
|
||||
클라이언트 쪽 조치("업무 데이터로 확인")는 digest 없이도 할 수 있어서 피해는 진단 시간이다.
|
||||
- **고치는 법**: (a) runbook 문장을 Javadoc과 같게 좁힌다. (b) `recovery(...)`에도 `diagnostic(scope)`를 실어 로그에 남긴다(in-flight와 같은 방식).
|
||||
(c) Redis·PG 각각 기록을 보는 명령과, 확인 뒤 키를 비우는 절차를 적거나 "도구 없음, 기록 수명(lease + replay-ttl)이 지나면 풀린다"고 정직하게 적는다.
|
||||
- **가이드 심각도·우선순위**: Low · P3. 경계: "주요 진단 정보 부족"은 가이드의 Medium 예시다. 업무 데이터 확인이라는 주 조치가 digest 없이 가능하고 (b)(c)가
|
||||
이 커밋 전부터 있던 것이라 낮은 쪽으로 뒀다. **증거**: E1.
|
||||
|
||||
#### RR3-03-04 · watchdog·계약으로 바뀐 뒤 옛 표현이 남은 문서 (이번 라운드)
|
||||
|
||||
- **위치**: `src/adapter/outbound/httpclient/README.md:45`("the JDK transport arms its own per-read timer"),
|
||||
`docs/httpclient/configuration-reference.md:107`("bounds each read with its own `read-idle` timer"),
|
||||
`src/application-core/CLAUDE.md:271`("`IdempotencyStoreContract` holds the fake, Redis and PostgreSQL to both on real servers").
|
||||
- **무엇**: RR-03-13으로 read별 타이머가 stream당 watchdog이 됐다. 보장(한 read의 대기만 센다)은 같지만 두 문서가 옛 구현을 설명한다.
|
||||
CLAUDE.md 문장은 in-memory fake도 시간 케이스를 실 서버에서 지킨다고 읽힌다. fake는 만료를 모델링하지 않아 시간 케이스를 abort한다(`IdempotencyStoreContract.java:110`).
|
||||
- **고치는 법**: "a per-stream watchdog bounds each read's wait"로 고친다. CLAUDE.md는 "Redis와 PostgreSQL을 실 서버에서, fake는 시간 없는 케이스만"으로 고친다.
|
||||
- **가이드 심각도·우선순위**: Low · P3. **증거**: E1.
|
||||
|
||||
#### RR3-03-05 · Redis inspect가 `processingLeaseUntil`을 key TTL로 계산한다 — 이제 lease + replay TTL이다 (이전부터)
|
||||
|
||||
- **위치**: `cache-redis/.../idempotency/RedisIdempotencyStoreAdapter.java:388-404`(`now.plusMillis(ttlMillis)`), INSPECT Lua `IdempotencyScripts.java:269-271`(`PTTL`을 돌려준다).
|
||||
- **무엇**: 포트 `IdempotencyInspection.processingLeaseUntil`에 Redis는 key가 사라지는 시각을, PG는 실제 lease(`PostgreSqlIdempotencyStore.java:623`)를 넣는다.
|
||||
전에는 replay TTL(24h)로 틀렸고, 이번 수정으로 lease + replay TTL로 더 멀어졌다. 공유 계약이 이 필드를 보지 않아 두 저장소가 갈라진 채 통과한다.
|
||||
- **왜 중요한가**: 지금은 이 값을 읽는 곳이 없다(executor는 owner·response만 쓴다). 다음에 "남은 lease가 있으면 이어서 실행" 같은 판단에 쓰면 Redis에서만 lease가 지난
|
||||
실행을 이어 가게 된다.
|
||||
- **고치는 법**: INSPECT가 CLAIMED·EXECUTING이면 `leaseUntil`(서버 ms)을 돌려주고 adapter가 그것을 쓴다. 공유 계약에 inspect lease 케이스 하나.
|
||||
- **가이드 심각도·우선순위**: Low · P3(소비자 없음). **증거**: E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- PG 저장소의 트랜잭션 모양. 유스케이스가 `execute`를 쓰기 트랜잭션 하나로 감싸면(sample `PublishPosterImageUseCase`) 중복 요청은 409 대신 claim insert에서 기다리고,
|
||||
claim의 abandon이나 executor의 실패 표시가 예외와 함께 롤백된다. persistence·core 영역의 판단이라 넘긴다.
|
||||
- Redis start·renew에는 lease 만료 검사가 없고 PG에는 있다(`IdempotencyTransitionGateway.java:39,69`). lease가 지났지만 아무도 claim하지 않은 holder가 Redis에서는 시작·연장할 수 있다.
|
||||
어느 쪽도 두 번 실행하지 않고 executor는 renew를 부르지 않는다. 이 커밋 전부터의 차이다.
|
||||
- 늦은 holder의 `markFailed(EFFECT_UNKNOWN_ABANDONED)`가 이미 ABANDONED인 기록에서 `ALREADY`를 받는다(TRANSITION이 목표 상태를 revision보다 먼저 본다). 상태가 같고 executor가 결과를 버리므로 무해하다고 봤다.
|
||||
- 계약 케이스 `anExecutionIsRememberedPastItsLeaseEvenWhenTheReplayTtlIsNoLonger`의 여유는 0.5초다(기록 2초, 마지막 claim 1.5초). 부하 15의 게이트에서 통과했다. 0.5초 넘는 정지가 나면 흔들릴 수 있지만 재현하지 않았다.
|
||||
- 10.3절 결정 "lease 뒤 늦게 끝난 첫 시도의 결과를 버린다". 결정이라 뒤집지 않는다. 만든 위험: executor는 lease를 연장하지 않으므로 기본 30초보다 오래 걸리는 action에 lease 뒤 중복 요청이 오면, 효과가 커밋된 첫 요청도 500을 받는다. http-contract `:119-124`에 적혀 있다.
|
||||
- reaper는 앱 시계, 저장소는 DB 시계를 쓴다(`IdempotencyReaper`). 이전부터다. 이번 수정으로 여유가 lease 이상이 돼 위험은 줄었다.
|
||||
- `HttpBodyReadException`이 `IOException`이라 "IOException이면 재시도"하는 호출자 코드는 비멱등 스트리밍 호출의 `PARTIAL_RESPONSE` 실패도 재시도한다. `bbe944bd` 전의 bare `IOException`과 같은 동작이고, 재시도 여부는 호출자 몫이며 `failure()`가 분류를 준다.
|
||||
- 금지 헤더 계산의 `TreeSet.removeAll`은 인자 쪽이 크거나 같으면 대소문자를 가린다(`AbstractSet.removeAll`). Spring 원본과 같은 동작이고 테스트가 같음을 고정한다.
|
||||
- `metrics.yaml`의 새 값 `histogram_buckets: percentile_histogram`. 이 값을 검사하는 schema는 없고(`MetricsAlertingContractTest`는 `slo_driven`만 본다) 주석이 뜻을 적는다.
|
||||
|
||||
## 수렴 판단
|
||||
|
||||
- **이 라운드가 만든 새 Important 이상: 없음.** 이 영역의 2차 발견 9건(RR-01-11, RR-03-11~18)이 모두 닫혔고 회귀는 없다.
|
||||
- 9.1절 결정 두 건(RR-01-11, RR-03-11)은 결정대로 구현됐다. 실 Redis에서 Lua를 직접 돌려 abandon·늦은 complete 거부·기록 수명·renew 여유를 확인했고(E3),
|
||||
공유 계약의 시간 케이스가 Live Redis와 실 PostgreSQL 모두에서 skip 없이 돌았다(E2, 게이트 보고서).
|
||||
- 이 라운드가 만든 새 결함은 Minor 4건이다(RR3-03-01~04). 그중 동작 결함은 RR3-03-01 하나이고, 비기본 JDK transport에서 외부 원인(공용 풀 포화)이 겹칠 때 timeout이 늦어지는 것이다.
|
||||
나머지는 문서 정확도다. RR3-03-05와 RR3-03-03의 (b)(c)는 이전부터다.
|
||||
- 따라서 이 영역만 보면 다음 수정 라운드가 필요하지 않다(9.1절 멈춤 기준 충족).
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge: Yes.** 2차 발견 9건이 코드·실 서버 탐침·게이트 보고서로 닫혔고, 이 라운드가 만든 Important 이상은 없다.
|
||||
남은 것은 Minor 5건이며, RR3-03-01(watchdog 실행 스레드)이 동작에 닿는 유일한 항목이다.
|
||||
@@ -0,0 +1,248 @@
|
||||
# 04 bootstrap·build·sample 3차 확인 리뷰 (2026-11-04)
|
||||
|
||||
리뷰 대상: Base `ecc74b7d` → Head `1885bf8d`(3차 수정 커밋, 묶음 r5-d), 영역 번호 04(slug `bootstrap-build-sample`).
|
||||
재확인한 2차 재리뷰 발견: `round2/04-bootstrap-build-sample.md`의 RR2-04-01~06. 이번 발견 ID 접두어는 `RR3-04-`.
|
||||
경로는 저장소 루트 기준이다.
|
||||
|
||||
## 범위 — 본 pathspec, 불러온 스킬과 적용한 기준, 실행한 명령과 결과, 못 본 것
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
```text
|
||||
src/app-bootstrap src/adapter/outbound/support src/adapter/outbound/objectstorage src/build-logic src/sample-portfolio
|
||||
src/Dockerfile.sample src/.env.example src/config src/optional-platforms src/README.md .github AGENTS.md CLAUDE.md
|
||||
docs/registries/secrets-classification.yaml docs/registries/env-keys.yaml docs/capability-status.md
|
||||
docs/upgrade/2026-11-maturity-review.md infra
|
||||
```
|
||||
|
||||
`git diff --stat` 기준 54파일 +1,994 −237. 하위 에이전트 없이 여러 번에 나눠 직접 읽었다.
|
||||
|
||||
- 전부 읽은 것: `StartupRuleRunner`·`StartupRule` diff와 본문, `StartupRuleRunnerTest` diff, `SecretSourceValidator` diff와 본문,
|
||||
`SecretSourceValidatorTest`·`SecretsClassificationRegistryTest` diff, `WorkflowGradleInvocations` diff와 `gradleInvocation` 본문,
|
||||
`TaskSelectors` 전문, `StrictLaneStagesPlugin`·`StrictLaneStagesExtension` diff, `StrictLaneStagesFunctionalTest`·`TaskSelectorsTest`
|
||||
diff, `EnvContractVerifier`·`ConfigContractPlugin`·`VerifyEnvKeysTask` diff, `SpringConfigConventionPlugin` diff, sample의
|
||||
`application.yml`·`SampleDemoAccountsProductionGuard`·`SampleDemoProfilesStartupSystemTest`·`application-test.yml`·
|
||||
`SampleDemoSecurityConfigTest` diff, `Dockerfile.sample`·`.env.example`·`src/README.md`·sample README diff, 업그레이드 안내 B-14·B-15·
|
||||
B-27·B-36 행, AGENTS.md·CLAUDE.md·`src/app-bootstrap/CLAUDE.md`·`src/app-bootstrap/README.md`·`infra/redis-sdk/acl/README.md`·
|
||||
`docs/capability-status.md`·`src/config/spotbugs/exclude.xml`·`src/build-logic/README.md`·objectstorage README diff.
|
||||
- 확인용으로 읽은 pathspec 밖 코드: `SecretReference`, `EnvironmentSecretSource`, `SecretSourceFactory`,
|
||||
`RedisCredentialResolver`, `RedisRuntimeAutoConfiguration.redisResolvedCredentials`, `RedisAccountContribution`,
|
||||
`RedisSdkComposition`, `RedisProductionSecrets`, `HttpClientAuthenticationAutoConfiguration.secretKey`,
|
||||
`MongoCredentialResolver`, `GrpcServerSettings`, `infra/redis-sdk/acl/*.acl`, `compose-profile-contracts.json`의 Redis lane 행.
|
||||
- 표본으로 읽은 것: `env-keys.yaml` diff(멱등성 행, r5-a 소관), 업그레이드 안내의 마이그레이션 표(r5-c 소관).
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿(Strengths → severity별 Issues → Declined → Assessment), "spec이 말하지 않은 동작은 합리적인 사용자의 기대로 판단", 읽기 전용, 의심 결함은 별도 worktree에서 확인 | 2차 발견마다 "고치는 법"과 9.1절 결정을 채웠는지, 수정이 만든 새 결함. 의심 9건을 worktree 실험으로 확인 |
|
||||
| `ci-cd-and-automation` | "No gate can be skipped", 게이트가 주장하는 것과 실제 파이프라인이 같아야 한다, 캐시 최적화가 결과나 증분을 깨면 안 된다 | `verifyStrictLaneStages`가 Gradle 계획과 같은 판정을 내리는지(축약·붙여 쓴 `-x`), 실제 `.github/workflows`를 어느 빌드의 어느 단계로 읽는지, `compileJava`→`processResources` 순서가 캐시·증분을 깨는지 |
|
||||
| `security-and-hardening` | 위협 모델 먼저(신뢰 경계·자산), 비밀은 환경에서, 공개된 자격증명은 쓰지 않는다, 기본값은 닫힘 | prod `fixture-` 검사가 "비밀값"을 어디서 모으는지, 그 목록에서 빠지는 비밀(우회 경로), 거부 메시지가 값을 드러내지 않는지 |
|
||||
| `codebase-design` | 인터페이스는 타입이 아니라 불변식까지다, seam에서 불변식을 지킨다, 갈라진 복사본은 결함 | `StartupRule`·`RequiredProductionSecrets` 인터페이스의 불변식(후처리기 없이 만들어짐)을 runner가 seam에서 강제하는지, `CLASSIFIED_SECRETS`·`TaskSelectors`·`EnvContractVerifier`의 두 "declared" 계산이 원본과 묶여 있는지 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
worktree `scratchpad/rr3-04`(HEAD `1885bf8d`)에서 Gradle을 `flock heavy.lock`으로 감싸 실행했다. 시작 부하 2.3.
|
||||
probe 파일과 workflow 수정은 worktree에만 했고, 끝난 뒤 `git worktree remove --force`로 지웠다. 메인 체크아웃은 건드리지 않았다.
|
||||
|
||||
| # | 명령 | 결과 |
|
||||
| --- | --- | --- |
|
||||
| 1 | support에 probe 추가 → `./gradlew :adapter:outbound:support:test --tests '*RR3ProbeTest*' -i` | rc=0(출력으로 판정). 아래 1-a~1-f |
|
||||
| 1-a | `@Bean static RequiredProductionSecrets hiddenSecrets()`가 `@Value` 필드 클래스를 돌려줌, 읽는 규칙 없음(= prod 아닌 프로필) | **기동 성공**, 그 bean은 나중에 정상 생성되어 `x=bound` |
|
||||
| 1-b | 같은 bean + `ObjectProvider<RequiredProductionSecrets>`를 기동 중에 읽는 규칙(= prod의 `SecretSourceValidator`) | 기동 실패 `'hiddenSecrets' (...ValueFieldSecrets) ... needs one: [x (@Value)]`. 실패 직전 규칙이 본 값은 `null` |
|
||||
| 1-c | `@Value`를 메타 애너테이션으로 단 필드를 가진 `@Import` 규칙 | 기동 실패, `[x (@Value)]` |
|
||||
| 1-d | 생성자 `@Value` 매개변수 하나인 `@Import` 규칙 | 기동 실패 `No default constructor found`(이전부터 같은 동작, 조용하지 않다) |
|
||||
| 1-e | 부모 클래스의 `@Autowired` setter를 상속한 `@Import` 규칙 | 기동 실패, `[setEnv() (@Autowired)]` |
|
||||
| 1-f | `@Bean static StartupRule`(선언 타입이 인터페이스)이 `@Value` 필드 클래스를 돌려줌 | 기동 실패, `'hiddenRule' ... [x (@Value)]` |
|
||||
| 2 | `./gradlew -p build-logic compileTestJava -xcompileJava --dry-run` | Gradle이 붙여 쓴 `-x`를 받는다. 계획에 `:compileJava`가 없다 |
|
||||
| 3 | worktree의 `integration-main.yml` optional performance 줄을 바꿔 `./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run` | `-x grpcPerformanceT`: **실패** `strict lane :grpc:grpc-testkit:grpcPerformanceTest is in no executed stage`(수정 동작). `-xgrpcPerformanceTest`: **통과** `every strict lane is in an executed stage` |
|
||||
| 3-b | `./gradlew -p optional-platforms performanceCheck [-xgrpcPerformanceTest] --dry-run` | 없으면 `:grpc:grpc-testkit:grpcPerformanceTest`가 계획에 있고, 붙여 쓴 `-x`면 빠진다 |
|
||||
| 4 | build-logic에 probe 추가 → `./gradlew -p build-logic test --tests '*RR3WorkflowDumpTest*'`(실제 `.github/workflows` 15개를 `WorkflowGradleInvocations.read`로 읽어 `executes(stage, build)` 출력) | 11줄. `src`: `:ci`·`:sample-portfolio:check` ← ci-quality-gates, `:mainCheck`·`:integrationCheck`·`:performanceCheck` ← integration-main, `:releaseCheck` ← release. `src/optional-platforms`: `:ci` ← ci-quality-gates, `:integrationCheck` ← integration-main·release, `:performanceCheck` ← integration-main, `:releaseCheck` ← release. 다른 빌드로 잘못 센 줄 없음 |
|
||||
| 5 | `:adapter:outbound:objectstorage:compileJava`를 리소스를 바꿔 가며 세 번 | 다른 리소스 추가: `processResources`만 재실행, `compileJava UP-TO-DATE`. additional metadata 수정: `compileJava` 재실행. 원복: `compileJava FROM-CACHE` |
|
||||
| 6 | `javap -c -p org/gradle/util/internal/NameMatcher.class`(Gradle 9.0.0 `gradle-core`) | 집합 6개(대소문자 무시·camel 전체·camel 앞부분·camel 앞부분 대소문자 무시·kebab 전체·kebab 앞부분)와 고르는 순서가 `TaskSelectors.matches`와 같은 모양. Levenshtein은 후보 제안에만 쓰인다 |
|
||||
|
||||
돌리지 않은 것: `ci`·`mainCheck`·`integrationCheck` 전체(README 10.2절 오케스트레이터 실행을 근거로 삼았다),
|
||||
`SampleDemoProfilesStartupSystemTest`(10.2절 `mainCheck`가 `:sample-portfolio:systemTest`를 돈다), `docker build`·`docker run`
|
||||
(r5-d 보고의 실행 결과를 근거로 삼고 Dockerfile은 정적 확인), `SecretSourceValidator` 우회 경로 실험(코드 읽기로 판정).
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 실제 CI runner에서의 workflow 실행(Gitea Actions가 꺼져 있다, README 10.3절).
|
||||
- `app-bootstrap/src/architectureTest`(01 소관), sample `V8_1`과 `SampleMigrationLockWaitTest`(02 소관), `env-keys.yaml`의 멱등성
|
||||
행 의미(r5-a 소관).
|
||||
- 파생 서비스(tech-log-backend 등)의 rule·workflow가 새 검사에서 어떻게 되는지.
|
||||
|
||||
## Strengths
|
||||
|
||||
- **prod `fixture-` 검사가 비밀값만 읽고, 비밀 목록이 레지스트리와 묶여 있다.**
|
||||
`src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java:62-81,124-138,170-202`.
|
||||
레지스트리 `secret` 행, 모듈이 기여한 비밀, 환경의 모든 `secret://…/<VAR>` 대상을 모은다. 9.1절 결정("분류된 키만")보다 넓게
|
||||
잡아 compose lane이 실제로 쓰는 모양(참조 + `REDIS_LANE_*`)을 덮는다. `CLASSIFIED_SECRETS`는
|
||||
`SecretsClassificationRegistryTest.java:85`가 레지스트리와 1:1로 묶는다. `HOSTNAME`이 통과하는 테스트는 실제
|
||||
`SystemEnvironmentPropertySource`를 쓴다(`SecretSourceValidatorTest.java:165`). 메시지는 변수 이름만 적고 값은 적지 않는다.
|
||||
- **runner가 선언 모양이 아니라 bean이 필요로 하는 것을 본다.** `StartupRuleRunner.java:104-111,151-165,191-228`.
|
||||
실험 1-c·1-e·1-f에서 메타 애너테이션 `@Value`, 상속한 `@Autowired` setter, 인터페이스 타입 `static @Bean`이 돌려준 규칙이
|
||||
모두 이름과 멤버를 대며 실패했다. 템플릿의 rule·비밀 목록 클래스 13개에는 해당 멤버가 없다(grep). 2차의 두 probe 모양(JavaBean
|
||||
설정 겸 비밀 목록, `@Value` 필드 규칙)은 `StartupRuleRunnerTest.java:168-241`이 RED로 고정한다.
|
||||
- **축약 `-x`를 Gradle과 같은 규칙으로 맞춘다.** `TaskSelectors.java:114-170`, `StrictLaneStagesPlugin.java:126-157`.
|
||||
실험 3에서 2차가 거짓 통과로 잡은 `-x grpcPerformanceT`가 이제 실패한다. 실험 6에서 복사 원본(Gradle 9.0.0 `NameMatcher`)과
|
||||
고르는 순서가 같다. 모호한 선택자는 후보 전부를 뺀 것으로 쳐서 닫힌 쪽으로 틀린다.
|
||||
- **빌드 디렉터리를 설정이 아니라 저장소 구조에서 읽는다.** `StrictLaneStagesPlugin.java:239-250`,
|
||||
`WorkflowGradleInvocations.java:255-370`. 실험 4에서 실제 workflow 15개의 모든 단계 실행이 맞는 빌드로 읽혔다.
|
||||
`with: run:`과 `defaults.run`은 이제 명령이 아니다(`isStepRun`).
|
||||
- **`compileJava`→`processResources` 순서가 캐시와 증분을 깨지 않는다.** `SpringConfigConventionPlugin.java:20-41`.
|
||||
실험 5: 다른 리소스 변경은 `compileJava`를 건드리지 않고, 입력은 additional metadata 파일 하나뿐이며, 원복하면 캐시를 다시 쓴다.
|
||||
- **허용한 데모 프로필 셋이 같은 문서를 받고, 그 목록에서 테스트가 파생된다.**
|
||||
`src/sample-portfolio/src/main/resources/application.yml:215-232`(`on-profile: local | test | demo`),
|
||||
`SampleDemoProfilesStartupSystemTest.java:36-63`(`DEMO_PROFILES`에서 파라미터). object storage를 숨기던 테스트 리소스 복사본을
|
||||
지웠다(`application-test.yml:176-177`, `SampleDemoSecurityConfigTest.java:54-58`). `Dockerfile.sample:8-22`는 이제 `demo`를 넘긴다.
|
||||
- **lane json의 읽히지 않는 비-`APP_` 키가 실패한다.** `EnvContractVerifier.java:284,348-365`. 1차 사례
|
||||
`CASKELETON_GRPC_ENABLED`를 실패로 단언한다(`EnvContractVerifierTest.java:276-300`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
상태: 닫힘 / 부분 / 회귀 / 결정으로 닫힘.
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| RR2-04-01 | 닫힘(잔여 Minor RR3-04-03) | 검사 대상이 레지스트리 `secret` 행·모듈 기여·`secret://` 대상으로 좁혀짐(`SecretSourceValidator.java:170-202`). `HOSTNAME`·앱 이름·topic이 통과하는 테스트(`SecretSourceValidatorTest.java:165`). 코드가 들고 있는 Redis 계정 참조만 빠진다 |
|
||||
| RR2-04-02 | 닫힘 | 세 프로필이 같은 yml 문서(`application.yml:224`), 각 프로필 기동 시스템 테스트(`SampleDemoProfilesStartupSystemTest.java:36-63`), guard remedy·README·Dockerfile이 `demo`로 맞춰짐(`SampleDemoAccountsProductionGuard.java:47-53`, `src/sample-portfolio/README.md:56-59`, `src/Dockerfile.sample:8-22`). r5-d가 이미지 실제 기동(프로필 없음 exit 71, `demo` ready)을 확인 |
|
||||
| RR2-04-03 | 닫힘(잔여 Minor RR3-04-01) | "조용히 null"이 남는 경로는 찾지 못했다(실험 1-c·1-e·1-f, 기존 테스트 4건). 다만 인터페이스 타입 `static @Bean`이 돌려준 비밀 목록은 prod에서만 실패한다(실험 1-a·1-b) |
|
||||
| RR2-04-04 | 닫힘(잔여 Minor RR3-04-02, 이전부터) | 지목한 네 가지 모두 고침: 축약 `-x`(실험 3), `workflow_dispatch` 전용(`WorkflowGradleInvocations.java:277-325`, TestKit), `working-directory`+`-p`(실험 4), `with: run:`(`isStepRun`). 붙여 쓴 `-x<task>`는 이전부터 읽지 않는다 |
|
||||
| RR2-04-05 | 닫힘 | 비-`APP_` 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_` 이거나 `secret://` 대상이어야 한다(`EnvContractVerifier.java:348-365`). `property:` 행은 metadata에 있을 때만 읽힘(`:284`). `@ConditionalOnProperty` 스위치는 additional metadata로 선언(`objectstorage/.../additional-spring-configuration-metadata.json`) |
|
||||
| RR2-04-06 | 닫힘 | capability-status gRPC 행(`app.grpc.server.*`, `GrpcServerSettings.java:27`과 일치), `.env.example:298-299`, `exclude.xml:474-480` 근거 문장, `Dockerfile.sample`, `StartupRuleRunner` Javadoc·`src/app-bootstrap/CLAUDE.md:89-95` |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR3-04-01 · 인터페이스 타입 `static @Bean`이 돌려준 비밀 목록은 사전 검사를 지나, `@Value` 멤버가 prod에서만 기동을 막는다 (이번 라운드)
|
||||
|
||||
- **위치**: `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/startup/StartupRuleRunner.java:104-111`
|
||||
(사전 검사가 `beanFactory.getType(name, false)`, 즉 `@Bean` 메서드의 선언 반환 타입을 본다), 같은 파일 `:63-64` Javadoc,
|
||||
`docs/upgrade/2026-11-maturity-review.md:70` B-15("후자는 모든 프로필").
|
||||
- **무엇이 틀렸나**: 사전 검사의 목적은 주석대로 "prod 첫 기동이 아니라 쓴 곳에서 실패"다. 그런데 `@Bean static
|
||||
RequiredProductionSecrets x() { return new MySecrets(); }`처럼 선언 타입이 인터페이스면, 사전 검사는 인터페이스만 보고 통과한다.
|
||||
런타임 클래스 검사는 그 bean이 기동 중에 만들어질 때만 돈다. 규칙은 모든 프로필에서 만들어지므로 규칙 쪽은 문제없다(실험 1-f).
|
||||
비밀 목록은 `SecretSourceValidator`가 prod에서만 꺼내므로, 그 클래스의 `@Value` 필드는 prod에서만 걸린다.
|
||||
- **증거 (E3)**: 실험 1-a — 읽는 규칙이 없으면 기동 성공, bean은 나중에 정상 바인딩. 실험 1-b — 읽는 규칙이 있으면
|
||||
`'hiddenSecrets' ... needs one: [x (@Value)]`로 실패.
|
||||
- **왜 중요한가**:
|
||||
- 발생 조건: 템플릿 자신의 비밀 목록 선언이 모두 이 모양(`static RequiredProductionSecrets ...()`, 반환은 람다)이다. 이를
|
||||
베낀 서비스가 람다 대신 `@Value` 필드를 가진 클래스를 돌려주면 dev·CI·staging(prod 프로필이 아니면)은 통과하고 첫 운영 배포가
|
||||
exit 78로 멈춘다.
|
||||
- 조용한 실패는 아니다. 메시지가 bean·멤버를 짚고, rolling 배포면 옛 pod가 남는다. 문서가 금지한 모양이기도 하다.
|
||||
- 그래서 경계 판단에서 낮은 쪽(Minor)으로 둔다. 다만 B-15는 "모든 프로필"이라고 약속하므로 운영자가 CI 통과를 근거로 안심한다.
|
||||
- **고치는 법**: 사전 검사에서 `RequiredProductionSecrets` bean은 프로필과 무관하게 한 번 만들어(계약상 static·무인자라 비용이
|
||||
없다) `refusePulledForward`와 런타임 클래스 검사를 거친다. 또는 예측 타입이 인터페이스·추상 타입이면 같은 처리를 한다.
|
||||
실험 1-a를 RED 테스트로 쓴다.
|
||||
- **가이드 심각도·우선순위**: Low · P3.
|
||||
- **증거 등급**: E3.
|
||||
|
||||
#### RR3-04-02 · 붙여 쓴 `-x<task>`는 여전히 읽지 않아 `verifyStrictLaneStages`가 거짓 통과한다 (이전부터)
|
||||
|
||||
- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java:610-621`
|
||||
(`-x`·`--exclude-task`만 인자를 받고, `-`로 시작하는 나머지 토큰은 버린다). 문서 주장: `StrictLaneStagesPlugin.java:33-34`
|
||||
("matched the way Gradle matches it"), `src/build-logic/README.md:19`, AGENTS.md:85.
|
||||
- **무엇이 틀렸나**: Gradle 명령줄은 짧은 옵션에 값을 붙여 쓰는 것을 받는다(`-Dk=v`와 같은 규칙). `-xgrpcPerformanceTest`는 그
|
||||
태스크를 계획에서 뺀다. reader는 이 토큰을 모르는 옵션으로 버린다.
|
||||
- **증거 (E3)**: 실험 2와 3-b(Gradle이 붙여 쓴 `-x`로 lane을 뺀다), 실험 3(같은 줄로 optional 검사가 "every strict lane is in an
|
||||
executed stage"로 통과).
|
||||
- **왜 중요한가**: 이번 수정이 고친 축약 `-x`와 같은 종류의 거짓 통과다. 지금 workflow에는 이런 줄이 없다. 이 커밋이 만든
|
||||
틈은 아니다(2차 코드도 같은 토큰을 버렸다).
|
||||
- **고치는 법**: `token.startsWith("-x") && token.length() > 2`이면 나머지를 제외 선택자로 넣는다. 같은 자리에서 `-p<dir>`도
|
||||
읽는다(지금은 버려져 main 빌드 실행으로 센다). reader 단위 테스트 2건.
|
||||
- **가이드 심각도·우선순위**: Low · P3.
|
||||
- **증거 등급**: E3.
|
||||
|
||||
#### RR3-04-03 · 코드가 들고 있는 Redis 계정 참조는 `fixture-` 검사가 보지 않는다 (이번 라운드)
|
||||
|
||||
- **위치**: `SecretSourceValidator.java:170-202`(참조를 Environment의 문자열 값에서만 모은다),
|
||||
`src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/config/RedisRuntimeAutoConfiguration.java:147-156`
|
||||
(`RedisAccountContribution` bean의 참조도 같은 secret source로 풀어 접속한다),
|
||||
`src/adapter/outbound/redis-sdk/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/connection/RedisSdkComposition.java:20,85`.
|
||||
- **무엇이 틀렸나**: SDK admin plane 같은 모듈은 Redis 계정 참조를 bean(`RedisAccountContribution`)으로 넘긴다. Javadoc 예시는
|
||||
`secret://ca-skeleton-admin@environment/APP_REDIS_ADMIN`이다. 그 참조는 Environment 값이 아니므로 검사가 `APP_REDIS_ADMIN`을
|
||||
모른다. 그 변수는 레지스트리 `secret` 행도, 모듈이 기여한 비밀도 아니다. lane ACL에는 같은 계정의 공개 비밀번호
|
||||
`fixture-admin`이 있다(`infra/redis-sdk/acl/lane-fixture-accounts.acl:5`).
|
||||
- **왜 중요한가**: 2차 코드는 모든 값을 봤으므로 이 변수도 잡았다. 범위를 좁힌 결정(9.1절)이 낳은 작은 틈이다. 발생하려면
|
||||
서비스가 admin 계정을 조립하고 lane ACL 비밀번호를 운영에 옮겨야 해서 드물다. 이 계정은 읽기 전용 진단 권한만 있다.
|
||||
- **고치는 법**: `RedisAccountContribution`을 만드는 쪽(redis-sdk 조립)이 참조 이름을 `RequiredProductionSecrets`로도 내거나,
|
||||
`SecretSourceValidator`가 `ObjectProvider<RedisAccountContribution>`를 받지 않고도 볼 수 있게 참조를 설정 키로 받게 한다.
|
||||
최소한 ACL README의 "검사가 보는 비밀" 문장에 이 경로가 빠진다고 적는다.
|
||||
- **가이드 심각도·우선순위**: Low · P3.
|
||||
- **증거 등급**: E1(코드 읽기).
|
||||
|
||||
#### RR3-04-04 · `EnvContractVerifier`의 "선언된 property" 계산이 둘로 갈라져, 단위 테스트는 운영 경로를 보지 않는다 (이번 라운드)
|
||||
|
||||
- **위치**: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/config/EnvContractVerifier.java:98-124`(7인자 overload가 scope
|
||||
metadata 파일에서 계산), `VerifyEnvKeysTask.java:86-87`(태스크는 metadata classpath 전체에서 계산해 8인자 overload로),
|
||||
`EnvContractVerifierTest.java:329-336`(모든 테스트가 7인자).
|
||||
- **무엇이 틀렸나**: RR2-04-05의 새 규칙("`property:` 행은 선언됐을 때만 읽힘")의 입력을 두 곳이 다르게 만든다. 테스트가 부르는
|
||||
쪽은 `app.redis.` scope 파일만, 태스크는 classpath의 모든 metadata다. 운영 계산(`propertiesUnder(..., "")`)은 단위 테스트에 없다.
|
||||
- **왜 중요한가**: 규칙 자체는 `mainCheck`의 실제 `verifyEnvKeys`가 지금 저장소로 확인한다. 그러나 classpath 계산이 틀어져도
|
||||
(예: additional metadata를 못 읽음) 단위 테스트는 녹색이다.
|
||||
- **고치는 법**: 7인자 overload가 declared를 따로 만들지 말고 호출자가 넘기게 하거나, `propertiesUnder`를 쓰는 테스트 하나를 둔다.
|
||||
- **가이드 심각도·우선순위**: Low · P3.
|
||||
- **증거 등급**: E1.
|
||||
|
||||
#### RR3-04-05 · sample `application.yml` 주석이 시스템 테스트를 실제보다 강하게 말한다 (이번 라운드)
|
||||
|
||||
- **위치**: `src/sample-portfolio/src/main/resources/application.yml:216-220`("starts the sample under each listed profile with
|
||||
nothing but this file and a database address").
|
||||
- **무엇이 틀렸나**: `test` 프로필에서는 systemTest 소스셋의 `application-test.yml`도 함께 읽힌다. 테스트 Javadoc
|
||||
(`SampleDemoProfilesStartupSystemTest.java:27-29`)은 이를 적는다. 출하 설정에서 `test`와 `demo`가 같은 문서를 받으므로
|
||||
결론(세 프로필 모두 뜬다)은 `demo` 실행으로 성립한다. 주석 문장만 틀렸다.
|
||||
- **고치는 법**: "`demo`·`local`은 이 파일만으로, `test`는 테스트 리소스를 더해 띄운다"로 고친다.
|
||||
- **가이드 심각도·우선순위**: Low · P3.
|
||||
- **증거 등급**: E1.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- 실험 1-d: 생성자 `@Value`를 가진 `@Import` 규칙이 `No default constructor found`로 실패한다 — 이전부터의 동작이고 모든
|
||||
프로필에서 크게 실패한다. 새 메시지가 "static `@Bean`의 생성자 인자로 넘겨라"라고 바른 길을 알려 준다.
|
||||
- 실험 1-b에서 규칙이 실패 직전에 바인딩 안 된 비밀 목록을 한 번 호출한다 — 바로 기동이 멈추므로 해가 없다.
|
||||
- `ConfigTreePropertySource`(Kubernetes secret 파일 mount) 값은 `String`이 아니라서 `forEachStringValue`가 건너뛴다. 센티넬
|
||||
검사는 이전부터 같다. `fixture-` 검사는 분류된 키를 `getProperty`로 풀어 잡으므로, 빠지는 것은 참조 자체를 파일로 mount한
|
||||
드문 경우뿐이다.
|
||||
- `RedisCredentialResolver`는 첫 `/`, `SecretReference.parse`는 마지막 `/`로 이름을 자른다 — 이름에 `/`가 든 환경 변수는
|
||||
현실적이지 않다. 이전부터.
|
||||
- HTTP client가 `secret://` 없는 평문 키 참조를 받는데 검사는 `secret://`만 모은다 — lane fixture 비밀번호가 흘러갈 경로가 아니다.
|
||||
- `paths:` 필터가 있는 PR workflow, `needs:`로 조건부 job에 묶인 job의 명령을 실행으로 센다 — 이전부터의 reader 범위이고 지금
|
||||
단계는 필터 없는 workflow가 돈다(실험 4).
|
||||
- `cd <dir> && ../gradlew` 형태의 디렉터리 이동은 읽지 않는다 — 이전부터. 이번 결정(B-36)은 `working-directory`를 요구한다.
|
||||
- 비-`APP_` 키 허용 접두사(`SPRING_`·`MANAGEMENT_`·`SERVER_`) 안의 오타는 통과한다 — RR2-04-05 고치는 법이 고른 수준이다.
|
||||
- `SampleDemoProfilesStartupSystemTest`가 Docker 없으면 건너뛴다(`disabledWithoutDocker`, systemTest lane은 skip을 거부하지 않음) —
|
||||
sample systemTest 전체가 같은 방식이다. 이전부터.
|
||||
- `CLASSIFIED_SECRETS`가 레지스트리의 복사본이다 — 테스트가 1:1로 묶으므로 갈라질 수 없다.
|
||||
- `TaskSelectors`가 Gradle 내부 클래스의 복사본이다 — 내부 API라서 부를 수 없고, Gradle 버전을 올리면 다시 맞춰야 한다. 실험 6에서
|
||||
9.0.0과 같은 모양.
|
||||
- `docs/upgrade` 표의 멱등성·마이그레이션 행 — r5-a·r5-c 소관.
|
||||
|
||||
## 수렴 판단 — 이 라운드가 만든 새 Important 이상이 있는가
|
||||
|
||||
**없다.**
|
||||
|
||||
- 2차의 Important 3건(RR2-04-01·02·03)은 모두 닫혔다. 01·03은 코드와 실험으로, 02는 시스템 테스트와 r5-d의 이미지 실행으로 확인했다.
|
||||
- 이 라운드가 만든 새 결함은 Minor 4건(RR3-04-01·03·04·05)이다. 가장 무거운 RR3-04-01도 조용한 실패가 아니라 이름을 대는
|
||||
기동 실패이고, 문서가 금지한 모양에서만 생긴다.
|
||||
- RR3-04-02는 이전부터 있던 틈이다.
|
||||
|
||||
이 영역은 다음 수정 라운드가 필요하지 않다. Minor는 후속 작업으로 둘 수 있다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? Yes.**
|
||||
|
||||
2차의 RR2-04-01~06은 코드·테스트·실험으로 닫혔고 회귀는 없다. 남은 것은 Low 5건(이번 라운드 4, 이전부터 1)이며,
|
||||
그중 운영에 닿는 RR3-04-01도 크게 실패하는 쪽이라 머지를 막지 않는다.
|
||||
@@ -0,0 +1,238 @@
|
||||
# r6 확인 리뷰 (2026-11-04)
|
||||
|
||||
대상: 커밋 `f40c03c6`(3차 확인 리뷰 Minor 19건 수정), Base `339cf8fd`. 리뷰어 1명이 네 영역을 나눠 직접 봤다(하위 에이전트 없음).
|
||||
발견 ID는 `RR4-<영역>-<순번>`이다. 영역 번호: 01 core·inbound, 02 persistence, 03 outbound·멱등성, 04 bootstrap·build.
|
||||
|
||||
## 범위
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
| 영역 | pathspec |
|
||||
| --- | --- |
|
||||
| 01 core·inbound | `src/application-core src/adapter/inbound src/composition/service-runtime src/app-bootstrap/src/architectureTest docs/manual/07-authorization.md docs/fileserver/operations.md` (+ `src/shared-contract`의 `OperationalError` 한 줄) |
|
||||
| 02 persistence | `src/adapter/outbound/persistence-jpa src/sample-portfolio src/grpc docs/jpa docs/runbooks/migration-failed.md docs/manual/04-persistence.md` (+ `docs/runbooks/outbox-dead-letter.md`) |
|
||||
| 03 outbound·멱등성 | `src/adapter/outbound/httpclient src/adapter/outbound/cache-redis src/application-core/.../idempotency docs/runbooks/idempotency-unavailable.md docs/web/http-contract.md docs/manual/05-idempotency.md` (+ `docs/httpclient`, `docs/registries/env-keys.yaml` 해당 행, `src/.env.example`, `src/composition/idempotency/README.md`, redis-runtime testFixtures의 `InMemorySemanticRedisCommands`) |
|
||||
| 04 bootstrap·build | `src/adapter/outbound/support src/app-bootstrap src/build-logic src/adapter/outbound/redis-sdk docs/upgrade/2026-11-maturity-review.md` (+ `infra/redis-sdk/acl/README.md`) |
|
||||
|
||||
요구사항은 `docs/reviews/2026-11-03-rereview/README.md` 11·11.1·12절과 `round3/01~04-*.md`의 "고치는 법"으로 맞춰 봤다.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 본 것 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 계획 대비 구현, Strengths·심각도별 Issues·Assessment, Declined to judge, 읽기 전용, 하위 에이전트 금지 | 19건 각각을 "고치는 법"과 대조했다. 이 문서 양식이 그 템플릿이다 |
|
||||
| `clean-architecture` | Dependency Rule(사용자 전송 → 권한 없는 쓰기 방향 금지), "Main(조립 설정)은 바깥의 plugin" | 새 규칙 `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`가 조립 설정을 사용자 전송으로 잘못 세는 경우(RR4-01-02), 의존 방향이 인터페이스로 뒤집히면 규칙이 못 보는 경우(RR4-01-01) |
|
||||
| `security-and-hardening` | 인가 경계(사용자 요청이 권한 없는 쓰기에 닿지 않음), "민감 데이터를 로그에 싣지 않는다", 파생 경로의 파괴적 조작은 소유 증거를 먼저 읽는다 | scope digest가 HMAC 값이고 응답에는 고정 문구만 나가는지, runbook의 삭제 명령이 상태를 확인하고 지우는지(RR4-03-02), `fixture-` 비밀 검사 문서 경로(RR3-04-03) |
|
||||
| `jpa-patterns` | 마이그레이션은 Flyway가 맡고 추가형으로, 양방향 연관은 한쪽에서만 | 잠금 대기 검사기 목록·상한 판정·`.sql.conf`, 동결 목록에 더한 5개 파일, 연관 규칙 메시지 |
|
||||
| `performance-optimization` | 측정 전후 비교, 개선을 지키는 회귀 장치가 실제로 회귀를 잡는가 | watchdog RED 테스트가 공용 풀 병렬도 1(2 vCPU)에서는 옛 코드도 통과시킴을 측정(RR4-03-01), read당 비용 주장은 다시 재지 않았다 |
|
||||
| `ci-cd-and-automation` | 게이트를 조용히 건너뛰지 못하게, 검사가 약해지지 않게 | 붙여 쓴 `-x`·`-p` 해석, `EnvContractVerifier` 합치기 뒤 빈 prefix가 이제 실패하는지(전보다 강해짐) |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
1. `git rev-parse 01a8a2a70:<path>` 대 `f40c03c6:<path>` — 동결 목록에 더한 5개 파일(`jpa/idempotency/V1`, `postgresql/V11`·`V12`, `jpa/notification-platform/V3`, `messaging/V1003`)의 blob이 main과 모두 같다.
|
||||
2. `javap -c` ArchUnit 1.3.0 `TransitiveDependencyCondition` — 규칙 대상 클래스(사용자 전송)를 경로 중간에서 건너뛰고(`getDirectDependencyTargetsOutsideOfAnalyzedClasses`), 대신 그 클래스 자신을 따로 검사한다. 그래서 경로의 마지막 사용자 전송에서 위반이 잡히고 이 필터로 생기는 거짓 음성은 없다.
|
||||
3. 따로 만든 worktree(`f40c03c6`)에 탐침 fixture 7개와 테스트 1개를 넣고
|
||||
`flock … ./gradlew :app-bootstrap:architectureTest --tests '*Rr4ProbeTest*' --offline -x spotlessCheck -x spotlessJavaCheck` → rc=0, 25초. 결과:
|
||||
|
||||
| 탐침 | 위반 |
|
||||
| --- | --- |
|
||||
| controller가 `@SystemCaller` 작업을 자기 인터페이스 타입으로 주입받아 호출 | **없음** (거짓 음성) |
|
||||
| controller가 `@Qualifier` `Runnable`로 주입받아 호출 | **없음** (거짓 음성) |
|
||||
| controller가 `ObjectProvider<구체 handler>`로 꺼내 호출 | 있음 (문서는 "못 잡는다"고 적음) |
|
||||
| `@Configuration`이 handler bean과 `HandlerInterceptor` bean을 함께 등록 | **있음** (거짓 양성) |
|
||||
| `@Configuration`이 handler bean과 controller bean을 함께 등록 | **있음** (거짓 양성) |
|
||||
|
||||
4. `LockWaitMigrationInspector`·`MigrationResource`를 `javac`로 컴파일해 입력 16개를 돌렸다. `SET LOCAL lock_timeout = '5s'; VACUUM FULL poster;` → `[]`(상한 있음으로 판정), `REINDEX (CONCURRENTLY) TABLE poster;` → 거부, `GRANT SELECT, REFERENCES ON TABLE poster TO r;` → `references on` 거부, `.sql.conf`의 `executeInTransaction=FALSE` → 트랜잭션 안으로 판정. 나머지(`'0.5s'`, `'1min'`, 주석 안의 `lock_timeout = 0`, `REFERENCES public.parent`, 따옴표 표 이름)는 기대대로였다.
|
||||
5. JDK `CompletableFuture.delayedExecutor` 공용 풀 포화 탐침 — 병렬도 21: 5,997 ms(공용 풀 worker), 병렬도 3: 6,000 ms, **병렬도 1: 302 ms(새 스레드 `Thread-1`)**.
|
||||
6. 끝나고 `git worktree remove --force`로 탐침 worktree를 지웠다. 이 체크아웃은 바꾸지 않았다(이 문서만 새로 씀).
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 전체 게이트는 다시 돌리지 않았다(README 12.1절 결과를 그대로 둔다).
|
||||
- runbook의 Redis·PostgreSQL 명령(`HMGET`·`DEL`·`DELETE … status = 'ABANDONED'`, `pg_locks` 조회)을 실 서버에서 직접 실행하지 않았다. 코드와 스키마(`V1__expand_owner_safe_v2.sql:48-81`)로만 맞춰 봤다.
|
||||
- gRPC ledger IT와 실 PG lane은 돌리지 않았다.
|
||||
- `docs/reviews/2026-11-03-rereview/README.md` 12절 본문은 요구사항으로만 읽고 리뷰 대상으로 보지 않았다.
|
||||
|
||||
## Strengths
|
||||
|
||||
- `ApplicationBoundaryArchitectureTest.java:564-566` — 표시 검사 대상이 `ARE_SYSTEM_CALLERS`로 바뀌어, 첫 규칙이 면제하는 집합과 둘째 규칙이 검사하는 집합이 같아졌다.
|
||||
- `ApplicationBoundaryArchitectureTest.java:592-605` + `ArchitectureViolationFixtureTest` — 위반 fixture(직접·중간 클래스·중첩 endpoint·JAX-RS)와 허용 fixture(`SystemCallerHandlerRegistrationFixture`)가 함께 있다. 규칙이 너무 넓어지면 허용 fixture가 깨진다.
|
||||
- `ReadIdleInputStream.java:158-171` — close와 예약이 각자 volatile을 쓰고 상대 값을 읽어, 둘 중 하나는 반드시 남은 wake를 취소한다. `setRemoveOnCancelPolicy(true)`(`:90-101`)로 취소한 wake가 큐에서 바로 빠지고, 테스트 두 개가 큐가 빈 것을 직접 본다.
|
||||
- `MigrationLockWaitTest.java:70-99` — 동결 목록을 두 방향(`isSubsetOf`, `containsAll`)으로 검사한다. 더한 5개 파일은 main과 blob이 같다(명령 1).
|
||||
- `VersionedMigrationFiles.java:25` — 운영 tree와 sample이 버전 정의 하나를 쓴다.
|
||||
- `StartupRuleRunner.java:115-124` — 비밀 목록을 모든 프로필에서 먼저 만들고, 다른 bean이 생기면 이름을 대며 실패한다. 순서 변경이 다른 bean을 조용히 앞당길 길이 없다.
|
||||
- `EnvContractVerifier.java:176-193` — 계산이 하나가 됐고, typed prefix 아래 선언이 하나도 없으면 실패한다. 옛 태스크는 빈 metadata 파일을 써서 이 경우를 조용히 통과시켰다. 검사는 약해지지 않고 강해졌다.
|
||||
- `IdempotencyExecutor.java:368-371` — 회복 필요 예외를 만드는 곳이 하나라 모든 경로가 digest를 싣는다. digest는 HMAC 값이고(`IdempotencyScopeDigest.java:6-11`), 응답은 고정 문구다(`GlobalExceptionHandler.java:187-200`, `GrpcStatusMapper.java:73`).
|
||||
- `docs/runbooks/idempotency-unavailable.md:90-96` — PostgreSQL 삭제가 `status = 'ABANDONED'`를 조건에 넣은 한 문장이라 원자적이다.
|
||||
- `IdempotencyStoreContract.java:384` — inspect lease를 두 저장소에 같은 단언으로 건다. Redis는 INSPECT가 `leaseUntil`을 돌려준다(`IdempotencyScripts.java:279`).
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| RR3-01-01 | 닫힘 | 고치는 법 1~3 모두: `ApplicationBoundaryArchitectureTest.java:566`(`that(ARE_SYSTEM_CALLERS)`), 새 규칙 `:592-605`, fixture `ArchitectureViolationFixtureTest`(직접·중간 클래스·중첩·허용). 남은 빈틈은 RR4-01-01·02(이 수정이 만든 규칙의 경계) |
|
||||
| RR3-01-02 | 닫힘 | `:466-469`(목록 방식 주석), `:482-483`(`jakarta.ws.rs..`·`graphql..`), 매뉴얼 07 `:106-110`, messaging README `:117-120`. `graphql..` fixture는 없다(README 12절에 기록) |
|
||||
| RR3-01-03 | 닫힘 | `docs/fileserver/operations.md:188`(`0, held`), `:173-174`(행 모양), `:136-137`(newest-first 서술) |
|
||||
| RR3-01-04 | 닫힘 | 매뉴얼 07 `:85-97`(정본 표), `:128-130`, `src/application-core/CLAUDE.md:205-210`, 업그레이드 안내 B-16, `PermissionEnforcementGuard.java:35-41` |
|
||||
| RR3-02-01 | 닫힘 | 목록 `LockWaitMigrationInspector.java:71-101`, 0·`DEFAULT`·`RESET` `:203-212`, `.sql.conf` `:158-164`, `IF NOT EXISTS` `:67`, 가이드 `docs/jpa/migration-guide.md:48-66`. 새 항목 `VACUUM FULL`의 판정 빈틈은 RR4-02-01 |
|
||||
| RR3-02-02 | 닫힘 | `docs/runbooks/migration-failed.md:47-60`, `docs/runbooks/outbox-dead-letter.md:132-142`(`pg_locks` + `granted`, `query` 주의) |
|
||||
| RR3-02-03 | 닫힘 | `VersionedMigrationFiles.java:25`, `MigrationTrees.java:52-62`, `SampleMigrationLockWaitTest.java:35`, `VersionedMigrationFilesTest`. gRPC는 정규식 한 벌을 따로 둔다(`GrpcOperationLedgerMigrations.java:38`, README 12절에 이유 기록) |
|
||||
| RR3-02-04 | 닫힘 | `GrpcOperationLedgerMigrations.java:34-42`(디스크 tree), `GrpcOperationLedgerMigrationLockWaitIT.java:60-65`(V001 뒤 전체) |
|
||||
| RR3-02-05 | 닫힘 | `SingleSidedAssociationCondition.java:142-165`(`Storage`로 저장 위치 판정), `:190-216`, 테스트 2건(`JpaArchitectureRulesTest`) |
|
||||
| RR3-03-01 | 닫힘 | `ReadIdleInputStream.java:90-101`, `:158-171`, `:217-220`. RED 테스트의 판별력 빈틈은 RR4-03-01, 스레드 수명은 RR4-03-04 |
|
||||
| RR3-03-02 | 닫힘 | `docs/web/http-contract.md:125-137`, `docs/manual/05-idempotency.md:60-63`, `env-keys.yaml` 해당 행 주석, `OperationalError.java:50-51`. 기동 검사는 소유자 결정으로 넣지 않음 |
|
||||
| RR3-03-03 | 닫힘 | (a) runbook `:20-25` (b) `IdempotencyExecutor.java:368-371` + 테스트 3경로 (c) runbook `:40-70`, `:79-101` |
|
||||
| RR3-03-04 | 닫힘 | `src/adapter/outbound/httpclient/README.md:45-46`, `docs/httpclient/configuration-reference.md:106-110`, `src/application-core/CLAUDE.md:274-276` |
|
||||
| RR3-03-05 | 닫힘 | `IdempotencyScripts.java:279`, `RedisIdempotencyStoreAdapter.java:364-373`, 계약 `IdempotencyStoreContract.java:384`, fake `InMemorySemanticRedisCommands` |
|
||||
| RR3-04-01 | 닫힘 | `StartupRuleRunner.java:115-124`, 테스트 `StartupRuleRunnerTest.java:249`(인터페이스 타입 `@Value`)와 바로 아래(규칙 없이 앞당김), B-15 문구 |
|
||||
| RR3-04-02 | 닫힘 | `WorkflowGradleInvocations.java:619-624`, 테스트 `WorkflowGradleInvocationsTest.java:231`, `:247` |
|
||||
| RR3-04-03 | 결정으로 닫힘 | 코드 수정은 새 의존 edge가 필요해 하지 않음(README 12절). 조립 쪽 `static RequiredProductionSecrets` 방법을 `RedisSdkComposition.java:17-35`, redis-sdk README `:43-55`, ACL README, `SecretSourceValidator.java:170-174`, B-14에 적음. Javadoc 예시의 계정 이름도 ACL 파일(`ca-skeleton-admin-readonly`)과 맞춤 |
|
||||
| RR3-04-04 | 닫힘 | `EnvContractVerifier.java:176-193`(classpath 한 계산), 테스트 `EnvContractVerifierTest.java:68`, `:375` |
|
||||
| RR3-04-05 | 닫힘 | `src/sample-portfolio/src/main/resources/application.yml:220-222` |
|
||||
|
||||
회귀로 판정한 발견: 없음.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR4-01-01 · 새 규칙은 인터페이스 타입으로 주입한 시스템 호출자를 못 본다 — 문서는 보이지 않는 경로를 반대로 적었다
|
||||
|
||||
- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:581-605`,
|
||||
`src/application-core/src/main/java/dev/caskeleton/application/security/SystemCaller.java:26-27`,
|
||||
`docs/manual/07-authorization.md:75`, `:104`, `:112-113`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 규칙은 사용자 전송에서 `@SystemCaller` 클래스로 가는 의존 경로를 찾는다.
|
||||
- controller가 작업을 그 작업의 인터페이스(자기 인터페이스, `Runnable`, `MessageHandler<T>`)로 주입받으면 경로가 없다. 의존은 작업 → 인터페이스 방향이기 때문이다. 탐침 두 개가 위반 없이 통과했다(범위 명령 3).
|
||||
- 문서 세 곳은 못 보는 경로로 `getBean`과 `ObjectProvider`를 든다. 그런데 `ObjectProvider<구체 handler>`는 타입 인자 의존으로 잡힌다(탐침). 못 보는 진짜 경로(인터페이스·상위 타입 주입, 문자열 이름 `getBean`)는 적혀 있지 않다.
|
||||
- 매뉴얼 흐름도 `:75`는 "빌드 실패, 중간 클래스를 거쳐도"라고 적는다.
|
||||
- **왜 중요한가**:
|
||||
- 발생 조건: 예약 작업과 controller가 같은 leaf에 있고(매뉴얼 07 `:94`가 "놓이기 쉽다"고 적은 경우), "지금 실행" endpoint가 작업을 인터페이스로 받는다. Spring에서 인터페이스 주입은 흔한 습관이다.
|
||||
- 영향: 인증만 된 사용자가 권한 검사 없는 쓰기를 부른다. 빌드는 신호가 없고, 문서는 이 모양을 잡는다고 읽힌다.
|
||||
- Minor로 둔 이유(경계): 원 발견 RR3-01-01과 같은 조건(같은 leaf)에 인터페이스 주입까지 겹쳐야 한다. 매뉴얼은 사용자용 실행을 `@RequiresPermission` 유스케이스로 따로 만들라고 적는다. endpoint는 인증을 요구한다.
|
||||
- **고치는 법**:
|
||||
1. 최소: 세 문서의 "못 보는 것"을 "인터페이스·상위 타입으로 주입받거나 이름으로 `getBean`한 시스템 호출자"로 고친다. `ObjectProvider` 예시는 지우거나 "구체 타입이면 잡힌다"로 고친다. 흐름도 `:75`에 같은 단서를 단다.
|
||||
2. 규칙을 넓히려면: 대상 술어를 "`@SystemCaller` 클래스, 또는 `@SystemCaller` 클래스만 구현하는 프로젝트 인터페이스"로 넓힌다. `Runnable`·`MessageHandler` 같은 공용 인터페이스는 이 방법으로 막을 수 없으니 1은 어느 쪽이든 필요하다.
|
||||
3. 탐침 두 개(자기 인터페이스, `Runnable`)를 허용·위반 어느 쪽인지 정한 fixture로 남긴다.
|
||||
- **가이드 심각도·우선순위**: Low · P3 (경계: 같은 leaf 조건이 서면 Medium)
|
||||
- **증거**: E2 — worktree 탐침 테스트(범위 명령 3). 통제: 구체 타입 경로 M3, 인터페이스 경로 M1(문서도 틀림).
|
||||
|
||||
#### RR4-01-02 · 웹 타입을 하나라도 쓰는 조립 설정이 handler를 등록하면 "사용자 전송"으로 잡힌다 (거짓 양성)
|
||||
|
||||
- **위치**: `ApplicationBoundaryArchitectureTest.java:492-506`(`ARE_USER_TRANSPORTS`), `docs/manual/07-authorization.md:104`
|
||||
("그래서 handler를 bean으로 등록하는 `@Configuration`은 걸리지 않는다"),
|
||||
`src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/adapter/inbound/messaging/SystemCallerHandlerRegistrationFixture.java:5-9`.
|
||||
- **무엇이 틀렸나**:
|
||||
- `ARE_USER_TRANSPORTS`는 "사용자 전송 타입에 직접 의존하는 클래스"다. 그 타입에는 `org.springframework.web..` 전체와 `..adapter.inbound.web..` 패키지의 모든 클래스가 들어간다.
|
||||
- 그래서 handler bean을 등록하는 `@Configuration`이 `HandlerInterceptor`·`WebMvcConfigurer` bean을 함께 만들거나 controller bean을 함께 등록하면 사용자 전송이 된다. 그 설정은 handler에 직접 의존하므로 실패한다. 탐침 두 개가 모두 위반이었다(범위 명령 3).
|
||||
- 허용 fixture는 웹 타입이 하나도 없는 설정만 본다. 매뉴얼 `:104`는 조건 없이 "걸리지 않는다"고 적는다.
|
||||
- **왜 중요한가**:
|
||||
- 발생 조건: 서비스가 feature 설정 클래스 하나에 웹 쪽 bean과 메시지 handler bean을 같이 둔다. 매뉴얼 09 「소비」 4단계 예시가 "이 leaf의 설정 클래스"에 handler를 등록하라고 적어 이 모양을 부른다.
|
||||
- 영향: 빌드가 실패하고 메시지는 "사용자 요청이 들어오는 클래스가 시스템 호출자에 닿는다"고 말한다. 실제로는 그런 경로가 없다. 권한 구멍은 아니다(실패 쪽으로 틀린다). 개발자가 원인을 찾느라 시간을 쓰고, 규칙을 믿지 않게 된다.
|
||||
- **고치는 법**: 하나를 고른다.
|
||||
- `ARE_USER_TRANSPORTS`에서 `@Configuration`·`@AutoConfiguration` 클래스를 뺀다. 조립 설정은 전송이 아니라 Main 쪽이다. 대신 설정이 controller를 `new`로 만들어 넘기는 길은 controller 자신이 검사받는지 확인한다(controller는 패키지로 이미 대상이다).
|
||||
- 또는 "타입에 의존"을 endpoint 표시(`@Controller`, `@RestController`, `@RequestMapping` 계열, `@MessageMapping`, `@Path`, gRPC `BindableService`)로 좁힌다.
|
||||
- 어느 쪽도 하지 않으면 매뉴얼 `:104`에 "웹 bean과 handler bean은 다른 설정 클래스에 둔다"를 적는다.
|
||||
- 탐침의 두 모양을 허용 fixture로 남긴다.
|
||||
- **가이드 심각도·우선순위**: Low · P3
|
||||
- **증거**: E2 — worktree 탐침 테스트(범위 명령 3).
|
||||
|
||||
#### RR4-02-01 · 검사기가 Flyway가 스스로 트랜잭션 밖에서 돌리는 문장을 모른다 — 새로 넣은 `VACUUM FULL`은 `SET LOCAL`과 함께 쓰면 통과한다
|
||||
|
||||
- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/migration/LockWaitMigrationInspector.java:89-92`(`VACUUM FULL`),
|
||||
`:80-83`(`REINDEX`), `:93`(`REFERENCES`), `:122-123`·`:158-164`(`.sql.conf`만 읽음), `docs/jpa/migration-guide.md:48-52`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 검사기는 `.sql.conf`의 `executeInTransaction=false`만 "트랜잭션 밖"으로 친다.
|
||||
- PostgreSQL에서 `VACUUM`은 트랜잭션 안에서 돌 수 없다. Flyway는 이런 문장을 스스로 알아보고 마이그레이션을 트랜잭션 밖에서 돌리거나(`mixed=true`), 다른 문장과 섞이면 거부한다(기본 `mixed=false`).
|
||||
- 그래서 `SET LOCAL lock_timeout = '5s'; VACUUM FULL t;`는 검사기에서 `[]`(상한 있음)이다(범위 명령 4). 실제로는 상한이 걸리지 않는다. `SET LOCAL`이 없으면 거부하고, 거부 메시지가 시키는 대로 `SET LOCAL`을 넣으면 통과하지만 Flyway가 받지 않는 파일이 된다. 이 항목은 맞게 통과할 길이 없다.
|
||||
- 같은 계열의 작은 오판: PG14 문법 `REINDEX (CONCURRENTLY) TABLE t`를 비동시로 거부한다. `GRANT … REFERENCES ON TABLE t`를 `references on`으로 거부한다. `executeInTransaction=FALSE`(대문자)를 트랜잭션 안으로 본다(Flyway가 대소문자를 가리는지는 확인하지 않았다).
|
||||
- **왜 중요한가**:
|
||||
- 기본 설정(`mixed=false`)에서는 배포 때 Flyway가 그 파일을 거부한다. 운영 중단이 아니라 실패한 배포다. `mixed=true`를 켠 서비스에서만 상한 없는 `ACCESS EXCLUSIVE` 대기가 된다. 템플릿은 `mixed`를 켜지 않는다(grep).
|
||||
- 나머지 셋은 대부분 거부 쪽 오판이라 피해가 작다.
|
||||
- **고치는 법**: 트랜잭션 밖에서만 도는 문장(`VACUUM`, `… CONCURRENTLY`, `REINDEX (CONCURRENTLY…)`)이 하나라도 있으면 `.sql.conf`와 같게 "트랜잭션 밖"으로 판정한다. `VACUUM FULL`은 "마이그레이션에 두지 않는다, 운영 절차로 한다"는 문장으로 거부한다. `REINDEX` 정규식의 괄호 옵션에서 `concurrently`를 읽는다. 가이드 `:48-52`에 "Flyway가 스스로 트랜잭션 밖에서 돌리는 문장"을 적는다.
|
||||
- **가이드 심각도·우선순위**: Low · P3
|
||||
- **증거**: E2 — 검사기를 그대로 컴파일해 입력 16개를 돌렸다(범위 명령 4). Flyway의 non-transactional 판정은 E0(문서·지식), 실행하지 않았다.
|
||||
|
||||
#### RR4-03-01 · watchdog RED 테스트는 공용 풀 병렬도가 1인 머신에서 옛 코드도 통과시킨다
|
||||
|
||||
- **위치**: `src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/jdk/ReadIdleInputStreamTest.java:74-107`
|
||||
(`aStalledReadTimesOutOnTimeWhileTheCommonPoolIsBlocked`, `:82`의 `getCommonPoolParallelism()`).
|
||||
- **무엇이 틀렸나**:
|
||||
- 테스트는 공용 `ForkJoinPool`을 막고 read-idle이 제때 나는지 본다. 옛 코드(`CompletableFuture.delayedExecutor`)로 돌아가는 회귀를 잡으려는 테스트다.
|
||||
- JDK는 공용 풀 병렬도가 1 이하이면 `delayedExecutor`의 작업을 공용 풀이 아니라 매번 새 스레드에서 돌린다. 그래서 그 환경에서는 옛 코드도 제때 깨어나 테스트가 통과한다. 탐침: 병렬도 1에서 302 ms(`Thread-1`), 병렬도 3에서 6,000 ms(범위 명령 5).
|
||||
- 병렬도 1은 CPU 2개 머신이다. workflow는 `ubuntu-latest`다. private 저장소의 기본 runner는 2 vCPU라 CI에서 이 테스트가 회귀를 못 잡는다.
|
||||
- **왜 중요한가**: 고친 동작(전용 스레드)은 맞다. 그러나 이 테스트가 지키는 회귀는 CI 머신 크기에 따라 보이거나 안 보인다. 개발 머신(병렬도 21)에서는 잡힌다. 원 결함이 Low라서 이 빈틈도 Low다.
|
||||
- **고치는 법**: 머신과 무관한 단언 하나를 더한다. 예: 막힌 read를 깨운 스레드 이름이 `httpclient-jdk-read-idle`인지 본다(주입한 `newWatchdogs()` 스케줄러로 확인 가능). 또는 그 테스트 클래스 JVM에 `-Djava.util.concurrent.ForkJoinPool.common.parallelism=4`를 준다.
|
||||
- **가이드 심각도·우선순위**: Low · P3
|
||||
- **증거**: E2 — JDK 탐침(범위 명령 5). workflow 파일의 `runs-on: ubuntu-latest` 확인. 저장소 공개 여부는 확인하지 않았다.
|
||||
|
||||
#### RR4-03-02 · Redis 기록 삭제가 "확인한 뒤 지우기" 두 명령이다
|
||||
|
||||
- **위치**: `docs/runbooks/idempotency-unavailable.md:86-88`.
|
||||
- **무엇이 틀렸나**: `HMGET <key> state`로 `ABANDONED`를 보고 `PTTL`에 몇 분 남았는지 본 뒤 `DEL <key>`를 친다. 두 명령 사이에 key가 만료되고 같은 키의 새 요청이 새 기록(`CLAIMED`·`EXECUTING`)을 만들면 `DEL`이 진행 중인 기록을 지운다. 그 뒤 같은 키의 다음 요청은 작업을 한 번 더 돌린다.
|
||||
- **왜 중요한가**: runbook은 "몇 분 남았을 때만"이라는 조건으로 이 창을 줄였다. `ABANDONED`는 key가 있는 동안 다른 상태로 바뀌지 않는다(`IdempotencyScripts.java:76-78`). 그래서 현실적 발생 확률은 낮다. PostgreSQL 쪽은 한 문장이라 이 문제가 없다.
|
||||
- **고치는 법**: Redis도 한 번에 확인하고 지운다.
|
||||
`EVAL "if redis.call('HGET', KEYS[1], 'state') == 'ABANDONED' then return redis.call('DEL', KEYS[1]) end return 0" 1 <key>` — 결과 1이면 지움, 0이면 상태가 바뀐 것이니 멈춘다.
|
||||
- **가이드 심각도·우선순위**: Low · P3
|
||||
- **증거**: E1 — runbook과 Lua 상태 전이 대조.
|
||||
|
||||
#### RR4-03-03 · (이전부터) gRPC 전송은 회복 필요 실패를 로그에 남기지 않아, runbook의 digest 찾기를 따라 할 수 없다
|
||||
|
||||
- **위치**: `docs/runbooks/idempotency-unavailable.md:40-45`("the web adapter logs …"),
|
||||
`src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java`(carrier 실패에 `log` 호출이 없다).
|
||||
- **무엇이 틀렸나**: runbook의 진단 첫 단계는 web adapter의 ERROR 줄에서 digest를 찾는 것이다. gRPC로 같은 쓰기를 받는 서비스에는 그 줄이 없다. runbook은 gRPC를 언급하지 않는다. README 12절은 "본 것"으로 적었지만 runbook에는 없다.
|
||||
- **왜 중요한가**: gRPC 운영자가 runbook을 따라 하면 첫 단계에서 막힌다. 클라이언트 쪽 조치(업무 데이터로 확인)는 digest 없이 된다. 이 커밋이 만든 것이 아니다.
|
||||
- **고치는 법**: runbook에 "gRPC는 이 줄이 없다"를 적거나, gRPC interceptor가 5xx carrier를 web과 같은 형식으로 로그에 남긴다.
|
||||
- **가이드 심각도·우선순위**: Low · P3 · 이전부터
|
||||
- **증거**: E1 — interceptor 코드 읽기, runbook 대조.
|
||||
|
||||
#### RR4-03-04 · watchdog 스레드는 한 번 생기면 끝나지 않는다 — 수명이 Javadoc에 없다
|
||||
|
||||
- **위치**: `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/jdk/ReadIdleInputStream.java:36-37`, `:90-101`, `:216-221`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 실행기는 첫 JDK 스트림을 만들 때(holder 클래스 초기화) 생기고, 스레드는 첫 wake를 예약할 때 생긴다. core 스레드 1개에 timeout이 없어 그 클래스 로더가 살아 있는 동안 끝나지 않는다. 모든 JDK 클라이언트가 이 한 스레드를 같이 쓴다.
|
||||
- 데몬이라 JVM 종료는 막지 않는다. 그러나 클래스 로더를 버리는 환경(WAR 재배포, 재시작 클래스 로더)에서는 이 스레드가 옛 로더를 붙잡는다. 스레드 context class loader도 처음 예약한 요청 스레드의 것을 물려받는다.
|
||||
- Javadoc은 "shared by every JDK stream and started with the first"까지만 적는다.
|
||||
- **왜 중요한가**: 템플릿은 실행 jar로 배포하고 DevTools를 쓰지 않는다(grep). 그래서 지금 피해는 없다. 다른 배포 방식을 쓰는 파생 서비스에서만 누수가 생긴다.
|
||||
- **고치는 법**: `scheduler.setKeepAliveTime(…)` + `allowCoreThreadTimeOut(true)`로 스트림이 없을 때 스레드가 끝나게 한다. 또는 Javadoc에 "JVM 수명 동안 한 개, 끝나지 않는다"를 적는다.
|
||||
- **가이드 심각도·우선순위**: Low · P3
|
||||
- **증거**: E1 — 코드 읽기.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- 04 영역에서는 발견이 없다. 붙여 쓴 `-x`·`-p`는 대소문자를 가려 `-P<prop>`와 섞이지 않는다. Gradle 단일 대시 옵션 가운데 `p`·`x`로 시작하는 다른 것이 없다는 것은 Gradle 파서로 전수 확인하지 않았다.
|
||||
- `EnvContractVerifier`의 새 실패(typed prefix 아래 선언 없음)는 파생 서비스가 redis-runtime leaf를 지우면 `verifyEnvKeys`를 멈춘다. 실패 쪽이고 메시지가 고칠 곳을 말하므로 결함으로 보지 않았다.
|
||||
- `StartupRuleRunner`가 모든 프로필에서 비밀 목록을 먼저 만드는 것은 non-static 비밀 목록을 쓰던 파생 서비스의 dev·test 기동도 멈춘다. B-15·표 4번 행에 적혀 있어 의도된 변경으로 봤다. 템플릿의 비밀 목록 bean 둘은 모두 `static` 무인자다(`JpaStartupAutoConfiguration.java:163`, `RedisCapabilityConfig.java:91`).
|
||||
- watchdog이 HTTP/2·TLS에서 `in.close()`를 하다 늦어지면 다른 스트림의 wake도 늦어진다. 측정하지 않았다(2차 리뷰에서도 미판단).
|
||||
- watchdog 스레드가 처음 예약한 요청 스레드의 `InheritableThreadLocal`을 물려받는다. 그 스레드는 닫기만 하므로 영향은 없다고 보고 판단하지 않았다.
|
||||
- scope digest가 이제 tracing span의 예외 메시지(`spanErrorRecorder.recordException`)에도 실린다. HMAC 값이라 문제로 보지 않았다.
|
||||
- `SingleSidedAssociationCondition`이 양쪽 모두 같은 `@JoinTable`을 명시한 쌍을 "두 번 저장"이라고 말할 수 있다. 드문 모양이라 판단하지 않았다.
|
||||
- gRPC ledger IT의 상대 경로 `Path.of("src/main/resources/…")`와 평평한 `Files.list`는 IDE에서 저장소 루트로 돌리면 실패하고 하위 폴더를 못 본다. Gradle lane에서는 맞게 돈다.
|
||||
- 새 transitive 규칙의 실행 시간(README의 5.7초)은 전체 run에서 다시 재지 않았다.
|
||||
- 파생 서비스(tech-log-backend)에 RR4-01-02 모양의 설정이 있는지는 보지 않았다. `@SystemCaller`가 아직 main에 없어 지금은 해당이 없다.
|
||||
- README 12절에 이미 남은 것으로 적힌 항목(`graphql..` fixture 없음, `spotbugsTestFixtures` ReDoS 경고, `failure-retention ≥ replay-ttl` 기동 검사, `-mx` 같은 짧은 플래그 묶음, RR3-04-03 코드 수정)은 다시 판단하지 않았다.
|
||||
|
||||
## 수렴 판단
|
||||
|
||||
이 라운드가 만든 새 결함 가운데 Important 이상은 **없다**.
|
||||
|
||||
- 새 발견 6건(RR4-01-01·02, RR4-02-01, RR4-03-01·02·04)은 모두 Low다. 넷은 이번 수정이 만든 규칙·검사기·테스트·runbook의 경계이고, 실패 쪽으로 틀리거나 비기본 조건(`mixed=true`, 2 vCPU CI, WAR 재배포)이 겹쳐야 한다.
|
||||
- RR4-01-01은 경계에 있다. 같은 leaf 조건에 인터페이스 주입이 겹치면 Medium에 닿는다. 원 발견 RR3-01-01과 같은 기준으로 낮은 쪽에 뒀다.
|
||||
- 이전부터 있던 것 1건(RR4-03-03).
|
||||
- 회귀 0건. 3차 확인 리뷰 Minor 19건 중 18건 닫힘, 1건(RR3-04-03) 결정으로 닫힘.
|
||||
|
||||
11.1절 멈춤 기준대로 다음 수정 라운드는 필요 없다. Minor는 남은 것으로 기록한다.
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? Yes**
|
||||
|
||||
새 Critical·Important가 없고 회귀도 없다. Minor 7건(이전부터 1건 포함)은 기록만 하고, 가장 먼저 볼 것은 RR4-01-01의 문서 정정(못 보는 경로를 바르게 적기)이다.
|
||||
@@ -0,0 +1,193 @@
|
||||
# r8 확인 리뷰 (2026-11-04)
|
||||
|
||||
대상: 커밋 `70fb80bf`(소유자 결정 ①②③ 반영), Base `b76285a5`. 리뷰어 1명이 세 영역을 나눠 직접 봤다(하위 에이전트 없음).
|
||||
발견 ID는 `RR5-<영역>-<순번>`이다. 영역 번호: 01 멱등성(결정 ①), 02 workflow `cd`(결정 ②), 03 설정 검사(결정 ③).
|
||||
|
||||
## 범위
|
||||
|
||||
### 본 pathspec
|
||||
|
||||
| 영역 | pathspec |
|
||||
| --- | --- |
|
||||
| 01 멱등성 | `src/application-core` (idempotency 패키지·CLAUDE.md·README, testFixtures `IdempotencyStoreContract`), `src/adapter/outbound/persistence-jpa` (`.../idempotency/postgresql`, 통합 테스트, README), `src/adapter/outbound/cache-redis` (`IdempotencyScripts`, `RedisIdempotencyStoreAdapter`, 테스트, README), `src/adapter/outbound/redis-runtime/src/testFixtures` (`InMemorySemanticRedisCommands`), `docs/web/http-contract.md` §2, `docs/manual/05-idempotency.md`, `docs/runbooks/idempotency-unavailable.md`, `docs/upgrade/2026-11-maturity-review.md`(B-30·5절 표), `docs/study/postgresql-jpa-walkthrough.ko.md` |
|
||||
| 02 workflow `cd` | `src/build-logic` (`WorkflowGradleInvocations`, `StrictLaneStagesPlugin`, 두 테스트, README), `AGENTS.md`, `CLAUDE.md`, `docs/upgrade/...`(B-36) |
|
||||
| 03 설정 | `src/composition/idempotency` (`IdempotencySettings`, 테스트, README), `docs/registries/env-keys.yaml`, `src/.env.example`, `docs/upgrade/...`(B-24) |
|
||||
|
||||
요구사항은 `docs/reviews/2026-11-03-rereview/README.md` 15절(결정 ①②③과 r8 묶음 결과·남은 것)으로 맞춰 봤다.
|
||||
변경 밖이지만 판정에 필요해 함께 읽은 것: `IdempotencyExecutor` 전체, PG `IdempotencyClaimGateway`의 INSERT, `PublishPosterImageUseCase`(executor 호출 모양), 두 저장소의 `markFailed`·`complete`, cache-redis·persistence-jpa의 lane 정의.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 본 것 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 계획(15절 결정) 대비 구현, 테스트가 진짜 동작을 보는가, 호환성·마이그레이션, Strengths·심각도별 Issues·Assessment, Declined to judge, 읽기 전용, 하위 에이전트 금지 | 결정 ①②③을 코드·계약 테스트·문서와 하나씩 맞췄다. 이 문서 양식이 그 템플릿이다 |
|
||||
| `api-and-interface-design` | 멱등 키 절: 원자적 claim(유일 제약·원자 스크립트), 처리 중 중복에 대한 의도된 응답, 결과는 성공·실패·불명 셋, 보존 기간은 가장 긴 재전송 경로보다 길게. Hyrum's Law(관찰되는 동작 변경), 일관된 오류 의미(값 하나에 뜻 하나) | PG `on conflict` + 행 잠금과 Lua 원자성에서 늦은 완료가 다른 판정과 겹치지 않는지, `inspect`·`renew` 결과 값의 뜻 변화(RR5-01-02), 계약 문서끼리의 안내 일치(RR5-01-01), `failure-retention ≥ replay-ttl` 검사 |
|
||||
| `doubt-driven-development` | 주장(CLAIM)을 적고 반증을 먼저 찾는다. 하위 에이전트를 띄울 수 없어 자기 반대 논증으로 대신했다 — 새 맥락 리뷰가 아니므로 약한 형태다. 교차 모델 검토는 비대화 하위 에이전트 맥락이라 건너뛰었다 | 주장 4개를 반증하려 했다: "다시 실행하는 경로가 없다"(TakenOver를 만드는 곳 전부, 같은 attempt 재사용 경로), "두 저장소가 같은 판정을 한다"(CLAIM·TRANSITION·RENEW·INSPECT 대조), "cd 추적이 새 거짓 통과를 만들지 않는다"(셸 모양 18개 실행), "③이 기존 설정을 깨지 않는다"(저장소 안 설정값 검색) |
|
||||
| `ci-cd-and-automation` | 게이트를 조용히 건너뛰지 못하게, 실패를 숨기는 명령을 실행으로 세지 않게 | `verifyStrictLaneStages`가 실제로는 돌지 않거나 실패를 막지 못하는 명령을 세는 모양(RR5-02-01·02), 실제 workflow에 대한 판정 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
- `git diff --stat b76285a5..70fb80bf`, 영역별 `git diff b76285a5..70fb80bf -- <pathspec>`, `git show 70fb80bf:<file>`.
|
||||
- 셸 모양 판독 실험: HEAD의 `WorkflowGradleInvocations.java`를 scratchpad로 꺼내 `javac`로 따로 컴파일하고, `run: |` 스크립트 18개를 읽혔다. 결과는 RR5-02-01·02 근거에 적었다.
|
||||
- 별도 worktree(`git worktree add --detach <scratchpad>/rr5 70fb80bf`), 공유 잠금(`flock .../heavy.lock`) 아래:
|
||||
- `./gradlew :application-core:test --tests '*InMemoryIdempotencyStoreContractTest' :adapter:outbound:cache-redis:test --tests '*RedisIdempotencyStoreContractTest' --tests '*RedisIdempotencyStoreAdapterTest' :composition:idempotency:test --tests '*IdempotencySettingsTest' --offline` → rc=0. 결과 XML: fake 계약 25개 중 12개 skip, command fake 위 Redis 계약 25개 중 12개 skip(둘 다 시간 케이스 12개 전부), `RedisIdempotencyStoreAdapterTest` 30/30, `IdempotencySettingsTest` 22/22. `-q`로 돌려 결과가 빌드 캐시에서 복원됐는지는 확인하지 않았다.
|
||||
- `./gradlew -p build-logic test --tests '*WorkflowGradleInvocationsTest' --offline` → rc=0, 20/20.
|
||||
- `./gradlew verifyStrictLaneStages --dry-run --offline` → `every strict lane is in an executed stage.`
|
||||
- 끝나고 `git worktree remove --force`.
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 실 PostgreSQL·실 Redis 계약 lane(`jpaPlatformContractTest`, `redisContainerContractTest`)은 다시 돌리지 않았다. Docker가 필요하다. README 15절의 결과(PG 계약 25/25, `redisContainerContractTest` 64/64)와 Redis lane의 `rejectSkipped = true`(`src/adapter/outbound/cache-redis/build.gradle:92`)를 근거로 삼았다.
|
||||
- 프론트 짝 문서(`clean-architecture-frontend-template` `docs/architecture/backend-api-and-server-state-contract.md`)는 다른 repo라 보지 않았다.
|
||||
- optional-platforms 빌드의 `verifyStrictLaneStages`는 돌리지 않았다(README 15.1 통과 기록만 봤다).
|
||||
|
||||
## Strengths
|
||||
|
||||
- 결정 ①을 두 저장소가 같은 모양으로 구현했다. PG는 lease 지난 `EXECUTING`에 아무 문장도 실행하지 않고 `RecoveryRequired`만 돌려준다(`PostgreSqlIdempotencyStore.java:153-159`). Redis CLAIM도 `rev`·TTL을 건드리지 않고 답한다(`IdempotencyScripts.java:92-97`). 지운 `abandonExpiredExecution` SQL이 갖던 "갱신 실패 → indeterminate" 분기도 함께 사라져 실패 경로가 하나 줄었다.
|
||||
- 넘겨받기 경로가 둘(만료된 `CLAIMED`, `FAILED_RETRYABLE`)로만 남았다. PG `resetClaim` 호출 3곳(`PostgreSqlIdempotencyStore.java:131-133, 147-152`)과 Redis `TAKEN_OVER` 1곳(`IdempotencyScripts.java:98-107`) 어디에도 `EXECUTING`이 없다.
|
||||
- `renew`는 두 저장소가 같은 조건으로 거절한다. PG는 원래 `processing_lease_until > clock_timestamp()`가 있었고(`IdempotencyTransitionGateway.java:74`), Redis RENEW가 같은 검사를 서버 `TIME`으로 더했다(`IdempotencyScripts.java:215-220`).
|
||||
- 공유 계약에 시간 케이스 6개를 더해 두 실 저장소에서 같은 판정을 강제한다(`IdempotencyStoreContract.java:493-617`). 옛 "늦은 complete 거절" 케이스를 지우지 않고 반대로 바꿔(`:516-532`) 이전 결정과의 차이가 테스트 이력에 남는다.
|
||||
- command fake의 Lua 복사본 세 곳을 같은 커밋에서 맞췄다(`InMemorySemanticRedisCommands.java:227-232, 324-327, 378-386`). adapter 테스트가 늦은 complete·재생, inspect, renew를 fake 시계로 본다(`RedisIdempotencyStoreAdapterTest.java:356-425`).
|
||||
- runbook이 "lease 지난 `EXECUTING`은 지우지 않는다"를 이유(늦은 결과가 `ABSENT`를 만나 사라지고 같은 키가 다시 실행된다)와 함께 적고(`docs/runbooks/idempotency-unavailable.md:99-102`), 옛 버전이 남긴 `EXPIRED_EXECUTION` 행을 읽는 법도 남겼다(`:75-76`).
|
||||
- 결정 ③의 메시지가 두 키와 두 값을 함께 보여 준다(`IdempotencySettings.java:91-101`). 경계값(같으면 통과, 1분 짧으면 거부)을 테스트가 본다(`IdempotencySettingsTest.java:204-249`).
|
||||
- 결정 ②의 판독이 보수적이다. `cd`는 "정확히 두 단어 + 따옴표 벗긴 상대 경로"일 때만 따라간다(`WorkflowGradleInvocations.java:266-271`). 따옴표 안 `;`, 백틱, `builtin cd`, `cd --` 같은 모양은 모두 "읽지 않음"으로 떨어진다. 실험에서 확인했다.
|
||||
- 세지 않은 명령을 이유와 함께 실패 메시지에 싣는다(`StrictLaneStagesPlugin.java:154, 194-213`). 파생 서비스가 왜 실패하는지 메시지만으로 안다.
|
||||
|
||||
## 발견 재확인 표
|
||||
|
||||
| ID | 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| 결정 ① lease 지난 `EXECUTING` → 기록 그대로 `RecoveryRequired` | 닫힘 | `PostgreSqlIdempotencyStore.java:153-159`, `IdempotencyScripts.java:92-97`, `InMemorySemanticRedisCommands.java:227-232`, 계약 `IdempotencyStoreContract.java:493-514` |
|
||||
| 결정 ① 주인의 늦은 `complete`·`markFailed` 기록, 다음 claim 재생 | 닫힘 | PG `COMPLETE_SQL`·`FAIL_SQL`은 lease를 보지 않는다(`IdempotencyTransitionGateway.java:77-120`), Redis TRANSITION도(`IdempotencyScripts.java:112-158`). 계약 `:516-577` |
|
||||
| 결정 ① 주인 아닌 호출 거절 | 닫힘 | 소유자 튜플 비교가 그대로다(`PostgreSqlIdempotencyStore.java:479-505`, `IdempotencyScripts.java:122-141`). `EXECUTING`은 넘겨받지 않으므로 다른 주인이 생기지 않는다 |
|
||||
| 결정 ① `renew` 거절 | 닫힘 (Minor RR5-01-02) | `IdempotencyScripts.java:215-220`, `IdempotencyTransitionGateway.java:74`, 계약 `:600-617` |
|
||||
| 결정 ① 남의 lease 지난 실행 `inspect` → `ABANDONED` | 닫힘 (Minor RR5-01-02) | `PostgreSqlIdempotencyStore.java:421-426`, `IdempotencyScripts.java:292-300`, `RedisIdempotencyStoreAdapter.java:394-397`, 계약 `:580-598` |
|
||||
| 결정 ① 문서(http-contract·manual·runbook·upgrade) | 부분 | 동작 설명은 맞다. 클라이언트 안내가 세 문서에서 갈라졌다(RR5-01-01) |
|
||||
| 결정 ② 같은 셸의 `cd <상대 경로>` 추적 | 닫힘 (Minor RR5-02-01) | `WorkflowGradleInvocations.java:212-308`, 테스트 `WorkflowGradleInvocationsTest`(20/20), 실제 workflow 판정 통과 |
|
||||
| 결정 ③ `failure-retention < replay-ttl` 기동 실패 | 닫힘 (Minor RR5-03-01) | `IdempotencySettings.java:87-101`, `IdempotencySettingsTest.java:204-249`, `env-keys.yaml:1683-1698`, B-24 |
|
||||
| README 15절 남음: CLAIMED → 시작에서 PG는 lease를 보고 Redis는 보지 않는다 | 그대로(이전부터, 결정 범위 밖) | PG `START_SQL`(`IdempotencyTransitionGateway.java:39`) vs Redis TRANSITION(lease 검사 없음). 결정 ① 뒤로는 Redis 쪽이 오히려 결과를 남긴다. 중복 실행은 없다 |
|
||||
| README 15절 남음: `|| true`·`| tee`·`if` 안 gradlew를 실행으로 센다 | 그대로(이전부터) | 같은 종류의 모양 둘을 더 찾았다(RR5-02-02) |
|
||||
|
||||
회귀로 판정한 발견은 없다.
|
||||
|
||||
## Issues
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Important (Should Fix)
|
||||
|
||||
없음.
|
||||
|
||||
### Minor (Nice to Have)
|
||||
|
||||
#### RR5-01-01 · `IDEMPOTENCY_RECOVERY_REQUIRED` 클라이언트 안내가 세 문서에서 갈라졌다
|
||||
|
||||
- 위치: `docs/web/http-contract.md:113`, `docs/manual/05-idempotency.md:54`, `docs/runbooks/idempotency-unavailable.md:97`
|
||||
- 무엇이 틀렸나: 이 커밋이 http-contract 표 행만 바꿨다. 세 문서가 이제 서로 다른 말을 한다.
|
||||
- http-contract 표: "같은 키로 다시 보내도 서버는 작업을 다시 돌리지 않는다 … 아니면 다시 500이다. 새 키로 보내지 않는다."
|
||||
- 같은 절 아래 문단(`http-contract.md:127`): "효과 없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다." 표의 "다시 돌리지 않는다 / 아니면 다시 500"과 어긋난다.
|
||||
- manual 표(`05-idempotency.md:54`): "재전송·재실행 모두 위험." 같은 행의 옛 문구가 남았다. 그런데 manual은 "짝 프론트 분류기도 이 표를 따른다"고 적는다(`:69`).
|
||||
- runbook(`idempotency-unavailable.md:97`): "효과가 없으면 클라이언트는 새 키로 다시 보낸다." http-contract의 "새 키로 보내지 않는다"와 정면으로 다르다.
|
||||
- 왜 중요한가: 결정 ①로 충돌한 실행(crash)의 기록은 `EXECUTING`으로 lease + `replay-ttl`(기본 약 24h) 동안 남는다. runbook은 이 기록을 지우지 말라고 한다(`:99-102`). 그래서 효과가 없다고 확인된 뒤 남는 길은 새 키뿐이다. 그런데 http-contract만 읽은 클라이언트는 새 키를 막는다. 그 사용자는 기록이 사라질 때까지 진행하지 못한다. 중복 실행이나 데이터 손상은 생기지 않는다. 드문 경우의 진행 막힘이라 낮은 쪽(Minor)으로 분류했다.
|
||||
- 고치는 법: 표 행을 "자동 재시도하지 않는다. 같은 키 재전송은 안전하다(재생·500·효과 없던 실패면 실행). 업무 데이터로 효과가 없다고 확인되면 운영 절차에 따라 새 키로 다시 보낸다"처럼 runbook과 맞춘다. manual 표 행을 같은 문구로 바꾼다.
|
||||
- 가이드 심각도 Low · P2 · 증거 E1(문서 대조)
|
||||
|
||||
#### RR5-01-02 · `renew`·`inspect` 결과 값의 뜻이 하나씩 늘었다
|
||||
|
||||
- 위치: `IdempotencyScripts.java:217-220`, `PostgreSqlIdempotencyStore.java:236-239`, `IdempotencyInspectionOutcome.java:11-17`
|
||||
- 무엇이 틀렸나:
|
||||
- lease가 끝난 주인의 `renew`가 `NOT_OWNER`를 받는다. 그 주인은 여전히 주인이다. 같은 handle로 `complete`하면 `COMPLETED`가 난다. `NOT_OWNER`는 다른 곳에서 "기록이 다른 주인에게 넘어갔다"는 뜻이다(PG 주석 `PostgreSqlIdempotencyStore.java:445-447`이 "값 하나에 뜻 하나"를 지킨다고 적는다).
|
||||
- `inspect`의 `ABANDONED`가 "끝난 포기"와 "남의 실행이 lease를 넘김(아직 `COMPLETED`로 바뀔 수 있음)" 둘을 뜻한다. javadoc에는 적혀 있다.
|
||||
- 왜 중요한가: 지금 `renew`·`inspect`를 부르는 곳은 executor뿐이고 executor는 `renew`를 부르지 않는다. 그래서 지금 틀린 동작은 없다. 나중에 lease를 늘리는 executor가 `NOT_OWNER`를 "넘겨받혔다"로 읽고 작업을 멈추거나 `complete`를 건너뛰면, 결정 ①이 지키려던 늦은 결과가 사라진다. 숨은 위험이다.
|
||||
- 고치는 법: `IdempotencyRenewOutcome`에 `LEASE_EXPIRED`(owner 없음)를 더하고 두 저장소와 계약이 그 값을 쓰게 한다. 아니면 `IdempotencyStorePort.renew` javadoc에 "lease가 끝났으면 `NOT_OWNER`지만 `complete`·`markFailed`는 여전히 받는다"를 적는다. `ABANDONED`는 javadoc을 그대로 두거나 `RECOVERY_REQUIRED_EXPIRED_EXECUTION` 같은 값을 나눈다.
|
||||
- 가이드 심각도 Low · P3 · 증거 E2(코드 읽기, 계약 `:600-617`이 `isNotEqualTo(RENEWED)`만 본다)
|
||||
|
||||
#### RR5-01-03 · 포트 javadoc의 "주인의 마지막 보고를 기록이 갖는다"가 동작과 다르다
|
||||
|
||||
- 위치: `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyStorePort.java:15-16`
|
||||
- 무엇이 틀렸나: "the holder's last report is the one the record keeps"라고 적었다. 실제로 기록은 첫 종료 보고를 갖는다. `COMPLETED` 뒤의 `markFailed`는 PG `NOT_IN_PROGRESS`(`PostgreSqlIdempotencyStore.java:501-503`), Redis `NOT_OWNER`나 `NOT_IN_PROGRESS`로 거절된다.
|
||||
- 왜 중요한가: 포트 구현자가 이 문장대로 "마지막 보고로 덮어쓰기"를 만들면 완료된 결과가 실패로 바뀐다. 계약에 그 케이스가 없어 막지 못한다.
|
||||
- 고치는 법: "the holder's final report — its completion or its failure, whichever comes first — is recorded"로 고친다.
|
||||
- 가이드 심각도 Low · P3 · 증거 E1
|
||||
|
||||
#### RR5-01-04 · 늦은 실패 경로를 계약이 끝까지 보지 않는다
|
||||
|
||||
- 위치: `IdempotencyStoreContract.java:556-578`, `RedisIdempotencyStoreAdapterTest.java:356-425`
|
||||
- 무엇이 틀렸나:
|
||||
- 늦은 재시도 가능 실패 케이스는 `MARKED_RETRYABLE`만 확인한다. 문서가 약속한 "다음 같은 키 요청이 다시 실행한다"(`http-contract.md:127`)는 시간 케이스로 확인하지 않는다.
|
||||
- 늦은 `EFFECT_UNKNOWN_ABANDONED` 보고 케이스가 없다.
|
||||
- command fake 쪽은 늦은 `complete`·`inspect`·`renew`만 본다. 늦은 `markFailed`는 fake 복사본으로 한 번도 지나가지 않는다.
|
||||
- fake와 command fake 위 계약은 시간 케이스 12개를 모두 skip한다(실행 결과). 시간 케이스는 실 PG·실 Redis lane에서만 돈다.
|
||||
- 왜 중요한가: 지금 코드는 맞다(PG `FAIL_SQL`이 lease를 now로 당기고 `FAILED_RETRYABLE`은 `resetClaim`으로 간다. Redis CLAIM은 `FAILED_RETRYABLE`을 넘겨받는다). 다만 이 경로가 바뀌어도 잡을 테스트가 없다.
|
||||
- 고치는 법: `:556` 케이스 끝에 다음 claim이 `TakenOverClaimed`인지 확인을 더한다. 늦은 `EFFECT_UNKNOWN_ABANDONED` → 다음 claim `RecoveryRequired` 케이스를 더한다. adapter 테스트에 늦은 `markFailed` 한 건을 더한다.
|
||||
- 가이드 심각도 Low · P3 · 증거 E3(테스트 실행 결과의 skip 목록)
|
||||
|
||||
#### RR5-01-05 · (이전부터) PostgreSQL에서는 결정 ①이 말하는 상황이 기본 사용 모양에서 생기지 않는다
|
||||
|
||||
- 위치: `IdempotencyClaimGateway.java:59`, `PublishPosterImageUseCase.java:108-117`, `persistence-jpa.yml:181`, `docs/web/http-contract.md:123-129`
|
||||
- 무엇이 틀렸나: PG 저장소는 호출자의 쓰기 트랜잭션 안에서만 돈다. 샘플처럼 `transactions.inWrite(() -> executor.execute(...))`로 부르면 claim·실행·complete가 한 트랜잭션이다. 두 번째 요청의 `insert … on conflict do nothing`은 첫 요청의 커밋 전 행을 기다린다. 그래서 두 번째 요청은 "lease 지난 `EXECUTING`"을 보지 못하고 잠금에서 기다린다. 또 쓰기 트랜잭션 제한(30s, B-21)이 기본 lease(30s)와 같아서 30s를 넘는 요청은 취소되고 claim 행까지 롤백된다. 새 문단 "첫 시도가 lease보다 오래 걸려도 그 결과는 기록된다 … 두 저장소 모두 500으로 답한다"는 PG 기본 사용에서 맞지 않는다.
|
||||
- 왜 중요한가: 이 커밋이 만든 동작 문제는 아니다. 옛 문서도 PG에 대해 같은 정도로 틀렸다. 다만 이 커밋이 새로 쓴 약속 문장이 PG 운영자에게 "30s 넘는 요청도 결과가 남는다"고 읽힌다. 실제로는 요청이 실패하고 기록이 사라져, 같은 키 재전송이 트랜잭션 밖 효과를 다시 일으킬 수 있다.
|
||||
- 고치는 법: http-contract §2 문단에 "PostgreSQL 저장소를 한 쓰기 트랜잭션 안에서 쓰면 같은 키 요청은 첫 요청이 끝날 때까지 기다리고, 쓰기 트랜잭션 제한(기본 30s)을 넘는 요청은 기록과 함께 롤백된다"를 더한다.
|
||||
- 가이드 심각도 Low · P3 · 증거 E2(SQL·호출 모양·설정값 읽기, 실행 재현은 안 했다)
|
||||
|
||||
#### RR5-02-01 · 셸이 그 자리에서 실행하지 않는 `cd` 줄도 따라간다
|
||||
|
||||
- 위치: `WorkflowGradleInvocations.java:31-45`(클래스 주석 "certain to have run"), `:212-308`, `:732-765`
|
||||
- 무엇이 틀렸나: 판독기는 줄 단위로 목록을 나눈다. 셸 문법의 일부를 모른다. 아래 모양에서 셸은 저장소 루트에 있는데 판독기는 `src`라고 읽고 `:ci`를 실행으로 센다. 실험 결과 모두 `countsSrcCi=true, reason=null`이었다.
|
||||
- heredoc 본문의 `cd src` 줄 (`cat > x.sh <<'EOF'` / `cd src` / `EOF` / `./gradlew ci`)
|
||||
- 정의만 하고 부르지 않은 함수 본문 (`enter() {` / ` cd src` / `}`). 여는 `{`가 첫 단어가 아니라 깊이를 세지 않는다(`:231-252`)
|
||||
- 여러 줄 따옴표 문자열 안의 `cd src` 줄
|
||||
- 이스케이프한 `\;` 뒤의 `cd src && ./gradlew ci`
|
||||
- 왜 중요한가: 이 저장소에는 루트에 `gradlew`가 없다. 그래서 위 모양의 `./gradlew ci`는 실제로 실패하고 workflow가 빨갛게 된다. 조용한 거짓 통과는 아니다. 조용한 거짓 통과가 되려면 다른 빌드 디렉터리(예: `src/optional-platforms`)에서 `../gradlew ci`가 성공하는 억지 모양이 필요하다. 그래서 Minor다. 다만 클래스 주석의 "확실히 실행된 cd만 따라간다"는 사실보다 강하다.
|
||||
- 고치는 법: `<<`가 있는 줄 뒤, `name() {`·`function` 정의, 짝이 안 맞는 따옴표가 있는 줄 뒤의 `cd`는 "읽지 않음"으로 둔다. 아니면 주석을 "줄 단위로 읽으며 heredoc·함수 본문·여러 줄 문자열은 구분하지 않는다"로 낮춘다.
|
||||
- 가이드 심각도 Low · P3 · 증거 E3(scratchpad 판독 실험)
|
||||
|
||||
#### RR5-02-02 · (이전부터) 실패를 막지 못하는 모양 둘이 README 15절 "남음" 목록에 없다
|
||||
|
||||
- 위치: `WorkflowGradleInvocations.java:58`(구분자에 `&` 없음), `:803-830`
|
||||
- 무엇이 틀렸나: 실험 결과 둘 다 `countsSrcCi=true`였다.
|
||||
- `cd src; ./gradlew ci &`: 백그라운드 실행이라 step이 결과를 기다리지 않는다. `&`는 task 이름으로 읽힌다(`tasks=[ci, &]`).
|
||||
- `false && cd src && ./gradlew ci` 다음 줄 `echo done`: 앞 명령이 실패하면 gradlew는 돌지 않는다. `bash -e`는 `&&` 목록 중간 실패로 끝나지 않는다. 그래서 step이 통과한다. `working-directory: src`와 `A && ./gradlew ci`에도 이전부터 있던 모양이다.
|
||||
- 왜 중요한가: 둘 다 조용한 거짓 통과다. README 15절은 `|| true`·`| tee`·`if`만 적어서 남은 범위가 실제보다 좁게 읽힌다.
|
||||
- 고치는 법: README 15절 "남음"에 두 모양을 더한다. 고칠 때는 `&`를 구분자로 읽고 그 앞 명령을 세지 않는다. `&&` 목록 중 마지막이 아닌 gradlew와 마지막이 아닌 목록의 gradlew는 세지 않는다.
|
||||
- 가이드 심각도 Low · P2 · 증거 E3
|
||||
|
||||
#### RR5-02-03 · 실패 메시지가 다른 디렉터리로 읽힌 명령은 보여 주지 않는다
|
||||
|
||||
- 위치: `StrictLaneStagesPlugin.java:194-213`
|
||||
- 무엇이 틀렸나: `notCounted`는 `uncountedReason`이 있는 명령만 싣는다. `cd scr && ./gradlew ci`(오타)처럼 따라간 `cd`가 다른 빌드로 이끈 명령은 이유가 `null`이라 빠진다. 메시지는 "a command started in another directory"라고만 한다.
|
||||
- 왜 중요한가: 결정 ②의 목적이 "파생 서비스가 왜 실패하는지 알게"였다. 가장 흔한 실수(경로 오타, `working-directory`와 `cd`를 둘 다 써서 `src/src`)가 이름 없이 남는다.
|
||||
- 고치는 법: 단계를 요청했지만 `buildDirectory()`가 다른 명령도 "다른 빌드 `<dir>`에서 시작한다"로 함께 싣는다.
|
||||
- 가이드 심각도 Low · P3 · 증거 E2
|
||||
|
||||
#### RR5-03-01 · `APP_IDEMPOTENCY_TTL` 쪽 안내가 새 상한을 말하지 않는다
|
||||
|
||||
- 위치: `docs/registries/env-keys.yaml:1602-1616`, `src/composition/idempotency/src/main/resources/config/module-defaults/idempotency.yml:14-17`, `src/composition/idempotency/README.md:48`(조정 표의 `APP_IDEMPOTENCY_TTL` 칸)
|
||||
- 무엇이 틀렸나: 결정 ③으로 `replay-ttl`은 이제 `failure-retention`(기본 24h)보다 길 수 없다. 그런데 `APP_IDEMPOTENCY_TTL` 행의 주석과 `validation`(`..._le_72h_ge_processing_lease`)은 72h 상한과 lease 하한만 말한다. module-defaults 주석도 lease 검사만 적는다. 새 검사는 `FAILURE_RETENTION` 행에만 있다.
|
||||
- 왜 중요한가: `APP_IDEMPOTENCY_TTL`만 48h·72h로 올리는 운영자는 TTL 행만 보고 기동 실패를 만난다. 메시지가 두 키와 값을 보여 주고 B-24가 적고 있어 바로 고칠 수 있다. 그래서 Minor다.
|
||||
- 고치는 법: TTL 행 주석에 "and not longer than APP_IDEMPOTENCY_FAILURE_RETENTION"을 더하고 `validation`을 `..._le_failure_retention`으로 맞춘다. module-defaults 주석과 composition README 조정 표에도 한 줄씩 더한다.
|
||||
- 가이드 심각도 Low · P3 · 증거 E1
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- 프론트 짝 문서 갱신 여부: 다른 repo라 보지 않았다.
|
||||
- 배포 중 옛 버전과 새 버전이 한 저장소를 함께 쓰는 동안: 옛 인스턴스의 claim은 여전히 기록을 `ABANDONED`로 바꿔 새 인스턴스의 늦은 완료를 거절한다. 중복 실행은 없고 옛 동작 그대로라 판단하지 않았다.
|
||||
- 같은 claim attempt를 다시 쓰는 호출: `ReplayedAcquire` 뒤 Redis는 `ALREADY_STARTED`로 작업을 다시 돌리고 PG는 digest의 revision 차이로 `OPERATION_CONFLICT`를 낸다. 이전부터의 차이이고, 지금 호출자는 모두 요청마다 새 attempt를 만든다(`PublishPosterImageUseCase.java:106`). 범위 밖이다.
|
||||
- 비동기 웹 요청 timeout(B-32)이 lease보다 짧으면 "첫 요청은 자기 응답을 정상으로 받는다"가 맞지 않는다: 웹 계층 설정 문제라 범위 밖이다.
|
||||
- PG `jpaPlatformContractTest` lane에 `rejectSkipped`가 없다: PG 계약은 `elapse`를 구현해 시간 케이스가 skip되지 않는다. 이전부터의 lane 설정이다.
|
||||
- 결정 ②의 구현 방식(손으로 짠 판독기 vs 셸 파서 사용, 또는 `working-directory`만 허용) 사이의 선택 기록: 결정 자체는 소유자가 내렸고, 구현 방식 선택 이유가 클래스 주석에 일부만 있다. 결정을 뒤집는 문제가 아니라 판단하지 않았다.
|
||||
|
||||
## 수렴 판단
|
||||
|
||||
세 영역 모두 이 라운드가 만든 새 Important 이상 결함은 없다. 결정 ①②③은 코드·계약 테스트·운영 문서에 결정대로 들어갔다. 회귀로 판정한 발견도 없다.
|
||||
이 커밋이 만든 것은 Minor 7건(RR5-01-01~04, RR5-02-01·03, RR5-03-01)이다. 이전부터 있던 것이 2건(RR5-01-05, RR5-02-02)이다. 다음 수정 라운드는 필요하지 않다. Minor는 기록만 한다.
|
||||
|
||||
건수: Critical 0 · Important 0 · Minor 9(이 커밋 7: RR5-01-01·02·03·04, RR5-02-01·03, RR5-03-01 / 이전부터 2: RR5-01-05, RR5-02-02).
|
||||
|
||||
## Assessment
|
||||
|
||||
**Ready to merge? Yes**
|
||||
|
||||
결정 ①②③이 두 저장소·공유 계약·문서에 같은 판정으로 들어갔고, 새 넘겨받기 경로나 새 조용한 거짓 통과는 찾지 못했다. 남은 것은 문서 사이의 안내 차이와 테스트·판독기의 작은 틈이다.
|
||||
@@ -0,0 +1,218 @@
|
||||
# 01 core·inbound r9 리뷰 (2026-11-05)
|
||||
|
||||
> 대상: `c508b1ba..45d2a478`의 r9-a 묶음. RR4-01-01·02(`@SystemCaller` 규칙), `graphql..` fixture, 원래 리뷰 16.3절
|
||||
> (템플릿 패키지 목록 두 벌), RR4-03-03(전송별 실패 로그).
|
||||
|
||||
## 범위
|
||||
|
||||
### pathspec
|
||||
|
||||
```
|
||||
src/application-core src/shared-contract src/adapter/inbound src/grpc src/composition/service-runtime src/app-bootstrap
|
||||
docs/manual/07-authorization.md docs/runbooks/idempotency-unavailable.md docs/upgrade/2026-11-maturity-review.md
|
||||
```
|
||||
|
||||
`git diff --stat c508b1ba..45d2a478 -- <pathspec>`: 57개 파일, +1956 −187. 새 파일(`ServerFailureLog`, `StompHandlerFailureLog`,
|
||||
`TemplatePackageOwnershipDocumentTest`, fixture 13개)은 HEAD 전체를 읽었다. 바뀐 클래스는 diff와 함께 주변 코드
|
||||
(`GrpcServerRunner` 인터셉터 순서, `WebSocketCorrelationInterceptor`, `GraphQlExceptionResolver`, `GlobalExceptionHandler`
|
||||
전체 분기)를 읽었다.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 기준 | 본 것 |
|
||||
|---|---|---|
|
||||
| `superpowers:requesting-code-review` | 주장(README 16절 r9-a)과 구현이 맞는가, 테스트가 이름대로의 동작을 보는가, 심각도 보정, Declined to judge, 읽기 전용(별도 worktree). 하위 에이전트는 띄우지 않고 diff를 여러 번에 나눠 직접 봤다 | 항목마다 닫힘 여부, 새 테스트의 이름과 준비 상태가 맞는지(RR6-01-04·08), 결함마다 실행 증거 |
|
||||
| `clean-architecture` | Dependency Rule, "Main(조립 설정)은 바깥의 plugin", Humble Object(경계 코드는 얇게) | 조립 설정을 사용자 전송에서 뺀 판단이 "설정은 요청을 받지 않는다"는 가정에 기대는데, Spring 함수형 endpoint는 설정 클래스 안에 요청 처리 코드를 둔다(RR6-01-01). 템플릿 패키지 목록의 정본과 복사본 |
|
||||
| `security-and-hardening` | 권한 검사는 모든 요청 경로에서, 민감 정보는 로그에 남기지 않는다("Never log sensitive data"), 오류 상세는 서버 로그로만 | 권한 없는 쓰기로 가는 우회 경로(RR6-01-01). 전송별 로그가 SQL·입력값을 싣는지(RR6-01-05·06). 4xx를 사고로 남기는지 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
모든 실행은 `git worktree add --detach <scratchpad>/rr6-01 45d2a478`에서 했다. Gradle은 공유 `heavy.lock`으로 감쌌다.
|
||||
탐침 코드(fixture·테스트)와 결과 파일은 공유 노트 폴더 `rr6-01-probes/`에 그대로 두었다. 고칠 때 fixture로 옮겨 쓸 수 있다.
|
||||
|
||||
| 명령 | 결과 | 직전 부하(1분) |
|
||||
|---|---|---|
|
||||
| `./gradlew :app-bootstrap:architectureTest --tests …Rr6ProbeTest :app-bootstrap:documentContractTest --tests …Rr6TablePairProbeTest :adapter:inbound:grpc:test --tests …Rr6GrpcProbeTest :adapter:inbound:websocket:test --tests …Rr6StompProbeTest --continue` | 표 대조·gRPC·STOMP 탐침 실행됨. architectureTest 탐침은 내 코드의 Error Prone 경고로 컴파일 실패 | 4.72 |
|
||||
| `./gradlew :app-bootstrap:architectureTest --tests …Rr6ProbeTest` | rc=0. 탐침 A1~A7 결과는 결함마다 | 4.94 |
|
||||
| `./gradlew :app-bootstrap:architectureTest --tests …Rr6AllRulesProbeTest` | 첫 실행은 내 탐침이 빈 규칙의 AssertionError를 안 잡아 실패. 고친 뒤 rc=0: 정적 `@ArchTest` 규칙 89개를 함수형 endpoint 설정 두 개에 돌려 위반 0(7개는 대상 클래스 없음) | 4.26 / 2.74 |
|
||||
| `./gradlew :app-bootstrap:architectureTest --tests …Rr6SharedProbeTest` | rc=0. `dev.caskeleton.shared.rr6bogus` 클래스에 `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES` 위반 없음 | 2.39 |
|
||||
|
||||
탐침의 모양:
|
||||
|
||||
- A1·A2: `@Configuration`(사용자 전송 패키지 밖)이 `RouterFunction` 람다 / graphql-java `DataFetcher` 람다 안에서 `@SystemCaller` 작업을 부른다. 새 규칙과 `c508b1ba` 판정식(설정 제외 없음)을 같은 클래스에 돌렸다. A1c: 같은 route를 `@Component`에 두었다(통제군).
|
||||
- A3·A7: `@SystemCaller` 안의 중첩 record·enum·예외, record로 쓴 `@SystemCaller`.
|
||||
- A4: production 클래스 3,415개에서 사용자 전송 570개가 `MessageHandler`에 닿는지.
|
||||
- A5: RR4-01-02 모양에서 익명 `WebMvcConfigurer`가 설정의 필드를 읽는다.
|
||||
- A6: 프로젝트 추상 클래스가 `Runnable`을 구현하고 `@SystemCaller`가 그것을 상속한다.
|
||||
- 표 대조 C0~C5: `TemplatePackageOwnershipDocumentTest`의 `root`를 임시 트리로 바꿔 표만 늘리기, 표에서 빼기(클래스에만 남김), 소유 leaf 바꾸기, 패키지 디렉터리 없애기, domain 표만 늘리기.
|
||||
- gRPC: 실제 Netty 서버(127.0.0.1, 포트 0)에 `GrpcExceptionHandlingInterceptor`를 걸고 실제 클라이언트로 불렀다.
|
||||
- STOMP: `StompHandlerFailureLogTest`와 같은 실제 `WebSocketAnnotationMethodMessageHandler`로 `@MessageMapping`이 `IllegalArgumentException`을 던지게 했다.
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 멱등성 저장소(store·Lua)와 그 계약 테스트 변경은 02 영역이라 판단하지 않았다. application-core의 executor·enum Javadoc 변경은 읽기만 했다.
|
||||
- `src/grpc/grpc-operation-ledger-jpa` 변경(r9-c)은 03 영역이라 보지 않았다.
|
||||
- r9 게이트(`ci`, `mainCheck` 등)는 다시 돌리지 않았다. 탐침은 `--tests`로 좁힌 실행뿐이다.
|
||||
|
||||
## 항목 재확인
|
||||
|
||||
| ID | 판정 | 근거 |
|
||||
|---|---|---|
|
||||
| RR4-01-01 (인터페이스·`Runnable` 주입을 못 봄, 문서가 반대로 적음) | 닫힘 | 대상 술어 `ApplicationBoundaryArchitectureTest.java:555-566`, 새 규칙 `:664-707`, fixture `SystemJobInterfaceInvokingControllerFixture`·`RunnableSystemJobFixture`·`IndirectlyRunnableSystemJobFixture`. 탐침 A6(상위 추상 클래스 경유 `Runnable`)도 잡힌다. 매뉴얼 07 `:118-131`이 못 보는 길(이름 조회, 설정이 넘기는 함수)을 바르게 적는다. 탐침 A4: production 사용자 전송은 `MessageHandler`에 닿지 않아 정석 handler 모양은 거짓 양성이 없다. 새 규칙의 거짓 양성은 RR6-01-03 |
|
||||
| RR4-01-02 (웹 bean을 함께 만드는 설정의 거짓 양성) | 부분 | 두 모양(`WebMvcConfigurer`, controller bean)은 허용 fixture로 통과한다. 익명 configurer가 설정의 상태를 쓰면 아직 걸린다(RR6-01-02). 고친 방법(설정 통째로 제외)이 새 구멍을 냈다(RR6-01-01) |
|
||||
| RR3-01-01 (사용자 전송 → `@SystemCaller` 금지, r6에서 닫힘) | 회귀 | 설정 안의 함수형 endpoint가 `@SystemCaller`를 불러도 더는 잡히지 않는다. `c508b1ba` 판정식은 잡았다(RR6-01-01) |
|
||||
| `graphql..` fixture | 닫힘 | `GraphQlJavaSystemCallerFixture`(graphql 타입 하나만 씀), `ArchitectureViolationFixtureTest.aGraphQlJavaDataFetcherMarkedAsASystemCallerIsCaught`. `app-bootstrap/build.gradle:284` compileOnly, lockfile은 `architectureTestCompileClasspath` 표시만 늘었다 |
|
||||
| 원래 리뷰 16.3 (템플릿 패키지 목록 두 벌) | 닫힘 | `TemplatePackageOwnershipDocumentTest`. 탐침 C1~C5가 표만·클래스만·소유 leaf·디렉터리 누락·domain 표를 모두 실패시켰고 C0은 통과했다. 목록에 없는 새 템플릿 패키지는 못 잡는다는 한계는 `src/application-core/CLAUDE.md:169-171`에 적혀 있다 |
|
||||
| RR4-03-03 (gRPC가 회복 필요 실패를 로그에 안 남김) | 닫힘 | carrier 분기 `GrpcExceptionHandlingInterceptor.java:125-130`, 테스트 `aServerSideCarrierIsLoggedAtError…`. runbook `:50-56`에 전송별 상관 정보. gRPC MDC 주장은 인터셉터 순서(`GrpcServerRunner.java:117-133`, correlation이 exception 바깥)로 맞다 |
|
||||
| r9-a가 새로 고친 것: gRPC `INTERNAL_ERROR` 무기록 | 부분 | 기록은 생겼다. 그러나 "클라이언트 취소" 판정이 틀리고(RR6-01-04), raw status 설명이 던진 경로로 로그에 남는다(RR6-01-05) |
|
||||
| r9-a가 새로 고친 것: STOMP가 persistence SQL 원인을 로그에 씀 | 닫힘 | `StompHandlerFailureLog.java:31-35`, 실제 method handler 테스트. 다만 IAE를 ERROR로 남긴다(RR6-01-06) |
|
||||
| web 로그 리팩터링 | 닫힘 | `GlobalExceptionHandler.java:171-183`. persistence(분류만, span 정리)·dependency·5xx·4xx 네 갈래가 전과 같다(E1, 분기 대조) |
|
||||
|
||||
## 결함
|
||||
|
||||
### RR6-01-01 · Important · 설정을 사용자 전송에서 통째로 빼서, 설정 안의 함수형 endpoint가 `@SystemCaller`를 불러도 잡히지 않는다 (회귀)
|
||||
|
||||
- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:516-519`(설정 제외),
|
||||
`:497-505`(Javadoc "Leaving it out opens nothing"), `docs/manual/07-authorization.md:105`, `:118-131`(「규칙이 못 보는 길」에 없음),
|
||||
`docs/upgrade/2026-11-maturity-review.md` B-16.
|
||||
- **무엇이 틀렸나**:
|
||||
- r9는 `@Configuration`·`@AutoConfiguration` 클래스를 사용자 전송으로 세지 않는다. 근거는 "설정은 조립 루트지 요청이 들어오는 곳이 아니다"이다.
|
||||
- Spring MVC 함수형 endpoint(`RouterFunction`)와 graphql-java `DataFetcher`는 요청 처리 코드를 람다로 쓴다. 람다 본문은 그 람다를 쓴 설정 클래스의 메서드로 컴파일된다. 그래서 그 설정 클래스가 곧 endpoint다.
|
||||
- 탐침 A1: 사용자 전송 패키지 밖 `@Configuration`이 `POST /admin/nightly/run-now` route 람다에서 `@SystemCaller` 작업의 `run()`을 부른다. 새 규칙은 위반 0. `c508b1ba` 판정식은 위반 1. 같은 route를 `@Component`에 두면(A1c) 새 규칙도 위반 1.
|
||||
- 탐침 A2: GraphQL `runNow` mutation의 `DataFetcher` 람다로 같은 모양. 새 규칙 위반 0, `c508b1ba` 판정식 위반 1.
|
||||
- 다른 규칙도 막지 않는다. 정적 `@ArchTest` 규칙 89개를 두 설정에 돌려 위반이 0이었다.
|
||||
- Javadoc은 "설정을 빼도 열리는 길이 없다. 설정이 만드는 controller는 자신이 검사받는다"고 적는다. 매뉴얼 07과 업그레이드 안내도 설정은 걸리지 않는다고만 적는다. 이 길은 「규칙이 못 보는 길」 목록에도 없다.
|
||||
- **발생 조건·영향**:
|
||||
- 조건: 파생 서비스가 "지금 실행" endpoint를 함수형으로 쓰고, 그 route 또는 fetcher를 작업과 같은 leaf의 설정 클래스(사용자 전송 패키지 밖)에 둔다. 매뉴얼 07 `:95`는 예약 작업이 controller와 같은 leaf에 놓이기 쉽다고 적는다. 함수형 endpoint는 Spring이 문서로 권하는 방식 가운데 하나다.
|
||||
- 영향: 인증만 된 사용자 요청이 권한 검사 없는 `@SystemInvoked` 쓰기를 부른다. 빌드는 아무 신호도 내지 않는다. r6에서 막은 RR3-01-01과 같은 피해다.
|
||||
- Important로 둔 이유: 이 커밋이 만든 회귀다. 문서 세 곳이 이 길이 닫혀 있다고 말한다. 조건은 RR3-01-01·RR4-01-01과 같은 "같은 leaf"라서 Critical·High는 아니다.
|
||||
- **고치는 법**:
|
||||
1. 설정 제외에 예외를 둔다. 설정이 요청 처리기를 만드는 타입에 직접 의존하면 사용자 전송으로 센다. 목록 예: `org.springframework.web.servlet.function..`, `org.springframework.web.reactive.function.server..`, `org.springframework.web.HttpRequestHandler`, `org.springframework.web.servlet.HandlerInterceptor`, `org.springframework.web.socket.WebSocketHandler`, `jakarta.servlet.Servlet`, `jakarta.servlet.Filter`, `graphql.schema.DataFetcher`, `org.springframework.graphql.execution.RuntimeWiringConfigurer`, `io.grpc.BindableService`, `io.grpc.ServerServiceDefinition`, `io.grpc.ServerCallHandler`. `WebMvcConfigurer`·`CorsRegistry` 같은 설정용 타입은 넣지 않는다(RR4-01-02 허용 fixture가 계속 통과해야 한다).
|
||||
2. 위반 fixture 두 개를 더한다: A1(`RunNowRoutesConfiguration`)과 A2(`RunNowDataFetcherConfiguration`). 노트 폴더 `rr6-01-probes/`의 파일을 그대로 쓸 수 있다.
|
||||
3. Javadoc `:497-505`, 매뉴얼 07 `:105`, 업그레이드 B-16을 "요청 처리기를 만들지 않는 설정"으로 고친다. 목록 방식이라 목록에 없는 endpoint 타입은 못 본다는 것을 「규칙이 못 보는 길」에 한 줄 더한다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋.
|
||||
- **증거**: E2 — 탐침 A1·A2·A1c(`Rr6ProbeTest`), 규칙 89개(`Rr6AllRulesProbeTest`).
|
||||
|
||||
### RR6-01-02 · Minor · 설정 안의 익명 configurer가 설정의 필드를 쓰면 아직 "사용자 전송"으로 잡힌다 (RR4-01-02 일부 남음)
|
||||
|
||||
- **위치**: `ApplicationBoundaryArchitectureTest.java:507-523`, `docs/manual/07-authorization.md:105`
|
||||
("같은 클래스에서 `WebMvcConfigurer`·interceptor·controller bean을 함께 만들어도 걸리지 않는다").
|
||||
- **무엇이 틀렸나**:
|
||||
- 제외는 설정 클래스 자신에만 적용된다. 그 안의 익명 클래스(`Config$1`)는 설정이 아니다.
|
||||
- 익명 `WebMvcConfigurer`는 웹 타입에 의존하므로 사용자 전송이다. 설정의 필드를 읽으면 바깥 인스턴스(`this$0`)에 의존한다. 설정은 handler bean에 의존한다. 그래서 `Config$1 → Config → handler` 경로가 위반이 된다.
|
||||
- 탐침 A5: 생성자에서 정한 `allowedOrigin` 필드를 `addCorsMappings`에서 읽는 익명 configurer와 handler bean을 한 설정에 두었다. 위반 1(`FeatureConfigWithAnonymousConfigurer$1 transitively depends on SystemCallerHandlerFixture`).
|
||||
- 허용 fixture `SystemCallerBesideWebMvcRegistrationFixture`는 빈 익명 클래스라 바깥을 참조하지 않아 통과한다.
|
||||
- **발생 조건·영향**: `WebMvcConfigurer`는 메서드가 여럿이라 람다로 못 쓰고 익명 클래스로 쓰는 것이 보통이다. 설정 값을 필드로 받아 쓰는 것도 흔하다. 빌드가 실패하고 메시지는 없는 경로를 말한다(실패 쪽으로 틀림). 매뉴얼은 걸리지 않는다고 적는다.
|
||||
- **고치는 법**: 설정 안에 중첩된 클래스도 설정과 같이 취급한다. 단 RR6-01-01의 "요청 처리기를 만드는 타입" 예외는 똑같이 적용한다(익명 `HandlerInterceptor`·`Filter`는 계속 사용자 전송). 탐침 A5를 허용 fixture로 더한다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋(RR4-01-02 수정이 덜 끝남).
|
||||
- **증거**: E2 — 탐침 A5.
|
||||
|
||||
### RR6-01-03 · Minor · `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`가 handler 안의 중첩 record·enum·예외와 record로 쓴 handler를 거부한다 (거짓 양성)
|
||||
|
||||
- **위치**: `ApplicationBoundaryArchitectureTest.java:664-707`(규칙과 조건), `:660-661`(익명·지역 클래스만 뺀 이유), `docs/manual/07-authorization.md:106`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 규칙은 `@SystemCaller` 클래스와 그 안에 중첩된 모든 이름 있는 클래스에 "프로젝트 밖 상위 타입 금지"를 건다.
|
||||
- 중첩 record는 `java.lang.Record`, 중첩 enum은 `java.lang.Enum`·`Comparable`·`Serializable`·`Constable`, 중첩 예외는 `RuntimeException`·`Throwable`·`Serializable`을 상위 타입으로 가진다. 모두 위반이다(탐침 A3, 세 건). record로 쓴 `@SystemCaller`도 위반이다(A7).
|
||||
- 규칙이 익명·지역 클래스를 빼는 이유는 "그 타입의 bean이 없다"이다. record·enum·예외 값도 bean이 아니고, 아무 endpoint도 그것을 `Record`·`Enum`·`Throwable`로 주입받지 않는다. 같은 이유가 적용되는데 빠지지 않았다.
|
||||
- 위반 메시지는 "endpoint가 그 타입으로 주입받으면 보이지 않는다"고 말한다. 이 경우에는 맞지 않는다.
|
||||
- **발생 조건·영향**: handler 안에 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외를 두는 것은 흔한 모양이다. 빌드가 실패하고 개발자는 그 타입을 밖으로 옮겨야 한다. 권한 구멍은 아니다(실패 쪽).
|
||||
- **고치는 법**: 조건 대상에서 record·enum·`Throwable` 하위 클래스를 뺀다(`isRecord`/`isEnum`/`isAssignableTo(Throwable.class)`). 표시한 클래스 자신의 상위 클래스 `java.lang.Record`는 `Object`처럼 무시한다. A3·A7을 허용 fixture로 더한다. 매뉴얼 07 `:106`의 "(익명·지역 클래스 제외)"를 "(익명·지역 클래스와 record·enum·예외 제외)"로 고친다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋.
|
||||
- **증거**: E2 — 탐침 A3·A7.
|
||||
|
||||
### RR6-01-04 · Minor · gRPC가 "클라이언트 취소"를 status 코드로 판정해, 서비스가 `CANCELLED`로 끝낸 살아 있는 호출의 `INTERNAL_ERROR`를 아무 데도 남기지 않는다
|
||||
|
||||
- **위치**: `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java:146-149`,
|
||||
Javadoc `:41-43`, `src/adapter/inbound/grpc/README.md:158`, 업그레이드 안내 "서버 로그" 행("클라이언트 취소 제외"),
|
||||
테스트 `GrpcExceptionHandlingInterceptorTest.java:227-240`과 `:336-338`(`isCancelled()`가 늘 `false`).
|
||||
- **무엇이 틀렸나**:
|
||||
- `logUnrecognised`는 `status.getCode() == CANCELLED`이면 남기지 않는다. 이 코드는 "이 호출의 클라이언트가 취소했다"가 아니라 "서비스가 넘긴 status가 CANCELLED다"를 뜻한다.
|
||||
- 서비스가 하위 gRPC 호출에서 받은 `CANCELLED`(프록시의 RST_STREAM CANCEL 등)를 그대로 던지거나 `onError`로 넘기면, 클라이언트는 기다리는 중인데 `INTERNAL_ERROR`를 받고 로그는 한 줄도 없다.
|
||||
- 탐침(실제 Netty): `ErrorsCancelled`(`onError(CANCELLED)`)와 `ThrowsCancelled`(`throw CANCELLED`) 둘 다 클라이언트는 `INTERNAL`, 로그 0줄. 서버 쪽 `isCancelled()`는 `false`였다. 진짜 클라이언트 취소(`Slow` + `future.cancel`)는 `isCancelled()`가 `true`, 로그 0줄.
|
||||
- 테스트 `aCallTheClientCancelledIsNotLogged`는 서비스가 `close(CANCELLED)`를 부르고 `isCancelled()`가 `false`인 호출을 만든다. 이름은 클라이언트 취소인데 보는 것은 서비스가 낸 CANCELLED다. 이 결함을 고정하는 테스트다.
|
||||
- **발생 조건·영향**: 이 커밋이 닫으려던 문제("`INTERNAL_ERROR` 실패를 아무 데도 남기지 않음")가 이 경로에 남는다. 운영자는 `INTERNAL_ERROR` 응답을 보고도 서버 로그에서 원인을 못 찾는다.
|
||||
- **고치는 법**: `close()`에서 `delegate.isCancelled()`로 판정한다(호출 자체가 취소됐을 때만 남기지 않음). 테스트 둘로 나눈다: `CapturingServerCall.isCancelled()`가 `true`인 호출은 남기지 않고, `false`인 호출에서 서비스가 `CANCELLED`로 끝내면 `unhandled failure … (status=CANCELLED)`로 남긴다. Javadoc·README·업그레이드 문구를 "클라이언트가 취소한 호출"로 맞춘다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋.
|
||||
- **증거**: E3 — 실제 Netty 서버·클라이언트 탐침(`Rr6GrpcProbeTest`).
|
||||
|
||||
### RR6-01-05 · Minor · gRPC 서비스가 raw status를 던지면 그 설명(입력값이 든)이 로그에 남는다 — 문서는 "남기지 않는다"고 적는다
|
||||
|
||||
- **위치**: `GrpcExceptionHandlingInterceptor.java:142-144`(`closeWithError`가 `withCause(exception)`), `:150-157`(cause를 예외로 붙임),
|
||||
Javadoc `:40-41`, `src/adapter/inbound/grpc/README.md:157-158`("raw status만 있으면 description은 남기지 않는다(입력이 들 수 있다)").
|
||||
- **무엇이 틀렸나**:
|
||||
- 서비스가 `onError(Status.X.withDescription(d).asRuntimeException())`로 끝내면 status에 cause가 없어 코드만 남는다.
|
||||
- 같은 status를 `throw`하면 인터셉터가 그 예외를 cause로 붙인다. `StatusRuntimeException`의 메시지는 `코드: 설명`이라서 설명이 예외 메시지로 로그에 남는다.
|
||||
- 탐침(실제 Netty): `ThrowsRawStatus`는 `throwable: INVALID_ARGUMENT: no customer with email alice@example.com`. `ErrorsRawStatus`는 같은 설명이 로그에 없다.
|
||||
- grpc-java에서 `throw Status.X.withDescription(...).asRuntimeException()`은 흔한 관용구다. 테스트 `aRawStatusWithoutACauseIsLoggedByItsCodeAlone`은 `close` 경로만 본다.
|
||||
- **발생 조건·영향**: 서비스가 입력값을 설명에 넣고 던지면 개인정보가 ERROR 로그(prod JSON의 `stack_trace`)에 남는다. 마스킹 decorator는 비밀 형식(토큰·비밀번호)만 가린다. 문서 주장과 코드가 다르다. 이 로그 줄 자체가 이 커밋에서 생겼다.
|
||||
- **고치는 법**: `logUnrecognised`에서 cause가 `StatusRuntimeException`·`StatusException`이면(즉 cause가 raw status 자신이면) 그것을 붙이지 않는다. 그 예외에 다시 cause가 있으면 그 cause만 붙인다. 테스트: handler가 설명에 입력값을 넣은 status를 던지면 로그 줄과 예외 어디에도 설명이 없다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋.
|
||||
- **증거**: E3 — 실제 Netty 탐침(`ThrowsRawStatus` / `ErrorsRawStatus`).
|
||||
|
||||
### RR6-01-06 · Minor · STOMP `@MessageMapping`의 `IllegalArgumentException`을 ERROR로, 메시지(입력값)까지 남긴다 — 다른 전송은 모두 클라이언트 쪽 `BAD_PARAMETER`로 본다
|
||||
|
||||
- **위치**: `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLog.java:31-38`,
|
||||
Javadoc `:17-20`, `src/adapter/inbound/websocket/README.md:37-39`.
|
||||
비교: `GlobalExceptionHandler.java:97`(web: WARN, 클래스 이름만), `GraphQlWireErrorMapper.java:115-121`·`:188-189`(GraphQL: `BAD_PARAMETER`, 남기지 않음),
|
||||
`GrpcExceptionHandlingInterceptor.java:131-132`(gRPC: 남기지 않음), `SafeStompSubProtocolErrorHandler.java:52`(STOMP 프레임: `BAD_PARAMETER`),
|
||||
`src/shared-contract/README.md:81`("`IllegalArgumentException`은 모든 전송에서 `BAD_PARAMETER`").
|
||||
- **무엇이 틀렸나**:
|
||||
- advice는 carrier가 아니면 모두 `unhandled failure in a STOMP message handler`로 ERROR에 예외를 붙여 남긴다. IAE도 여기로 간다.
|
||||
- 탐침: `throw new IllegalArgumentException("unknown recipient alice@example.com")` → `ERROR … | throwable: java.lang.IllegalArgumentException: unknown recipient alice@example.com`.
|
||||
- web은 이 경우 메시지를 일부러 빼고 클래스 이름만 WARN으로 남긴다. GraphQL·gRPC는 남기지 않는다. advice의 Javadoc은 "클라이언트 쪽 거절을 오류로 남기던 것"을 고쳤다고 적는다.
|
||||
- **발생 조건·영향**: 잘못된 입력 하나마다 ERROR 줄과 스택이 생기고, 입력값(이메일 등)이 로그에 남는다. "모든 전송이 같은 줄"이라는 r9 주장과 다르다.
|
||||
- **고치는 법**: advice가 IAE를 `BAD_PARAMETER`로 보고 `ServerFailureLog.of(failure, OperationalError.BAD_PARAMETER)`를 쓴다(결과: 남기지 않음). web의 WARN 한 줄까지 맞추려면 "IAE → `BAD_PARAMETER`" 줄을 `ServerFailureLog`에 두고 네 전송이 같이 쓴다. STOMP 테스트에 IAE 경우를 더한다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋(advice가 새로 생김). web의 WARN 줄과 GraphQL·gRPC의 무기록이 다른 것은 이전부터.
|
||||
- **증거**: E2 — `Rr6StompProbeTest`(실제 STOMP method handler).
|
||||
|
||||
### RR6-01-07 · Minor · runbook이 lease 만료 시작 거절의 문구를 "ERROR 줄의 message"에 있다고 적는다 — 실제로는 붙은 예외의 메시지다
|
||||
|
||||
- **위치**: `docs/runbooks/idempotency-unavailable.md:21-23`("The ERROR line's message then reads `the claim's processing lease ran out …`"), `:101`("When the message says …").
|
||||
- **무엇이 틀렸나**:
|
||||
- 그 거절은 `IdempotencyUnavailableException`(503)이다. 로그 줄의 message는 `ServerFailureLog`가 정한 `failure classified as IDEMPOTENCY_UNAVAILABLE (category=…, retryable=true)`다.
|
||||
- "the claim's processing lease ran out …" 문구는 붙은 예외의 메시지다. prod 로그는 `LogstashEncoder`(`src/app-bootstrap/src/main/resources/logback-spring.xml:87`)라서 이 문구는 `message`가 아니라 `stack_trace` 필드에 있다.
|
||||
- 같은 runbook의 `IDEMPOTENCY_RECOVERY_REQUIRED` 설명(`:51-61`)은 "예외가 붙고, 예외 메시지 끝에 digest"라고 바르게 적는다.
|
||||
- **발생 조건·영향**: 운영자가 `message` 필드로 검색하면 찾지 못한다. "저장소는 멀쩡하다"는 판단의 근거를 놓치고 저장소 장애를 쫓는다.
|
||||
- **고치는 법**: `:21-23`을 "the line has the exception attached; its message reads …"로, `:101`을 "When the exception message says …"로 고친다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋.
|
||||
- **증거**: E1 — `IdempotencyExecutor.java:198-201`, `ServerFailureLog.java:66-71`, `logback-spring.xml:87` 대조.
|
||||
|
||||
### RR6-01-08 · Minor · GraphQL 테스트 `aClientSideCarrierIsNotLogged`가 carrier가 아니라 `IllegalArgumentException`을 넣는다
|
||||
|
||||
- **위치**: `src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapperTest.java:193-206`.
|
||||
- **무엇이 틀렸나**: 이름은 "클라이언트 쪽 carrier는 남기지 않는다"인데 입력은 `new IllegalArgumentException("bad cursor")`다. `sharedCodeOf`의 carrier 분기(`failure instanceof ApiErrorCarrier`)가 아니라 IAE 분기를 지난다. 4xx carrier가 남지 않는다는 것은 이 테스트가 보지 않는다. gRPC·STOMP의 같은 이름 테스트는 실제 4xx carrier를 쓴다.
|
||||
- **발생 조건·영향**: carrier 분기에서 로그 조건이 바뀌어도 이 테스트는 통과한다.
|
||||
- **고치는 법**: 4xx carrier(예: 테스트 안의 작은 carrier에 `OperationalError.BAD_PARAMETER`, 또는 `IdempotencyInFlightException`)로 바꾼다. IAE 경우는 이름을 맞춘 별도 테스트로 남긴다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋.
|
||||
- **증거**: E1 — 테스트 코드와 `GraphQlWireErrorMapper.java:184-190` 대조.
|
||||
|
||||
### RR6-01-09 · Minor · (이전부터) `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`는 shared-contract 안에서 아무것도 잡지 못한다 — 코드에 "KNOWN DEFECT"로 남아 있다
|
||||
|
||||
- **위치**: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java:98-114`(주석 "KNOWN DEFECT, deliberately left as found"), `:52-72`(허용 목록), `:78-80`(접두어 비교).
|
||||
- **무엇이 틀렸나**:
|
||||
- 허용 목록에 모듈 뿌리 `dev.caskeleton.shared`가 있고 비교는 접두어다. 그래서 `dev.caskeleton.shared` 아래 모든 패키지가 허용된다.
|
||||
- 탐침: `dev.caskeleton.shared.rr6bogus.BusinessRuleInShared`(업무 규칙 흉내)에 위반이 없다.
|
||||
- 지금 shared-contract의 `digest`·`observability`·`ratelimit`·`retry`·`runtime` 패키지는 목록에 없는데도 통과한다. 목록이 이미 실제와 다르다는 뜻이다.
|
||||
- 대상 술어 `..shared..`는 모듈과 무관한 `…tenancy.shared` 같은 패키지를 잡아 목록에 예외(`:65`)를 늘렸다. 주석이 스스로 두 잘못을 적고 고치기를 미뤘다. 이 리뷰 시리즈의 README·라운드 문서 어디에도 기록되지 않았다(`docs/reviews/2026-11-0*` grep 0건).
|
||||
- **발생 조건·영향**: shared-contract에 업무 개념 패키지가 생겨도 빌드가 모른다. CLAUDE.md 표는 shared-contract를 "Skeleton-wide operational contracts"로 묶는다. 이 규칙이 그 경계의 유일한 패키지 검사다. 소유자 지시("남은 문제 0")와도 어긋난다.
|
||||
- **고치는 법**: 대상을 `dev.caskeleton.shared..`로 좁힌다. 허용은 정확히 같은 패키지 또는 그 아래로 하되 뿌리는 뿌리 자체(`package-info`)만 허용한다. 지금 있는 패키지 중 계약인 것을 목록에 넣는다(`digest`·`observability`·`ratelimit`·`retry`·`runtime`은 shared-contract CLAUDE.md "Responsibility"에 근거가 있다). `…tenancy.shared` 예외는 지운다. 위반 fixture는 `TemplatePackageOwnership`처럼 뿌리를 매개변수로 받는 판정식으로 fixture 뿌리에서 증명한다(주석이 미룬 이유 "fixture가 규칙의 분석 범위에 들어간다"를 이 방법이 푼다).
|
||||
- **이번 커밋/이전부터**: 이전부터(`1400dc15` 이전, 2026-08 wave0 baseline에 처음 기록).
|
||||
- **증거**: E2 — `Rr6SharedProbeTest`. E1 — 허용 목록과 `src/shared-contract/src/main/java/dev/caskeleton/shared/` 디렉터리 대조.
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- 감싼 carrier: web·GraphQL·STOMP는 맨 위 예외만 carrier로 보고, gRPC는 원인 사슬을 따라간다(`carrierOf`). 그래서 다른 예외에 감싼 `PersistenceFailureException`은 web·GraphQL·STOMP에서 "unhandled"로 SQL 원인과 함께 남고 gRPC에서는 분류만 남는다. 이전부터의 차이다. 템플릿 코드에서 carrier를 감싸 던지는 곳은 찾지 못했고(GraphQL은 Spring이 `CompletionException`을 벗긴다), 현실 조건을 세우지 못해 판단하지 않았다.
|
||||
- `DependencyFailureException`과 그 밖의 5xx carrier는 모든 전송에서 원인 사슬째 남는다. web은 전부터 그랬고 이번에 다른 전송으로 넓어졌다. 의존 클라이언트 예외 메시지가 자격 증명·URL을 싣는지는 클라이언트마다 달라 판단하지 않았다(마스킹 decorator가 알려진 비밀 형식은 가린다).
|
||||
- GraphQL은 실패한 필드마다 한 줄을 남긴다. 키 N개가 5xx batch 코드로 실패하면 ERROR 줄도 N개다. 필드 단위 오류 설계의 결과이고 양은 재지 않았다.
|
||||
- `docs/upgrade/2026-11-maturity-review.md` B-34가 템플릿 패키지 이름을 다시 나열한다(세 번째 복사본). 그 릴리스 시점의 변경 기록이라 갈라진 복사본으로 보지 않았다.
|
||||
- STOMP에서 payload 변환·검증 실패(`MessageConversionException`, `MethodArgumentNotValidException`)는 여전히 ERROR로 남는다. 전에도 Spring이 그렇게 남겼고, STOMP 프레임 매핑도 이것을 클라이언트 코드로 분류하지 않아 RR6-01-06에 넣지 않았다.
|
||||
- RR6-01-01 고치는 법의 endpoint 타입 목록이 완전한지는 확인하지 않았다. 목록 방식의 한계는 기존 `ARE_USER_TRANSPORT_TYPES`와 같다.
|
||||
- 규칙 89개 탐침은 정적 `@ArchTest` 필드만 돌렸다. 이 스위트들에 메서드형 `@ArchTest`는 없다(grep).
|
||||
|
||||
## 결론
|
||||
|
||||
- 결함 9건: Important 1, Minor 8. 이번 커밋 8건, 이전부터 1건(RR6-01-09).
|
||||
- 회귀 1건: `@Configuration` 제외(RR4-01-02 수정)가 RR3-01-01이 막은 "사용자 요청 → 시스템 호출자" 길을 함수형 endpoint에 다시 열었다(RR6-01-01). 가장 먼저 고칠 것이다.
|
||||
- 닫힘: RR4-01-01, `graphql..` fixture, 원래 리뷰 16.3(세 방향 모두 탐침으로 확인), RR4-03-03, STOMP SQL 원인 기록, web 로그 리팩터링.
|
||||
- 부분: RR4-01-02(익명 configurer 거짓 양성, RR6-01-02), gRPC `INTERNAL_ERROR` 기록(RR6-01-04·05).
|
||||
- 판정: With fixes.
|
||||
@@ -0,0 +1,231 @@
|
||||
# 02 멱등성·outbound r9 리뷰 (2026-11-05)
|
||||
|
||||
대상: 수정 커밋 `45d2a478`(Base `c508b1ba`)의 r9-b 묶음 — CLAIMED → 시작의 lease, RR5-01-02~05, RR5-03-01,
|
||||
RR4-03-01·02·04 — 와 README 16.1절의 httpclient drain 스레드 수정. 결함 ID 접두어 `RR6-02-`.
|
||||
|
||||
## 범위
|
||||
|
||||
### pathspec
|
||||
|
||||
```
|
||||
src/application-core/src/main/java/dev/caskeleton/application/idempotency src/application-core/src/testFixtures
|
||||
src/application-core/src/test src/adapter/outbound/cache-redis
|
||||
src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency
|
||||
src/adapter/outbound/persistence-jpa/src/test src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest
|
||||
src/adapter/outbound/httpclient src/adapter/outbound/redis-runtime src/composition/idempotency src/.env.example
|
||||
docs/web/http-contract.md docs/manual/05-idempotency.md docs/runbooks/idempotency-unavailable.md
|
||||
docs/registries/env-keys.yaml
|
||||
```
|
||||
|
||||
`git diff c508b1ba..45d2a478 -- <pathspec>`: 33파일, +1445 −115. 의미가 바뀐 공개 설명을 따라가느라 pathspec 밖
|
||||
파일도 읽었다: `src/adapter/inbound/web/README.md`, `docs/upgrade/2026-11-maturity-review.md`,
|
||||
`src/shared-contract/.../ServerFailureLog.java`, `src/app-bootstrap/src/main/resources/logback-spring.xml`,
|
||||
`infra/redis-sdk/acl/*`, `docs/registries/error-codes.yaml`.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 무엇을 봤나 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 이 커밋이 만든 결함과 "고쳤다"는 주장의 닫힘을 따로, 심각도별, file:line 근거 | 항목 재확인 표, 결함 5건 |
|
||||
| `api-and-interface-design` | 멱등 키 절: 원자적 claim, 처리 중 중복에 대한 의도된 응답, 결과는 성공·실패·불명 셋, 실패 의미 일관성(값 하나에 뜻 하나), Hyrum's Law(관찰되는 동작 변화는 계약 변화) | `LEASE_EXPIRED`가 두 저장소에서 같은 순서·같은 경계로 판정되는지, executor의 503이 "실행 안 됨"과 맞는지, 같은 attempt 재시도의 결과(RR6-02-01), 새 enum 값의 공개 영향(B-41) |
|
||||
| `performance-optimization` | 측정 전후, 회귀 장치가 실제로 회귀를 잡는가, 스레드·큐 비용 | watchdog 스레드의 유휴 종료가 read당 비용을 바꾸지 않는지(코드), 유휴 종료 직후 새 예약이 고립되지 않는지(JDK 탐침 4만 회), RR4-03-01 RED 단언이 기계와 무관한지 |
|
||||
| `doubt-driven-development` | 주장마다 반증을 먼저 시도. 하위 에이전트 금지라 fresh-context 리뷰어 대신 스스로 반대 논증을 세웠다(성능 저하된 단독 모드). 비대화 맥락이라 cross-model 검토는 하지 않았다 | "두 저장소 판정이 같다", "runbook 삭제가 원자적이고 ACL과 맞다", "watchdog 경쟁이 안전하다", "공유 계약이 세 구현에서 돈다"를 각각 실 Redis·실 PG·JDK 탐침으로 반증 시도. 결함마다 반대 논증을 적었다 |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
모두 별도 worktree(`git worktree add --detach <scratchpad>/rr6-02/wt 45d2a478`)에서, Gradle·Docker는 공유 잠금
|
||||
`flock …/heavy.lock`으로 감쌌다.
|
||||
|
||||
1. 실 Redis 7.4 + `infra/redis-sdk/acl/lane-fixture-accounts.acl`(부하 3.25). runbook의 두 줄을 파일에서 그대로
|
||||
꺼내 `redis-cli`에 넣었다(`probe/runbook-redis.sh`). advanced 계정: `SCRIPT LOAD` 성공, `ABANDONED` 기록에
|
||||
`EVALSHA` → `1`·키 삭제, `EXECUTING` 기록 → `0`·상태 유지, 없는 키 → `0`, `EVAL` → `NOPERM`, 스크립트 캐시를
|
||||
비운 뒤 → `NOSCRIPT`·삭제 없음. application 계정: `SCRIPT LOAD`·`EVALSHA` 모두 `NOPERM`.
|
||||
2. `:adapter:outbound:cache-redis:test --tests '*RedisIdempotencyStoreContractTest' --tests '*RedisIdempotencyStoreAdapterTest'`
|
||||
— worktree에서 `RedisIdempotencyStoreContractTest`에 `elapse → commands.advance(duration)` 3줄을 넣은 탐침
|
||||
(부하 3.84). 계약 31 통과·skip 0, adapter 34 통과. 탐침은 되돌렸다.
|
||||
3. 원래 코드로 `:adapter:outbound:cache-redis:test --tests '*RedisIdempotencyStoreContractTest' :application-core:test --tests '*idempotency*' :adapter:outbound:httpclient:test --tests '*ReadIdleInputStreamTest' --tests '*ClientRuntimeRegistryTest'`
|
||||
(부하 4.11) — 모두 통과. command fake 계약 31 중 17 skip, in-memory fake 계약 31 중 17 skip,
|
||||
`IdempotencyExecutorTest` 17, `ReadIdleInputStreamTest` 10, `ClientRuntimeRegistryTest` 4.
|
||||
4. `java StpeRace.java 200 20000`, `java StpeRace.java 50 20000` — watchdog과 같은 설정(core 1,
|
||||
`allowCoreThreadTimeOut`, keep-alive 200µs/50µs)의 실행기에 worker가 유휴 종료하는 순간 근처로 예약을 4만 번
|
||||
넣었다. 고립된 예약 0, 최대 대기 5 ms, 스레드가 없는 상태에서 시작한 회차 4,823/350.
|
||||
5. 실 Redis 7.4에서 출하 `CLAIM`·`TRANSITION` 프로그램을 `SCRIPT LOAD`+`EVALSHA`(advanced 계정)로 실행
|
||||
(`probe/retained.sh`, 부하 2.81): 같은 attempt가 lease 1s를 넘긴 뒤 재시도 3회 모두 `REPLAYED_ACQUIRE` →
|
||||
`LEASE_EXPIRED`, 새 attempt는 `TAKEN_OVER 2`(RR6-02-01).
|
||||
6. `:adapter:outbound:cache-redis:redisContainerContractTest :adapter:outbound:persistence-jpa:postgresqlIdempotencyIntegrationTest`
|
||||
(부하 3.37, 잠금 대기 약 10분 뒤 1분 14초) — live Redis lane 72 통과·skip 0(그중 `LiveRedisIdempotencyStoreContractTest`
|
||||
31, `LiveRedisIdempotencyRunbookTest` 2), PG 멱등성 통합 10 통과.
|
||||
7. `:adapter:outbound:persistence-jpa:jpaPlatformContractTest --tests '*PostgreSqlIdempotencyStoreContractTest'`
|
||||
(부하 3.58) — 31 통과·skip 0(33초).
|
||||
8. executor + Redis adapter + command fake 탐침 테스트(`Rr602RetainedAttemptProbeTest`, 부하 2.37): 같은 attempt
|
||||
재시도 3회와 1시간 뒤 모두 503 `IDEMPOTENCY_UNAVAILABLE`, 새 attempt는 작업을 한 번 실행. 탐침 파일은 지웠다.
|
||||
9. `java F.java` — JDK 21.0.12의 `Thread`에 `inheritedAccessControlContext` 필드가 있음을 확인(Declined 참고).
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- pathspec 안의 r9-c 파일(`PostgreSqlMigrationLockWaitIntegrationTest`, `LockWaitMigrationInspectorTest`,
|
||||
`VersionedMigrationFilesTest`)은 영역 03(persistence) 몫이라 깊게 보지 않았다.
|
||||
- `httpclient`의 `httpClientPerformanceTest`·`httpClientFailureInjectionTest`는 다시 돌리지 않았다.
|
||||
- 16.1절의 RED 주장(옛 `ClientRuntimeRegistry`에서 새 테스트 실패)은 다시 돌리지 않았다. 옛 코드가 scheduler를
|
||||
멈추기 전에 예외를 던지므로 결정적으로 실패한다(코드 읽기).
|
||||
- Redis cluster에서 runbook의 `NOSCRIPT` 절차는 실행하지 않았다(standalone만).
|
||||
- 짝 프론트 repo 문서는 보지 않았다.
|
||||
|
||||
## 항목 재확인
|
||||
|
||||
| ID | 판정 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| README 15 남음 — CLAIMED → 시작에서 PG는 lease를 보고 Redis는 보지 않음 | 닫힘 | Redis `IdempotencyScripts.java:155-162`, PG `PostgreSqlIdempotencyStore.java:197-204`·`IdempotencyTransitionGateway.java:42`, fixture `InMemorySemanticRedisCommands.java:280-283`, 계약 `IdempotencyStoreContract.java:731-771`(실 PG·실 Redis 모두 통과, 명령 6·7), executor `IdempotencyExecutor.java:195-201`. 두 저장소 모두 서버 시계로 `now ≥ leaseUntil`이면 만료(claim과 같은 경계), 이미 적용된 시작의 재시도(`ALREADY`)는 lease보다 먼저 판정. 같은 attempt 재시도는 RR6-02-01 |
|
||||
| RR5-01-02 renew·inspect 값의 뜻 | 닫힘 | `IdempotencyRenewOutcome.java:4-35`, PG `:240-246`, Redis `IdempotencyScripts.java:235-240`, fixture `:327-332`, 계약 `:709-727`(`LEASE_EXPIRED` + 빈 owner). `ABANDONED`는 Javadoc 유지(권고안 중 하나)와 executor 주석 `:171-175` |
|
||||
| RR5-01-03 포트 Javadoc "마지막 보고" | 닫힘 | `IdempotencyStorePort.java:12-23`, 계약 `:381-405`. 저장소·문서에 "last report" 문구 남지 않음(grep) |
|
||||
| RR5-01-04 늦은 실패 경로 | 닫힘 | 계약 `:617-685`(실 PG·실 Redis 통과), adapter `RedisIdempotencyStoreAdapterTest.java:410-445`. 두 fake 위 시간 케이스 skip은 RR6-02-02 |
|
||||
| RR5-01-05 PG 기본 모양 | 닫힘 | `http-contract.md:123-141`, `manual/05-idempotency.md:59-70`, runbook `:40-43`, `PostgreSqlIdempotencyIntegrationTest`의 두 새 테스트(명령 6). 매뉴얼 첫 문장은 RR6-02-05 |
|
||||
| RR5-03-01 `APP_IDEMPOTENCY_TTL` 상한 안내 | 닫힘 | `env-keys.yaml:1603-1616`, `module-defaults/idempotency.yml:15-19`, `composition/idempotency/README.md:48`·`:76`, `.env.example:124-125`. `IdempotencySettings`의 `<` 비교와 문서의 "이하"가 같다 |
|
||||
| RR4-03-01 watchdog RED 테스트가 병렬도 1에서 무력 | 닫힘 | `ReadIdleInputStreamTest.java:114`(닫은 스레드 이름 단언 — 옛 코드는 공용 풀이나 `Thread-N`에서 닫는다) |
|
||||
| RR4-03-02 Redis 삭제가 두 명령 | 닫힘 | runbook `:126-145`, `LiveRedisIdempotencyRunbookTest`(명령 6), 실 `redis-cli`로 블록 그대로 실행(명령 1). Lua 한 번이라 확인과 삭제 사이 틈이 없다. ACL: advanced 계정에 `script|load`·`evalsha`가 있고 `eval`이 없음과 맞다 |
|
||||
| RR4-03-04 watchdog 스레드 수명 | 닫힘 | `ReadIdleInputStream.java:51-59`·`:101-134`, 테스트 `:160-243`. 유휴 종료 직후 예약 경쟁은 JDK `processWorkerExit`가 큐를 다시 보고 worker를 만든다 — 명령 4에서 고립 0 |
|
||||
| README 16.1 drain 스레드 join·예외 순서 | 닫힘 | `ClientRuntimeRegistry.java:148-195`: 런타임 실패가 먼저, scheduler 정지 실패는 suppressed. `awaitTermination` 뒤 같은 마감 안에서 join. 테스트 `ClientRuntimeRegistryTest.java:63-83` |
|
||||
|
||||
## 결함
|
||||
|
||||
### RR6-02-01 · Minor · 시작을 `LEASE_EXPIRED`로 거절당한 attempt는 같은 attempt로 다시 보내도 영원히 503이다
|
||||
|
||||
- **위치**: `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java:82-89`
|
||||
(CLAIM이 같은 owner·operation을 lease보다 먼저 `REPLAYED_ACQUIRE`로 답함), `:155-162`(시작 거절),
|
||||
`src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java:141-143`,
|
||||
`src/application-core/.../idempotency/IdempotencyExecutor.java:142-143`·`:198-201`. 약속하는 문서:
|
||||
`docs/web/http-contract.md:111`, `docs/manual/05-idempotency.md:72-73`, `src/application-core/README.md:274-275`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 시작을 `LEASE_EXPIRED`로 거절당한 claim은 `CLAIMED`로 남는다.
|
||||
- 같은 attempt(같은 owner token·operation id)로 다시 claim하면 CLAIM은 lease를 보기 전에 `REPLAYED_ACQUIRE`로
|
||||
답한다. PG도 `sameClaimAttempt`가 만료 검사(`:147`)보다 앞이다.
|
||||
- executor는 `ReplayedAcquire`를 `Acquired`처럼 시작으로 보낸다. 시작은 다시 `LEASE_EXPIRED`다.
|
||||
- 그래서 그 attempt를 쥔 호출자는 기록이 사라질 때까지(lease + `replay-ttl`, 기본 약 24h) 매번 503을 받는다.
|
||||
- 문서의 "다음 같은 키 요청이 그 claim을 넘겨받아 실행한다"는 새 attempt에만 맞다.
|
||||
- **발생 조건·영향**:
|
||||
- API는 attempt를 재시도 사이에 유지하라고 한다: `IdempotencyClaimAttempt` "Caller-retained identity for one
|
||||
claim send/retry sequence", `IdempotencyExecutor#newAttempt` "retains across a lost response".
|
||||
- 503은 `retryable=true`다. attempt를 유지하는 호출자(재시도 래퍼, 메시지 소비자)는 같은 attempt로 다시 보낸다.
|
||||
- 템플릿 안의 호출자(`PublishPosterImageUseCase.java:106`)는 요청마다 새 attempt를 만들어 해당하지 않는다.
|
||||
HTTP 재전송은 서버에서 새 attempt가 되어 HTTP 계약은 지켜진다.
|
||||
- 중복 실행은 없다. 진행이 막힌다. 이 커밋 전에는 Redis가 그 claim을 시작해 실행했다.
|
||||
- PG를 쓰기 트랜잭션 하나로 쓰면 503과 함께 기록이 롤백되어 해당하지 않는다. 호출마다 트랜잭션을 여는
|
||||
모양에서는 같다.
|
||||
- **고치는 법**(둘 중 하나를 정한다):
|
||||
- (a) 두 저장소 claim에서 "lease가 지난 `CLAIMED`는 같은 attempt라도 넘겨받는다". Redis CLAIM의
|
||||
`state == 'CLAIMED' and leaseOver` 분기를 `owner == ARGV[1]` 분기 앞으로, PG `claim`의 `:147` 검사를
|
||||
`:141` 앞으로 옮긴다. 답은 `TakenOverClaimed`(attempt+1, 새 lease). command fake도 같게. 공유 계약에 "시작을
|
||||
거절당한 attempt가 같은 attempt로 다시 claim하면 넘겨받아 시작한다" 케이스를 더한다. 주의: 같은 attempt의 멈춘
|
||||
첫 호출이 나중에 시작을 보내면 Redis TRANSITION은 상태가 이미 `EXECUTING`일 때 revision을 보지 않고
|
||||
`ALREADY`로 답한다(`:138-146`). 같은 attempt를 동시에 쓰는 이전부터의 위험(5차 리뷰 Declined)과 같은 것이다.
|
||||
- (b) 동작을 두려면 `IdempotencyClaimAttempt`·`IdempotencyExecutor#newAttempt` Javadoc과 executor 메시지
|
||||
(`:199-201`)에 "`LEASE_EXPIRED`로 거절된 attempt는 다시 쓰지 않고 새 attempt를 만든다"를 적는다. 문서 세 곳의
|
||||
"다음 같은 키 요청"을 "다음 같은 키 요청(새 attempt)"으로 좁힌다. 공유 계약에 지금 동작을 고정하는 케이스를 둔다.
|
||||
- **반대 논증**: attempt는 응답을 잃었을 때만 유지하고 명시적 거절 뒤에는 새로 만드는 것이 의도라면, 동작이 아니라
|
||||
문서 누락이다. 그 의도는 어디에도 적혀 있지 않고, 503은 재시도하라고 말한다.
|
||||
- **이번 커밋**. 가이드 심각도 Low · P3.
|
||||
- **증거**: E3 — 실 Redis에서 출하 Lua(명령 5). E3 — executor까지 command fake 위에서(명령 8). PG는 E1(코드).
|
||||
|
||||
### RR6-02-02 · Minor · command fake 위 공유 계약이 시계를 움직일 수 있는데도 시간 케이스 17개를 skip한다
|
||||
|
||||
- **위치**: `src/application-core/src/testFixtures/.../testkit/IdempotencyStoreContract.java:64-69`(Javadoc),
|
||||
`src/adapter/outbound/cache-redis/src/test/.../idempotency/RedisIdempotencyStoreContractTest.java:17-37`
|
||||
(`elapse` override 없음), `src/adapter/outbound/redis-runtime/src/testFixtures/.../InMemorySemanticRedisCommands.java:44`
|
||||
(`advance`), `RedisIdempotencyStoreAdapterTest.java:357-445`(손 사본).
|
||||
- **무엇이 틀렸나**:
|
||||
- 계약 Javadoc은 command fake 위 Redis store를 "시계를 움직일 수 없는 store"로 묶어 기본 `elapse`(abort)를 쓴다고 적는다.
|
||||
- command fake는 `advance(Duration)`로 시계를 움직인다. adapter 테스트가 그것으로 시간 케이스를 손으로 다시 쓴다.
|
||||
- 그래서 `RedisIdempotencyStoreContractTest`는 시간 케이스 17개를 skip한다. adapter 테스트는 그중 일부만 복사한다.
|
||||
이 커밋이 사본을 4건 더 늘렸다(`:373-445`).
|
||||
- 사본이 없는 시간 케이스(`aClaimMeetingAnExpiredExecutionLeavesTheRecordToItsHolder`,
|
||||
`anExpiredExecutionsHolderCanStillReportAnUnknownEffect`, `aRenewedLeaseOutlivesItsFirstExpiry` 등)에서는
|
||||
fixture의 Lua 사본이 단위 수준에서 검사되지 않는다.
|
||||
- **발생 조건·영향**: fixture가 Lua와 갈라지면 단위 테스트가 못 잡는다. 실 Lua는 `redisContainerContractTest`가
|
||||
잡으므로 운영 동작 피해는 없다. 잃는 것은 fixture를 쓰는 테스트의 신뢰도다.
|
||||
- **고치는 법**: `RedisIdempotencyStoreContractTest`가 만든 `InMemorySemanticRedisCommands`를 필드로 두고
|
||||
`elapse`에서 `commands.advance(duration)`을 부른다. 계약 Javadoc `:64-69`에서 command fake를 뺀다. 계약과 겹치는
|
||||
adapter 손 사본은 지우거나 계약 케이스를 가리키게 한다. fixture는 멱등성 hash에 key TTL을 두지 않는다
|
||||
(`InMemorySemanticRedisCommands.java:184-247`에 PEXPIRE 없음). 그래서 기록 수명 케이스
|
||||
(`aLeaseLongerThanTheReplayTtlKeepsTheRecordForTheWholeLease` 등)는 기록이 영원히 남아서 통과한다. 그 케이스도
|
||||
의미 있게 하려면 fixture CLAIM·TRANSITION·RENEW에 TTL을 둔다.
|
||||
- **이전부터**(Javadoc 문장은 `5786126c`/`bbe944bd`). 이번 커밋이 손 사본을 늘렸다. 가이드 심각도 Low · P3.
|
||||
- **증거**: E2 — `elapse` override 3줄을 넣은 탐침으로 31 통과·skip 0(명령 2). 원래 코드는 31 중 17 skip(명령 3).
|
||||
|
||||
### RR6-02-03 · Minor · runbook이 시작 거절 문장을 ERROR 줄의 "message"에서 찾으라고 한다
|
||||
|
||||
- **위치**: `docs/runbooks/idempotency-unavailable.md:20-24`, `:100-101`.
|
||||
- **무엇이 틀렸나**:
|
||||
- runbook은 "The ERROR line's message then reads `the claim's processing lease ran out before the action started; …`"라고 적는다.
|
||||
- 실제 ERROR 줄의 메시지는 `failure classified as IDEMPOTENCY_UNAVAILABLE (category=TRANSIENT_DEPENDENCY, retryable=true)`다
|
||||
(`ServerFailureLog.java` 5xx 분기). 그 문장은 줄에 붙은 예외의 메시지다.
|
||||
- local·dev 밖 프로필의 로그는 `LogstashEncoder` JSON이다(`logback-spring.xml:84-100`). 예외는 `message`가 아니라
|
||||
`stack_trace` 필드에 있다.
|
||||
- 같은 runbook의 `IDEMPOTENCY_RECOVERY_REQUIRED` 항목(`:51-61`)은 "with the exception attached … The exception
|
||||
message ends with"로 맞게 적는다.
|
||||
- **발생 조건·영향**: 운영자가 로그 시스템에서 `message`로 이 문장을 찾으면 못 찾는다. 그러면 저장소 장애로 보고
|
||||
저장소 담당을 부른다. 이 503을 저장소 장애와 가르는 것이 이 문단의 목적이다.
|
||||
- **고치는 법**: `:22`를 "The ERROR line (`failure classified as IDEMPOTENCY_UNAVAILABLE …`) carries the exception,
|
||||
whose message reads `…`; in JSON logs it is in `stack_trace`."로, `:100-101`의 "When the message says"를 "When the
|
||||
attached exception's message says"로 고친다.
|
||||
- **이번 커밋**. 가이드 심각도 Low · P3.
|
||||
- **증거**: E1 — `ServerFailureLog.of`의 형식 문자열, logback 설정.
|
||||
|
||||
### RR6-02-04 · Minor · `IDEMPOTENCY_UNAVAILABLE`의 넓어진 뜻이 웹 어댑터 매핑 표와 프론트 인계 표에 없다
|
||||
|
||||
- **위치**: `src/adapter/inbound/web/README.md:243`, `docs/upgrade/2026-11-maturity-review.md:280`(7절 짝 프론트).
|
||||
둘 다 pathspec 밖이다.
|
||||
- **무엇이 틀렸나**:
|
||||
- 이 커밋으로 503 `IDEMPOTENCY_UNAVAILABLE`은 "저장소가 응답하지 않음"과 "claim의 lease가 시작 전에 끝나 저장소가
|
||||
시작을 거절함" 둘을 뜻한다.
|
||||
- `http-contract.md:111`, `manual/05-idempotency.md:52`, runbook, `application-core/README.md:274-275`는 고쳤다.
|
||||
- 위 두 곳은 여전히 "조정 저장소가 응답하지 않아 action 전에 거부", "실행 전 저장소 응답 없음"만 적는다.
|
||||
- **발생 조건·영향**: 클라이언트 행동은 같다(같은 키로 나중에). 다만 매핑 표와 인계 표를 읽는 개발자는 이 503을
|
||||
저장소 장애로만 읽는다. 갈라진 복사본이다.
|
||||
- **고치는 법**: 두 행에 "또는 claim의 processing lease가 시작 전에 끝나 저장소가 시작을 거절함(실행 안 됨)"을 더한다.
|
||||
- **이번 커밋**. 가이드 심각도 Low · P3.
|
||||
- **증거**: E1 — `grep -rn IDEMPOTENCY_UNAVAILABLE`.
|
||||
|
||||
### RR6-02-05 · Minor · 매뉴얼 05의 첫 문장 "같은 키 재전송은 작업을 다시 돌리지 않는다"가 바로 아래 PostgreSQL 항목과 어긋난다
|
||||
|
||||
- **위치**: `docs/manual/05-idempotency.md:57-58`과 `:65-70`.
|
||||
- **무엇이 틀렸나**:
|
||||
- 문단 첫 문장은 "같은 키 재전송은 작업을 다시 돌리지 않는다"이고, 예외를 "첫 시도가 lease보다 오래 걸릴 때"로 좁힌다.
|
||||
- 바로 아래 PostgreSQL 항목은 lease와 무관하게 "작업이 예외로 끝나면 실패 기록도 함께 롤백되어 다음 같은 키
|
||||
요청이 다시 실행한다", "트랜잭션 밖 효과는 다음 요청에서 다시 일어날 수 있다"고 적는다.
|
||||
- 그래서 첫 문장은 PostgreSQL 기본 모양에서 틀리다. `http-contract.md:119-122`는 같은 단언을 "이것은 Redis
|
||||
저장소의 판정이다"로 좁혀 맞다.
|
||||
- **발생 조건·영향**: 매뉴얼만 읽은 개발자가 PG provider에서 효과 불명 실패 뒤 같은 키 재전송도 막힌다고 믿는다.
|
||||
그러면 트랜잭션 밖 효과(외부 호출, 메시지)를 따로 멱등하게 만들지 않는다.
|
||||
- **고치는 법**: 첫 문장을 저장소별로 나눈다. 예: "Redis 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을
|
||||
다시 돌리지 않는다. PostgreSQL 저장소를 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
|
||||
요청이 다시 실행한다(아래)."
|
||||
- **이번 커밋**(PG 항목이 이 커밋에서 생겼다). 가이드 심각도 Low · P3.
|
||||
- **증거**: E1. PG 동작 자체는 E3 — `aSameKeyClaimAfterTheFirstTransactionRolledBackItsAbandonedRecordRunsAfresh`(명령 6).
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- **watchdog 스레드의 `inheritedAccessControlContext`**: JDK 21 `Thread`는 만드는 스레드의 스택에서
|
||||
`AccessControlContext`를 잡는다(명령 9). 요청 스레드가 watchdog을 시작하면 그 스택의 ProtectionDomain(과 class
|
||||
loader)이 스레드가 사는 동안 잡힌다. README의 "pins neither … a redeployed application's loader"보다 약간 넓다.
|
||||
다만 스레드는 마지막 예약 뒤 60초 안에 끝나고, httpclient가 WAR 안에 있으면 같은 loader라 의미가 없다. httpclient를
|
||||
공유 부모 loader에 두는 배포에서만 남는다. 템플릿은 실행 jar로 배포한다. 판단하지 않았다.
|
||||
- **`ClientRuntimeRegistry.close()`의 interrupt 처리**: 닫는 스레드가 interrupt 상태면 `awaitTermination`이 바로
|
||||
예외를 내고, close는 flag만 되살린 채 정상으로 돌아온다. 그때는 "스레드를 남기지 않는다"가 성립하지 않는다.
|
||||
이전부터의 모양이고 Spring 종료 스레드는 보통 interrupt되지 않는다.
|
||||
- **배포 중 섞인 버전**: 옛 인스턴스의 TRANSITION은 lease가 지난 claim을 시작하고 새 인스턴스는 거절한다. 배포
|
||||
동안만이고 중복 실행은 없다.
|
||||
- **`docs/registries/error-codes.yaml`의 `IDEMPOTENCY_UNAVAILABLE` `log_level: WARN`**: 전송은 5xx carrier를 ERROR로
|
||||
남긴다(`ServerFailureLog`). 영역 밖이고 이전부터이며, `log_level`을 읽는 코드가 없어 규범인지 판단하지 않았다.
|
||||
- **시작 호출의 operation id가 claim과 다를 때**: Redis는 `OPERATION_CONFLICT`, PG는 시작을 적용한다. 이전부터의
|
||||
차이이고 executor는 항상 claim의 operation id를 넘긴다.
|
||||
- **in-memory fake(application-core)가 lease를 모델링하지 않음**: 시간 케이스 17개 skip은 RR-01-06 결정의 설계다.
|
||||
executor의 `LEASE_EXPIRED` → 503 매핑은 손 fake 단위 테스트(`IdempotencyExecutorTest`)와 위 탐침(명령 8)이 본다.
|
||||
|
||||
## 결론
|
||||
|
||||
- 고쳤다고 한 10개 항목은 모두 닫혔다. 회귀는 없다.
|
||||
- 두 저장소의 `LEASE_EXPIRED` 판정은 같은 시계(서버), 같은 경계(`now ≥ leaseUntil`), 같은 순서(이미 적용된
|
||||
시작의 재시도가 먼저)다. 공유 계약 31건이 실 PG·실 Redis에서 skip 없이 통과했다. executor의 503은 계약 문서와 맞다.
|
||||
- runbook의 Redis 삭제는 Lua 한 번이라 원자적이고, 실 Redis에서 블록 그대로 advanced 계정으로 돈다.
|
||||
- watchdog 유휴 종료 직후의 새 예약은 고립되지 않는다. drain 스레드 close는 join 마감과 예외 순서가 맞다.
|
||||
- 결함 5건, 모두 Minor: 이번 커밋 4건(RR6-02-01·03·04·05), 이전부터 1건(RR6-02-02, 이번 커밋이 넓힘).
|
||||
@@ -0,0 +1,194 @@
|
||||
# 03 persistence r9 리뷰 (2026-11-05)
|
||||
|
||||
대상: 커밋 `45d2a478`(r9), Base `c508b1ba`. 리뷰어 1명이 직접 봤다(하위 에이전트 없음). 결함 ID는 `RR6-03-<순번>`이다.
|
||||
|
||||
## 범위
|
||||
|
||||
### pathspec
|
||||
|
||||
```
|
||||
src/adapter/outbound/persistence-jpa src/sample-portfolio src/grpc/grpc-operation-ledger-jpa src/optional-platforms
|
||||
docs/jpa docs/manual/04-persistence.md docs/upgrade/2026-11-maturity-review.md
|
||||
```
|
||||
|
||||
`git diff c508b1ba..45d2a478 -- <pathspec>`의 15개 파일. persistence-jpa 안의 멱등성 store 변경(`IdempotencyTransitionGateway`, `PostgreSqlIdempotencyStore`, `PostgreSqlIdempotencyIntegrationTest`, README 멱등성 문단)은 02가 보므로 뺐다.
|
||||
|
||||
요구사항은 재리뷰 README 16절 r9-c 행이다. 항목은 RR4-02-01(`round4/review.md`), gRPC 버전 정규식 복사본(README 12절 r6-b), V21 주석(README 6절 r4-e 남음), r9-c가 새로 찾아 고친 가이드 오류 네 가지다.
|
||||
|
||||
판정에 필요해 함께 읽은 것:
|
||||
- Flyway 11.14.1(lockfile 버전) `PostgreSQLParser`, `Parser`, `ParserSqlScript`, `SqlScriptMetadata`, `ConfigUtils` — Gradle 캐시의 jar를 scratchpad에서 디컴파일했다.
|
||||
- `ConcurrentIndexMigrationInspector`, `PostgreSqlMigrationUpgradeContractTest`, `MigrationLockWaitTest`, `MigrationTrees`, `applied-migrations.sha256`.
|
||||
- `persistence-jpa.yml`의 `spring.flyway` 절, 직접 `Flyway.configure()`를 부르는 main 코드 5곳.
|
||||
- `.github/workflows/ci-quality-gates.yml`·`integration-main.yml`의 optional 빌드 job, `QualityConventionsPlugin`의 Spotless 설정.
|
||||
- `docs/study/postgresql-jpa-walkthrough.ko.md` §8.2(pathspec 밖, 같은 주장이 있어서).
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 적용한 기준 | 본 것 |
|
||||
| --- | --- | --- |
|
||||
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 계획(16절 r9-c) 대비 구현, 테스트가 진짜 동작을 보는가, 마이그레이션 전략, 문서 완결성, 심각도별 Issues, Declined to judge, 읽기 전용 checkout, 하위 에이전트 금지 | 네 항목이 정말 닫혔는지, 새 Flyway 대조 테스트가 주장하는 것을 실제로 지키는지 봤다. 이 문서 양식이 그 템플릿이다 |
|
||||
| `jpa-patterns` | "Migrations: Flyway·Liquibase, Hibernate auto DDL 금지", "Testing Data Access: Testcontainers로 운영과 같게" | 가이드가 안내하는 마이그레이션 모양(CIC + `.sql.conf`)을 실제 Flyway·실 PostgreSQL로 끝까지 돌려 봤다(RR6-03-01). `ddl-auto: validate` 확인 |
|
||||
| `supabase-postgres-best-practices` | `lock-short-transactions`(잠금을 짧게, 긴 트랜잭션 금지), `lock-advisory`(transaction-level과 session-level advisory lock의 차이), `query-*`의 인덱스 생성 | Flyway의 transaction-level advisory lock이 열어 둔 트랜잭션을 CIC가 기다리는 것(RR6-03-01), `lock_timeout` 상한 판정, E-문자열 escape(RR6-03-02) |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
모두 `scratchpad/rr6-03/wt`(detached `45d2a478` worktree)에서 공유 잠금(`flock …/heavy.lock`)으로 돌렸다. 괄호 안은 실행 직전 1분 부하다.
|
||||
|
||||
1. `./gradlew :adapter:outbound:persistence-jpa:test --tests '*LockWaitMigrationInspectorTest' --tests '*VersionedMigrationFilesTest' --tests '*MigrationLockWaitTest' --tests '*AppliedMigrationImmutabilityTest' --tests '*ConcurrentIndexMigrationInspectorTest' :sample-portfolio:test --tests '*SampleMigrationLockWaitTest'` (2.31) → rc=0. 71·3·2·2·4·1건, 실패 0.
|
||||
2. `applied-migrations.sha256` 대조(python, LF 정규화, `MigrationTrees.ROOTS` 네 tree) → 파일 47, 고정 47, 빠짐·남음·불일치 0.
|
||||
3. 검사기 오프라인 탐침: testFixtures 클래스로 `javac`·`java`, 입력 12개(E-문자열, 중첩 주석, dollar quote, `BEGIN ATOMIC`, 옛 `REINDEX VERBOSE` 등).
|
||||
4. `./gradlew :adapter:outbound:persistence-jpa:postgresqlMigrationLockWaitIntegrationTest` (3.25) — worktree 사본에 탐침 9개를 더했다 → rc=0, 37/37(원래 28 + 탐침). 탐침 결과:
|
||||
|
||||
| 입력(앞에 `SET LOCAL lock_timeout = '5s';`) | Flyway mixed 거부 | 검사기 트랜잭션 밖 판정 | 일치 |
|
||||
| --- | --- | --- | --- |
|
||||
| `UPDATE probe SET note = E'it\'s'; VACUUM FULL probe` | 거부 | `[]` | **불일치** (RR6-03-02) |
|
||||
| `/* outer /* inner */ VACUUM probe; */ SELECT 1` | 통과 | `[vacuum]` | 불일치(거부 쪽, Declined) |
|
||||
| `REINDEX VERBOSE SCHEMA public` | 거부 | `[reindex verbose schema]` | 일치 |
|
||||
| `CREATE INDEX CONCURRENTLY IF NOT EXISTS …` | 거부 | `[create index concurrently]` | 일치 |
|
||||
| `VACUUM "public"."probe"` | 거부 | `[vacuum]` | 일치 |
|
||||
| `CREATE TABLESPACE probe_ts LOCATION '/tmp'` | 거부 | `[create tablespace]` | 일치 |
|
||||
| `ALTER TABLE probe DETACH PARTITION probe_p CONCURRENTLY` | 통과(PG 오류) | `[]` | 일치 |
|
||||
| `CLUSTER` | 통과(PG 오류) | `[]` | 일치 |
|
||||
|
||||
그리고 SET LOCAL 없이 `INSERT … VALUES (1, E'it\'s'); ALTER TABLE probe ADD COLUMN c INT;`를 읽는 트랜잭션이 열린 채 Flyway로 적용했다 → 검사기 `[]`, Flyway는 15,018 ms 기다린 뒤 적용(상한 없음, RR6-03-02).
|
||||
5. `./gradlew -p optional-platforms ci --dry-run` → ledger의 `sharedMigrationFileSources`, `spotlessJava`, `compileIntegrationTestJava`, `spotbugsIntegrationTest`가 `ci`에 있다. 정본이 깨지면 optional `ci`(PR마다 도는 job)에서 컴파일로 잡힌다.
|
||||
6. `./gradlew -p optional-platforms :grpc:grpc-operation-ledger-jpa:compileIntegrationTestJava :grpc:grpc-operation-ledger-jpa:spotlessCheck :grpc:grpc-operation-ledger-jpa:spotbugsIntegrationTest` 두 번 (4.60) → 둘 다 rc=0, 두 번째는 네 태스크 모두 UP-TO-DATE.
|
||||
7. 정본 `VersionedMigrationFiles`에 포맷이 틀린 메서드를 넣고 같은 명령 (4.35) → `sharedMigrationFileSources`·`compileIntegrationTestJava`가 다시 돌았다(정본을 따라온다). `spotlessJavaCheck`는 `build/generated/sources/sharedMigrationFiles/…/VersionedMigrationFiles.java`를 위반으로 댔다. 이어서 `-p optional-platforms :grpc:grpc-operation-ledger-jpa:spotlessApply` (4.77) → rc=0, 정본 diff 변화 없음 → `spotlessCheck` 다시 실패(RR6-03-04). 정본은 원래대로 되돌렸다.
|
||||
8. `./gradlew -p optional-platforms :grpc:grpc-operation-ledger-jpa:integrationTest` (3.56) → rc=0, 46/46. lock-wait IT는 `inVersionOrder` 순서대로 V002·V003 두 건.
|
||||
9. CIC 단독 마이그레이션 탐침(같은 IT lane, 4.11): `CREATE INDEX CONCURRENTLY ix_probe_note ON probe (note);` 하나만 든 V1을 Flyway 기본 설정으로 적용 → 10분 넘게 멈췄다. 컨테이너에서 `pg_stat_activity`·`pg_locks`를 보니 Flyway 연결(pid 62)이 `idle in transaction`으로 advisory `ExclusiveLock`을 들고 있고, CIC(pid 63)는 `Lock/virtualxid` `ShareLock`을 기다렸다(granted=f). `pg_terminate_backend(63)`로 끝냈다.
|
||||
10. 두 번째 배포 탐침(같은 lane, 3.69): V1(테이블·인덱스)을 적용한 뒤 V2를 적용한다. 20초가 지나면 감시자가 `pg_cancel_backend`로 취소한다 → rc=0.
|
||||
|
||||
| V2 | `.sql.conf` | Flyway PostgreSQL 잠금 | 결과 |
|
||||
| --- | --- | --- | --- |
|
||||
| `CREATE INDEX CONCURRENTLY` | `executeInTransaction=false`(가이드 모양) | 기본(transactional) | **멈춤** → 20초에 취소, version 1 |
|
||||
| `CREATE INDEX CONCURRENTLY` | 없음 | 기본 | **멈춤** |
|
||||
| `CREATE INDEX CONCURRENTLY` | `executeInTransaction=false` | `flyway.postgresql.transactional.lock=false` | 20 ms에 적용, version 2 |
|
||||
| `DROP INDEX CONCURRENTLY` | `executeInTransaction=false` | 기본 | 19 ms에 적용 |
|
||||
| `REINDEX INDEX CONCURRENTLY` | `executeInTransaction=false` | 기본 | **멈춤** |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- IntelliJ 가져오기는 실행하지 않았다. Sync 방식의 IDE 영향은 정적 판단이다(Declined).
|
||||
- staging·prod의 "deployment-owned migration" 도구가 저장소에 없다. RR6-03-01은 Flyway API·Spring Boot 기본값으로만 확인했다(Flyway CLI 기본값도 같다는 것은 E0).
|
||||
- PostgreSQL 16.15 외 버전.
|
||||
- 전체 `check`·`ci`·`mainCheck`·`integrationCheck`는 돌리지 않았다(총괄 게이트 몫). 위 좁힌 태스크만 돌렸다.
|
||||
|
||||
## 항목 재확인
|
||||
|
||||
| ID | 판정 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| RR4-02-01 | 닫힘 | Flyway 11.14.1 `PostgreSQLParser#detectCanExecuteInTransaction`이 PG 12 이상에서 쓰는 정규식 6개와 `LockWaitMigrationInspector.java:154-161`이 같다(디컴파일 대조). 판정 규칙(`.sql.conf`가 있으면 그것, 없으면 문장 판정)은 `ParserSqlScript.executeInTransaction()`과 같다(`:243-247`). `VACUUM FULL` + `SET LOCAL`은 "cannot run in a transaction … keep it out of migrations"로 거부(`:275-280`, 명령 1). `REINDEX (CONCURRENTLY)`(`:82-83`), `GRANT … REFERENCES ON`(`:117`), `executeInTransaction=FALSE`(`:378-399`, Flyway `ConfigUtils.removeBoolean`과 같은 판정) 모두 고쳐졌다. 가이드 `docs/jpa/migration-guide.md:55-69`. 남은 lexer 빈틈은 이전부터의 RR6-03-02, 업그레이드 감시의 빈틈은 RR6-03-03 |
|
||||
| gRPC 버전 정규식 복사본 | 닫힘 | `GrpcOperationLedgerMigrations.java:35-39`가 `VersionedMigrationFiles.inVersionOrder`를 쓰고 자체 정규식·`version()`이 지워졌다. `build.gradle:27-33` Sync. 정본을 바꾸면 optional 빌드가 따라오고(명령 7), 두 번째 실행은 UP-TO-DATE(명령 6), optional `ci`가 컴파일한다(명령 5). 새 `inVersionOrder`는 Flyway처럼 수로 비교하고 없는 자리를 0으로 보며 같은 버전을 거부한다(`VersionedMigrationFiles.java:54-98`, 테스트 2건). 부작용: RR6-03-04 |
|
||||
| V21 주석 | 닫힘 | `V21__outbox_aggregate_sequence.sql:10`의 `JpaOutboxStore#nextSequence`가 있다(`JpaOutboxStore.java:133`). sha256 `applied-migrations.sha256:43`이 파일과 같다(명령 2) |
|
||||
| 가이드 "CONCURRENTLY는 Flyway가 트랜잭션으로 감싼다" (r9-c가 새로 찾아 고침) | 부분 | 가이드 `:98-104`는 고쳤다. 같은 주장이 `ConcurrentIndexMigrationInspector.java:10-14`, `GrpcOperationLedgerMigrationLockWaitIT.java:32-33`, study 문서 `:1338-1344`에 남았다(RR6-03-05). 고친 문장이 안내하는 길(CIC·`REINDEX … CONCURRENTLY`를 자기 마이그레이션에)은 Flyway 기본 설정에서 멈춘다(RR6-03-01) |
|
||||
| 동결 목록(`RELEASED_BEFORE_THE_RULE`) | 맞음 | `MigrationLockWaitTest.java:79-99`가 두 방향으로 통과(명령 1). 이번 커밋에서 목록·마이그레이션 파일 변경 없음. `SampleMigrationLockWaitTest`는 `isEqualTo(V8)`로 통과 |
|
||||
| sha256 고정 목록 | 맞음 | 47/47 일치(명령 2), `AppliedMigrationImmutabilityTest` 2/2 |
|
||||
|
||||
## 결함
|
||||
|
||||
### RR6-03-01 · Important · CIC·`REINDEX … CONCURRENTLY` 마이그레이션은 Flyway 기본 설정에서 끝나지 않는다 — 가이드가 그 길을 안내한다
|
||||
|
||||
- **위치**:
|
||||
- 안내: `docs/jpa/migration-guide.md:98-114`("Concurrent index builds": CIC 마이그레이션 + `executeInTransaction=false`), `:63-65`(r9: `REINDEX TABLE|INDEX CONCURRENTLY`는 `executeInTransaction=false`), `:101-104`(r9: 동반 설정을 늘 쓴다), `LockWaitMigrationInspector.java:286-290`(r9 메시지: "put create index concurrently in a migration of its own").
|
||||
- 설정: `src/adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml:125-139`(`spring.flyway`에 `postgresql.transactional-lock` 없음). 직접 만드는 Flyway: `IdempotencySchemaStream.java:85`, `NotificationSchemaStream.java:58`, `MessagingInboxSchemaStream.java:77`, `SamplePostgreSqlPersistenceConfig.java:41`, `SchemaTenantMigrationOrchestrator.java:51`.
|
||||
- **무엇이 틀렸나**:
|
||||
- Flyway 11.14.1은 PostgreSQL에서 기본으로 transaction-level advisory lock을 쓴다.
|
||||
- 그 잠금을 든 연결은 migrate가 끝날 때까지 트랜잭션을 열어 둔다(`idle in transaction`).
|
||||
- `CREATE INDEX CONCURRENTLY`와 `REINDEX … CONCURRENTLY`는 먼저 시작한 트랜잭션이 모두 끝나기를 기다린다(virtualxid 대기).
|
||||
- 그래서 CIC는 Flyway 자신의 잠금 트랜잭션을 기다리고, Flyway는 CIC를 기다린다. 둘 다 끝나지 않는다.
|
||||
- 이 대기에는 상한이 없다. `executeInTransaction=false` 파일에는 `SET LOCAL lock_timeout`을 둘 수 없다.
|
||||
- 명령 10: 가이드 모양 그대로(`.sql.conf` 포함) 두 번째 배포가 멈췄다. 같은 파일이 session-level 잠금(`flyway.postgresql.transactional.lock=false`)에서는 20 ms에 적용됐다. `DROP INDEX CONCURRENTLY`는 멈추지 않는다.
|
||||
- **발생 조건·영향**:
|
||||
- 가이드대로 운영 중인 큰 테이블에 CIC 마이그레이션으로 인덱스를 더하는 파생 서비스. 템플릿 자체에는 지금 그런 파일이 없다.
|
||||
- dev·test(기동 때 migrate)에서는 앱 기동이 멈춘다. 배포 마이그레이션도 Flyway 기본값이면 배포가 끝나지 않는다.
|
||||
- 그동안 CIC가 테이블에 `SHARE UPDATE EXCLUSIVE`를 들어 그 테이블의 다른 DDL·autovacuum이 막힌다. Flyway advisory lock 때문에 다른 인스턴스의 migrate도 줄을 선다.
|
||||
- 실패가 아니라 멈춤이라 알람과 롤백이 늦다. 취소하면 INVALID 인덱스가 남는다.
|
||||
- **테스트가 못 본 이유**: CIC 마이그레이션을 Flyway로 끝까지 돌린 테스트가 없다. `PostgreSqlMigrationUpgradeContractTest.java:72-81`은 CIC를 JDBC autocommit으로만 돌린다. r9의 IT는 CIC를 `SET LOCAL` 옆에 두어 Flyway가 파싱 단계에서 거부하는 것만 본다(`PostgreSqlMigrationLockWaitIntegrationTest.java:129-188`).
|
||||
- **고치는 법** (하나를 고른다):
|
||||
- (권장) Flyway의 PostgreSQL 잠금을 session-level로 바꾼다.
|
||||
- module-defaults에 `spring.flyway.postgresql.transactional-lock: false`(Spring Boot 4.0.8 속성, 기본값 없음 → Flyway 기본 true).
|
||||
- 직접 만드는 Flyway 5곳에 같은 값(`flyway.postgresql.transactional.lock=false`)을 공용 helper 하나로 넣는다.
|
||||
- 가이드 "Who may change the schema"·"Concurrent index builds"에 배포 마이그레이션 도구도 같은 값을 써야 한다고 적는다.
|
||||
- session-level advisory lock은 transaction-mode PgBouncer 뒤에서 깨진다. 템플릿은 Hikari 직접 연결이라는 전제를 같은 곳에 적는다.
|
||||
- RED: 실 PG IT 하나. 템플릿 설정으로 만든 Flyway가 V1 적용 뒤 `.sql.conf`가 있는 CIC V2를 상한(예: 30초) 안에 적용하는지 본다. 지금 설정에서는 상한에 걸려 실패한다.
|
||||
- (대안) CIC·`REINDEX … CONCURRENTLY`를 `VACUUM FULL`처럼 "마이그레이션에 두지 않고 운영 절차로" 한다. 검사기가 거부하고, 가이드 "Concurrent index builds"를 runbook 절차로 바꾸고, `ConcurrentIndexMigrationInspector`를 정리한다.
|
||||
- **이번 커밋/이전부터**: 이전부터(가이드 "Concurrent index builds"). 이번 커밋이 같은 길을 더 안내했다(가이드 `:63-65`, `:101-104`, 검사기 메시지 `:286-290`).
|
||||
- **증거**: E3 — 명령 9·10(`pg_stat_activity`·`pg_locks`로 대기 관계 확인). Flyway 잠금 동작은 E1(디컴파일한 `PostgreSQLParser`·Spring Boot `spring-configuration-metadata.json`의 `spring.flyway.postgresql.transactional-lock`).
|
||||
|
||||
### RR6-03-02 · Minor · `E'…\'…'` 문자열이 검사기의 문자열 판정을 어긋나게 해, 뒤의 잠금 문장과 트랜잭션 밖 문장을 못 본다
|
||||
|
||||
- **위치**: `LockWaitMigrationInspector.java:433-471`(`withoutCommentsAndLiterals`, `'` 처리 `:446-458`). `:370-372` `normalized`가 이 결과를 잠금 판정과 트랜잭션 밖 판정에 함께 쓴다.
|
||||
- **무엇이 틀렸나**:
|
||||
- PostgreSQL과 Flyway는 `E'it\'s'`의 `\'`를 문자열 안의 따옴표로 읽는다(Flyway `Parser.readToken`의 `E'` 분기).
|
||||
- 검사기는 `''`만 escape로 읽는다. 그래서 `\'`에서 문자열을 닫는다.
|
||||
- 그 뒤 `s'`의 따옴표가 새 문자열을 연다. 다음 따옴표까지(없으면 파일 끝까지)가 문자열로 지워진다.
|
||||
- 명령 4: `INSERT INTO probe (id, note) VALUES (1, E'it\'s');` 다음 줄의 `ALTER TABLE probe ADD COLUMN c INT;`를 검사기는 못 봤다(`[]`). 실 PG에서 읽는 트랜잭션이 열린 채 Flyway로 적용하니 15,018 ms를 기다린 뒤 적용됐다.
|
||||
- 같은 이유로 `UPDATE … E'it\'s'; VACUUM FULL probe;`를 검사기는 트랜잭션 안으로 판정했다. Flyway는 mixed로 거부했다.
|
||||
- **발생 조건·영향**: 시드·데이터 마이그레이션이 E-문자열에 `\'`를 쓰고 그 뒤에 잠금 문장을 둔 파일. 검사기가 막으려는 상한 없는 잠금 대기가 그대로 통과한다. 모양이 드물어 Minor다.
|
||||
- **고치는 법**: `'` 바로 앞 글자가 `e`/`E`이고 그 앞이 식별자 글자가 아니면 E-문자열로 읽어 `\` 다음 글자를 건너뛴다(`\\`, `\'`). RED: 위 두 입력을 `LockWaitMigrationInspectorTest`에 더한다. 두 번째 입력은 IT의 Flyway 대조 목록(`:129-153`)에도 더한다.
|
||||
- **이번 커밋/이전부터**: 이전부터(RR3-02-01 때의 함수). 이번 커밋의 트랜잭션 밖 판정도 같은 출력을 써서 함께 틀린다.
|
||||
- **증거**: E3 — 명령 3·4.
|
||||
|
||||
### RR6-03-03 · Minor · "Flyway를 올리면 IT가 실패한다"는 주장이 Flyway 목록에 문장이 더해지는 경우를 못 본다
|
||||
|
||||
- **위치**: `LockWaitMigrationInspector.java:151-152`, `PostgreSqlMigrationLockWaitIntegrationTest.java:45-50`·`:129-153`, `docs/jpa/migration-guide.md:87-88`.
|
||||
- **무엇이 틀렸나**:
|
||||
- Javadoc은 `postgresqlMigrationLockWaitIntegrationTest`가 목록을 Flyway에 묶어 두어 "목록을 바꾸는 Flyway 업그레이드는 거기서 실패한다"고 한다. 가이드도 "the statements it names are exactly those Flyway refuses"라고 한다.
|
||||
- IT는 고정 문장 21개에서만 검사기와 Flyway를 대조한다. Flyway가 목록에 새 문장을 더하면, 그 문장이 21개 안에 없는 한 아무 테스트도 실패하지 않는다.
|
||||
- 지금 목록의 일부도 대조에 없다: `CREATE`/`DROP TABLESPACE`, `CREATE`/`DROP SUBSCRIPTION`, `REINDEX SYSTEM`, 옛 문법 `REINDEX VERBOSE SCHEMA`. 명령 4로 TABLESPACE·`REINDEX VERBOSE`는 지금 일치함을 확인했다.
|
||||
- 이 lane은 `integrationCheck`(main push)에서만 돈다. Flyway를 올리는 PR의 `ci`는 이 대조를 돌리지 않는다.
|
||||
- **발생 조건·영향**: Flyway가 트랜잭션 밖 목록에 문장을 더하는 업그레이드. 그 문장과 `SET LOCAL`이 든 마이그레이션을 검사기가 통과시킨다. 기본 `mixed=false`에서는 배포 때 Flyway가 거부하고, `mixed=true`에서는 상한 없이 돈다. 검사기 사본이 조용히 Flyway와 갈라진다.
|
||||
- **고치는 법**:
|
||||
- persistence-jpa `test`(PR `ci`에서 도는 lane)에 테스트 하나를 둔다. `org.flywaydb.database.postgresql.PostgreSQLParser`의 static `Pattern` 필드를 reflection으로 읽어 `pattern()` 집합을 11.14.1 기준 값으로 고정한다. 다르면 "Flyway의 트랜잭션 밖 목록이 바뀌었다: `FLYWAY_OUTSIDE_A_TRANSACTION`과 IT 대조 목록을 갱신하라"로 실패한다. `flyway-database-postgresql`은 이미 testRuntimeClasspath에 있다(lockfile).
|
||||
- IT 대조 목록에 위 네 대안을 더한다.
|
||||
- Javadoc `:151-152`·가이드 `:87-88`을 실제로 지키는 범위로 고친다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋.
|
||||
- **증거**: E1 — 디컴파일한 `PostgreSQLParser`와 IT 대조 목록 비교, lane 단계(`integration-main.yml`). E3 — 명령 4.
|
||||
|
||||
### RR6-03-04 · Minor · optional 빌드의 Spotless가 Sync로 가져온 사본을 검사하고, 안내한 `spotlessApply`는 아무것도 고치지 못한다
|
||||
|
||||
- **위치**: `src/grpc/grpc-operation-ledger-jpa/build.gradle:27-33`. Spotless 대상은 기본값이다(`src/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java:46-51`, target 미지정 → 모든 source set).
|
||||
- **무엇이 틀렸나**:
|
||||
- Sync 출력이 integrationTest source set의 소스 폴더가 됐다. Spotless 기본 대상은 모든 source set이라 `build/generated/sources/sharedMigrationFiles/…/VersionedMigrationFiles.java`도 검사한다(명령 5의 `spotlessJava`가 Sync에 의존).
|
||||
- 정본의 포맷이 틀리면 optional 빌드는 생성 사본 경로를 대며 `spotlessApply`를 하라고 한다.
|
||||
- 명령 7: `-p optional-platforms …:spotlessApply`는 rc=0으로 끝났지만 생성 사본만 고쳤다. 정본은 그대로였다. 다음 Sync가 사본을 되돌려 `spotlessCheck`가 다시 실패했다.
|
||||
- **발생 조건·영향**: 정본을 고치다 포맷을 어긴 개발자가 optional 빌드만 돌릴 때. 안내대로 해도 고쳐지지 않는다. 주 빌드의 persistence-jpa `spotlessCheck`가 같은 PR에서 정본 경로로 잡으므로 피해는 혼란과 이중 보고다.
|
||||
- **고치는 법**: ledger `build.gradle`에서 Sync 출력을 Spotless 대상에서 뺀다(예: `spotless { java { targetExclude('build/generated/sources/sharedMigrationFiles/**') } }`). 정본의 포맷은 주 빌드가 맡는다고 그 옆 주석(`:19-26`)에 적는다. RED: 정본에 포맷 위반을 넣으면 지금은 optional `spotlessCheck`가 사본 경로로 실패한다. 고친 뒤에는 통과하고, 주 빌드의 persistence-jpa `spotlessCheck`만 정본 경로로 실패한다.
|
||||
- **이번 커밋/이전부터**: 이번 커밋.
|
||||
- **증거**: E2 — 명령 5·6·7.
|
||||
|
||||
### RR6-03-05 · Minor · "Flyway는 마이그레이션을 늘 트랜잭션으로 감싼다"는 설명이 가이드 밖 세 곳에 남았다
|
||||
|
||||
- **위치**: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/migration/ConcurrentIndexMigrationInspector.java:10-14`, `src/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java:32-33`, `docs/study/postgresql-jpa-walkthrough.ko.md:1338-1344`(pathspec 밖).
|
||||
- **무엇이 틀렸나**:
|
||||
- r9-c는 가이드의 같은 오류만 고쳤다(가이드 `:55-63`, `:100-104`: Flyway는 CIC가 든 파일을 스스로 트랜잭션 밖에서 돌린다).
|
||||
- testkit Javadoc과 study 문서는 아직 이렇게 말한다. "Flyway가 트랜잭션으로 감싸서 CIC 마이그레이션은 첫 배포에서 실패한다(좋은 경우)." "다른 문장과 섞이면 그것들은 커밋되고 인덱스만 안 된다(나쁜 경우)."
|
||||
- Flyway 11.14.1에서 CIC만 든 파일은 트랜잭션 밖에서 돈다(그리고 RR6-03-01 때문에 멈춘다, 명령 9·10). 섞인 파일은 기본 `mixed=false`에서 아무것도 실행하기 전에 거부된다(명령 4). 두 설명이 모두 틀렸다.
|
||||
- gRPC ledger IT Javadoc은 "마이그레이션을 Flyway가 돌리는 대로, 한 트랜잭션에서 돌린다"고 한다. Flyway가 트랜잭션 밖에서 돌릴 파일(CIC 등)은 IT가 다르게 돌린다. JDBC 트랜잭션 안에서 25001로 실패하고, 실패 메시지는 "SET LOCAL을 넣어라"라고 한다. 그 안내를 따르면 Flyway가 mixed로 거부한다.
|
||||
- **발생 조건·영향**: 읽는 사람이 Flyway 동작을 잘못 배운다. 가이드와 testkit 설명이 서로 다르다. ledger에 CIC 마이그레이션을 더하는 사람은 따를 수 없는 안내를 받는다.
|
||||
- **고치는 법**:
|
||||
- 두 설명을 가이드 `:55-65`·`:98-104`와 같게 고친다(RR6-03-01에서 고른 방법을 반영한 뒤).
|
||||
- ledger IT Javadoc은 이렇게 고친다. "지금 파일들(`SET LOCAL` + 트랜잭션 안 문장)은 Flyway도 한 트랜잭션에서 돌린다. Flyway가 트랜잭션 밖에서 돌릴 파일은 여기서 판정하지 못하니 이 테스트에 예외로 적는다." SQLState가 25001이면 실패 메시지에 같은 안내를 덧붙인다.
|
||||
- **이번 커밋/이전부터**: 이전부터. r9-c가 가이드만 고치고 같은 주장의 다른 사본은 남겼다.
|
||||
- **증거**: E1(세 문서·코드), E3(명령 4의 mixed 거부, 명령 10의 CIC 단독 배포).
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- **검사기의 10단어 셈이 Flyway와 다르다.** 검사기는 괄호 안 단어와 식별자도 센다(`:317-355`). Flyway는 괄호 밖 키워드만 센다. 판정 단어가 문장의 첫 4개 키워드 안에 있고, 그 앞에 오는 괄호(`REINDEX` 옵션)는 많아야 6단어라 결과가 달라지는 입력이 없다. Javadoc `:294-296`의 "the way Flyway finds them"도 그래서 결함으로 올리지 않았다.
|
||||
- **중첩 블록 주석.** `/* outer /* inner */ VACUUM probe; */`를 검사기는 트랜잭션 밖으로 판정했다(명령 4). PostgreSQL과 Flyway는 중첩을 센다. 거부 쪽 오판이고 실제 마이그레이션에서 보기 힘든 모양이다. 고친다면 RR6-03-02와 같은 함수다.
|
||||
- **`.sql.conf`의 `executeInTransaction=true` + `SET LOCAL` + `VACUUM FULL`.** 검사기는 통과시킨다(`:243-248`). Javadoc `:61-63`은 `VACUUM FULL`을 늘 거부한다고 읽힌다. 그러나 PostgreSQL이 배포 때 25001로 거부해 잠금 대기가 생기지 않고, 이 조합을 쓸 이유가 없는 입력이다.
|
||||
- **`REINDEX (CONCURRENTLY 'false')`.** 문자열 값이 `''`로 지워져 동시로 판정된다. PostgreSQL이 받는 값이지만 쓰는 사람을 상정하기 어렵다.
|
||||
- **`.sql.conf`의 placeholder·환경 변수.** Flyway는 `${…}`를 치환하고 검사기는 `IllegalStateException`으로 실패한다(`:394-398`). 거부 쪽이다.
|
||||
- **Sync 방식과 IDE.** 생성 폴더는 Gradle을 한 번 돌리기 전에는 없다. 생성 사본을 IDE에서 고치면 다음 Sync가 덮는다. 생성 소스의 일반적인 성질이고, IntelliJ 기본(Gradle에 빌드 위임)에서는 Sync가 먼저 돈다. 실행으로 확인하지 않았다.
|
||||
- **persistence-jpa 디렉터리가 없는 파생 서비스.** ledger의 integrationTest가 컴파일되지 않는다. 문서화된 capability 제거는 `runtimeOnly` 줄을 지우는 것이지 디렉터리를 지우는 것이 아니다.
|
||||
- **V002 주석 "Flyway runs each migration in a transaction"**(`V002__index_grpc_operation_ledger_finished_rows.sql:11`). RR6-03-05와 같은 오류다. 다만 적용된 마이그레이션이라 고치면 checksum이 바뀐다. 이 파일의 결론(빈 테이블이라 일반 인덱스)은 맞다. 고칠지는 소유자 판단이다.
|
||||
- **`MessagingMigrationNamespaceTest`의 정규식 `V(\d+)__.+\.sql`.** 05 영역이다. 소수 버전을 실패시키는 쪽이라 조용히 빠지지 않는다.
|
||||
- **Flyway `mixed=true`·전역 `executeInTransaction=false`를 쓰는 서비스.** 검사기 Javadoc `:63-65`와 가이드 `:62`에 가정으로 적혀 있다.
|
||||
|
||||
## 결론
|
||||
|
||||
결함 5건: Important 1건, Minor 4건. 이번 커밋 2건(RR6-03-03, RR6-03-04), 이전부터 3건(RR6-03-01, RR6-03-02, RR6-03-05). RR6-03-01은 이전부터지만 이번 커밋이 같은 길을 더 안내했다.
|
||||
|
||||
- r9-c가 맡은 세 항목(RR4-02-01, gRPC 버전 정규식 복사본, V21 주석)은 닫혔다. 검사기의 Flyway 목록은 11.14.1과 같다. 동결 목록과 sha256 목록도 맞다.
|
||||
- r9-c가 새로 고친 가이드 오류는 부분 닫힘이다(RR6-03-05).
|
||||
- 가장 큰 문제는 RR6-03-01이다. 가이드가 안내하는 CIC 마이그레이션이 Flyway 기본 설정에서 끝나지 않는다. 고치기 전에 소유자가 방법(session-level 잠금 또는 운영 절차로 이동)을 정해야 한다.
|
||||
@@ -0,0 +1,169 @@
|
||||
# 04 build-logic r9 리뷰 (2026-11-05)
|
||||
|
||||
> 대상: `c508b1ba..45d2a478`의 r9-d 묶음. 실패를 막지 못하는 workflow 명령, 실행되지 않는 줄의 `cd`, 실패 메시지,
|
||||
> 짧은 플래그 묶음, httpclient 장애 주입 lane 중복 실행 제거.
|
||||
|
||||
## 범위
|
||||
|
||||
### pathspec
|
||||
|
||||
```
|
||||
src/build-logic src/build.gradle src/adapter/outbound/httpclient/build.gradle .github AGENTS.md CLAUDE.md
|
||||
src/README.md docs/upgrade/2026-11-maturity-review.md
|
||||
```
|
||||
|
||||
`git diff c508b1ba..45d2a478 -- <pathspec>`: 11개 파일, +1985 −330. `.github`와 `src/build.gradle`은 이번 커밋에서 바뀌지 않았다. 새 `ShellScript.java`(1213줄)와 `WorkflowGradleInvocations.java`(778줄)는 diff가 아니라 HEAD 전체를 읽었다.
|
||||
|
||||
### 불러온 스킬과 적용한 기준
|
||||
|
||||
| 스킬 | 기준 | 본 것 |
|
||||
|---|---|---|
|
||||
| `superpowers:requesting-code-review` | 계획(README 16절 r9-d 주장)과 구현이 맞는가, 테스트가 실제 동작을 보는가, 심각도 보정, Declined to judge, 읽기 전용(별도 worktree) | r9-d 항목마다 닫힘 여부, 테스트가 주장하는 고정 범위(RR6-04-02), 결함마다 실행 증거 |
|
||||
| `ci-cd-and-automation` | "No gate can be skipped", 레드 플래그 "CI failures ignored or silenced" | 검사가 단계를 실행으로 세는데 실제로는 돌지 않거나 실패가 삼켜지는 모양(거짓 통과). `mainCheck`에서 뺀 httpclient lane이 다른 단계에서 실제로 도는지 |
|
||||
| `codebase-design` | 깊은 모듈, seam은 실제 adapter와 맞물려 검증되는가("One adapter means a hypothetical seam"), 인터페이스가 테스트 표면인가 | `ShellScript.commands(script, dir, options)` 인터페이스는 작고 `WorkflowGradleInvocations.read`로 테스트된다. 반면 Gradle 명령줄 판독은 Gradle 파서의 손 복사본인데 실행 중인 Gradle과 맞대는 계약 테스트가 두 모양뿐이다(RR6-04-02) |
|
||||
|
||||
### 실행한 명령과 결과
|
||||
|
||||
모든 실행은 `git worktree add --detach <scratchpad>/rr6-04/wt 45d2a478`에서 했다. Gradle은 공유 `heavy.lock`으로 감쌌다.
|
||||
|
||||
| 명령 | 결과 | 직전 부하(1분) |
|
||||
|---|---|---|
|
||||
| `./gradlew :mainCheck --dry-run` | rc=0, 계획에 `httpClientFailureInjectionTest` 0회 | 3.89 |
|
||||
| `./gradlew :integrationCheck --dry-run` | rc=0, 계획에 `:adapter:outbound:httpclient:httpClientFailureInjectionTest` 1회 | 3.89 |
|
||||
| `./gradlew :verifyStrictLaneStages --dry-run` / `-p optional-platforms …` | rc=0 / rc=0, 둘 다 "every strict lane is in an executed stage" | 3.79 |
|
||||
| `./gradlew -p build-logic test --tests 'dev.caskeleton.buildlogic.strictlane.*'` | rc=0, 76개 통과, 실패·건너뜀 0 | 4.00 |
|
||||
| Gradle 9.0.0·9.2.0·9.7.1 `gradle --help` | 옵션 표 대조: 9.0.0과 판독기 표가 정확히 같음. 9.2.0에 `--task-graph`, 9.7.1에 `--console-unicode`·`--develocity-url`·`--develocity-plugin-version`·`--non-interactive`·`--isolated-projects` 추가 | 3.80 |
|
||||
| 임시 프로젝트(`ci` 태스크가 파일을 씀)에서 9.0.0·9.2.0 `gradle --no-daemon -q :ci --task-graph` | 9.0.0 rc=1(옵션 모름), 9.2.0 rc=0·작업 미실행 | 2.98 |
|
||||
| 같은 프로젝트에서 9.0.0 `:ci -v`, `:ci --version`, `-v :ci`, `:ci --help`, `:ci -h`, `:ci --status`, `:ci -V` | `-V`만 작업 실행. 나머지 여섯은 rc=0·작업 미실행 | 5.20 |
|
||||
| 판독기 probe: HEAD의 `ShellScript.java`·`WorkflowGradleInvocations.java`를 scratchpad로 꺼내 `javac`로 따로 컴파일하고 사례 workflow 12개를 읽힘 | 결과는 결함마다 적었다 | — |
|
||||
| 같은 probe로 이 repo의 workflow 15개 | run 스크립트 104개 파싱 실패 0. 단계 명령 11개 모두 COUNTED | — |
|
||||
| `c508b1ba`의 판독기와 HEAD 판독기를 같은 workflow 15개에 | 단계 명령 11개 판정 같음. 다른 것은 단계가 아닌 명령: task 단어 6개(`-P…=${{ matrix.x }}`가 한 단어로 읽힘)와 미집계 3개(`for`·명령 치환 안) | — |
|
||||
| `bash -e`로 가짜 `gradlew`(호출을 기록하고 exit 1)를 부르는 스크립트 13개 | 결함마다 적었다 | — |
|
||||
| GitHub 문서(workflow syntax의 shell 표·exit code 절·`needs` 절, container 문서) | 기본 셸: Linux·macOS `bash -e {0}`, `shell: bash`는 `bash --noprofile --norc -eo pipefail {0}`, Windows는 `pwsh`, container 안은 `sh` | — |
|
||||
|
||||
### 못 본 것
|
||||
|
||||
- 실제 GitHub runner 실행, pwsh 실행(이 환경에 pwsh가 없다).
|
||||
- `--stop`: 같은 Gradle 버전의 다른 세션 데몬을 멈추므로 실행하지 않았다(Gradle `--help` 설명과 코드 경로로만 판단).
|
||||
- `-p build-logic check` 전체와 javadoc: strictlane 테스트만 돌렸다.
|
||||
- README 16절의 "run 스크립트 253개" 코퍼스: 이 repo의 104개만 다시 파싱했다.
|
||||
|
||||
## 항목 재확인
|
||||
|
||||
| ID | 판정 | 근거 |
|
||||
|---|---|---|
|
||||
| README 15절 남음: `\|\| true`, pipefail 없는 `\| tee`, `if ./gradlew ci; then` | 닫힘 | `ShellScript.java:953-998`. 테스트 `gradlewWhoseFailureIsHandledOrDroppedDoesNotCountAndSaysWhy`, `gradlewThatRunsOnlyUnderAConditionOrInALoopOrFunctionDoesNotCount`, TestKit `aStageCalledOnlyInShapesThatCannotFailTheStepFailsNamingWhy` |
|
||||
| RR5-02-02 `&`, `false && cd src && ./gradlew ci` | 닫힘 | `ShellScript.java:566-570`, `:959-979`. 테스트 `gradlewInAnAndListCountsOnlyWhenTheListIsTheScriptsLastCommand`. `bash -e` probe(`false && ./gradlew :ci` / `echo done`)는 rc=0·호출 0이고 판독기는 세지 않는다 |
|
||||
| RR5-02-01 heredoc·부르지 않은 함수·여러 줄 문자열·`\;` 뒤의 `cd` | 닫힘 | `ShellScript.java:290-303`(heredoc 본문), `:663-674`·`:784-791`(함수 정의), `:332-334`(여러 줄 문자열), `:318-323`(이스케이프). 테스트 `aCdTheShellDoesNotRunThereIsNotFollowed`, `aCdInAFunctionBodyIsNotFollowedAndTheCommandsAfterItDoNotCount` |
|
||||
| RR5-02-03 다른 빌드로 읽힌 명령을 실패 메시지에 | 닫힘 | `StrictLaneStagesPlugin.java:200-220`, `WorkflowGradleInvocations.java:152-160`. TestKit `aStageCalledForAnotherBuildIsNamedWithThatBuildInTheFailure`(`scr`, `src/src`) |
|
||||
| `-mx` 같은 짧은 플래그 묶음 | 닫힘 | `WorkflowGradleInvocations.java:696-760`. 값 옵션·플래그 표가 9.0.0 `--help`와 같다. 작업 없이 끝나는 플래그는 별도 결함 RR6-04-01 |
|
||||
| "Gradle 9.0 파서 동작을 TestKit으로 고정" | 부분 | `StrictLaneStagesFunctionalTest.java:564-606`은 `-qm`·`-mx` 두 모양만 고정한다 → RR6-04-02 |
|
||||
| `shell:` 기본값·`defaults.run.shell` | 부분 | Linux·macOS 기본과 `shell: bash`·`sh`, job·workflow `defaults.run.shell`은 맞게 읽는다(probe `10-defaults-shell`). Windows 기본 pwsh를 bash로 읽는다 → RR6-04-04 |
|
||||
| httpclient 장애 주입 lane 두 번 실행 | 닫힘 | `src/adapter/outbound/httpclient/build.gradle:230-242`. `:mainCheck --dry-run` 0회, `:integrationCheck --dry-run` 1회. `.github/workflows/integration-main.yml:173-176`의 `integration-check`가 main push·nightly에 `:integrationCheck`를 돌리고 판독기가 COUNTED로 읽는다. 문서(`docs/upgrade/…:236`, `docs/capability-status.md:38`)도 같다 |
|
||||
| 새로 찾아 고친 것(`$(( ))`, `help --task ci`, `${{ }}` 안 공백, `-x=b`) | 닫힘 | 테스트 `aScriptWithArithmeticIsReadAsShellAndItsLastGradlewCounts`, `bundledShortOptionsAreReadTheWayGradleReadsThem`. 실제 workflow 비교에서 `${{ }}`가 한 단어로 읽힌다 |
|
||||
| "실제 workflow 판독 전후 같음" | 확인 | 단계 명령 11개 판정이 `c508b1ba`와 같다 |
|
||||
|
||||
## 결함
|
||||
|
||||
### RR6-04-01 · 작업을 실행하지 않고 끝나는 Gradle 옵션을 실행으로 센다
|
||||
|
||||
- 심각도: Minor (가이드 Low · P2)
|
||||
- 위치: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java:73-83`(`GRADLE_FLAGS`), `:728-744`(묶음 안의 글자), `:752-759`(`m`·`dry-run`만 계획 전용으로 본다)
|
||||
- 무엇이 틀렸나: Gradle 9.0은 `-v`·`--version`, `-h`·`-?`·`--help`, `--status`를 받으면 정보만 찍고 작업 없이 0으로 끝난다. `--stop`도 데몬을 멈추고 끝난다. 판독기는 이 옵션들을 값 없는 플래그로만 읽는다. 그래서 `./gradlew :ci -v`를 `:ci` 실행으로 센다.
|
||||
- 발생 조건·영향: 다른 도구처럼 `-v`를 "자세히"로 알고 붙인 workflow 명령이 대표적이다. 그 step은 Gradle 버전만 찍고 초록으로 끝난다. `verifyStrictLaneStages`도 통과한다. 단계와 그 lane은 아무 데서도 돌지 않는다. `-qm`을 계획 전용으로 막은 것과 같은 종류인데 빠졌다.
|
||||
- 고치는 법: 작업 없이 끝나는 옵션 목록(`v`, `version`, `h`, `?`, `help`, `status`, `stop`)을 따로 둔다. 이 옵션이 단독으로든 묶음 안(`-qv`)으로든 나오면 "Gradle은 `<옵션>`을 받으면 작업을 실행하지 않고 끝난다"는 이유로 세지 않는다. 단위 테스트에 `:ci -v`, `:ci --help`, `-qv :ci`, `:ci --status`를 더한다. TestKit에는 `runner(":ci", "-v")`가 작업을 실행하지 않는다는 것을 고정한다(`--stop`은 TestKit에서도 돌리지 않는다).
|
||||
- 이번 커밋/이전부터: 이전부터. 이번 커밋이 판독을 "Gradle 9.0 파서대로"로 다시 쓰고 `-qm`만 계획 전용에 더하면서 남았다.
|
||||
- 증거: E3. 임시 프로젝트에서 Gradle 9.0.0 `gradle --no-daemon -q :ci -v`·`:ci --version`·`-v :ci`·`:ci --help`·`:ci -h`·`:ci --status` → 모두 rc=0, 작업 미실행(`-V`는 실행). 판독기 probe(`cases/06-early-exit-flags.yml`, `-qv`·`--stop` 포함 6개) → 모두 `executes(:ci, src)=true`.
|
||||
|
||||
### RR6-04-02 · Gradle을 올려 옵션 표가 낡아도 잡는 테스트가 없다 — 9.2의 `--task-graph`가 그 예
|
||||
|
||||
- 심각도: Minor (Low · P2)
|
||||
- 위치: `WorkflowGradleInvocations.java:60-83`(9.0 값 옵션·플래그 표), `:658-660`(Javadoc "pinned by `StrictLaneStagesFunctionalTest`"), `src/build-logic/README.md:19`("the reader follows Gradle 9.0's parser, probed in round 9"), `src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java:564-606`(고정한 것은 `-qm`·`-mx`뿐)
|
||||
- 무엇이 틀렸나: 옵션 표는 9.0.0 `--help`와 정확히 같다. 하지만 표를 실행 중인 Gradle과 비교하는 테스트가 없다. TestKit 테스트는 build-logic을 돌리는 Gradle(wrapper)에서 돌지만 두 모양만 본다. Gradle 9.2.0은 `--task-graph`("Print task graph instead of executing tasks")를 더했다. 9.2.0에서 `gradle :ci --task-graph`는 rc=0이고 작업을 실행하지 않는다. 판독기는 이 옵션을 모르는 긴 옵션으로 넘기고 `:ci` 실행으로 센다.
|
||||
- 발생 조건·영향: wrapper를 9.2 이상으로 올린 뒤 계획만 보려고 `./gradlew :integrationCheck --task-graph` 같은 step을 둔 경우다. 이 repo의 `configuration-cache` job이 `--dry-run`으로 하는 일과 같은 용도다. 검사는 통과하고 lane은 돌지 않는다. wrapper 변경 PR은 `build-logic.yml`(경로 `src/gradle/**`)을 돌리지만 지금 테스트는 그대로 통과한다. 9.7.1은 값 옵션 `--console-unicode`·`--develocity-url`·`--develocity-plugin-version`과 플래그 `--non-interactive`·`--isolated-projects`도 더했다.
|
||||
- 고치는 법: TestKit 테스트 하나를 더한다. `runner("--help")` 출력에서 옵션 이름을 뽑아 `GRADLE_FLAGS ∪ GRADLE_VALUE_OPTIONS`(그리고 RR6-04-01의 작업 없이 끝나는 목록)과 같다고 단언한다. 그러면 Gradle을 올리는 PR이 새 옵션마다 "값을 받는가, 작업을 실행하는가"를 정해야 통과한다. Javadoc과 README의 "고정" 문장은 실제로 고정한 범위로 고친다.
|
||||
- 이번 커밋/이전부터: 이번 커밋. 표와 "고정" 주장을 이번에 새로 뒀다.
|
||||
- 증거: E3. Gradle 9.0.0·9.2.0·9.7.1 `--help`의 옵션 이름과 판독기 표 대조(9.0.0: 표에 없는 옵션 0, 표에만 있는 옵션 0). 임시 프로젝트에서 9.0.0 `:ci --task-graph` → rc=1 "Problem configuring task :ci from command line", 9.2.0 → rc=0, "Tasks graph for: :ci", 작업 미실행. 판독기 probe(`cases/03-task-graph.yml`) → `executes=true`.
|
||||
|
||||
### RR6-04-03 · 스크립트가 그 명령 앞에서 끝날 수 있는 모양 중 맨 위의 `exit`만 본다
|
||||
|
||||
- 심각도: Minor (Low · P2)
|
||||
- 위치: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java:943-948`(맨 위에 혼자 있는 `exit`만 `terminated`), `:21-29`(Javadoc "anything after ... a top-level exit"), `:1144-1174`(`setEffect`가 `-n`을 모름)
|
||||
- 무엇이 틀렸나: 판독기는 뒤 명령이 아예 돌지 않는 경우를 맨 위의 무조건 `exit` 하나로만 안다. 아래 모양에서 bash는 `./gradlew :ci`를 돌리지 않거나 그 실패를 버리고 step을 초록으로 끝낸다. 판독기는 모두 실행으로 센다.
|
||||
- `if git diff --quiet origin/main -- .; then echo "no source change"; exit 0; fi` 다음 줄의 `./gradlew :ci`
|
||||
- `[ "$SKIP_CI" = true ] && exit 0` 다음 줄
|
||||
- `skip() { echo skip; exit 0; }`를 부른 다음 줄
|
||||
- `exec ./gradlew :help` 다음 줄(셸이 Gradle로 바뀌어 다음 줄은 돌지 않는다)
|
||||
- `set -n` 다음 줄(명령을 읽기만 하고 실행하지 않는다)
|
||||
- `trap 'exit 0' EXIT` 뒤의 `./gradlew :ci`(돌지만 실패해도 step이 0으로 끝난다)
|
||||
- 왜 결함인가: 같은 판독기는 step의 `if:`가 상태 함수가 아니면 "매 실행이 아니다"라며 세지 않는다. 스크립트 안의 조건부 `exit 0`도 같은 일을 한다. "바뀐 것이 없으면 건너뛴다"는 CI에서 흔한 모양이다.
|
||||
- 고치는 법:
|
||||
1. 맨 위가 아닌 곳(복합 명령, `&&`·`\|\|` 목록, 함수 본문)의 `exit`가 `exit 0`, 인자 없는 `exit`, 리터럴이 아닌 값이면 그 뒤 명령을 "앞의 `<exit>`가 그 전에 스크립트를 끝낼 수 있다"로 세지 않는다. `exit 1`처럼 0이 아닌 리터럴은 step을 실패로 끝내므로 지금처럼 둔다(이 repo `main-check` 첫 step의 `if …; then …; exit 1; fi` 모양).
|
||||
2. 맨 위의 `exec <명령>`은 `exit`처럼 그 뒤를 끝낸 것으로 본다.
|
||||
3. `set -n`·`set -o noexec`도 그 뒤를 끝낸 것으로 본다.
|
||||
4. `trap`의 `EXIT`·`ERR` 동작에 `exit`가 있으면 그 뒤 명령을 세지 않는다.
|
||||
5. 모양마다 RED 단위 테스트를 둔다.
|
||||
- 이번 커밋/이전부터: 이전부터. 이번 커밋이 `exit`를 다루면서 무조건 `exit`만 막았다.
|
||||
- 증거: E3. `bash -e`에 가짜 `gradlew`(호출을 기록하고 exit 1): 조건부 exit 두 모양·함수 안 exit·`set -n` → rc=0, 호출 0. `exec` → 다음 줄 호출 없음. `trap 'exit 0' EXIT` → 호출됐지만 rc=0. 판독기 probe(`cases/02-conditional-exit.yml`, `cases/11-more-exit.yml`) → 6개 모두 `executes=true`.
|
||||
|
||||
### RR6-04-04 · Windows runner의 기본 셸을 `bash -e`로 읽는다
|
||||
|
||||
- 심각도: Minor (Low · P3)
|
||||
- 위치: `WorkflowGradleInvocations.java:32-35`(Javadoc "GitHub's default `bash -e`"), `:94-99`(`SHELLS`의 `""` → `bash -e`), `:298-310`(`runs-on`을 보지 않음), `src/build-logic/README.md:19`("a step whose `shell:` is not the default, `bash` or `sh`"), `docs/upgrade/2026-11-maturity-review.md:107`(B-36 "`shell:`이 기본·`bash`·`sh`가 아닌 단계도 세지 않는다")
|
||||
- 무엇이 틀렸나: GitHub 문서에서 `shell`이 없을 때 Linux·macOS의 기본은 `bash -e {0}`이고 Windows의 기본은 `pwsh`다. pwsh에서 GitHub는 `$ErrorActionPreference = 'stop'`을 앞에, `if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }`를 뒤에 붙인다. 네이티브 명령(`gradlew.bat`)이 0이 아닌 코드로 끝나도 스크립트는 멈추지 않는다. step 결과는 마지막 네이티브 명령의 코드다. 판독기는 `runs-on`을 보지 않고 모든 기본 셸을 `bash -e`로 읽는다.
|
||||
- 발생 조건·영향: 파생 서비스가 `runs-on: windows-latest`(또는 matrix에 windows가 있는) job에서 `./gradlew :ci` 다음 줄에 `git status` 같은 네이티브 명령을 둔 경우다. Gradle이 실패해도 step은 초록이고 검사도 통과한다. 이 repo의 job 62개는 모두 `ubuntu-latest`라 지금은 해당하지 않는다. `container:` job의 기본은 `sh -e`인데 `-e` 켜짐·pipefail 없음이 같아 판정은 바뀌지 않는다. 주석의 "기본 = bash -e"만 정확하지 않다.
|
||||
- 고치는 법: job의 `runs-on`을 읽는다. `shell`이 없고 `runs-on`이 `ubuntu-`·`macos-` 리터럴이 아니면(Windows 라벨, `${{ }}` 식, 알 수 없는 self-hosted 라벨) "기본 셸이 Windows의 pwsh일 수 있다"로 세지 않는다. Javadoc·README·B-36에는 "Linux·macOS의 기본"과 container의 `sh -e`를 적는다. `runs-on: windows-latest` RED 단위 테스트를 둔다.
|
||||
- 이번 커밋/이전부터: 이번 커밋. 셸 판독과 "기본 = `bash -e`" 주장을 이번에 새로 뒀다.
|
||||
- 증거: E3(판독기 probe `cases/01-windows.yml` → `executes=true`) + E1(GitHub workflow syntax의 shell 표와 "Exit codes and error action preference" 절, container 문서의 "The default shell for `run` steps inside a container is `sh`"). pwsh 실행은 하지 않았다.
|
||||
|
||||
### RR6-04-05 · 문서와 실패 메시지가 세지 않는 이유를 사실과 반대로 적는다
|
||||
|
||||
- 심각도: Minor (Low · P3)
|
||||
- 위치: `docs/upgrade/2026-11-maturity-review.md:107`(B-36 괄호 안의 `\|\| exit 1`, "`if`·`for`·`case`·함수·`$( )`·`bash -c` 안"), `src/build-logic/README.md:19`("`\|\| true` or any `\|\|`", "the condition or body of `if`/`while`/`for`/`case`", "a command line Gradle rejects (`-mx` …)"), `AGENTS.md:87-89`("복합 명령·함수·명령 치환 안", "Gradle이 거부하는 명령줄(`-mx`)"), `CLAUDE.md:44-46`, `StrictLaneStagesPlugin.java:153-156`(요약 문구), `ShellScript.java:967-970`(`|| exit 1`에 "its failure is handled")
|
||||
- 무엇이 틀렸나:
|
||||
- `./gradlew ci || exit 1`, `if [ -n "$RUN" ]; then ./gradlew ci; fi`, `{ ./gradlew ci; }`, `( ./gradlew ci )`의 Gradle 실패는 `bash -e`에서 step을 실패시킨다. README 16절 결정대로 이 모양을 세지 않는 것(거짓 실패 쪽)은 맞다. 그런데 문서 넷과 실패 메시지는 이유를 "실패해도 단계를 실패시키지 못한다(a command whose failure cannot fail its step)"로 적는다. 사실과 반대다.
|
||||
- 문서는 "Gradle이 거부하는 명령줄은 세지 않는다"고 적는다. 구현은 짧은 옵션 묶음만 본다. `./gradlew :ci --task-graph`(9.0에서 거부, rc=1)나 `./gradlew :ci -x --dry-run`은 Gradle이 거부하지만 판독기는 센다. 매 실행 빨간 step이라 조용한 통과는 아니다. 문서가 구현보다 넓게 약속한다.
|
||||
- 영향: 실패를 workflow annotation으로 남기려고 `./gradlew ci || { echo "::error::ci failed"; exit 1; }`를 쓴 파생 서비스는 "your command cannot fail its step"을 받는다. 개발자는 검사가 틀렸다고 보고 우회를 찾는다. 해야 할 일(명령을 혼자 한 줄로 둔다)은 메시지에 없다.
|
||||
- 고치는 법: 세지 않는 이유를 셋으로 나눠 문서와 메시지에 같은 말로 적는다.
|
||||
1. 실패를 막지 못함: `|| true`·`|| :`, pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, `set +e` 뒤, 마지막이 아닌 `&&` 목록.
|
||||
2. 돌지 않을 수 있음: 복합 명령·함수 본문 안, 맨 위 `exit` 뒤(RR6-04-03), 상태 함수가 아닌 `if:`.
|
||||
3. 판독기가 읽지 않음(실패하면 step도 실패하지만 세지 않는다, 거짓 실패 쪽): `|| exit 1`, `|| { …; exit 1; }`, 서브셸·`{ }`, `$( )`, `bash -c`.
|
||||
`listReason`은 `||` 오른쪽이 0이 아닌 `exit`면 "이 모양은 읽지 않는다. 명령을 혼자 한 줄로 두라"고 말한다. "Gradle이 거부하는 명령줄"은 "Gradle이 거부하는 짧은 옵션 묶음(`-mx`)"으로 좁힌다. 요약 문구와 AGENTS.md·CLAUDE.md·README·B-36을 함께 고친다.
|
||||
- 이번 커밋/이전부터: 이번 커밋.
|
||||
- 증거: E3. `bash -e` probe: `./gradlew :ci || exit 1`, `if true; then ./gradlew :ci; fi`, `{ ./gradlew :ci; }`, `( ./gradlew :ci )` 각각 다음 줄에 `echo done` → 모두 rc=1(step 실패). 판독기 probe(`cases/12-gated-but-uncounted.yml`) → 미집계, 이유 "its failure is handled by the `|| { echo "::error::ci failed"; exit 1; }` after it". 문서는 E1 대조.
|
||||
|
||||
### RR6-04-06 · 사람이나 다른 workflow가 시작해야만 도는 workflow·job을 실행으로 센다
|
||||
|
||||
- 심각도: Minor (Low · P3)
|
||||
- 위치: `WorkflowGradleInvocations.java:364-410`(`dispatchOnlyReason`은 trigger가 모두 `workflow_dispatch`일 때만), `:528-542`(`uncountedReason`은 step과 자기 job의 `if:`만 본다)
|
||||
- 무엇이 틀렸나: "`workflow_dispatch`로만 시작하는 workflow는 묻지 않으면 아무것도 돌리지 않으므로 세지 않는다"(RR2-04-04)는 규칙이 같은 이유의 다른 모양을 보지 않는다. 아래는 모두 판독기가 실행으로 센다.
|
||||
- `on: [workflow_dispatch, repository_dispatch]`, `on: issue_comment`(ChatOps `/test`): 외부 요청이 있어야 돈다.
|
||||
- `on: workflow_call`만 있는 재사용 workflow: 부르는 workflow가 없거나 조건부로 부르면 돌지 않는다.
|
||||
- `needs:`로 기다리는 job이 상태 함수가 아닌 `if:`로 건너뛰어지는 job. GitHub 문서: "If a job fails or is skipped, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue."
|
||||
- 발생 조건·영향: 파생 서비스가 무거운 단계를 ChatOps나 재사용 workflow, 또는 조건부 job 뒤로 옮긴 경우다. 검사는 통과하고 단계는 요청이 있을 때만 돈다. 이 repo의 workflow에는 지금 이 모양이 없다.
|
||||
- 고치는 법:
|
||||
1. 시작 trigger가 모두 요청형(`workflow_dispatch`, `repository_dispatch`, `issue_comment` 등)이면 세지 않는다.
|
||||
2. `workflow_call`만 있는 workflow는 직접 세지 않는다. `jobs.<id>.uses: ./.github/workflows/<file>`로 부르는 job의 trigger와 `if:`를 물려받아 센다. 부르는 곳이 없으면 세지 않는다.
|
||||
3. job의 `needs:`를 따라가며 각 job의 `if:`에 같은 규칙을 적용한다. 자기 `if:`에 `always()`·`!cancelled()`가 있으면 거기서 끊는다.
|
||||
4. 모양마다 RED 테스트를 둔다.
|
||||
- 이번 커밋/이전부터: 이전부터.
|
||||
- 증거: E3(판독기 probe `cases/04-workflow-call.yml`, `07-triggers.yml`, `08-issue-comment.yml`, `09-needs.yml` → 모두 `executes=true`) + E1(GitHub workflow syntax `jobs.<job_id>.needs` 절).
|
||||
|
||||
## Declined to judge
|
||||
|
||||
- 경로·브랜치 필터(`paths:`, `branches:`)가 있는 trigger: 그 workflow가 도는 이벤트에서는 단계가 실제로 돈다. 어떤 필터가 충분한지는 저장소 정책이라 판단하지 않았다.
|
||||
- 설계상 거짓 실패 모양(`timeout ./gradlew …`, `set +e` / `./gradlew …` / `exit $status`, `|| exit 1`, 서브셸·`eval`·`source` 안의 `cd` 뒤): README 16절 결정이라 다시 올리지 않았다. 이유 문구만 RR6-04-05에 넣었다.
|
||||
- `${{ }}` 값이 `--dry-run`이나 `|| true`로 펼쳐지는 경우: 실행 전에는 값을 알 수 없다.
|
||||
- `CDPATH`·심볼릭 링크로 `cd`가 다른 곳으로 가는 경우: GitHub runner 기본 환경에는 `CDPATH`가 없다.
|
||||
- composite action(`.github/actions/*/action.yml`) 안의 `run:`: 판독기가 읽지 않는다. 거짓 실패 쪽이라 결함으로 올리지 않았다.
|
||||
- httpclient 문서(`docs/httpclient/support-matrix.md:61,65`, `docs/httpclient/release-checklist.md:12`): 장애 주입 lane 주기에 main push가 빠졌고, `spring62CompatibilityTest`는 없는 lane 이름이다(실제 이름 `spring62ApiSurfaceScan`, 2026-09-18 리뷰가 이미 적음). pathspec 밖 다른 영역 파일이라 판정하지 않았다. 총괄이 해당 영역으로 넘길 것.
|
||||
- 실제 GitHub runner와 pwsh 동작: 이 환경에서 실행할 수 없다. RR6-04-04는 문서 근거다.
|
||||
|
||||
## 결론
|
||||
|
||||
Critical 0, Important 0, 회귀 0. 결함 6건, 모두 Minor다.
|
||||
|
||||
- 이번 커밋 3건: RR6-04-02(옵션 표를 Gradle 올림에서 지키는 테스트 없음), RR6-04-04(Windows 기본 셸), RR6-04-05(세지 않는 이유 문구).
|
||||
- 이전부터 3건: RR6-04-01(작업 없이 끝나는 Gradle 옵션), RR6-04-03(조건부 `exit`·`exec`·`set -n`·`trap`), RR6-04-06(요청형 trigger·`workflow_call`·`needs`).
|
||||
|
||||
r9-d가 고쳤다고 한 항목(README 15 남음, RR5-02-01·02·03, `-mx`, 장애 주입 lane 중복)은 모두 닫혔다. 이 repo의 실제 workflow 판정은 `c508b1ba`와 같고 두 빌드의 `verifyStrictLaneStages --dry-run`이 통과한다. 남은 결함은 모두 파생 서비스가 쓸 수 있는 모양에서 검사가 거짓으로 통과하거나 이유를 틀리게 말하는 것이다.
|
||||
@@ -18,7 +18,8 @@ status: stub
|
||||
## Diagnosis
|
||||
|
||||
- Check token `aud` claim value
|
||||
- Compare against configured `spring.security.oauth2.resourceserver.jwt.audiences`
|
||||
- Compare against configured `app.security.audience` (`APP_SECURITY_JWT_AUDIENCE`, comma-separated;
|
||||
the token must name at least one)
|
||||
|
||||
## Action
|
||||
|
||||
|
||||
@@ -38,8 +38,45 @@ the time, and which half is not knowable from the status.
|
||||
6. If the method is not keyed, there is no ledger row. Resolve it against the business resource, or
|
||||
escalate to the service owner. This is the case the keyed profile exists to avoid.
|
||||
|
||||
7. `IN_PROGRESS` means a claim exists and has not finished. If its owner died, the claim is not
|
||||
stuck forever: once it is older than the claim TTL (`app.grpc.platform.operation-ledger-claim-ttl`,
|
||||
default 5m), the next retry of the same request takes it over and runs again,
|
||||
and a later reconciler pass sees that attempt's `COMMITTED` or `FAILED_TERMINAL`. Until a retry
|
||||
arrives, the case stays pending. The re-run is safe only when the ledger commit is recorded in the
|
||||
mutation's own transaction; if this service commits them separately, check the business resource
|
||||
before letting the retry through. An owner that was only slow cannot spoil the takeover: its claim
|
||||
attempt (`claim_attempt`) is behind, so its late commit is refused and its late failure ignored.
|
||||
A log line saying an operation "is no longer held by attempt N" is that refusal, not an outage.
|
||||
|
||||
**Escalate when** the reconciler's pending list grows across passes. That means the ledger is
|
||||
unreachable rather than slow.
|
||||
unreachable rather than slow. A case pending as `IN_PROGRESS` for longer than the claim TTL with no
|
||||
retry arriving is a caller that gave up; it needs the business resource checked, not a ledger fix.
|
||||
|
||||
---
|
||||
|
||||
## The operation ledger table keeps growing
|
||||
|
||||
**What you are seeing.** `grpc_operation_ledger` grows without bound, or a retry of an old key runs
|
||||
the mutation again instead of replaying.
|
||||
|
||||
**What it means.** Finished rows (`COMMITTED`, `FAILED_TERMINAL`) are deleted only when something
|
||||
calls `GrpcOperationLedgerRetention.purgeExpired(now)`; the starter assembles that bean
|
||||
(`app.grpc.platform.operation-ledger-enabled=true`) but does not schedule it. A growing table means
|
||||
the service's scheduler is not calling it. A retry that re-ran after the retention
|
||||
(`app.grpc.platform.operation-ledger-retention`, default 24h) is the trade the retention makes: its
|
||||
record was purged, so it was a new operation.
|
||||
|
||||
**What to do.**
|
||||
|
||||
1. Check that the service schedules `purgeExpired`. Each call deletes in batches of 500 until a batch
|
||||
comes back short, never touching `IN_PROGRESS` rows.
|
||||
2. For a large backlog, call it repeatedly; each batch is a short transaction that skips rows another
|
||||
transaction holds.
|
||||
3. If retried keys re-run after the retention, raise the retention above the callers' retry window
|
||||
rather than skipping the purge.
|
||||
|
||||
**Escalate when** old `IN_PROGRESS` rows accumulate. Those are not purged by design; each is an
|
||||
abandoned claim no retry has taken over (see `IN_PROGRESS` above).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
title: Runbook — IDEMPOTENCY_UNAVAILABLE (멱등성 조정 저장소 사용 불가)
|
||||
category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_RECOVERY_REQUIRED]
|
||||
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_COMPLETION_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-09-28
|
||||
last_updated: 2026-11-05
|
||||
status: active
|
||||
---
|
||||
|
||||
@@ -17,8 +17,32 @@ status: active
|
||||
- `IdempotencyExecutor` refused to run the action because the replay store (JPA or Redis, whichever
|
||||
`app.idempotency` selects) did not answer. Nothing was executed: the refusal happens before the
|
||||
action, so a client retry is safe.
|
||||
- The same 503 when the store refused to start a claim whose processing lease had already run out
|
||||
— the request spent longer than the lease between its claim and the start of its action (a
|
||||
stalled process, a slow store call). The ERROR line, `failure classified as
|
||||
IDEMPOTENCY_UNAVAILABLE (…)`, has the exception attached, and the exception's message reads `the
|
||||
claim's processing lease ran out before the action started; nothing ran: <scope>` — in prod JSON
|
||||
logs that is in `stack_trace`, not `message`. The store may be healthy.
|
||||
Nothing ran here either, and the next request with the key takes the claim over and runs it.
|
||||
- HTTP 503 `IDEMPOTENCY_COMPLETION_UNKNOWN` (`retryable=true`) is the same outage hitting after the
|
||||
action ran: the store did not answer while the result was being recorded. When the use case called
|
||||
the executor inside its write transaction, that transaction's database writes rolled back with the
|
||||
exception; an action that committed a transaction of its own kept its writes, and anything outside
|
||||
a transaction (an outbound call, a message) may have happened. This is not "nothing was executed".
|
||||
Clients resend with the same key.
|
||||
- HTTP 500 `IDEMPOTENCY_RECOVERY_REQUIRED` (`retryable=false`) means the opposite case: the store
|
||||
cannot tell whether an earlier attempt's external effect already happened.
|
||||
cannot tell whether an earlier attempt's effect already happened. Two records produce it:
|
||||
- `ABANDONED`: the action threw, or reported its effect unknown. Final until the record expires.
|
||||
- `EXECUTING` past its processing lease (`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s): the attempt
|
||||
crashed, or is still running longer than the lease. The executor never renews the lease, so a
|
||||
slow but healthy request lands here too. The server never runs it again and does not touch the
|
||||
record. If the attempt is still running and finishes, its result is recorded, the first request
|
||||
gets its normal answer, and later requests with the key get that result replayed; a failure it
|
||||
reports is recorded the same way. So this 500 can stop on its own (owner decision 2026-11-04).
|
||||
This is the Redis store's case. The PostgreSQL store, called inside the use case's write
|
||||
transaction as the template calls it, never shows another request an unfinished record: that
|
||||
request waits for the first transaction to end, and gets the replay if it committed or a fresh
|
||||
run if it rolled back (`docs/web/http-contract.md` §2).
|
||||
|
||||
## Diagnosis
|
||||
|
||||
@@ -26,15 +50,114 @@ status: active
|
||||
JPA datasource or Redis, depending on the selected provider).
|
||||
- Look for connection-pool saturation or timeouts on that store in the same time window; the
|
||||
executor reports saturation as unavailable rather than guessing.
|
||||
- For `IDEMPOTENCY_RECOVERY_REQUIRED`, find the scope digest in the server log line of the failed
|
||||
request and inspect that record's state in the store.
|
||||
- For `IDEMPOTENCY_RECOVERY_REQUIRED`, find the scope in the server's ERROR log of the failed request.
|
||||
Every transport writes the same line, `failure classified as IDEMPOTENCY_RECOVERY_REQUIRED
|
||||
(category=DATA_INTEGRITY, retryable=false)`, with the exception attached
|
||||
(shared-contract `ServerFailureLog`), and adds its own correlation:
|
||||
- web: no suffix; the line carries the request's `X-Request-Id` (MDC `request_id`).
|
||||
- gRPC: ` (method=<service>/<method>)`; MDC `request_id` too when the service closed the call on
|
||||
its callback thread.
|
||||
- GraphQL: ` (executionId=<id>)`, the `executionId` the client got in the error's `extensions`.
|
||||
- STOMP (`@MessageMapping`): no suffix; MDC `request_id` is the frame's.
|
||||
|
||||
The exception message ends with
|
||||
`<operation code>::v<digest version>::<scope digest>`, for example
|
||||
`claim requires reconciliation: CHARGE_CARD::v1::3f9a…` (64 hex characters). Then look at the
|
||||
record in the store the service uses (`APP_IDEMPOTENCY_PROVIDER`). There is no tool for this; these
|
||||
are the commands.
|
||||
- Redis. The key, for example `prod:order:shared:idem:v1:d1:CHARGE_CARD:3f9a…`, is
|
||||
|
||||
<!-- runbook-redis: idempotency-record-key -->
|
||||
```
|
||||
<APP_REDIS_NAMESPACE_ENVIRONMENT>:<APP_REDIS_NAMESPACE_SERVICE>:<APP_REDIS_NAMESPACE_DOMAIN>:idem:v1:d<digest version>:<operation code>:<scope digest>
|
||||
```
|
||||
|
||||
```
|
||||
HMGET <key> state attempt leaseUntil
|
||||
PTTL <key>
|
||||
```
|
||||
|
||||
`state` `ABANDONED` is final. `state` `EXECUTING` with a `leaseUntil` (lease end, epoch
|
||||
milliseconds, server clock) earlier than the server's `TIME` (first value × 1000) is an attempt
|
||||
past its lease that may still be running. `PTTL` is how long the record still lives, in
|
||||
milliseconds.
|
||||
- PostgreSQL, in the application's schema:
|
||||
|
||||
```sql
|
||||
SELECT status, attempt, failure_disposition, last_transition_kind,
|
||||
processing_lease_until, expires_at, updated_at
|
||||
FROM idempotency_record
|
||||
WHERE record_version = 2
|
||||
AND scope_hash = '<scope digest>';
|
||||
```
|
||||
|
||||
`status` `ABANDONED` with `last_transition_kind` `FAIL_ABANDONED` means the action threw or
|
||||
reported its effect unknown. `status` `EXECUTING` with `processing_lease_until` before
|
||||
`clock_timestamp()` is an attempt past its lease that may still be running. (`ABANDONED` with
|
||||
`EXPIRED_EXECUTION` is a lease that ran out under a version before 2026-11-04, which abandoned
|
||||
such rows; it goes away when the row expires.) `expires_at` is when the reaper deletes the row.
|
||||
|
||||
## Action
|
||||
|
||||
- `IDEMPOTENCY_UNAVAILABLE`: restore the store; clients retry with the same key and backoff.
|
||||
- `IDEMPOTENCY_RECOVERY_REQUIRED`: do not ask the client to retry blindly. Confirm whether the
|
||||
downstream effect of the earlier attempt exists, then complete or release the record so the next
|
||||
request with that key replays or re-executes deterministically.
|
||||
- `IDEMPOTENCY_UNAVAILABLE`: restore the store; clients retry with the same key and backoff. When
|
||||
the exception message says the claim's processing lease ran out before the action started, the
|
||||
store is not the cause: find what held those requests between claim and start (thread dumps, GC
|
||||
pauses, the store's latency in that window). Nothing to repair; the next same-key request runs.
|
||||
- `IDEMPOTENCY_COMPLETION_UNKNOWN`: restore the store, then check the effects outside the
|
||||
transaction for the failed requests (the ERROR log line names the code). A same-key resend replays
|
||||
a result that was in fact recorded, gets `IDEMPOTENT_IN_FLIGHT` while the attempt's lease lasts,
|
||||
and `IDEMPOTENCY_RECOVERY_REQUIRED` after it — handle that one as below.
|
||||
- `IDEMPOTENCY_RECOVERY_REQUIRED`: do not ask the client to retry blindly. If the record is
|
||||
`EXECUTING` past its lease, first wait for the attempt: look the record up again after the
|
||||
longest time the action can take. It changes by itself when the attempt finishes — `COMPLETED`
|
||||
(resends replay it, nothing to do), `ABANDONED`, or `FAILED_RETRYABLE` (the attempt proved it had
|
||||
no effect, and the next request with the key runs it). A crashed attempt, or one whose request
|
||||
already ended with `IDEMPOTENCY_COMPLETION_UNKNOWN`, never changes it; that record stays
|
||||
`EXECUTING` until it expires. Business data checked while the attempt still runs can say "no
|
||||
effect" a moment before the effect lands. Then confirm from business data (the order, the
|
||||
payment, the downstream system) whether the effect exists. There is no way to complete the record
|
||||
by hand — the stored response is the action's own result.
|
||||
- The effect exists: tell the client it was applied. Leave the record; a resend with the key keeps
|
||||
getting this 500 until the record expires (Redis `PTTL`, PostgreSQL `expires_at`).
|
||||
- The effect does not exist: the client sends the request again under a new key. To let the same
|
||||
key run again instead, delete the record — only while it is `ABANDONED`, because any other state
|
||||
belongs to a request that may still be running or to a stored result. Do not delete an
|
||||
`EXECUTING` record, even past its lease: if its attempt is still alive, its late result finds no
|
||||
record (`ABSENT`) — the result is lost, the first request gets this 500 after its work took
|
||||
effect, and the next request with the key runs the work a second time. Leave it to expire.
|
||||
- Redis: check and delete in one step, as the account the service's registered scripts run as
|
||||
(`APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE`, or the application account when it
|
||||
is unset). Checking with `HMGET` and then sending `DEL` is two commands: a record that expires
|
||||
between them and is claimed again by a new request is deleted while that request runs, and
|
||||
the next request with the key runs the work a second time (re-review 2026-11-04 RR4-03-02).
|
||||
The program below deletes the key only while its `state` is `ABANDONED`. The application
|
||||
accounts are denied `EVAL` (`infra/redis-sdk/acl/README.md`), so load it and run it by the
|
||||
digest `SCRIPT LOAD` prints, as the service runs its own scripts:
|
||||
|
||||
<!-- runbook-redis: idempotency-delete-abandoned -->
|
||||
```
|
||||
SCRIPT LOAD "if redis.call('HGET', KEYS[1], 'state') == 'ABANDONED' then return redis.call('DEL', KEYS[1]) end return 0"
|
||||
EVALSHA <digest SCRIPT LOAD printed> 1 <key>
|
||||
```
|
||||
|
||||
`1` deleted the record; the key is new. `0` deleted nothing: the record is no longer
|
||||
`ABANDONED` (or is gone) — look again before doing anything else. `NOSCRIPT` means the node
|
||||
that holds the key (a cluster) has not loaded the program: run `SCRIPT LOAD` on that node and
|
||||
`EVALSHA` again; nothing was deleted. A record that is about to expire needs nothing; once it
|
||||
is gone the key is new.
|
||||
- PostgreSQL:
|
||||
|
||||
```sql
|
||||
DELETE FROM idempotency_record
|
||||
WHERE record_version = 2
|
||||
AND scope_hash = '<scope digest>'
|
||||
AND status = 'ABANDONED';
|
||||
```
|
||||
|
||||
Without either step the key is released when the record expires. A record whose attempt never
|
||||
finished lives for the processing lease plus `APP_IDEMPOTENCY_TTL` from its claim; one the action
|
||||
marked failed lives for `APP_IDEMPOTENCY_FAILURE_RETENTION` (not shorter than `APP_IDEMPOTENCY_TTL`)
|
||||
from the failure (`docs/web/http-contract.md`, "서버가 기억하는 기간").
|
||||
|
||||
## Escalation
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [JOB_TIMEOUT]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-13
|
||||
last_updated: 2026-11-03
|
||||
status: stub
|
||||
---
|
||||
|
||||
@@ -48,7 +48,10 @@ status: stub
|
||||
## 5. Escalation
|
||||
|
||||
- 의존성 지연이 근본 원인이면 해당 의존성 오너에게 escalate
|
||||
- shutdown 예산(20s) vs k8s `terminationGracePeriodSeconds`(30s) 정합 이슈면 플랫폼/런타임 오너에게 escalate
|
||||
- 종료 예산은 차례로 더한 값이다: 웹 drain(`APP_SERVER_SHUTDOWN_TIMEOUT`, 기본 30s)이 끝난 뒤 async 대기 19s,
|
||||
합계 49s에 preStop(5s)과 여유를 더한다. k8s `terminationGracePeriodSeconds`가 이보다 작으면(예: 기본 30s)
|
||||
async 대기 중 SIGKILL이다. compose는 60s(`docker-compose.yml` `stop_grace_period`, 합계는
|
||||
`DeveloperExperienceContractTest`가 검사). 정합 이슈면 플랫폼/런타임 오너에게 escalate
|
||||
|
||||
## 6. Recovery / Verification
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: INTERNAL
|
||||
error_codes: [MIGRATION_FAILED]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-07-29
|
||||
last_updated: 2026-11-04
|
||||
status: active
|
||||
---
|
||||
|
||||
@@ -40,8 +40,27 @@ status: active
|
||||
4. Check whether any owned relation was created without a successful history entry. Compare only
|
||||
against the owned tables in the reviewed migration; do not drop unrelated relations.
|
||||
5. Classify the failure:
|
||||
- lock/statement timeout: remove the blocker or reduce rollout concurrency, then rerun;
|
||||
- lock/statement timeout: remove the blocker or reduce rollout concurrency, then rerun. A
|
||||
migration that locks a table already in use gives up after its own `SET LOCAL lock_timeout`
|
||||
(5 s; SQLState `55P03` `lock_not_available`) and rolls back whole, so the history ends one
|
||||
version below it. The blocker is a transaction that touched the table and is still open —
|
||||
often an idle-in-transaction session. Find it by the lock it holds on that table (`<table>`
|
||||
is the table the failing statement locks; for a `REFERENCES`, also the table it references):
|
||||
|
||||
```sql
|
||||
SELECT DISTINCT a.pid, a.state, a.xact_start, a.query
|
||||
FROM pg_locks l JOIN pg_stat_activity a USING (pid)
|
||||
WHERE l.relation = '<table>'::regclass AND l.granted AND a.pid <> pg_backend_pid()
|
||||
ORDER BY a.xact_start;
|
||||
```
|
||||
|
||||
`query` is only that session's last statement, not the one that touched the table, so do not
|
||||
look for the table name in it. Listing every long transaction instead names unrelated ones
|
||||
(reports, batches) beside the blocker. End the blocker, then rerun
|
||||
(`docs/jpa/migration-guide.md` "Bound the lock wait");
|
||||
- SQL/data precondition: create a new forward migration that makes the precondition explicit;
|
||||
a duplicate outbox order key stopping V21 (`ux_outbox_event_aggregate_order`) is the known
|
||||
case — clean it up with `outbox-dead-letter.md` §8 and rerun, the migration stays as it is;
|
||||
- checksum mismatch: compare the deployed artifact with the already applied script before
|
||||
considering repair;
|
||||
- connection/TLS failure: fix transport or credentials without changing Flyway history.
|
||||
|
||||
@@ -4,7 +4,7 @@ category: INTERNAL
|
||||
error_codes: [OUTBOX_DEAD_LETTER]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-11
|
||||
last_updated: 2026-11-04
|
||||
status: stub
|
||||
---
|
||||
|
||||
@@ -16,18 +16,28 @@ status: stub
|
||||
|
||||
- alert name: `outbox_dead_letter`
|
||||
- alert payload 필수 field: `error.code=OUTBOX_DEAD_LETTER`, `event_type`, `event_id`, `correlation_id`, `runbook_link`
|
||||
- 임계: `outbox.publisher.published.total{outcome=DEAD}` > 0 (DEAD 전이는 자동 회복이 없으므로 단건도 점검 대상)
|
||||
- 임계: `outbox.publisher.published.total{outcome=DEAD}` > 0 또는 `outbox.pending.size{status=DEAD}` > 0 (DEAD 전이는
|
||||
자동 회복이 없으므로 단건도 점검 대상). 두 번째 조건이 필요한 이유: claim이 행을 DEAD로 옮기는 경우
|
||||
(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 relay 결과를 거치지 않아 첫 번째 카운터가 오르지 않는다
|
||||
(재리뷰 2026-11-03 2차 RR-02-12)
|
||||
|
||||
## 2. First Response (5분 이내)
|
||||
|
||||
### Step 1 — 확인
|
||||
1. ERROR log에서 `OUTBOX_DEAD_LETTER` 라인 확인: `event_id`, `event_type`, `correlation_id`, 마지막 실패 원인 예외 추출
|
||||
1. ERROR log에서 `OUTBOX_DEAD_LETTER` 라인 확인: `event_id`, `event_type`, `correlation_id`, `error.reason`(원인
|
||||
코드 — publisher가 붙인 코드, 없으면 거부 결과 이름, 분류되지 않은 예외면 그 타입 이름) 추출. 같은 값이 행의
|
||||
`last_failure_code`에 남는다. ERROR가 없고 WARN `outbox claim moved a row ... to DEAD`만 있으면 relay가 아니라
|
||||
claim이 행을 DEAD로 옮긴 것이다 — `error.reason`이 `ATTEMPT_COUNTERS_INCONSISTENT`면 `deferred_attempt_count`를
|
||||
되돌리지 않은 수동 재발행이 원인이니 §4의 SQL로 다시 재발행한다. `UNREADABLE_ROW`면 행 자체가 event로 읽히지
|
||||
않는다(canonical 봉투 없음, 저장된 해시와 바이트 불일치). 이 경우에도 같은 코드가 행의 `last_failure_code`에
|
||||
남는다 — 그 전 발행 실패의 코드는 덮어쓴다
|
||||
2. DB에서 DEAD row 확인: `SELECT * FROM outbox_event WHERE status = 'DEAD' ORDER BY occurred_at;`
|
||||
3. **차단 영향 파악 (중요)**: strict per-aggregate FIFO 정책상 DEAD row는 같은 `aggregate_id`의 후행 이벤트를 계속 차단함 —
|
||||
`SELECT count(*) FROM outbox_event b WHERE b.status <> 'PUBLISHED' AND EXISTS (SELECT 1 FROM outbox_event d WHERE d.status='DEAD' AND d.aggregate_id=b.aggregate_id AND d.occurred_at < b.occurred_at);`
|
||||
3. **차단 영향 파악 (중요)**: strict per-aggregate FIFO 정책상 DEAD row는 같은 aggregate(`tenant_scope`, `aggregate_type`, `aggregate_id`)의 후행 이벤트를 계속 차단함. 순서는 `(aggregate_sequence, event_index)`로 비교한다(claim SQL `PostgreSqlOutboxClaimRepository`와 같은 키) —
|
||||
`SELECT count(*) FROM outbox_event b WHERE b.status <> 'PUBLISHED' AND EXISTS (SELECT 1 FROM outbox_event d WHERE d.status='DEAD' AND d.tenant_scope=b.tenant_scope AND d.aggregate_type=b.aggregate_type AND d.aggregate_id=b.aggregate_id AND (d.aggregate_sequence < b.aggregate_sequence OR (d.aggregate_sequence = b.aggregate_sequence AND d.event_index < b.event_index)));`
|
||||
|
||||
### Step 2 — 임시 격리
|
||||
- DEAD는 max attempts(3) 소진의 최종 상태 — 자동 재시도 없음, 수동 개입 필수
|
||||
- DEAD는 확정 거부(`REJECTED_BEFORE_SEND`·`REJECTED_AFTER_BROKER`) 또는 분류되지 않은 발행 예외의 max attempts(3) 소진의 최종 상태 — 자동 재시도 없음, 수동 개입 필수
|
||||
- broker 정지·종료 중 거부·Kafka 인증/인가 실패는 DEAD가 되지 않는다(FAILED로 계속 재시도). 이것들로 DEAD가 보이면 이 변경 이전에 생긴 행이다
|
||||
- 차단된 aggregate가 비즈니스 크리티컬하면 아래 §4의 수동 처분(재발행 또는 skip)을 우선 수행
|
||||
|
||||
## 3. Diagnosis
|
||||
@@ -35,18 +45,41 @@ status: stub
|
||||
- log query: `{service="app"} | error.code="OUTBOX_DEAD_LETTER" | stats count by event_type`
|
||||
- 마지막 실패 원인 분류:
|
||||
- poison event (payload 직렬화/계약 위반) → payload 자체 결함, 재발행해도 실패 — 수정 후 재발행 또는 skip
|
||||
- broker 장기 outage 중 attempts 소진 → broker 회복 후 재발행으로 해결 가능
|
||||
- broker 장기 outage 중 attempts 소진 → 현재 relay에서는 일어나지 않는다(일시적 실패는 예산을 쓰지 않음). 이전 버전에서 생긴 행은 broker 회복 후 재발행으로 해결 가능
|
||||
- 구성 오류 (Kafka disabled 상태에서 producer 활성) → 구성 수정 후 재발행
|
||||
- 가능한 원인 우선순위: 구성 오류 > broker outage > poison payload
|
||||
|
||||
## 4. Mitigation (수동 처분 — 둘 중 하나)
|
||||
|
||||
- **재발행 (기본)**: 원인 해소 후 해당 row를 다시 claim 가능 상태로 되돌림 —
|
||||
`UPDATE outbox_event SET status = 'PENDING', attempt_count = 0, next_attempt_at = now() WHERE event_id = '<id>' AND status = 'DEAD';`
|
||||
(consumer는 at-least-once + idempotencyKey dedupe 의무가 있으므로 중복 발행은 안전)
|
||||
- **skip (영구 폐기)**: 이벤트가 더 이상 유효하지 않으면 PUBLISHED로 마킹해 FIFO 차단을 해제 —
|
||||
`UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '<id>' AND status = 'DEAD';`
|
||||
⚠️ skip은 다운스트림에 영구 이벤트 갭을 만든다 — 비즈니스 오너 승인 후에만 수행하고 incident 기록에 남김
|
||||
**재발행 (기본)**: 원인 해소 후 해당 row를 다시 claim 가능 상태로 되돌린다. 시도 횟수 두 개
|
||||
(`attempt_count`, `deferred_attempt_count`)를 함께 0으로 되돌린다. `attempt_count`만 되돌리면 다음 claim에서
|
||||
미룬 claim 수가 전체 claim 수보다 많아지고, claim은 그 행을 읽지 않고 다시 DEAD로 옮긴다(재리뷰 2026-11-03
|
||||
RR-05-01).
|
||||
|
||||
<!-- runbook-sql: dead-redrive-one -->
|
||||
```sql
|
||||
UPDATE outbox_event SET status = 'PENDING', attempt_count = 0, deferred_attempt_count = 0, next_attempt_at = now() WHERE event_id = '<id>' AND status = 'DEAD';
|
||||
```
|
||||
|
||||
장애 구간 전체를 한 번에 되돌리려면(원인이 해소된 것을 확인한 뒤). outbox_event에는 DEAD가 된 시각
|
||||
컬럼이 없어 이벤트 발생 시각으로 고른다 — 먼저 같은 조건의 SELECT로 대상을 확인한다.
|
||||
|
||||
<!-- runbook-sql: dead-redrive-window -->
|
||||
```sql
|
||||
UPDATE outbox_event SET status = 'PENDING', attempt_count = 0, deferred_attempt_count = 0, next_attempt_at = now() WHERE status = 'DEAD' AND occurred_at BETWEEN '<장애 시작>' AND '<장애 끝>';
|
||||
```
|
||||
|
||||
consumer는 at-least-once + idempotencyKey dedupe 의무가 있으므로 중복 발행은 안전하다.
|
||||
|
||||
**skip (영구 폐기)**: 이벤트가 더 이상 유효하지 않으면 PUBLISHED로 마킹해 FIFO 차단을 해제한다.
|
||||
⚠️ skip은 다운스트림에 영구 이벤트 갭을 만든다 — 비즈니스 오너 승인 후에만 수행하고 incident 기록에
|
||||
남긴다.
|
||||
|
||||
<!-- runbook-sql: dead-skip-one -->
|
||||
```sql
|
||||
UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '<id>' AND status = 'DEAD';
|
||||
```
|
||||
|
||||
- 장기: poison event 재발 방지(payload 계약 테스트 보강), DEAD 빈발 event_type의 producer 검증 강화
|
||||
|
||||
## 5. Escalation
|
||||
@@ -64,10 +97,170 @@ status: stub
|
||||
|
||||
- error-codes.yaml rows: `OUTBOX_DEAD_LETTER` (INTERNAL, retryable=false)
|
||||
- metrics.yaml: `outbox.publisher.published.total{outcome=DEAD}`, `outbox.pending.size{status=DEAD}`, `outbox.publisher.lag`
|
||||
- 코드: `application-core` `PublishPendingOutboxEventsUseCase`(FAILED→DEAD 전이), `adapter-persistence` `outbox/OutboxEventJpaRepository`(FIFO 게이트 — DEAD가 후행 차단)
|
||||
- 코드: `application-core` `PublishPendingOutboxEventsUseCase`(FAILED→DEAD 전이), `adapter:outbound:persistence-jpa` `outbox/postgresql/PostgreSqlOutboxClaimRepository`(FIFO 게이트 — DEAD가 후행 차단), `outbox/jpa/JpaOutboxStore#claimBatch`(읽을 수 없는 행을 claim 때 DEAD로)
|
||||
- §4의 SQL 블록은 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는 테스트가 있다
|
||||
(`PostgreSqlOutboxDispositionRunbookIntegrationTest`, lane `postgresqlOutboxDispositionRunbookIntegrationTest`).
|
||||
블록을 고치면 그 lane을 다시 돌린다
|
||||
- 관련 runbook: [[outbox-publish-failed]]
|
||||
- 관련 branch: [[feature-domain-event-outbox-contract]], [[feature-background-job-async-contract]] (max attempts/DLQ vocabulary SSOT)
|
||||
|
||||
## 8. 배포 전 확인 — V21 순서 키 중복
|
||||
|
||||
V21(`V21__outbox_aggregate_sequence.sql`)은 `outbox_event`의 순서 키
|
||||
`(tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)`에 유일 인덱스
|
||||
`ux_outbox_event_aggregate_order`를 만든다. 같은 키를 가진 행이 이미 둘 이상 있으면 인덱스 생성이
|
||||
실패하고 기동이 멈춘다(`MIGRATION_FAILED`, exit 70). 이 실패는 의도한 동작이다(리뷰 2026-11-01
|
||||
README 15절 결정). 같은 키의 행들은 claim gate가 순서를 정하지 못한 행이다. 그냥 넘기면 순서 위반이
|
||||
숨는다. V21은 transaction 하나로 적용되므로, 실패하면 V21 전체가 롤백되고 V20 상태로 남는다.
|
||||
|
||||
V21이 하는 일은 세 가지 더 있다.
|
||||
|
||||
- **floor 기록.** `outbox_aggregate_sequence_floor`에 V21 적용 시각(epoch 마이크로초)을 한 번 쓴다. 새로
|
||||
생기는 aggregate counter는 이 값과 남은 행의 최대 번호 중 큰 값 다음에서 시작한다. 그래서 reaper가
|
||||
행을 지운 aggregate, tenant scope가 바뀐 aggregate도 소비자가 이미 받은 벽시계 번호(약 1.7×10¹⁵)보다
|
||||
작은 번호를 받지 않는다(리뷰 RR-03-02). 벽시계 번호를 쓴 적 없는 서비스도 첫 번호가 floor + 1이다.
|
||||
- **counter 미리 만들기.** 남은 행이 있는 aggregate의 counter를 그 최대 번호로 만든다.
|
||||
- **잠금 대기 5초.** 유일 인덱스는 만드는 동안 `outbox_event`에 SHARE 잠금을 건다. 그동안 outbox를 쓰는
|
||||
업무 쓰기가 모두 멈춘다. V21은 `lock_timeout = 5s`로 잠금을 기다린다. 열린 outbox 쓰기 트랜잭션 때문에
|
||||
5초 안에 못 잡으면 V21이 실패하고 V20에 남는다(`MIGRATION_FAILED`). 덜 바쁜 시각에 다시 배포하거나
|
||||
Step 0으로 인덱스를 먼저 만든다.
|
||||
|
||||
V20(`deferred_attempt_count`)과 V22(`last_failure_code`)도 같은 상한을 둔다(재리뷰 2026-11-03 2차 RR-02-09).
|
||||
둘 다 `ALTER TABLE outbox_event`라 가장 강한 잠금(ACCESS EXCLUSIVE)을 건다. 이 잠금은 읽기와도 충돌하므로,
|
||||
`outbox_event`를 읽기만 한 트랜잭션 하나(운영자가 `BEGIN` 안에서 조회하고 둔 psql 세션 포함)가 열려 있어도
|
||||
기다린다. 5초 안에 못 잡으면 그 마이그레이션이 실패·롤백되고 DB는 한 버전 아래(V19 또는 V21)에 남으며 새 버전은
|
||||
기동하지 않는다(`MIGRATION_FAILED`, exit 70). `outbox_event`에 잠금을 쥔 열린 트랜잭션을 찾아 끝낸 뒤 다시 배포한다.
|
||||
|
||||
```sql
|
||||
SELECT DISTINCT a.pid, a.state, a.xact_start, a.query
|
||||
FROM pg_locks l JOIN pg_stat_activity a USING (pid)
|
||||
WHERE l.relation = 'outbox_event'::regclass AND l.granted AND a.pid <> pg_backend_pid()
|
||||
ORDER BY a.xact_start;
|
||||
```
|
||||
|
||||
`query`는 그 세션의 마지막 문장일 뿐이다. `outbox_event`를 읽은 뒤 다른 문장을 실행한 세션이면 표 이름이 보이지
|
||||
않으니 `query`로 원인을 고르지 않는다. 오래 열린 트랜잭션을 모두 보는 조회는 보고·배치 같은 무관한 트랜잭션까지 낸다.
|
||||
|
||||
rolling 배포 중 아직 옛 버전인 인스턴스가 벽시계 번호로 쓴 행은 floor보다 크다. 새 버전의 counter는
|
||||
그 aggregate의 가장 큰 행 번호보다 작아지지 않으므로 그 행 뒤에 번호를 준다. 서로 커밋되지 않은 채
|
||||
겹친 옛·새 쓰기 사이의 순서는 보장하지 않는다 — 옛 벽시계 방식도 보장하지 않던 것이다.
|
||||
|
||||
이 "그 행 뒤에"는 **같은 aggregate identity**의 행에만 성립한다. tenant scope를 바꾸는 배포에서는 옛 버전이
|
||||
옛 scope로, 새 버전이 새 scope로 쓴다. 새 버전의 counter는 옛 scope 행을 보지 못하므로 floor + 1부터 시작하고,
|
||||
rolling 중 옛 버전이 방금 쓴 번호(floor보다 초당 10⁶씩 큰 벽시계 번호)보다 **작은** 번호를 준다(재리뷰
|
||||
2026-11-03 2차 RR-02-10, 실 PG 확인). scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한
|
||||
소비자는 그 사이 새 이벤트를 버린다. 그래서 **tenant scope를 바꾸는 배포는 rolling으로 하지 않는다**: 옛 버전
|
||||
인스턴스를 모두 멈춘 뒤(옛·새 버전이 함께 쓰는 구간 없이) 새 버전을 띄운다.
|
||||
|
||||
tenant scope를 바꾼 서비스(샘플은 `portfolio` → 단일 scope)는 배포 전에 옛 scope의 미발행 행이
|
||||
없는지 확인한다. 옛 scope 행과 새 scope 행은 서로 다른 aggregate로 보여 claim gate가 서로를 막지 않고,
|
||||
partition key도 달라 다른 partition으로 간다.
|
||||
|
||||
```sql
|
||||
SELECT tenant_scope, count(*) AS unpublished
|
||||
FROM outbox_event
|
||||
WHERE status <> 'PUBLISHED'
|
||||
GROUP BY tenant_scope;
|
||||
```
|
||||
|
||||
V20 이하 DB를 V21 이상으로 올리는 배포 전에 아래 순서로 확인한다.
|
||||
|
||||
**Step 0 — (outbox가 큰 경우만) 순서 키 인덱스를 먼저 만든다**
|
||||
|
||||
V21이 인덱스를 만드는 동안 outbox 쓰기가 멈춘다. reaper가 `outbox_event`를 보존 기간 안으로 줄이므로
|
||||
보통은 짧다. 그 시간도 멈출 수 없을 만큼 크면, Step 1~3으로 중복을 없앤 뒤 같은 이름·같은 열의 인덱스를
|
||||
`CONCURRENTLY`로 먼저 만든다. 쓰기를 막지 않는다. transaction 밖(autocommit)에서 실행한다. V21의
|
||||
`IF NOT EXISTS`가 이 인덱스를 그대로 쓴다.
|
||||
|
||||
<!-- runbook-sql: v21-prebuild-order-index -->
|
||||
```sql
|
||||
CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS ux_outbox_event_aggregate_order
|
||||
ON outbox_event (tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index);
|
||||
```
|
||||
|
||||
`CONCURRENTLY` 빌드가 중복이나 중단으로 실패하면 INVALID 인덱스가 남는다. 이 인덱스는 유일성을 지키지
|
||||
않는다. V21은 이 이름의 인덱스가 유효한 유일 인덱스가 아니면 건너뛰지 않고 실패한다. 그때는
|
||||
`DROP INDEX CONCURRENTLY ux_outbox_event_aggregate_order;` 뒤 Step 1부터 다시 한다. 빌드가 아직 도는
|
||||
중에도 INVALID로 보이므로, 지우기 전에 `pg_stat_progress_create_index`에 진행 중인 빌드가 없는지 본다.
|
||||
|
||||
V21 안에서 `CONCURRENTLY`를 쓰지 않은 이유: `CONCURRENTLY`는 transaction 안에서 돌 수 없다. V21을
|
||||
transaction 밖으로 빼면 중복을 만났을 때 "V21 전체 롤백, V20 그대로"가 깨지고, 반쯤 적용된 counter·floor와
|
||||
INVALID 인덱스가 남는다. 인덱스만 V22로 떼어 내도 실패 시 INVALID 인덱스와 Flyway 실패 이력이 남아 수동
|
||||
복구가 필요하다. 그래서 기본은 transaction 안 빌드 + 잠금 대기 5초, 큰 outbox는 이 Step 0이다.
|
||||
|
||||
**Step 1 — 중복 확인 (읽기 전용)**
|
||||
|
||||
<!-- runbook-sql: v21-duplicate-order-keys -->
|
||||
```sql
|
||||
SELECT tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index,
|
||||
count(*) AS row_count,
|
||||
count(*) FILTER (WHERE status <> 'PUBLISHED') AS unpublished_count,
|
||||
string_agg(event_id || ':' || status, ', ' ORDER BY occurred_at, event_id) AS events
|
||||
FROM outbox_event
|
||||
WHERE tenant_scope IS NOT NULL
|
||||
AND aggregate_type IS NOT NULL
|
||||
AND aggregate_sequence IS NOT NULL
|
||||
AND event_index IS NOT NULL
|
||||
GROUP BY tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index
|
||||
HAVING count(*) > 1
|
||||
ORDER BY tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index;
|
||||
```
|
||||
|
||||
- 결과가 0행이면 그대로 배포한다.
|
||||
- 1행 이상이면 Step 2로 간다. 결과 한 행이 순서 키 하나이고, `events`가 그 키를 쓰는 행들이다.
|
||||
- `IS NOT NULL` 조건이 있는 이유: 유일 인덱스는 다섯 열 중 하나라도 NULL인 행을 비교하지 않는다
|
||||
(PostgreSQL 기본 동작). 순서 열이 비어 있는 옛 행은 V21을 막지 않는다.
|
||||
|
||||
**Step 2 — 미발행 행이 빠질 때까지 기다린다**
|
||||
|
||||
`unpublished_count`가 0이 아닌 키는 아직 지우지 않는다. 같은 키의 행끼리는 서로를 막지 않으므로
|
||||
지금 배포된 relay가 계속 발행한다. `DEAD` 행은 §4의 처분(재발행 또는 skip)을 먼저 한다. Step 1을
|
||||
다시 돌려 모든 키의 `unpublished_count`가 0이 되면 Step 3으로 간다.
|
||||
|
||||
**Step 3 — 이미 발행된 중복을 정리한다**
|
||||
|
||||
모든 행이 `PUBLISHED`인 키에서 가장 먼저 생긴 행(`occurred_at`, `event_id` 순) 하나만 남기고 나머지를
|
||||
지운다. 이 행들은 이미 broker로 나갔고 다시 나가지 않는다. 보존 기간이 지나면 reaper가 어차피 지운다.
|
||||
지우기 전에 `outbox_event_v21_duplicates` 테이블로 복사해 증거를 남긴다. 미발행 행이 하나라도 있는
|
||||
키는 이 SQL이 건드리지 않는다.
|
||||
|
||||
<!-- runbook-sql: v21-remove-published-duplicates -->
|
||||
```sql
|
||||
BEGIN;
|
||||
CREATE TABLE outbox_event_v21_duplicates AS
|
||||
SELECT o.*
|
||||
FROM outbox_event o
|
||||
JOIN (SELECT event_id,
|
||||
row_number() OVER same_key AS copy_no,
|
||||
bool_and(status = 'PUBLISHED') OVER same_key AS all_published
|
||||
FROM outbox_event
|
||||
WHERE tenant_scope IS NOT NULL
|
||||
AND aggregate_type IS NOT NULL
|
||||
AND aggregate_sequence IS NOT NULL
|
||||
AND event_index IS NOT NULL
|
||||
WINDOW same_key AS (
|
||||
PARTITION BY tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index
|
||||
ORDER BY occurred_at, event_id
|
||||
ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING)) d
|
||||
ON d.event_id = o.event_id
|
||||
WHERE d.copy_no > 1
|
||||
AND d.all_published;
|
||||
DELETE FROM outbox_event o
|
||||
USING outbox_event_v21_duplicates d
|
||||
WHERE o.event_id = d.event_id;
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
Step 1을 다시 돌려 0행이면 배포한다. 정리와 배포 사이에 옛 버전이 새 중복을 만들 수 있다(벽시계로
|
||||
순서 번호를 만든 샘플 코드가 그 원인이었다). 그래도 V21은 실패하고 롤백될 뿐이니 Step 1부터 다시 한다.
|
||||
`outbox_event_v21_duplicates`는 확인이 끝나면 지운다.
|
||||
|
||||
확인 쿼리, 정리 SQL, Step 0의 인덱스 SQL은 이 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는
|
||||
테스트가 있다(`PostgreSqlOutboxOrderKeyRunbookIntegrationTest`, lane
|
||||
`postgresqlOutboxOrderKeyRunbookIntegrationTest`). 같은 lane이 V21의 counter·floor, 잠금 대기 실패,
|
||||
INVALID 인덱스 거부도 본다. 이 절의 `runbook-sql` 블록을 고치면 그 lane을 다시 돌린다. V20·V22의 잠금 대기
|
||||
실패는 `PostgreSqlMigrationLockWaitIntegrationTest`(lane `postgresqlMigrationLockWaitIntegrationTest`)가 본다.
|
||||
|
||||
---
|
||||
|
||||
> **Stub 상태 안내**: 이 runbook은 skeleton 단계의 stub. 실제 broker·DLQ 토픽·승인 체계 확정 시 보강 필요.
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [OUTBOX_PUBLISH_FAILED]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-11
|
||||
last_updated: 2026-11-04
|
||||
status: stub
|
||||
---
|
||||
|
||||
@@ -14,17 +14,23 @@ status: stub
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
|
||||
- alert name: `outbox_publish_failed_rate` 또는 `outbox_publisher_lag`
|
||||
- alert payload 필수 field: `error.code=OUTBOX_PUBLISH_FAILED`, `event_type`, `correlation_id`, `runbook_link`
|
||||
- alert name: `outbox_publish_failed_rate`, `outbox_publisher_lag` 또는 `outbox_retry_long`
|
||||
- alert payload 필수 field: `error.code=OUTBOX_PUBLISH_FAILED`, `error.reason`, `event_type`, `correlation_id`, `runbook_link`
|
||||
- 임계 (metrics.yaml verbatim):
|
||||
- P2: `outbox.publisher.published.total{outcome=FAILED}` rate > 1% for 10m
|
||||
- P2: `outbox.publisher.lag` > 60s for 10m / P1: > 300s for 5m
|
||||
- P2: `outbox.pending.size{status=PENDING}` growing for 10m
|
||||
- P2: `outbox.retry.long.size` > 0 for 10m — §4.1 "끝나지 않는 재시도"로 간다
|
||||
|
||||
## 2. First Response (5분 이내)
|
||||
|
||||
### Step 1 — 확인
|
||||
1. ERROR log에서 `OUTBOX_PUBLISH_FAILED` 라인 확인: `event_type`, `event_id`, `correlation_id`, `attempt_count` 추출
|
||||
1. ERROR log에서 `OUTBOX_PUBLISH_FAILED` 라인 확인: `event_type`, `event_id`, `correlation_id`, `attempt_count`,
|
||||
`error.reason` 추출. `error.reason`이 원인 코드다 — publisher가 붙인 코드(예: `KAFKA_AUTHENTICATIONEXCEPTION`,
|
||||
`KAFKA_TRANSPORT_CLOSED`, `PUBLISH_RUNTIME_UNAVAILABLE`, `PUBLISH_DEADLINE_EXCEEDED`), 코드가 없으면 결과
|
||||
이름(`AMBIGUOUS`, `REJECTED_RETRYABLE`), 분류되지 않고 던져진 실패면 예외 타입 이름이다. 같은 값이 행의
|
||||
`last_failure_code`에도 남는다. `error.cause_type`은 어느 결과였는지만 말한다(`OutboxPublishRefusedException`이면
|
||||
거부, `OutboxPublishAmbiguousException`이면 응답 없음)
|
||||
2. broker 상태 확인: `APP_MESSAGING_BROKER` 값과 broker endpoint 가용성. 이 키는 활성화 스위치가
|
||||
아니라 **선택자**다 — messaging을 끄는 것은 `APP_MESSAGING_ENABLED=false`이고, 이 값을 비운다고
|
||||
messaging이 꺼지지는 않는다.
|
||||
@@ -40,8 +46,13 @@ status: stub
|
||||
3. `outbox.pending.size` status 분포 확인 (FAILED 누적 vs PENDING 누적)
|
||||
|
||||
### Step 2 — 임시 격리
|
||||
- 일시 실패는 자동 backoff 재시도(30s × 2^(attempt-1) + jitter, max attempts 3)가 동작 — 즉시 수동 개입 불필요
|
||||
- broker 장기 다운이면 DEAD 전이 누적 전에 broker 회복을 우선 (max attempts 소진 시 `runbook://outbox/dead-letter`로 이관)
|
||||
- 일시 실패는 자동 backoff 재시도(30s × 2^(attempt-1) + jitter, 상한 5분)가 동작 — broker 장애처럼 원인이 저절로
|
||||
풀리는 경우는 수동 개입이 필요 없다
|
||||
- broker 정지·종료 중 거부·Kafka 인증/인가 실패(`AMBIGUOUS`, `REJECTED_RETRYABLE`)는 시도 예산을 쓰지 않는다 — 장애가 길어도 DEAD가 되지 않고, broker가 돌아오면 늦어도 약 5분 30초 안에 자동 재발행된다
|
||||
- **그 대신 끝이 없다.** 원인이 저절로 풀리지 않으면(진짜로 틀린 credential·ACL, Kafka adapter가 이름을 모르는
|
||||
broker 거부 — topic timestamp 정책, 없는 topic의 metadata 대기 초과는 기본값으로 `AMBIGUOUS`가 된다) 그 행은 5분
|
||||
간격으로 영원히 FAILED가 되고 그 aggregate의 뒤 이벤트를 막는다. `outbox.retry.long.size` > 0이면 §4.1로 간다
|
||||
- max attempts 3은 adapter가 분류하지 못하고 던진 발행 예외에만 적용된다 (소진 시 `runbook://outbox/dead-letter`로 이관)
|
||||
- relay 자체를 멈춰야 하면 `app.outbox.relay-enabled=false`로 스케줄러 비활성 (이벤트는 outbox 테이블에 안전하게 보존됨 — 유실 없음)
|
||||
|
||||
## 3. Diagnosis
|
||||
@@ -55,7 +66,11 @@ status: stub
|
||||
- 가능한 원인:
|
||||
- broker outage/네트워크 → broker 측 회복 대기
|
||||
- Kafka adapter 미구성(enabled인데 brokers 누락은 기동 시 차단됨) / disabled 상태에서 producer 활성화
|
||||
- poison event (직렬화 불가/payload 계약 위반) → 재시도 무의미, attempts 소진 후 DEAD로 흘러감 (의도된 동작)
|
||||
- poison event (직렬화 불가/payload 계약 위반) → 확정 거부(`REJECTED_*`)면 바로, 분류되지 않은 예외면 attempts 소진 후 DEAD로 흘러감 (의도된 동작)
|
||||
- 같은 행의 `OUTBOX_PUBLISH_FAILED`가 5분 간격으로 끝없이 반복되면 §4.1의 조회로 그 행의 `last_failure_code`를
|
||||
본다. `KAFKA_AUTHENTICATIONEXCEPTION`·`KAFKA_*AUTHORIZATIONEXCEPTION`이면 credential·ACL이 실제로 틀린
|
||||
것이다 — 고치면 다음 재시도에서 저절로 빠진다. 그 밖의 코드가 같은 행에서만 반복되면 broker가 그 레코드를
|
||||
받지 않는 것이다 — §4.1로 보류한다
|
||||
- 동일 aggregate head 실패로 후행 이벤트가 FIFO 게이트에 차단되어 lag 증가 (strict per-aggregate FIFO — 설계 의도)
|
||||
|
||||
## 4. Mitigation
|
||||
@@ -64,6 +79,68 @@ status: stub
|
||||
- IN_FLIGHT orphan(claim 후 crash)은 in-flight-timeout(기본 PT5M) 경과 후 자동 재claim — at-least-once이므로 중복 발행 가능, consumer dedupe(idempotencyKey)가 흡수
|
||||
- 장기: `app.outbox.poll-interval`/`batch-size` 조정, broker 가용성 SLA 점검, 빈발 event_type의 payload 계약 검토
|
||||
|
||||
### 4.1 끝나지 않는 재시도 — 찾기, 보류(park), 재개(resume), 버리기(skip)
|
||||
|
||||
시도 예산을 쓰지 않는 실패(§2 Step 2)는 끝 상태가 없다. 리뷰 2026-11-01 README 15절 결정(재시도 유지)은 그대로 두고,
|
||||
운영자가 그런 행을 보고 멈출 수 있게 한다(재리뷰 2026-11-03 RR-05-03 결정).
|
||||
|
||||
**Step 1 — 찾기 (읽기 전용).** 미룬 claim(`deferred_attempt_count`)이 10번 이상인 FAILED 행이다. backoff 상한이
|
||||
5분이라 10번은 적어도 약 35분 동안 계속 실패했다는 뜻이다. `outbox.retry.long.size`·`outbox.retry.long.age`가
|
||||
같은 기준(`OutboxMetrics.LONG_RETRY_DEFERRED_CLAIMS`)으로 센다. 아래 SQL의 숫자를 바꾸면 그 상수도 같이 바꾼다 —
|
||||
`OutboxLongRetryRunbookContractTest`(lane `:composition:outbox-relay:outboxRelayDocumentContractTest`)가 둘을 비교한다.
|
||||
|
||||
<!-- runbook-sql: long-retries -->
|
||||
```sql
|
||||
SELECT event_id, event_type, aggregate_type, aggregate_id, attempt_count, deferred_attempt_count,
|
||||
last_failure_code, occurred_at, next_attempt_at
|
||||
FROM outbox_event
|
||||
WHERE status = 'FAILED'
|
||||
AND deferred_attempt_count >= 10
|
||||
ORDER BY occurred_at, event_id;
|
||||
```
|
||||
|
||||
`last_failure_code`로 원인을 가른다(§3). 원인이 고쳐지는 것(credential·ACL·topic 설정)이면 고치고 기다린다 —
|
||||
다음 재시도에서 저절로 빠진다. 고칠 때까지 재시도 소음과 실패 로그를 멈추고 싶거나, 그 레코드만 broker가
|
||||
받지 않는 것이면 Step 2로 보류한다.
|
||||
|
||||
**Step 2 — 보류(park).** FAILED 행 하나를 `PARKED`로 둔다. relay는 PARKED 행을 claim하지 않는다. 그 행은
|
||||
여전히 미발행이라 같은 aggregate의 뒤 이벤트를 계속 막는다 — 순서는 지킨다. `outbox.publisher.lag`도 계속
|
||||
오른다. 보류는 원인을 찾는 동안 재시도만 멈추는 것이지 incident를 닫는 것이 아니다.
|
||||
|
||||
<!-- runbook-sql: park-one -->
|
||||
```sql
|
||||
UPDATE outbox_event SET status = 'PARKED' WHERE event_id = '<id>' AND status = 'FAILED';
|
||||
```
|
||||
|
||||
`UPDATE 0`이면 그 사이 relay가 행을 claim해 IN_FLIGHT다. `next_attempt_at`이 지난 뒤 다시 실행한다.
|
||||
보류된 행 수는 `outbox.pending.size{status=PARKED}`로 보인다.
|
||||
|
||||
**롤백 전에 보류를 푼다.** `PARKED`는 이 버전(`bbe944bd` 이후)에 생긴 상태다. 그보다 옛 버전은 이 이름을 몰라
|
||||
상태별 집계 전체가 실패하고, `outbox.pending.size` 게이지가 PENDING까지 통째로 꺼진다 — `PENDING size growing`
|
||||
경보의 입력이 사라진다(재리뷰 2026-11-03 2차 RR-02-11). 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두
|
||||
Step 3으로 재개하거나 버린다. 이 버전부터는 모르는 상태가 있어도 그 상태만 빼고 세고 WARN 한 번으로 이름을
|
||||
말한다(`outbox_event holds rows in a status this version does not know`).
|
||||
|
||||
**Step 3 — 재개(resume) 또는 버리기(skip).** 원인을 고쳤으면 재개한다. 행은 FAILED로 돌아가 바로 claim
|
||||
대상이 된다. 시도 횟수는 그대로 둔다(미룬 claim은 예산을 쓰지 않으므로 DEAD로 바로 가지 않는다).
|
||||
|
||||
<!-- runbook-sql: resume-one -->
|
||||
```sql
|
||||
UPDATE outbox_event SET status = 'FAILED', next_attempt_at = now() WHERE event_id = '<id>' AND status = 'PARKED';
|
||||
```
|
||||
|
||||
그 이벤트를 영원히 보내지 않기로 했으면 버린다. DEAD skip과 같은 승인 조건이다 — 다운스트림에 영구 이벤트
|
||||
갭이 생기므로 비즈니스 오너 승인 후에만 하고 incident 기록에 남긴다.
|
||||
|
||||
<!-- runbook-sql: parked-skip-one -->
|
||||
```sql
|
||||
UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '<id>' AND status = 'PARKED';
|
||||
```
|
||||
|
||||
이 절의 SQL 블록은 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는 테스트가 있다
|
||||
(`PostgreSqlOutboxDispositionRunbookIntegrationTest`, lane `postgresqlOutboxDispositionRunbookIntegrationTest`).
|
||||
블록을 고치면 그 lane을 다시 돌린다.
|
||||
|
||||
## 5. Escalation
|
||||
|
||||
- P1 lag(>300s 5m) 지속 + broker 회복 불가면 broker/infra 팀에 page
|
||||
@@ -77,8 +154,8 @@ status: stub
|
||||
## 7. Related
|
||||
|
||||
- error-codes.yaml rows: `OUTBOX_PUBLISH_FAILED` (TRANSIENT_DEPENDENCY, retryable=true, retry_after 30s)
|
||||
- metrics.yaml: `outbox.publisher.published.total`, `outbox.publisher.lag`, `outbox.pending.size`
|
||||
- 코드: `application-core` `PublishPendingOutboxEventsUseCase`(상태머신), `adapter-persistence` `outbox/OutboxEventJpaRepository`(SKIP LOCKED claim + FIFO 게이트), `adapter-outbound` `messaging/outbox/KafkaOutboxMessagePublishAdapter`(fail-closed)
|
||||
- metrics.yaml: `outbox.publisher.published.total`, `outbox.publisher.lag`, `outbox.pending.size`, `outbox.retry.long.size`, `outbox.retry.long.age`
|
||||
- 코드: `application-core` `PublishPendingOutboxEventsUseCase`(상태머신), `adapter:outbound:persistence-jpa` `outbox/postgresql/PostgreSqlOutboxClaimRepository`(SKIP LOCKED claim + FIFO 게이트), `adapter:outbound:messaging` `outbox/OutboxMessagePublishAdapter`·`platformbridge/PlatformIntegrationEventPublishAdapter`(fail-closed, 원인 코드 번역)
|
||||
- 관련 runbook: [[outbox-dead-letter]]
|
||||
- 관련 branch: [[feature-domain-event-outbox-contract]], [[feature-background-job-async-contract]] (retry/DLQ vocabulary SSOT)
|
||||
|
||||
|
||||
@@ -34,21 +34,22 @@ Redis liveness 실패만으로 pod를 재시작하지 않는다. 재시작 폭
|
||||
- `evictionValidation=CONFIGURED_EXPECTATION_ONLY`와
|
||||
`externalEvictionAttestation=INCOMPLETE`는 effective server policy가 증명되지 않았다는
|
||||
뜻이다. 이를 정상 attestation으로 해석하지 않는다.
|
||||
- `redis.capability.operations.total`과 `redis.capability.duration.seconds`에서 affected
|
||||
capability/role/operation의 실제 반환 outcome을 확인한다. mutation의
|
||||
`certainty=indeterminate`는 timeout이나 연결 끊김을 미실행 증거로 바꾸지 않는다.
|
||||
- `redis.capability.admission.rejected.total`에서 `rejected_saturated`와
|
||||
`rejected_closed`를 구분하고, `redis.capability.inflight.total`의 같은 role에 대해 현재 0이
|
||||
아닌 state를 확인한다. in-flight gauge는 bounded command count이며 byte 수나 queue depth가
|
||||
아니다.
|
||||
- `redis.capability.readiness.total`은 현재 상태 gauge가 아니라 exact sanitized
|
||||
`RoleHealth` 관측 횟수다. 최신 health detail의 state/reason/requirement와 함께 해석한다.
|
||||
optional cache의 degraded serving과 required coordination/session의 fail-closed 결정을
|
||||
같은 availability 의미로 합치지 않는다.
|
||||
- 종료 시 `redis.capability.lifecycle.drain.total`에서 `drained`,
|
||||
`forced_after_timeout`, `interrupted`를 구분한다. repeated close는 새 drain을 시작하거나
|
||||
중복 관측을 만들지 않는다.
|
||||
- reconnect, cache source-load, session repository error 지표의 변화를 함께 본다.
|
||||
- **지금 내보내는 Redis 지표는 connection lane 단위 `redis.lane.*`다**(`docs/registries/metrics.yaml`,
|
||||
`lane` 태그). capability·operation 단위 지표(`redis.capability.*`)는 설계만 있고 아직 어떤 코드도
|
||||
내보내지 않는다 — 대시보드에서 찾지 않는다(재리뷰 2026-11-03, `src/adapter/outbound/cache-redis/README.md`
|
||||
「아직 내보내지 않는 지표」).
|
||||
- lane 포화: `redis.lane.acquire.refused.total`(거절)과 `redis.lane.acquire.wait.seconds`(대기)를 lane별로
|
||||
본다. `CACHE_SCRIPT`만 차 있으면 캐시 조건부 쓰기의 문제이고, 멱등성·lease가 쓰는 `SCRIPT` lane은
|
||||
따로 본다(재리뷰 RR-04-02).
|
||||
- 연결 불안정: `redis.lane.connections.opened.total`·`redis.lane.connections.discarded.total`의 급증,
|
||||
`redis.lane.connections.active`·`pending`.
|
||||
- operation 결과(hit/miss/denied/conflict, `certainty=indeterminate`)는 지표가 아니라 각 capability의
|
||||
로그와 health detail에서 확인한다. timeout이나 연결 끊김은 미실행 증거가 아니다.
|
||||
- readiness는 최신 health detail의 state/reason/requirement로 본다. optional cache의 degraded serving과
|
||||
required coordination/session의 fail-closed 결정을 같은 availability 의미로 합치지 않는다.
|
||||
- 재연결은 `redis.lane.connections.opened.total`과 `discarded.total`을 함께 본다(Cluster `TRANSACTION`
|
||||
lane은 borrow마다 열어 opened가 꾸준히 오른다 — `cache-redis/README.md`). cache source-load·session
|
||||
repository 오류 지표는 내보내는 코드가 없다(설계만 있음).
|
||||
- Redis server 측에서는 memory/eviction, rejected clients, replication link/lag,
|
||||
persistence error, Cluster coverage를 operator dashboard에서 확인한다.
|
||||
- `NOSCRIPT`, result-schema mismatch, ACL denial, TLS/auth failure, OOM, timeout을 서로 다른
|
||||
@@ -56,24 +57,23 @@ Redis liveness 실패만으로 pod를 재시작하지 않는다. 재시작 폭
|
||||
|
||||
### Observability and lifecycle boundaries
|
||||
|
||||
- 여섯 `redis.capability.*` meter의 tag는 닫힌 enum에서만 생성된다. key, subject, session id,
|
||||
token, endpoint, exception text, script/SHA, value 같은 identity/wire material을 metric이나
|
||||
ticket에 복사하지 않는다.
|
||||
- semantic operation 계측은 logical provider가 실제로 반환한 hit/miss/denied/conflict/
|
||||
unavailable/indeterminate 결과를 기록한다. cache의 `stale`/`skipped`, session의
|
||||
`tombstoned`/`absolute_expired`도 정상 hit/miss와 분리한다. meter registry, classifier,
|
||||
monotonic ticker 장애는 command 결과나 원래 exception instance를 바꾸지 않는다.
|
||||
- `redis.lane.*` meter의 tag는 닫힌 lane 이름뿐이다. key, subject, session id, token, endpoint,
|
||||
exception text, script/SHA, value 같은 identity/wire material을 metric이나 ticket에 복사하지 않는다.
|
||||
- semantic operation 단위 계측(hit/miss/denied/conflict/unavailable/indeterminate 결과, cache의
|
||||
`stale`/`skipped`, session의 `tombstoned`/`absolute_expired`)은 **설계만 있고 내보내지 않는다**
|
||||
(`redis.capability.*`, 위 Detection 절). operation 결과는 로그와 health detail로 본다. `redis.lane.*`
|
||||
계측(listener)이 실패해도 borrow 결과나 원래 exception은 바뀌지 않는다. 처음 실패는 WARN 로그 한 줄로
|
||||
남고(`RedisRuntimeOwner`), 그 뒤는 DEBUG다 — 지표가 통째로 비면 그 WARN을 찾는다.
|
||||
- route 응답이 설정된 byte/collection bound를 넘으면 동일 logical operation을
|
||||
`unavailable`로 종료한다. GET/read-only 응답은 `not_applied`, mutation VALUE/MULTI 응답은
|
||||
서버 실행 여부를 되돌릴 수 없으므로 `indeterminate`다. 앞선 `success` 표본과 이 실패를 두
|
||||
operation으로 합산하지 않는다.
|
||||
서버 실행 여부를 되돌릴 수 없으므로 `indeterminate`다.
|
||||
- Spring 종료의 dependency order는 invalidation subscription 같은 capability dependent를 먼저
|
||||
닫고, capability bean을 닫은 다음 canonical registry가 router admission을 닫아 in-flight를
|
||||
bounded drain하고 마지막에 runtime을 닫는 순서다. 종료 중 새 command를 허용하거나 drain
|
||||
timeout 뒤 무기한 기다리지 않는다.
|
||||
- 현재 composition에는 active Redis scheduler나 dormant credential-rotation coordinator가 없다.
|
||||
존재하지 않는 lifecycle coordinator를 복구 절차에서 찾거나 수동 호출하지 않는다.
|
||||
- 이 meter와 단일-process lifecycle test는 Sentinel/Cluster failover, TLS/ACL 배포 적합성,
|
||||
- `redis.lane.*` meter와 단일-process lifecycle test는 Sentinel/Cluster failover, TLS/ACL 배포 적합성,
|
||||
k3s multi-node, L1/L2 분산 일관성, distributed session 동작의 qualification 증거가 아니다.
|
||||
해당 label은 별도 topology/conformance lane의 실제 증거가 있어야 한다.
|
||||
|
||||
|
||||
@@ -1136,12 +1136,19 @@ GQL-007이 *"named fragment가 custom introspection gate를 우회하고 variabl
|
||||
> *Guessing it from the operation root would price `order { customer { orders { … } } }` as three
|
||||
> root fields and miss the multiplication entirely.*
|
||||
|
||||
**(2) 카디널리티는 스키마가 아니라 요청에서 온다.**
|
||||
**(2) 목록을 돌려주는 필드는 클라이언트가 어떻게 물어도 원소 수만큼 곱한다.** page 필드(스키마에
|
||||
`first`/`last` 가 있거나 catalog 에 connection 으로 등록)는 리터럴 → 요청 변수 → 연산의 변수
|
||||
기본값 → 스키마 인자 기본값 순서로 page 를 찾고, 없으면 기본 page 크기로 곱한다. 찾은 값은 전부
|
||||
상한으로 검사한다. page 인자가 없는 일반 list 는 catalog 에 선언한 추정 크기(없으면 기본 page
|
||||
크기)로 차원마다 곱한다. connection 객체 바로 안의 `edges`·`nodes` 는 이미 곱한 page 라서 다시
|
||||
곱하지 않는다.
|
||||
|
||||
> *a connection's children are multiplied by the effective page size, and a page size supplied
|
||||
> through a variable is resolved from the request variables rather than assumed to be the default.
|
||||
> That is the difference between a budget and a suggestion — `first: $n` would otherwise cost the
|
||||
> same at 1 and at 1000.*
|
||||
> *Pricing an omitted argument as one row was the bypass: `items(first: 20)` scored 410 while
|
||||
> `items` scored 40, and four nested lists added up instead of multiplying.*
|
||||
|
||||
2026-11-01 리뷰 03-01 이 이 구멍을 찾았다. 그 전 javadoc 은 "변수로 준 page 를 요청 변수에서
|
||||
읽는다"까지만 말했고, 변수 기본값과 생략한 인자, 일반 list 는 1 로 계산됐다. 상세는
|
||||
`src/adapter/inbound/graphql/README.md` 의 「목록을 돌려주는 필드는…」 절.
|
||||
|
||||
**(3) 순회 자체가 유한하다.** 기본 `maximumVisitedNodes = 200_000`, fragment cycle은 확장 경로
|
||||
추적으로 끊는다. javadoc이 왜 검증된 문서에도 경계를 유지하는지 쓴다 — 이 scorer는 pre-execution
|
||||
|
||||
@@ -1336,15 +1336,35 @@ startup 동작으로는 절대 아니다.
|
||||
|
||||
### 8.2 `ConcurrentIndexMigrationInspector`
|
||||
|
||||
PostgreSQL은 `CREATE INDEX CONCURRENTLY`를 트랜잭션 블록 안에서 아예 거부하고, Flyway는
|
||||
기본적으로 마이그레이션을 트랜잭션으로 감싼다. **그래서 첫 배포에서 실패하는데, 그게 좋은
|
||||
경우다.**
|
||||
PostgreSQL은 `CREATE INDEX CONCURRENTLY`·`DROP INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY`를
|
||||
트랜잭션 블록 안에서 거부한다. Flyway 11은 `CREATE`/`DROP INDEX CONCURRENTLY`가 든 파일을 **스스로
|
||||
트랜잭션 밖에서** 돌린다. `REINDEX … CONCURRENTLY`는 모른다. 그 파일은 트랜잭션 안에서 돌고, 배포 때
|
||||
PostgreSQL이 거부한다. 그래서 검사기는 동시 인덱스 문장이 있으면 `.sql.conf`에
|
||||
`executeInTransaction=false`를 적으라고 요구한다. Flyway가 알아서 빼 주는 문장에도 적는다. 파일이
|
||||
자기에게 필요한 것을 스스로 말하게 하려는 것이다.
|
||||
|
||||
> 나쁜 경우는 다른 statement와 섞인 마이그레이션이다: 그것들은 커밋되고, concurrent index는
|
||||
> 안 되고, 스키마는 **history row가 반대로 말하는 채로 부분 마이그레이션 상태로 남는다.**
|
||||
> 다른 문장과 섞인 파일은 Flyway가 기본값(`mixed=false`)에서 **아무것도 실행하기 전에 거부**한다.
|
||||
> 부분 적용은 일어나지 않는다. 그래도 한 파일에 하나만 두는 이유는 아래 `requireIsolatedStatement`의
|
||||
> 복구 때문이다.
|
||||
|
||||
검사 대상: `create index concurrently`, `drop index concurrently`, `reindex index concurrently`,
|
||||
`reindex table concurrently`, `reindex concurrently`.
|
||||
트랜잭션 밖에서도 동시 빌드는 **자기보다 먼저 시작한 트랜잭션이 모두 끝나기를 기다린다.**
|
||||
|
||||
```
|
||||
Flyway 기본값: 잠금 트랜잭션(열린 채) ──기다림──▶ 마이그레이션 끝
|
||||
▲ │
|
||||
└──────── CIC가 기다림 ◀───────────┘ → 배포가 끝나지 않는다
|
||||
```
|
||||
|
||||
- Flyway는 기본으로 마이그레이션 잠금(PostgreSQL advisory lock)을 트랜잭션 안에 두고, 실행 내내 그
|
||||
트랜잭션을 열어 둔다.
|
||||
- CIC는 그 트랜잭션도 기다린다. Flyway는 CIC가 끝나기를 기다린다. 오류도 시간 제한도 없다.
|
||||
- 템플릿은 잠금을 세션에 둔다. Spring Boot의 Flyway는 module-defaults의
|
||||
`spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway는
|
||||
`FlywaySchemaPolicy.configure()`로 받는다. 배포 마이그레이션 도구도 같은 값이어야 한다
|
||||
(`docs/jpa/migration-guide.md` "Who may change the schema").
|
||||
|
||||
검사 대상: `CREATE [UNIQUE] INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX … CONCURRENTLY`
|
||||
(`REINDEX (CONCURRENTLY) TABLE` 같은 괄호 옵션 포함).
|
||||
|
||||
`requireIsolatedStatement`도 있다 — concurrent 빌드가 실패하면 invalid index가 남고, 그
|
||||
복구는 마이그레이션이 다른 걸 아무것도 안 했으면 `DROP INDEX` 하나지만 뭔가 했으면 부분
|
||||
@@ -1681,7 +1701,7 @@ setter가 아니라 **registry 생성자**에서 설정한다.
|
||||
|---|---|
|
||||
| `IdempotencyCapabilityGuard` | 3개 precondition (vendor, capability, transaction) |
|
||||
| `IdempotencyRowMapper` | row 읽기 + `clock_timestamp()` |
|
||||
| `IdempotencyClaimGateway` | 소유권을 **정하는** 3개 statement (insert / reset / abandon) |
|
||||
| `IdempotencyClaimGateway` | 소유권을 **정하는** 2개 statement (insert / reset) |
|
||||
| `IdempotencyTransitionGateway` | 이미 가진 claim을 **진행시키는** 5개 statement |
|
||||
| `IdempotencyDigestPolicy` | transition digest 구성 |
|
||||
| `IdempotencyRecordRow` | row 정의 (package-private) |
|
||||
@@ -1700,17 +1720,23 @@ inserted == 1 → Acquired
|
||||
COMPLETED이고 replay_until 지남 → resetClaim → TakenOverClaimed
|
||||
request_hash 불일치 → FingerprintMismatch
|
||||
COMPLETED이고 replay_until 있음 → CompletedReplay(payload, replayUntil)
|
||||
같은 claim attempt(token+operationId) → ReplayedAcquire
|
||||
같은 token, 다른 operationId → OwnerOperationConflict
|
||||
ABANDONED → RecoveryRequired
|
||||
CLAIMED이고 lease 만료 → resetClaim → TakenOverClaimed
|
||||
FAILED_RETRYABLE → resetClaim → TakenOverClaimed
|
||||
EXECUTING이고 lease 만료 → abandonExpiredExecution → RecoveryRequired
|
||||
ABANDONED → RecoveryRequired
|
||||
같은 claim attempt(token+operationId) → ReplayedAcquire
|
||||
같은 token, 다른 operationId → OwnerOperationConflict
|
||||
EXECUTING이고 lease 만료 → RecoveryRequired (행은 그대로)
|
||||
그 외 → InProgress(retryAfter, attempt)
|
||||
```
|
||||
|
||||
**만료된 `CLAIMED`만 takeover하고, 만료된 `EXECUTING`은 `ABANDONED`로 닫고 reconciliation을
|
||||
요구한다.** 실행이 시작된 뒤의 blind retry를 하지 않는다는 뜻이다.
|
||||
넘겨받기 두 줄이 같은 attempt의 재생보다 앞이다. 시작을 거절당했거나 재시도 가능 실패로 끝난 attempt가
|
||||
같은 attempt로 다시 오면 재생이 아니라 넘겨받기다. 재생하면 시작할 수 없는 claim을 돌려줘 기록이 사라질
|
||||
때까지 막혔다(라운드6 RR6-02-01, Redis CLAIM도 같은 순서).
|
||||
|
||||
**만료된 `CLAIMED`만 takeover하고, 만료된 `EXECUTING`은 reconciliation을 요구하되 행은 바꾸지
|
||||
않는다.** 실행이 시작된 뒤의 blind retry를 하지 않는다는 뜻이다. 행을 그대로 두는 이유는 주인이 아직
|
||||
돌고 있을 수 있어서다. 주인이 늦게 끝나면 그 결과가 기록되고 다음 claim이 재생한다(2026-11-04 소유자
|
||||
결정 — 전에는 `abandonExpiredExecution`이 행을 `ABANDONED`로 바꿔 늦은 결과를 버렸다).
|
||||
|
||||
`IdempotencyCapabilityGuard`에 아주 좋은 버그 기록이 있다.
|
||||
|
||||
@@ -1746,6 +1772,9 @@ update idempotency_record
|
||||
> 무언가가 record를 움직였으니 caller는 자기 view를 현재로 취급하면 안 된다. row를 읽고 나서
|
||||
> scope만으로 update하면 lease가 만료된 worker가 takeover한 worker의 상태를 덮어쓸 수 있다.
|
||||
|
||||
START/RENEW만은 store가 잠근 row를 owner 튜플과 먼저 비교한 뒤에 돌리므로, 그 둘의 0은 lease가 끝난
|
||||
것이다. 그래서 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로 답한다(재리뷰 2026-11-04 RR5-01-02).
|
||||
|
||||
`IdempotencyDigestPolicy`의 기록이 특히 좋다.
|
||||
|
||||
> `transition|operationId|ownerToken|attempt|stateRevision`은 **누가, 언제**를 덮고 **무엇**은
|
||||
@@ -2830,7 +2859,8 @@ Flyway는 세 옵션이 **pin**되어 있다(env-driven 아님): `baseline-on-mi
|
||||
`reaper-interval: PT10M`, `published-retention: P7D`.
|
||||
|
||||
`ca-skeleton.capabilities.idempotency.*`: `provider: disabled`, `processing-lease: 30s`,
|
||||
`replay-ttl: 24h`(`APP_IDEMPOTENCY_TTL`, 최대 72h), `failure-retention: 24h`,
|
||||
`replay-ttl: 24h`(`APP_IDEMPOTENCY_TTL`, 최대 72h, `processing-lease` 이상·`failure-retention` 이하),
|
||||
`failure-retention: 24h`,
|
||||
`reaper-interval: 10m`. 한 record(`IdempotencySettings`)가 전부 바인딩한다.
|
||||
|
||||
---
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user