chore(ci): 백엔드 PR #17·#19~#27을 합친 트리를 한 번에 검사하고 병합한다 #28

Merged
donghyeon.kang merged 53 commits from claude/r9-be-combined-check into main 2026-11-12 23:28:18 +00:00
232 changed files with 5500 additions and 1335 deletions
+21 -56
View File
@@ -9,10 +9,13 @@
# is a credential in the repository, and the fact that it is 'only an example' is not something a
# scanner, a fork, or a hurried operator can tell.
#
# A key left blank here uses the inline default in application.yml. Seven values have no default
# at all — the datasource URL, username and password, the application name, and the JWT issuer and
# audience — because a default for any of them is a deployment running against something nobody
# chose.
# Every value here is the registry default (or the row's `example:`, a recommended production
# value such as the SMTP submission port). A blank line is not "use the default": Compose env_file
# and bootRun both set the variable to an empty string, which replaces the default. So a key is left
# blank only when it has no default — secrets, and the values a deployment must choose itself (the
# profile, the application name, the datasource URL and username, the JWT issuer and audience),
# because a default for any of them is a deployment running against something nobody chose.
# Keys the registry marks deprecated_orphaned are not listed: nothing reads them.
# =============================================================================
# ---- Configuration -----------------------------------------------------------
@@ -20,9 +23,13 @@ SPRING_PROFILES_ACTIVE=
APP_NAME=
APP_SERVER_PORT=8080
MANAGEMENT_SERVER_PORT=9001
# Loopback by default, so the actuator is reachable only from inside the container. Kubernetes
# probes and a Prometheus scrape reach the pod IP: set the address they use (for example 0.0.0.0
# behind a NetworkPolicy) or run them as a sidecar.
MANAGEMENT_SERVER_ADDRESS=127.0.0.1
APP_SERVER_SHUTDOWN=graceful
APP_SERVER_SHUTDOWN_TIMEOUT=30s
APP_SERVER_FORWARD_HEADERS_STRATEGY=native
APP_SERVER_FORWARD_HEADERS_STRATEGY=none
APP_SERVER_TOMCAT_MAX_THREADS=200
APP_SERVER_TOMCAT_MIN_SPARE_THREADS=10
APP_SERVER_TOMCAT_ACCEPT_COUNT=100
@@ -42,7 +49,7 @@ APP_DATASOURCE_URL=
APP_DATASOURCE_USERNAME=
APP_DATASOURCE_POOL_MAX_SIZE=10
APP_DATASOURCE_POOL_MIN_IDLE=2
APP_DATASOURCE_CONNECTION_TIMEOUT=5s
APP_DATASOURCE_CONNECTION_TIMEOUT=5000
APP_DATASOURCE_DRIVER=org.postgresql.Driver
APP_DATASOURCE_DDL_AUTO=validate
APP_DATASOURCE_SHOW_SQL=false
@@ -57,7 +64,7 @@ APP_LOG_LEVEL_ROOT=INFO
APP_LOG_LEVEL_APP=INFO
APP_LOG_LEVEL_SPRING=INFO
APP_LOG_LEVEL_WEB=INFO
APP_LOG_LEVEL_SQL=WARN
APP_LOG_LEVEL_SQL=INFO
APP_LOG_FILE_ENABLED=false
APP_LOG_FILE_PATH=logs/ca-skeleton.json
APP_LOG_FILE_MAX_SIZE=100MB
@@ -76,7 +83,7 @@ APP_SECURITY_CORS_ENABLED=false
APP_SECURITY_CORS_ALLOWED_METHODS=
APP_SECURITY_CORS_ALLOWED_HEADERS=*
APP_SECURITY_CORS_ALLOW_CREDENTIALS=false
APP_SECURITY_CORS_MAX_AGE=600s
APP_SECURITY_CORS_MAX_AGE=600
APP_SECURITY_AUTH_MODE=jwt
APP_SESSION_COOKIE_NAME=CA_SESSION
APP_SESSION_COOKIE_SECURE=true
@@ -85,33 +92,16 @@ APP_SESSION_COOKIE_SAME_SITE=Lax
APP_SESSION_COOKIE_PATH=/
APP_SESSION_CSRF_COOKIE_NAME=XSRF-TOKEN
APP_SESSION_CSRF_HEADER_NAME=X-XSRF-TOKEN
APP_SESSION_REDIS_NAMESPACE_ENVIRONMENT=local
APP_SESSION_IDLE_TIMEOUT=30m
APP_SESSION_ABSOLUTE_LIFETIME=8h
APP_SESSION_TOUCH_INTERVAL=1m
APP_SESSION_TOMBSTONE_TTL=5m
APP_SESSION_MAXIMUM_ENVELOPE_BYTES=32768
APP_SESSION_MAXIMUM_ATTRIBUTES=64
APP_SESSION_MAXIMUM_SCALAR_BYTES=8192
APP_SECURITY_JWT_ISSUER=
APP_SECURITY_JWT_AUDIENCE=
APP_RATE_LIMIT_ENABLED=false
APP_RATE_LIMIT_REDIS_ENABLED=false
APP_RATE_LIMIT_PROVIDER=disabled
APP_RATE_LIMIT_FAILURE_POLICY=fail-closed
APP_RATE_LIMIT_DEFAULT_POLICY_ID=api-default
APP_RATE_LIMIT_FAILURE_RETRY_AFTER=100ms
APP_RATE_LIMIT_HASH_KEY_VERSION=1
APP_RATE_LIMIT_KEY_VERSION=1
APP_RATE_LIMIT_REDIS_HOST=
APP_RATE_LIMIT_REDIS_PORT=6379
APP_RATE_LIMIT_REDIS_TRUST_PEM=
APP_SESSION_REDIS_TRUST_PEM=
APP_RATE_LIMIT_REDIS_COMMAND_TIMEOUT=1s
APP_RATE_LIMIT_REDIS_MAXIMUM_COMMAND_BYTES=16384
APP_RATE_LIMIT_REDIS_MAXIMUM_QUEUED_COMMANDS=32
APP_RATE_LIMIT_REDIS_MAXIMUM_IN_FLIGHT_BYTES=1048576
APP_RATE_LIMIT_REDIS_NAMESPACE_ENVIRONMENT=local
APP_RATE_LIMIT_REDIS_COMMAND_TIMEOUT=200ms
APP_RATE_LIMIT_POLICY_REVISION=v1
APP_RATE_LIMIT_ALGORITHM=sliding-counter
APP_RATE_LIMIT_LIMIT=100
@@ -127,12 +117,10 @@ APP_IDEMPOTENCY_TTL=24h
# disabled | redis | postgresql. postgresql refuses a non-PostgreSQL data source, so bootRunH2
# runs with disabled or redis.
APP_IDEMPOTENCY_PROVIDER=disabled
APP_IDEMPOTENCY_REDIS_NAMESPACE_ENVIRONMENT=local
APP_IDEMPOTENCY_PROCESSING_LEASE=30s
# Failure retention: at most 30d and not shorter than APP_IDEMPOTENCY_TTL (startup fails).
APP_IDEMPOTENCY_FAILURE_RETENTION=24h
APP_LEASE_PROVIDER=disabled
APP_LEASE_REDIS_NAMESPACE_ENVIRONMENT=local
APP_LEASE_REDIS_DRIFT_BUDGET=10ms
APP_CACHE_CANONICAL_DEFAULT_PROVIDER=disabled
APP_REDIS_ENABLED=true
@@ -179,32 +167,10 @@ APP_REDIS_TLS_CLIENT_KEY_REFERENCE=
APP_REDIS_TLS_ENABLED=false
APP_REDIS_TLS_HOSTNAME_VERIFICATION=true
APP_REDIS_TLS_TRUST_MATERIAL_RESOURCE=
APP_CACHE_REDIS_ENABLED=false
APP_CACHE_REDIS_CLIENT_MODE=managed
APP_CACHE_REDIS_HOST=
APP_CACHE_REDIS_PORT=6379
APP_CACHE_REDIS_TRUST_PEM=
APP_REDIS_SEMANTIC_PROBE_MINIMUM_INTERVAL=5s
APP_REDIS_SENTINEL_DISCOVERY_REFRESH_PERIOD=30s
APP_REDIS_SEMANTIC_PROBE_MAXIMUM_STALENESS=15s
APP_CACHE_REDIS_COMMAND_TIMEOUT=2s
APP_CACHE_REDIS_MAXIMUM_QUEUED_COMMANDS=8
APP_CACHE_REDIS_MAXIMUM_IN_FLIGHT_BYTES=16777216
APP_CACHE_REDIS_POSITIVE_SOFT_TTL=
APP_CACHE_REDIS_TTL_JITTER=0.10
APP_CACHE_REDIS_COMMAND_TIMEOUT=200ms
APP_CACHE_REDIS_POSITIVE_SOFT_TTL=30s
APP_CACHE_REDIS_MINIMUM_HARD_TTL=1s
APP_CACHE_REDIS_NAMESPACE_ENVIRONMENT=local
APP_CACHE_REDIS_SEMANTIC_REGION=default
APP_CACHE_REDIS_MAXIMUM_VALUE_BYTES=1048576
APP_CACHE_REDIS_L1_ENABLED=false
APP_CACHE_REDIS_L1_MAXIMUM_ENTRIES=10000
APP_CACHE_REDIS_L1_MAXIMUM_WEIGHT_BYTES=67108864
APP_CACHE_REDIS_L1_MAXIMUM_ENTRY_WEIGHT_BYTES=1048576
APP_CACHE_REDIS_L1_TTL=30s
APP_CACHE_REDIS_L1_GENERATION_RECHECK_INTERVAL=5s
APP_CACHE_REDIS_L1_INVALIDATION_QUEUE_CAPACITY=1024
APP_CACHE_DEFAULT_TTL=300s
APP_CACHE_NEGATIVE_TTL=60s
APP_MESSAGING_BROKER=kafka
APP_MESSAGING_PRODUCER_ID=
APP_MESSAGING_KAFKA_BROKERS=
@@ -301,6 +267,9 @@ APP_WEBSOCKET_ENABLED=true
# `false` is the explicit off the Compose lanes set.
APP_OBJECTSTORAGE_ENABLED=true
APP_GRPC_SERVER_ENABLED=true
# The listener is loopback plaintext only; a deployment that selects the gRPC module sets this to
# true or startup refuses.
APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL=false
APP_WEBSOCKET_ENDPOINT=/ws
APP_WEBSOCKET_ALLOWED_ORIGINS=http://localhost:3000
APP_WEBSOCKET_BROADCAST_DESTINATION=/topic/events
@@ -384,10 +353,6 @@ APP_PRIVACY_PSEUDONYMIZATION_SALT=
APP_RATE_LIMIT_REDIS_PASSWORD=
APP_RATE_LIMIT_REDIS_KEY_HMAC_SECRET=
APP_SESSION_REDIS_PASSWORD=
APP_SESSION_REDIS_KEY_HMAC_SECRET=
APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET=
APP_LEASE_REDIS_KEY_HMAC_SECRET=
APP_CACHE_REDIS_PASSWORD=
APP_CACHE_REDIS_KEY_HMAC_SECRET=
APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY=
# The notification platform's seven key purposes. Each is base64 of at least 32 bytes and must
+6 -3
View File
@@ -3,8 +3,9 @@
이 정책을 강제하는 것은
[`scripts/ci/trivy-scan.sh`](../scripts/ci/trivy-scan.sh)(pull request workflow의 `done` job, main·nightly
workflow의 `vulnerabilities` job, release workflow의 이미지 job이 부른다),
[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS,
[`../renovate.json`](../renovate.json)이다.
[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS다. [`../renovate.json`](../renovate.json)은 갱신 PR을 만드는
설정일 뿐 강제 수단이 아니다. 이 repo를 보는 Renovate 실행기가 지금 Gitea에 없어서, 그 설정은 누가 Renovate를 이 repo에
붙일 때부터 쓰인다.
## 실행 위치와 플랫폼 경계
@@ -92,7 +93,9 @@ mirror가 살아 있고 최신인지는 운영이 챙길 의존이다. 낡은 mi
## 의존성 갱신 정책
Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다
Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 실행기가 붙어 있지 않은 동안 갱신은 trivy 실패를 본 관리자가
손으로 한다. GitHub vulnerability alert(`vulnerabilityAlerts`)는 GitHub 호스트에서만 있고, 그 밖에서는
`osvVulnerabilityAlerts`가 근거다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다
(`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가
`./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께
커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를
+12 -7
View File
@@ -152,8 +152,8 @@ ENV HOME=/tmp
# -XX:MaxRAMPercentage=75 — use up to 75% of the container memory limit for heap.
# -XX:+UseContainerSupport — respect cgroup memory limits (default on JDK 10+, explicit here).
# -XX:+ExitOnOutOfMemoryError — terminate immediately on OOM so the orchestrator can restart.
# -XX:+HeapDumpOnOutOfMemoryError / -XX:HeapDumpPath — write a heap dump to the writable
# /var/tmp/heap mount (see tmpfs mounts in compose files, D2).
# -XX:+HeapDumpOnOutOfMemoryError / -XX:HeapDumpPath — write a heap dump to /var/tmp/heap when a
# disk-backed volume is mounted there (see below).
# -Dserver.tomcat.basedir=/tmp — redirect Tomcat temp files to /tmp (D2: read-only root fs).
ENV JAVA_TOOL_OPTIONS="\
-XX:MaxRAMPercentage=75 \
@@ -164,10 +164,13 @@ ENV JAVA_TOOL_OPTIONS="\
-Dserver.tomcat.basedir=/tmp"
# ---- Filesystem layout (D2: read-only root filesystem) ----------------------
# /var/tmp/heap — heap dump landing zone; must be a writable mount at runtime.
# /tmp — Tomcat working directory (see JAVA_TOOL_OPTIONS above).
# Both directories are declared here so tooling is aware of them; at runtime they
# MUST be mounted as tmpfs (or host volumes) by the orchestrator (see compose files).
# /tmp — Tomcat working directory (see JAVA_TOOL_OPTIONS above); a tmpfs at runtime.
# /var/tmp/heap — heap dump landing zone. To keep dumps, mount a disk-backed volume there: in
# Kubernetes an emptyDir without `medium: Memory` (it survives a container restart)
# or a PersistentVolume. Never a tmpfs: it is charged to the container's memory
# limit and vanishes on exit, so the dump only risks an OOM kill. With nothing
# mounted the read-only root refuses the file and the JVM exits 3 at once (compose.yaml).
# Both directories are declared here so tooling is aware of them.
RUN mkdir -p /var/tmp/heap && chmod 1777 /var/tmp/heap
# ---- Non-root user (D3) -----------------------------------------------------
@@ -219,7 +222,9 @@ EXPOSE 8080 9001
# connection adds its own indicator when it is selected — the JPA module adds the datasource — so a
# container started without that dependency reachable is genuinely not ready.
# Kubernetes ignores HEALTHCHECK and uses its own probes against the same path; this exists for
# docker and Compose.
# docker and Compose. A kubelet probe reaches the pod IP, and the management port binds loopback
# by default (MANAGEMENT_SERVER_ADDRESS=127.0.0.1): a Kubernetes deployment sets that address, or
# its probes fail (src/bootstrap/service-runtime/README.md 「management/security」).
#
# wget is present in eclipse-temurin:21-jre-noble, so nothing is installed for it.
HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+5 -2
View File
@@ -116,12 +116,15 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.
1. `settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿, SpotBugs 제외 목록(`config/spotbugs/`), 루트 `build.gradle`과 build-logic의 `group`, registry와 공개 API 스냅숏(`docs/registries/`, `docs/architecture/`, `docs/notification/api-surface-snapshot.txt`)도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다. build-logic 자신의 패키지(`dev.caskeleton.buildlogic`)는 앱 패키지가 아니라 그대로 둬도 된다.
```bash
git grep -l 'dev\.caskeleton' -- src scripts
git grep -l -e 'dev\.caskeleton' -- src scripts config build.gradle docs/registries docs/architecture docs/notification
git grep -l -e '"dev\.caskeleton"' -- build-logic/src/main
```
SpotBugs 목록을 빼먹으면 `qualityCheck`가, 스냅숏을 빼먹으면 각 leaf `check`의 API surface 검사가 실패한다.
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다.
4. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
@@ -34,10 +34,22 @@ public final class ApiSurfacePlugin implements Plugin<Project> {
if (extension.getSourceRoot() != null && !extension.getSourceRoot().isBlank()) {
sourcePaths.add(extension.getSourceRoot());
}
extension.getAdditionalSourceRoots().stream()
.filter(path -> path != null && !path.isBlank())
.forEach(sourcePaths::add);
List<File> roots = sourcePaths.stream().map(project::file).toList();
List<File> additional =
extension.getAdditionalSourceRoots().stream()
.filter(path -> path != null && !path.isBlank())
.map(project::file)
.toList();
// A missing additional root used to be skipped without a word, so an approved update
// recorded a surface with a whole module's types gone (2026-11-12 review).
List<File> missing = additional.stream().filter(root -> !root.isDirectory()).toList();
if (!missing.isEmpty()) {
throw new GradleException(
project.getPath()
+ " apiSurface.additionalSourceRoots names a folder that does not exist: "
+ missing);
}
List<File> roots = new ArrayList<>(sourcePaths.stream().map(project::file).toList());
roots.addAll(additional);
String verifyTaskName = "verify" + label + "ApiSurface";
String updateTaskName = "update" + label + "ApiSurface";
String approvalProperty = "approve" + label + "ApiSurfaceChange";
@@ -9,21 +9,28 @@ import java.util.ArrayList;
import java.util.Collection;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
import java.util.TreeMap;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/** Repository policy for the operator-facing environment contract. No Gradle API. */
public final class EnvContractVerifier {
private static final Pattern ENV_LINE = Pattern.compile("^([A-Z][A-Z0-9_]*)=.*");
private static final Pattern ENV_LINE = Pattern.compile("^([A-Z][A-Z0-9_]*)=(.*)$");
private static final Pattern PLACEHOLDER =
Pattern.compile("\\$\\{([A-Z][A-Z0-9_]*)(:[^}]*)?}");
private static final Pattern SECRET_REFERENCE =
Pattern.compile("secret://environment/(APP_[A-Z][A-Z0-9_]*)");
/**
* A registry row of any name. It used to match {@code APP_} rows only, so the framework-named
* rows ({@code MANAGEMENT_SERVER_ADDRESS}, {@code SPRING_MAIL_*}) were invisible to every rule
* below and a placeholder outside {@code APP_} needed no row at all.
*/
private static final Pattern REGISTRY_NAME =
Pattern.compile("^\\s*- name: (APP_[A-Z0-9_]+)");
Pattern.compile("^\\s*- name: ([A-Z][A-Z0-9_]*)\\s*$");
private static final Pattern REGISTRY_FIELD =
Pattern.compile("^\\s*([a-z_]+):\\s*(\\S.*)?$");
private static final Pattern APP_KEY = Pattern.compile("APP_[A-Z][A-Z0-9_]*");
@@ -114,23 +121,34 @@ public final class EnvContractVerifier {
requireFile(registryFile, "missing " + registryFile);
Set<String> envKeys = new TreeSet<>();
Map<String, String> envValues = new TreeMap<>();
for (String line : readLines(envFile)) {
Matcher matcher = ENV_LINE.matcher(line);
if (matcher.matches()) {
envKeys.add(matcher.group(1));
envValues.put(matcher.group(1), matcher.group(2).trim());
}
}
Set<String> requiredPlaceholders = new TreeSet<>();
Set<String> allPlaceholders = new TreeSet<>();
Set<String> environmentSecretReferences = new TreeSet<>();
// name -> the literal defaults the non-profile shipped files give it ("" for ${KEY:}). A
// profile file (application-<profile>.yml) overrides on purpose and is not compared; a default
// that nests another placeholder is not a literal and is not compared either.
Map<String, Set<String>> shippedDefaults = new TreeMap<>();
for (File configurationFile : configurationFiles) {
String configuration = read(configurationFile);
boolean profileFile = configurationFile.getName().startsWith("application-");
Matcher placeholderMatcher = PLACEHOLDER.matcher(configuration);
while (placeholderMatcher.find()) {
allPlaceholders.add(placeholderMatcher.group(1));
if (placeholderMatcher.group(2) == null) {
requiredPlaceholders.add(placeholderMatcher.group(1));
} else if (!profileFile && !placeholderMatcher.group(2).contains("${")) {
shippedDefaults
.computeIfAbsent(placeholderMatcher.group(1), name -> new TreeSet<>())
.add(normalizedValue(placeholderMatcher.group(2).substring(1)));
}
}
Matcher secretMatcher = SECRET_REFERENCE.matcher(configuration);
@@ -139,10 +157,9 @@ public final class EnvContractVerifier {
}
}
Set<String> applicationAppReferences = new TreeSet<>();
allPlaceholders.stream()
.filter(name -> name.startsWith("APP_"))
.forEach(applicationAppReferences::add);
// Every name the shipped configuration reads, whatever its prefix: a placeholder outside APP_
// (SECURITY_PUBLIC_PATHS opens paths to anonymous callers) needs a row as much as an APP_ one.
Set<String> applicationAppReferences = new TreeSet<>(allPlaceholders);
applicationAppReferences.addAll(environmentSecretReferences);
failUnlessEmpty(
@@ -152,26 +169,80 @@ public final class EnvContractVerifier {
List<EnvRegistryRow> registryRows = parseRegistryRows(registryFile);
Set<String> registryAppKeys = new TreeSet<>();
Set<String> registryProperties = new TreeSet<>();
Set<String> liveAppRows = new TreeSet<>();
Set<String> deprecatedRows = new TreeSet<>();
for (EnvRegistryRow row : registryRows) {
registryAppKeys.add(row.name());
row.property().ifPresent(registryProperties::add);
if (row.deprecatedOrphaned()) {
deprecatedRows.add(row.name());
} else if (row.name().startsWith("APP_")) {
liveAppRows.add(row.name());
}
}
failUnlessEmpty(
difference(registryAppKeys, envKeys),
difference(liveAppRows, envKeys),
"docs/registries/env-keys.yaml registers APP_ keys absent from .env.example, so an "
+ "adopter copying the example never sees them: ");
Set<String> envAppKeys = new TreeSet<>();
envKeys.stream().filter(name -> name.startsWith("APP_")).forEach(envAppKeys::add);
failUnlessEmpty(
difference(envAppKeys, registryAppKeys),
".env.example declares APP_ keys absent from docs/registries/env-keys.yaml "
+ "(registry is the SSOT for APP_ keys): ");
intersection(deprecatedRows, envKeys),
".env.example sets keys the registry marks deprecated_orphaned — an adopter who copies it"
+ " sets a variable nothing reads and believes it is in force: ",
" — take the line out; the registry row stays to tell a deployment that still sets it.");
failUnlessEmpty(
intersection(deprecatedRows, applicationAppReferences),
"docs/registries/env-keys.yaml marks keys deprecated_orphaned that the shipped"
+ " configuration still reads: ",
" — the row says nothing reads them and tells deployments to stop setting them; restore"
+ " the row (and its default) or remove the placeholder.");
failUnlessEmpty(
difference(envKeys, registryAppKeys),
".env.example declares keys absent from docs/registries/env-keys.yaml "
+ "(registry is the SSOT): ");
failUnlessEmpty(
difference(applicationAppReferences, registryAppKeys),
"shipped configuration references APP_ keys absent from docs/registries/env-keys.yaml "
+ "(optional defaults and environment secret references are included): ");
"shipped configuration references env keys absent from docs/registries/env-keys.yaml "
+ "(any prefix; optional defaults and environment secret references are included): ");
List<String> valueMismatches = new ArrayList<>();
for (EnvRegistryRow row : registryRows) {
String expected = row.exampleValue();
String written = envValues.get(row.name());
if (written != null && !normalizedValue(written).equals(expected)) {
valueMismatches.add(
row.name()
+ ": .env.example writes '"
+ written
+ "', the registry "
+ (row.example().isPresent() ? "example" : "default")
+ " is '"
+ expected
+ "'"
+ (written.isEmpty()
? " (a blank line sets an empty string, which replaces the default)"
: ""));
}
Set<String> defaults = shippedDefaults.getOrDefault(row.name(), Set.of());
String registered = row.defaultValue().orElse("");
for (String shipped : defaults) {
if (!shipped.equals(registered)) {
valueMismatches.add(
row.name()
+ ": the shipped configuration defaults to '"
+ shipped
+ "', the registry default is '"
+ registered
+ "'");
}
}
}
failUnlessEmpty(
valueMismatches,
"env values disagree with docs/registries/env-keys.yaml: ",
" — the registry default is what the shipped configuration falls back to, and"
+ " .env.example writes that default (or the row's example:).");
Set<String> declared = ConfigurationMetadataClasspath.propertiesUnder(metadataClasspath, "");
Set<String> typedProperties = new TreeSet<>();
@@ -351,6 +422,10 @@ public final class EnvContractVerifier {
current.property = value;
} else if (key.equals("deprecated_orphaned")) {
current.deprecatedOrphaned = Boolean.parseBoolean(value);
} else if (key.equals("default")) {
current.defaultValue = normalizedValue(value);
} else if (key.equals("example")) {
current.example = normalizedValue(value);
}
}
if (current != null) {
@@ -391,6 +466,25 @@ public final class EnvContractVerifier {
}
}
private static Set<String> intersection(Collection<String> left, Collection<String> right) {
Set<String> result = new TreeSet<>(left);
result.retainAll(new HashSet<>(right));
return result;
}
/** A registry or env value without YAML quotes; {@code null}, {@code ~} and blank are "". */
private static String normalizedValue(String raw) {
String value = raw.trim();
if (value.length() >= 2
&& (value.startsWith("\"") && value.endsWith("\"")
|| value.startsWith("'") && value.endsWith("'"))) {
value = value.substring(1, value.length() - 1);
} else if (value.equals("null") || value.equals("~")) {
value = "";
}
return value;
}
private static Set<String> difference(Collection<String> left, Collection<String> right) {
Set<String> result = new TreeSet<>(left);
result.removeAll(new HashSet<>(right));
@@ -417,13 +511,20 @@ public final class EnvContractVerifier {
private final String name;
private String property;
private boolean deprecatedOrphaned;
private String defaultValue;
private String example;
private RowBuilder(String name) {
this.name = name;
}
private EnvRegistryRow build() {
return new EnvRegistryRow(name, Optional.ofNullable(property), deprecatedOrphaned);
return new EnvRegistryRow(
name,
Optional.ofNullable(property),
deprecatedOrphaned,
Optional.ofNullable(defaultValue).filter(value -> !value.isEmpty()),
Optional.ofNullable(example));
}
}
}
@@ -3,10 +3,33 @@ package dev.caskeleton.buildlogic.config;
import java.util.Objects;
import java.util.Optional;
/**
* One {@code env-keys.yaml} row as the environment contract reads it.
*
* @param defaultValue the row's {@code default:}, empty when it is {@code null} or blank — the
* value the shipped configuration falls back to and {@code .env.example} writes
* @param example the row's {@code example:}, the value {@code .env.example} writes instead of the
* default (a recommended production value such as the SMTP submission port)
*/
public record EnvRegistryRow(
String name, Optional<String> property, boolean deprecatedOrphaned) {
String name,
Optional<String> property,
boolean deprecatedOrphaned,
Optional<String> defaultValue,
Optional<String> example) {
public EnvRegistryRow {
Objects.requireNonNull(name, "name");
property = property == null ? Optional.empty() : property;
defaultValue = defaultValue == null ? Optional.empty() : defaultValue;
example = example == null ? Optional.empty() : example;
}
public EnvRegistryRow(String name, Optional<String> property, boolean deprecatedOrphaned) {
this(name, property, deprecatedOrphaned, Optional.empty(), Optional.empty());
}
/** What {@code .env.example} must write for this row: the example, else the default. */
public String exampleValue() {
return example.or(() -> defaultValue).orElse("");
}
}
@@ -3,6 +3,14 @@ package dev.caskeleton.buildlogic.convention;
import org.gradle.api.Plugin;
import org.gradle.api.Project;
/**
* Quality conventions plus the Spring Boot test starter for a Spring library leaf.
*
* <p>Only {@code spring-boot-starter-test}. The web MVC test starter (MockMvc, {@code @WebMvcTest},
* and an embedded Tomcat with them) used to be added to every leaf here, so thirty leaves resolved
* and locked a servlet container for tests that never start one. A leaf whose tests use MockMvc
* declares {@code spring-boot-starter-webmvc-test} in its own build script (2026-11-12 review).
*/
public final class SpringLibraryConventionPlugin implements Plugin<Project> {
@Override
public void apply(Project project) {
@@ -10,8 +18,5 @@ public final class SpringLibraryConventionPlugin implements Plugin<Project> {
project
.getDependencies()
.add("testImplementation", "org.springframework.boot:spring-boot-starter-test");
project
.getDependencies()
.add("testImplementation", "org.springframework.boot:spring-boot-starter-webmvc-test");
}
}
@@ -310,7 +310,14 @@ public final class JavaConventionsPlugin implements Plugin<Project> {
return catalog;
}
private static Map<String, String> containerImages(File catalog) {
/**
* The catalog, refused when an image is not pinned by digest.
*
* <p>The catalog's header promises digests: a red lane should mean this repository changed, not
* that a registry moved a tag. Two images were tag-only for weeks with a note to pin them later
* (2026-11-12 review), and nothing noticed, so the promise is checked where the file is read.
*/
static Map<String, String> containerImages(File catalog) {
Properties properties = new Properties();
try (var in = Files.newInputStream(catalog.toPath())) {
properties.load(in);
@@ -319,6 +326,18 @@ public final class JavaConventionsPlugin implements Plugin<Project> {
}
Map<String, String> images = new TreeMap<>();
properties.stringPropertyNames().forEach(key -> images.put(key, properties.getProperty(key)));
List<String> unpinned =
images.entrySet().stream()
.filter(entry -> !entry.getValue().contains("@sha256:"))
.map(Map.Entry::getKey)
.toList();
if (!unpinned.isEmpty()) {
throw new GradleException(
catalog.getName()
+ ": pin every image by digest (repository@sha256:...), with its tag in a comment;"
+ " not pinned: "
+ unpinned);
}
return Map.copyOf(images);
}
}
@@ -173,6 +173,27 @@ class ApiSurfaceConventionTest {
""");
}
@Test
@org.junit.jupiter.api.DisplayName("없는 추가 source root는 건너뛰지 않고 그 경로를 짚어 실패한다")
void aMissingAdditionalSourceRootFailsInsteadOfShrinkingTheSurface() throws Exception {
// given
Files.writeString(
projectDir.resolve("build.gradle"),
Files.readString(projectDir.resolve("build.gradle"))
.replace(
"baseline = file('surface.txt')",
"baseline = file('surface.txt')\n additionalSourceRoots = ['../moved/src/main/java']"));
// when
BuildResult result =
runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").buildAndFail();
// then
assertTrue(
result.getOutput().contains("additionalSourceRoots names a folder that does not exist"),
result.getOutput());
}
private void writeConfiguredBuild(String sourceRoot) throws Exception {
Files.writeString(
projectDir.resolve("build.gradle"),
@@ -102,7 +102,7 @@ class EnvContractVerifierTest {
Files.readString(fixture.registry())
+ "- name: APP_REDIS_UNUSED\n"
+ " type: string\n"
+ " default: null\n");
+ " default: present-but-unread\n");
IllegalStateException failure =
assertThrows(
@@ -142,7 +142,7 @@ class EnvContractVerifierTest {
List.of("APP_REDIS_"),
List.of()));
assertTrue(failure.getMessage().contains("shipped configuration references APP_ keys"));
assertTrue(failure.getMessage().contains("shipped configuration references env keys"));
assertTrue(failure.getMessage().contains("APP_SECONDARY_ONLY"));
}
@@ -356,7 +356,7 @@ class EnvContractVerifierTest {
Files.writeString(
fixture.registry(),
Files.readString(fixture.registry())
+ "- name: APP_GHOST_ENABLED\n property: app.ghost.enabled\n type: boolean\n");
+ "- name: APP_GHOST_ENABLED\n property: app.ghost.enabled\n type: boolean\n default: true\n");
Path compose = fixture.repositoryRoot().resolve("compose.yaml");
Files.writeString(
compose, "services:\n app:\n environment:\n APP_GHOST_ENABLED: \"true\"\n");
@@ -381,7 +381,7 @@ class EnvContractVerifierTest {
Files.writeString(
fixture.registry(),
Files.readString(fixture.registry())
+ "- name: APP_GHOST_ENABLED\n property: app.ghost.enabled\n type: boolean\n");
+ "- name: APP_GHOST_ENABLED\n property: app.ghost.enabled\n type: boolean\n default: true\n");
Path ghostClasses = fixture.repositoryRoot().resolve("adapter/ghost/build/classes/java/main");
Files.createDirectories(ghostClasses.resolve("META-INF"));
Files.writeString(
@@ -398,6 +398,167 @@ class EnvContractVerifierTest {
assertEquals(3, result.envKeyCount());
}
@Test
@DisplayName("APP_ 밖 이름의 placeholder도 레지스트리에 없으면 실패한다")
void aPlaceholderOutsideTheAppPrefixMustBeRegistered(@TempDir Path temp) throws Exception {
// given
Fixture fixture = fixture(temp);
Files.writeString(
fixture.applicationYaml(),
Files.readString(fixture.applicationYaml()) + "paths: ${SECURITY_PUBLIC_PATHS:/v1/health}\n");
// when
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> verify(fixture));
// then
assertTrue(failure.getMessage().contains("shipped configuration references env keys absent"));
assertTrue(failure.getMessage().contains("SECURITY_PUBLIC_PATHS"));
}
@Test
@DisplayName("APP_ 밖 이름의 레지스트리 행도 placeholder를 등록한 것으로 친다")
void aFrameworkNamedRegistryRowRegistersItsPlaceholder(@TempDir Path temp) throws Exception {
// given
Fixture fixture = fixture(temp);
Files.writeString(
fixture.applicationYaml(),
Files.readString(fixture.applicationYaml())
+ "address: ${MANAGEMENT_SERVER_ADDRESS:127.0.0.1}\n");
Files.writeString(
fixture.registry(),
Files.readString(fixture.registry())
+ "- name: MANAGEMENT_SERVER_ADDRESS\n type: string\n default: 127.0.0.1\n");
// when
EnvContractResult result = verify(fixture);
// then
assertEquals(3, result.applicationReferenceCount());
}
@Test
@DisplayName("deprecated_orphaned 행의 키를 .env.example이 아직 쓰면 실패한다")
void aDeprecatedKeyTheExampleStillSetsFails(@TempDir Path temp) throws Exception {
// given
Fixture fixture = fixture(temp);
Files.writeString(
fixture.envFile(), Files.readString(fixture.envFile()) + "APP_REDIS_OLD=2s\n");
Files.writeString(
fixture.registry(),
Files.readString(fixture.registry())
+ "- name: APP_REDIS_OLD\n deprecated_orphaned: true\n type: duration\n default: 2s\n");
// when
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> verify(fixture));
// then
assertTrue(failure.getMessage().contains("marks deprecated_orphaned"));
assertTrue(failure.getMessage().contains("APP_REDIS_OLD"));
}
@Test
@DisplayName("deprecated_orphaned 행의 키를 배포 설정이 아직 읽으면 실패한다")
void aDeprecatedKeyTheConfigurationStillReadsFails(@TempDir Path temp) throws Exception {
// given
Fixture fixture = fixture(temp);
Files.writeString(
fixture.applicationYaml(),
Files.readString(fixture.applicationYaml()) + "timeout: ${APP_REDIS_OLD:200ms}\n");
Files.writeString(
fixture.registry(),
Files.readString(fixture.registry())
+ "- name: APP_REDIS_OLD\n deprecated_orphaned: true\n type: duration\n default: 200ms\n");
// when
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> verify(fixture));
// then
assertTrue(failure.getMessage().contains("that the shipped configuration still reads"));
assertTrue(failure.getMessage().contains("APP_REDIS_OLD"));
}
@Test
@DisplayName(".env.example 값이 레지스트리 기본값과 다르면 실패하고, 빈 줄은 빈 문자열로 친다")
void anExampleValueThatIsNotTheRegistryDefaultFails(@TempDir Path temp) throws Exception {
// given
Fixture fixture = fixture(temp);
Files.writeString(fixture.envFile(), "APP_REQUIRED=required\nAPP_REDIS_HOST=\n");
// when
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> verify(fixture));
// then
assertTrue(failure.getMessage().contains("APP_REDIS_HOST: .env.example writes ''"));
assertTrue(failure.getMessage().contains("a blank line sets an empty string"));
}
@Test
@DisplayName("행의 example 값을 .env.example이 쓰면 기본값과 달라도 통과한다")
void anExampleValueTheRowNamesPasses(@TempDir Path temp) throws Exception {
// given
Fixture fixture = fixture(temp);
Files.writeString(
fixture.envFile(), Files.readString(fixture.envFile()) + "SPRING_MAIL_PORT=587\n");
Files.writeString(
fixture.registry(),
Files.readString(fixture.registry())
+ "- name: SPRING_MAIL_PORT\n type: integer\n default: null\n example: 587\n");
// when
EnvContractResult result = verify(fixture);
// then
assertEquals(3, result.envKeyCount());
}
@Test
@DisplayName("배포 설정의 기본값이 레지스트리 기본값과 다르면 실패하고, profile 파일은 비교하지 않는다")
void aShippedDefaultThatIsNotTheRegistryDefaultFails(@TempDir Path temp) throws Exception {
// given
Fixture fixture = fixture(temp);
Path profile = fixture.applicationYaml().resolveSibling("application-local.yml");
Files.writeString(profile, "redis: ${APP_REDIS_HOST:127.0.0.1}\n");
Files.writeString(
fixture.applicationYaml(),
"required: ${APP_REQUIRED}\nredis: ${APP_REDIS_HOST:redis.internal}\n");
// when
IllegalStateException failure =
assertThrows(
IllegalStateException.class,
() ->
EnvContractVerifier.verify(
fixture.envFile().toFile(),
List.of(fixture.applicationYaml().toFile(), profile.toFile()),
fixture.registry().toFile(),
List.of(),
fixture.metadataClasspath(),
List.of("app.redis."),
List.of("APP_REDIS_"),
List.of()));
// then
assertTrue(
failure
.getMessage()
.contains(
"APP_REDIS_HOST: the shipped configuration defaults to 'redis.internal', the"
+ " registry default is 'localhost'"));
assertTrue(!failure.getMessage().contains("127.0.0.1"), failure.getMessage());
}
private static EnvContractResult verify(Fixture fixture) {
return EnvContractVerifier.verify(
fixture.envFile().toFile(),
List.of(fixture.applicationYaml().toFile()),
fixture.registry().toFile(),
List.of(),
fixture.metadataClasspath(),
List.of("app.redis."),
List.of("APP_REDIS_"),
List.of());
}
private static EnvContractResult verifyWithOperatorFiles(
Fixture fixture, Path operatorFile, Path... otherModuleClasses) {
List<File> classpath = new ArrayList<>(fixture.metadataClasspath());
@@ -435,7 +596,7 @@ class EnvContractVerifierTest {
applicationYaml, "required: ${APP_REQUIRED}\nredis: ${APP_REDIS_HOST:localhost}\n");
Files.writeString(
registry,
"- name: APP_REQUIRED\n type: string\n default: none\n"
"- name: APP_REQUIRED\n type: string\n default: required\n"
+ "- name: APP_REDIS_HOST\n property: app.redis.host\n type: string\n default: localhost\n");
Files.writeString(metadata, "{\"properties\":[{\"name\":\"app.redis.host\"}]}");
return new Fixture(repositoryRoot, envFile, applicationYaml, registry, redisClasses, metadata);
@@ -0,0 +1,50 @@
package dev.caskeleton.buildlogic.java;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import org.gradle.api.GradleException;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
class ContainerImageCatalogTest {
@Test
@DisplayName("digest 없이 tag만 적은 이미지는 목록을 읽는 단계에서 그 키를 짚어 실패한다")
void aTagOnlyImageFailsNamingItsKey(@TempDir Path directory) throws IOException {
// given
Path catalog = directory.resolve("container-images.properties");
Files.writeString(
catalog,
"pinned=postgres@sha256:"
+ "0".repeat(64)
+ "\nfloating=postgres:17-alpine\n");
// when
Throwable failure = catchThrowable(() -> JavaConventionsPlugin.containerImages(catalog.toFile()));
// then
assertThat(failure)
.isInstanceOf(GradleException.class)
.hasMessageEndingWith("not pinned: [floating]");
}
@Test
@DisplayName("모든 이미지가 digest로 고정된 목록은 키와 값을 그대로 돌려준다")
void aDigestPinnedCatalogIsReadAsIs(@TempDir Path directory) throws IOException {
// given
Path catalog = directory.resolve("container-images.properties");
String image = "postgres@sha256:" + "a".repeat(64);
Files.writeString(catalog, "# postgres:17-alpine\npostgres-17=" + image + "\n");
// when
var images = JavaConventionsPlugin.containerImages(catalog.toFile());
// then
assertThat(images).containsExactly(java.util.Map.entry("postgres-17", image));
}
}
+12 -7
View File
@@ -85,10 +85,11 @@ services:
required: false
ports:
- "${APP_SERVER_PORT:-8080}:8080"
# 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"
# Management (health, info, prometheus — answered without authentication) is not published.
# It binds the container's loopback (MANAGEMENT_SERVER_ADDRESS, default 127.0.0.1), so a host
# port mapped to it would answer nothing, and binding 0.0.0.0 to publish it would open it to
# every container on the network as well. The healthcheck and the smoke lanes read it from
# inside the container: `docker compose exec app wget -qO- http://localhost:9001/actuator/health`.
environment:
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
# environment the application believes it is in. The dev and prod-smoke lane overlays set
@@ -107,13 +108,17 @@ services:
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
# ---- Read-only root filesystem (D2) -------------------------------------
# The application must write only to the tmpfs mounts declared below.
# The application must write only to the tmpfs mount declared below.
# /tmp — Tomcat basedir (see -Dserver.tomcat.basedir=/tmp in Dockerfile).
# /var/tmp/heap — heap dump landing zone (see -XX:HeapDumpPath=/var/tmp/heap).
# /var/tmp/heap — the heap dump path (-XX:HeapDumpPath) — is deliberately not a tmpfs. A tmpfs is
# charged to this container's mem_limit and is gone once the container exits, so a dump written
# there at an OutOfMemoryError could only turn the clean exit 3 into an OOM kill, and was never
# there to read. On the read-only root the JVM cannot create the file and exits 3 at once. The
# dev lane mounts a volume there to keep dumps; scripts/verify-compose-profile-contracts.sh
# refuses a tmpfs at that path in every lane.
read_only: true
tmpfs:
- /tmp:mode=1777,size=128m
- /var/tmp/heap:mode=1777,size=512m
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
# mount in its own overlay, added with -f when the capability is selected, so this file never
# names one (07-08).
-10
View File
@@ -59,16 +59,6 @@
<Source name="DefaultTypingFixture.java"/>
</Match>
<!-- Micrometer holds gauge referents weakly, so a gauge whose source object is collected
reports NaN forever afterwards. The only way to assert that the notification metrics do
NOT have that defect is to provoke a collection, which is what DM_GC flags. Scoped to the
single test method that does it; a System.gc() anywhere else remains reportable. -->
<Match>
<Bug pattern="DM_GC"/>
<Class name="dev.caskeleton.bootstrap.autoconfigure.notification.observation.NotificationObservationTest"/>
<Method name="aGaugeKeepsReportingAfterGarbageCollectionInsteadOfDecayingToNaN"/>
</Match>
<!-- =========================================================================================
Confidence MEDIUM (review 2026-11-01 08-07). Everything below was added when the report
level went from HIGH to MEDIUM. Each entry was judged against the code it names; defects
+1 -1
View File
@@ -33,7 +33,7 @@
| `registries/` | 레지스트리: env 키, 오류 코드, 메트릭, HTTP 헤더, 로그(MDC) 키, 비밀 분류, use case capability, 객체 저장소 준비도. 테스트가 코드와 대조한다 |
| `web/` | HTTP wire 계약(`web/http-contract.md`), PATCH·스트리밍 계약, 선택형 web 기능(`web-advanced`), web 장애 대응 |
| `architecture/` | 공개 API 표면 스냅숏(`*-api-surface.txt`). API surface 검사가 대조한다 |
| `security/` | 기본 공개 경로 스냅숏. `verifyPublicPathSnapshot`이 대조한다 |
| `security/` | 공개 경로 스냅숏(`verifyPublicPathSnapshot`이 대조한다)과 요청률 제한을 어디서 거는지(`rate-limiting.md`) |
| `observability/` | 구조화 로그 필드 사전 |
### 영역 운영 문서
+3 -3
View File
@@ -1,8 +1,8 @@
# GraphQL leaf public API surface — every public top-level type in src/main/java.
# A public type in a single-jar leaf is reachable from every adopter's code, so
# additions are reviewed rather than discovered. `api` and `spi` are the intended
# external surface; the rest are candidates to become internal when this leaf is
# split into capability artifacts.
# additions are reviewed rather than discovered. `api` is the intended external
# surface; the rest are candidates to become internal when this leaf is split into
# capability artifacts.
# Update only after review with:
# ./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange
# types: 161
+30 -30
View File
@@ -20,18 +20,21 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
(`config/checkstyle/checkstyle.xml`). 줄 길이·들여쓰기·import 순서 모듈이 여기에 없는 것은 누락이
아니라 포매터와 싸우지 않기 위한 선택이다. Error Prone은 컴파일 시점 버그 패턴을 담당한다.
무엇이 어느 단계에서 도는지의 정본은 `docs/work/reference/gates.md` 1절과 루트 `build.gradle`의 단계 태스크다. 아래 표는
태스크 하나하나가 하는 일이다.
| 게이트 | 하는 일 |
| --- | --- |
| `architectureCheck` | Clean Architecture 의존 방향, domain-core·shared-contract·application-* 순수성, Git에 실리지 않는 source package, ArchUnit을 검사 |
| `qualityCheck` | 모든 leaf의 SpotBugs + FindSecBugs를 실행 |
| `configContractCheck` | `:app-bootstrap:verifyEnvKeys`로 환경 설정 계약을 검사 |
| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 |
| `qualificationCheck` | 전체 기동(system) 레인(`systemTestCheck`), 보조 source set Checkstyle, 시험 품질 검사(`testQualityCheck`)를 실행 |
| `integrationCheck` | 선언된 strict integration lane을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `main.yml` `performance` job이 nightly에 다른 무거운 job 뒤에서 같은 명령으로 돌림 |
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계(`prCheck`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 단계마다 선언한 workflow job이 `./gradlew <단계>`를 정해진 한 줄로 조건 없이(또는 선언한 조건으로) 돌리는지 검사. 형식은 `build-logic/AGENTS.md` 「단계 job의 모양」. PR 단계가 돌림 |
| `prCheck` | PR 단계: `ci` + `verifyDependencyLocks` + compose 렌더링(`verifyComposeProfiles`) + 저장소 배치(`verifyRepositoryLayout`) + 작업 지침 분량·이력 ID(`verifyWorkDocs`) + 문서 검사(`documentCheck`) |
| `ci` | 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + `verifyPublicPathSnapshot` + 전송·메시징 qualification(`conditionalTransportQualification`, `verifyMessagingContracts`) + graphql 전송 경계 lane(`graphqlStableTest`) + 생성 명령 왕복(`verifyFeatureScaffold`) + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
따라서 로컬에서 한 모듈만 수정했다면 `./gradlew :domain-core:check`처럼 focused task를
@@ -48,10 +51,10 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
### 로컬 첫 실행
`scripts/bootstrap-local.sh`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 →
app 기동(Flyway 포함) → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, 리뷰
BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김).
DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, app startup Flyway가
끝나 public health endpoint가 준비되어야 다음 단계로 넘어간다. `.env.example`은 커밋된
app 기동 → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, build-logic 플러그인에서 스크립트로 옮김).
DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, public health
endpoint가 준비되어야 다음 단계로 넘어간다. 기본 조립은 web뿐이라 datasource를 열지 않고 Flyway도 돌지 않는다.
persistence-jpa 줄을 켠 서비스는 그 대기 안에서 startup Flyway가 끝난다. `.env.example`은 커밋된
env 계약이고 `.env`는 로컬 실행 입력이다. `verifyEnvKeys`는 example/registry/shipped YAML을
함께 검사한다.
@@ -147,28 +150,22 @@ Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돈다
### `verifyPublicPathSnapshot`
- **하는 일.** deny-by-default public path 표면이 승인 없이 바뀌면 빌드를 실패시킨다.
- **배경.** 이 앱은 deny-by-default이다. 즉 `SECURITY_PUBLIC_PATHS` 가 먹이는 명시적 `permitAll()`
경로를 **제외한** 모든 요청은 인증을 요구한다
(`src/bootstrap/app/src/main/resources/config/security.yml` → `SecuritySettings.publicPaths()` →
`SecurityConfig`). 설정 분할 이전에는 이 SSOT 가 `.env` 였고 문서만 그대로 남아 있었다.
스냅샷 플러그인이 실제로 읽는 파일은 `config/security.yml`이다
(`build-logic/.../publicpath/PublicPathSnapshotPlugin.java`).
이 public 표면이 바뀌는 순간이 곧 보호되던 엔드포인트가 조용히 공개로 노출되는 지점이다.
그래서 그 표면을 snapshot 으로 떠 두고, 미승인 변경에 빌드를 실패시킨다.
- **승인 방법.** `verifyPublicPathSnapshot` 은 항상 읽기 전용이다. reviewer 가 변경을 승인한 뒤
`./gradlew updatePublicPathSnapshot -PapprovePublicPathChange` 로 snapshot 을 명시적으로 다시
생성한다. 공개 경로 변경은 보안 리뷰 대상으로 보고 재생성된 snapshot 을 함께 커밋한다.
- **결정 — 무엇을 snapshot 했나 (프로젝트 선택).** 초기안은 기동 시
`SecurityFilterChain.getFilters()` 를 introspection 하는 방식이었다. 하지만 그 reflection
은 Spring 버전마다 깨지기 쉽다(`permitAll` matcher 가
`RequestMatcherDelegatingAuthorizationManager` 의 private 필드에 숨어 있음). 그래서 `permitAll()`
을 실제로 먹이는 결정적 SSOT 인 `SECURITY_PUBLIC_PATHS` 자체를 snapshot 한다. 탐지 목표(공개 경로
변경은 무조건 게이트를 실패시킨다)는 같고, 메커니즘은 더 견고하다.
- **snapshot 위치.** `docs/security/public-paths-snapshot.txt`. 이 파일은 커밋된 필수 보안
baseline이다. CI 는 Gradle 실행 전에 파일이 비어 있지 않고 Git에 추적되는지 검사하므로 fresh
checkout 에서 누락되거나 untracked 상태면 즉시 실패한다. 승인된 변경만 update task로 재생성한
뒤 보안 리뷰와 함께 커밋한다.
- **하는 일.** 인증 없이 들어올 수 있는 표면이 승인 없이 바뀌면 빌드를 실패시킨다. main 단계(`mainCheck`)와
`releaseCheck`의 lane `:app-bootstrap:publicPathSnapshotTest`다.
- **스냅숏에 드는 셋.** `docs/security/public-paths-snapshot.txt`의 세 절이다.
- 기본 공개 경로: `src/bootstrap/app/src/main/resources/config/security.yml`의 `app.security.public-paths` 기본값
(`SecuritySettings.publicPaths()` → web `SecurityConfig`의 `permitAll()`).
- profile이 덮는 값: `application-<profile>.yml`이 `public-paths`를 리터럴로 덮으면 그 값.
- 모듈 chain: 모든 leaf의 운영 코드에서 Spring Security를 쓰는 파일의 `permitAll` 문장과 chain 범위
(`securityMatcher`) 문장. 알림 callback chain, actuator chain이 여기에 든다. 문장 글자가 바뀌면(새 matcher,
넓어진 pattern) 스냅숏이 바뀐다.
- **못 보는 것.** 운영자가 배포 env(`SECURITY_PUBLIC_PATHS`)로 준 값, 그리고 matcher를 상수나 변수로 다른 줄에서
만든 경우의 그 값(문장 글자만 본다). 그런 변경은 리뷰가 본다.
- **승인 방법.** 리뷰가 변경을 받은 뒤 `./gradlew verifyPublicPathSnapshot -PapprovePublicPathChange`로 스냅숏을 다시
쓰고 함께 커밋한다. 플래그 없이 돌리면 비교만 한다.
- **결정 — 무엇을 스냅숏하나.** 기동한 `SecurityFilterChain`의 matcher를 reflection으로 읽는 안은 Spring 버전마다
깨진다(`permitAll` matcher가 `RequestMatcherDelegatingAuthorizationManager`의 private 필드에 있다). 그래서 설정의
기본값과 소스의 `permitAll` 문장을 글자로 고정한다.
### Trivy suppression과 플래키 격리 — 정책은 유지, 파서는 삭제
@@ -276,7 +273,7 @@ Kafka 없이 기동한다. 나머지 기능은 `src/bootstrap/app/build.gradle`
| WebSocket (STOMP push) | `runtimeOnly project(':adapter:inbound:websocket')` | 없음(기본값으로 동작). origin은 `APP_WEBSOCKET_ALLOWED_ORIGINS` | `APP_WEBSOCKET_ENABLED` |
| gRPC 서버 | `runtimeOnly project(':adapter:inbound:grpc')` | `APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL=true` (지금 받는 listener가 loopback plaintext뿐) | `app.grpc.server.enabled` |
| 파일 서버 (JPA를 함께 가져옴) | `runtimeOnly project(':composition:fileserver-platform')` | `APP_FILESERVER_PLATFORM_STORAGE_ROOT`, `APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY`, 그리고 `FileAccessPolicyPort` bean 또는 `APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY=role-based` | `APP_FILESERVER_PLATFORM_ENABLED` |
| 알림 (SMTP/SES, JPA 줄도 필요) | `runtimeOnly project(':composition:notification-platform')` | 키 8종과 각 `_ID`(`APP_NOTIFICATION_PLATFORM_*_KEY`, `*_KEY_ID`), 쓰는 provider 설정(`APP_NOTIFICATION_PLATFORM_SMTP_*` 또는 `_SES_*`) | `APP_NOTIFICATION_PLATFORM_ENABLED` |
| 알림 (SMTP/SES, JPA 줄도 필요) | `runtimeOnly project(':composition:notification-platform')` | 키와 각 `_ID`(`APP_NOTIFICATION_PLATFORM_*_KEY`, `*_KEY_ID`, 목록은 registry), 쓰는 provider 설정(`APP_NOTIFICATION_PLATFORM_SMTP_*` 또는 `_SES_*`) | `APP_NOTIFICATION_PLATFORM_ENABLED` |
전체 목록과 타입·기본값은 `docs/registries/env-keys.yaml`, 각 모듈이 제공하는 것은 그 모듈 README의
"제공하는 것 · 추가할 한 줄 · env 키" 절에 있다. 기능 사이의 의존(알림·파일 서버 → JPA, outbox relay
@@ -410,7 +407,7 @@ app:
### 분산 추적
- **`OTEL_EXPORTER_OTLP_ENDPOINT`** — OTLP exporter endpoint. 빈 값 = exporter off(스켈레톤에서 OTel
SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증한다.
SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingSettings` 가 검증한다.
- **`APP_TRACING_ENABLED`** — `false` 면 tracing seam 은 꺼지지만, `meta.traceId` 는
`WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성한다(D4 disabled-fallback 보장).
- **`APP_TRACING_SAMPLE_RATE`** — per-profile 기본값을 덮어쓰는 샘플 비율. [0.0, 1.0] float.
@@ -575,3 +572,6 @@ docker compose up -d --wait db
- **결정 — management 포트 분리.** actuator 엔드포인트를 앱 API 와 **같은 소켓에 노출하지 않으려고**
별도 management 포트를 둔다.
- **`MANAGEMENT_SERVER_PORT`** — 1~65535 정수. **`APP_SERVER_PORT`(8080)와 달라야 한다.**
- **`MANAGEMENT_SERVER_ADDRESS`** — 관리 커넥터가 묶이는 주소. 기본 `127.0.0.1`(컨테이너 안 loopback). 그래서
컨테이너 밖에서는 닿지 않고, compose도 이 포트를 publish하지 않는다. Kubernetes 프로브와 Prometheus처럼 pod IP로
읽는 배포는 이 값을 바꾸거나(`0.0.0.0`과 NetworkPolicy) 같은 pod의 sidecar로 읽는다.
+6 -3
View File
@@ -30,10 +30,10 @@ lanes and CI; it is not a deployment artifact.
| 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 `main.yml` → `main` (`:integrationCheck`), qualify it against PostgreSQL. `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 `main.yml` → `main` (`: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 and the messaging library `dev.cakit.messaging` (messaging-library repo, catalog `messagingLibrary`) with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). The application's own publish and consume paths run against a live Kafka in `messagingKafkaRelayIntegrationTest` and `messagingInboxRedeliveryIntegrationTest`. The library's broker certification (`verifyMessagingCertificationEvidence`) runs in the messaging-library repo's main stage since 2026-11-08. 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: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. |
| 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 `main.yml` job `redis-topology` (`scripts/ci/redis-topology.sh`). 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`이 그 모듈을 `runtimeOnly` 한 줄로 받고, 다른 조립은 없다. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `main.yml` → `main` (`: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. |
| 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 (`OutboxRelayAutoConfiguration`) is the composition module `:composition:outbox-relay` 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. `persistence-jpa:postgresqlOutboxConcurrentRelayIntegrationTest` 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`. `NotificationEvidenceVerifierTest` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; it runs in the leaf's main-stage lane `notificationDocumentContractTest`, run by `main.yml` → `main` (`:mainCheck`). 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 `main.yml` → `main` (`: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 `main.yml` → `main` (`: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. |
@@ -71,6 +71,8 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
복구가 필요하면 표의 커밋에서 경로를 꺼낸다(`git show <커밋>:<경로>`).
표의 경로는 지운 때의 배치다. 2026-11 재배치(Gradle 루트를 저장소 루트로) 전에 지운 행은 `src/app-bootstrap/`·`src/adapters/` 같은 옛 경로를 적고, 그 경로는 지금 트리에 없다. 지금 위치로 고치지 않는다. 그 커밋에서 꺼낼 때 쓰는 경로가 그것이기 때문이다. 옛 배치와 새 배치의 대응은 `docs/upgrade/2026-11-relayout.md`다.
리뷰 후속 작업(2026-09-25~28, `docs/history/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다.
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
@@ -526,3 +528,4 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
| `SecretSourceValidator`의 `RELATIONAL_PERSISTENCE_PROPERTY`·`isRelationalPersistenceOn()`(모듈 스위치 해석) | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java` | `0ebb77b5` | P22-new-1: persistence-jpa가 기여 |
| 설정 키 `app.notification.platform.smtp.max-concurrency`(이름 변경 → `dispatch-concurrency`, env `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` 그대로) | `NotificationSmtpSettings.java`, `notification.yml` | `0ebb77b5` | P20-new-1 |
| Redis ACL `+@pubsub`·`&prod:*`(application 계정 2개) | `infra/redis-sdk/acl/*.acl` | `0ebb77b5` | P22-new-2 |
| 시험 `ComposeMergeCharacterizationTest` | `src/bootstrap/app/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java` | `ca1fbfde`(지운 커밋 `23139722`의 부모) | 어느 lane도 고르지 않아 한 번도 돌지 않았다(`integrationTest` lane은 `requires`로 적은 클래스만 고른다). 보던 것(기본·dev 조합 렌더링, 계약 스크립트)은 PR 단계 `verifyComposeProfiles`가 모든 lane으로 본다(2026-11-12 리뷰) |
+42 -4
View File
@@ -9,7 +9,7 @@
|---|---|---|---|
| POST | `/v1/files` | `201` READY, `202` VERIFYING | multipart 단일 업로드 |
| POST | `/v1/files:raw` | `201`, `202` | 요청 본문 전체가 파일이다 |
| POST | `/v1/files:batch` | `200` | part별 결과를 순서대로 준다. 명시적으로 원자적이지 않다 |
| POST | `/v1/files:batch` | `200` | 공용 bulk envelope(`docs/web/http-contract.md` 1절). 명시적으로 원자적이지 않다 |
| GET | `/v1/files/{fileId}` | `200` | 공개 metadata. content key나 경로는 절대 주지 않는다 |
| GET | `/v1/files/{fileId}/content` | `200`, `206`, `304` | 다운로드 |
| HEAD | `/v1/files/{fileId}/content` | `200`, `304` | 같은 헤더, 본문 없음 |
@@ -76,7 +76,6 @@ servlet chain에서 `app.fileserver-platform.security.admin-roles`로 막고,
```json
{
"success": false,
"data": null,
"error": {
"code": "UPLOAD_OFFSET_MISMATCH",
"category": "CONFLICT",
@@ -97,8 +96,10 @@ servlet chain에서 `app.fileserver-platform.security.admin-roles`로 막고,
`ambiguous`는 client가 재시도 전에 읽어야 하는 필드다. 결과를 모르는 실패는 이미 효과가 났을 수 있다.
`retryable`은 이번 발생에 대한 판단이고, 그 code가 허락하는 범위보다 넓어지지 않는다.
batch 업로드에서 거부된 part는 `results[]` 항목에 같은 `error` 객체(`code`, `category`, `message`,
`retryable`)를 담는다.
batch 업로드는 공용 bulk envelope다. 모든 part가 성공하면 `success: true`와 `results[]`(part마다 `clientPartId`,
`status`, `fileId`)다. 한 part라도 거부되면 `success: false`, `error.code = BATCH_PARTIAL_FAILURE`, `error.details[]`다.
`details[]` 항목은 part 순서의 `index`, `status`(`ok`·`error`), 성공한 part의 `id`(fileId), 거부된 part의 `code`와
category 고정 문구 `message`다. 부분 실패에서 part는 요청에 보낸 순서의 `index`로 짚는다(`clientPartId`는 전부 성공한 `results[]`에만 있다). 성공한 part는 되돌리지 않는다.
### Envelope 규칙의 프로토콜 예외
@@ -111,6 +112,43 @@ batch 업로드에서 거부된 part는 `results[]` 항목에 같은 `error` 객
`409 application/problem+json`, `type = https://iana.org/assignments/http-problem-types#mismatching-upload-offset`,
`expectedOffset`과 `providedOffset`. Envelope가 아닌 실패 본문은 이것 하나뿐이다.
## 오류 코드
`error.code`는 `FileserverErrorCode`(application-fileserver)가 정한다. 아래 표가 그 전부이고, client는 이 값으로
분기한다. `retryable`은 그 code가 허락하는 최대치다. 실제 응답의 `retryable`은 그 발생에 대한 판단이라 `true`인
code도 `false`로 올 수 있다(위 「실패 본문」). `Retry-After`는 retryable인 발생에만 붙는다.
| code | status | category | retryable | `Retry-After` | 언제 |
| --- | --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | `VALIDATION` | false | — | 헤더나 헤더 조합이 잘못됐다 |
| `UNAUTHENTICATED` | 401 | `AUTH` | false | — | 인증하지 않았다 |
| `ACCESS_DENIED` | 403 | `AUTHZ` | false | — | 권한이 없다. 존재를 숨기는 profile에서는 `FILE_NOT_FOUND`로 온다 |
| `FILE_NOT_FOUND` | 404 | `NOT_FOUND` | false | — | 파일이 없거나 숨겼다 |
| `FILE_ALREADY_EXISTS` | 409 | `CONFLICT` | false | — | 대상 이름이 이미 있다(copy·move는 새로 만들기만 한다) |
| `FILE_NOT_READY` | 409 | `CONFLICT` | true | 2 | 검증이 끝나지 않아 아직 읽을 수 없다 |
| `UPLOAD_OFFSET_MISMATCH` | 409 | `CONFLICT` | true | — | 이어 쓰기 offset이 서버 offset과 다르다. `details.currentOffset`부터 다시 보낸다 |
| `CONCURRENT_MODIFICATION` | 409 | `CONFLICT` | true | 1 | 같은 자원을 다른 요청이 바꾸는 중이다 |
| `UPLOAD_EXPIRED` | 410 | `CONFLICT` | false | — | 만료되거나 끝난(취소, 거부, 격리) 업로드다 |
| `CONTENT_LENGTH_REQUIRED` | 411 | `VALIDATION` | false | — | `require-content-length` profile인데 길이가 없다 |
| `PRECONDITION_FAILED` | 412 | `CONFLICT` | false | — | `If-Match`·`If-Unmodified-Since`가 맞지 않는다 |
| `FILE_TOO_LARGE` | 413 | `VALIDATION` | false | — | 파일 크기 정책을 넘었다 |
| `QUOTA_EXCEEDED` | 413 | `CONFLICT` | false | — | 저장 할당량을 넘었다 |
| `UNSUPPORTED_MEDIA_TYPE` | 415 | `VALIDATION` | false | — | 받지 않는 media type이다 |
| `RANGE_NOT_SATISFIABLE` | 416 | `VALIDATION` | false | — | Range를 만족할 수 없다. `Content-Range: bytes */<길이>`를 싣는다 |
| `INTEGRITY_MISMATCH` | 422 | `DATA_INTEGRITY` | false | — | 선언한 digest와 받은 바이트가 다르다 |
| `MALWARE_DETECTED` | 422 | `DATA_INTEGRITY` | false | — | 검사기가 거부했다 |
| `INVALID_PATH` | 422 | `VALIDATION` | false | — | 경로 형식이 틀렸다 |
| `PATH_OUTSIDE_NAMESPACE` | 422 | `VALIDATION` | false | — | 경로가 namespace 밖을 가리킨다 |
| `TRANSFER_ADMISSION_REJECTED` | 429 | `RATE_LIMIT` | true | 1 | 호출자 자신의 동시 전송 permit이 찼다. 자기 전송이 끝나면 풀린다 |
| `CHECKSUM_MISMATCH` | 460 | `DATA_INTEGRITY` | false | — | tus `Upload-Checksum`이 그 요청의 바이트와 다르다. 그 chunk만 버린다 |
| `PARTIAL_WRITE` | 500 | `TRANSIENT_DEPENDENCY` | false | — | 쓰기가 중간에 끊겼다 |
| `AMBIGUOUS_COMPLETION` | 500 | `DATA_INTEGRITY` | false | — | 결과를 모른다. 이미 효과가 났을 수 있어 그대로 재시도하지 않는다 |
| `ATOMIC_PUBLISH_UNSUPPORTED` | 503 | `PERMANENT_DEPENDENCY` | false | — | 저장소가 원자적 게시를 지원하지 않는다(배포 설정 결함) |
| `STORAGE_UNAVAILABLE` | 503 | `TRANSIENT_DEPENDENCY` | true | 30 | 저장소나 검사기를 쓸 수 없다 |
| `SERVER_BUSY` | 503 | `TRANSIENT_DEPENDENCY` | true | 1 | instance 전체의 전송 permit이나 전송 worker pool이 찼다. 공용 서버 포화 코드와 같다 |
| `TRANSFER_TIMEOUT` | 504 | `TRANSIENT_DEPENDENCY` | true | 5 | 전송이 시간 안에 끝나지 않았다 |
| `STORAGE_FULL` | 507 | `TRANSIENT_DEPENDENCY` | false | — | 저장 용량이 없다 |
## 헤더 계약
| 헤더 | 계약 |
+4 -1
View File
@@ -63,7 +63,10 @@ V1__create_fileserver_metadata.sql → capability_schema_registry: jpa-fileser
- **content가 아직 있으면 삭제는 `204`가 아니라 `202`로 답한다.** 파일은 이미 읽을 수 없고, 물리 회수는
미뤘다. `202`를 실패로 다루면 쓸데없이 재시도한다.
- **batch 업로드는 part가 실패해도 `200`으로 답한다.** batch는 명시적으로 원자적이지 않고, 상태 코드 하나로는
부분 결과를 정직하게 알릴 수 없다. `results[].error`를 읽는다.
부분 결과를 정직하게 알릴 수 없다. 판별은 `success`다. 모두 성공하면 `success: true`와 `results[]`, 하나라도
실패하면 `success: false`, `error.code = BATCH_PARTIAL_FAILURE`와 part별 `error.details[]`(`index`, `status`,
성공한 part의 `id`, 실패한 part의 `code`·`message`)다. 2026-11-12 전에는 실패가 있어도 `success: true`였다
(`docs/upgrade/2026-11-round9-contracts.md`).
- **결과를 모르는 실패는 재시도하면 안 된다.** 실패 Envelope의 `error.details`에서 `"ambiguous": true`를 본다.
- **`If-Match`는 version 숫자가 아니라 strong ETag를 받는다.** client는 실제로 받은 표현에 대해서만 주장할 수
있다.
+2 -2
View File
@@ -55,8 +55,8 @@ gRPC/GraphQL/WebSocket: 같은 ApiErrorCarrier를 자기 status 모양으로
- 템플릿 운영 코드: `OperationalError` + `docs/registries/error-codes.yaml`을 같은 변경에서 고친다.
`ErrorCodeRegistryMappingTest`(app-bootstrap)가 status 일치를 검사한다.
- 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 "Product/fork ApiErrorCode enums own local
registries"). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 모양은 위
- 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 「제품·fork의 ApiErrorCode enum은 자기 레지스트리·계약을
가진다」). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 모양은 위
`ErrorCodeRegistryMappingTest`(`src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ErrorCodeRegistryMappingTest.java`)다.
## 지금 이해하면 되는 것
+3 -2
View File
@@ -102,9 +102,10 @@ client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지
| 규칙 | 무엇을 막나 | 어디 |
| --- | --- | --- |
| bean 금지 | `@SystemInvoked` 유스케이스가 bean이면 기동 실패. 호출자가 `new`로 만들어 혼자 들고 있는 것만 허용한다 | `src/bootstrap/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`) |
| 시스템 호출자만 | inbound adapter가 그 클래스에 의존하면 빌드 실패. `@SystemCaller(reason = "...")`를 단 클래스와 그 안에 중첩된 클래스만 예외. inbound 밖 사용자 전송과 중간 클래스를 거친 길은 아래 「전송 → 시스템 호출자 금지」가 잡는다 | `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) |
| controller 위치 | Spring controller는 `..adapter.inbound..`에만 둔다. 조립 루트나 조립 모듈에 둔 controller는 빌드 실패 | `CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS`(`AdapterBoundaryArchitectureTest`) |
| 표시 검사 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping과 channel interceptor·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`, STOMP `ChannelInterceptor`·`ExecutorChannelInterceptor` 등)에 의존하는 것. 요청 처리 코드를 설정에 직접 쓴 경우와 등록만 한 경우가 모두 든다. channel interceptor를 구현한 설정은 프레임마다 자기 메서드가 돈다. interceptor를 `@Bean`으로 내놓는 설정은 route를 등록하는 설정과 같다. 함수형 route나 data fetcher를 람다로 쓰면 그 코드가 설정 클래스의 메서드로 컴파일되어 설정이 곧 endpoint다. 처리 코드를 다른 클래스에 두고 메서드 참조로 등록만 해도(`route().GET("/orders", orders::list)`) 설정은 route builder에 의존한다. 클래스 의존으로는 등록과 처리 코드를 가를 수 없어서 둘 다 사용자 전송으로 센다. ③ 설정 안에 중첩된 클래스 가운데 사용자 전송 타입에 의존하는 것. 중첩된 JAX-RS 자원·`@ServerEndpoint`, `configureClientInboundChannel`에서 등록하는 STOMP channel interceptor(익명 클래스여도, STOMP 헤더를 읽지 않아도)도 여기서 잡힌다. 설정용 타입(`WebMvcConfigurer`·`WebSocketConfigurer`·STOMP broker 설정과 그 registry, CORS 설정, `RequestMethod`)에만 의존하는 중첩 클래스는 설정의 일부로 본다. inbound channel의 thread 수만 정하는 설정도 설정용이다. ④ 그 밖의 클래스 가운데 사용자 전송 타입에 의존하는 것. 사용자 전송 패키지 밖에 둔 channel interceptor가 여기에 든다. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`(설정 필드를 읽는 익명 클래스여도)·CORS 설정·controller bean을 함께 만들어도 걸리지 않는다. 같은 클래스에 "지금 실행" route·data fetcher·interceptor를 쓰거나, route를 등록하거나, 안에 중첩한 endpoint가 작업을 부르면(설정의 메서드를 거쳐 불러도) 걸린다. route·data fetcher·interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
| 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등), 또는 `@SystemInvoked` 유스케이스 자신에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 타입에는 Spring Security의 요청 경로 확장점(`org.springframework.security.web`·`.config.annotation.web`·`.oauth2.server.resource`·`.oauth2.jwt` 패키지, `AuthenticationProvider`, `AuthorizationManager`)이 든다. 그래서 web 패키지 밖에 둔 JWT converter나 authorization manager도 사용자 전송이다. 사용자 전송 클래스는 넷이다. ① 사용자 전송 패키지에 있는 클래스. ② 설정(`@Configuration`·`@AutoConfiguration`) 클래스 자신이 요청 처리기 타입(함수형 `RouterFunction`·`HandlerFunction`, `@RestController`·`@RequestMapping`, servlet·`Filter`·`HandlerInterceptor`, `WebSocketHandler`, GraphQL `DataFetcher`·`RuntimeWiringConfigurer`, gRPC `BindableService`·`ServerInterceptor`, STOMP `ChannelInterceptor`·`ExecutorChannelInterceptor` 등)에 의존하는 것. 요청 처리 코드를 설정에 직접 쓴 경우와 등록만 한 경우가 모두 든다. 요청 처리기 타입을 구현·상속한 프로젝트 클래스(예: `ChannelInterceptor`를 구현한 interceptor)를 필드·생성자 인자·`new`로 쥔 설정도 든다. `registration.interceptors(frameCounter)`는 클래스 의존으로 `ChannelRegistration`만 남기므로 그 필드의 타입이 설정을 사용자 전송으로 만든다. channel interceptor를 구현한 설정은 프레임마다 자기 메서드가 돈다. interceptor를 `@Bean`으로 내놓는 설정은 route를 등록하는 설정과 같다. 함수형 route나 data fetcher를 람다로 쓰면 그 코드가 설정 클래스의 메서드로 컴파일되어 설정이 곧 endpoint다. 처리 코드를 다른 클래스에 두고 메서드 참조로 등록만 해도(`route().GET("/orders", orders::list)`) 설정은 route builder에 의존한다. 클래스 의존으로는 등록과 처리 코드를 가를 수 없어서 둘 다 사용자 전송으로 센다. ③ 설정 안에 중첩된 클래스 가운데 사용자 전송 타입에 의존하는 것. 중첩된 JAX-RS 자원·`@ServerEndpoint`, `configureClientInboundChannel`에서 등록하는 STOMP channel interceptor(익명 클래스여도, STOMP 헤더를 읽지 않아도)도 여기서 잡힌다. 설정용 타입(`WebMvcConfigurer`·`WebSocketConfigurer`·STOMP broker 설정과 그 registry, CORS 설정, `RequestMethod`)에만 의존하는 중첩 클래스는 설정의 일부로 본다. inbound channel의 thread 수만 정하는 설정도 설정용이다. ④ 그 밖의 클래스 가운데 사용자 전송 타입에 의존하는 것. 사용자 전송 패키지 밖에 둔 channel interceptor가 여기에 든다. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`(설정 필드를 읽는 익명 클래스여도)·CORS 설정·controller bean을 함께 만들어도 걸리지 않는다. 같은 클래스에 "지금 실행" route·data fetcher·interceptor를 쓰거나, route를 등록하거나, 안에 중첩한 endpoint가 작업을 부르면(설정의 메서드를 거쳐 불러도) 걸린다. route·data fetcher·interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스와 예외 제외)는 프로젝트(`dev.caskeleton..`와 소유자의 별도 repo 라이브러리 `dev.cakit..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler<T>`(메시징 라이브러리 `dev.cakit.messaging`)는 프로젝트 타입으로 쳐서 된다. record·enum은 언어가 붙이는 상위 타입(`Record`, `Enum`과 `Enum`이 구현하는 `Comparable`·`Serializable`·`Constable`)만은 가져도 된다. 그래서 handler 안의 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외, record로 쓴 handler는 통과하고, `Runnable`을 구현한 record는 걸린다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) |
규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 이 성질은 **패키지** 쪽에서만 온다.
+1 -1
View File
@@ -34,7 +34,7 @@
## inbound
- [ ] 컨트롤러는 변환만 한다. repository·엔티티를 모른다.
- [ ] 경로는 lowerCamel 복수형(AIP-122). 생성은 201 + `Location`.
- [ ] 경로는 lowerCamel 복수형(AIP-122). 생성은 201 + `Location`. 만든 것을 읽는 endpoint가 없으면 `Location`을 싣지 않고 controller 주석에 그 이유를 적는다.
- [ ] 도메인 규칙을 DTO bean validation에 다시 쓰지 않았다.
- [ ] 엔드포인트를 더했으면 **요청률 제한**을 어디서 거는지(ingress/app) 배포 설계에 있다. 앱 기본 off·켜는 법은 [docs/security/rate-limiting.md](../security/rate-limiting.md).
@@ -16,6 +16,9 @@ body size limit
→ 2xx
```
응답은 본문 없는 status다: 받으면(중복도) 204, 서명·형식 거절은 400, 본문 한도 초과는 413, 검증을 돌리지 못하면
503과 `Retry-After`. provider는 4xx면 멈추고 5xx면 다시 보낸다. 인증 전 경로라 거절 이유를 싣지 않는다.
projection보다 ledger 추가를 먼저 하기 때문에 빠른 2xx가 정직하다. provider에게는 이벤트가 기록됐다고 알리고,
projector 결함은 이벤트 유실이 아니라 replay 문제가 된다.
+208 -22
View File
@@ -1,13 +1,18 @@
# Registry: Env Keys
# Schema owner: feature-contract-registry-governance
# Owner branch: feature-env-driven-runtime-configuration
# Last updated: 2026-09-25
# Last updated: 2026-11-12
#
# 표기 규칙
# - 애플리케이션이 가진 env는 모두 `APP_` 접두어를 쓴다(D2, 2026-06-05). Spring 속성으로 이어지는
# datasource·server 등의 키도 APP_*로 바꿨다(예: SERVER_PORT -> APP_SERVER_PORT).
# - Spring 런타임이 직접 읽는 env만 원래 이름으로 둔다: SPRING_*와 SPRING_PROFILES_ACTIVE
# (D6 — profile 선택자는 APP_가 아니라 Spring 자체 이름이다).
# - 원래 이름으로 두는 것: Spring Boot 이름공간(SPRING_*·MANAGEMENT_*·SERVER_*, profile 선택자 SPRING_PROFILES_ACTIVE
# 포함 — D6), OpenTelemetry 규격 이름(OTEL_*), 그리고 APP_ 통일 전에 퍼진 두 이름(SECURITY_PUBLIC_PATHS,
# PRESENTATION_API_BASE_PATH, 맨 아래 절). 새 키는 APP_를 쓴다.
# - 배포 설정의 placeholder는 접두어와 상관없이 모두 행이 있어야 한다(verifyEnvKeys, 2026-11-12부터).
# - `default`는 배포 설정의 placeholder 기본값과 같고, .env.example은 그 값을 쓴다. 기본값이 아닌 권장값을 쓰는
# 행은 `example`에 그 값을 둔다. 빈 줄은 빈 문자열로 들어가 기본값을 덮으므로, 빈 칸은 기본값이 없는 키뿐이다.
# - `deprecated_orphaned: true` 행은 배포 설정이 읽지 않고 .env.example에도 없다(둘 다 verifyEnvKeys가 본다).
# - `classification: secret` 행은 secrets-classification.yaml을 가리키기만 한다. 행 전체는 그 파일이 가진다.
# - reload_policy 기본값 = `restart-only` (env-driven branch "config reload: no runtime reload" — 실행 중
# 다시 읽지 않는다).
@@ -666,7 +671,7 @@ env_keys:
- name: APP_LOG_LEVEL_SQL
# source: feature-log-management-contract — JPA/JDBC SQL 패키지 레벨 (DEBUG면 SQL을 찍는다)
type: enum
default: WARN
default: INFO
allowed_values: [TRACE, DEBUG, INFO, WARN, ERROR, OFF]
classification: public-config
required: false
@@ -938,14 +943,16 @@ env_keys:
- name: APP_SECURITY_CORS_MAX_AGE
# source: feature-security-operational-baseline 2026-05-22
# "preflight max-age 600s default"
type: duration
default: 600s
# 단위: 초. 이 값은 app.cors.max-age-seconds(CorsSettings의 long)로 간다 — "600s"는 바인딩되지 않아
# dev·prod 기동이 실패한다. 이 행이 duration / 600s라 했고 .env.example이 그 값을 복사했다(2026-11-12 리뷰).
type: integer
default: 600
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-security-operational-baseline
validation: spring_duration_shorthand
validation: non_negative_integer_seconds
compatibility_impact: behavior-change
required_test: security-contract:cors-preflight-max-age
@@ -1425,7 +1432,7 @@ env_keys:
- name: APP_RATE_LIMIT_REDIS_COMMAND_TIMEOUT
type: duration
default: 1s
default: 200ms
allowed_values: null
classification: public-config
required: false
@@ -2545,10 +2552,9 @@ env_keys:
required_test: redis-contract:semantic-probe-staleness-bounded
- name: APP_CACHE_REDIS_KEY_HMAC_SECRET
# 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도
# 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다.
deprecated_orphaned: true
removal_deadline: 2026-11-30
# 2026-09-25 capability 포장 때 cache-redis 모듈 기본 설정(config/module-defaults/cache-redis.yml)이
# app.capabilities.cache.*에 이 키를 다시 묶었다. 2026-08-10 폐기 표시가 그 뒤로 틀린 채 남아 있었다
# (2026-11-12 리뷰, verifyEnvKeys가 이제 폐기 행을 읽는 placeholder를 잡는다).
type: string
default: null
allowed_values: null
@@ -2561,12 +2567,11 @@ env_keys:
required_test: cache-contract:redis-hmac-secret-bounded
- name: APP_CACHE_REDIS_COMMAND_TIMEOUT
# 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도
# 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다.
deprecated_orphaned: true
removal_deadline: 2026-11-30
# 2026-09-25 capability 포장 때 cache-redis 모듈 기본 설정(config/module-defaults/cache-redis.yml)이
# app.capabilities.cache.*에 이 키를 다시 묶었다. 2026-08-10 폐기 표시가 그 뒤로 틀린 채 남아 있었다
# (2026-11-12 리뷰, verifyEnvKeys가 이제 폐기 행을 읽는 placeholder를 잡는다).
type: duration
default: 2s
default: 200ms
allowed_values: null
classification: public-config
required: false
@@ -2610,7 +2615,7 @@ env_keys:
- name: APP_CACHE_REDIS_POSITIVE_SOFT_TTL
type: duration
default: null
default: 30s
allowed_values: null
classification: public-config
required: false
@@ -2668,10 +2673,9 @@ env_keys:
required_test: cache-contract:redis-namespace-environment-bound
- name: APP_CACHE_REDIS_SEMANTIC_REGION
# 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도
# 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다.
deprecated_orphaned: true
removal_deadline: 2026-11-30
# 2026-09-25 capability 포장 때 cache-redis 모듈 기본 설정(config/module-defaults/cache-redis.yml)이
# app.capabilities.cache.*에 이 키를 다시 묶었다. 2026-08-10 폐기 표시가 그 뒤로 틀린 채 남아 있었다
# (2026-11-12 리뷰, verifyEnvKeys가 이제 폐기 행을 읽는 placeholder를 잡는다).
type: string
default: default
allowed_values: null
@@ -3860,6 +3864,8 @@ env_keys:
# source: persistence-mongo techlead review C1. Spring Boot 4는 이 자체 키를 spring.mongodb.uri로 쓴다.
# 유효한 연결 출처 둘 중 하나다. 다른 하나는 고른 typed profile의 uri-secret을 MongoCredentialResolver로 푼
# 값이다.
property: spring.mongodb.uri
owner_module: adapter-outbound-persistence-mongo
type: string
default: null
allowed_values: null
@@ -4072,6 +4078,22 @@ env_keys:
validation: boolean
compatibility_impact: none
required_test: off-state-zero-side-effects-and-env-round-trip
- name: APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL
# 2026-11-12 등록: 지금 구현이 여는 listener는 loopback plaintext뿐이라, 모듈을 켠 배포는 이 값을 true로
# 명시해야 기동한다(GrpcServerSettings, grpc README 「켜기와 끄기」). registry에 없어 운영자가 찾을 곳이 없었다.
property: app.grpc.server.allow-insecure-local
owner_module: adapter-inbound-grpc
type: boolean
default: false
allowed_values: [true, false]
classification: security-relevant
required: false
required_when: gRPC 모듈이 런타임에 있고 app.grpc.server.enabled가 true일 때
reload_policy: restart-only
owner_branch: refactor/maturity-review-2026-11
validation: boolean
compatibility_impact: none
required_test: adapter-contract:grpc-plaintext-requires-explicit-opt-in
- name: APP_GRAPHQL_ENABLED
# 2026-09-25 capability 포장: 모듈은 있으면 켜진다(모듈 자신의 설정 yml이 이 키를 기본 true로 잇는다).
# false가 명시적으로 끄는 값이다. 빌드에 모듈이 없는 것이 보통의 꺼진 상태다.
@@ -4846,6 +4868,7 @@ env_keys:
owner_module: adapter-outbound-notification
type: integer
default: null
example: 587
allowed_values: null
classification: public-config
required: false
@@ -4897,6 +4920,7 @@ env_keys:
owner_module: adapter-outbound-notification
type: boolean
default: null
example: true
allowed_values: null
classification: public-config
required: false
@@ -4914,6 +4938,7 @@ env_keys:
owner_module: adapter-outbound-notification
type: boolean
default: null
example: true
allowed_values: null
classification: public-config
required: false
@@ -4931,6 +4956,7 @@ env_keys:
owner_module: adapter-outbound-notification
type: integer
default: null
example: 5000
allowed_values: null
classification: public-config
required: false
@@ -4948,6 +4974,7 @@ env_keys:
owner_module: adapter-outbound-notification
type: integer
default: null
example: 10000
allowed_values: null
classification: public-config
required: false
@@ -4965,6 +4992,7 @@ env_keys:
owner_module: adapter-outbound-notification
type: integer
default: null
example: 10000
allowed_values: null
classification: public-config
required: false
@@ -5270,3 +5298,161 @@ env_keys:
validation: positive_duration
compatibility_impact: behavior-change
required_test: adapter-contract:notification-callback-replay
# === 원래 이름으로 읽는 placeholder (2026-11-12 등록) ===
# 배포 설정이 읽는데 행이 없던 이름이다. verifyEnvKeys가 APP_ 밖 placeholder를 보지 않아 빠졌다. 이름을 APP_로
# 바꾸면 파생 서비스의 배포 env가 소리 없이 무시되므로 지금 이름 그대로 등록한다(바꾸는 것은 소유자 결정).
# SPRING_JACKSON_DESER_*·SPRING_JACKSON_SER_*·SPRING_BANNER_MODE는 Spring relaxed 이름이 아니라 application.yml
# placeholder가 만든 이름이다. relaxed 이름(예: SPRING_JACKSON_DESERIALIZATION_FAIL_ON_UNKNOWN_PROPERTIES,
# SPRING_MAIN_BANNER_MODE)도 같은 속성을 덮고, 둘 다 있으면 relaxed 이름이 이긴다(환경 변수 소스가 yml보다 앞선다).
- name: SECURITY_PUBLIC_PATHS
# 인증을 건너뛰는 경로 CSV(app.security.public-paths). 기본값은 API base path 뒤의 healthcheck 하나이고
# docs/security/public-paths-snapshot.txt가 그 기본값을 고정한다. 운영자 값은 스냅숏 밖이다.
property: app.security.public-paths
type: csv
default: /v1/healthcheck
allowed_values: null
classification: security-relevant
required: false
reload_policy: restart-only
owner_branch: feature-security-operational-baseline
validation: csv_of_absolute_paths
compatibility_impact: behavior-change
required_test: security-contract:public-path-snapshot
- name: PRESENTATION_API_BASE_PATH
# 모든 controller 앞에 붙는 경로(presentation.api-base-path). 빈 값이면 접두어 없음. SECURITY_PUBLIC_PATHS의
# 기본값도 이 값에서 나온다.
type: string
default: /v1
allowed_values: null
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-api-contract-baseline
validation: leading_slash_path_or_empty
compatibility_impact: behavior-change
required_test: web-contract:api-base-path-prefix
- name: SPRING_BANNER_MODE
property: spring.main.banner-mode
type: enum
default: console
allowed_values: [off, console, log]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-env-driven-runtime-configuration
validation: enum_in_allowed_values
compatibility_impact: behavior-change
required_test: env-contract:spring-runtime-placeholder
- name: SPRING_MAIN_LAZY_INITIALIZATION
property: spring.main.lazy-initialization
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-env-driven-runtime-configuration
validation: boolean
compatibility_impact: behavior-change
required_test: env-contract:spring-runtime-placeholder
- name: SPRING_MAIN_LOG_STARTUP_INFO
property: spring.main.log-startup-info
type: boolean
default: true
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-env-driven-runtime-configuration
validation: boolean
compatibility_impact: behavior-change
required_test: env-contract:spring-runtime-placeholder
- name: SPRING_THREADS_VIRTUAL_ENABLED
property: spring.threads.virtual.enabled
type: boolean
default: true
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-env-driven-runtime-configuration
validation: boolean
compatibility_impact: behavior-change
required_test: env-contract:spring-runtime-placeholder
- name: SPRING_JACKSON_DESER_FAIL_ON_UNKNOWN_PROPERTIES
# 요청 경계 Jackson 정책(web AGENTS B1). 끄면 잘못된 본문을 조용히 받아들인다.
property: spring.jackson.deserialization.fail-on-unknown-properties
type: boolean
default: true
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-env-driven-runtime-configuration
validation: boolean
compatibility_impact: behavior-change
required_test: env-contract:spring-runtime-placeholder
- name: SPRING_JACKSON_DESER_FAIL_ON_NULL_FOR_PRIMITIVES
# 요청 경계 Jackson 정책(web AGENTS B1). 끄면 잘못된 본문을 조용히 받아들인다.
property: spring.jackson.deserialization.fail-on-null-for-primitives
type: boolean
default: true
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-env-driven-runtime-configuration
validation: boolean
compatibility_impact: behavior-change
required_test: env-contract:spring-runtime-placeholder
- name: SPRING_JACKSON_DESER_FAIL_ON_IGNORED_PROPERTIES
# 요청 경계 Jackson 정책(web AGENTS B1). 끄면 잘못된 본문을 조용히 받아들인다.
property: spring.jackson.deserialization.fail-on-ignored-properties
type: boolean
default: true
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-env-driven-runtime-configuration
validation: boolean
compatibility_impact: behavior-change
required_test: env-contract:spring-runtime-placeholder
- name: SPRING_JACKSON_DESER_READ_UNKNOWN_ENUM_VALUES_AS_NULL
# 요청 경계 Jackson 정책(web AGENTS B1). 끄면 잘못된 본문을 조용히 받아들인다.
property: spring.jackson.datatype.enum.read-unknown-enum-values-as-null
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-env-driven-runtime-configuration
validation: boolean
compatibility_impact: behavior-change
required_test: env-contract:spring-runtime-placeholder
- name: SPRING_JACKSON_SER_WRITE_DATES_AS_TIMESTAMPS
# 요청 경계 Jackson 정책(web AGENTS B1). 끄면 잘못된 본문을 조용히 받아들인다.
property: spring.jackson.datatype.datetime.write-dates-as-timestamps
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
reload_policy: restart-only
owner_branch: feature-env-driven-runtime-configuration
validation: boolean
compatibility_impact: behavior-change
required_test: env-contract:spring-runtime-placeholder
+15
View File
@@ -380,6 +380,21 @@ errors:
compatibility_impact: none
required_test: contract-verification:rate-limit
# source: 2026-11-12 리뷰 결정 ② — 서버 포화(허가 상한, 꽉 찬 work pool)는 전송마다 다른 코드였다(web-advanced
# ADMISSION_REFUSED 503, fileserver TRANSFER_ADMISSION_REJECTED 429, gRPC RATE_LIMIT_EXCEEDED). 이 코드 하나로 모은다.
# 호출자 자신의 빈도·동시성 초과만 429(RATE_LIMIT_EXCEEDED, fileserver TRANSFER_ADMISSION_REJECTED)다.
- code: SERVER_BUSY
category: TRANSIENT_DEPENDENCY
http_status: 503
retryable: true
retry_after_seconds: 1
owner_branch: 2026-11-12-round9-review
owner_layer: presentation
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
runbook_link: "runbook://server/busy"
compatibility_impact: behavior-change
required_test: contract-verification:server-saturation
# 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).
@@ -0,0 +1,221 @@
# round9 영역 01 — 영속성·메시징·성능
- 대상: main `a7e38c10`(2026-11-12). 범위와 방법은 [README](README.md) 「범위」다.
- 발견마다: 출처(리뷰어), 증거 수준, 이전부터/최근 변경, 고칠 묶음(README 「묶음」). 원문의 `파일:줄`은 저장소 루트 기준이다.
### RR9-01-01 · Medium · inbox TransactionRunner `new TransactionTemplate` timeout 없음 → 유스케이스…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B9 트랜잭션 시한·정리
- 내용: inbound/messaging `MessagingInboxAutoConfiguration.java:76` — inbox TransactionRunner `new TransactionTemplate` timeout 없음 → 유스케이스 tx.inWrite가 합류해 30초 상한 버림(`SpringTransaction.java:200`). 근거 persistence-jpa/AGENTS.md:138, manual 09:123. 고침: setTimeout(write-timeout) + 테스트. 이전부터.
### RR9-01-02 · Medium · heartbeat·progress·succeed·fail이 lease_owner=:workerId만 확인, fence 없음. 같은…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B8 claim·fence
- 내용: persistence-jpa `DurableOperationJpaRepository.java:121,143,168,194` — heartbeat·progress·succeed·fail이 lease_owner=:workerId만 확인, fence 없음. 같은 workerId 재claim 시 앞 실행이 true. 포트 `DurableOperationStorePort.java:14,57`은 workerId 유일 조건 안 적음. outbox lease_token·알림 lease_fence·reconciliation claim_fence·fileserver claim_token과 갈림. 고침: claimNext가 token 돌려주고 조건에 넣기 or 포트에 유일성 명시 + 계약 케이스. 이전부터.
### RR9-01-03 · Medium · live_event_log 행 retention 지나도 안 지움, sweepExpired 호출자·스케줄 없음, 문서도 서비스 의무로 안…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B9 트랜잭션 시한·정리
- 내용: persistence-jpa `JpaLiveEventReplay.java:142` — live_event_log 행 retention 지나도 안 지움, sweepExpired 호출자·스케줄 없음, 문서도 서비스 의무로 안 적음(inbox는 09장 179줄에 적음). 고침: reaper 조립 or 문서 의무. 이전부터.
### RR9-01-04 · Low · 상한 없는 DELETE 한 문장(outbox는 1000행씩, OutboxEventJpaRepository.java:35-47),…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B8 claim·fence
- 내용: persistence-jpa `IdempotencyReaper.java:27-29` — 상한 없는 DELETE 한 문장(outbox는 1000행씩, OutboxEventJpaRepository.java:35-47), expires_at은 DB 시계(IdempotencyClaimGateway.java:90 clock_timestamp())인데 비교는 앱 clock. 고침: 묶음 삭제 + SQL now(). 이전부터.
### RR9-01-05 · Low · join() 시간 상한 없음,…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10a 발행·발송·캐시
- 내용: messaging `OutboxMessagePublishAdapter.java:53` — join() 시간 상한 없음, longestAttempt()(PlatformIntegrationEventPublishAdapter.java:93-96) 검사가 실제 대기에 안 걸림 → lease 지나 중복 발행, 종료 대기 약속 깨짐. VerificationCoordinator.java:56은 get(timeout). 고침: orTimeout(longestAttempt) + AMBIGUOUS. 이전부터.
### RR9-01-06 · Low · Javadoc "enqueue is an upsert"인데 UPDATE 0행이면 INSERT 두 단계, 동시 enqueue 시…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B8 claim·fence
- 내용: persistence-fileserver `JpaRecoveryQueue.java:18,43-46` — Javadoc "enqueue is an upsert"인데 UPDATE 0행이면 INSERT 두 단계, 동시 enqueue 시 uq_fs_recovery_open(V2:53) 위반·25P02, DefaultFileReconciliationService.java:242가 그대로 던짐. 고침: INSERT … ON CONFLICT (file_id) WHERE status='PENDING' DO UPDATE. 이전부터.
### RR9-01-07 · Low · app.lock.wait-time 읽는 곳 없음(lease-ttl 교차 검사로 기동 막기만). README:559…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B9 트랜잭션 시한·정리
- 내용: persistence-jpa `LockSettings.java:21-41` — app.lock.wait-time 읽는 곳 없음(lease-ttl 교차 검사로 기동 막기만). README:559 "@EnableConfigurationProperties가 바인딩"(실제 StrictSettingsBinder), :536 데코레이터 위치 "컴포지션 루트". 근거 manual 10 기준 3. 이전부터.
### RR9-01-08 · Low · 408·429를 조건 없이 재시도로 적음, 코드(DefaultRetryEligibilityEngine.java:81-99,…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10b S3·Mongo·httpclient
- 내용: `docs/httpclient/retry-and-ambiguity.md:53,55` — 408·429를 조건 없이 재시도로 적음, 코드(DefaultRetryEligibilityEngine.java:81-99, RetryEligibilityEngineTest.java:200-207)는 비멱등에서 408 결과모름·429 거부. 이전부터.
### RR9-01-09 · Low · 주석 "retention has no default on purpose"인데…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B9 트랜잭션 시한·정리
- 내용: persistence-jpa `JpaAdapterBeansConfig.java:124-125` — 주석 "retention has no default on purpose"인데 persistence-jpa.yml:212·env-keys.yaml:387 기본 1h. 이전부터.
### RR9-01-10 · Low · Javadoc lane 목록에 lock timeout runbook…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B9 트랜잭션 시한·정리
- 내용: persistence-jpa postgresqlIntegrationTest `readiness/RunbookSql.java:10-13` — Javadoc lane 목록에 lock timeout runbook lane(PostgreSqlDistributedLockIntegrationTest.java:36,137,162) 빠짐. 이전부터(ba189869).
### RR9-01-11 · Low · Redis 같은 키 재전송 안 돌린다를 조건 없이 약속, Sentinel·Cluster failover 비동기 복제 손실…
- 출처: 물결 1 영속성·메시징·성능
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10b S3·Mongo·httpclient
- 내용: `docs/manual/05-idempotency.md:59` — Redis 같은 키 재전송 안 돌린다를 조건 없이 약속, Sentinel·Cluster failover 비동기 복제 손실 한계(redis-capability-incident.md:145-151) 안 적음. 이전부터.
### RR9-01-12 · Medium · 회복이 행 잠금 없이 읽고(RecipientDeliveryJpaRepository.java:187-194) requeue 무조건…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B8 claim·fence
- 내용: `LeaseRecoveryService.java:113,157-164`, `JpaRecipientDeliveryStore.java:59-71` — 회복이 행 잠금 없이 읽고(RecipientDeliveryJpaRepository.java:187-194) requeue 무조건 read-modify-write, 인스턴스마다 돎(NotificationBackgroundWorkers.java:77) → 완료·재claim 행을 READY로. 고침: state·lease_until·lease_fence 조건부 UPDATE.
### RR9-01-13 · Medium · UPDATE … WHERE id IN (SELECT … LIMIT), 상태 조건 subquery 안만 → READ COMMITTED 재평가 안…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B8 claim·fence
- 내용: `RecipientClaimSql.java:55-68`(EXPIRE_OVERDUE), `InboxItemJpaRepository.java:89-106`(markAllRead) — UPDATE … WHERE id IN (SELECT … LIMIT), 상태 조건 subquery 안만 → READ COMMITTED 재평가 안 함, claim된 행 EXPIRED, archive 행 READ(주석 96-97이 막겠다던 것). 고침: 바깥 WHERE 상태 조건 or FOR UPDATE SKIP LOCKED.
### RR9-01-14 · Medium · poll마다 SQL 4개, PROJECTION_LAG WHERE 없음 → notification_provider_event 전체 스캔(지우는…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B9 트랜잭션 시한·정리
- 내용: `JdbcNotificationServingState.java:60-69,89-118`, `NotificationSchedulerWorker.java:84-87` — poll마다 SQL 4개, PROJECTION_LAG WHERE 없음 → notification_provider_event 전체 스캔(지우는 경로 없음), Javadoc 20-22 「claim 인덱스」. 고침: backlog만 or 캐시, 부분 인덱스 조건.
### RR9-01-15 · Medium · ThreadPoolExecutor(1,n,LinkedBlockingQueue(4n)) 큐 찰 때까지 스레드 1, limiter 4로 큐 안…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10a 발행·발송·캐시
- 내용: `NotificationSmtpProviderConfig.java:117-129` — ThreadPoolExecutor(1,n,LinkedBlockingQueue(4n)) 큐 찰 때까지 스레드 1, limiter 4로 큐 안 참(SmtpProviderRuntimeAssembler.java:110) → SMTP 직렬, NotificationSmtpSettings.java:22. 고침: core=max + allowCoreThreadTimeOut.
### RR9-01-16 · Medium · RejectedExecution을 AMBIGUOUS_SUBMISSION으로(SMTP 상태 조회 없음 → 운영자 대기),…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10a 발행·발송·캐시
- 내용: 같은 executor + `RegistryProviderDispatchGateway.java:59-61`, `ProviderOutcomeClassifier.java:49-57` — RejectedExecution을 AMBIGUOUS_SUBMISSION으로(SMTP 상태 조회 없음 → 운영자 대기), max-concurrency > 5×dispatch-concurrency 조건, 기동 검사 없음. 고침: ProviderCallNotStartedException + 기동 검사.
### RR9-01-17 · Medium · 캐시가 대기 예산 없는 run → lane 대기 2s + commandTimeout, @param "ceiling on one cache…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10a 발행·발송·캐시
- 내용: `RedisCacheRegionAdapter.java:118,131-138,161,270,346`, `SemanticRedisCall.java:115-117,134-137`, `RedisRuntimeOwner.java:171-172` — 캐시가 대기 예산 없는 run → lane 대기 2s + commandTimeout, @param "ceiling on one cache operation". rate limit은 effectWithin. 고침: effectWithin(commandTimeout).
### RR9-01-18 · Medium · 캐시 값 크기 상한 없음(옛 키 폐기 env-keys.yaml:2686-2689, RedisKeyRules는 키만). 고침: encode 길이…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10a 발행·발송·캐시
- 내용: `RedisCacheRegionAdapter.java:233-341` — 캐시 값 크기 상한 없음(옛 키 폐기 env-keys.yaml:2686-2689, RedisKeyRules는 키만). 고침: encode 길이 검사.
### RR9-01-19 · Medium · 조건부 PUT 본문 재전송 가능 → SDK 재시도가 412 → ObjectControlConflictException,…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10b S3·Mongo·httpclient
- 내용: `S3ConditionalObjectControlStore.java:101-118`, `S3AsyncClientFactory.java:38-48` — 조건부 PUT 본문 재전송 가능 → SDK 재시도가 412 → ObjectControlConflictException, reconcileLostResponse(121) 안 돎, CAS(ObjectOperationKernel.java:112-125)는 자기 쓰기를 stale로. 조건 retry.maximum-attempts>1. 고침: 조건부 PUT 재시도 끔 or 412에서 다시 읽어 비교.
### RR9-01-20 · Medium · getMappedResults 전부 메모리 후 셈, maxResultBytes 미집행(95), query-aggregation-guide…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10b S3·Mongo·httpclient
- 내용: `PolicyAwareMongoAggregationExecutor.java:76-85`, `MongoOperationBudget.java:5-11` — getMappedResults 전부 메모리 후 셈, maxResultBytes 미집행(95), query-aggregation-guide 3절. 고침: $limit(max+1) + cursor 바이트 누적.
### RR9-01-21 · Medium · heap 384m을 512m tmpfs에 dump, 같은 cgroup·swap 없음 → dump 중 OOM kill 가능,…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B19 compose·Docker 운영
- 내용: (넘어온 2) Dockerfile:157-163, compose.yaml:113-123, docs/runbooks/internal-error-spike.md:39 — heap 384m을 512m tmpfs에 dump, 같은 cgroup·swap 없음 → dump 중 OOM kill 가능, ExitOnOutOfMemoryError로 tmpfs 사라짐. dev.yaml:25-28만 volume. 고침: named volume or runbook.
### RR9-01-22 · Low · (넘어온 1) .env.example:193 POSITIVE_SOFT_TTL= → 빈 Duration null → setter 안 불림 →…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B2 env 계약
- 내용: (넘어온 1) .env.example:193 POSITIVE_SOFT_TTL= → 빈 Duration null → setter 안 불림 → 필드 기본 30s(RedisCapabilitySettings.java:85), HARD_TTL<30s면 운영자가 정하지 않은 soft로 기동 실패(101-105). 고침: soft 비면 min(30s,hard).
### RR9-01-23 · Low · max-items 100을 10분 lease로 한꺼번에 claim, lease 안에 끝나는지 검사 없음(outbox…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B8 claim·fence
- 내용: `DefaultCleanupService.java:50,96-122` — max-items 100을 10분 lease로 한꺼번에 claim, lease 안에 끝나는지 검사 없음(outbox OutboxSettings.java:68-96, notification NotificationSchedulerWorker.java:71-75와 갈림).
### RR9-01-24 · Low · "lease > provider 호출·timeout" 주석만, 검사 없음.
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B8 claim·fence
- 내용: notification.yml:46-48, NotificationDispatchProperties.java:40-48 — "lease > provider 호출·timeout" 주석만, 검사 없음.
### RR9-01-25 · Low · 트랜잭션 30초 상한 없음(decisions 2.5), row cap 사후 검사(inbox 건과 같은 원인).
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B9 트랜잭션 시한·정리
- 내용: `HibernateStatelessSessionRunner.java:56-67` — 트랜잭션 30초 상한 없음(decisions 2.5), row cap 사후 검사(inbox 건과 같은 원인).
### RR9-01-26 · Low · 새 pool 크기 모른 채 합계 미만만 봄 → 상한 초과, Javadoc "would exceed".
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B9 트랜잭션 시한·정리
- 내용: `TenantPoolBudget.java:29-33`, `TenantDataSourceRegistry.java:54` — 새 pool 크기 모른 채 합계 미만만 봄 → 상한 초과, Javadoc "would exceed".
### RR9-01-27 · Low · acquire void, idle 판정 마지막 acquire 시각 → 사용 중 client 닫음, 닫기 실패가 다른 tenant…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10b S3·Mongo·httpclient
- 내용: `MongoTenantClientRegistry.java:85-128,130-156` — acquire void, idle 판정 마지막 acquire 시각 → 사용 중 client 닫음, 닫기 실패가 다른 tenant acquire에서(153). Experimental.
### RR9-01-28 · Low · requireCurrentFence가 UNFENCED만 거름(MongoMigrationLock.java:32), refresh(166-170)…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10b S3·Mongo·httpclient
- 내용: `MongoCollectionMigrationLedger.java:93,120,177` — requireCurrentFence가 UNFENCED만 거름(MongoMigrationLock.java:32), refresh(166-170) ISE vs MongoMigrationHeartbeat.java:22 MongoOperationRejectedException 약속.
### RR9-01-29 · Low · lease 만료 시계 구현마다 다름: JpaRecipientLeaseStore.java:52,117,…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B8 claim·fence
- 내용: lease 만료 시계 구현마다 다름: JpaRecipientLeaseStore.java:52,117, DefaultCleanupService.java:88, MongoCollectionMigrationLock.java:76-80(JVM) vs 멱등·rate limit(서버). R1-4와 같은 원인.
### RR9-01-30 · Low · compression=true면 Apache가 푼 스트림을 wire 계수기가 셈(ApacheClientFactory.java:114-116)…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10b S3·Mongo·httpclient
- 내용: `RestClientResponseReader.java:112-124`, `ResponseLimits.java:8-13` — compression=true면 Apache가 푼 스트림을 wire 계수기가 셈(ApacheClientFactory.java:114-116) → 6MiB 응답 wire 초과 거절.
### RR9-01-31 · Low · ProxyType.SOCKS를 HTTP 프록시로, capability…
- 출처: 물결 2 outbound
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B10b S3·Mongo·httpclient
- 내용: `ApacheClientFactory.java:117-123` — ProxyType.SOCKS를 HTTP 프록시로, capability proxySupport=true(BlockingTransportCapabilities.java:33-35).
@@ -0,0 +1,221 @@
# round9 영역 02 — 보안·관측
- 대상: main `a7e38c10`(2026-11-12). 범위와 방법은 [README](README.md) 「범위」다.
- 발견마다: 출처(리뷰어), 증거 수준, 이전부터/최근 변경, 고칠 묶음(README 「묶음」). 원문의 `파일:줄`은 저장소 루트 기준이다.
### RR9-02-01 · Medium · 관리 포트 기본 127.0.0.1(PR #12)인데 service-runtime/README.md:275-276·Dockerfile:221은…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B3 공개 경로·관리 포트
- 내용: bootstrap/app `config/observability.yml:34` — 관리 포트 기본 127.0.0.1(PR #12)인데 service-runtime/README.md:275-276·Dockerfile:221은 k8s 프로브·Prometheus가 닿는다고 약속. `MANAGEMENT_SERVER_ADDRESS`가 docs/build.md:573·.env.example·env-keys에 없음. compose.yaml:88-91·compose-lanes/dev.yaml:70 `127.0.0.1:9001:9001` publish는 컨테이너 loopback에 못 닿음(죽은 설정). 고침: 세 문서에 원격 프로브는 MANAGEMENT_SERVER_ADDRESS 필요, .env.example 행, publish 줄 정리. 최근(PR #12, 9fb5a61f).
### RR9-02-02 · Medium · 최상위 `roles` 클레임 fallback을 권한에 합침. manual 07:51-53·decisions 2.6 「JWT…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B4 인증·인가
- 내용: web `auth/JwtToAuthenticatedPrincipalConverter.java:101-105` — 최상위 `roles` 클레임 fallback을 권한에 합침. manual 07:51-53·decisions 2.6 「JWT audience·role」은 realm_access·자기 client resource_access만. 고침: fallback 삭제 + 시험 "최상위 roles만 → 권한 0". 이전부터.
### RR9-02-03 · Medium · config/security.yml 한 줄만 읽음, 문서(gates.md:63, build.md:166)는 보안 체인 전체 약속.…
- 출처: 물결 1 보안·관측(같은 결함을 물결 1 API 계약·시험도 적음)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B3 공개 경로·관리 포트
- 내용: bootstrap/app test `PublicPathSnapshotTest.java:31` — config/security.yml 한 줄만 읽음, 문서(gates.md:63, build.md:166)는 보안 체인 전체 약속. profile의 public-paths(application-local.yml:161), 모듈 체인 permitAll(web-notification CallbackMvcSecurityConfiguration.java:29-35 `/internal/notification/callbacks/**`) 우회. 고침: 입력 넓히기(context 띄워 matcher 나열) or 약속 좁히기. 이전부터.
### RR9-02-04 · Medium · runbook 둘이 없는 신호로 탐지:…
- 출처: 물결 1 보안·관측(같은 결함을 물결 2 계약·문서도 적음)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B7 runbook 신호
- 내용: runbook 둘이 없는 신호로 탐지: `docs/runbooks/management-actuator-forbidden.md:15-16`(403 ACTUATOR_FORBIDDEN; 실제 404·본문없는 401 ManagementSecurityConfig.java:55-56, 코드 OperationalError.java:89 선언만), `docs/runbooks/authz-cross-tenant-violation.md:18-21,27,37`(403 AUTHZ_TENANT_MISMATCH 경보, 칸·지표 authz_denied_total 등 없음; 실제 404·로그·지표 없음). 고침: 신호 만들기(WARN+counter) 후 runbook 맞추기 or 신호 없음 명시. 이전부터.
### RR9-02-05 · Medium · `docs/registries/metrics.yaml` 양방향 불일치: 코드 없는…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B5 관측 registry
- 내용: `docs/registries/metrics.yaml` 양방향 불일치: 코드 없는 행(http.server.requests.latency:47, dependency.client.requests:72, db.query.duration:211, resilience4j.* 98·117·137, cache.invalidations.total:454, cache.local.* 473·492·508), 행 없는 코드(http.client.* 25개, notification.* 16, graphql.* 4, jpa.query.*, backend.redis.*, mongodb.driver.*, fileserver.*.duration), http.server.requests tag 표기(uri_template·2xx vs uri·숫자·outcome·exception), MetricsDistributionMeterFilter.java:19-24 없는 이름에 SLO, CardinalityBounds Javadoc "used by MeterFilter" 미사용, 단위 접미사 규칙 위반 lock.acquisition:308·executor.saturation:233. 고침: 행↔meter 맞추기 + "registry ⊆ 등록 meter" 시험. 이전부터.
### RR9-02-06 · Medium · JMX 9999 무인증·무TLS, jmxremote.host 없어 모든 인터페이스. 주석 15·54 "localhost only". 고침:…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B3 공개 경로·관리 포트
- 내용: `src/bootstrap/app/compose-lanes/dev.yaml:62-67` — JMX 9999 무인증·무TLS, jmxremote.host 없어 모든 인터페이스. 주석 15·54 "localhost only". 고침: -Dcom.sun.management.jmxremote.host=127.0.0.1 or JMX 제거. 이전부터.
### RR9-02-07 · Low · 18키 중 5개만 코드가 넣음(logback-spring.xml:90-94). tenant_id(77-88) required_in인데…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B5 관측 registry
- 내용: `docs/registries/mdc-keys.yaml` — 18키 중 5개만 코드가 넣음(logback-spring.xml:90-94). tenant_id(77-88) required_in인데 없음(JwtToAuthenticatedPrincipalConverter.java:40-41 "tenant_id is also the MDC key"). method·status·duration_ms 메시지에만(RequestLoggingFilter.java:52-57). request_id·correlation_id type ulid인데 UUIDv4(WebMvcRequestIdFilter.java:159, GrpcCorrelationInterceptor.java:67, WebSocketCorrelationInterceptor.java:34). required_test contract-verification:* 시험 없음. 이전부터.
### RR9-02-08 · Low · 전송별 correlation 규칙 다름: web(WebMvcRequestIdFilter.java:189-191),…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B5 관측 registry
- 내용: 전송별 correlation 규칙 다름: web(WebMvcRequestIdFilter.java:189-191), gRPC(GrpcCorrelationInterceptor.java:65-74 correlation_id 없음, traceparent 없으면 trace_id 없음; Javadoc 17 "same keys"), STOMP 세션 id(WebSocketCorrelationInterceptor.java:34-37). mdc-keys.yaml:60-71. 고침: shared-contract에 결정 하나. 이전부터.
### RR9-02-09 · Low · 401·403 WARN에 원본 getRequestURI(Javadoc 15-19 "only redacted"). 같은 모양…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B6a 로그 내용
- 내용: web `auth/AuthErrorResponseWriter.java:35-41` — 401·403 WARN에 원본 getRequestURI(Javadoc 15-19 "only redacted"). 같은 모양 RequestLoggingFilter.java:66-69, GlobalExceptionHandler.java:213 getDescription(false). 고침: 매칭 pattern·분류. 이전부터.
### RR9-02-10 · Low · IP 신뢰 문서 둘: application-local.yml:120-121 "framework via…
- 출처: 물결 1 보안·관측(같은 결함을 물결 2 계약·문서도 적음)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B6b 비밀·IP 문서
- 내용: IP 신뢰 문서 둘: application-local.yml:120-121 "framework via env"(server.yml:12·env-keys.yaml:133-141 금지), docs/security/rate-limiting.md:18 지운 APP_RATE_LIMIT_CLIENT_IP_MODE(capability-status.md:319 삭제). 고침: native + internal-proxies. local은 이전부터, rate-limiting은 PR #12(1444d1e0).
### RR9-02-11 · Low · config/security.yml:23 `SECURITY_PUBLIC_PATHS`, config/runtime.yml:18…
- 출처: 물결 1 보안·관측(같은 결함을 물결 1 API 계약·시험도 적음)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B2 env 계약
- 내용: config/security.yml:23 `SECURITY_PUBLIC_PATHS`, config/runtime.yml:18 `PRESENTATION_API_BASE_PATH` env-keys·.env.example 미등록(머리말 7-10 "APP_, 예외 SPRING_*"). 이전부터.
### RR9-02-12 · Low · masking_rule full_except_last_4 구현 없음(LogMaskingPatterns.java:23-41 URI…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B6b 비밀·IP 문서
- 내용: `docs/registries/secrets-classification.yaml` — masking_rule full_except_last_4 구현 없음(LogMaskingPatterns.java:23-41 URI userinfo 못 가림), 죽은 행 APP_PROFILE:399·SERVER_PORT:415·APP_NOTIFICATION_SLACK_WEBHOOK_URL:330·APP_SECURITY_GOOGLE_OAUTH_CLIENT_ID:344, required_test secrets-contract:* 없음. 이전부터.
### RR9-02-13 · Low · 로컬 비밀 기본값 `__LOCAL_DEV_` 규칙 미준수: compose.yaml:108·158, application-local.yml:55…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B6b 비밀·IP 문서
- 내용: 로컬 비밀 기본값 `__LOCAL_DEV_` 규칙 미준수: compose.yaml:108·158, application-local.yml:55 `ca_skeleton`, compose.yaml:337·366 `caskeleton-local`, compose.yaml:388 `admin`. SecretSourceValidator(146-161) sentinel 못 알아봄. 이전부터.
### RR9-02-14 · Low · "The standalone sample does that." 지운 샘플(ab5982e9). 최근.
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B6b 비밀·IP 문서
- 내용: service-runtime `management/security/ManagementSecurityConfig.java:33-35` — "The standalone sample does that." 지운 샘플(ab5982e9). 최근.
### RR9-02-15 · Low · main 호출자 없음, WebMvcRequestIdFilter.java:182-188이 버린 규칙. 고침: 클래스·시험·README:511…
- 출처: 물결 1 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B6a 로그 내용
- 내용: web `observability/HeaderSanitizer.java:3-6` — main 호출자 없음, WebMvcRequestIdFilter.java:182-188이 버린 규칙. 고침: 클래스·시험·README:511 삭제. 이전부터.
### RR9-02-16 · Medium · 인증 없는 모르는 profile POST → ISE → GlobalExceptionHandler.java:213…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B4 인증·인가
- 내용: `ProviderCallbackIngressBridge.java:51-61`, `MapProviderCallbackAdapterRegistry.java:50`, `NotificationCallbackMvcController.java:105` — 인증 없는 모르는 profile POST → ISE → GlobalExceptionHandler.java:213 ERROR(스택·URI)+500 envelope("bare status, no body" Javadoc), 크기·content-type 검사가 profile 확인보다 먼저라 공격자 profile 문자열이 notification.security WARN. 고침: require 먼저, CallbackValidationException.
### RR9-02-17 · Medium · root 좌표만 판정, GraphQlAuthorizationPolicy.java:11-16 builder는 User.salary 하위 좌표…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B4 인증·인가
- 내용: `GraphQlDocumentAuthorizationHandler.java:69` — root 좌표만 판정, GraphQlAuthorizationPolicy.java:11-16 builder는 User.salary 하위 좌표 규칙 받고 버림 → 누구나 실행. 고침: 기동 거절 or 모든 필드 판정.
### RR9-02-18 · Medium · @RequiresPermission web만: gRPC principal을…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B4 인증·인가
- 내용: @RequiresPermission web만: gRPC principal을 Context에만(GrpcAuthenticationInterceptor.java:38), STOMP SecurityContext 전파 없음(WebSocketConfig.java:94), RequiresPermissionAuthorizationManager.java:56은 SecurityContextHolder → 항상 거부. 거부 결과도 web 403, gRPC INTERNAL+ERROR(GrpcExceptionHandlingInterceptor.java:147), STOMP ERROR(StompHandlerFailureLog.java:76), GraphQL masked INTERNAL_ERROR+ERROR(GraphQlExceptionResolver.java:66). manual 07, gRPC README AUTHZ→PERMISSION_DENIED. 고침: 전송별 SecurityContext 전달 + 같은 코드.
### RR9-02-19 · Medium · 모든 projection을 /topic 하나로 모든 인증 세션에, tenant·소유자 판정 없음, README 「한계」 95-106 없음.…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11b graphql·websocket 계약
- 내용: `LiveEventStompBroadcaster.java:89-92` — 모든 projection을 /topic 하나로 모든 인증 세션에, tenant·소유자 판정 없음, README 「한계」 95-106 없음. 고침: 목적지 분리 or 규칙·시험.
### RR9-02-20 · Medium · SPRING_PROFILES_ACTIVE=test면 배포 jar 통과 → prod 검사 모두 꺼짐(SecretSourceValidator…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B4 인증·인가
- 내용: `RuntimeEnvironmentProfileValidator.java:50` — SPRING_PROFILES_ACTIVE=test면 배포 jar 통과 → prod 검사 모두 꺼짐(SecretSourceValidator __LOCAL_DEV_·fixture-, fileserver unenforced, GraphQL 모드), JpaSafetySettings.java:32-33 local 편의 켜짐. RuntimeEnvironment.java:52 "test는 배포 환경 아님" 장치 없음. 고침: 배포 jar + test 표지 없음 → 기동 실패.
### RR9-02-21 · Medium · INFO 이하 로거 구분 없이 버림, 감사 로거 INFO(LoggingNotificationAudit.java:31,…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B6a 로그 내용
- 내용: `SamplingTurboFilter.java:46-56` — INFO 이하 로거 구분 없이 버림, 감사 로거 INFO(LoggingNotificationAudit.java:31, StructuredAdminAudit.java:25, StructuredFileserverAudit.java:21), prod 0.1 권장(app README:349, env-keys.yaml:838) → 감사 90% 손실. 고침: 감사 로거·marker 제외 + 시험.
### RR9-02-22 · Medium · 예외 통째 로그 → SQL·제약·값, 전송은 ServerFailureLog.of(ServerFailureLog.java:59-63). 고침:…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B6a 로그 내용
- 내용: `OutboxRelayScheduler.java:115-121`, `FileserverCleanupWorker.java:79-85,110-116` — 예외 통째 로그 → SQL·제약·값, 전송은 ServerFailureLog.of(ServerFailureLog.java:59-63). 고침: carrier면 ServerFailureLog 줄.
### RR9-02-23 · Medium · sub 없는 토큰 idpUserId=null → FileAccessSubject.java:24,…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B4 인증·인가
- 내용: `JwtToAuthenticatedPrincipalConverter.java:57` — sub 없는 토큰 idpUserId=null → FileAccessSubject.java:24, EdgeRateLimitSubject.java:25 NPE 500. AUTH_CLAIM_MAPPING_FAILED(OperationalError.java:33) 안 던짐, tenant claim 틀리면(:78) 문자열 매칭으로 AUTH_TOKEN_MALFORMED(SecurityErrorClassifier.java:110). 고침: 변환기에서 AUTH_CLAIM_MAPPING_FAILED 구조화. 구조적 위험.
### RR9-02-24 · Low · 금지 값; auth-kid-unknown.md:25, auth-token-rotation-failure.md:29 없는 JWKS 손잡이;…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B7 runbook 신호
- 내용: auth runbook(R2-4와 같은 원인): auth-claim-mapping-failed.md:20 토큰 payload, auth-token-malformed.md:20 Authorization 원문, auth-token-missing.md:20 — 금지 값; auth-kid-unknown.md:25, auth-token-rotation-failure.md:29 없는 JWKS 손잡이; auth-token-rotation-failure.md:16,33,64 없는 경보·지표; auth-issuer-mismatch.md:20 키 이름(app.security.issuer-uri / APP_SECURITY_JWT_ISSUER).
### RR9-02-25 · Low · `WebSocketConfig.java:93` 주석 틀림(거부 preSend…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B6a 로그 내용
- 내용: `WebSocketConfig.java:93` 주석 틀림(거부 preSend WebSocketInboundAuthorizationInterceptor.java:49, request_id는 beforeHandle WebSocketCorrelationInterceptor.java:34), 플랫폼 거부 로그 없음, Spring StompSubProtocolHandler가 거부 SEND만 ERROR, SUBSCRIBE 흔적 없음(A8). 고침: 거부 WARN, Spring 로거 레벨, 주석.
### RR9-02-26 · Low · 컨텍스트 속성만 바꿈, logback-spring.xml:89,122 ${APP_PROFILE}은 이미 치환 → JSON profile 칸…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B6a 로그 내용
- 내용: `ResolvedProfileLoggingContextListener.java:56` — 컨텍스트 속성만 바꿈, logback-spring.xml:89,122 ${APP_PROFILE}은 이미 치환 → JSON profile 칸 그대로, LogProfileDriftCharacterizationTest:38 속성만. 구조적 위험.
### RR9-02-27 · Low · in-process lock 미계량 → lock.acquisition 0, metrics.yaml:307 "1:1",…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B5 관측 registry
- 내용: `DistributedLockPersistenceConfig.java:48-50` — in-process lock 미계량 → lock.acquisition 0, metrics.yaml:307 "1:1", persistence-jpa README:563-564 "호출마다".
### RR9-02-28 · Low · "서버 허용 목록 이름이라 echo 안전"인데 요청 값 echo(PatchFieldAuthorization.java:59,…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B4 인증·인가
- 내용: `PatchAuthorizationException.java:15,25` — "서버 허용 목록 이름이라 echo 안전"인데 요청 값 echo(PatchFieldAuthorization.java:59, JsonPointerAuthorization.java:76) → details·메시지.
### RR9-02-29 · Low · tenant 규칙 갈림: WebTenantContextResolver.java:19-20 거부 목록에 tenant_id 없음,…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B4 인증·인가
- 내용: tenant 규칙 갈림: WebTenantContextResolver.java:19-20 거부 목록에 tenant_id 없음, GraphQlTenantIsolationPolicy.java:59 호출자 목록·대소문자, :41 source()==null 죽은 코드, 익명에 SYSTEM tenant(GraphQlRequestContextConfiguration.java:128, TenantContext.java:25), GraphQlContextPropagator.java:14 "모든 스레드 이동" 호출 0.
### RR9-02-30 · Low · `compose/redis/acl/README.md:43` advanced 계정 pub/sub 더함, 실제…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B19 compose·Docker 운영
- 내용: `compose/redis/acl/README.md:43` advanced 계정 pub/sub 더함, 실제 application-advanced.acl:1에 @pubsub 없음, redis-sdk README:58 "pub/sub 없음".
### RR9-02-31 · Low · `GraphQlClientPolicy.java:24` maxInputListElements "한 input list 상한"인데…
- 출처: 물결 2 보안·관측
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11b graphql·websocket 계약
- 내용: `GraphQlClientPolicy.java:24` maxInputListElements "한 input list 상한"인데 variables·extensions만(GraphQlJsonStructurePolicy.java:54).
@@ -0,0 +1,228 @@
# round9 영역 03 — API 계약·시험
- 대상: main `a7e38c10`(2026-11-12). 범위와 방법은 [README](README.md) 「범위」다.
- 발견마다: 출처(리뷰어), 증거 수준, 이전부터/최근 변경, 고칠 묶음(README 「묶음」). 원문의 `파일:줄`은 저장소 루트 기준이다.
### RR9-03-01 · Medium · 부분 실패 batch가 success:true + data.results. fullySucceeded() 미사용. 약속 충돌: web…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B12 fileserver·notification HTTP
- 내용: web-fileserver `FileUploadController.java:128-136`, `dto/BatchUploadResponse.java:18` — 부분 실패 batch가 success:true + data.results. fullySucceeded() 미사용. 약속 충돌: web AGENTS B8·docs/web/http-contract.md:29(success:false+BATCH_PARTIAL_FAILURE) vs docs/fileserver/http-contract.md:12,100·upgrade-guide:65(200+results[].error). → 소유자 결정 필요(약속끼리 다름). 이전부터.
### RR9-03-02 · Medium · partial() error.message 영어 고정, BulkItemResult 호출자 문구 그대로·null 키 남김(mix-in 아님,…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B12 fileserver·notification HTTP
- 내용: shared-contract `response/BulkEnvelope.java:28`, `BulkItemResult.java:13-21` — partial() error.message 영어 고정, BulkItemResult 호출자 문구 그대로·null 키 남김(mix-in 아님, EnvelopeWireFormatConfig.java:34-37). 근거 http-contract.md:44, error-codes.yaml:15-16(ClientErrorMessages). 고침: ClientErrorMessages.of(BATCH_PARTIAL_FAILURE), 항목 message 정리, mix-in. 이전부터.
### RR9-03-03 · Medium · 실제 long maxAgeSeconds(CorsSettings.java:19-20, config/security.yml:54) → 예시 그대로…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B2 env 계약
- 내용: `.env.example:79` APP_SECURITY_CORS_MAX_AGE=600s, env-keys.yaml:941-948(duration, 600s) — 실제 long maxAgeSeconds(CorsSettings.java:19-20, config/security.yml:54) → 예시 그대로 쓰면 기동 실패. 고침: int(초)·600. 이전부터.
### RR9-03-04 · Medium · env-keys.yaml:2563-2577·2670-2684…
- 출처: 물결 1 API 계약·시험(같은 결함을 물결 2 outbound도 적음)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B2 env 계약
- 내용: env-keys.yaml:2563-2577·2670-2684 APP_CACHE_REDIS_COMMAND_TIMEOUT·SEMANTIC_REGION "닿지 않음, 2026-11-30 제거"인데 cache-redis.yml:32,35 바인딩(기본 200ms vs registry 2s). 기본값 불일치: APP_RATE_LIMIT_REDIS_COMMAND_TIMEOUT 1s/200ms(cache-redis.yml:69), APP_LOG_LEVEL_SQL WARN/INFO(observability.yml:117), APP_CACHE_REDIS_POSITIVE_SOFT_TTL null/30s(cache-redis.yml:36). 이전부터.
### RR9-03-05 · Medium · docs/registries/headers.yaml:16,154 X-Request-Id·X-Correlation-Id type ulid(코드…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B5 관측 registry
- 내용: docs/registries/headers.yaml:16,154 X-Request-Id·X-Correlation-Id type ulid(코드 UUID, WebMvcRequestIdFilter.java:159,163,191; correlation [A-Za-z0-9._-]{1,128}). ETag·Location·Allow·Cache-Control·Vary·Content-Range·tus·Upload-* 행 없음. web README.md:487-490 "코드 미러, 맞추는 시험 있음", 없는 X-Api-Version "여기서 생산". HeaderRegistryRuntimeAlignmentTest 행 3개만. 고침: 타입·행·ApiHeaders 대조 시험. 이전부터.
### RR9-03-06 · Medium · 서버 포화를 전송마다 다른 코드: gRPC GrpcCallAdmission.java:82-83 RATE_LIMIT_EXCEEDED("요청이…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B13 전송 오류 코드
- 내용: 서버 포화를 전송마다 다른 코드: gRPC GrpcCallAdmission.java:82-83 RATE_LIMIT_EXCEEDED("요청이 너무 잦습니다"), web-advanced WebAdvancedError.java:23 ADMISSION_REFUSED 503, fileserver FileserverErrorCode.java:45 429 RATE_LIMIT, 공용 OperationalError.java:81 JOB_EXECUTOR_REJECTED. decisions 2.3 행 없음 → 소유자 결정(wire 바뀜). 이전부터.
### RR9-03-07 · Medium · 27개 중 23개 계약 문서에 없음, docs/fileserver/http-contract.md:79 예시 "data":…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B12 fileserver·notification HTTP
- 내용: application/fileserver `api/error/FileserverErrorCode.java` — 27개 중 23개 계약 문서에 없음, docs/fileserver/http-contract.md:79 예시 "data": null(NON_NULL 결정과 다름). 고침: 코드 표 + 예시. 이전부터.
### RR9-03-08 · Medium · grpc README.md:26-28 "전용 APP_* 키 registry에 없다"인데 APP_GRPC_SERVER_ENABLED…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B2 env 계약
- 내용: grpc README.md:26-28 "전용 APP_* 키 registry에 없다"인데 APP_GRPC_SERVER_ENABLED 등록(env-keys.yaml:4059). APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL registry·.env.example 없음. 이전부터.
### RR9-03-09 · Medium · Content-Range(MvcDownloadResponseWriter.java:43,…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B12 fileserver·notification HTTP
- 내용: FileserverHttpSurfaceConfiguration.java:43-56, http-contract.md:178-180 — Content-Range(MvcDownloadResponseWriter.java:43, FileserverProblemHeaders.java:55) 노출 헤더 목록 없음 → CORS 이어받기 못 함. 이전부터.
### RR9-03-10 · Low · MANAGEMENT_SERVER_ADDRESS registry 있음·.env.example 없음(R2-1 일부). 최근(#12).
- 출처: 물결 1 API 계약·시험(같은 결함을 물결 2 계약·문서도 적음)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B2 env 계약
- 내용: observability.yml:34, .env.example:22 — MANAGEMENT_SERVER_ADDRESS registry 있음·.env.example 없음(R2-1 일부). 최근(#12).
### RR9-03-11 · Low · OPERATION_NOT_FOUND(operation/OperationErrorCode.java) §4에 없음(decisions 2.3 「새…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B13 전송 오류 코드
- 내용: docs/web/http-contract.md:184-193 — OPERATION_NOT_FOUND(operation/OperationErrorCode.java) §4에 없음(decisions 2.3 「새 오류 코드 소유」). 이전부터.
### RR9-03-12 · Low · 모든 503이 REQUEST_TIMEOUT(retryable). §4는 비동기 시간 초과에만. 이전부터.
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B13 전송 오류 코드
- 내용: web `error/HttpStatusErrorCodes.java:31` — 모든 503이 REQUEST_TIMEOUT(retryable). §4는 비동기 시간 초과에만. 이전부터.
### RR9-03-13 · Low · 모르는 channel·slot·locale이 details 없는 BAD_PARAMETER(주석은 validation error, S4는…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B12 fileserver·notification HTTP
- 내용: NotificationSubmissionController.java:98-104,114-121, NotificationTemplateController.java:85,119-131 — 모르는 channel·slot·locale이 details 없는 BAD_PARAMETER(주석은 validation error, S4는 VALIDATION_FAILED), 201에 Location 없음, 경로 /notification-templates lowerCamel 아님(manual 11:37). 이전부터.
### RR9-03-14 · Low · ERROR frame code만(category·retryable 없음), 원인 사슬 어디 IAE든 BAD_PARAMETER(다른 전송은 실패…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11b graphql·websocket 계약
- 내용: websocket `SafeStompSubProtocolErrorHandler.java:51-58,62-67` — ERROR frame code만(category·retryable 없음), 원인 사슬 어디 IAE든 BAD_PARAMETER(다른 전송은 실패 자신만), Javadoc:16-17 "다른 전송과 같은 코드". 이전부터.
### RR9-03-15 · Low · Retry-After를 occurrence만 보고 붙임, 본문은 코드 값으로 좁힘(ErrorResponseFactory.java:42) →…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B12 fileserver·notification HTTP
- 내용: FileserverProblemHeaders.java:51 — Retry-After를 occurrence만 보고 붙임, 본문은 코드 값으로 좁힘(ErrorResponseFactory.java:42) → ATOMIC_PUBLISH_UNSUPPORTED 행 어긋남. 이전부터.
### RR9-03-16 · Low · 낡은 문서: GrpcStatusMapper.java:21 WORKLOG_NOT_FOUND 예시(ab5982e95 이후), graphql 스냅숏…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B13 전송 오류 코드
- 내용: 낡은 문서: GrpcStatusMapper.java:21 WORKLOG_NOT_FOUND 예시(ab5982e95 이후), graphql 스냅숏 머리말 없는 spi 패키지(graphql/build.gradle:149).
### RR9-03-17 · Medium · test에서 태그 없이 env-keys.yaml 읽음, modules.json 거슬러 ca.repository.root 가드 우회, 입력…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B16 시험 품질
- 내용: GraphQlDeploymentModeRegistryParityTest.java:26-46 — test에서 태그 없이 env-keys.yaml 읽음, modules.json 거슬러 ca.repository.root 가드 우회, 입력 미선언 → 캐시가 registry 변경 놓침. 근거 build-logic/AGENTS.md:14-17. 고침: document-contract로. 이전부터.
### RR9-03-18 · Medium · "값을 싣지 않는다" 단언에 예외 타입 없음 → 메시지 null NPE로 바꿔도 통과. 이전부터.
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B16 시험 품질
- 내용: WebSecurityContextBridgeTest.java:39-43, GraphQlScalarContractTest.java:83-89, GraphQlScalarSymmetryTest.java:80-85 — "값을 싣지 않는다" 단언에 예외 타입 없음 → 메시지 null NPE로 바꿔도 통과. 이전부터.
### RR9-03-19 · Low · 빈 목록이면 통과, GWT 없음. 고침: 메서드 목록 고정. 최근(#12 bb8bb31b9).
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B16 시험 품질
- 내용: FileserverAdminControllerRequestBodyValidationTest.java:27-41 — 빈 목록이면 통과, GWT 없음. 고침: 메서드 목록 고정. 최근(#12 bb8bb31b9).
### RR9-03-20 · Low · MvcUploadExecutorSaturationTest.java:112-121(이름 timeout인데 타입만), :45 sleep(200),…
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B16 시험 품질
- 내용: MvcUploadExecutorSaturationTest.java:112-121(이름 timeout인데 타입만), :45 sleep(200), GraphQlRequestDeadlineTest.java:101-104 sleep(500) 뒤 부재 단언. 이전부터.
### RR9-03-21 · Low · EnvelopeWireShapeTest
- 출처: 물결 1 API 계약·시험
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B16 시험 품질
- 내용: EnvelopeWireShapeTest — http-contract.md:9가 §1 증거로 대는데 data null 키 없음(:32), String→Envelope(:33), sort:null(:55), 부분 실패 message 안 봄. EnvelopeTest.java:34 when 둘. 이전부터.
### RR9-03-22 · Low · 영어 @DisplayName 381/940, // when 없는 3문장+ 테스트 약 890/1550(휴리스틱). 규칙은 "손댈 때 고침" →…
- 출처: 물결 1 API 계약·시험(같은 결함을 물결 2 arch-reviewer도 적음)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B16 시험 품질
- 내용: 영어 @DisplayName 381/940, // when 없는 3문장+ 테스트 약 890/1550(휴리스틱). 규칙은 "손댈 때 고침" → 일괄 전환은 소유자 결정. 표 입력 반복문·when 둘: WebSecurityContextBridgeTest.everySpelling…, HmacGraphQlCursorCodecTest:232, GraphQlMutationResultMapperTest:44.
### RR9-03-23 · Medium · web-advanced patch 위반이 세 코드(PATCH_REJECTED 400 / BAD_PARAMETER 400 IAE /…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11a web-advanced 계약
- 내용: web-advanced patch 위반이 세 코드(PATCH_REJECTED 400 / BAD_PARAMETER 400 IAE / PATCH_PATH_FORBIDDEN 403), 비JSON 본문 → readTree JacksonException → GlobalExceptionHandler.java:207 500 INTERNAL_ERROR. JsonPatchDocument.java:151-155,175, JsonPatchOperation.java:28-53, JsonMergePatchDocument.java:55-62,92, JsonPointerAuthorization.java:128-130. 근거 WebAdvancedError.java:26, README:61. 고침: JsonPatchRejectedException 통일 + 파싱 감쌈 + upgrade 행.
### RR9-03-24 · Medium · "결과를 문서 전체로 검증 후 적용" 약속, 검증기 안 받음.
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11a web-advanced 계약
- 내용: JsonMergePatchApplier.java:42-44, JsonPatchApplier.java:14-16, patch-contract.md:43-44,62-64 — "결과를 문서 전체로 검증 후 적용" 약속, 검증기 안 받음.
### RR9-03-25 · Medium · sequence 엄격 증가·heartbeat·idle·max-age·버퍼 상한·drain 재연결 약속, writer 아무것도 안…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11a web-advanced 계약
- 내용: streaming-contract.md:25,58-62,66-67,71-72 vs MvcStreamWriter.java:52-77 — sequence 엄격 증가·heartbeat·idle·max-age·버퍼 상한·drain 재연결 약속, writer 아무것도 안 함(GapAndDuplicateGuard·WebStreamSession·WebStreamDrainCoordinator main에 없음, IDLE_TIMEOUT·MAX_AGE 안 냄).
### RR9-03-26 · Medium · commit 뒤 실패 코드 DEPENDENCY_FAILURE 고정(registry·WebAdvancedError·§4 없음),…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11a web-advanced 계약
- 내용: MvcStreamWriter.java:97-100 — commit 뒤 실패 코드 DEPENDENCY_FAILURE 고정(registry·WebAdvancedError·§4 없음), StreamItemTooLargeException(README:67)·carrier 코드 버림.
### RR9-03-27 · Medium · 503+Retry-After 약속, guard bean만, 요청 경로에서 run 안 부름(manual 10 기준 3).
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11a web-advanced 계약
- 내용: virtual-thread-profile.md:16-17,36-40, advanced-capabilities.md:13 vs VirtualThreadMvcConfiguration.java:53-58 — 503+Retry-After 약속, guard bean만, 요청 경로에서 run 안 부름(manual 10 기준 3).
### RR9-03-28 · Medium · 정본 충돌 → 소유자 결정.
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11a web-advanced 계약
- 내용: web AGENTS.md:65 B2 "merge-patch+json 안 씀" vs patch-contract.md:22 "필드 변경은 merge patch" — 정본 충돌 → 소유자 결정.
### RR9-03-29 · Medium · Javadoc "Stable request-error code GRAPHQL_CURSOR_REJECTED"인데 플랫폼 거부·carrier 아님…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B11b graphql·websocket 계약
- 내용: GraphQlCursorException.java:10-15, GraphQlConnectionException.java:8-13 — Javadoc "Stable request-error code GRAPHQL_CURSOR_REJECTED"인데 플랫폼 거부·carrier 아님 → resolver 안에서 INTERNAL_ERROR+ERROR(GraphQlErrorCodeCatalogTest:58-61).
### RR9-03-30 · Medium · compose 병합 특성 시험이 어느 lane에서도 돌지 않았다
- 출처: 고치며 찾음(B19, 2026-11-13)
- 증거: E2(desktop 실행: `:app-bootstrap:integrationTest --tests '*ComposeMergeCharacterizationTest'`가 「No tests found」) · 이전부터
- 묶음: B19 compose·Docker 운영
- 내용: `src/bootstrap/app/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java` — `integrationTest` lane은 `requires`로 적은 클래스 넷만 고른다(`StrictTestLanePlugin.java:228-232`). `src/bootstrap/app/build.gradle`은 그 lane 입력에 compose 파일을 선언해 이 시험이 돈다고 적었다. 시험이 보던 것(기본·dev 조합 렌더링, 계약 스크립트)은 PR 단계 `verifyComposeProfiles`가 18개 lane으로 이미 본다. 고침: 시험과 입력 선언을 지운다.
### RR9-03-31 · Medium · application-objectstorage에 포트 계약 시험이 없다
- 출처: 고치며 찾음(그룹 C 문서 묶음 구조 리뷰, 2026-11-13)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B20 objectstorage 포트 계약
- 내용: `docs/manual/10-capabilities.md` 기준 5는 포트를 가진 모듈의 testFixtures에 포트 계약(추상 클래스)을 두고 fake와 실제 adapter가 모두 통과하게 한다. `src/application/objectstorage`에는 testFixtures가 없다. adapter testFixtures의 `ObjectStorageProviderContract`는 adapter 안 provider SPI를 시험하고 application 포트는 시험하지 않는다. 고침: 포트 계약을 application-objectstorage testFixtures에 두고 fake와 adapter(실제 벤더 lane 포함)가 상속한다.
### RR9-03-32 · Low · 알림 provider callback의 본문 없는 응답이 Envelope 예외로 적혀 있지 않다
- 출처: 고치며 찾음(그룹 C 문서 묶음 구조 리뷰, 2026-11-13)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: `NotificationCallbackMvcController`는 204·400·413·503을 본문 없이 답한다. `docs/web/http-contract.md` §1과 `docs/fileserver/http-contract.md` 「Envelope 규칙의 프로토콜 예외」는 Envelope가 아닌 응답을 fileserver 프로토콜 예외뿐인 것처럼 적는다. 고침: 동작은 그대로 두고(provider는 status만 읽고, 인증 전 경로라 이유를 싣지 않는다) 예외로 적는다. 6절 ⑦.
@@ -0,0 +1,319 @@
# round9 영역 04 — 빌드·문서
- 대상: main `a7e38c10`(2026-11-12). 범위와 방법은 [README](README.md) 「범위」다.
- 발견마다: 출처(리뷰어), 증거 수준, 이전부터/최근 변경, 고칠 묶음(README 「묶음」). 원문의 `파일:줄`은 저장소 루트 기준이다.
### RR9-04-01 · Medium · #12가 줄 더해 151/150, check-work-docs rc=1 → verify.sh docs·라운드 끝 실패. 같은 줄 "(W4…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · E2(실행) · 최근 변경
- 묶음: B1 문서·지침
- 내용: `docs/work/operate.md:120` — #12가 줄 더해 151/150, check-work-docs rc=1 → verify.sh docs·라운드 끝 실패. 같은 줄 "(W4 BE-OBS-A)" 묶음 ID(docs/work 금지), --history가 못 잡음. 고침: 문장 옮기고 ID 삭제, `W\d BE-` 패턴 검사에. E2. 최근 #12(1444d1e0).
### RR9-04-02 · Medium · `cd ~/workspace/<작업>/src` 뒤 ./gradlew(#10 뒤 src에 gradlew 없음). desktop-gates…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B1 문서·지침
- 내용: `docs/work/operate.md:57,87` — `cd ~/workspace/<작업>/src` 뒤 ./gradlew(#10 뒤 src에 gradlew 없음). desktop-gates 6단계가 이 절차로 보냄. 최근 #10.
### RR9-04-03 · Medium · "Gradle 루트가 src/라 두 단계 위", `--include-build ../../messaging-library` →…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B1 문서·지침
- 내용: `docs/work/reference/related-repos.md:19,22` — "Gradle 루트가 src/라 두 단계 위", `--include-build ../../messaging-library` → `../messaging-library`. 최근 #10.
### RR9-04-04 · Medium · 이름 바꾸기 `git grep -l 'dev\.caskeleton' -- src scripts`가 build.gradle:26,…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B18a 스크립트
- 내용: `README.md:122` — 이름 바꾸기 `git grep -l 'dev\.caskeleton' -- src scripts`가 build.gradle:26, JavaConventionsPlugin.java:67, config/spotbugs/exclude.xml(69줄)·exclude-test.xml(8줄) 놓침 → qualityCheck 실패. 고침: pathspec 넓힘. 최근 #10.
### RR9-04-05 · Medium · 없는 PublicPathSnapshotPlugin.java·updatePublicPathSnapshot, 없는 CI step. 고침:…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B3 공개 경로·관리 포트
- 내용: `docs/build.md:156,160,169` — 없는 PublicPathSnapshotPlugin.java·updatePublicPathSnapshot, 없는 CI step. 고침: `./gradlew verifyPublicPathSnapshot -PapprovePublicPathChange`. 이전부터. (R2-3·R3-7 문서 부분과 같은 자리)
### RR9-04-06 · Medium · `:app-bootstrap:test --tests '*CleanArchitectureTest'` 고르는 클래스…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B17 빌드
- 내용: `scripts/verify-mongodb-platform.sh:130` — `:app-bootstrap:test --tests '*CleanArchitectureTest'` 고르는 클래스 없음(architectureTest source set) → 항상 FAILED. persistence-mongo/AGENTS.md:155·docs/mongodb/repository-adaptation.md:123가 시킴. :156 태그 증거. 고침: :app-bootstrap:architectureTest, 이미지는 카탈로그 mongo-8. 이전부터.
### RR9-04-07 · Medium · `docs/work/experts.md:56-66` 3절 표가 스킬 paths와 갈림(be-build-ci…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B1 문서·지침
- 내용: `docs/work/experts.md:56-66` 3절 표가 스킬 paths와 갈림(be-build-ci settings.gradle·gradle.properties·Dockerfile·renovate.json, be-api-contract .env.example·docs/upgrade/**, be-security .trivyignore.yaml, be-testing docs/testing/**·container-images.properties, be-observability docs/runbooks/**, be-persistence docs/jpa/**·docs/mongodb/**, be-docs **/CLAUDE.md). test_claude_setup.py:158 이름만. 고침: 표가 paths 가리키게 or 대조 시험. 최근 #14(c611b06f).
### RR9-04-08 · Medium · 행이 코드와 다르고 「바뀜」 표시 없음: 64 docs-check workflow 없음, 193 build-logic 잠그지 않음 vs…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B1 문서·지침
- 내용: `docs/work/reference/decisions.md:64,193,194,199` — 행이 코드와 다르고 「바뀜」 표시 없음: 64 docs-check workflow 없음, 193 build-logic 잠그지 않음 vs build-logic/build.gradle:35-38 STRICT, 194 cosign keyless vs release.yml:8-11 키 쌍(11-07), 199 cd 따라감 vs 11-08 형식 검사 셸 거절(StrictLaneStagesPlugin.java:46-48). 193 이전부터, 나머지 최근 #7.
### RR9-04-09 · Medium · 단계 구성표 네 곳: docs/testing/TESTING_STRATEGY.md:146-148(틀림,…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18b 문서 본문
- 내용: 단계 구성표 네 곳: docs/testing/TESTING_STRATEGY.md:146-148(틀림, build.gradle:175-181,269-274), docs/build.md:28,34(testQualityCheck·verifyFeatureScaffold·graphqlStableTest 빠짐), gates.md:42, build.gradle:62-85 주석. 고침: gates.md 1절만 남기고 가리킴. 이전부터.
### RR9-04-10 · Medium · 33·36 지운…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B18b 문서 본문
- 내용: `docs/capability-status.md:16,33,35,36` — 33·36 지운 redis-sdk-topology.yml·notification-platform.yml·verifyNotificationEvidence, 35 relay가 app-bootstrap OutboxConfig(지금 :composition:outbox-relay, 같은 문서 :439), 없는 lane postgresqlLegacyOutboxConcurrentRelayIntegrationTest. HISTORY_HOLDERS라 reference 검사 안 봄. 최근 #7·이전부터.
### RR9-04-11 · Medium · nightly jpa-postgresql·release jpa-release-gate. 고침: digest. 이전부터.
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B17 빌드
- 내용: `gradle/container-images.properties:27-30` postgres-17·18 태그만(머리말 :8, gates.md:193, 함정 12와 다름) — nightly jpa-postgresql·release jpa-release-gate. 고침: digest. 이전부터.
### RR9-04-12 · Medium · 모든 ca.spring-library leaf(30) testImplementation에…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B17 빌드
- 내용: build-logic `SpringLibraryConventionPlugin.java:12-15` — 모든 ca.spring-library leaf(30) testImplementation에 spring-boot-starter-webmvc-test(Tomcat 포함), MockMvc 쓰는 leaf 5개. 예 identifier/gradle.lockfile:68-131, Tomcat 테스트 classpath lockfile 14개. 고침: 쓰는 leaf만. 이전부터(60b6a319).
### RR9-04-13 · Low · `gradle/libs.versions.toml` 미사용 칸: 120 errorprone-core, 121 findsecbugs-plugin,…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B17 빌드
- 내용: `gradle/libs.versions.toml` 미사용 칸: 120 errorprone-core, 121 findsecbugs-plugin, 123 jackson3-core, 125·126 jmh, 130 junit-platform-launcher(+70), 142 protobuf-java-legacy(+91 주석), 148·149 spock(+97-98, 머리말 12-18), 플러그인 174-177 spring-dependency-management·spotless·spotbugs·errorprone(루트 미적용 build.gradle:5-9), 167-170 주석의 libs.errorprone.core. 이전부터.
### RR9-04-14 · Low · "쓰는 lane만 다시 돈다"인데 JavaConventionsPlugin.java:279-288이 파일 전체를 모든 leaf 모든 Test…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B17 빌드
- 내용: `gradle/container-images.properties:3-5` — "쓰는 lane만 다시 돈다"인데 JavaConventionsPlugin.java:279-288이 파일 전체를 모든 leaf 모든 Test 입력으로 → 이미지 하나 바꿔도 domain-core 캐시 무효. postgres-16-4(:24-26) 미사용. 이전부터.
### RR9-04-15 · Low · 없는 클래스…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B17 빌드
- 내용: `config/spotbugs/exclude.xml:62-70` — 없는 클래스 ...bootstrap.autoconfigure.notification.observation.NotificationObservationTest, exclude-test.xml:102-109에 이미 있음. 이전부터.
### RR9-04-16 · Low · `src/adapter/outbound/notification/build.gradle:104` additionalSourceRoots 상대…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B17 빌드
- 내용: `src/adapter/outbound/notification/build.gradle:104` additionalSourceRoots 상대 경로 `../../../application/notification/src/main/java`(함정 10), JavaPublicTypes.java:35-37 없는 폴더 말없이 건너뜀 → 승인 update 시 줄어든 surface 기록. 고침: project(':application-notification').file(...), 없으면 실패. 이전부터.
### RR9-04-17 · Low · 검사 스크립트 정비: check-repo-layout.py:90-96 HISTORY_PREFIXES 없는 폴더…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B18a 스크립트
- 내용: 검사 스크립트 정비: check-repo-layout.py:90-96 HISTORY_PREFIXES 없는 폴더 셋(superpowers·evidence·study), docs/history/·docs/design/ 빠짐; 머리 주석에 부르는 쪽 없음(check-repo-layout, check-docs, check-work-docs, verify-httpclient-docs, verify-compose-profile-contracts); scripts/tests 시험 없음(check-repo-layout, check-review-index, verify-httpclient-docs). 이전부터·#10.
### RR9-04-18 · Low · docstring 낡음: check-docs.py:2,18,41 "검사 여섯"(여덟), check-work-docs.py:31 lychee…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18a 스크립트
- 내용: docstring 낡음: check-docs.py:2,18,41 "검사 여섯"(여덟), check-work-docs.py:31 lychee "PR workflow"(main). 이전부터·#7.
### RR9-04-19 · Low · `docs/README.md:187` "PR마다 workflow docs-check" → pr.yml done → :prCheck →…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B1 문서·지침
- 내용: `docs/README.md:187` "PR마다 workflow docs-check" → pr.yml done → :prCheck → documentCheck. 최근 #7.
### RR9-04-20 · Low · 기본 조립: docs/build.md:50-56·scripts/bootstrap-local.sh:12-14,42 "app 기동(Flyway…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18b 문서 본문
- 내용: 기본 조립: docs/build.md:50-56·scripts/bootstrap-local.sh:12-14,42 "app 기동(Flyway 포함)"(기본 web만, build.md:254), build.md:279 알림 키 "8종"(7개). 이전부터.
### RR9-04-21 · Low · `docs/roadmap/messaging-r2.md:45,48` 지운…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18b 문서 본문
- 내용: `docs/roadmap/messaging-r2.md:45,48` 지운 VerifyMessagingEvidenceTask·MessagingQualificationPlugin. 이전부터.
### RR9-04-22 · Low · #13이 합친 integration job을 가리킴: cache-redis/README.md:332,…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B18b 문서 본문
- 내용: #13이 합친 integration job을 가리킴: cache-redis/README.md:332, cache-redis/build.gradle:74, httpclient/build.gradle:233. 최근 #13.
### RR9-04-23 · Low · bootstrap-local.sh를 flock으로 직접(:33 ./gradlew --no-daemon 없음), "4.1절의 정리법"…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B1 문서·지침
- 내용: `.claude/agents/verify-api.md:21,23` — bootstrap-local.sh를 flock으로 직접(:33 ./gradlew --no-daemon 없음), "4.1절의 정리법" operate.md에 없음. 고침: scripts/verify.sh app --on here. 최근 c67c7131.
### RR9-04-24 · Low · `CLAUDE.md:8` "분야 지식 be-* 10개" 개수 복사(함정 6). 최근 #14.
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B1 문서·지침
- 내용: `CLAUDE.md:8` "분야 지식 be-* 10개" 개수 복사(함정 6). 최근 #14.
### RR9-04-25 · Low · `renovate.json:9,17` "either bot"·GitHub vulnerability alerts 전제, Gitea에서…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B18b 문서 본문
- 내용: `renovate.json:9,17` "either bot"·GitHub vulnerability alerts 전제, Gitea에서 Renovate 근거 없음, .github/dependency-vulnerability-policy.md:7,95 정책 수단으로 듦. 최근 #7.
### RR9-04-26 · Low · `scripts/run-compose-runtime-smoke.sh:388` lane마다 정적 계약 전체 재실행(compose config…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18a 스크립트
- 내용: `scripts/run-compose-runtime-smoke.sh:388` lane마다 정적 계약 전체 재실행(compose config ~650회/nightly), PR이 verifyComposeProfiles로 이미 함. 고침: 루프 전 한 번. 이전부터.
### RR9-04-27 · Low · handoff --force-recreate가 1단계 재시작 수 지움, ps -a -q 빈 결과면 restarts.txt 비고 || true로…
- 출처: 물결 1 빌드·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B18a 스크립트
- 내용: `run-compose-runtime-smoke.sh:533-537,602-606` — handoff --force-recreate가 1단계 재시작 수 지움, ps -a -q 빈 결과면 restarts.txt 비고 || true로 통과. 최근 50cd7154.
### RR9-04-28 · Medium · graphql AGENTS·README가 「모듈별 yml 금지」라 하지만 모듈이 config/graphql.yml을 읽는다
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18b 문서 본문
- 내용: graphql AGENTS.md:116, README.md:126,152,166-168 — "모듈별 yml 금지·없음"인데 config/graphql.yml 직접 읽음(GraphQlActivationEnvironmentPostProcessor:55, manual 10:67 예외), app.graphql.console.*, 지운 "execution profile".
### RR9-04-29 · Medium · `.env.example`의 APP_DATASOURCE_CONNECTION_TIMEOUT=5s는 registry가 기동 실패라 적은 값이다
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B2 env 계약
- 내용: .env.example:45 APP_DATASOURCE_CONNECTION_TIMEOUT=5s(registry가 기동 실패라 적은 값) — B2 묶음.
### RR9-04-30 · Medium · `.env.example`의 FORWARD_HEADERS_STRATEGY=native가 registry 기본 none과 다르다
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B2 env 계약
- 내용: .env.example:25 FORWARD_HEADERS_STRATEGY=native — registry 기본 none·"기본은 닫힘"(env-keys.yaml:135-140). 고침: 비우거나 none. — B2 묶음(기존 안은 example: native였음 → 리뷰어는 none 권함).
### RR9-04-31 · Low · `.env.example` 머리말 「Seven values」가 여섯만 나열하고, 폐기 키 48개에 값이 들어 있다
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B2 env 계약
- 내용: .env.example:12-15 "Seven values" 여섯, deprecated 48개 — B2 묶음.
### RR9-04-32 · Medium · cache-redis README가 운영 비밀로 폐기 키 넷을 넣으라고 한다
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B2 env 계약
- 내용: cache-redis/README.md:49-50 운영 비밀로 deprecated_orphaned 키 넷(APP_CACHE_REDIS_PASSWORD·_KEY_HMAC_SECRET, APP_IDEMPOTENCY_/LEASE_REDIS_KEY_HMAC_SECRET). 고침: APP_REDIS_AUTHENTICATION_*.
### RR9-04-33 · Medium · 지식 스킬 넷이 재배치 뒤에도 「명령은 src/에서」라고 한다
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B1 문서·지침
- 내용: 스킬 넷 "명령은 src/에서" — PR #16에서 고침(2249d442).
### RR9-04-34 · Low · docs/web/runbook.md:37,49,56-58 TTL "연산마다"(전역 APP_IDEMPOTENCY_TTL),…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B7 runbook 신호
- 내용: docs/web/runbook.md:37,49,56-58 TTL "연산마다"(전역 APP_IDEMPOTENCY_TTL), GracefulShutdownProbe(testFixtures)를 운영 장치로, routeTemplate tag 없음.
### RR9-04-35 · Low · docs/web/repository-adaptation.md:146-162 "앱은 애플리케이션 칸 강제 안 함" vs…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: docs/web/repository-adaptation.md:146-162 "앱은 애플리케이션 칸 강제 안 함" vs app.web.mvc.max-json-body-size 1MB 413(WebMvcPlatformSettings.java:31).
### RR9-04-36 · Low · openapi-32-compatibility.md가 아무도 만들지 않는 3.1.2 산출물·snapshot 불변식을 적는다
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: docs/web/openapi-32-compatibility.md:10,14,26 "3.1.2 릴리스 산출물", "3.1 snapshot" 불변식 — 만드는·대조하는 build 없음(샘플 삭제 뒤).
### RR9-04-37 · Low · 없는 metric·행 가리키는 runbook: authz-cross-tenant-violation.md:38,67,…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B7 runbook 신호
- 내용: 없는 metric·행 가리키는 runbook: authz-cross-tenant-violation.md:38,67, rate-limit-exceeded.md:38,68(gateway_rate_limit_*, 헤더 X-RateLimit-Remaining), dependency-unavailable.md:75(CACHE_UNAVAILABLE).
### RR9-04-38 · Low · 옮기거나 바꾼 타입: persistence-jpa/README.md:43 OutboxConfig,…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: 옮기거나 바꾼 타입: persistence-jpa/README.md:43 OutboxConfig, :220·application/core/README.md:287 IdempotencyProviderSelectionConfig→IdempotencyAutoConfiguration, docs/build.md:413 TracingProperties→TracingSettings, bootstrap/app/README.md:88 SecretSource→SecretSourcePort, web/README.md:472 JsonNullableModule, graphql AGENTS.md:104·README.md:130 GraphQlPlatformProperties→Settings, web/AGENTS.md:139 PeriodTest, application/core/AGENTS.md:80 OutboxEventIdFactory.
### RR9-04-39 · Low · 지운 샘플: defect-patterns.md:68 SampleDemoProfilesStartupSystemTest,…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: 지운 샘플: defect-patterns.md:68 SampleDemoProfilesStartupSystemTest, TESTING_STRATEGY.md:292, IdempotencyAutoConfiguration.java:24, ManagementSecurityConfig.java:35 Javadoc.
### RR9-04-40 · Low · graphql AGENTS.md:23-33·README.md:186 "messaging leaf registry 등록, 두 패턴…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: graphql AGENTS.md:23-33·README.md:186 "messaging leaf registry 등록, 두 패턴 공존"(#8), grpc AGENTS.md:44-45·README.md:62 "vendored 플랫폼 starter"(#6), docs/websocket/runbook.md:5·defect-patterns.md:20 leaf CLAUDE.md(지금 AGENTS.md).
### RR9-04-41 · Low · graphql AGENTS.md:19·README.md:183 "366개 java 파일"(246), AGENTS.md:160 "23…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: graphql AGENTS.md:19·README.md:183 "366개 java 파일"(246), AGENTS.md:160 "23 tests"(34), manual 06:58 registry 머리말 옛 영어 인용.
### RR9-04-42 · Low · leaf 안내 공백: application-notification·-fileserver·-objectstorage 가장 가까운 AGENTS가…
- 출처: 물결 2 계약·문서
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 최근 변경
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: leaf 안내 공백: application-notification·-fileserver·-objectstorage 가장 가까운 AGENTS가 루트뿐·README 없음, web-notification·web-fileserver·redis-runtime 자기 AGENTS·README 없음, docs/README.md 지도 security/ 행이 rate-limiting.md 안 덮음(#12).
### RR9-04-43 · Low · persistence-jpa release registry가 아무도 읽지 않는 PostgreSQL tag를 적는다
- 출처: 고치며 찾음(그룹 C 시험·빌드 묶음 리뷰, 2026-11-13)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B17 빌드 정리
- 내용: `src/adapter/outbound/persistence-jpa/release/release-registry.json`의 `databases[].image`가 `postgres:NN-alpine` tag다. `JpaReleaseManifest`는 major와 support-level만 읽고 lane은 `gradle/container-images.properties`의 digest를 쓴다. 카탈로그 밖에 이미지를 한 번 더 적은 곳이다. 고침: 칸을 지우고 이미지는 카탈로그가 정한다고 적는다.
### RR9-04-44 · Low · web 한도 표가 아무도 막지 않는 칸을 「늘 애플리케이션」이라 적는다
- 출처: 고치며 찾음(그룹 C 문서 묶음 리뷰, 2026-11-13)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: `docs/web/repository-adaptation.md` 8절 표의 query parameter 수·JSON 깊이·배열 크기·응답 크기 행이 「넘으면 누가 답하나」를 「늘 애플리케이션」이라 한다. 같은 절 머리말대로 그 칸은 `budget` 목록 값뿐이고 강제하는 코드가 없다. 고침: 실제로 막는 쪽(없음, Jackson 기본 한도, edge)을 적는다.
### RR9-04-45 · Low · objectstorage README가 registry에 있는 env 키를 「없다」고 한다
- 출처: 고치며 찾음(그룹 C 문서 묶음 구조 리뷰, 2026-11-13)
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B18c 낡은 이름·leaf 안내
- 내용: `src/adapter/outbound/objectstorage/README.md` 「env 키」가 「전용 `APP_*` 키는 없다」고 하지만 `docs/registries/env-keys.yaml`에 `APP_OBJECTSTORAGE_ENABLED`가 있다. 고침: 그 키 하나를 적는다.
@@ -0,0 +1,137 @@
# round9 영역 05 — 계층·도메인·SRP
- 대상: main `a7e38c10`(2026-11-12). 범위와 방법은 [README](README.md) 「범위」다.
- 발견마다: 출처(리뷰어), 증거 수준, 이전부터/최근 변경, 고칠 묶음(README 「묶음」). 원문의 `파일:줄`은 저장소 루트 기준이다.
### RR9-05-01 · High · controller가 domain `<Aggregate>Repository` 포트를 주입해도 안 걸림(HARD-STOP 2). 생성 명령이…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B14 아키텍처 규칙
- 내용: architectureTest `AdapterBoundaryArchitectureTest.java:410-421`, `WebForbiddenTypeCatalog.java:23` — controller가 domain `<Aggregate>Repository` 포트를 주입해도 안 걸림(HARD-STOP 2). 생성 명령이 포트를 `dev.caskeleton.domain.<f>`에 둠(Create__Feature__UseCase.java.tmpl:13), 규칙은 `..repository..`만, web testkit은 Spring Data·JPA만. gRPC 서비스는 ARE_CONTROLLERS 밖. 고침: inbound가 domain *Repository·*IdFactory, application *StorePort·*QueryPort 못 쓰게 + fixture. 현재 inbound import 0건.
### RR9-05-02 · High · inbound 밖 사용자 전송(bootstrap·composition controller, JWT converter)이…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B14 아키텍처 규칙
- 내용: `ApplicationBoundaryArchitectureTest.java:759-774,736-747,822-826` — inbound 밖 사용자 전송(bootstrap·composition controller, JWT converter)이 @SystemInvoked 유스케이스에 닿아도 통과, `new`·비@SystemCaller 중간 클래스 경유도 통과(OutboxRelayScheduler.java:51). manual 07:75 "빌드 실패" 약속. "bootstrap에 controller 금지"(app AGENTS) 규칙 없음. 고침: USER_TRANSPORTS 전이 대상에 @SystemInvoked, controller는 ..adapter.inbound.. 규칙.
### RR9-05-03 · Medium · web 밖 JWT…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B14 아키텍처 규칙
- 내용: (a) `ApplicationBoundaryArchitectureTest.java:472-494,523-558` — web 밖 JWT converter·JwtDecoder·OAuth2TokenValidator·AuthenticationProvider·AuthorizationManager·HttpSecurity 람다 설정 못 잡음(Filter·EntryPoint·AccessDeniedHandler·BearerTokenResolver는 잡힘). 고침: spring security web·oauth2 resource server·jwt 패키지와 두 타입을 목록에 + fixture.
### RR9-05-04 · Medium · `registration.interceptors(x)`에서 x가 구체 클래스 필드·생성자·new, ChannelInterceptor 지역…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B14 아키텍처 규칙
- 내용: (b) `:584-587,626-627` — `registration.interceptors(x)`에서 x가 구체 클래스 필드·생성자·new, ChannelInterceptor 지역 변수, 구체 반환 @Bean이면 설정 자신 안 잡힘(ArchUnit 1.3.0 anewarray 미기록). manual 07:107 과대 약속. 고침: assignable 검사 or 문서 한계.
### RR9-05-05 · Medium · capabilityProjects에 :adapter:inbound:messaging 없음 → 전체 ArchUnit이…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B14 아키텍처 규칙
- 내용: `src/bootstrap/app/build.gradle:131-143` — capabilityProjects에 :adapter:inbound:messaging 없음 → 전체 ArchUnit이 MessagingInboxAutoConfiguration 안 읽음. 125줄 주석 "모든 모듈". 고침: 목록·주석 runtimeOnly 줄.
### RR9-05-06 · Medium · 시스템 호출 쓰기가 유스케이스 계약 밖: fileserver DefaultCleanupService.java:32,…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15a application 구조
- 내용: `FileserverUseCaseContractDeviationTest.java:22-30,42-43` — 시스템 호출 쓰기가 유스케이스 계약 밖: fileserver DefaultCleanupService.java:32, DefaultFileReconciliationService.java:28; notification NotificationDispatchService.java:49, LeaseRecoveryService.java:36, ReconciliationService.java:32, ProviderEventProjectionService.java:17. 사용자·시스템이 같은 서비스(CleanupUploadsApplicationUseCase·FileserverCleanupWorker, admin·LeaseRecoveryService). 고침: @SystemInvoked 분리 or 결정 기록 + notification freeze 시험.
### RR9-05-07 · Medium · 연산 4개 inbound 포트, UseCase·capability·@RequiresPermission 없음, 쓰는 전송…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15a application 구조
- 내용: `NotificationAdminService.java:9`, `NotificationAdminApplicationService.java:45` — 연산 4개 inbound 포트, UseCase·capability·@RequiresPermission 없음, 쓰는 전송 없음(NotificationDeliveryConfiguration.java:167-169), 협력 객체 12. 고침: 유스케이스 4개 or 삭제.
### RR9-05-08 · Medium · `FileserverMaintenanceServiceConfiguration.java:27-63`(outbound adapter가…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15a application 구조
- 내용: `FileserverMaintenanceServiceConfiguration.java:27-63`(outbound adapter가 application 서비스 조립), NotificationPlatformPolicyConfig.java:79·89-92·140(retry ofMinutes(1)·jitter를 설정에서), NotificationPlatformDispatchConfig.java:65, notification worker가 adapter.outbound.notification(NotificationSchedulerWorker.java:31). 고침: composition으로, retry 값 settings.
### RR9-05-09 · Medium · 전송 4곳이 "upload.bin" 기본 이름(HARD-STOP 4·중복), application…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B12 fileserver·notification HTTP
- 내용: `RawUploadRequestMapper.java:23,44` 외 MultipartUploadRequestMapper.java:16, Draft12UploadController.java:244, TusController.java:115 — 전송 4곳이 "upload.bin" 기본 이름(HARD-STOP 4·중복), application OriginalFilenamePolicy.java:16은 "file". 고침: 전송은 없음으로, 정책 한 곳.
### RR9-05-10 · Medium · web이 outbound LiveEventReplayPort 직접 읽음(application-core AGENTS 「읽기·query 경로」).…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15a application 구조
- 내용: `MessagingReplayBridge.java:31,68` — web이 outbound LiveEventReplayPort 직접 읽음(application-core AGENTS 「읽기·query 경로」). 고침: 조회 유스케이스 + 1번 규칙.
### RR9-05-11 · Medium · operation id 문법 셋, owner token 64 hex(IdempotencyClaimAttempt.java:19) vs…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15b application 작은 것
- 내용: `OperationId.java:24`·`LeaseValidation.java:16-20`·`DurableOperationId.java:16` — operation id 문법 셋, owner token 64 hex(IdempotencyClaimAttempt.java:19) vs base64url. 고침: 값 타입 통일 or 이유.
### RR9-05-12 · Medium · 표시·문서만), notification…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15b application 작은 것
- 내용: 멱등 판정 세 벌: durable operation SubmitDurableOperationUseCase.java:54 KEYED인데 executor 안 씀(결정 15·26 지문 방식 — 표시·문서만), notification AcceptNotificationApplicationUseCase.java:140-155·NotificationRequestRecord.java:17·NotificationRequestStorePort.java:36 원본 키 저장·자체 판정(결정 없음). 고침: executor or 결정.
### RR9-05-13 · Low · durable operation이 core 공통 타입 안 따름: tenant·principal…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15b application 작은 것
- 내용: durable operation이 core 공통 타입 안 따름: tenant·principal String(OperationCommand.java:31-32, GetDurableOperationQuery.java:14, CancelDurableOperationCommand.java:14, DurableOperationAccessPolicy.java:25), DurableOperationIdFactory·Id가 IdFactory·ResourceId 아님(AGENTS:80 예외 없음), id를 controller에서 만듦.
### RR9-05-14 · Low · `SubmitDurableOperationUseCase.java:177-190` UUIDv7 파생을 유스케이스가 →…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15b application 작은 것
- 내용: `SubmitDurableOperationUseCase.java:177-190` UUIDv7 파생을 유스케이스가 → IntegrationIdentity로.
### RR9-05-15 · Low · 미사용 추상화: ReadConsistency.java:4(참조 0, persistence-jpa에 다른 모양 동명),…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15b application 작은 것
- 내용: 미사용 추상화: ReadConsistency.java:4(참조 0, persistence-jpa에 다른 모양 동명), FileserverSpans.java(span 안 냄), ProviderEventId.java, NotificationExpiredException.java, BatchNotificationProviderAdapter.java, CollapseCapability.java(시험만).
### RR9-05-16 · Low · application-core README.md:780 "final이 아니다", be-domain 함정 12.
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15b application 작은 것
- 내용: GetDurableOperationUseCase.java:18, PublishPendingOutboxEventsUseCase.java:43 final — application-core README.md:780 "final이 아니다", be-domain 함정 12.
### RR9-05-17 · Low · FileMetadataPort(insert·transition·markDeleting·relocate),…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15b application 작은 것
- 내용: FileMetadataPort(insert·transition·markDeleting·relocate), UploadSessionPort(acquireLease·commitOffset) 실패 결과 Javadoc 없음(어댑터 JpaFileMetadata.java:146-168만).
### RR9-05-18 · Low · `CanonicalNotificationPlanEncoder.java:73,78,262,264,265,282,299` 문자열에 NUL 바이트…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B15b application 작은 것
- 내용: `CanonicalNotificationPlanEncoder.java:73,78,262,264,265,282,299` 문자열에 NUL 바이트 → git·grep 바이너리. 고침: "\u0000".
### RR9-05-19 · Low · `FileserverAdminController.java:151-152,164-176` orphan apply·cleanup…
- 출처: 물결 2 arch-reviewer
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
- 묶음: B12 fileserver·notification HTTP
- 내용: `FileserverAdminController.java:151-152,164-176` orphan apply·cleanup 기본값(maxBytes 1<<30, reasonCode, dryRun)을 controller가 → application command 팩터리.
@@ -0,0 +1,270 @@
# round9 전체 리뷰 (2026-11-12)
## 1. 결론
main `a7e38c10`(Gradle 루트 재배치, gRPC·메시징 플랫폼 분리, 분야 전문가 스킬, CI 재편, red team 수정이 들어간 뒤)을
새 눈으로 전체 리뷰했다. 발견 152건: Critical 0, High 2, Medium 72, Low 78. 고치며 6건(Medium 2, Low 4)을 더 찾아 모두 158건이다. 이 밖에 CI workflow·`build.gradle`·`gates.md`처럼
백엔드 CI 세션이 고치는 중인 파일의 발견 9건은 그 세션에 넘겼다(5절).
- High 둘은 아키텍처 규칙의 사각지대다(HARD-STOP 2). controller가 domain repository 포트를 들어도, inbound 밖 사용자
전송이 `@SystemInvoked` 유스케이스에 닿아도 빌드가 통과한다(RR9-05-01·02).
- Medium의 큰 덩어리: env 계약이 registry·`.env.example`·배포 설정 사이에서 갈렸다(예시를 그대로 복사하면 JPA 배포가
기동하지 않는 값 포함), 공개 경로 게이트가 모듈 chain을 못 본다, 관측 registry와 코드의 지표·MDC 이름이 어긋난다,
claim·lease의 fence가 구현마다 갈렸다, 문서가 재배치 뒤 낡은 경로·명령을 가리킨다.
- 결함은 모두 고친다(`docs/work/improve.md` 4.5절). 원인 묶음마다 PR 하나다(4절).
## 2. 범위
- 대상: main `a7e38c10`, 작업 트리 깨끗함, 2026-11-12. 기준 게이트(desktop, `--no-cache`): `scripts/verify.sh pr` rc=0
(21:06~21:39, 시험 6724건 실패 0, skip 28), `scripts/verify.sh main` rc=0(시험 1867건 실패 0, skip 19). `nightly`·`release`
기준 실행은 desktop 잠금을 수정 검증에 쓰려고 접었다. 라운드 끝 게이트가 합친 트리에서 돈다(7절).
- 방법: `docs/work/experts.md`의 분야 렌즈로 `reviewer` 서브에이전트를 두 물결에 나눠 띄웠다(lead 스킬, 한 물결 4명).
모든 발견은 E1(현재 커밋 코드·문서 정적 확인)이고, 고칠 때 RED 시험(수정 전 실패)으로 다시 확인한다.
| 물결 | 렌즈 | 경로 |
| --- | --- | --- |
| 1 | be-persistence + be-messaging + be-performance | `src/adapter/outbound/**`, inbound messaging, outbox·멱등·durable operation 조립, 마이그레이션·runbook |
| 1 | be-security + be-observability | `src/bootstrap/app`, service-runtime, inbound 보안·필터, 보안·관측 registry, Dockerfile·compose |
| 1 | be-api-contract + be-testing | inbound 전송 계약, shared-contract, 계약 registry·스냅숏, 시험 품질 |
| 1 | be-build-ci + be-docs | build-logic, gradle, config, scripts, 진입 문서·`docs/**`·`.claude/**` |
| 2 | be-domain(`arch-reviewer`) | domain·application·shared-contract, HARD-STOP 1~5 전체, ArchUnit 사각지대 |
| 2 | be-persistence + be-performance + be-messaging | 물결 1이 못 본 outbound(mongo, redis-sdk, httpclient, objectstorage, notification, fileserver 등) |
| 2 | be-security + be-observability | 물결 1이 못 본 web-advanced·graphql·grpc·websocket·web-fileserver 보안, 조립 모듈, logback, auth runbook |
| 2 | be-api-contract + be-docs | web-advanced·graphql·websocket·tus 계약, 매뉴얼·runbook·모듈 README 본문 |
- 못 본 것(두 물결이 모두 「못 본 하위 경로」로 적은 곳): redis-sdk의 programmability·cluster·reactive, persistence-mongo의
csfle·qe·sharding, httpclient의 auth·dynamic·http3, objectstorage publication kernel 본문, web-advanced의 codec·openapi·
versioning, graphql의 cost scorer 내부. 다음 확인 리뷰가 표본으로 본다.
- 지난 라운드가 넘긴 항목: 동시 인덱스 `_ccold`(결함 아님, E1), 멱등 Redis Lua의 cluster 원자성(결함 아님, 남는 것은
failover 내구성 RR9-01-11), `RunbookSql` lane 목록(RR9-01-10), 메시징 인증 증거 대조(이 repo에서 닫힘, 라이브러리
repo의 일), compose smoke OOM(고쳐짐, 남은 틈 RR9-04-27), STOMP 밖 Spring Security 확장점·`registration.interceptors(x)`
사각지대(RR9-05-03·04).
## 3. 색인
| ID | 심각도 | 영역 | 내용 | 묶음 |
| --- | --- | --- | --- | --- |
| RR9-01-01 | Medium | 영속성·메시징·성능 | inbox TransactionRunner `new TransactionTemplate` timeout 없음 → 유스케이스… | B9 트랜잭션 시한·정리 |
| RR9-01-02 | Medium | 영속성·메시징·성능 | heartbeat·progress·succeed·fail이 lease_owner=:workerId만 확인, fence 없음. 같은… | B8 claim·fence |
| RR9-01-03 | Medium | 영속성·메시징·성능 | live_event_log 행 retention 지나도 안 지움, sweepExpired 호출자·스케줄 없음, 문서도 서비스 의무로 안… | B9 트랜잭션 시한·정리 |
| RR9-01-04 | Low | 영속성·메시징·성능 | 상한 없는 DELETE 한 문장(outbox는 1000행씩, OutboxEventJpaRepository.java:35-47),… | B8 claim·fence |
| RR9-01-05 | Low | 영속성·메시징·성능 | join() 시간 상한 없음,… | B10a 발행·발송·캐시 |
| RR9-01-06 | Low | 영속성·메시징·성능 | Javadoc "enqueue is an upsert"인데 UPDATE 0행이면 INSERT 두 단계, 동시 enqueue 시… | B8 claim·fence |
| RR9-01-07 | Low | 영속성·메시징·성능 | app.lock.wait-time 읽는 곳 없음(lease-ttl 교차 검사로 기동 막기만). README:559… | B9 트랜잭션 시한·정리 |
| RR9-01-08 | Low | 영속성·메시징·성능 | 408·429를 조건 없이 재시도로 적음, 코드(DefaultRetryEligibilityEngine.java:81-99,… | B10b S3·Mongo·httpclient |
| RR9-01-09 | Low | 영속성·메시징·성능 | 주석 "retention has no default on purpose"인데… | B9 트랜잭션 시한·정리 |
| RR9-01-10 | Low | 영속성·메시징·성능 | Javadoc lane 목록에 lock timeout runbook… | B9 트랜잭션 시한·정리 |
| RR9-01-11 | Low | 영속성·메시징·성능 | Redis 같은 키 재전송 안 돌린다를 조건 없이 약속, Sentinel·Cluster failover 비동기 복제 손실… | B10b S3·Mongo·httpclient |
| RR9-01-12 | Medium | 영속성·메시징·성능 | 회복이 행 잠금 없이 읽고(RecipientDeliveryJpaRepository.java:187-194) requeue 무조건… | B8 claim·fence |
| RR9-01-13 | Medium | 영속성·메시징·성능 | UPDATE … WHERE id IN (SELECT … LIMIT), 상태 조건 subquery 안만 → READ COMMITTED 재평가 안… | B8 claim·fence |
| RR9-01-14 | Medium | 영속성·메시징·성능 | poll마다 SQL 4개, PROJECTION_LAG WHERE 없음 → notification_provider_event 전체 스캔(지우는… | B9 트랜잭션 시한·정리 |
| RR9-01-15 | Medium | 영속성·메시징·성능 | ThreadPoolExecutor(1,n,LinkedBlockingQueue(4n)) 큐 찰 때까지 스레드 1, limiter 4로 큐 안… | B10a 발행·발송·캐시 |
| RR9-01-16 | Medium | 영속성·메시징·성능 | RejectedExecution을 AMBIGUOUS_SUBMISSION으로(SMTP 상태 조회 없음 → 운영자 대기),… | B10a 발행·발송·캐시 |
| RR9-01-17 | Medium | 영속성·메시징·성능 | 캐시가 대기 예산 없는 run → lane 대기 2s + commandTimeout, @param "ceiling on one cache… | B10a 발행·발송·캐시 |
| RR9-01-18 | Medium | 영속성·메시징·성능 | 캐시 값 크기 상한 없음(옛 키 폐기 env-keys.yaml:2686-2689, RedisKeyRules는 키만). 고침: encode 길이… | B10a 발행·발송·캐시 |
| RR9-01-19 | Medium | 영속성·메시징·성능 | 조건부 PUT 본문 재전송 가능 → SDK 재시도가 412 → ObjectControlConflictException,… | B10b S3·Mongo·httpclient |
| RR9-01-20 | Medium | 영속성·메시징·성능 | getMappedResults 전부 메모리 후 셈, maxResultBytes 미집행(95), query-aggregation-guide… | B10b S3·Mongo·httpclient |
| RR9-01-21 | Medium | 영속성·메시징·성능 | heap 384m을 512m tmpfs에 dump, 같은 cgroup·swap 없음 → dump 중 OOM kill 가능,… | B19 compose·Docker 운영 |
| RR9-01-22 | Low | 영속성·메시징·성능 | (넘어온 1) .env.example:193 POSITIVE_SOFT_TTL= → 빈 Duration null → setter 안 불림 →… | B2 env 계약 |
| RR9-01-23 | Low | 영속성·메시징·성능 | max-items 100을 10분 lease로 한꺼번에 claim, lease 안에 끝나는지 검사 없음(outbox… | B8 claim·fence |
| RR9-01-24 | Low | 영속성·메시징·성능 | "lease > provider 호출·timeout" 주석만, 검사 없음. | B8 claim·fence |
| RR9-01-25 | Low | 영속성·메시징·성능 | 트랜잭션 30초 상한 없음(decisions 2.5), row cap 사후 검사(inbox 건과 같은 원인). | B9 트랜잭션 시한·정리 |
| RR9-01-26 | Low | 영속성·메시징·성능 | 새 pool 크기 모른 채 합계 미만만 봄 → 상한 초과, Javadoc "would exceed". | B9 트랜잭션 시한·정리 |
| RR9-01-27 | Low | 영속성·메시징·성능 | acquire void, idle 판정 마지막 acquire 시각 → 사용 중 client 닫음, 닫기 실패가 다른 tenant… | B10b S3·Mongo·httpclient |
| RR9-01-28 | Low | 영속성·메시징·성능 | requireCurrentFence가 UNFENCED만 거름(MongoMigrationLock.java:32), refresh(166-170)… | B10b S3·Mongo·httpclient |
| RR9-01-29 | Low | 영속성·메시징·성능 | lease 만료 시계 구현마다 다름: JpaRecipientLeaseStore.java:52,117,… | B8 claim·fence |
| RR9-01-30 | Low | 영속성·메시징·성능 | compression=true면 Apache가 푼 스트림을 wire 계수기가 셈(ApacheClientFactory.java:114-116)… | B10b S3·Mongo·httpclient |
| RR9-01-31 | Low | 영속성·메시징·성능 | ProxyType.SOCKS를 HTTP 프록시로, capability… | B10b S3·Mongo·httpclient |
| RR9-02-01 | Medium | 보안·관측 | 관리 포트 기본 127.0.0.1(PR #12)인데 service-runtime/README.md:275-276·Dockerfile:221은… | B3 공개 경로·관리 포트 |
| RR9-02-02 | Medium | 보안·관측 | 최상위 `roles` 클레임 fallback을 권한에 합침. manual 07:51-53·decisions 2.6 「JWT… | B4 인증·인가 |
| RR9-02-03 | Medium | 보안·관측 | config/security.yml 한 줄만 읽음, 문서(gates.md:63, build.md:166)는 보안 체인 전체 약속.… | B3 공개 경로·관리 포트 |
| RR9-02-04 | Medium | 보안·관측 | runbook 둘이 없는 신호로 탐지:… | B7 runbook 신호 |
| RR9-02-05 | Medium | 보안·관측 | `docs/registries/metrics.yaml` 양방향 불일치: 코드 없는… | B5 관측 registry |
| RR9-02-06 | Medium | 보안·관측 | JMX 9999 무인증·무TLS, jmxremote.host 없어 모든 인터페이스. 주석 15·54 "localhost only". 고침:… | B3 공개 경로·관리 포트 |
| RR9-02-07 | Low | 보안·관측 | 18키 중 5개만 코드가 넣음(logback-spring.xml:90-94). tenant_id(77-88) required_in인데… | B5 관측 registry |
| RR9-02-08 | Low | 보안·관측 | 전송별 correlation 규칙 다름: web(WebMvcRequestIdFilter.java:189-191),… | B5 관측 registry |
| RR9-02-09 | Low | 보안·관측 | 401·403 WARN에 원본 getRequestURI(Javadoc 15-19 "only redacted"). 같은 모양… | B6a 로그 내용 |
| RR9-02-10 | Low | 보안·관측 | IP 신뢰 문서 둘: application-local.yml:120-121 "framework via… | B6b 비밀·IP 문서 |
| RR9-02-11 | Low | 보안·관측 | config/security.yml:23 `SECURITY_PUBLIC_PATHS`, config/runtime.yml:18… | B2 env 계약 |
| RR9-02-12 | Low | 보안·관측 | masking_rule full_except_last_4 구현 없음(LogMaskingPatterns.java:23-41 URI… | B6b 비밀·IP 문서 |
| RR9-02-13 | Low | 보안·관측 | 로컬 비밀 기본값 `__LOCAL_DEV_` 규칙 미준수: compose.yaml:108·158, application-local.yml:55… | B6b 비밀·IP 문서 |
| RR9-02-14 | Low | 보안·관측 | "The standalone sample does that." 지운 샘플(ab5982e9). 최근. | B6b 비밀·IP 문서 |
| RR9-02-15 | Low | 보안·관측 | main 호출자 없음, WebMvcRequestIdFilter.java:182-188이 버린 규칙. 고침: 클래스·시험·README:511… | B6a 로그 내용 |
| RR9-02-16 | Medium | 보안·관측 | 인증 없는 모르는 profile POST → ISE → GlobalExceptionHandler.java:213… | B4 인증·인가 |
| RR9-02-17 | Medium | 보안·관측 | root 좌표만 판정, GraphQlAuthorizationPolicy.java:11-16 builder는 User.salary 하위 좌표… | B4 인증·인가 |
| RR9-02-18 | Medium | 보안·관측 | @RequiresPermission web만: gRPC principal을… | B4 인증·인가 |
| RR9-02-19 | Medium | 보안·관측 | 모든 projection을 /topic 하나로 모든 인증 세션에, tenant·소유자 판정 없음, README 「한계」 95-106 없음.… | B11b graphql·websocket 계약 |
| RR9-02-20 | Medium | 보안·관측 | SPRING_PROFILES_ACTIVE=test면 배포 jar 통과 → prod 검사 모두 꺼짐(SecretSourceValidator… | B4 인증·인가 |
| RR9-02-21 | Medium | 보안·관측 | INFO 이하 로거 구분 없이 버림, 감사 로거 INFO(LoggingNotificationAudit.java:31,… | B6a 로그 내용 |
| RR9-02-22 | Medium | 보안·관측 | 예외 통째 로그 → SQL·제약·값, 전송은 ServerFailureLog.of(ServerFailureLog.java:59-63). 고침:… | B6a 로그 내용 |
| RR9-02-23 | Medium | 보안·관측 | sub 없는 토큰 idpUserId=null → FileAccessSubject.java:24,… | B4 인증·인가 |
| RR9-02-24 | Low | 보안·관측 | 금지 값; auth-kid-unknown.md:25, auth-token-rotation-failure.md:29 없는 JWKS 손잡이;… | B7 runbook 신호 |
| RR9-02-25 | Low | 보안·관측 | `WebSocketConfig.java:93` 주석 틀림(거부 preSend… | B6a 로그 내용 |
| RR9-02-26 | Low | 보안·관측 | 컨텍스트 속성만 바꿈, logback-spring.xml:89,122 ${APP_PROFILE}은 이미 치환 → JSON profile 칸… | B6a 로그 내용 |
| RR9-02-27 | Low | 보안·관측 | in-process lock 미계량 → lock.acquisition 0, metrics.yaml:307 "1:1",… | B5 관측 registry |
| RR9-02-28 | Low | 보안·관측 | "서버 허용 목록 이름이라 echo 안전"인데 요청 값 echo(PatchFieldAuthorization.java:59,… | B4 인증·인가 |
| RR9-02-29 | Low | 보안·관측 | tenant 규칙 갈림: WebTenantContextResolver.java:19-20 거부 목록에 tenant_id 없음,… | B4 인증·인가 |
| RR9-02-30 | Low | 보안·관측 | `compose/redis/acl/README.md:43` advanced 계정 pub/sub 더함, 실제… | B19 compose·Docker 운영 |
| RR9-02-31 | Low | 보안·관측 | `GraphQlClientPolicy.java:24` maxInputListElements "한 input list 상한"인데… | B11b graphql·websocket 계약 |
| RR9-03-01 | Medium | API 계약·시험 | 부분 실패 batch가 success:true + data.results. fullySucceeded() 미사용. 약속 충돌: web… | B12 fileserver·notification HTTP |
| RR9-03-02 | Medium | API 계약·시험 | partial() error.message 영어 고정, BulkItemResult 호출자 문구 그대로·null 키 남김(mix-in 아님,… | B12 fileserver·notification HTTP |
| RR9-03-03 | Medium | API 계약·시험 | 실제 long maxAgeSeconds(CorsSettings.java:19-20, config/security.yml:54) → 예시 그대로… | B2 env 계약 |
| RR9-03-04 | Medium | API 계약·시험 | env-keys.yaml:2563-2577·2670-2684… | B2 env 계약 |
| RR9-03-05 | Medium | API 계약·시험 | docs/registries/headers.yaml:16,154 X-Request-Id·X-Correlation-Id type ulid(코드… | B5 관측 registry |
| RR9-03-06 | Medium | API 계약·시험 | 서버 포화를 전송마다 다른 코드: gRPC GrpcCallAdmission.java:82-83 RATE_LIMIT_EXCEEDED("요청이… | B13 전송 오류 코드 |
| RR9-03-07 | Medium | API 계약·시험 | 27개 중 23개 계약 문서에 없음, docs/fileserver/http-contract.md:79 예시 "data":… | B12 fileserver·notification HTTP |
| RR9-03-08 | Medium | API 계약·시험 | grpc README.md:26-28 "전용 APP_* 키 registry에 없다"인데 APP_GRPC_SERVER_ENABLED… | B2 env 계약 |
| RR9-03-09 | Medium | API 계약·시험 | Content-Range(MvcDownloadResponseWriter.java:43,… | B12 fileserver·notification HTTP |
| RR9-03-10 | Low | API 계약·시험 | MANAGEMENT_SERVER_ADDRESS registry 있음·.env.example 없음(R2-1 일부). 최근(#12). | B2 env 계약 |
| RR9-03-11 | Low | API 계약·시험 | OPERATION_NOT_FOUND(operation/OperationErrorCode.java) §4에 없음(decisions 2.3 「새… | B13 전송 오류 코드 |
| RR9-03-12 | Low | API 계약·시험 | 모든 503이 REQUEST_TIMEOUT(retryable). §4는 비동기 시간 초과에만. 이전부터. | B13 전송 오류 코드 |
| RR9-03-13 | Low | API 계약·시험 | 모르는 channel·slot·locale이 details 없는 BAD_PARAMETER(주석은 validation error, S4는… | B12 fileserver·notification HTTP |
| RR9-03-14 | Low | API 계약·시험 | ERROR frame code만(category·retryable 없음), 원인 사슬 어디 IAE든 BAD_PARAMETER(다른 전송은 실패… | B11b graphql·websocket 계약 |
| RR9-03-15 | Low | API 계약·시험 | Retry-After를 occurrence만 보고 붙임, 본문은 코드 값으로 좁힘(ErrorResponseFactory.java:42) →… | B12 fileserver·notification HTTP |
| RR9-03-16 | Low | API 계약·시험 | 낡은 문서: GrpcStatusMapper.java:21 WORKLOG_NOT_FOUND 예시(ab5982e95 이후), graphql 스냅숏… | B13 전송 오류 코드 |
| RR9-03-17 | Medium | API 계약·시험 | test에서 태그 없이 env-keys.yaml 읽음, modules.json 거슬러 ca.repository.root 가드 우회, 입력… | B16 시험 품질 |
| RR9-03-18 | Medium | API 계약·시험 | "값을 싣지 않는다" 단언에 예외 타입 없음 → 메시지 null NPE로 바꿔도 통과. 이전부터. | B16 시험 품질 |
| RR9-03-19 | Low | API 계약·시험 | 빈 목록이면 통과, GWT 없음. 고침: 메서드 목록 고정. 최근(#12 bb8bb31b9). | B16 시험 품질 |
| RR9-03-20 | Low | API 계약·시험 | MvcUploadExecutorSaturationTest.java:112-121(이름 timeout인데 타입만), :45 sleep(200),… | B16 시험 품질 |
| RR9-03-21 | Low | API 계약·시험 | EnvelopeWireShapeTest | B16 시험 품질 |
| RR9-03-22 | Low | API 계약·시험 | 영어 @DisplayName 381/940, // when 없는 3문장+ 테스트 약 890/1550(휴리스틱). 규칙은 "손댈 때 고침" →… | B16 시험 품질 |
| RR9-03-23 | Medium | API 계약·시험 | web-advanced patch 위반이 세 코드(PATCH_REJECTED 400 / BAD_PARAMETER 400 IAE /… | B11a web-advanced 계약 |
| RR9-03-24 | Medium | API 계약·시험 | "결과를 문서 전체로 검증 후 적용" 약속, 검증기 안 받음. | B11a web-advanced 계약 |
| RR9-03-25 | Medium | API 계약·시험 | sequence 엄격 증가·heartbeat·idle·max-age·버퍼 상한·drain 재연결 약속, writer 아무것도 안… | B11a web-advanced 계약 |
| RR9-03-26 | Medium | API 계약·시험 | commit 뒤 실패 코드 DEPENDENCY_FAILURE 고정(registry·WebAdvancedError·§4 없음),… | B11a web-advanced 계약 |
| RR9-03-27 | Medium | API 계약·시험 | 503+Retry-After 약속, guard bean만, 요청 경로에서 run 안 부름(manual 10 기준 3). | B11a web-advanced 계약 |
| RR9-03-28 | Medium | API 계약·시험 | 정본 충돌 → 소유자 결정. | B11a web-advanced 계약 |
| RR9-03-29 | Medium | API 계약·시험 | Javadoc "Stable request-error code GRAPHQL_CURSOR_REJECTED"인데 플랫폼 거부·carrier 아님… | B11b graphql·websocket 계약 |
| RR9-03-30 | Medium | API 계약·시험 | compose 병합 특성 시험이 어느 lane에서도 돌지 않았다 | B19 compose·Docker 운영 |
| RR9-03-31 | Medium | API 계약·시험 | application-objectstorage에 포트 계약 시험이 없다(manual 10 기준 5) | B20 objectstorage 포트 계약 |
| RR9-03-32 | Low | API 계약·시험 | 알림 provider callback의 본문 없는 응답이 Envelope 예외로 적혀 있지 않다 | B18c 낡은 이름·leaf 안내 |
| RR9-04-01 | Medium | 빌드·문서 | #12가 줄 더해 151/150, check-work-docs rc=1 → verify.sh docs·라운드 끝 실패. 같은 줄 "(W4… | B1 문서·지침 |
| RR9-04-02 | Medium | 빌드·문서 | `cd ~/workspace/<작업>/src` 뒤 ./gradlew(#10 뒤 src에 gradlew 없음). desktop-gates… | B1 문서·지침 |
| RR9-04-03 | Medium | 빌드·문서 | "Gradle 루트가 src/라 두 단계 위", `--include-build ../../messaging-library` →… | B1 문서·지침 |
| RR9-04-04 | Medium | 빌드·문서 | 이름 바꾸기 `git grep -l 'dev\.caskeleton' -- src scripts`가 build.gradle:26,… | B18a 스크립트 |
| RR9-04-05 | Medium | 빌드·문서 | 없는 PublicPathSnapshotPlugin.java·updatePublicPathSnapshot, 없는 CI step. 고침:… | B3 공개 경로·관리 포트 |
| RR9-04-06 | Medium | 빌드·문서 | `:app-bootstrap:test --tests '*CleanArchitectureTest'` 고르는 클래스… | B17 빌드 |
| RR9-04-07 | Medium | 빌드·문서 | `docs/work/experts.md:56-66` 3절 표가 스킬 paths와 갈림(be-build-ci… | B1 문서·지침 |
| RR9-04-08 | Medium | 빌드·문서 | 행이 코드와 다르고 「바뀜」 표시 없음: 64 docs-check workflow 없음, 193 build-logic 잠그지 않음 vs… | B1 문서·지침 |
| RR9-04-09 | Medium | 빌드·문서 | 단계 구성표 네 곳: docs/testing/TESTING_STRATEGY.md:146-148(틀림,… | B18b 문서 본문 |
| RR9-04-10 | Medium | 빌드·문서 | 33·36 지운… | B18b 문서 본문 |
| RR9-04-11 | Medium | 빌드·문서 | nightly jpa-postgresql·release jpa-release-gate. 고침: digest. 이전부터. | B17 빌드 |
| RR9-04-12 | Medium | 빌드·문서 | 모든 ca.spring-library leaf(30) testImplementation에… | B17 빌드 |
| RR9-04-13 | Low | 빌드·문서 | `gradle/libs.versions.toml` 미사용 칸: 120 errorprone-core, 121 findsecbugs-plugin,… | B17 빌드 |
| RR9-04-14 | Low | 빌드·문서 | "쓰는 lane만 다시 돈다"인데 JavaConventionsPlugin.java:279-288이 파일 전체를 모든 leaf 모든 Test… | B17 빌드 |
| RR9-04-15 | Low | 빌드·문서 | 없는 클래스… | B17 빌드 |
| RR9-04-16 | Low | 빌드·문서 | `src/adapter/outbound/notification/build.gradle:104` additionalSourceRoots 상대… | B17 빌드 |
| RR9-04-17 | Low | 빌드·문서 | 검사 스크립트 정비: check-repo-layout.py:90-96 HISTORY_PREFIXES 없는 폴더… | B18a 스크립트 |
| RR9-04-18 | Low | 빌드·문서 | docstring 낡음: check-docs.py:2,18,41 "검사 여섯"(여덟), check-work-docs.py:31 lychee… | B18a 스크립트 |
| RR9-04-19 | Low | 빌드·문서 | `docs/README.md:187` "PR마다 workflow docs-check" → pr.yml done → :prCheck →… | B1 문서·지침 |
| RR9-04-20 | Low | 빌드·문서 | 기본 조립: docs/build.md:50-56·scripts/bootstrap-local.sh:12-14,42 "app 기동(Flyway… | B18b 문서 본문 |
| RR9-04-21 | Low | 빌드·문서 | `docs/roadmap/messaging-r2.md:45,48` 지운… | B18b 문서 본문 |
| RR9-04-22 | Low | 빌드·문서 | #13이 합친 integration job을 가리킴: cache-redis/README.md:332,… | B18b 문서 본문 |
| RR9-04-23 | Low | 빌드·문서 | bootstrap-local.sh를 flock으로 직접(:33 ./gradlew --no-daemon 없음), "4.1절의 정리법"… | B1 문서·지침 |
| RR9-04-24 | Low | 빌드·문서 | `CLAUDE.md:8` "분야 지식 be-* 10개" 개수 복사(함정 6). 최근 #14. | B1 문서·지침 |
| RR9-04-25 | Low | 빌드·문서 | `renovate.json:9,17` "either bot"·GitHub vulnerability alerts 전제, Gitea에서… | B18b 문서 본문 |
| RR9-04-26 | Low | 빌드·문서 | `scripts/run-compose-runtime-smoke.sh:388` lane마다 정적 계약 전체 재실행(compose config… | B18a 스크립트 |
| RR9-04-27 | Low | 빌드·문서 | handoff --force-recreate가 1단계 재시작 수 지움, ps -a -q 빈 결과면 restarts.txt 비고 || true로… | B18a 스크립트 |
| RR9-04-28 | Medium | 빌드·문서 | graphql AGENTS·README가 「모듈별 yml 금지」라 하지만 모듈이 config/graphql.yml을 읽는다 | B18b 문서 본문 |
| RR9-04-29 | Medium | 빌드·문서 | `.env.example`의 APP_DATASOURCE_CONNECTION_TIMEOUT=5s는 registry가 기동 실패라 적은 값이다 | B2 env 계약 |
| RR9-04-30 | Medium | 빌드·문서 | `.env.example`의 FORWARD_HEADERS_STRATEGY=native가 registry 기본 none과 다르다 | B2 env 계약 |
| RR9-04-31 | Low | 빌드·문서 | `.env.example` 머리말 「Seven values」가 여섯만 나열하고, 폐기 키 48개에 값이 들어 있다 | B2 env 계약 |
| RR9-04-32 | Medium | 빌드·문서 | cache-redis README가 운영 비밀로 폐기 키 넷을 넣으라고 한다 | B2 env 계약 |
| RR9-04-33 | Medium | 빌드·문서 | 지식 스킬 넷이 재배치 뒤에도 「명령은 src/에서」라고 한다 | B1 문서·지침 |
| RR9-04-34 | Low | 빌드·문서 | docs/web/runbook.md:37,49,56-58 TTL "연산마다"(전역 APP_IDEMPOTENCY_TTL),… | B7 runbook 신호 |
| RR9-04-35 | Low | 빌드·문서 | docs/web/repository-adaptation.md:146-162 "앱은 애플리케이션 칸 강제 안 함" vs… | B18c 낡은 이름·leaf 안내 |
| RR9-04-36 | Low | 빌드·문서 | openapi-32-compatibility.md가 아무도 만들지 않는 3.1.2 산출물·snapshot 불변식을 적는다 | B18c 낡은 이름·leaf 안내 |
| RR9-04-37 | Low | 빌드·문서 | 없는 metric·행 가리키는 runbook: authz-cross-tenant-violation.md:38,67,… | B7 runbook 신호 |
| RR9-04-38 | Low | 빌드·문서 | 옮기거나 바꾼 타입: persistence-jpa/README.md:43 OutboxConfig,… | B18c 낡은 이름·leaf 안내 |
| RR9-04-39 | Low | 빌드·문서 | 지운 샘플: defect-patterns.md:68 SampleDemoProfilesStartupSystemTest,… | B18c 낡은 이름·leaf 안내 |
| RR9-04-40 | Low | 빌드·문서 | graphql AGENTS.md:23-33·README.md:186 "messaging leaf registry 등록, 두 패턴… | B18c 낡은 이름·leaf 안내 |
| RR9-04-41 | Low | 빌드·문서 | graphql AGENTS.md:19·README.md:183 "366개 java 파일"(246), AGENTS.md:160 "23… | B18c 낡은 이름·leaf 안내 |
| RR9-04-42 | Low | 빌드·문서 | leaf 안내 공백: application-notification·-fileserver·-objectstorage 가장 가까운 AGENTS가… | B18c 낡은 이름·leaf 안내 |
| RR9-04-43 | Low | 빌드·문서 | persistence-jpa release registry가 아무도 읽지 않는 PostgreSQL tag를 적는다 | B17 빌드 정리 |
| RR9-04-44 | Low | 빌드·문서 | web 한도 표가 아무도 막지 않는 칸을 「늘 애플리케이션」이라 적는다 | B18c 낡은 이름·leaf 안내 |
| RR9-04-45 | Low | 빌드·문서 | objectstorage README가 registry에 있는 env 키를 「없다」고 한다 | B18c 낡은 이름·leaf 안내 |
| RR9-05-01 | High | 계층·도메인·SRP | controller가 domain `<Aggregate>Repository` 포트를 주입해도 안 걸림(HARD-STOP 2). 생성 명령이… | B14 아키텍처 규칙 |
| RR9-05-02 | High | 계층·도메인·SRP | inbound 밖 사용자 전송(bootstrap·composition controller, JWT converter)이… | B14 아키텍처 규칙 |
| RR9-05-03 | Medium | 계층·도메인·SRP | web 밖 JWT… | B14 아키텍처 규칙 |
| RR9-05-04 | Medium | 계층·도메인·SRP | `registration.interceptors(x)`에서 x가 구체 클래스 필드·생성자·new, ChannelInterceptor 지역… | B14 아키텍처 규칙 |
| RR9-05-05 | Medium | 계층·도메인·SRP | capabilityProjects에 :adapter:inbound:messaging 없음 → 전체 ArchUnit이… | B14 아키텍처 규칙 |
| RR9-05-06 | Medium | 계층·도메인·SRP | 시스템 호출 쓰기가 유스케이스 계약 밖: fileserver DefaultCleanupService.java:32,… | B15a application 구조 |
| RR9-05-07 | Medium | 계층·도메인·SRP | 연산 4개 inbound 포트, UseCase·capability·@RequiresPermission 없음, 쓰는 전송… | B15a application 구조 |
| RR9-05-08 | Medium | 계층·도메인·SRP | `FileserverMaintenanceServiceConfiguration.java:27-63`(outbound adapter가… | B15a application 구조 |
| RR9-05-09 | Medium | 계층·도메인·SRP | 전송 4곳이 "upload.bin" 기본 이름(HARD-STOP 4·중복), application… | B12 fileserver·notification HTTP |
| RR9-05-10 | Medium | 계층·도메인·SRP | web이 outbound LiveEventReplayPort 직접 읽음(application-core AGENTS 「읽기·query 경로」).… | B15a application 구조 |
| RR9-05-11 | Medium | 계층·도메인·SRP | operation id 문법 셋, owner token 64 hex(IdempotencyClaimAttempt.java:19) vs… | B15b application 작은 것 |
| RR9-05-12 | Medium | 계층·도메인·SRP | 표시·문서만), notification… | B15b application 작은 것 |
| RR9-05-13 | Low | 계층·도메인·SRP | durable operation이 core 공통 타입 안 따름: tenant·principal… | B15b application 작은 것 |
| RR9-05-14 | Low | 계층·도메인·SRP | `SubmitDurableOperationUseCase.java:177-190` UUIDv7 파생을 유스케이스가 →… | B15b application 작은 것 |
| RR9-05-15 | Low | 계층·도메인·SRP | 미사용 추상화: ReadConsistency.java:4(참조 0, persistence-jpa에 다른 모양 동명),… | B15b application 작은 것 |
| RR9-05-16 | Low | 계층·도메인·SRP | application-core README.md:780 "final이 아니다", be-domain 함정 12. | B15b application 작은 것 |
| RR9-05-17 | Low | 계층·도메인·SRP | FileMetadataPort(insert·transition·markDeleting·relocate),… | B15b application 작은 것 |
| RR9-05-18 | Low | 계층·도메인·SRP | `CanonicalNotificationPlanEncoder.java:73,78,262,264,265,282,299` 문자열에 NUL 바이트… | B15b application 작은 것 |
| RR9-05-19 | Low | 계층·도메인·SRP | `FileserverAdminController.java:151-152,164-176` orphan apply·cleanup… | B12 fileserver·notification HTTP |
같은 결함을 두 리뷰어가 적은 것은 하나로 셌다(영역 문서 「출처」에 둘 다 적음).
## 4. 묶음
원인 묶음마다 브랜치 하나·PR 하나다. 묶음의 발견 목록은 위 색인의 「묶음」 칸이다.
| 묶음 | 브랜치 | 상태 |
| --- | --- | --- |
| B1 문서·지침 | `claude/r9-docs-work` | PR #16 |
| B2 env 계약 | `claude/r9-env-keys` | PR #20 |
| B3 공개 경로·관리 포트 | `claude/r9-public-surface` | PR #23 |
| B9a inbox 트랜잭션 상한(RR9-01-01) | `claude/r9-tx-timeouts` | PR #21 |
| B14 아키텍처 규칙 | `claude/r9-arch-rules` | PR #19 |
| B18c 낡은 이름(RR9-04-38~41) | `claude/r9-stale-names` | PR #22 |
| B19 compose·Docker 운영(RR9-01-21, RR9-03-30) | `claude/r9-compose-ops` | PR #24 |
| 그룹 A 보안·관측·전송: B4, B5, B6a, B6b, B7, B11b | 그룹 세션 | 대기 |
| 그룹 B 영속성·outbound·application: B8, B9 나머지, B10a, B10b, B15a, B15b, B16 일부 | 그룹 세션 | 대기 |
| 그룹 C 계약·시험·빌드·문서: B11a, B12, B13, B16, B17, B18a, B18b, B18c 나머지(RR9-04-35·36·42) | `claude/r9-c-contracts`·`claude/r9-c-tests-build`·`claude/r9-c-docs-body` | PR #25(B11a·B12·B13), #27(B16·B17·B18a), #26(B18b·B18c 나머지, #23·#24·#25 뒤) |
| B20 objectstorage 포트 계약(RR9-03-31) | `claude/r9-objstore-contract` | 진행 중 |
그룹은 서로 파일이 겹치지 않게 나눴다. 묶음과 경로는 위 색인의 「묶음」 칸과 같다.
### 고치며 찾은 것
- RR9-03-30(Medium): 고치는 중에 찾은 발견이다. 색인과 `03-contract-testing.md`에 더했다.
- RR9-03-31(Medium)·RR9-03-32·RR9-04-43~45(Low): 그룹 C 묶음의 새 눈 리뷰가 찾은 기존 결함이다(2026-11-13). 색인과 `03-contract-testing.md`·`04-build-docs.md`에 더했다. 묶음 PR이 만든 회귀는 그 PR에서 고쳤고 여기 세지 않는다.
## 5. 다른 세션에 넘긴 것
백엔드 CI 세션(workflow·루트 `build.gradle`·`gates.md`·`verify.sh`·`scripts/ci/**`·`template-vs-consumer.md`·redis-sdk
compose README를 고치는 중)에 9건을 넘겼다(2026-11-12). 그 세션 PR이 병합되면 확인 리뷰가 본다.
1. [Medium] docs 단계(`check-work-docs.py`)가 어느 workflow에서도 돌지 않는데 문서는 「`prCheck` 안」이라 한다
(`gates.md:17`, `verify.sh:7`, `build.gradle:196-198·218-233`).
2. [Low] `verify.sh:9`의 PR job 이름(`gradle` → `done`).
3. [Low] `build.gradle:11`「JMH leaf 셋」, `:147-150`「leaf 다섯 중첩 빌드」.
4. [Low] `release.yml:31-32`「ci를 다시 돌리지 않는다」와 재실행 job들.
5. [Low] `main.yml:100` lychee 범위(`src/**/CLAUDE.md`만, `AGENTS.md` 빠짐), `gates.md:86`.
6. [Low] `gates.md:115`의 desktop 직접 실행과 `redis-topology.sh:88` `--no-daemon` 없음, `gates.md:193` digest 문장.
7. [Low] `redis-sdk/compose/README.md:94-96` 필수 클래스 수.
8. [Low] `template-vs-consumer.md:20`(object-storage-aws를 nightly로), `:39`.
9. [Low] (1과 같은 원인의 문서 쪽 `operate.md`는 B1이 고침)
10. [Low] `build-logic/AGENTS.md:17` 「저장소 루트(`ca.repository.root`)는 이 두 레인에만 준다」: 루트는 leaf `build.gradle`의 lane이 `systemProperty`로 준다(build-logic이 주지 않는다). 그룹 C 시험·빌드 PR이 graphql `graphqlDocumentContractTest`에도 준다(2026-11-13 넘김).
## 6. 결정이 필요한 것
소유자 결정이 필요한 항목은 소유자 지시(중간 승인 없이 권하는 안으로 진행)대로 권하는 안을 적용하고, PR 본문
「정한 기본값」과 여기에 남긴다. 소유자가 뒤집을 수 있다.
| # | 항목 | 권하는 안 |
| --- | --- | --- |
| ① | RR9-03-01 batch 부분 실패 응답: web AGENTS B8·http-contract(`success:false`+`BATCH_PARTIAL_FAILURE`) vs fileserver 계약(200+`results[].error`) | 공용 B8로 맞춘다. upgrade 안내 행 |
| ② | RR9-03-06 서버 포화 오류 코드가 전송마다 다르다 | 서버 포화는 공용 코드 하나(503, retryable, `Retry-After`), 호출자 빈도 초과만 429 |
| ③ | RR9-03-28 merge patch: web AGENTS B2 「쓰지 않는다」 vs patch-contract 「필드 변경은 merge patch」 | patch-contract를 정본으로, web AGENTS B2가 그쪽을 가리킨다 |
| ④ | RR9-03-22 영어 `@DisplayName`·`// when` 없는 시험의 일괄 전환 | 규칙 그대로(고치는 시험에 적용). 일괄 전환하지 않고 결정 색인에 적는다 |
| ⑤ | RR9-05-12 notification 멱등 판정이 executor와 다르다 | 근거를 보고 executor로 옮기거나 결정으로 기록 — 묶음이 고른다 |
| ⑥ | env 이름 `SECURITY_PUBLIC_PATHS`·`PRESENTATION_API_BASE_PATH`의 `APP_` 접두 | 지금 이름 그대로 registry에 등록(바꾸면 파생 서비스 배포 env가 소리 없이 무시됨). 이름 변경은 소유자 결정 |
| ⑦ | RR9-03-32 provider callback의 본문 없는 응답: 소유자 결정 12 「Envelope가 아닌 실패는 Draft-12 offset 문서 하나」 | 동작 그대로(provider는 status만 읽고, 인증 전 경로라 거절 이유를 싣지 않음), HTTP 계약 §1에 예외로 적는다 |
## 7. 멈춤 기준 상태 (`docs/work/improve.md` 4.5절)
1. 마지막 확인 리뷰 발견 0: 아님. 이 라운드 158건을 고친 뒤 확인 리뷰(독립 리뷰어 둘)가 판정한다.
2. 열린 「Declined to judge」 0: 참. 판정을 미룬 항목은 없다. 못 본 경로는 2절에 적었다.
3. 합친 트리의 라운드 끝 게이트: 아직. 묶음을 합친 뒤 돈다.
4. README의 남은 항목 0: 아님. 4절의 대기 묶음과 6절의 결정이 남았다.
+4 -3
View File
@@ -42,8 +42,9 @@ verifyMessagingTargetBindingPreflight
1. 각 시나리오를 실제로 실행하는 Test 태스크.
2. 그 실행 결과(JUnit XML)에서 payload-free manifest를 만드는 producer.
3. `src/adapter/outbound/messaging/release/evidence/build-evidence-manifest-v1.schema.json`으로 그 manifest 바이트를
검증하는 단계(build-tools `VerifyMessagingEvidenceTask`가 쓰고 바로 검증한다).
검증하는 단계. manifest를 쓰는 태스크가 쓰자마자 검증한다.
4. 위 셋이 모두 생긴 다음에 `verifyMessaging<Scenario>R2` 태스크 등록.
build-tools `MessagingQualificationPlugin`의 `verifyMessagingContracts`가 그 네 단계를 모두 갖춘
예시다.
> 이력: 네 단계를 모두 갖춘 예시였던 build-tools `MessagingQualificationPlugin`과 `VerifyMessagingEvidenceTask`는
> 2026-09-25 capability 포장(`6d27356e`)에서 지웠다. 루트 `verifyMessagingContracts`는 남아 있고, 지금은
> application·shared 계약 lane 둘을 묶기만 한다(루트 `build.gradle`).
+1 -1
View File
@@ -36,7 +36,7 @@ status: 초안
- log query: `{service="app"} | http.status>=500 | stats count by error.code`
- metric panel: `jvm_memory_used_bytes{area="heap"}`, `jvm_gc_pause_seconds`, `process_cpu_seconds_total`, `http_server_requests_seconds_count{status=~"5.."}`
- trace: 실패 request의 `traceId`로 span chain 확인 → stack trace에서 root exception 추출
- heap dump 위치: `/var/tmp/heap/heapdump-<pid>.hprof` (JVM ergonomics: `-XX:MaxRAMPercentage=75 -XX:+HeapDumpOnOutOfMemoryError`)
- heap dump 위치: `/var/tmp/heap/java_pid<pid>.hprof`(`-XX:HeapDumpPath=/var/tmp/heap`). 그 경로에 디스크 볼륨을 붙인 배포에만 남는다. 읽는 법은 `docs/runbooks/runtime-jvm-oom.md` 「진단」
- 가능한 원인:
- 직전 deploy의 회귀 버그 → rollback
- JVM OOM (메모리 leak 또는 부하 증가) → heap dump 분석
+8 -1
View File
@@ -22,7 +22,14 @@ status: 초안
## 진단
- 힙 덤프를 본다. 이미지의 `JAVA_TOOL_OPTIONS`가 `-XX:+HeapDumpOnOutOfMemoryError`와
`-XX:HeapDumpPath=/var/tmp/heap`을 켠다(`Dockerfile`).
`-XX:HeapDumpPath=/var/tmp/heap`을 켠다(`Dockerfile`). 파일은 `/var/tmp/heap/java_pid<pid>.hprof`다.
- 덤프는 그 경로에 디스크 볼륨을 붙였을 때만 남는다.
- Kubernetes: `medium: Memory`가 없는 emptyDir나 PersistentVolume. emptyDir는 컨테이너가 다시 떠도 남는다.
`kubectl cp <pod>:/var/tmp/heap/java_pid1.hprof .`로 꺼낸다.
- compose dev lane: named volume `heap-dumps`. `docker compose cp app:/var/tmp/heap/<파일> .`로 꺼낸다.
- 기본 `compose.yaml`: 그 경로에 아무것도 붙이지 않는다. 루트가 읽기 전용이라 JVM이 파일을 못 만들고 바로
코드 3으로 끝난다. tmpfs는 쓰지 않는다. 컨테이너 메모리 한계에 함께 잡혀 덤프 중 OOM kill(코드 137)이 나고,
컨테이너가 끝나면 함께 사라진다.
- 죽기 전 메모리 사용 추세를 본다.
- 메모리 누수를 찾는다: 커지기만 하는 캐시, 상한 없는 목록, 쌓이는 세션.
+46
View File
@@ -0,0 +1,46 @@
---
title: Runbook — 서버 포화(SERVER_BUSY)
category: TRANSIENT_DEPENDENCY
error_codes: [SERVER_BUSY]
severity: P2
owner: oncall
last_updated: 2026-11-13
status: 운영
---
# Runbook: 서버 포화 (`runbook://server/busy`)
이 instance가 요청을 더 받을 자리가 없어 바로 거절했다. 호출자의 빈도 초과(`RATE_LIMIT_EXCEEDED` 429)와 다르다. 이
코드는 서버 쪽 상한이 찼다는 뜻이다.
## 증상
- HTTP `503`과 `error.code = SERVER_BUSY`, `Retry-After: 1`. gRPC는 `UNAVAILABLE`와 trailer `error-code: SERVER_BUSY`.
- `http_server_requests_seconds_count{status="503"}`이 오르고, 같은 때 p95 지연은 오르지 않는다. 거절은 일을 하기 전에
나기 때문이다.
- 이 코드를 내는 곳은 셋이다.
| 내는 곳 | 찬 상한 | 설정 |
| --- | --- | --- |
| web-advanced `VirtualThreadAdmissionFilter` | 동시에 처리하는 요청 수 | `app.web.advanced.mvc-virtual-threads.admission-limit` |
| fileserver 전송 허가 | instance 전체 업로드·직접 다운로드 permit, 전송 worker pool | `app.fileserver-platform.quota.instance-upload-permits`, `…direct-download-permits` |
| gRPC `GrpcCallAdmission` | feature 호출 worker와 대기열 | `app.grpc.server.executor-max-pool-size`, `executor-queue-capacity` |
## 진단
1. 거절이 한 instance에만 몰리는지 본다. 한 instance만이면 부하 분산이 고르지 않거나 그 instance의 하류가 느리다.
2. 같은 때 하류 지연(DB pool 대기, 외부 HTTP 지연)을 본다. 하류가 느리면 허가를 쥔 요청이 오래 머물러 상한이 찬다.
이때 상한을 올리면 하류 pool 앞의 줄만 길어진다.
3. 정상 부하에서 상한 자체가 작은지 본다. 거절률이 트래픽에 비례하고 하류가 건강하면 상한이 작다.
## 조치
- 하류가 느린 경우: 하류 runbook(`db-unavailable`, `dependency-timeout`)을 먼저 따른다. 상한은 그대로 둔다.
- 상한이 작은 경우: instance를 늘리거나 위 표의 설정을 올린다. virtual thread `admission-limit`은 DB pool과 외부
bulkhead를 넘지 않게 둔다(`docs/web/virtual-thread-profile.md`).
- client는 `Retry-After` 뒤에 같은 요청을 다시 보낸다. 고칠 것이 없으면 거절은 1초 안에 풀린다.
## 에스컬레이션
- 5분 넘게 거절률이 전체 요청의 5%를 넘으면 P1으로 올리고 인프라 당번을 부른다.
- 모든 instance가 같이 거절하고 하류가 건강하면 용량 문제다. 배포 소유자에게 scale-out을 요청한다.
+9
View File
@@ -4,3 +4,12 @@
# overrides it at run time and is outside this snapshot.
# Update only after review with: ./gradlew verifyPublicPathSnapshot -PapprovePublicPathChange
/v1/healthcheck
# Profile overrides of app.security.public-paths
profile local: /api/healthcheck
# Filter-chain statements that permit requests without authentication
src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/callback/CallbackMvcSecurityConfiguration.java: .authorizeHttpRequests(requests -> requests.anyRequest().permitAll())
src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/callback/CallbackMvcSecurityConfiguration.java: return http.securityMatcher("/internal/notification/callbacks/**")
src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/SecurityConfig.java: auth.dispatcherTypeMatchers(DispatcherType.ERROR).permitAll();
src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/SecurityConfig.java: auth.requestMatchers(publicPaths).permitAll();
src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/management/security/ManagementSecurityConfig.java: .requestMatchers(EndpointRequest.to("health", "info", "prometheus")) .permitAll()
src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/management/security/ManagementSecurityConfig.java: http.securityMatcher(EndpointRequest.toAnyEndpoint())
+8 -9
View File
@@ -141,15 +141,14 @@ fixture는 **지원 코드**다. TEST/INTEGRATION/SYSTEM/ARCHITECTURE/PERFORMANC
### repository
- `integrationCheck`: production leaf들의 INTEGRATION lanes.
- `systemTestCheck`: production leaf들의 SYSTEM lanes.
- `architectureCheck`: repository architecture rules + ARCHITECTURE lanes.
- `qualificationCheck`: SYSTEM composition + auxiliary-source style gate.
- `ci`: leaf checks + architecture/quality/config contract + qualification.
- `releaseCheck`: `ci` + release-only provenance/archive/public-path checks.
category별 묶음 태스크: `integrationCheck`(모든 leaf의 INTEGRATION lane), `performanceCheck`(PERFORMANCE lane),
`systemTestCheck`(SYSTEM lane. app-bootstrap은 `check`가 이미 돌려 뺀다), `architectureCheck`(저장소 아키텍처 규칙과
ARCHITECTURE lane). 이것들을 어느 단계(`prCheck`·`mainCheck`·`releaseCheck` 등)가 부르는지와 단계마다 무엇이 더 붙는지의 정본은
`docs/work/reference/gates.md` 1절과 루트 `build.gradle`의 단계 태스크다. 여기에 복사하지 않는다.
`integrationCheck`는 현재 `ci`에 암묵적으로 포함되지 않는다.
여러 integration lane이 container runtime을 요구하므로 별도 workflow/main/nightly에서 실행할 수 있다.
- `integrationCheck`는 `ci`에 들지 않는다. container runtime이 드는 lane이 많아 main 단계(`main.yml` `main` job)가
따로 부른다.
- `systemTestCheck`는 `qualificationCheck`를 거쳐 main 단계에서 돈다.
PERFORMANCE는 기본 로컬 `check`에 붙이지 않는다. 명시적 benchmark/performance task나
scheduled workflow가 실행한다.
@@ -289,7 +288,7 @@ source set에서 태그 `jpa-contract`로 `jpaPlatformContractTest` lane이 돌
케이스 3건이 실패함을 확인했다.
- `OutboxAggregateSequenceContract`는 포트 Javadoc의 세 약속 중 둘을 보지 않았다(RR-01-06). "쓰기
트랜잭션 밖 거부"와 "롤백된 번호는 다시 준다"를 넣었다. fake는 `DirectTransactionPort`를 받으면 같은
규칙으로 동작한다(인자 없이 만들면 예전처럼 트랜잭션을 보지 않는다 — sample 테스트가 쓰는 방식).
규칙으로 동작한다(인자 없이 만들면 예전처럼 트랜잭션을 보지 않는다).
`CacheRegionContract`에는 2^53 위 revision 한 자리 차이 경우를 넣었다. fake가 revision을 double로
비교하게 바꾼 변이가 이제 실패한다(전에는 통과).
+25
View File
@@ -0,0 +1,25 @@
# 업그레이드 안내 — 2026-11 시험 classpath·이미지 카탈로그·빌드 정리
- 범위: `ca.spring-library` 규약의 시험 의존, 컨테이너 이미지 카탈로그, version catalog, API surface 플러그인,
graphql의 registry 대조 시험 위치. 운영 코드와 HTTP 응답은 그대로다. 빌드와 시험만 바뀐다.
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 빌드·시험 발견
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 자기 leaf를 더한 서비스가 특히 본다.
## 2. 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
| --- | --- | --- | --- |
| 1 | 자기 leaf 시험이 쓰는 web 시험 도구를 그 leaf `build.gradle`에 직접 선언한다. MockMvc(`@WebMvcTest`, `@AutoConfigureMockMvc`)는 `testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'`, `TestRestTemplate`만이면 `spring-boot-resttestclient`, `WebApplicationContextRunner`는 `spring-web`, 시험이 `tools.jackson.databind`로 JSON을 읽으면 `tools.jackson.core:jackson-databind`다. 그다음 `./gradlew resolveAndLockAll --write-locks`로 lockfile을 다시 만든다 | 시험 컴파일이 실패한다(`cannot find symbol`, `class file for ... not found`). 운영 코드는 영향이 없다 | `ca.spring-library`를 쓰는 자기 leaf가 있는 서비스 |
| 2 | `gradle/container-images.properties`에 더한 이미지를 `이름@sha256:<digest>`로 고정한다 | 설정 단계에서 `GradleException`으로 빌드가 멈춘다 | 카탈로그에 이미지를 더한 서비스 |
| 3 | 시험이 `ca.test.image.postgres-16-4`를 읽었다면 `ca.test.image.postgres-16`으로 바꾼다. 그 칸은 지웠다 | 속성이 비어 Testcontainers가 이미지를 못 찾는다 | 그 칸을 쓰던 서비스 |
| 4 | version catalog에서 지운 칸을 쓰던 빌드 스크립트는 자기 칸을 둔다. 지운 라이브러리 칸: `errorprone-core`, `findsecbugs-plugin`, `jackson3-core`, `jmh-core`, `jmh-generator-annprocess`, `junit-platform-launcher`, `protobuf-java-legacy`, `spock-core-groovy4`, `spock-core-groovy5`. 지운 플러그인 칸: `spring-dependency-management`, `spotless`, `spotbugs`, `errorprone`(규약 플러그인이 쓰는 버전은 그대로다) | 빌드 스크립트 컴파일이 실패한다 | 그 alias를 쓰던 서비스 |
| 5 | `apiSurface`의 추가 source root가 실제로 있는 폴더를 가리키는지 본다. 상대 경로 대신 `project(':x').file('src/main/java').path`를 쓴다 | 설정 단계에서 실패한다. 전에는 말없이 건너뛰어 줄어든 표면을 승인할 수 있었다 | API surface에 추가 root를 둔 leaf |
| 6 | graphql의 `GraphQlDeploymentModeRegistryParityTest`는 `test`가 아니라 main 단계 lane `:adapter:inbound:graphql:graphqlDocumentContractTest`에서 돈다. 손으로 돌릴 때 그 lane을 부른다 | `test`만 돌리면 registry 대조를 보지 않는다 | graphql을 실은 서비스 |
## 3. 확인
- `./gradlew resolveAndLockAll --write-locks` 뒤 `git diff --stat -- '*gradle.lockfile'`로 시험 classpath에서 빠진 항목을 본다.
- `./gradlew <자기 leaf>:check`가 시험 컴파일부터 통과하는지 본다.
+32
View File
@@ -0,0 +1,32 @@
# 업그레이드 안내 — 2026-11 HTTP 계약·오류 코드 정리
- 범위: web-advanced(patch·stream·virtual thread), fileserver·notification HTTP, 전송 오류 코드를 약속한 계약에 맞춘
변경. 응답 코드·모양이 바뀐 곳이 있다. 아래 표가 그 목록이다.
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 계약·오류 코드 발견
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스와, 그 서비스의 HTTP 응답을 읽는 client 팀이 읽는다.
## 2. 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
| --- | --- | --- | --- |
| 1 | `JsonMergePatchApplier`·`JsonPatchApplier`를 만드는 코드에 셋째 인자로 Boot의 `jakarta.validation.Validator` bean을 넘긴다 | 컴파일이 실패한다 | web-advanced patch를 쓰는 서비스 |
| 2 | patch 거부를 읽는 client는 `PATCH_REJECTED`(400) 하나로 본다. 전에는 JSON이 아닌 본문이 `500 INTERNAL_ERROR`, 빈 문서·연산 모양 오류·merge 깊이 초과가 `400 BAD_PARAMETER`, 너무 깊은 pointer가 `403 PATCH_PATH_FORBIDDEN`이었다 | client가 옛 코드로 분기하던 곳이 다른 코드를 받는다 | patch route를 둔 서비스와 그 client |
| 3 | patch 결과가 Bean Validation 제약을 어기면 `400 VALIDATION_FAILED`와 필드별 `details`가 나간다. patch 대상 타입의 제약을 확인한다 | 전에는 제약을 어긴 객체가 그대로 저장 경로로 갔다 | web-advanced patch를 쓰는 서비스 |
| 4 | 스트림 `Failure` 기록의 `code`가 실패의 코드(예: `STREAM_ITEM_TOO_LARGE`) 또는 `INTERNAL_ERROR`다. `DEPENDENCY_FAILURE`로 분기하던 client를 고친다 | 그 분기가 다시는 맞지 않는다 | NDJSON·JSON-seq stream을 읽는 client |
| 5 | virtual thread profile을 켠 배포는 이제 실제로 허가 상한을 건다. `admission-limit`이 부하에 맞는지 본다 | 전에는 상한이 없어 모든 요청이 들어왔다. 이제 넘치면 `503 SERVER_BUSY`와 `Retry-After: 1`이다 | `app.web.advanced.mvc-virtual-threads.enabled=true`인 배포 |
| 6 | fileserver batch(`POST /v1/files:batch`)를 읽는 client는 `success`로 가른다. 모두 성공하면 `success: true`와 최상위 `results[]`, 하나라도 실패하면 `success: false`, `error.code = BATCH_PARTIAL_FAILURE`, part별 `error.details[]`(`index`, `status`, `id`, `code`, `message`)다. 부분 실패에서는 part를 요청 순서 `index`로 짚는다(`clientPartId`는 전부 성공한 `results[]`에만 있다) | 전에는 실패가 있어도 `success: true`이고 결과가 `data.results[]`에 있었다. 옛 경로로 읽던 client는 결과를 못 찾는다 | fileserver를 쓰는 서비스와 그 client |
| 7 | `BulkItemResult.error(index, code, message)`를 부르던 코드를 `BulkItemResult.error(index, ApiErrorCode)`로 바꾼다. 문구는 code의 category 고정 문구가 된다 | 컴파일이 실패한다 | bulk endpoint를 둔 서비스 |
| 8 | 서버 포화 거절을 읽는 client는 `SERVER_BUSY`(503, retryable, `Retry-After: 1`)로 본다. web-advanced `ADMISSION_REFUSED`, fileserver instance·전송 pool 포화의 `TRANSFER_ADMISSION_REJECTED`(429), gRPC 포화의 `RESOURCE_EXHAUSTED`/`RATE_LIMIT_EXCEEDED`가 이 코드로 바뀌었다(gRPC status는 `UNAVAILABLE`). 호출자 자신의 동시 전송 초과만 `TRANSFER_ADMISSION_REJECTED` 429로 남는다 | 옛 코드로 분기하던 재시도 로직이 맞지 않는다. 자바에서 `WebAdvancedError.ADMISSION_REFUSED`를 참조하던 코드는 컴파일이 실패한다 | 세 전송의 client, web-advanced 코드를 참조하던 서비스 |
| 9 | 컨테이너가 넘긴 503(필터의 `sendError(503)` 등)은 `SERVER_BUSY`다. 비동기 요청 시간 초과만 `REQUEST_TIMEOUT`이다 | 전에는 모든 503이 `REQUEST_TIMEOUT`이었다 | web을 쓰는 모든 서비스의 client |
| 10 | 알림 template 게시 경로를 `/notification-templates`에서 `/notificationTemplates`로 바꾼다(prefix 뒤) | 옛 경로는 404다 | 알림 template을 게시하는 client와 배포 스크립트 |
| 11 | 알림 제출·template 게시의 모르는 `channel`·`slot`·`locale`·`fallbackLocale`은 `400 VALIDATION_FAILED`와 그 필드를 짚는 `details`다(전에는 details 없는 `BAD_PARAMETER`) | `BAD_PARAMETER`로 분기하던 client가 다른 코드를 받는다 | 알림 HTTP client |
| 12 | 이름 없이 올린 파일의 표시 이름이 `upload.bin`에서 `file`이 된다(모든 전송에서 같다) | 표시 이름이 바뀐다. 동작은 같다 | fileserver를 쓰는 서비스 |
| 13 | fileserver `ATOMIC_PUBLISH_UNSUPPORTED`(재시도 불가 code)는 더 이상 `Retry-After`를 싣지 않는다. 본문 `retryable=false`와 맞춘 것이다 | 그 헤더로 재시도하던 client가 재시도하지 않는다(원래 재시도해도 소용없는 실패다) | fileserver client |
| 14 | 브라우저 client는 `Content-Range`를 읽을 수 있다(CORS 노출 목록에 더함) | — 더하기만 한 변경 | fileserver 다운로드를 이어 받는 브라우저 client |
| 15 | bulk 부분 실패의 `error.message`가 영어 문구에서 category 고정 문구(`ClientErrorMessages`)로 바뀌었다. 항목(`details[]`)은 자기 상태에 맞는 키만 싣는다(성공 항목에 `code`·`message` 키 없음, 실패 항목에 `id` 키 없음) | 문구로 분기하던 client(원래 하면 안 된다)나 null 키를 기대하던 strict client가 다르게 본다 | bulk endpoint를 둔 서비스의 client |
| 16 | 스트림에서 위치가 앞 항목보다 크지 않은 항목은 이제 나가지 않고, 스트림이 `INTERNAL_ERROR` `Failure` 기록으로 끝난다(전에는 그 항목을 쓴 뒤 끝났다) | 서버 결함이 있는 source의 client가 마지막 항목을 받지 않는다 | NDJSON·JSON-seq stream을 읽는 client |
| 17 | 상태만 아는 503·429(Spring이 던진 `ResponseStatusException` 등)도 registry의 `Retry-After`를 싣는다 | — 헤더를 더하기만 한 변경 | web을 쓰는 서비스의 client |
| 18 | virtual thread admission filter가 Spring Security chain 뒤에서 돈다. 인증·권한에서 거절된 요청은 허가를 쓰지 않고, 거절 503에 CORS 헤더가 붙는다 | — | virtual thread profile을 켠 배포 |
+45
View File
@@ -0,0 +1,45 @@
# 업그레이드 안내 — 2026-11 env 키 계약 정리
- 범위: `docs/registries/env-keys.yaml`·`.env.example`·`verifyEnvKeys`를 배포 설정의 실제 동작에 맞춘 변경. 앱이 읽는 키와
그 기본값은 바뀌지 않았다. 바뀐 것은 예시 파일의 값, registry 행, 그리고 검사가 실패로 보는 범위다.
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 env 계약 발견
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 예전 `.env.example`을 복사해 `.env`나
배포 env를 만든 서비스, 자기 배포 설정에 placeholder를 더한 서비스다.
## 2. 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
| --- | --- | --- | --- |
| 1 | 옛 `.env.example`에서 복사한 `APP_DATASOURCE_CONNECTION_TIMEOUT=5s`를 `5000`(밀리초)으로 바꾼다 | JPA를 켠 배포가 Hikari 바인딩 실패로 기동하지 않는다 | persistence-jpa 선택 |
| 2 | 옛 예시의 `APP_SECURITY_CORS_MAX_AGE=600s`를 `600`(초)으로 바꾼다 | dev·prod 기동이 `app.cors.max-age-seconds` 바인딩 실패로 멈춘다(local은 profile 리터럴이 덮어 안 보인다) | 예시를 복사한 서비스 |
| 3 | 옛 예시에서 복사한 값 다섯을 확인한다: `APP_CACHE_REDIS_COMMAND_TIMEOUT=2s`, `APP_RATE_LIMIT_REDIS_COMMAND_TIMEOUT=1s`, `APP_LOG_LEVEL_SQL=WARN`, `APP_SERVER_FORWARD_HEADERS_STRATEGY=native`, `APP_CACHE_REDIS_POSITIVE_SOFT_TTL=`(빈 값). 새 예시는 기본값(`200ms`, `200ms`, `INFO`, `none`, `30s`)을 쓴다 | 그 값들이 env가 없을 때와 다르게 동작한다. 특히 `native`는 프록시를 거치지 않는 배포에서 호출자가 보낸 forwarded 헤더를 믿는다 | 예시를 복사한 서비스 |
| 4 | `.env`·배포 env에 남은 `deprecated_orphaned` 키(예: `APP_CACHE_REDIS_TTL_JITTER`, `APP_SESSION_IDLE_TIMEOUT`, `APP_CACHE_REDIS_L1_*`)를 지운다. 무엇이 대신하는지는 registry 행 주석에 있다 | 아무 일도 하지 않는 값을 켠 것으로 믿는다 | 예시를 복사한 서비스 |
| 5 | 서비스가 배포 설정(profile 파일 밖의 `application.yml`, `config/*.yml`, 모듈 `config/module-defaults/*.yml`)에 더한 placeholder는 접두어와 상관없이 registry에 행을 더하고, 행의 `default`를 placeholder 기본값과 같게 둔다 | `:app-bootstrap:verifyEnvKeys`(`mainCheck` 안)가 실패한다 | 자기 placeholder를 더한 서비스 |
| 6 | `.env.example`의 값을 registry `default`(또는 행의 `example`)와 같게 둔다. 기본값이 있는 키를 빈 줄로 두지 않는다 | 같은 검사가 실패한다 | 자기 키를 예시에 더한 서비스 |
## 3. 다시 살린 registry 행
아래 셋은 2026-08-10 폐기로 적혀 있었지만, 2026-09-25 capability 포장 뒤로 cache-redis 모듈 설정이 다시 읽는다.
`deprecated_orphaned`를 지우고 기본값을 모듈 설정에 맞췄다.
| 키 | 읽는 곳 | 기본값 |
| --- | --- | --- |
| `APP_CACHE_REDIS_COMMAND_TIMEOUT` | `app.capabilities.cache.command-timeout` | `200ms`(registry가 `2s`라고 적었다) |
| `APP_CACHE_REDIS_SEMANTIC_REGION` | `app.capabilities.cache.semantic-region` | `default` |
| `APP_CACHE_REDIS_KEY_HMAC_SECRET` | `secret://environment/APP_CACHE_REDIS_KEY_HMAC_SECRET` 참조 | 없음(비밀) |
## 4. 새로 등록한 이름
배포 설정이 읽는데 registry에 없던 이름이다. 이름은 그대로이고 동작도 같다.
- `SECURITY_PUBLIC_PATHS`, `PRESENTATION_API_BASE_PATH` — APP_ 통일 전에 퍼진 이름이다. 바꾸면 파생 서비스의 배포 env가
소리 없이 무시되어 그대로 둔다.
- `SPRING_BANNER_MODE`, `SPRING_JACKSON_DESER_*` 넷, `SPRING_JACKSON_SER_WRITE_DATES_AS_TIMESTAMPS`,
`SPRING_MAIN_LAZY_INITIALIZATION`, `SPRING_MAIN_LOG_STARTUP_INFO`, `SPRING_THREADS_VIRTUAL_ENABLED` — `application.yml`
placeholder 이름이다. Spring relaxed 이름도 같은 속성을 덮고, 둘 다 있으면 relaxed 이름이 이긴다.
- `APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL` — gRPC 모듈을 켠 배포가 기동하려면 `true`로 명시하는 값이다.
- `.env.example`에 `MANAGEMENT_SERVER_ADDRESS=127.0.0.1`을 더했다. Kubernetes 프로브와 Prometheus는 pod IP로 붙으므로
원격에서 읽으려면 이 값을 바꾼다.
@@ -0,0 +1,28 @@
# 업그레이드 안내 — 2026-11 공개 경로 스냅숏과 관리 포트
- 범위: 공개 경로 스냅숏(`docs/security/public-paths-snapshot.txt`)이 보는 범위를 넓힌 변경과, compose가 관리 포트·JMX를
publish하던 줄을 지운 변경. 앱이 여는 경로와 기본 설정은 바뀌지 않았다.
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 공개 경로·관리 포트 발견
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 자기 모듈에 Spring Security filter
chain을 둔 서비스, profile 파일에서 `app.security.public-paths`를 덮은 서비스, Kubernetes에 배포하는 서비스, dev
compose lane으로 JVM을 원격 JMX로 보던 사람이다.
## 2. 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
| --- | --- | --- | --- |
| 1 | merge 뒤 `./gradlew verifyPublicPathSnapshot`을 돌린다. 실패하면 스냅숏에 새로 든 두 절(profile이 덮는 값, filter chain의 `permitAll`·`securityMatcher` 문장)을 읽고, 의도한 공개면 `./gradlew verifyPublicPathSnapshot -PapprovePublicPathChange`로 다시 쓴 파일을 보안 리뷰와 함께 커밋한다 | `mainCheck`·`releaseCheck`의 `:app-bootstrap:publicPathSnapshotTest`가 실패한다 | 자기 chain이나 profile 덮어쓰기가 있는 서비스 |
| 2 | Kubernetes 배포는 `MANAGEMENT_SERVER_ADDRESS`를 pod IP에서 닿는 주소(예: `0.0.0.0`과 NetworkPolicy)로 두거나 같은 pod의 sidecar로 읽는다. 기본값 `127.0.0.1`은 2026-11-12 main 병합(관리 포트 loopback 고정)부터다 | kubelet 프로브가 관리 포트에 닿지 않아 liveness 실패로 재시작하고 readiness가 오지 않는다. Prometheus도 못 읽는다 | Kubernetes 배포 |
| 3 | compose에서 관리 포트를 호스트로 읽던 명령(`curl localhost:9001/...`)을 `docker compose exec app wget -qO- http://localhost:9001/actuator/health`로 바꾼다 | 호스트 포트가 없어 연결이 거절된다. 지운 publish 줄도 컨테이너 loopback에 닿지 않아 원래 아무것도 답하지 않았다 | compose로 띄우는 사람 |
| 4 | dev lane에서 원격 JMX(9999) 대신 `docker compose exec app jcmd 1 <명령>`(`VM.flags`, `Thread.print`, `JFR.start`)을 쓴다 | 9999 연결이 거절된다 | dev lane으로 JVM을 보던 사람 |
## 3. 바뀐 것
- 스냅숏은 세 절이다: 기본 공개 경로(`config/security.yml`), profile이 덮는 값(`application-<profile>.yml`), 모든 leaf
운영 코드의 `permitAll`·`securityMatcher` 문장. 알림 callback chain과 actuator chain이 셋째 절에 든다.
- 스냅숏이 못 보는 것은 운영자가 배포 env(`SECURITY_PUBLIC_PATHS`)로 준 값과, matcher를 상수나 변수로 다른 줄에서
만든 경우의 그 값이다. 그런 변경은 리뷰가 본다(`docs/build.md` 「`verifyPublicPathSnapshot`」).
- dev lane의 원격 JMX는 인증·TLS 없이 열려 있었고 `jmxremote.host`가 없어 모든 인터페이스에 묶였다. 그래서 지웠다.
+1 -1
View File
@@ -10,7 +10,7 @@ Advanced capability는 따로 된 leaf `adapter:inbound:web-advanced`(`src/adapt
| Capability | 켜는 법 | 더하는 것 | 테스트 |
| --- | --- | --- | --- |
| MVC virtual thread | `app.web.advanced.mvc-virtual-threads.enabled=true`(+ 허가 상한과 예산) | **모든** 요청에 대한 다른 스케줄링 모델 | `MvcAdvancedConfigurationTest`, `VirtualThreadAdmissionTest` |
| MVC virtual thread | `app.web.advanced.mvc-virtual-threads.enabled=true`(+ 허가 상한과 예산) | **모든** 요청에 대한 다른 스케줄링 모델과 요청마다 거는 허가 상한(`VirtualThreadAdmissionFilter`) | `MvcAdvancedConfigurationTest`, `VirtualThreadAdmissionTest`, `VirtualThreadAdmissionFilterTest` |
| NDJSON 스트리밍 | `app.web.advanced.ndjson.enabled=true` | 오래 사는 connection | `MvcStreamingWiringTest`, `WebStreamCoreTest`, `WebStreamDrainTest`, `WebStreamingSoakIT` |
| JSON text sequence(RFC 7464) | `app.web.advanced.json-sequence.enabled=true` | 오래 사는 connection | NDJSON과 같다 |
| JSON Merge Patch(RFC 7396) | 라이브러리 — `JsonMergePatchApplier` | 부분 문서 | `JsonMergePatchApplierTest` |
+10 -3
View File
@@ -70,6 +70,10 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
4xx·5xx status로 나가는 본문은 `success:true`로 감싸지 않는다. 실패 Envelope가 아닌 본문을 오류 status로
돌려주는 핸들러는 그 본문이 그대로 나간다.
Envelope가 아닌 응답은 두 곳뿐이다. fileserver의 프로토콜 예외(`docs/fileserver/http-contract.md` 「Envelope 규칙의
프로토콜 예외」)와 알림 provider callback이다. callback은 provider가 status만 읽는 webhook 응답이라 본문 없이
204·400·413·503만 답한다(`src/adapter/inbound/web-notification/AGENTS.md`).
### 왜 이렇게 나가는가
`Envelope`·`BulkEnvelope`·`ApiError`·`ResponseMeta`는 `shared-contract`에 있고, 이 leaf는 Java
@@ -177,7 +181,7 @@ CORS가 켜져 있으면(`app.cors.enabled=true`) cross-origin 실제 응답의
`traceparent`, `Location`, `ETag`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- fileserver를 실은 배포: `Tus-Resumable`, `Tus-Version`, `Tus-Extension`, `Tus-Max-Size`,
`Upload-Offset`, `Upload-Length`, `Upload-Defer-Length`, `Upload-Expires`, `Upload-Complete`,
`Upload-Limit`, `Content-Disposition`, `Accept-Ranges`
`Upload-Limit`, `Content-Disposition`, `Accept-Ranges`, `Content-Range`
새 응답 헤더를 쓰는 모듈은 `CorsExposedHeaders` bean으로 자기 헤더를 기여한다.
@@ -187,15 +191,18 @@ CORS가 켜져 있으면(`app.cors.enabled=true`) cross-origin 실제 응답의
| 코드 | status | category | `retryable` | `Retry-After` | 언제 |
| --- | --- | --- | --- | --- | --- |
| `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. GraphQL도 같은 이름을 쓰지만 그쪽 `category`는 GraphQL 전용 어휘 `TIMEOUT`이다(`src/adapter/inbound/graphql/README.md`) |
| `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. 그 밖의 503(필터의 `sendError(503)` 등)은 공용 `SERVER_BUSY`다. GraphQL도 같은 이름을 쓰지만 그쪽 `category`는 GraphQL 전용 어휘 `TIMEOUT`이다(`src/adapter/inbound/graphql/README.md`) |
| `IDEMPOTENCY_KEY_INVALID` | 400 | `VALIDATION` | `false` | 없음 | 2절 |
| `RATE_LIMIT_UNAVAILABLE` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 있음 | rate-limit 저장소 응답 없음(`docs/web/runbook.md`) |
| `RATE_LIMIT_INCOMPATIBLE` | 503 | `INTERNAL` | `false` | 없음 | rate-limit 제공자가 계약과 맞지 않음 |
| `OPERATION_NOT_FOUND` | 404 | `NOT_FOUND` | `false` | 없음 | durable operation 조회(`DurableOperationController`)에서 그 operation이 없거나 다른 호출자의 것이다. 둘을 가르지 않는다 |
- 컨트롤러 파라미터 제약 위반(`@RequestParam @Max(10)`)은 요청 본문 위반과 같은
`400 VALIDATION_FAILED`이고 `details`는 `[{field, code, message}]`다. 거절된 값은 싣지 않는다.
- web-advanced를 실은 서비스의 예외 코드(`ADMISSION_REFUSED` 503 등 10종)는
- web-advanced를 실은 서비스의 예외 코드(`PATCH_REJECTED` 400 등)는
`src/adapter/inbound/web-advanced/README.md` 「오류 응답」이 정본이다.
- 서버 포화(허가 상한, 꽉 찬 work pool)는 모든 전송이 공용 `SERVER_BUSY`(503, retryable, `Retry-After: 1`)
하나로 답한다. 호출자 자신의 빈도 초과만 `RATE_LIMIT_EXCEEDED` 429다(`docs/registries/error-codes.yaml`).
- 직접 쓰는 거부 응답(401·403·429·503)도 컨트롤러 응답과 같이 `application/json;charset=UTF-8`이다.
## 5. 바꿀 때
+7 -5
View File
@@ -7,12 +7,14 @@
API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client generator가 다 이해하지 못하는 버전의 문서는 실패하지
않는다. 컴파일되는데 틀린 client를 만든다. 문서가 아예 없는 것보다 나쁘다.
그래서 3.1.2가 릴리스 산출물로 남고, 3.2는 그 옆에서 만든다.
그래서 3.2는 3.1 문서를 바꾸지 않고 그 옆에서 만든다. 이 템플릿 자체는 OpenAPI 문서를 릴리스 산출물로 내지
않는다(만들던 샘플을 2026-09-25에 지웠다). 아래는 3.1 문서를 내는 서비스가 3.2를 함께 만들 때의 규칙이다.
## 불변식
**3.2를 만드는 것이 3.1 snapshot을 바꾸면 안 된다.** 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에 모델을
바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만.
**3.2를 만드는 것이 그 서비스의 3.1 문서를 바꾸면 안 된다.** 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에
모델을 바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만. 서비스는 자기 3.1 문서를
snapshot으로 두고 3.2를 만들 때 그것이 그대로인지 본다.
이 저장소에는 그것을 검사하는 것이 더는 없다. snapshot을 hash하고 어떤 parser, linter, generator, client 컴파일이
3.2 출력을 읽었는지 기록하던 승격 보고서 `OpenApi32CompatibilityReport`와 `OpenApiToolchainMatrix`는 2026-09-25에
@@ -23,5 +25,5 @@ API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client gene
## 돌리기
이 저장소의 어떤 workflow도 3.2를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`이 릴리스 산출물이고,
`WebOpenApi32GeneratorTest`가 generator를 다룬다.
이 저장소의 어떤 workflow도 OpenAPI 문서를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`은 서비스가 내보낼 안정
lane의 이름이고, `WebOpenApi32GeneratorTest`가 3.2 generator를 다룬다.
+11 -2
View File
@@ -38,6 +38,10 @@ route는 정확히 하나만 받고, 다른 것을 보내면 최선의 짐작
**한도.** 연산은 최대 100개, pointer 깊이는 최대 16, merge patch 중첩 깊이는 최대 32. 앞의 둘은 곱해진다. 연산마다
서버가 먼저 깊이 복사한 문서 위로 pointer를 따라 걷는다.
**거부 코드.** 형식이 틀린 문서(JSON이 아닌 본문, 빈 문서, 한도 초과, 연산 모양 오류)는 모두 `400 PATCH_REJECTED`다.
허용 목록 밖의 경로만 `403 PATCH_PATH_FORBIDDEN`이고, 실패한 `test`는 `409 PATCH_TEST_FAILED`다. 너무 깊은 pointer는
권한 문제가 아니라 형식 문제라 400이다.
## 원자성
JSON Patch 문서는 전부 적용되거나 하나도 적용되지 않는다. 모든 연산은 작업 사본에서 돈다. 모든 연산이 성공하고
@@ -60,8 +64,13 @@ JSON Patch 문서는 전부 적용되거나 하나도 적용되지 않는다.
## 검증
patch를 적용한 결과는 필드 하나씩이 아니라 문서 전체로 검증한다. 필드 하나하나는 모두 유효한 patch가 유효하지 않은
객체를 만들 수 있다. 서로 맞아야 하는 두 필드, 허락되지 않은 상태 전이 같은 것이다. 바뀐 것만 검증하면 그중 아무것도
보지 못한다.
객체를 만들 수 있다. 서로 맞아야 하는 두 필드가 그런 예다. 바뀐 것만 검증하면 그것을 보지 못한다.
- 두 applier는 서비스의 Bean Validation `Validator`를 생성자로 받고, 결과 객체 전체를 검증한 뒤에 돌려준다. 위반은
`@Valid` 본문과 같은 `400 VALIDATION_FAILED`와 필드별 `details`다.
- 결과가 자원 타입으로 읽히지 않으면(숫자 자리에 문자열) `400 PATCH_REJECTED`다.
- 검증하는 대상은 web 표현 DTO이고, 제약은 요청 문법이다(web AGENTS B4·C1). 상태 전이처럼 업무 규칙인 검증은 여기서
하지 않는다. 결과를 command로 바꿔 받은 유스케이스가 한다.
## 선행 조건
+11 -10
View File
@@ -144,9 +144,10 @@ worker는 바뀐 행 수로 그것을 안다.
## 8. 예산 강제: edge가 막는 것과 애플리케이션이 막는 것
> **2026-09-25에 지움.** servlet 예산 filter(`WebMvcBudgetFilter`)와 그 problem 대응은 2세대 플랫폼과 함께 지웠다.
> 내보내는 애플리케이션은 더는 아래 애플리케이션 칸을 강제하지 않는다. `budget` 목록(`WebRequestBudget`,
> `WebBudgetCatalog`)은 `adapter:inbound:web-advanced`에 라이브러리 코드로 남고, 쓰이지 않던 meter(`WebBudgetMeter`와
> 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다.
> 내보내는 애플리케이션이 직접 강제하는 칸은 요청 본문 한도뿐이다. JSON 본문은 web 한도(`app.web.mvc.max-json-body-size`,
> 기본 1 MiB, web `JsonBodyLimitFilter`, 넘으면 413 `PAYLOAD_TOO_LARGE` Envelope), multipart는 Spring 기본 한도다. 나머지 칸의 이름(`maxUriBytes` 등)은
> `budget` 목록(`WebRequestBudget`, `WebBudgetCatalog`)의 값이고, 그 목록은 `adapter:inbound:web-advanced`에 라이브러리
> 코드로만 남았다. 쓰이지 않던 meter(`WebBudgetMeter`와 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다.
설계(Task 49)는 edge proxy의 한도와 애플리케이션 자체 한도의 차이를 장애 중에 발견하지 말고 적어 두라고 요구한다.
같은 차원에 한도는 늘 둘 있고, 둘은 결코 같지 않으며, 어느 쪽이 걸리는지가 호출자가 보는 것을 정한다.
@@ -155,11 +156,11 @@ worker는 바뀐 행 수로 그것을 안다.
| --- | --- | --- | --- |
| 요청 줄 / URI | `large_client_header_buffers`(기본 8k) | `maxUriBytes` | edge가 먼저 — nginx가 자기 HTML로 414 |
| 요청 헤더 | `large_client_header_buffers` | `maxHeaderBytes` | edge가 먼저 — nginx 400, problem document 없음 |
| 요청 본문 | `client_max_body_size`(기본 1m) | `maxBodyBytes`(플랫폼 상한 8 MiB) | 더 작은 쪽. nginx는 HTML로 413 |
| query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 늘 애플리케이션 |
| JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 늘 애플리케이션 |
| 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | 플랫폼 쪽이 더 크면 edge가 먼저 |
| 응답 크기 | 강제하지 않음 | `maxResponseBytes`(상한 32 MiB) | 늘 애플리케이션 |
| 요청 본문 | `client_max_body_size`(기본 1m) | JSON 본문: `app.web.mvc.max-json-body-size`(기본 1 MiB, 강제함). multipart 본문: Spring 기본 한도(`spring.servlet.multipart.*`, 넘으면 Envelope 413). 그 밖의 raw 본문: 전역 한도 없음, endpoint가 둔다 | 더 작은 쪽. nginx는 HTML로 413, 애플리케이션은 Envelope로 413 |
| query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 아무도 막지 않는다(애플리케이션 칸은 목록 값뿐) |
| JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 깊이는 Jackson 기본 `StreamReadConstraints`만 걸린다. 배열 크기는 아무도 막지 않는다 |
| 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | edge. 애플리케이션 칸은 목록 값뿐이다 |
| 응답 크기 | 강제하지 않음 | `maxResponseBytes`(상한 32 MiB) | 아무도 막지 않는다(애플리케이션 칸은 목록 값뿐) |
둘 다 직관과 반대라서 적어 둘 만한 결과가 둘 있다.
@@ -167,8 +168,8 @@ worker는 바뀐 행 수로 그것을 안다.
HTML 오류 쪽을 답하므로, `error.code`로 분기하는 client는 파싱할 수 없는 본문을 받는다. client에게 중요한 차원이면
edge 한도를 애플리케이션보다 *높게* 두어 애플리케이션이 거부하게 한다.
**edge 한도가 애플리케이션보다 높아도 쓸데없지 않다.** 애플리케이션의 meter가 세기 전에 문제가 될 만큼 큰 본문과
프로세스 사이에 서 있는 것은 그것뿐이다. 둘 다 있어야 하고, 정할 것은 순서뿐이다.
**edge 한도가 애플리케이션보다 높아도 쓸데없지 않다.** 애플리케이션이 막지 않는 차원(위 표의 「아무도 막지 않는다」)에서
큰 요청과 프로세스 사이에 서 있는 것은 그것뿐이다. 둘 다 있어야 하고, 정할 것은 순서뿐이다.
## 9. Nginx lane (2026-09-25에 지움)
+16 -11
View File
@@ -12,8 +12,9 @@ writer는 `adapter:inbound:web-advanced`(골라 쓰는 leaf, `app.web.advanced.n
connection은 결과를 알 수 없다. 끝은 셋이다.
1. **`Complete` envelope.** stream이 끝났다. `lastSequence`가 마지막 위치다.
2. **`Failure` 기록.** commit 뒤에 무언가 실패했다. 오류 code와 client에게 보여도 되는 메시지를 담는다. 상태는 여전히
200이다.
2. **`Failure` 기록.** commit 뒤에 무언가 실패했다. 상태는 여전히 200이다. `code`는 실패한 예외의 코드다(예:
`STREAM_ITEM_TOO_LARGE`). 코드가 없는 실패는 등록된 `INTERNAL_ERROR`다. `message`는 그 category의 고정 문구다. commit 전에
던져졌다면 받았을 코드·문구와 같다.
3. **둘 다 아님.** stream 중간에 connection이 닫혔다. 서버는 이것을 `ABRUPT_CLOSE`로 기록한다. client 쪽에서는 *끝
envelope를 찾지 않는 한* 끝난 stream과 구분할 수 없다.
@@ -23,7 +24,7 @@ connection은 결과를 알 수 없다. 끝은 셋이다.
## 위치
모든 `Item`은 1부터 세는 `sequence`를 가진다. 위치는 엄격히 증가하고, 서버가 그것을 강제한다. 반복이나 후퇴는 client가
견뎌야 할 것이 아니라 서버 쪽 오류다.
견뎌야 할 것이 아니라 서버 쪽 오류다. writer는 그런 항목을 쓰지 않고 stream을 `INTERNAL_ERROR` `Failure` 기록으로 끝낸다.
0은 절대 유효한 위치가 아니다. 첫 항목이 0을 주장한 stream과 sequence를 아예 정하지 않은 stream이 똑같아 보이기
때문이다.
@@ -55,21 +56,25 @@ resnapshot은 자원을 보통 endpoint에서 다시 읽고 새 stream을 시작
## Heartbeat와 시간 초과
서버는 `heartbeatInterval`마다 keepalive를 쓴다. 그보다 오래 아무것도 보지 못한 client는 connection이 죽었다고 봐야
한다. socket에서는 조용한 connection과 끊긴 connection이 같고, heartbeat가 둘을 가른다.
writer(`MvcStreamWriter`)는 요청 thread에서 source를 차례로 쓴다. 그래서 heartbeat를 보내지 않고, `idleTimeout`·
`maxStreamAge`로 stream을 닫지도 않는다. 그 값은 `WebStreamPolicy`에 있고, 자기 stream을 `WebStreamRegistry`에 올려
돌리는 서비스가 쓴다.
stream은 `idleTimeout`(만든 것이 없음)과 `maxStreamAge`(활동과 상관없음)에 닫힌다. 둘 다 보통의 끝이고, connection이
허락하면 둘 다 끝 envelope를 보낸다.
- client는 heartbeat를 기대하지 않는다. 자기 읽기 시간 초과를 두고, 그 시간에 아무것도 오지 않으면 끝 envelope 없이
닫힌 것으로 보고 이어 받기 cursor로 다시 연결한다.
- socket에서는 조용한 connection과 끊긴 connection이 같다. heartbeat가 필요한 route는 서비스가 그것을 더하고 이 문서의
route 설명에 적는다.
## 느린 소비자
서버는 뒤처진 소비자를 위해 최대 `maxBufferedItems`까지만 버퍼링한다. 그것을 넘으면 버퍼를 키우지 않고 connection을
닫는다. 따라가지 못하는 client는 서버가 밀린 것을 쥐고 있기를 기대하지 말고, 이어 받기 cursor로 다시 연결한다.
writer는 버퍼를 두지 않는다. 느린 소비자는 서버의 쓰기를 막고, 그동안 source도 멈춘다. 서버 heap에 밀린 항목이 쌓이지
않는다. `maxBufferedItems`는 버퍼를 두는 서비스 구현의 한도다. 따라가지 못하는 client는 이어 받기 cursor로 다시 연결한다.
## 종료
rolling 배포 중에는 노드가 받기를 멈추기 전에 열린 stream이 다시 연결하라는 요청을 받는다. 바로 다시 연결한다. 노드는
drain 기한에 아직 열린 것을 강제로 닫고, 그것은 갑작스러운 닫힘으로 도착한다.
drain 순서(받기를 멈추고, 다시 연결을 요청하고, 기한에 강제로 닫기)는 `WebStreamDrainCoordinator`에 있다. 서비스가
자기 stream을 `WebStreamRegistry`에 등록하고 그 조정기를 종료 순서에 넣었을 때만 돈다. 기본 writer만 쓰는 배포에서는
종료 때 열린 stream이 갑작스러운 닫힘으로 끝난다.
갑작스러운 닫힘에 backoff와 jitter 없이 바로 다시 연결하지 않는다. 노드의 stream이 한꺼번에 끊겼을 때 모든 client가
한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다.
+6 -1
View File
@@ -36,7 +36,12 @@ app:
`VirtualThreadAdmissionGuard`는 pool이 아니라 공정한 semaphore다. 스레드를 제한하면 기다림을 되돌려 놓고 virtual
thread로 얻은 것을 버리게 된다. virtual thread 만 개가 있어도 백 개만 허가를 쥐고 나머지는 문 앞에서 거부된다.
거부는 **`Retry-After`가 붙은 503**이고, 상한이 만들려는 결과가 바로 그것이다. 1밀리초 만에 거부된 요청이, 받아들여진 뒤
상한은 `VirtualThreadAdmissionFilter`가 모든 요청에 건다. Spring Security chain 바로 뒤라, 거절 응답에도 CORS 헤더가
붙어 브라우저가 503과 `Retry-After`를 읽고, 보안 chain이 거절한 요청(인증 없음, 권한 없음)은 허가를 쓰지 않는다. 거절된
요청은 handler에 닿지 않는다. async 요청은 async 일이 끝날 때까지 허가를 쥔다. 넘겨준 순간 돌려주면 넘기는 일만 제한하고 정작
하류 pool을 쓰는 일은 제한하지 못한다.
거부는 **`Retry-After`가 붙은 503**(공용 코드 `SERVER_BUSY`)이고, 상한이 만들려는 결과가 바로 그것이다. 1밀리초 만에 거부된 요청이, 받아들여진 뒤
가득 찬 pool 뒤에서 30초 뒤에 시간 초과가 난 같은 요청보다 client에게 확실히 낫다.
semaphore는 일부러 공정하다. 불공정한 것이 빠르지만, 새로 온 요청이 기다리던 요청을 앞지르게 두고, 앞지름당한
+1 -1
View File
@@ -2,7 +2,7 @@
> **범위:** 내보내는 조립은 WebSocket 런타임을 조립하지 않는다. 이 runbook은 `PlatformWebSocketHandler`를 스스로 등록한
> 서비스에 적용한다(`src/adapter/inbound/websocket/README.md` 「라이브러리 API」). STOMP channel의 규칙은 leaf
> `CLAUDE.md`에 있다.
> `AGENTS.md`에 있다.
무엇을 보았는지로 나눴다. 장애 중에 손에 있는 것이 그것이기 때문이다.
+4
View File
@@ -58,6 +58,7 @@
| 개선 매뉴얼을 먼저(지난 것) | 다음 개선 작업 전에 repo마다 개선 매뉴얼을 만든다 → 2026-11-06 「매뉴얼 체계」로 바뀜 | 소유자 | 2026-11-05 | 2026-11-05 총괄 세션 brief |
| 스킬 | 리뷰·수정에 알맞은 스킬을 쓴다 | 소유자 | 2026-11-05 | `1103` 2절 |
| `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `.claude/rules/java-tests.md` 규칙 2 |
| 시험 형식 일괄 전환 | 영어 `@DisplayName`과 `// when` 없는 시험을 한꺼번에 바꾸지 않는다. 규칙(`.claude/rules/java-tests.md`)은 그대로이고, 고치는 시험에 적용한다. 한꺼번에 바꾸면 수천 줄의 diff가 결함 수정을 가린다 | 기본값(소유자가 뒤집을 수 있다) | 2026-11-12 | 2026-11-12 전체 리뷰 기록 README 6절 ④ |
| 학습 문서(지난 것) | 삭제된 코드를 설명하는 학습 문서(지금 `docs/history/study/*.ko.md`, `docs/history/packages/*-superpowers-package/`)는 현재 코드에 맞게 갱신 → 2026-11-07 갱신하지 않고 기록으로 보관(머리 블록만 단다)으로 바뀜 | 소유자 | 2026-09-25 | 결정 6, design-docs `repo-structure/README.md` 3.2절 |
| 문서 체계 | 문서를 수명으로 나눈다. 살아 있는 문서는 제자리에 두고 한국어로 옮긴다. 기록은 `docs/history/`, 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`에 둔다. 폴더 이름은 짝 프론트와 같이 쓴다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, 적용은 `docs/README.md` |
| 한국어의 범위 | 살아 있는 문서는 본문까지 한국어로 쓴다. 기록 문서는 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달고 본문은 원문 그대로 둔다. 상태는 한국어 고정 어휘다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
@@ -116,6 +117,9 @@
| GraphQL 인자 변환 실패 | Spring GraphQL 인자 binder의 `BindException`(`@Argument` 값이 파라미터 타입으로 바뀌지 않음)은 `BAD_PARAMETER`(`REQUEST`)로 답하고, WARN 한 줄(예외 타입만, 입력값 없음)을 남긴다. web이 바뀌지 않는 경로 변수에 답하는 것과 같다 | 소유자 | 2026-11-07 같은 전달, r8-f1 보고 「범위 밖」 2 |
| 약속한 응답으로 맞추기 | 레지스트리·`docs/web/http-contract.md`·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이다. 고치기 전에 묻지 않고, 응답이 바뀌니 업그레이드 안내 행은 적는다. 약속한 곳끼리 다르면 묻는다 | 소유자(2026-11-07, 기본값 확인) | `docs/work/improve.md` 7절, `docs/work/evidence.md` 11절 |
| STOMP 필수 header 누락 | 필수 header·destination 변수가 없을 때 Spring이 던지는 `MessageHandlingException`은 ERROR 그대로 둔다. 메시지에 입력값이 없고, Spring이 같은 타입으로 서버 실패(handler의 `Error` 등)도 감싸서 타입만으로는 클라이언트 탓을 가를 수 없다 | 기본값(2026-11-07) | 2026-11-07 총괄 지시, r8-f1 보고 「범위 밖」 3 |
| 서버 포화 코드 | 서버 쪽 상한(요청 허가, 꽉 찬 work pool)이 찬 거절은 모든 전송이 공용 `SERVER_BUSY`(503, `TRANSIENT_DEPENDENCY`, retryable, `Retry-After: 1`) 하나다. 호출자 자신의 빈도·동시성 초과만 429(`RATE_LIMIT_EXCEEDED`, fileserver `TRANSFER_ADMISSION_REJECTED`)다. 상태만 아는 503도 `SERVER_BUSY`이고, 비동기 요청 시간 초과만 `REQUEST_TIMEOUT`이다 | 기본값(2026-11-12, 소유자가 뒤집을 수 있다) | 2026-11-12 전체 리뷰 기록 README 6절 ② |
| batch 부분 실패 | fileserver batch도 공용 bulk envelope(web AGENTS B8)다. 하나라도 실패하면 `success:false` + `BATCH_PARTIAL_FAILURE` + 항목별 `details` | 기본값(2026-11-12) | 같은 README 6절 ① |
| PATCH 정본 | `docs/web/patch-contract.md`가 merge patch·JSON Patch의 정본이다. web AGENTS B2는 `application/json` PATCH DTO만 다루고 그쪽을 가리킨다 | 기본값(2026-11-12) | 같은 README 6절 ③ |
### 2.4 멱등성
+2 -2
View File
@@ -17,7 +17,7 @@
- **모양**: 계약·runbook·매뉴얼·README·Javadoc·실패 메시지가 현재 동작과 다르다.
- **막는 기준**: 동작을 바꾸는 변경은 그 동작을 설명하는 모든 문서를 같은 변경에서 고친다. 대상: `docs/web/http-contract.md`, `docs/registries/`, runbook, 매뉴얼, leaf README·`CLAUDE.md`, Javadoc, 업그레이드 안내. 고친 뒤 옛 표현을 grep으로 찾아 남은 곳을 없앤다.
- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`, `src/**/README.md`, `src/**/CLAUDE.md`를 grep.
- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`, `src/**/README.md`, `src/**/AGENTS.md`를 grep.
- **장치**: 일부만 있다. runbook 숫자와 상수를 비교하는 document-contract lane, runbook SQL을 실 PostgreSQL에서 그대로 실행하는 lane. 나머지는 리뷰가 본다. 이 repo는 문서 전체를 파싱하는 검사를 일부러 두지 않는다(`docs/testing/TESTING_STRATEGY.md` 8절).
### A3. 선언과 실행이 떨어져 있다
@@ -65,7 +65,7 @@
- **모양**: 프로필·환경 이름 하나가 다르면 위험한 기능이 열린다. 허용한 값으로는 실제로 동작하지 않는다.
- **막는 기준**: 위험한 기능(데모 계정, 비밀 검사 면제 등)은 거부 목록이 아니라 허용 목록으로 연다. 허용 목록의 값마다 실제로 그 값으로 동작해야 한다.
- **볼 것**: 프로필·환경 이름 문자열 비교, 허용 값마다 실제로 기동하는 테스트가 있는지.
- **장치**: `SampleDemoProfilesStartupSystemTest`(허용 프로필마다 기동).
- **장치**: 기동 때 profile 값을 검사하는 `RuntimeEnvironmentProfileValidator`와 그 시험. 허용 프로필마다 실제로 기동해 보던 시험은 샘플과 함께 지웠다(2026-11-07).
### A10. 글로만 있는 규칙
+8 -10
View File
@@ -1,9 +1,10 @@
# The container images the test lanes start, in one place (review 2026-11-01 08-04).
#
# ca.java-conventions reads this file and hands every key to every Test JVM as the system property
# `ca.test.image.<key>`; the file is an input of every Test task, so changing an image reruns the
# lanes that use it. Build scripts read the same values as `testContainerImages['<key>']`. An image
# change is a change to this file only.
# `ca.test.image.<key>`; the file is an input of every Test task, so changing any image reruns every
# test task in every leaf, not only the lanes that start that image. That is the price of one file
# for all of them: the cache cannot tell which lane reads which key. Build scripts read the same
# values as `testContainerImages['<key>']`. An image change is a change to this file only.
#
# Each image is pinned by digest, with its tag in the comment above it: a red lane should mean this repository changed, not
# that someone pushed a new image under the same tag. A lane whose image cannot be pulled fails; it
@@ -21,13 +22,10 @@
# postgres:16-alpine
postgres-16=postgres@sha256:0cefaabd882e42bcb2a2f3dc56d3ce4770560ba62fd7f197f1a2e008fd5731ab
# The sample's poster-image migration qualification was written against this patch release.
# postgres:16.4-alpine
postgres-16-4=postgres@sha256:5660c2cbfea50c7a9127d17dc4e48543eedd3d7a41a595a2dfa572471e37e64c
# 17 and 18 are not digest-pinned yet: they were not pulled on the machine this catalog was made
# on, and a digest copied from elsewhere would be unverified. Pin them with the next image update.
postgres-17=postgres:17-alpine
postgres-18=postgres:18-alpine
# postgres:17-alpine (PostgreSQL 17.11, pulled on the desktop runner 2026-11-13)
postgres-17=postgres@sha256:e5d2edd28b1f8d40a0a6c0c9cdc545b19b56a0d5d88f94bc11a97d970d4700d0
# postgres:18-alpine (PostgreSQL 18.6, pulled on the desktop runner 2026-11-13)
postgres-18=postgres@sha256:9ba53c7d41ea093baf5c1ba635ba5434c4f979880527d49bb7d9237d3193085b
# mongo:8.0.16
mongo-8=mongo@sha256:4b58ebcb1dc7a7b4e84cd8ce9098d48764ae4478876898ff9551acf2ac4a6a6d
# mongo:7.0.28
+12 -42
View File
@@ -6,24 +6,16 @@
# this build does choose. What is here is the set a module used to spell out inline, once per usage.
#
# The reason is visibility, not reproducibility — `gradle.lockfile` already fixes what resolves.
# Before this file, 59 coordinate strings were scattered across 15 build files and nothing could
# show them side by side, so two artifacts had quietly reached two versions:
#
# * spock-core 2.3-groovy-4.0 and 2.4-groovy-5.0
# * protobuf-java 4.29.3 and 4.33.2 (the 4.33.2 user, the messaging library's protobuf codec,
# moved to its own repository on 2026-11-08)
#
# Both are kept as separate aliases rather than unified. Unifying them here would change what
# resolves, in a change whose whole purpose is that it does not; the aliases make the split
# reviewable, and whoever converges them does so deliberately with the lockfiles regenerated.
# Before this file, coordinate strings were scattered across build files and nothing could show them
# side by side. An entry nothing reads is deleted rather than kept for later: the catalog claims to
# be what this build pins, and an unread line is a version nobody is looking after (2026-11-12).
#
# Tool and plugin versions live here too. They are not dependencies of any module, so they never
# appear in a gradle.lockfile and nothing but this file can show them side by side. Four of them
# (Spring Boot, spotless, spotbugs, errorprone) were spelled out in the root `plugins {}` block, and
# three more (google-java-format, the Checkstyle tool, the SpotBugs tool) inside the shared
# `configure(subprojects)` block; the errorprone *plugin* and the errorprone *checker* it runs were
# pinned in two different files, which is exactly the pair this file exists to put next to each
# other.
# appear in a gradle.lockfile and nothing but this file can show them side by side. build-logic reads
# the plugin versions (spotless, spotbugs, errorprone, Spring dependency management) for its own
# classpath and the tool versions (google-java-format, Checkstyle, SpotBugs, the errorprone checker)
# for the quality conventions; the errorprone *plugin* and the errorprone *checker* it runs are the
# pair this file exists to put next to each other.
#
# What is deliberately NOT here: the BOM property overrides in build-logic's JavaConventionsPlugin
# (ca.java-conventions) — `commons-lang3.version`, `httpcore5.version`, `httpclient5.version`. They
@@ -67,7 +59,6 @@ jqwik = "1.9.1"
jackson3 = "3.1.7"
jsonSchemaValidator = "3.0.2"
junitJupiter = "5.11.3"
junitPlatform = "1.11.3"
logstashLogbackEncoder = "8.0"
# Pinned (see `pinned-*` below). CVE-2026-106451, fixed in 1.11.4. Brought by kafka-clients (1.10.1).
lz4Java = "1.11.4"
@@ -79,23 +70,16 @@ okhttp = "4.12.0"
# Pinned (see `pinned-*` below). CVE-2025-67030, fixed in 3.6.1 on the 3.x line. Brought by the
# Checkstyle tool's doxia (3.3.0).
plexusUtils = "3.6.1"
# The second live protobuf version (the messaging library's schema codec pins the third, 4.33.2, in its
# own repository since 2026-11-08). adapter:inbound:grpc
# The protobuf version adapter:inbound:grpc
# imports protobuf-bom at this major to match the gRPC BOM above; it is read through
# `ext.protobufVersion`. Keep it at the protobuf-java that grpc-protobuf of that BOM declares: the
# protobuf-bom import is what resolves, so a lower number here would run gRPC on an older runtime
# than it was built against.
protobufGrpc = "3.25.8"
# The websocket leaf's proto contract is generated against an older runtime and has not been
# requalified; see the coordinate's own comment in that leaf.
protobufLegacy = "4.29.3"
resilience4j = "2.2.0"
# Pinned (see `pinned-*` below). CVE-2026-93451 and CVE-2026-108106, fixed in 1.1.10.9. Brought by
# kafka-clients (1.1.10.7).
snappyJava = "1.1.10.9"
# Two Groovy generations, deliberately not merged. See the header.
spockGroovy4 = "2.3-groovy-4.0"
spockGroovy5 = "2.4-groovy-5.0"
# SpotBugs *tool* version (the `spotbugs` extension). The plugin that runs it is spotbugsPlugin.
spotbugs = "4.10.2"
spotbugsPlugin = "6.5.6"
@@ -117,17 +101,11 @@ uuidCreator = "6.1.1"
approvaltests = { module = "com.approvaltests:approvaltests", version.ref = "approvaltests" }
assertj-core = { module = "org.assertj:assertj-core", version.ref = "assertj" }
archunit-junit5 = { module = "com.tngtech.archunit:archunit-junit5", version.ref = "archunit" }
errorprone-core = { module = "com.google.errorprone:error_prone_core", version.ref = "errorprone" }
findsecbugs-plugin = { module = "com.h3xstream.findsecbugs:findsecbugs-plugin", version.ref = "findsecbugs" }
jackson-databind-nullable = { module = "org.openapitools:jackson-databind-nullable", version = "0.2.6" }
jackson3-core = { module = "tools.jackson.core:jackson-core", version.ref = "jackson3" }
jackson3-databind = { module = "tools.jackson.core:jackson-databind", version.ref = "jackson3" }
jmh-core = { module = "org.openjdk.jmh:jmh-core", version.ref = "jmh" }
jmh-generator-annprocess = { module = "org.openjdk.jmh:jmh-generator-annprocess", version.ref = "jmh" }
jqwik = { module = "net.jqwik:jqwik", version.ref = "jqwik" }
json-schema-validator = { module = "com.networknt:json-schema-validator", version.ref = "jsonSchemaValidator" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junitJupiter" }
junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher", version.ref = "junitPlatform" }
logstash-logback-encoder = { module = "net.logstash.logback:logstash-logback-encoder", version.ref = "logstashLogbackEncoder" }
# The messaging library's modules the leaves use. Each leaf's registry row lists the ones it may
# reach in `allowed_libraries` (gradle/modules.json).
@@ -139,14 +117,11 @@ messaging-spring-boot-starter = { module = "dev.cakit.messaging:messaging-spring
messaging-spring-boot-starter-kafka = { module = "dev.cakit.messaging:messaging-spring-boot-starter-kafka", version.ref = "messagingLibrary" }
mockwebserver = { module = "com.squareup.okhttp3:mockwebserver", version.ref = "okhttp" }
okhttp-tls = { module = "com.squareup.okhttp3:okhttp-tls", version.ref = "okhttp" }
protobuf-java-legacy = { module = "com.google.protobuf:protobuf-java", version.ref = "protobufLegacy" }
resilience4j-bulkhead = { module = "io.github.resilience4j:resilience4j-bulkhead", version.ref = "resilience4j" }
resilience4j-circuitbreaker = { module = "io.github.resilience4j:resilience4j-circuitbreaker", version.ref = "resilience4j" }
resilience4j-micrometer = { module = "io.github.resilience4j:resilience4j-micrometer", version.ref = "resilience4j" }
resilience4j-ratelimiter = { module = "io.github.resilience4j:resilience4j-ratelimiter", version.ref = "resilience4j" }
resilience4j-retry = { module = "io.github.resilience4j:resilience4j-retry", version.ref = "resilience4j" }
spock-core-groovy4 = { module = "org.spockframework:spock-core", version.ref = "spockGroovy4" }
spock-core-groovy5 = { module = "org.spockframework:spock-core", version.ref = "spockGroovy5" }
spring-cloud-context = { module = "org.springframework.cloud:spring-cloud-context", version.ref = "springCloudContext" }
spring-dotenv = { module = "me.paulschwarz:spring-dotenv", version.ref = "springDotenv" }
springdoc-openapi-starter-webmvc-api = { module = "org.springdoc:springdoc-openapi-starter-webmvc-api", version.ref = "springdoc" }
@@ -164,17 +139,12 @@ pinned-lz4-java = { module = "at.yawk.lz4:lz4-java", version.ref = "lz4Java" }
pinned-plexus-utils = { module = "org.codehaus.plexus:plexus-utils", version.ref = "plexusUtils" }
pinned-snappy-java = { module = "org.xerial.snappy:snappy-java", version.ref = "snappyJava" }
# Plugin coordinates for the root `plugins {}` block. Declared here so that a plugin version and the
# library version it governs cannot drift in two files — errorprone is the live example: the plugin
# (errorpronePlugin) and the checker jar it puts on the compile classpath (errorprone, referenced by
# libs.errorprone.core below) are now one screen apart.
# Plugin coordinates for the root `plugins {}` block: only the plugins it applies. The quality
# plugins (spotless, spotbugs, errorprone) are applied by build-logic, which takes their versions
# from [versions] above for its own classpath.
#
# The convention plugins from the included build (`ca.*`) are NOT here and cannot be: an included
# build supplies the plugin itself, so there is no coordinate and no version to pin.
[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "springBoot" }
spring-dependency-management = { id = "io.spring.dependency-management", version.ref = "springDependencyManagement" }
spotless = { id = "com.diffplug.spotless", version.ref = "spotless" }
spotbugs = { id = "com.github.spotbugs", version.ref = "spotbugsPlugin" }
errorprone = { id = "net.ltgt.errorprone", version.ref = "errorpronePlugin" }
jmh = { id = "me.champeau.jmh", version.ref = "jmhPlugin" }
+5 -3
View File
@@ -6,15 +6,17 @@
"This repository uses strict per-leaf Gradle lockfiles; Renovate does not regenerate those locks here.",
"A maintainer must run `./gradlew resolveAndLockAll --write-locks`, review the lock diff,",
"and commit the refreshed lockfiles before a dependency PR can pass `verifyDependencyLocks`.",
"Transitive vulnerabilities are NOT covered by either bot (direct deps only) — pin them with a Gradle",
"dependency constraint / resolutionStrategy.force (§4) and regenerate locks (supply-chain D8)."
"Transitive vulnerabilities are NOT covered by Renovate (direct deps only) — pin them with a Gradle",
"dependency constraint / resolutionStrategy.force (§4) and regenerate locks (supply-chain D8).",
"This file takes effect only where a Renovate instance is pointed at the repository; none is wired",
"for the Gitea host today. The enforced gate is scripts/ci/trivy-scan.sh in the pipelines."
],
"extends": [
"config:recommended",
"security:only-security-updates"
],
"vulnerabilityAlerts": {
"description": "Stable GitHub vulnerability alerts → immediate security PR, ignoring schedule.",
"description": "GitHub-hosted only: Renovate reads GitHub's Dependabot alerts, which a Gitea host does not have. osvVulnerabilityAlerts below is the source elsewhere.",
"enabled": true,
"labels": [
"security",
+4 -3
View File
@@ -10,8 +10,9 @@
# This was the build-logic `ca.developer-bootstrap` plugin (`./gradlew bootstrap`). Starting
# containers and probing an HTTP endpoint is not a build rule, so it is a script now (review
# 2026-09-24 BUILD-O3-5). The four stages and their order are unchanged: the next stage starts only
# when the previous one succeeded, and the app stage waits for startup Flyway through the compose
# healthcheck before the smoke probe runs.
# when the previous one succeeded, and the app stage waits for the compose healthcheck before the
# smoke probe runs. The default composition is web only: it opens no datasource and runs no
# Flyway. A service that adds the persistence-jpa line gets startup Flyway inside the same wait.
#
# Until 2026-11-07 it merged docker-compose.yml with docker-compose.local.yml and asked for a `db`
# service neither file had defined since the database moved to a third file, so the documented
@@ -40,7 +41,7 @@ fi
echo "bootstrap 2/4: starting the PostgreSQL dependency and waiting for readiness"
"${compose[@]}" up -d --wait db
echo "bootstrap 3/4: building and starting the app; startup Flyway finishes before health is ready"
echo "bootstrap 3/4: building and starting the app and waiting for its health"
"${compose[@]}" up -d --build --wait app
echo "bootstrap 4/4: requiring HTTP 200 and status=UP from ${health_endpoint}"
+5 -3
View File
@@ -1,5 +1,7 @@
#!/usr/bin/env python3
"""문서 검사 여섯: 언어, 기록의 머리 블록, 참조, 복사한 숫자, 문서 지도, 루트 README 절. 하나라도 걸리면 rc=1이다.
"""문서 검사 여덟: 언어, 기록의 머리 블록, 참조, 복사한 숫자, 문서 지도, 모듈 README 절, 상대 링크, 문체. 하나라도 걸리면 rc=1이다.
부르는 곳: PR 단계 `prCheck`의 `documentCheck`(루트 `build.gradle`), `scripts/verify.sh docs`.
규칙의 정본은 design-docs `conventions/docs-system.md`이고, 이 repo의 적용은 `docs/README.md`
「문서 수명과 언어」다. 이 스크립트는 그 규칙 중 기계로 볼 수 있는 것만 본다.
@@ -39,8 +41,8 @@
python3 -c 'import hashlib,sys; print(hashlib.sha256(sys.argv[1].encode()).hexdigest()[:16])' "<줄>"
- 2026-11-07 번역 단계에서 목록의 줄을 모두 지워 목록과 FROZEN이 비었다.
python3 scripts/check-docs.py # 여섯 모두
python3 scripts/check-docs.py --only head # 하나만 (language, head, reference, number, map, readme)
python3 scripts/check-docs.py # 여덟 모두
python3 scripts/check-docs.py --only head # 하나만 (CHECKS의 이름 하나)
python3 -m unittest discover -s scripts/tests # 이 검사의 시험
Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(build-logic/AGENTS.md 「저장소 파일을 읽는 테스트」).
+5 -3
View File
@@ -1,6 +1,8 @@
#!/usr/bin/env python3
"""저장소 루트와 src/ 최상위에 허용 목록 밖의 항목이 생기면 실패한다.
부르는 곳: PR 단계 `prCheck`의 `verifyRepositoryLayout`(루트 `build.gradle`), `scripts/verify.sh docs`.
왜: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이 여덟으로 늘었고, 어느 커밋도 최상위
모양을 묻지 않았다. 루트에는 개발 환경·테스트 fixture·운영 인프라가 섞인 compose 파일과 infra/ 폴더가
쌓였다(2026-11-07 저장소 정리, design-docs repo-structure/01-backend-layout.md). 소유자는 배치 규칙을
@@ -87,11 +89,11 @@ SRC_ALLOWED = {
# 아무도 가리키지 않으면 경고할 파일: 개발 환경과 테스트 fixture.
FIXTURE_SUFFIXES = (".sh", ".acl", ".json", ".yaml", ".yml")
FIXTURE_PREFIXES = ("compose/", "scripts/", "src/bootstrap/app/compose-lanes/")
# 기록 문서 폴더(docs/README.md 「문서 수명과 언어」). 기록이 옛 경로를 적은 것은 참조가 아니다.
HISTORY_PREFIXES = (
"docs/reviews/",
"docs/superpowers/",
"docs/evidence/",
"docs/study/",
"docs/history/",
"docs/design/",
"docs/adr/",
)
+4 -1
View File
@@ -1,6 +1,9 @@
#!/usr/bin/env python3
"""Fail when the work manual stops being readable without history or grows past its size limits.
Called by: the pull-request stage `prCheck` (`verifyWorkDocs`, root `build.gradle`) and
`scripts/verify.sh docs`.
The work manual is the root `AGENTS.md` (the map and the rule book) plus `docs/work/`. A Claude Code
session reads the map through the root `CLAUDE.md`, which imports it (`@AGENTS.md`) and adds a few
Claude-only lines. A session that has never seen this repository's history reads the map,
@@ -28,7 +31,7 @@ This lives outside Gradle on purpose: the build does not parse documents.
python3 scripts/check-work-docs.py --links docs README.md # relative links only, any files
python3 scripts/check-work-docs.py --history docs/manual # history IDs only, any files
The --links form is for machines without lychee (the link checker the pull-request workflow runs).
The --links form is for machines without lychee (the link checker the main-stage workflow runs).
The --history form applies the same history-ID patterns to documents outside docs/work/.
"""
+34 -8
View File
@@ -145,6 +145,25 @@ random_secret() { head -c 32 /dev/urandom | base64 | tr -d '=+/' | cut -c1-32; }
# characters decode to 24 and are rejected. This keeps the padding and the full alphabet.
random_key() { head -c 32 /dev/urandom | base64 | tr -d '\n'; }
# Appends one line per container of the lane's project to restarts.txt, prefixed with the phase.
# Fails when there is no container to inspect: an empty file used to pass the restart check, so a
# lane whose project name drifted reported "no restarts" over containers it never looked at. The
# callers run it as `record_restarts ... || return 1`, which turns `set -e` off inside, so a failed
# inspect returns on its own line instead of counting a container whose line was never written.
record_restarts() {
local phase="$1" container inspected=0
while read -r container; do
[[ -z "${container}" ]] && continue
docker inspect --format "${phase} {{.Name}} restarts={{.RestartCount}} oomKilled={{.State.OOMKilled}}" \
"${container}" >>"${LANE_EVIDENCE}/restarts.txt" || return 1
inspected=$((inspected + 1))
done < <(docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" ps -a -q)
if [[ ${inspected} -eq 0 ]]; then
echo "${id}: no container of project ${PROJECT} to inspect for restarts (${phase})" >&2
return 1
fi
}
run_lane() {
local lane_json="$1"
local id runtime profile
@@ -384,8 +403,8 @@ run_lane() {
echo "== ${id} (project ${PROJECT}, runtime ${runtime})"
# 2. static contract, then render, then create
"${REPO_ROOT}/scripts/verify-compose-profile-contracts.sh" >"${LANE_EVIDENCE}/contract.log" 2>&1
# 2. render, then create. The static contract ran once for the whole run, before the first lane
# (it renders every lane itself, so running it per lane rendered the matrix once per lane).
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" config >"${LANE_EVIDENCE}/rendered.yml" )
redact_in_place "${LANE_EVIDENCE}/rendered.yml"
# Build before create. The app service declares both `build:` and `image:`, so Compose reuses a
@@ -528,6 +547,10 @@ run_lane() {
cp "${LANE_EVIDENCE}/health.json" "${LANE_EVIDENCE}/health-phase1.json"
cp "${LANE_EVIDENCE}/info.json" "${LANE_EVIDENCE}/info-phase1.json"
# Recorded before the recreate: --force-recreate makes a new container whose restart count
# starts at zero, so a kill during the first phase would otherwise leave no trace.
record_restarts phase1 || return 1
# The application only. The database and its volume stay up, which is the whole point.
echo "-- ${id}: restarting the application into the second phase"
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" stop app >/dev/null 2>&1 )
@@ -595,14 +618,10 @@ run_lane() {
# checks above all ask the application a question, and a restarted application answers them, so
# the restart itself has to be the failure. The peak memory is recorded beside it, so a lane that
# is close to its limit is visible before it crosses it.
local container restarted=""
local restarted=""
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app cat /sys/fs/cgroup/memory.peak \
>"${LANE_EVIDENCE}/app-memory-peak-bytes.txt" 2>/dev/null || true
while read -r container; do
[[ -z "${container}" ]] && continue
docker inspect --format '{{.Name}} restarts={{.RestartCount}} oomKilled={{.State.OOMKilled}}' \
"${container}" >>"${LANE_EVIDENCE}/restarts.txt"
done < <(docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" ps -a -q)
record_restarts final || return 1
restarted="$(grep -v ' restarts=0 oomKilled=false$' "${LANE_EVIDENCE}/restarts.txt" || true)"
if [[ -n "${restarted}" ]]; then
echo "${id}: a container restarted or was killed for memory during the lane:" >&2
@@ -626,6 +645,13 @@ run_lane() {
GENERATED_SECRETS=()
FAILED_LANES=()
# The static contract once for the run, in both modes: it renders every lane by itself, so running it
# inside each lane rendered the whole matrix once per lane.
mkdir -p "${EVIDENCE_ROOT}"
CONTRACT_LOG="${EVIDENCE_ROOT}/contract-${RUN_ID}.log"
"${REPO_ROOT}/scripts/verify-compose-profile-contracts.sh" >"${CONTRACT_LOG}" 2>&1 \
|| { echo "run-compose-runtime-smoke: the static Compose contract failed; see ${CONTRACT_LOG}" >&2; exit 1; }
if [[ "${MODE}" == "lane" ]]; then
lane_json="$(jq -c --arg id "${SELECTED_LANE}" '.lanes[] | select(.id == $id)' "${CONTRACTS}")"
[[ -n "${lane_json}" ]] || { echo "no lane '${SELECTED_LANE}' in ${CONTRACTS}" >&2; exit 64; }
+84
View File
@@ -0,0 +1,84 @@
"""scripts/check-repo-layout.py의 시험. 허용 목록 밖의 항목과 registry 경로를 실패로 보는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import json
import sys
import tempfile
import unittest
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
_spec = importlib.util.spec_from_file_location("check_repo_layout", SCRIPTS / "check-repo-layout.py")
check_repo_layout = importlib.util.module_from_spec(_spec)
sys.modules["check_repo_layout"] = check_repo_layout
_spec.loader.exec_module(check_repo_layout)
class TopLevelTest(unittest.TestCase):
def test_a_root_entry_outside_the_allow_list_is_not_allowed(self) -> None:
# given
paths = ["AGENTS.md", "stray-notes.txt", "src/domain/core/build.gradle"]
# when
unknown = check_repo_layout.top_level(paths, "") - check_repo_layout.ROOT_ALLOWED.keys()
# then
self.assertEqual(unknown, {"stray-notes.txt"})
def test_a_folder_under_src_that_is_not_a_layer_is_not_allowed(self) -> None:
# given
paths = ["src/domain/core/build.gradle", "src/tools/helper.py"]
# when
unknown = check_repo_layout.top_level(paths, "src/") - check_repo_layout.SRC_ALLOWED.keys()
# then
self.assertEqual(unknown, {"tools"})
class RegistryTest(unittest.TestCase):
def test_a_registry_source_path_outside_the_layer_folders_is_reported(self) -> None:
# given
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
(root / "gradle").mkdir()
modules = [
{"id": "domain-core", "source_path": "src/domain/core"},
{"id": "stray", "source_path": "tools/stray"},
]
(root / check_repo_layout.REGISTRY).write_text(
json.dumps({"modules": modules}), encoding="utf-8"
)
original = check_repo_layout.REPO_ROOT
check_repo_layout.REPO_ROOT = root
try:
# when
problems = check_repo_layout.registry_violations()
finally:
check_repo_layout.REPO_ROOT = original
# then
self.assertEqual(len(problems), 1)
self.assertIn("stray", problems[0])
class HistoryPrefixesTest(unittest.TestCase):
def test_every_history_prefix_is_a_folder_that_exists(self) -> None:
# when
missing = [
prefix
for prefix in check_repo_layout.HISTORY_PREFIXES
if not (check_repo_layout.REPO_ROOT / prefix).is_dir()
]
# then
self.assertEqual(missing, [], "a prefix for a folder that is gone excludes nothing")
if __name__ == "__main__":
unittest.main()
+75
View File
@@ -0,0 +1,75 @@
"""scripts/check-review-index.py의 시험. 영역 문서의 발견이 README 색인에 빠지면 실패하는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import io
import sys
import tempfile
import unittest
from contextlib import redirect_stderr, redirect_stdout
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
_spec = importlib.util.spec_from_file_location("check_review_index", SCRIPTS / "check-review-index.py")
check_review_index = importlib.util.module_from_spec(_spec)
sys.modules["check_review_index"] = check_review_index
_spec.loader.exec_module(check_review_index)
def run(review: Path) -> int:
argv = sys.argv
sys.argv = ["check-review-index.py", str(review)]
try:
with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
return check_review_index.main()
finally:
sys.argv = argv
class ReviewIndexTest(unittest.TestCase):
def setUp(self) -> None:
self._directory = tempfile.TemporaryDirectory()
self.review = Path(self._directory.name)
(self.review / "01-area.md").write_text(
"# 영역\n\n### RR9-01-01 · Medium · 하나\n\n### RR9-01-02 · Low · 둘\n", encoding="utf-8"
)
def tearDown(self) -> None:
self._directory.cleanup()
def test_a_finding_missing_from_the_index_fails(self) -> None:
# given
(self.review / "README.md").write_text("| RR9-01-01 | Medium |\n", encoding="utf-8")
# when
rc = run(self.review)
# then
self.assertEqual(rc, 1)
def test_an_index_that_names_every_finding_passes(self) -> None:
# given
(self.review / "README.md").write_text(
"| RR9-01-01 | Medium |\n| RR9-01-02 | Low |\n", encoding="utf-8"
)
# when
rc = run(self.review)
# then
self.assertEqual(rc, 0)
def test_a_range_in_the_index_counts_for_every_id_inside_it(self) -> None:
# when
ids = check_review_index.indexed_ids("RR9-01-01~03, RR9-02-05·07")
# then
self.assertEqual(ids, {"RR9-01-01", "RR9-01-02", "RR9-01-03", "RR9-02-05", "RR9-02-07"})
if __name__ == "__main__":
unittest.main()
@@ -0,0 +1,45 @@
"""scripts/verify-httpclient-docs.py의 시험. 코드의 이름이 문서에서 빠지면 실패하는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import io
import sys
import unittest
from contextlib import redirect_stdout
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
_spec = importlib.util.spec_from_file_location("verify_httpclient_docs", SCRIPTS / "verify-httpclient-docs.py")
verify_httpclient_docs = importlib.util.module_from_spec(_spec)
sys.modules["verify_httpclient_docs"] = verify_httpclient_docs
_spec.loader.exec_module(verify_httpclient_docs)
class HttpclientDocsTest(unittest.TestCase):
# No case runs the verifier over the real tree and expects 0: that is the release workflow's
# check, and this suite runs in the pull-request gate (documentCheck).
def test_a_metric_missing_from_the_documentation_fails_naming_it(self) -> None:
# given
metric = verify_httpclient_docs.metric_names()[0]
original = verify_httpclient_docs.read_docs
verify_httpclient_docs.read_docs = lambda: original().replace(metric, "")
output = io.StringIO()
try:
# when
with redirect_stdout(output):
rc = verify_httpclient_docs.main()
finally:
verify_httpclient_docs.read_docs = original
# then
self.assertEqual(rc, 1)
self.assertIn(f"metric '{metric}'", output.getvalue())
if __name__ == "__main__":
unittest.main()
+19 -3
View File
@@ -1,7 +1,10 @@
#!/usr/bin/env bash
# The static half of the Compose contract: every lane renders, and renders exactly what it claims.
#
# Nine things are checked, and each exists because assuming it cost something:
# Called by: the pull-request stage `prCheck` (`verifyComposeProfiles`, root build.gradle) and
# scripts/run-compose-runtime-smoke.sh before it starts the lanes.
#
# Ten things are checked, and each exists because assuming it cost something:
#
# 1. the Compose version, because `!override` is what stops the dev overlay's tmpfs merging with
# the base's and colliding with a bind mount, and it needs 2.24.4;
@@ -24,7 +27,11 @@
# would hide the same trade in production; the lane has to look like a deployment instead.
# 8. a lane's appMemoryLimit, when it has one, is a Compose memory size, because the smoke wrapper
# writes it into the application's mem_limit and a malformed one fails only at `up`.
# 9. the Keycloak realm artifact carries no key Keycloak refuses (below the lane loop).
# 9. the application's heap dump path (-XX:HeapDumpPath in the Dockerfile) is not a tmpfs, because a
# tmpfs is charged to the container's memory limit and is gone once the container exits: the
# dump written at an OutOfMemoryError could only push the container into an OOM kill and was
# never there to read (2026-11-12 review).
# 10. the Keycloak realm artifact carries no key Keycloak refuses (below the lane loop).
#
# Static only. Nothing starts here; scripts/run-compose-runtime-smoke.sh owns that.
set -euo pipefail
@@ -103,6 +110,8 @@ redis_authentication_problems() {
}
command -v jq >/dev/null 2>&1 || { echo "jq is required" >&2; exit 78; }
HEAP_DUMP_PATH="$(sed -n 's/.*-XX:HeapDumpPath=\([^ \\"]*\).*/\1/p' "${REPO_ROOT}/Dockerfile" | head -1)"
[[ -n "${HEAP_DUMP_PATH}" ]] || { echo "the Dockerfile sets no -XX:HeapDumpPath" >&2; exit 78; }
command -v docker >/dev/null 2>&1 || { echo "docker is required" >&2; exit 78; }
[[ -r "${CONTRACTS}" ]] || { echo "missing ${CONTRACTS}" >&2; exit 78; }
@@ -233,10 +242,17 @@ for index in $(seq 0 $((lane_count - 1))); do
fail "${id}: appMemoryLimit '${memory_limit}' is not a Compose memory size such as 1g"
fi
# 9. the heap dump path is not a tmpfs.
heap_tmpfs="$(jq -r --arg path "${HEAP_DUMP_PATH}" \
'.services.app.tmpfs // [] | .[] | split(":")[0] | select(. == $path)' <<<"${model}")"
if [[ -n "${heap_tmpfs}" ]]; then
fail "${id}: app mounts the heap dump path ${HEAP_DUMP_PATH} as a tmpfs, which counts against its memory limit and is gone when it exits"
fi
[[ ${FAILURES} -eq 0 ]] && echo "${id}: ${expected} @ ${runtime}"
done
# 9. the Keycloak realm artifact deserializes into Keycloak's own representation.
# 10. the Keycloak realm artifact deserializes into Keycloak's own representation.
#
# Keycloak rejects unknown fields rather than ignoring them, so one annotation key anywhere in the
# tree fails the whole import, the container exits 1, and every lane that needs an identity provider
+2
View File
@@ -1,6 +1,8 @@
#!/usr/bin/env python3
"""Fail when the HTTP Client Platform's code and documentation have drifted.
Called by: the release workflow (`.gitea/workflows/release.yml`, job `httpclient-documentation`).
The design (§33 "Documentation") requires the support matrix, configuration reference, security
guide and runbook to match the code. Review cannot hold that line by itself, so
this verifier extracts the names that are part of the public contract -- stable exceptions, metric
+2 -2
View File
@@ -127,7 +127,7 @@ echo ""
echo "=== [architecture] repository-wide verification"
if (cd "${GRADLE_DIR}" \
&& "${GRADLE[@]}" verifyCleanArchitectureDependencies \
&& "${GRADLE[@]}" :app-bootstrap:test --tests '*CleanArchitectureTest'); then
&& "${GRADLE[@]}" :app-bootstrap:architectureTest); then
RAN+=("architecture:repository-wide")
else
FAILED+=("architecture:repository-wide")
@@ -153,7 +153,7 @@ mkdir -p "${MANIFEST_DIR}"
echo "{"
echo " \"commit\": \"$(git -C "${REPO_ROOT}" rev-parse HEAD)\","
echo " \"commitDirty\": $( [[ -n "$(git -C "${REPO_ROOT}" status --porcelain)" ]] && echo true || echo false ),"
echo " \"serverImage\": \"${MONGODB_IMAGE:-mongo:8.0.16}\","
echo " \"serverImage\": \"$(sed -n 's/^mongo-8=//p' "${REPO_ROOT}/gradle/container-images.properties")\","
echo " \"generatedAt\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\","
echo " \"contractManifest\": \"src/adapter/outbound/persistence-mongo/release/release-contracts.json\","
echo " \"contractManifestSha256\": \"$(sha256sum "${REPO_ROOT}/src/adapter/outbound/persistence-mongo/release/release-contracts.json" | cut -d' ' -f1)\""
+18 -15
View File
@@ -16,21 +16,15 @@ Package root: `dev.caskeleton.adapter.inbound.graphql`.
## 플랫폼 모듈 = sub-package (Gradle 모듈 아님)
GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이
leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은
leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 여러 기능 package를 같은
방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성
SSOT(`gradle/modules.json`)까지 밀어올리지 않는다는 선택이다.
**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매
플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는
`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간
낡는다. 즉 이 레포에는 두 패턴이 공존한다:
| | 방식 | 경계 강제 |
| --- | --- | --- |
| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 |
| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) |
어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다.
**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하다. 자매 플랫폼 messaging 은
한때 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 그 플랫폼은 2026-11-08 별도 repo
`messaging-library`로 옮겨 버전으로 받는다(`docs/work/reference/related-repos.md`). 그래서 이 repo 안에는 비교할 다른
패턴이 없다. GraphQL 내부를 leaf로 나누는 일은 레지스트리에 leaf를 더하는 변경이고, 경계 강제는 지금
아래 ArchUnit 테스트(전송 경계만)다.
sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/`
모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다
@@ -89,6 +83,8 @@ required-class 검사가 이 테스트가 조용히 사라지는 것을 막는
의존해야 했고, 그건 의존 방향이 뒤집힌다.
- `spring-boot-starter-graphql` (Spring Boot BOM 관리 — 버전 명시 없음).
- test scope 에 한해 `spring-boot-starter-web`(random-port 전송 테스트용),
`spring-boot-restclient`·`spring-boot-resttestclient`(그 테스트가 부르는 `TestRestTemplate`),
`spring-boot-starter-graphql-test`(`GraphQlTester`),
`spring-boot-starter-security`(HTTP 인증/CORS qualification 용),
`io.micrometer:micrometer-core`(실제 `MeterRegistry` 로 metric label cardinality 를 **측정**).
- `java-test-fixtures` — 계약 스위트·통합 fixture·in-memory 스텁은 `src/testFixtures/java` 가
@@ -101,7 +97,7 @@ required-class 검사가 이 테스트가 조용히 사라지는 것을 막는
고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행
프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformSettings` 가
`@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티
게이트가 이 선언을 요구한다.
@@ -113,7 +109,9 @@ required-class 검사가 이 테스트가 조용히 사라지는 것을 막는
모듈을 자동 커버 — per-module 규칙 추가 불필요).
- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의
`HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다.
- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다.
- `config/graphql.yml` 밖의 설정 파일 — 이 leaf의 설정 기본값은 그 파일 하나다. 의존성에 support가 없어 공용
`ModuleDefaultsEnvironmentPostProcessor` 대신 `GraphQlActivationEnvironmentPostProcessor`가 읽는다(manual 10 기준 7 뒤 예외).
전송 설정 `spring.graphql.*`은 composition-root `application.yml`에 둔다.
## 오류 대응 (`Category → ErrorType`)
@@ -157,9 +155,14 @@ health 스키마만 소유한다.
```bash
./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지
./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버)
./gradlew :adapter:inbound:graphql:systemTest --console=plain # 실제 HTTP 서버
./gradlew :adapter:inbound:graphql:graphqlDocumentContractTest --console=plain # env-keys registry 대조
```
`graphqlDocumentContractTest` 는 `document-contract` 태그 시험(`GraphQlDeploymentModeRegistryParityTest`)만 돌린다.
저장소 문서를 읽으므로 `test` 에서는 돌지 않고 main 단계(leaf `mainCheck`)에서 돈다. 저장소 루트
(`ca.repository.root`)는 이 lane 만 받는다.
`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면
실패한다(`build.gradle` 의 strict lane `requires` + `rejectSkipped`). 같은 클래스는 `test` 에서도 돈다.
+11 -11
View File
@@ -123,11 +123,12 @@ gRPC 와 달리 spring-graphql / graphql-java 는 Spring Boot BOM 이 관리한
## 설정 — 프레임워크 `spring.graphql.*` + 플랫폼 `app.graphql.*`
전송 계층 설정(path, graphiql, introspection, schema location)은 프레임워크 `spring.graphql.*`
가 소유한다. composition-root `application.yml` 에서 설정하며 모듈별 `yml` 은 없다.
가 소유한다. composition-root `application.yml` 에서 설정한다. 이 leaf의 `app.graphql.*` 기본값과 env 연결은
모듈의 `config/graphql.yml` 하나에 있고, `GraphQlActivationEnvironmentPostProcessor`가 가장 낮은 우선순위로 읽는다.
플랫폼 정책은 `spring.graphql.*` 로 표현할 수 없다 — cost/page 한계, preparsed
캐시 경계, 관측 label 로 허용할 operation 이름은 전부 이 leaf 의 결정이다. 그래서
`GraphQlPlatformProperties` 가 **`app.graphql`** prefix 로 `@ConfigurationProperties` 를
`GraphQlPlatformSettings` 가 **`app.graphql`** prefix 로 `@ConfigurationProperties` 를
바인딩한다(`spring.graphql.platform.*` 이 아니다 — 그 prefix 는 존재한 적이 없다).
```yaml
@@ -148,9 +149,9 @@ app:
observed-operation-names: [] # 비우면 모든 operation 이름이 `other` 로 접힌다
```
이 모듈의 `config/graphql.yml`이 위 wired 설정을 `APP_GRAPHQL_*`로 노출한다. `APP_GRAPHQL_ENABLED`와
`APP_GRAPHQL_DEPLOYMENT_MODE` 외에도 execution profile, console, page/complexity, preparsed-cache
한계와 관측 operation allowlist가 같은 property tree로 들어간다.
이 모듈의 `config/graphql.yml`이 위 설정을 `APP_GRAPHQL_*`로 노출한다. `APP_GRAPHQL_ENABLED`와
`APP_GRAPHQL_DEPLOYMENT_MODE` 외에도 console(`APP_GRAPHQL_GRAPHIQL_ENABLED`, `APP_GRAPHQL_INTROSPECTION_ENABLED`),
page/complexity, preparsed-cache 한계, N+1 경고 임계와 관측 operation allowlist가 같은 property tree로 들어간다.
production mode는 env만으로 완성되지 않는다. 애플리케이션 좌표를 스켈레톤이 알 수 없으므로
**명시적인 `GraphQlAuthorizationPolicy` bean이 반드시 필요**하며, 이것은 의도된 fail-closed
@@ -180,16 +181,15 @@ composition root 는 이 leaf 를 채택할 때 인증/인가 및 CORS 정책을
(`gradle/modules.json`)에 추가하는 것은 레지스트리·
`settings.gradle` fail-closed 검증·의존 게이트를 동시에 건드리는 변경이다. GraphQL 표면은 하나의
인바운드 전송 경계이므로 그 **내부** 분할을 레포 전역 SSOT 까지 밀어올리지 않기로 하고,
**모듈 = bounded sub-package** 로 매핑했다(선례: httpclient leaf 가 366개 java 파일을 같은 방식으로
**모듈 = bounded sub-package** 로 매핑했다(선례: httpclient leaf 가 여러 기능 package를 같은 방식으로
담는다).
**정직하게 기록해 둘 반례:** 이후 main 에 통합된 자매 플랫폼 messaging 은 정반대로
**자기 leaf 를 레지스트리에 하나씩 등록**했다(지금의 leaf 목록과 수는 레지스트리가 정한다). 즉 레지스트리는 닫혀 있지 않았고,
"확장하면 게이트가 깨진다"는 전제는 과했다. 두 플랫폼이 서로 다른 패턴을 쓰고 있으므로
**어느 쪽으로 통일할지는 미결 아키텍처 결정**이다.
**정직하게 기록해 둘 반례:** 자매 플랫폼 messaging 은 정반대로 **자기 leaf 를 레지스트리에 하나씩
등록**했다. 즉 레지스트리는 닫혀 있지 않았고, "확장하면 게이트가 깨진다"는 전제는 과했다. 그 플랫폼은
2026-11-08 별도 repo `messaging-library`로 옮겼으므로 지금 이 repo에서 두 패턴이 공존하지는 않는다.
sub-package 경계를 값으로 선언하던 `moduleboundary/` 모델(소스 텍스트 스캐너 포함)은
2026-09-25 에 삭제했다. 두 플랫폼 중 어느 패턴으로 통일할지 정할 때 다시 설계한다.
2026-09-25 에 삭제했다. GraphQL 내부를 leaf로 나누기로 정할 때 다시 설계한다.
## 전송 경계 규칙은 빌드 때 ArchUnit 으로 검사한다
+27 -6
View File
@@ -42,6 +42,9 @@ configurations {
dependencies {
// TestRestTemplate for the random-port HTTP boundary tests. The spring-library convention adds
// only spring-boot-starter-test, so a leaf names the web test client it calls.
testImplementation 'org.springframework.boot:spring-boot-resttestclient'
implementation project(':shared-contract')
// The object-access rule this platform consults belongs to the application, and so does its
@@ -127,6 +130,24 @@ strictTestLanes {
requires 'dev.caskeleton.adapter.inbound.graphql.GraphQlTransportBoundaryArchitectureTest'
rejectSkipped = true
}
// GraphQlDeploymentModeRegistryParityTest reads docs/registries/env-keys.yaml. A comparison with
// a repository document runs here, in this leaf's `mainCheck`, not in the pull-request `test`,
// whose cache cannot see the registry change (build-logic/AGENTS.md, 2026-11-12 review). A lane
// never reports up to date, so it needs no inputs declared for the file it reads.
lane('graphqlDocumentContractTest') {
tag = 'document-contract'
description = 'Holds the GraphQL deployment modes to docs/registries/env-keys.yaml.'
rejectSkipped = true
mainStage()
// Only this lane gets the repository root, and it declares the one file it reads; the plain
// `test` gets neither, so an untagged test that reads the repository fails there.
systemProperty 'ca.repository.root', rootProject.projectDir.absolutePath
customize { Test task ->
task.inputs.file(rootProject.file('docs/registries/env-keys.yaml'))
.withPathSensitivity(PathSensitivity.RELATIVE)
.withPropertyName('envKeyRegistry')
}
}
}
// verifyGraphQlApiSurface — every public type this leaf exposes is a committed decision.
@@ -139,17 +160,17 @@ strictTestLanes {
// be.
//
// A snapshot does not shrink the surface. It makes each addition visible in review, which is the
// prerequisite for shrinking it: the `api` and `spi` packages are the surface an adopter is meant
// to use, and everything else in this file is a candidate for becoming internal when the leaf is
// split into capability artifacts. Until then the number cannot grow by accident.
// prerequisite for shrinking it: the `api` package is the surface an adopter is meant to use, and
// everything else in this file is a candidate for becoming internal when the leaf is split into
// capability artifacts. Until then the number cannot grow by accident.
apiSurface {
label = 'GraphQl'
baseline = rootProject.file('docs/architecture/graphql-api-surface.txt')
description = 'GraphQL leaf public API surface — every public top-level type in src/main/java.'
rationale = [
'A public type in a single-jar leaf is reachable from every adopter\'s code, so',
'additions are reviewed rather than discovered. `api` and `spi` are the intended',
'external surface; the rest are candidates to become internal when this leaf is',
'split into capability artifacts.',
'additions are reviewed rather than discovered. `api` is the intended external',
'surface; the rest are candidates to become internal when this leaf is split into',
'capability artifacts.',
]
}
@@ -146,14 +146,11 @@ org.springframework.boot:spring-boot-starter-test:4.0.9=systemTestCompileClasspa
org.springframework.boot:spring-boot-starter-tomcat-runtime:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-tomcat:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-web:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-webmvc-test:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-webmvc:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter:4.0.9=compileClasspath,runtimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-test-autoconfigure:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-test:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-tomcat:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-web-server:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-webmvc-test:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-webmvc:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-webtestclient:4.0.9=systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot:4.0.9=compileClasspath,runtimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath,testRuntimeClasspath
@@ -98,8 +98,9 @@ class GraphQlRequestDeadlineTest {
assertThat(finished)
.as("the running resolver is not interrupted; it finishes on its own thread")
.isTrue();
// Room for graphql-java to have dispatched the child, had the cancellation not stopped it.
Thread.sleep(500);
assertThat(SlowWork.slowExecutionEnded.await(5, TimeUnit.SECONDS))
.as("the execution ends after its last field, so a child that was going to start has")
.isTrue();
assertThat(SlowWork.DETAIL_INVOCATIONS)
.as("a cancelled execution must not start new fields once the client has been answered")
.hasValue(0);
@@ -114,5 +115,10 @@ class GraphQlRequestDeadlineTest {
GraphQlClientPolicy shortBudgetClientPolicy() {
return RuntimeLimitsTestSupport.policyWithExecutionBudget(BUDGET);
}
@Bean
graphql.execution.instrumentation.Instrumentation slowExecutionEndSignal() {
return SlowWork.executionEndSignal();
}
}
}
@@ -2,6 +2,13 @@ package dev.caskeleton.adapter.inbound.graphql.runtime;
import dev.caskeleton.adapter.inbound.graphql.HealthGraphqlController;
import dev.caskeleton.adapter.inbound.graphql.policy.GraphQlClientPolicy;
import graphql.ExecutionResult;
import graphql.execution.instrumentation.Instrumentation;
import graphql.execution.instrumentation.InstrumentationContext;
import graphql.execution.instrumentation.InstrumentationState;
import graphql.execution.instrumentation.SimpleInstrumentationContext;
import graphql.execution.instrumentation.SimplePerformantInstrumentation;
import graphql.execution.instrumentation.parameters.InstrumentationExecutionParameters;
import java.net.URI;
import java.time.Duration;
import java.util.concurrent.CountDownLatch;
@@ -85,12 +92,43 @@ final class RuntimeLimitsTestSupport {
static final AtomicInteger DETAIL_INVOCATIONS = new AtomicInteger();
static volatile CountDownLatch slowFinished = new CountDownLatch(1);
/**
* Counted down when a {@code slowNode} execution begun after the last {@link #reset()} has
* ended. The point after which a child field can no longer start, so an absence asserted after
* it is an absence and not a guess at how long the engine needs.
*/
static volatile CountDownLatch slowExecutionEnded = new CountDownLatch(1);
private static final AtomicInteger GENERATION = new AtomicInteger();
private SlowWork() {}
static void reset() {
SLOW_STARTED.set(0);
DETAIL_INVOCATIONS.set(0);
slowFinished = new CountDownLatch(1);
slowExecutionEnded = new CountDownLatch(1);
GENERATION.incrementAndGet();
}
/** Signals the end of each {@code slowNode} execution begun in the current generation. */
static Instrumentation executionEndSignal() {
return new SimplePerformantInstrumentation() {
@Override
public InstrumentationContext<ExecutionResult> beginExecution(
InstrumentationExecutionParameters parameters, InstrumentationState state) {
int generation = GENERATION.get();
CountDownLatch ended = slowExecutionEnded;
boolean slow =
parameters.getQuery() != null && parameters.getQuery().contains("slowNode");
return SimpleInstrumentationContext.whenCompleted(
(result, failure) -> {
if (slow && generation == GENERATION.get()) {
ended.countDown();
}
});
}
};
}
}
@@ -8,6 +8,8 @@ import java.nio.file.Path;
import java.util.Arrays;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
/**
@@ -16,7 +18,12 @@ import org.junit.jupiter.api.Test;
* <p>A mode the registry documents but the enum cannot bind fails at startup with a type-conversion
* error; a mode the enum has but the registry omits is one no operator is told about. Which runtime
* accepts each mode is held by {@code GraphQlDeploymentModeContractTest}.
*
* <p>Tagged {@code document-contract}: it reads a repository document, so it runs in the leaf's
* main-stage lane {@code graphqlDocumentContractTest}, never in the cached {@code test}. Only that
* lane receives the repository root ({@code ca.repository.root}); the test does not look for it.
*/
@Tag("document-contract")
class GraphQlDeploymentModeRegistryParityTest {
private static final Pattern ALLOWED_VALUES =
@@ -24,11 +31,16 @@ class GraphQlDeploymentModeRegistryParityTest {
"name: APP_GRAPHQL_DEPLOYMENT_MODE.*?allowed_values: \\[([^\\]]*)\\]", Pattern.DOTALL);
@Test
@DisplayName("registry의 APP_GRAPHQL_DEPLOYMENT_MODE 허용 값은 enum이 받는 값과 정확히 같다")
void theRegistryListsExactlyTheModesTheEnumHas() throws IOException {
// given
String registry = Files.readString(repositoryRoot().resolve("docs/registries/env-keys.yaml"));
Matcher matcher = ALLOWED_VALUES.matcher(registry);
assertThat(matcher.find()).isTrue();
// when
Matcher matcher = ALLOWED_VALUES.matcher(registry);
// then
assertThat(matcher.find()).as("the registry row and its allowed_values").isTrue();
assertThat(Arrays.stream(matcher.group(1).split(",")).map(String::trim))
.as("the registry is what an operator sets APP_GRAPHQL_DEPLOYMENT_MODE from")
.containsExactlyInAnyOrderElementsOf(
@@ -36,13 +48,12 @@ class GraphQlDeploymentModeRegistryParityTest {
}
private static Path repositoryRoot() {
Path candidate = Path.of("").toAbsolutePath();
while (candidate != null && !Files.isRegularFile(candidate.resolve("gradle/modules.json"))) {
candidate = candidate.getParent();
String root = System.getProperty("ca.repository.root");
if (root == null || root.isBlank()) {
throw new IllegalStateException(
"ca.repository.root is missing: only the graphqlDocumentContractTest lane reads the"
+ " repository");
}
if (candidate == null) {
throw new IllegalStateException("could not locate the repository root from the test cwd");
}
return candidate;
return Path.of(root);
}
}
@@ -41,9 +41,13 @@ class GraphQlMutationResultMapperTest {
}
@Test
void oneRootFieldCallsOneUseCase() {
void oneRootFieldThatCallsOneUseCaseIsAccepted() {
assertThatCode(() -> GraphQlMutationContractValidator.requireSingleUseCase(CREATE_ORDER, 1))
.doesNotThrowAnyException();
}
@Test
void oneRootFieldThatCallsTwoUseCasesIsRefused() {
assertThatThrownBy(() -> GraphQlMutationContractValidator.requireSingleUseCase(CREATE_ORDER, 2))
.isInstanceOf(GraphQlMutationContractException.class)
.hasMessageContaining("one use case");
@@ -58,6 +62,13 @@ class GraphQlMutationResultMapperTest {
() -> GraphQlMutationContractValidator.rejectRequestWideTransaction(roots, true))
.isInstanceOf(GraphQlMutationContractException.class)
.hasMessageContaining("not a shared transaction");
}
@Test
void severalRootMutationsWithoutARequestWideTransactionAreAccepted() {
List<GraphQlMutationCoordinate> roots =
List.of(CREATE_ORDER, new GraphQlMutationCoordinate("Mutation.createInvoice"));
assertThatCode(
() -> GraphQlMutationContractValidator.rejectRequestWideTransaction(roots, false))
.doesNotThrowAnyException();
@@ -232,6 +232,10 @@ class HmacGraphQlCursorCodecTest {
void framingRejectsADeclaredLengthLongerThanTheBody() {
assertThatThrownBy(() -> GraphQlCursorFraming.readAll("99:short"))
.isInstanceOf(GraphQlCursorException.class);
}
@Test
void framingAcceptsADeclaredLengthThatMatchesTheBody() {
assertThatCode(() -> GraphQlCursorFraming.readAll("5:hello")).doesNotThrowAnyException();
}
@@ -2,6 +2,7 @@ package dev.caskeleton.adapter.inbound.graphql.scalar;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarDefinition;
import dev.caskeleton.adapter.inbound.graphql.schema.GraphQlScalarManifest;
@@ -13,7 +14,13 @@ import java.time.Instant;
import java.time.LocalDate;
import java.util.Map;
import java.util.UUID;
import java.util.function.Function;
import java.util.stream.Stream;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource;
/** Stable custom scalar serialization and coercion contract (Stable plan Task 13). */
class GraphQlScalarContractTest {
@@ -79,14 +86,30 @@ class GraphQlScalarContractTest {
assertThat(LongScalar.serialize(42L)).isEqualTo("42");
}
@Test
void coercionErrorsDoNotEchoTheOffendingValue() {
static Stream<Arguments> parsers() {
return Stream.of(
Arguments.of("UUID", (Function<String, Object>) UuidScalar::parse),
Arguments.of("Date", (Function<String, Object>) DateScalar::parse),
Arguments.of("BigDecimal", (Function<String, Object>) BigDecimalScalar::parse),
Arguments.of("Long", (Function<String, Object>) LongScalar::parse));
}
@ParameterizedTest(name = "{0}")
@MethodSource("parsers")
@DisplayName("scalar 변환 오류는 거절한 값을 메시지에 싣지 않는다")
void coercionErrorsDoNotEchoTheOffendingValue(String scalar, Function<String, Object> parse) {
// given
String secret = "4111-1111-1111-1111";
assertThatThrownBy(() -> UuidScalar.parse(secret)).hasMessageNotContaining(secret);
assertThatThrownBy(() -> DateScalar.parse(secret)).hasMessageNotContaining(secret);
assertThatThrownBy(() -> BigDecimalScalar.parse(secret)).hasMessageNotContaining(secret);
assertThatThrownBy(() -> LongScalar.parse(secret)).hasMessageNotContaining(secret);
// when
Throwable refused = catchThrowable(() -> parse.apply(secret));
// then
// The type first: a message that merely lacks the value also passes for an NPE thrown before
// the scalar ever looked at it, which is not the refusal this test is about.
assertThat(refused)
.isInstanceOf(CoercingParseValueException.class)
.hasMessageNotContaining(secret);
}
@Test
@@ -81,6 +81,7 @@ class GraphQlScalarSymmetryTest {
String secret = "9".repeat(500);
assertThatThrownBy(() -> BigDecimalScalar.parse(secret))
.isInstanceOf(graphql.schema.CoercingParseValueException.class)
.hasMessageNotContaining(secret)
.hasMessageNotContaining("999");
}
+2 -2
View File
@@ -42,8 +42,8 @@ Package root: `dev.caskeleton.adapter.inbound.grpc`.
타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다
(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이
`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*`
키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`).
`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 `grpc-library` starter를 함께 받은 서비스의
`app.grpc.platform.*` 키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`).
| key | default | 의미 |
|---|---|---|
+7 -5
View File
@@ -23,9 +23,10 @@
이 줄을 지우면 서버, 포트, 설정 바인딩이 모두 함께 빠진다.
- 켜기와 끄기: 모듈이 있으면 켜진다. `app.grpc.server.enabled=false`로만 끈다.
- 필요한 설정: 전용 `APP_*` env 키는 registry에 없다. 켜진 상태에서 지금 구현이 받는 listener는
loopback plaintext뿐이라 `app.grpc.server.allow-insecure-local=true`(env
`APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL=true`)를 명시해야 기동한다. 선택: `app.grpc.server.port`
- 필요한 설정: registry 행은 끄는 값 `APP_GRPC_SERVER_ENABLED`와 `APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL` 둘이다.
켜진 상태에서 지금 구현이 받는 listener는 loopback plaintext뿐이라
`APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL=true`(`app.grpc.server.allow-insecure-local`)를 명시해야 기동한다. 나머지
`app.grpc.server.*`는 registry 행 없이 Spring relaxed 이름(`APP_GRPC_SERVER_PORT` 등)으로 받는다. 선택: `app.grpc.server.port`
(기본 9090), `.bind-address`(기본 127.0.0.1), `.reflection-enabled`, `.shutdown-grace-seconds`,
`.shutdown-drain-seconds`, 그리고 아래 「서버 한도」 절의 전송 한도 키.
@@ -59,7 +60,7 @@
io.grpc 기본값은 메시지 4 MiB, 연결당 동시 호출 무제한, 호출마다 스레드를 늘리는 cached
executor, 서버 deadline 없음, 연결 수명 무제한이다. 어댑터 서버는 이 값을 모두 명시한다.
| 키 (`app.grpc.server.*`) | 기본값 | 같은 값의 출처 (vendored 플랫폼) |
| 키 (`app.grpc.server.*`) | 기본값 | 같은 값의 출처 (`grpc-library` 플랫폼) |
|---|---|---|
| `max-inbound-message-bytes` | 1048576 (1 MiB) | `GrpcTransportLimits.DEFAULT_MAX_MESSAGE_BYTES` |
| `max-inbound-metadata-bytes` | 8192 (8 KiB) | `GrpcTransportLimits.DEFAULT_MAX_METADATA_BYTES` |
@@ -94,7 +95,8 @@ executor, 서버 deadline 없음, 연결 수명 무제한이다. 어댑터 서
health/reflection 에는 적용하지 않는다(`Health/Watch` 는 원래 오래 사는 스트림이다).
- **포화 시 동작(`GrpcCallAdmission`).** feature 호출은 `executor-max-pool-size +
executor-queue-capacity` 개까지만 받고, 넘친 호출은 handler 를 시작하지 않고 즉시
`RESOURCE_EXHAUSTED`(`RATE_LIMIT_EXCEEDED`, retryable)로 닫는다. 구현: io.grpc
`UNAVAILABLE`(`SERVER_BUSY`, retryable)로 닫는다. 서버 포화는 모든 전송이 이 공용 코드 하나다(2026-11-12 전에는
`RESOURCE_EXHAUSTED`/`RATE_LIMIT_EXCEEDED`였다). 구현: io.grpc
`ServerCallExecutorSupplier`(`@ExperimentalApi`, 1.39부터)가 호출 시작 전에 permit 을 확인해
받은 호출만 고정 크기 work pool 로 옮기고, 못 받은 호출은 가장 바깥 인터셉터가 닫는다. 메서드
조회·context 정리·health·reflection 은 작은 dispatch pool 에서 돈다. 버린 대안:
-22
View File
@@ -4,7 +4,6 @@
biz.aQute.bnd:biz.aQute.bnd.annotation:7.1.0=compileClasspath,testCompileClasspath
ch.qos.logback:logback-classic:1.5.38=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
ch.qos.logback:logback-core:1.5.38=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.fasterxml.jackson.core:jackson-annotations:2.21=testCompileClasspath,testRuntimeClasspath
com.fasterxml:classmate:1.7.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
@@ -78,9 +77,7 @@ org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.tomcat.embed:tomcat-embed-core:11.0.27=testCompileClasspath,testRuntimeClasspath
org.apache.tomcat.embed:tomcat-embed-el:11.0.27=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apache.tomcat.embed:tomcat-embed-websocket:11.0.27=testCompileClasspath,testRuntimeClasspath
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
@@ -128,27 +125,13 @@ org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.20=checkstyle
org.springframework.boot:spring-boot-autoconfigure:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-configuration-processor:4.0.9=annotationProcessor
org.springframework.boot:spring-boot-http-converter:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-jackson:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-resttestclient:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-servlet:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-jackson-test:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-jackson:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-logging:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-test:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-tomcat-runtime:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-tomcat:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-validation:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-webmvc-test:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-webmvc:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-test-autoconfigure:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-test:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-tomcat:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-validation:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-web-server:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-webmvc-test:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-webmvc:4.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot:4.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-aop:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-beans:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
@@ -156,12 +139,7 @@ org.springframework:spring-context:7.0.10=compileClasspath,runtimeClasspath,test
org.springframework:spring-core:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-expression:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-test:7.0.10=testCompileClasspath,testRuntimeClasspath
org.springframework:spring-web:7.0.10=testCompileClasspath,testRuntimeClasspath
org.springframework:spring-webmvc:7.0.10=testCompileClasspath,testRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
org.xmlunit:xmlunit-core:2.10.4=testCompileClasspath,testRuntimeClasspath
org.yaml:snakeyaml:2.5=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-core:3.1.7=testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-databind:3.1.7=testCompileClasspath,testRuntimeClasspath
tools.jackson:jackson-bom:3.1.7=testCompileClasspath,testRuntimeClasspath
empty=
@@ -28,9 +28,11 @@ import java.util.concurrent.atomic.AtomicBoolean;
* dispatch executor, before the call starts. A feature call that gets a permit is moved to the
* bounded work pool; one that does not stays on the dispatch executor and is marked, and this same
* object, installed as the outermost feature interceptor, closes the marked call with {@code
* RATE_LIMIT_EXCEEDED} without starting the handler. The permit is returned once, when the admitted
* call completes or is cancelled. Health and reflection are not feature calls: they take no permit
* and run on the dispatch executor, so a saturated pool cannot make health lie.
* SERVER_BUSY} ({@code UNAVAILABLE}) without starting the handler: the shared code every transport
* answers server saturation with, not the caller-rate {@code RATE_LIMIT_EXCEEDED} it used to be.
* The permit is returned once, when the admitted call completes or is cancelled. Health and
* reflection are not feature calls: they take no permit and run on the dispatch executor, so a
* saturated pool cannot make health lie.
*
* <p>Each admitted call has at most one task in the work pool at a time (io.grpc serializes a
* call's callbacks), so a work queue as deep as the permit count can never reject.
@@ -79,8 +81,8 @@ final class GrpcCallAdmission implements ServerCallExecutorSupplier, ServerInter
ServerCall<Q, R> call, Metadata headers, ServerCallHandler<Q, R> next) {
if (refused.remove(headers)) {
call.close(
statusMapper.statusFor(OperationalError.RATE_LIMIT_EXCEEDED),
statusMapper.trailersFor(OperationalError.RATE_LIMIT_EXCEEDED));
statusMapper.statusFor(OperationalError.SERVER_BUSY),
statusMapper.trailersFor(OperationalError.SERVER_BUSY));
return new ServerCall.Listener<>() {};
}
AtomicBoolean released = new AtomicBoolean();
@@ -17,9 +17,7 @@ import io.grpc.Status;
*/
public class GrpcStatusMapper {
/**
* Trailer key carrying the stable {@link ApiErrorCode#code()} (e.g. {@code WORKLOG_NOT_FOUND}).
*/
/** Trailer key carrying the stable {@link ApiErrorCode#code()} (e.g. {@code SERVER_BUSY}). */
static final Metadata.Key<String> CODE_KEY =
Metadata.Key.of("error-code", Metadata.ASCII_STRING_MARSHALLER);
@@ -329,8 +329,8 @@ class GrpcP1BoundaryWireTest {
}
@Test
@DisplayName("스레드와 대기열이 모두 찬 서버는 넘친 호출을 기다리게 두지 않고 즉시 RESOURCE_EXHAUSTED로 거절한다")
void aCallBeyondTheExecutorAndQueueIsRefusedAtOnceAsResourceExhausted() {
@DisplayName("스레드와 대기열이 모두 찬 서버는 넘친 호출을 기다리게 두지 않고 즉시 UNAVAILABLE(SERVER_BUSY)로 거절한다")
void aCallBeyondTheExecutorAndQueueIsRefusedAtOnceAsServerBusy() {
withChannel(
contextRunner.withPropertyValues(
"app.grpc.server.executor-max-pool-size=1",
@@ -351,12 +351,11 @@ class GrpcP1BoundaryWireTest {
// then
assertThat(outcomes)
.extracting(Status::getCode)
.containsExactlyInAnyOrder(
Status.Code.OK, Status.Code.OK, Status.Code.RESOURCE_EXHAUSTED);
.containsExactlyInAnyOrder(Status.Code.OK, Status.Code.OK, Status.Code.UNAVAILABLE);
assertThat(outcomes)
.filteredOn(status -> !status.isOk())
.extracting(Status::getDescription)
.containsExactly(ClientErrorMessages.of(Category.RATE_LIMIT));
.containsExactly(ClientErrorMessages.of(Category.TRANSIENT_DEPENDENCY));
});
}
+2
View File
@@ -27,6 +27,8 @@ Kafka ─▶ platform consumer (starter-kafka)
- `IdempotentConsumer.TransactionRunner`(애플리케이션 `PlatformTransactionManager` 위의
`TransactionTemplate`). inbox 예약과 use case의 JPA 쓰기가 한 트랜잭션에서 함께 커밋되거나 함께
롤백된다. handler가 실패하면 예약도 롤백되어 재전달이 효과를 다시 적용한다.
이 트랜잭션은 30초 상한(`TransactionPort` 쓰기와 같은 값)으로 열린다. handler의 유스케이스 `inWrite`는 이
트랜잭션에 합류해 자기 상한을 쓰지 않으므로, 막힌 문장이나 잠금 대기는 이 상한에서 끊긴다.
- platform starter(`MessagingReliabilityAutoConfiguration`)가 이 두 bean으로 `IdempotentConsumer`를
만든다. platform은 애플리케이션의 datasource·트랜잭션을 스스로 고르지 않는다는 기존 설계를 그대로 둔다.
- 애플리케이션의 handler(`MessageHandler<T>` 구현)는 이 leaf에 둔다. 컨트롤러가 HTTP 요청을 use case
+5 -22
View File
@@ -121,9 +121,6 @@ org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.tomcat.embed:tomcat-embed-core:11.0.27=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apache.tomcat.embed:tomcat-embed-el:11.0.27=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apache.tomcat.embed:tomcat-embed-websocket:11.0.27=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=integrationTestCompileClasspath,testCompileClasspath
org.aspectj:aspectjweaver:1.9.25.1=integrationTestRuntimeClasspath
@@ -192,8 +189,7 @@ org.springframework.boot:spring-boot-data-jpa:4.0.9=integrationTestRuntimeClassp
org.springframework.boot:spring-boot-flyway:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-health:4.0.9=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-hibernate:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-http-converter:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-jackson:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-jackson:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-jdbc:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-jpa:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-micrometer-metrics:4.0.9=integrationTestRuntimeClasspath,testRuntimeClasspath
@@ -202,33 +198,21 @@ org.springframework.boot:spring-boot-micrometer-tracing-opentelemetry:4.0.9=inte
org.springframework.boot:spring-boot-micrometer-tracing:4.0.9=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-opentelemetry:4.0.9=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-persistence:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-resttestclient:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-security:4.0.9=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-servlet:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-sql:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-actuator:4.0.9=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-data-jpa:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-flyway:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-jackson-test:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-jackson:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-jdbc:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-json:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-logging:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-micrometer-metrics:4.0.9=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-security:4.0.9=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-test:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-tomcat-runtime:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-tomcat:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-webmvc-test:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-webmvc:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-test-autoconfigure:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-test:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-tomcat:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-transaction:4.0.9=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-web-server:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-webmvc-test:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-webmvc:4.0.9=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot:4.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.data:spring-data-commons:4.0.8=integrationTestRuntimeClasspath
org.springframework.data:spring-data-jpa:4.0.8=integrationTestRuntimeClasspath
@@ -249,8 +233,7 @@ org.springframework:spring-messaging:7.0.10=integrationTestRuntimeClasspath
org.springframework:spring-orm:7.0.10=integrationTestRuntimeClasspath
org.springframework:spring-test:7.0.10=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-tx:7.0.10=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-web:7.0.10=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-webmvc:7.0.10=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-web:7.0.10=integrationTestRuntimeClasspath,testRuntimeClasspath
org.testcontainers:testcontainers-database-commons:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers-jdbc:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
org.testcontainers:testcontainers-kafka:2.0.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath
@@ -260,7 +243,7 @@ org.xerial.snappy:snappy-java:1.1.10.9=integrationTestRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
org.xmlunit:xmlunit-core:2.10.4=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.yaml:snakeyaml:2.5=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-core:3.1.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-databind:3.1.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson:jackson-bom:3.1.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-core:3.1.7=integrationTestRuntimeClasspath
tools.jackson.core:jackson-databind:3.1.7=integrationTestRuntimeClasspath
tools.jackson:jackson-bom:3.1.7=integrationTestRuntimeClasspath
empty=
@@ -68,12 +68,22 @@ public class MessagingInboxAutoConfiguration {
return new MessagingInboxSchemaStream(dataSource);
}
/**
* The upper bound on one delivery's transaction, in whole seconds: the same 30 s as one {@code
* TransactionPort} write ({@code app.persistence-jpa.transaction.write-timeout}). The handler's
* use case joins this transaction, and a joined {@code inWrite} leaves the deadline to the call
* that began it, so without one here a blocked statement or lock wait held the connection and the
* partition for as long as it lasted (review 2026-11-12).
*/
static final int TRANSACTION_TIMEOUT_SECONDS = 30;
/** Runs the inbox reservation and the handler in one application transaction. */
@Bean
@ConditionalOnMissingBean(IdempotentConsumer.TransactionRunner.class)
public IdempotentConsumer.TransactionRunner messagingInboxTransactions(
PlatformTransactionManager transactionManager) {
TransactionTemplate template = new TransactionTemplate(transactionManager);
template.setTimeout(TRANSACTION_TIMEOUT_SECONDS);
return new IdempotentConsumer.TransactionRunner() {
@Override
public <T> T inTransaction(java.util.function.Supplier<T> work) {
@@ -164,6 +164,25 @@ class MessagingInboxAutoConfigurationTest {
assertThat(transactions.outcomes).containsExactly("commit", "rollback");
}
@Test
@DisplayName("트랜잭션 runner는 TransactionPort 쓰기와 같은 30초 상한으로 트랜잭션을 연다")
void theRunnerOpensItsTransactionWithTheWriteTimeout() {
// given
RecordingTransactions transactions = new RecordingTransactions();
IdempotentConsumer.TransactionRunner runner =
new MessagingInboxAutoConfiguration().messagingInboxTransactions(transactions);
// when
runner.inTransaction(() -> "applied");
// then
assertThat(transactions.timeouts)
.as(
"the handler's use case joins this transaction, and a joined inWrite leaves the deadline"
+ " to the call that began it")
.containsExactly(30);
}
@Test
@DisplayName("같은 메시지가 두 번 전달돼도 handler의 부작용은 한 번만 일어난다")
void theSameMessageDeliveredTwiceRunsTheSideEffectOnce() {
@@ -232,6 +251,7 @@ class MessagingInboxAutoConfigurationTest {
private static final long serialVersionUID = 1L;
private final transient List<String> outcomes = new ArrayList<>();
private final transient List<Integer> timeouts = new ArrayList<>();
@Override
protected Object doGetTransaction() {
@@ -239,7 +259,9 @@ class MessagingInboxAutoConfigurationTest {
}
@Override
protected void doBegin(Object transaction, TransactionDefinition definition) {}
protected void doBegin(Object transaction, TransactionDefinition definition) {
timeouts.add(definition.getTimeout());
}
@Override
protected void doCommit(DefaultTransactionStatus status) {
+3 -3
View File
@@ -51,14 +51,14 @@ virtual thread 실행기는 `TaskDecorator` bean 을 요구한다(요청 상관
이 leaf 의 예외는 모두 `ApiErrorCarrier` 다. 코드는 `error.WebAdvancedError` 한 enum 이 정하고, web 의
`GlobalExceptionHandler.handleCarrier` 한 분기가 Envelope 로 답한다(별도 `@RestControllerAdvice` 없음).
예전에는 10종 모두 `500 INTERNAL_ERROR` 였다(리뷰 2026-11-01 02-07). 아래 표와 enum 은 같은 값을 말하고,
예전에는 10종 모두 `500 INTERNAL_ERROR` 였다(리뷰 2026-11-01 02-07). admission 거절은 2026-11-12부터 공용 `SERVER_BUSY`다. 아래 표와 enum 은 같은 값을 말하고,
`WebAdvancedErrorMappingTest` 가 실제 응답으로 확인한다.
| 예외 | `error.code` | status | category | retryable | 응답에 더 실리는 것 | 클라이언트 행동 |
| --- | --- | --- | --- | --- | --- | --- |
| `AdmissionRefusedException` | `ADMISSION_REFUSED` | 503 | `TRANSIENT_DEPENDENCY` | true | `Retry-After: 1` | 잠시 뒤 같은 요청 |
| `AdmissionRefusedException` | `SERVER_BUSY`(공용 `OperationalError`) | 503 | `TRANSIENT_DEPENDENCY` | true | `Retry-After: 1` | 잠시 뒤 같은 요청. 서버 포화는 모든 전송이 이 코드 하나다 |
| `JsonPatchTestFailedException` | `PATCH_TEST_FAILED` | 409 | `CONFLICT` | false | `details.pointer`(서버 값은 없음) | 다시 읽고 새 patch |
| `JsonPatchRejectedException` | `PATCH_REJECTED` | 400 | `VALIDATION` | false | — | patch 문서를 고친다 |
| `JsonPatchRejectedException` | `PATCH_REJECTED` | 400 | `VALIDATION` | false | — | patch 문서를 고친다. JSON이 아닌 본문, 빈 문서, 한도·깊이 초과, 연산 모양 오류, 결과가 자원 타입으로 읽히지 않는 patch가 모두 이 코드다 |
| `PatchAuthorizationException` | `PATCH_PATH_FORBIDDEN` | 403 | `AUTHZ` | false | `details.refusedPaths` | 해당 경로를 빼거나 권한 확보 |
| `UnsupportedApiVersionException` | `API_VERSION_UNSUPPORTED` | 404 | `NOT_FOUND` | false | — | 지원 버전 경로로 |
| `SunsetViolationException` | `API_DEPRECATION_INVALID` | 500 | `INTERNAL` | false | — | 서버 설정 결함(등록 시점 오류) |
@@ -15,6 +15,9 @@ plugins {
// Package root `dev.caskeleton.adapter.inbound.web.advanced` — its own package, the same way
// `web-fileserver` owns `web.fileserver`, so no package is split across two jars.
dependencies {
// MockMvc and the web MVC test auto-configuration: this leaf's tests use them, so it declares
// them itself (the spring-library convention adds only spring-boot-starter-test).
testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'
implementation project(':adapter:inbound:web')
implementation project(':application-core')
implementation project(':shared-contract')
@@ -11,16 +11,14 @@ import dev.caskeleton.shared.error.Category;
* leaf README's "오류 응답" section; it states the same values.
*
* <p>Before this existed every one of these reached the client as {@code 500 INTERNAL_ERROR} with
* an ERROR log line, including an admission refusal the profile documents as a 503 (review
* 2026-11-01 02-07).
* an ERROR log line (review 2026-11-01 02-07). The admission refusal it used to name is now the
* shared {@code OperationalError.SERVER_BUSY} (review 2026-11-12).
*
* <p>Like {@code RateLimitTransportError}, these are not in {@code
* docs/registries/error-codes.yaml}, which is the {@code OperationalError} SSOT.
*/
public enum WebAdvancedError implements ApiErrorCode, RetryAfterHint {
/** The virtual-thread admission limit was full. A refusal in a millisecond; come back shortly. */
ADMISSION_REFUSED(Category.TRANSIENT_DEPENDENCY, 503, true, 1),
/** A JSON Patch {@code test} did not hold; nothing was applied. Re-read, then retry. */
PATCH_TEST_FAILED(Category.CONFLICT, 409, false, 0),
/** The patch document is malformed or over a limit; nothing was applied. */
@@ -6,6 +6,10 @@ import dev.caskeleton.adapter.inbound.web.advanced.stream.WebStreamTermination;
import dev.caskeleton.adapter.inbound.web.advanced.stream.encoding.NdjsonRecord;
import dev.caskeleton.adapter.inbound.web.advanced.stream.encoding.StreamFraming;
import dev.caskeleton.adapter.inbound.web.advanced.stream.encoding.StreamRecordEncoder;
import dev.caskeleton.shared.error.ApiErrorCarrier;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.ClientErrorMessages;
import dev.caskeleton.shared.error.OperationalError;
import java.io.IOException;
import java.io.OutputStream;
import java.time.Clock;
@@ -20,6 +24,16 @@ import java.util.Objects;
* terminal record before closing, and classify a write failure rather than letting it become a 500
* on a response that is already 200.
*
* <p>Positions are enforced before each write, by {@code WebStreamEvidence#requireNext}: an item
* whose sequence is not above the previous one is a server fault, and the stream ends with a
* terminal failure record instead of handing the client a repeat or a rewind it would apply.
*
* <p>What this writer does not do: it writes synchronously from an iterator on the request thread,
* so it sends no heartbeat while the source is blocked, enforces no idle timeout or maximum age,
* and keeps no buffer (a slow consumer blocks the source instead). Those bounds are in {@code
* WebStreamPolicy} and the drain in {@code WebStreamDrainCoordinator} for a service that runs its
* streams through {@code WebStreamRegistry}; {@code docs/web/streaming-contract.md} says which.
*
* <p>**Flushing after every record is not optional.** Without it the container buffers, and a
* streaming response that arrives in one chunk at the end is a slow non-streaming response — which
* passes every test that checks the body and fails the only thing the client wanted.
@@ -58,6 +72,10 @@ public final class MvcStreamWriter {
try {
while (records.hasNext()) {
NdjsonRecord<T> record = records.next();
if (record instanceof NdjsonRecord.Item<T> item) {
// WebStreamEvidence owns the rule; asked before the write so the item never leaves.
evidence.requireNext(new StreamSequence(item.sequence()));
}
writeRecord(record, output);
if (record instanceof NdjsonRecord.Item<T> item) {
evidence.recordDelivered(new StreamSequence(item.sequence()));
@@ -91,13 +109,17 @@ public final class MvcStreamWriter {
}
// Otherwise the source failed after commit. The status is already 200, so the failure goes
// into the stream as a terminal record — and if even that cannot be written, it is an abrupt
// close and is recorded as one rather than counted as a completion.
// close and is recorded as one rather than counted as a completion. The record carries the
// failure's own code when it has one (a carrier anywhere in the cause chain, such as
// STREAM_ITEM_TOO_LARGE), else the registered INTERNAL_ERROR, and the category's fixed message:
// the same code and wording a client would have read before commit.
ApiErrorCode code =
ApiErrorCarrier.firstIn(failure)
.map(carrier -> ((ApiErrorCarrier) carrier).errorCode())
.orElse(OperationalError.INTERNAL_ERROR);
try {
writeRecord(
new NdjsonRecord.Failure<T>(
lastSequence,
"DEPENDENCY_FAILURE",
"the stream ended early because a dependency failed"),
new NdjsonRecord.Failure<T>(lastSequence, code.code(), ClientErrorMessages.of(code)),
output);
evidence.recordTermination(WebStreamTermination.TERMINAL_ERROR_RECORD, clock.instant());
return WebStreamTermination.TERMINAL_ERROR_RECORD;
@@ -0,0 +1,119 @@
package dev.caskeleton.adapter.inbound.web.advanced.mvc;
import dev.caskeleton.adapter.inbound.web.advanced.virtualthread.AdmissionRefusedException;
import dev.caskeleton.adapter.inbound.web.advanced.virtualthread.VirtualThreadAdmissionGuard;
import dev.caskeleton.adapter.inbound.web.error.EnvelopeResponseWriter;
import dev.caskeleton.adapter.inbound.web.http.ApiHeaders;
import dev.caskeleton.adapter.inbound.web.observability.RetryAfterAdvisor;
import jakarta.servlet.AsyncEvent;
import jakarta.servlet.AsyncListener;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Objects;
import org.springframework.core.Ordered;
import org.springframework.web.filter.OncePerRequestFilter;
import tools.jackson.databind.ObjectMapper;
/**
* Puts every request under the virtual-thread admission limit.
*
* <p>The guard alone was a bean nothing called: the profile promised a {@code 503} with {@code
* Retry-After} past the limit, and a deployment that switched it on admitted every arrival (review
* 2026-11-12). A filter, not an interceptor, so the limit covers the handler and its async work;
* ordered after the security chain (see {@link #ORDER}).
*
* <p>A request that goes async keeps its permit until the async work ends: releasing when this
* thread returns would bound only the hand-off, and the work the limit protects the downstream
* pools from happens after it.
*/
public final class VirtualThreadAdmissionFilter extends OncePerRequestFilter implements Ordered {
/**
* Right after the Spring Security filter chain (Boot's {@code SecurityProperties
* .DEFAULT_FILTER_ORDER}, -100). Two reasons. The chain applies CORS, so a cross-origin refusal
* carries {@code Access-Control-Allow-Origin} and the browser can read its 503 and {@code
* Retry-After}; in front of the chain it reached the page as a network error. And a request the
* chain refuses (unauthenticated, forbidden) never takes a permit from the admitted ones (review
* 2026-11-12).
*/
public static final int ORDER = -99;
private final VirtualThreadAdmissionGuard guard;
private final ObjectMapper objectMapper;
public VirtualThreadAdmissionFilter(
VirtualThreadAdmissionGuard guard, ObjectMapper objectMapper) {
this.guard = Objects.requireNonNull(guard, "guard");
this.objectMapper = Objects.requireNonNull(objectMapper, "objectMapper");
}
@Override
public int getOrder() {
return ORDER;
}
@Override
protected void doFilterInternal(
HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws ServletException, IOException {
VirtualThreadAdmissionGuard.Permit permit;
try {
permit = guard.enter();
} catch (AdmissionRefusedException refused) {
RetryAfterAdvisor.retryAfterSeconds(refused.errorCode())
.ifPresent(
seconds -> response.setHeader(ApiHeaders.RETRY_AFTER, Integer.toString(seconds)));
EnvelopeResponseWriter.write(response, refused.errorCode(), objectMapper);
return;
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new ServletException("interrupted while waiting for admission", interrupted);
}
boolean handedToAsync = false;
try {
chain.doFilter(request, response);
if (request.isAsyncStarted()) {
request.getAsyncContext().addListener(new ReleaseWhenDone(permit));
handedToAsync = true;
}
} finally {
if (!handedToAsync) {
permit.close();
}
}
}
/** Releases the permit when the async request ends, however it ends. */
private static final class ReleaseWhenDone implements AsyncListener {
private final VirtualThreadAdmissionGuard.Permit permit;
ReleaseWhenDone(VirtualThreadAdmissionGuard.Permit permit) {
this.permit = permit;
}
@Override
public void onComplete(AsyncEvent event) {
permit.close();
}
@Override
public void onTimeout(AsyncEvent event) {
permit.close();
}
@Override
public void onError(AsyncEvent event) {
permit.close();
}
@Override
public void onStartAsync(AsyncEvent event) {
// A restarted async cycle drops the listeners of the previous one.
event.getAsyncContext().addListener(this);
}
}
}
@@ -13,6 +13,7 @@ import org.springframework.context.annotation.Bean;
import org.springframework.core.task.AsyncTaskExecutor;
import org.springframework.core.task.TaskDecorator;
import org.springframework.core.task.support.TaskExecutorAdapter;
import tools.jackson.databind.ObjectMapper;
/**
* Wires the virtual-thread executor and, in the same configuration, the admission limit.
@@ -57,6 +58,17 @@ public class VirtualThreadMvcConfiguration {
properties.getAdmissionLimit(), properties.getAdmissionWait());
}
/**
* The request path through the guard: without this the guard is a bean nothing calls, and the
* profile admits every arrival while promising a 503 past the limit.
*/
@Bean
@ConditionalOnMissingBean
public VirtualThreadAdmissionFilter virtualThreadAdmissionFilter(
VirtualThreadAdmissionGuard guard, ObjectMapper objectMapper) {
return new VirtualThreadAdmissionFilter(guard, objectMapper);
}
/**
* The executor Spring MVC dispatches async request handling onto.
*
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.advanced.patch;
import jakarta.validation.Validator;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
@@ -23,14 +24,19 @@ import tools.jackson.databind.node.ObjectNode;
public final class JsonMergePatchApplier {
private final ObjectMapper mapper;
private final Validator validator;
private final PatchFieldAuthorization authorization;
/**
* @param mapper the service's JSON mapper (Boot's {@code JsonMapper} bean)
* @param authorization which fields may be modified
* @param validator the service's Bean Validation validator (Boot's {@code Validator} bean); the
* patched document is validated whole before it is returned
*/
public JsonMergePatchApplier(ObjectMapper mapper, PatchFieldAuthorization authorization) {
public JsonMergePatchApplier(
ObjectMapper mapper, PatchFieldAuthorization authorization, Validator validator) {
this.mapper = Objects.requireNonNull(mapper, "mapper");
this.validator = Objects.requireNonNull(validator, "validator");
this.authorization = Objects.requireNonNull(authorization, "authorization");
}
@@ -52,7 +58,8 @@ public final class JsonMergePatchApplier {
authorization.validate(patch.fieldNames());
JsonNode before = mapper.valueToTree(current);
if (!before.isObject()) {
throw new IllegalArgumentException("a merge patch target must serialize to a JSON object");
// The target type is the server's choice, so this is a server fault, not a bad request.
throw new IllegalStateException("a merge patch target must serialize to a JSON object");
}
ObjectNode after = merge((ObjectNode) before.deepCopy(), patch.root());
List<String> modified = new ArrayList<>();
@@ -63,7 +70,7 @@ public final class JsonMergePatchApplier {
modified.add(field);
}
}
return new PatchResult<>(mapper.treeToValue(after, type), modified);
return new PatchResult<>(PatchBodies.toTarget(mapper, validator, after, type), modified);
}
private static ObjectNode merge(ObjectNode target, ObjectNode patch) {
@@ -25,7 +25,7 @@ public record JsonMergePatchDocument(ObjectNode root) {
Objects.requireNonNull(root, "root");
int depth = depthOf(root, 1);
if (depth > MAX_DEPTH) {
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
"a merge patch nested "
+ depth
+ " deep exceeds the "
@@ -56,17 +56,17 @@ public record JsonMergePatchDocument(ObjectNode root) {
*
* @param mapper the service's JSON mapper (Boot's {@code JsonMapper} bean)
* @param body the request body
* @throws IllegalArgumentException if the body is not a JSON object
* @throws JsonPatchRejectedException if the body is not JSON or not a JSON object
*/
public static JsonMergePatchDocument parse(ObjectMapper mapper, byte[] body) {
Objects.requireNonNull(mapper, "mapper");
Objects.requireNonNull(body, "body");
JsonNode parsed = mapper.readTree(body);
JsonNode parsed = PatchBodies.readTree(mapper, body);
if (!parsed.isObject()) {
// RFC 7396 permits a scalar or an array as a whole-document replacement. Refused here: a
// merge patch that replaces the entire resource is a PUT, and routing it through the patch
// path skips the full-document validation a PUT gets.
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
"a merge patch must be a JSON object; a scalar or array patch replaces the whole "
+ "resource, which is a PUT and belongs on the PUT route with its validation");
}
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.advanced.patch;
import jakarta.validation.Validator;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
@@ -27,14 +28,19 @@ import tools.jackson.databind.node.ObjectNode;
public final class JsonPatchApplier {
private final ObjectMapper mapper;
private final Validator validator;
private final JsonPointerAuthorization authorization;
/**
* @param mapper the service's JSON mapper (Boot's {@code JsonMapper} bean)
* @param authorization which pointers may be modified
* @param validator the service's Bean Validation validator (Boot's {@code Validator} bean); the
* patched document is validated whole before it is returned
*/
public JsonPatchApplier(ObjectMapper mapper, JsonPointerAuthorization authorization) {
public JsonPatchApplier(
ObjectMapper mapper, JsonPointerAuthorization authorization, Validator validator) {
this.mapper = Objects.requireNonNull(mapper, "mapper");
this.validator = Objects.requireNonNull(validator, "validator");
this.authorization = Objects.requireNonNull(authorization, "authorization");
}
@@ -61,9 +67,9 @@ public final class JsonPatchApplier {
}
}
if (working.equals(before)) {
return new PatchResult<>(mapper.treeToValue(working, type), List.of());
return new PatchResult<>(PatchBodies.toTarget(mapper, validator, working, type), List.of());
}
return new PatchResult<>(mapper.treeToValue(working, type), touched);
return new PatchResult<>(PatchBodies.toTarget(mapper, validator, working, type), touched);
}
private JsonNode applyOne(JsonNode root, JsonPatchOperation operation) {
@@ -24,7 +24,7 @@ public record JsonPatchDocument(List<JsonPatchOperation> operations) {
public JsonPatchDocument {
operations = List.copyOf(Objects.requireNonNull(operations, "operations"));
if (operations.isEmpty()) {
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
"an empty patch document changes nothing; sending one is a client bug and answering 200 "
+ "hides it");
}
@@ -43,11 +43,12 @@ public record JsonPatchDocument(List<JsonPatchOperation> operations) {
*
* @param mapper the service's JSON mapper (Boot's {@code JsonMapper} bean)
* @param body the request body
* @throws JsonPatchRejectedException if the body is not JSON or not a valid patch document
*/
public static JsonPatchDocument parse(ObjectMapper mapper, byte[] body) {
Objects.requireNonNull(mapper, "mapper");
Objects.requireNonNull(body, "body");
JsonNode root = mapper.readTree(body);
JsonNode root = PatchBodies.readTree(mapper, body);
if (!root.isArray()) {
throw new JsonPatchRejectedException(
"an RFC 6902 patch is an array of operations; an object here is a merge patch sent to "
@@ -26,22 +26,22 @@ public record JsonPatchOperation(
Objects.requireNonNull(value, "value");
Objects.requireNonNull(from, "from");
if (!path.isEmpty() && !path.startsWith("/")) {
throw new IllegalArgumentException("a JSON Pointer is empty or starts with '/': " + path);
throw new JsonPatchRejectedException("a JSON Pointer is empty or starts with '/': " + path);
}
if (kind.requiresValue() != value.isPresent()) {
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
kind.wireName()
+ (kind.requiresValue()
? " requires a value member"
: " carries no value member, and one here means the client meant a different op"));
}
if (kind.requiresFrom() != from.isPresent()) {
throw new IllegalArgumentException(
throw new JsonPatchRejectedException(
kind.wireName()
+ (kind.requiresFrom() ? " requires a from member" : " carries no from member"));
}
if (from.isPresent() && !from.get().isEmpty() && !from.get().startsWith("/")) {
throw new IllegalArgumentException("a JSON Pointer is empty or starts with '/'");
throw new JsonPatchRejectedException("a JSON Pointer is empty or starts with '/'");
}
if (kind == JsonPatchOperationKind.MOVE
&& from.isPresent()
@@ -49,7 +49,7 @@ public record JsonPatchOperation(
// RFC 6902 section 4.4: the target cannot be inside the source. Moving a subtree into itself
// is not a thing that has a result, and an implementation that tries produces either an
// infinite structure or a silently truncated one.
throw new IllegalArgumentException("a move cannot target a location inside its own source");
throw new JsonPatchRejectedException("a move cannot target a location inside its own source");
}
}
@@ -66,10 +66,21 @@ public final class JsonPointerAuthorization {
/**
* Check every pointer a document names, including {@code from} pointers.
*
* @throws PatchAuthorizationException naming all of them
* @throws JsonPatchRejectedException if a pointer is deeper than {@link #MAX_POINTER_DEPTH}: a
* malformed document, not a permission question
* @throws PatchAuthorizationException naming every pointer the caller may not modify
*/
public void validate(List<JsonPatchOperation> operations) {
Objects.requireNonNull(operations, "operations");
for (JsonPatchOperation operation : operations) {
boolean tooDeep =
depthOf(operation.path()) > MAX_POINTER_DEPTH
|| operation.from().filter(from -> depthOf(from) > MAX_POINTER_DEPTH).isPresent();
if (tooDeep) {
throw new JsonPatchRejectedException(
"a JSON Pointer deeper than " + MAX_POINTER_DEPTH + " segments is over the limit");
}
}
List<String> refused = new ArrayList<>();
for (JsonPatchOperation operation : operations) {
if (operation.kind().mutating() && !writable(operation.path())) {
@@ -0,0 +1,55 @@
package dev.caskeleton.adapter.inbound.web.advanced.patch;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import jakarta.validation.Validator;
import java.util.Set;
import tools.jackson.core.JacksonException;
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;
/**
* The two places a patch meets Jackson, answered as the patch's fault rather than the server's.
*
* <p>A body that is not JSON, and a patched tree that no longer reads as the target type (a string
* where a number was), are both the client's document. Left to Jackson they reached the web
* adapter's catch-all as {@code 500 INTERNAL_ERROR}; here they are {@code 400 PATCH_REJECTED} like
* every other patch the server will not apply (review 2026-11-12).
*/
final class PatchBodies {
private PatchBodies() {}
static JsonNode readTree(ObjectMapper mapper, byte[] body) {
try {
return mapper.readTree(body);
} catch (JacksonException notJson) {
throw new JsonPatchRejectedException("the patch body is not a JSON document");
}
}
/**
* The patched tree as the target type, validated as a whole document.
*
* <p>Whole, not field by field: two fields whose values must agree are invisible to a check of
* the changed fields alone. {@code T} is the web representation DTO, whose constraints are
* request syntax (web AGENTS B4·C1); business rules such as allowed state transitions belong to
* the use case the caller hands the result to as a command. A violation is the same {@link
* ConstraintViolationException} a {@code @Valid} body raises, so the client gets {@code 400
* VALIDATION_FAILED} with the per-field details it already knows.
*/
static <T> T toTarget(ObjectMapper mapper, Validator validator, JsonNode patched, Class<T> type) {
T result;
try {
result = mapper.treeToValue(patched, type);
} catch (JacksonException wrongShape) {
throw new JsonPatchRejectedException(
"the patched document no longer reads as the resource: a value has the wrong type");
}
Set<ConstraintViolation<T>> violations = validator.validate(result);
if (!violations.isEmpty()) {
throw new ConstraintViolationException(violations);
}
return result;
}
}

Some files were not shown because too many files have changed in this diff Show More