fix!: 성숙도 리뷰의 High·P1 결함 19건을 고친다

문제: 2026-11-01 성숙도 리뷰에서 High 21건·P1 25건이 나왔다. 결과를
모르는 일을 "확실함"으로 기록했다(발송 중 죽은 알림 재발송, 커밋 중
끊긴 쓰기를 재시도 가능으로 응답, 재시도 가능한 거부를 DEAD로). 중복을
DB가 아니라 코드 순서로 막았다(정산 job, 포스터 제목). 짝 프론트와
wire 계약이 달랐고(처리 중 409, Envelope null), JWT audience 검증이
기본으로 꺼져 있었고, 트레이스가 나가지 않았고, CI가 strict lane 14개를
한 번도 돌리지 않았다.

방법: 발견마다 실패하는 테스트를 먼저 쓰고 고쳤다. 주요 선택:
- 알림 attempt는 처음부터 "시작 여부 모름"으로 쓴다(호출 직전 갱신은
  쓰기가 하나 늘어 버림).
- 정산 job claim은 lease·fence를 갱신하는 UPDATE 한 문장(처리 전체를
  트랜잭션으로 감싸는 안은 외부 호출 동안 잠금을 잡아 버림).
- 커밋 단계 연결 끊김은 DB_COMPLETION_UNKNOWN(재시도 불가).
- 처리 중 409는 retryable=true + Retry-After: 2, Envelope null 필드는
  web Jackson mixin으로 생략(shared-contract는 stdlib only).
- 트레이싱은 자체 Tracer를 지우고 Boot 4 tracing·OTLP로.
- strict lane을 단계에 연결하고 verifyStrictLaneStages가 고아를 막는다.
발견별 RED·GREEN·버린 대안은 리뷰 README 13절 표에 있다.

위험·한계: JWT 모드는 APP_SECURITY_JWT_AUDIENCE가 없으면 기동하지
않는다. 짝 프론트는 409 retryable과 Envelope 키 규칙을 맞춰야 한다.
이 커밋 시점에는 MinIO 공식 이미지가 사라져 MinIO 2 lane이 실패한다
(다음 커밋에서 대체 이미지로 해결).

검증: ci 통과. mainCheck·integrationCheck는 MinIO 2 lane만 실패(이미지
pull 거부). -p optional-platforms ci integrationCheck, performanceCheck,
releaseCheck(-PgitRevision) 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 2·13절
BREAKING CHANGE: JWT 모드에서 APP_SECURITY_JWT_AUDIENCE가 필수가 되고 role은
audience client와 realm 것만 읽는다. IDEMPOTENT_IN_FLIGHT가 retryable=true,
Retry-After: 2로 바뀌고 Envelope는 null 필드를 보내지 않는다.
This commit is contained in:
DongHyeonka
2026-11-03 19:52:06 +09:00
parent 01a8a2a70f
commit 34565130e0
253 changed files with 13849 additions and 1140 deletions
+3 -2
View File
@@ -60,7 +60,7 @@ configurations, Redis as one 376-line class.
capability is a commented `runtimeOnly` line in `build.gradle`; the default composition is web,
observability, the cores, support and identifier. This leaf keeps no list of capabilities: no
switch registry, no cross-capability dependency validator, no activation endpoint. Component scan
covers `dev.caskeleton.bootstrap` only; web (`WebAdapterAutoConfiguration`, `WebSecurityAutoConfiguration`) and support
covers `dev.caskeleton.bootstrap` only; web (`WebAdapterAutoConfiguration`, `WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`) and support
(`OutboundSupportConfig`) arrive through their own `AutoConfiguration.imports`. What stays in `autoconfigure/<name>/` is application
composition over application-core ports that names no module type: `operation` (the durable
operation use cases and their `/operations` endpoints, on only when the operation store and the
@@ -83,7 +83,8 @@ configurations, Redis as one 376-line class.
`ReadinessGroup`, `RuntimeWarnings`), so capability modules fail the same way without depending on
this leaf. `runtime/startup/` keeps only `StartupFailureExceptionReporter`.
- **An environment-only guard is a `StartupRule` bean** (`support.startup`): it returns violations,
and the one `StartupRuleRunner` raises them. A guard that needs another bean stays a bean. A
and the one `StartupRuleRunner` raises them before any other singleton exists (declare it with a
parameterless `static` `@Bean` method). A guard that needs another bean stays a bean. A
capability's production secrets are the capability's: its module contributes a
`RequiredProductionSecrets` bean, and `SecretSourceValidator` checks the names without knowing
which roles exist.
+5 -3
View File
@@ -21,7 +21,7 @@ WebSocket, gRPC, 파일 서버, 알림)는 `build.gradle`에 주석 처리된 `r
있다. 주석을 풀면 그 모듈이 자기 `AutoConfiguration.imports`와 설정 기본값으로 켜지고, 줄을 지우면 함께
사라진다. 있는 모듈은 자기 `enabled` 키(기본 `true`)를 `false`로 줄 때만 꺼진다. 합성 루트는 capability
목록을 따로 들고 있지 않다(스위치 목록, scan 제외 정규식, 의존 검사기 없음). component scan은
`dev.caskeleton.bootstrap`만 보고, web(`WebAdapterAutoConfiguration`·`WebSecurityAutoConfiguration`)과 support(`OutboundSupportConfig`)도
`dev.caskeleton.bootstrap`만 보고, web(`WebAdapterAutoConfiguration`·`WebSecurityAutoConfiguration`·`WebMethodSecurityAutoConfiguration`)과 support(`OutboundSupportConfig`)도
자기 auto-configuration으로 들어온다.
- 줄마다 필요한 env와 끄는 키: [src/README.md](../README.md)의 "기능 추가 = 한 줄 + env" 표.
@@ -156,8 +156,10 @@ README의 "startup" 절에 있다.
환경만 읽는 검사(`RuntimeNumericBoundsValidator`, `ErrorDetailExposureSafetyValidator`와
persistence-jpa의 datasource·Flyway·OSIV·TLS·vendor·Hikari 검사)는 `StartupRule`이다: 위반 목록만
돌려주고, `adapter:outbound:support`의 `StartupRuleRunner` 하나가 모든 싱글톤 생성 후 규칙마다 그
phase의 종료 코드로 실패시킨다. 다른 bean이 필요한 검사(`SecretSourceValidator`의 `SecretSourcePort`,
돌려주고, `adapter:outbound:support`의 `StartupRuleRunner` 하나가 다른 싱글톤을 만들기 전에(bean factory
post-processor 단계) 규칙마다 그 phase의 종료 코드로 실패시킨다. 그래서 prod 금지 값은 DataSource가
연결을 열거나 Flyway가 마이그레이션하기 전에 거부된다. 규칙은 그만큼 일찍 만들어지므로 매개변수 없는
`static` `@Bean` 메서드로 선언한다. 다른 bean이 필요한 검사(`SecretSourceValidator`의 `SecretSourcePort`,
`StartupSafetyValidator`의 bean factory, persistence-jpa의 datasource 검사)는 계속 bean이고, 부팅 전에
돌아야 하는 profile 규칙(`RuntimeEnvironmentProfileValidator`)은 `EnvironmentPostProcessor`로 남는다.
+2 -2
View File
@@ -218,9 +218,9 @@ dependencies {
// Micrometer core for the bootstrap meters (no-op without a MeterRegistry). See README.
implementation 'io.micrometer:micrometer-core'
// OTel/Micrometer tracer runtime (exporter stays off until an OTLP endpoint is set). See README.
// The Micrometer Tracing API the tracing contract tests name. The tracer runtime itself — Boot's
// tracing auto-configuration and the OTLP exporter — is composition:service-runtime's.
implementation 'io.micrometer:micrometer-tracing-bridge-otel'
implementation 'io.opentelemetry:opentelemetry-exporter-otlp'
// Actuator + Prometheus registry (health/info/prometheus/loggers endpoints).
implementation 'org.springframework.boot:spring-boot-starter-actuator'
+4 -1
View File
@@ -133,7 +133,7 @@ io.opentelemetry:opentelemetry-common:1.55.0=architectureTestCompileClasspath,ar
io.opentelemetry:opentelemetry-context:1.55.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,bootRunH2Classpath,compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-exporter-common:1.55.0=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-exporter-otlp-common:1.55.0=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-exporter-otlp:1.55.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,bootRunH2Classpath,compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-exporter-otlp:1.55.0=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-exporter-sender-okhttp:1.55.0=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-extension-trace-propagators:1.55.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,bootRunH2Classpath,compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-sdk-common:1.55.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,bootRunH2Classpath,compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
@@ -297,7 +297,10 @@ org.springframework.boot:spring-boot-jpa:4.0.8=architectureTestCompileClasspath,
org.springframework.boot:spring-boot-mail:4.0.8=architectureTestRuntimeClasspath,qualificationRuntimeClasspath
org.springframework.boot:spring-boot-micrometer-metrics:4.0.8=architectureTestCompileClasspath,architectureTestRuntimeClasspath,bootRunH2Classpath,compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-micrometer-observation:4.0.8=architectureTestCompileClasspath,architectureTestRuntimeClasspath,bootRunH2Classpath,compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-micrometer-tracing-opentelemetry:4.0.8=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-micrometer-tracing:4.0.8=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-mongodb:4.0.8=architectureTestRuntimeClasspath,qualificationRuntimeClasspath
org.springframework.boot:spring-boot-opentelemetry:4.0.8=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,productionRuntimeClasspath,qualificationRuntimeClasspath,runtimeClasspath,systemTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-persistence:4.0.8=architectureTestCompileClasspath,architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,qualificationRuntimeClasspath,systemTestCompileClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-reactor:4.0.8=architectureTestRuntimeClasspath,conditionalTransportBuildContractTestRuntimeClasspath,qualificationRuntimeClasspath
org.springframework.boot:spring-boot-resttestclient:4.0.8=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,testCompileClasspath,testRuntimeClasspath
@@ -95,6 +95,11 @@ class JpaProductionArchitectureTest {
JpaArchitectureRules.noGenericRepository().check(productionClasses);
}
@Test
void everyProductionAssociationIsMappedFromOneSideOnly() {
JpaArchitectureRules.associationsAreMappedFromOneSideOnly().check(productionClasses);
}
@Test
@DisplayName("no entity uses two audit mechanisms at once")
void noEntityUsesTwoAuditMechanismsAtOnce() {
@@ -20,12 +20,12 @@ public class RuntimeSafetyConfig {
}
@Bean
RuntimeNumericBoundsValidator runtimeNumericBoundsValidator() {
static RuntimeNumericBoundsValidator runtimeNumericBoundsValidator() {
return new RuntimeNumericBoundsValidator();
}
@Bean
ErrorDetailExposureSafetyValidator errorDetailExposureSafetyValidator() {
static ErrorDetailExposureSafetyValidator errorDetailExposureSafetyValidator() {
return new ErrorDetailExposureSafetyValidator();
}
}
@@ -42,7 +42,8 @@ spring:
# OIDC issuer (e.g., Keycloak realm URL). Spring Boot resolves JWKS from
# /.well-known/openid-configuration at this URI.
issuer-uri: ${APP_SECURITY_JWT_ISSUER}
# validated against the JWT `aud` claim; blank disables the check
# Spring's own decoder is replaced by JwtDecoderConfig, which validates `aud` against
# app.security.audience (required in jwt mode; blank refuses startup)
audiences: ${APP_SECURITY_JWT_AUDIENCE}
main:
# off | console | log
@@ -151,11 +151,11 @@ app:
# sentinel; prod MUST supply a real secret-manager value.
pseudonymization-salt: ${APP_PRIVACY_PSEUDONYMIZATION_SALT:}
# feature-distributed-tracing-contract D1/D4/D6 — tracing seam settings.
# The OTel/Micrometer tracer runtime is active in this repo (Plan A — seam activated):
# micrometer-tracing-bridge-otel + opentelemetry-exporter-otlp are wired in
# app-bootstrap/build.gradle. The exporter remains off while OTEL_EXPORTER_OTLP_ENDPOINT
# is blank (url_or_empty default). A fork can supply the endpoint via env or override
# SpanErrorRecorder with its own bean.
# The tracer is Spring Boot's (spring-boot-micrometer-tracing-opentelemetry, carried by
# composition:service-runtime): each HTTP request is a span. TracingEnvironmentPostProcessor
# translates these keys into Boot's: OTEL_EXPORTER_OTLP_ENDPOINT is the OTLP base address and
# spans go to <endpoint>/v1/traces over HTTP; blank = no exporter bean at all.
# enabled=false removes Boot's tracing auto-configuration (no Tracer bean).
# D4 disabled-fallback: even when enabled=false, WebMvcRequestIdFilter always
# generates a W3C traceparent so meta.traceId and log trace_id are never null.
# D6 per-runtime defaults: prod=0.01 / dev·local=1.0 (RuntimeEnvironment SSOT).
@@ -8,7 +8,8 @@ app:
auth-mode: ${APP_SECURITY_AUTH_MODE:jwt}
# Required only in jwt mode.
issuer-uri: ${APP_SECURITY_JWT_ISSUER}
# blank to skip audience check
# Required in jwt mode; blank refuses startup. Comma-separated client ids: a token passes when
# its `aud` names any of them, and only these clients' resource_access roles are read.
audience: ${APP_SECURITY_JWT_AUDIENCE}
# comma-separated list (Spring binds to List<String>)
#
@@ -0,0 +1,162 @@
package dev.caskeleton.bootstrap.composition;
import static org.assertj.core.api.Assertions.assertThat;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.InputStream;
import java.net.InetAddress;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.HexFormat;
import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Stream;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.boot.WebApplicationType;
import org.springframework.context.ConfigurableApplicationContext;
/**
* The shipped composition exports the spans of an HTTP request to the OTLP endpoint an operator
* names, and exports nothing when none is named.
*
* <p>The receiver is a plain HTTP server in this JVM standing in for an OpenTelemetry collector. It
* records what arrives at the OTLP/HTTP trace path; the request's trace id is looked for in those
* bytes, because OTLP/protobuf carries a trace id as its 16 raw bytes. Finding it proves three
* things at once: a span was made, it was exported to the configured address, and it belongs to the
* trace the response and the access log name.
*/
class TracingExportSystemTest {
private static final String TRACES_PATH = "/v1/traces";
private static final Pattern META_TRACE_ID =
Pattern.compile("\"traceId\"\\s*:\\s*\"([0-9a-f]{32})\"");
private final List<byte[]> receivedTraceExports = new CopyOnWriteArrayList<>();
private HttpServer collector;
@BeforeEach
void startCollector() throws IOException {
collector = HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), 0), 0);
collector.createContext(
TRACES_PATH,
exchange -> {
try (InputStream body = exchange.getRequestBody()) {
receivedTraceExports.add(body.readAllBytes());
}
exchange.sendResponseHeaders(200, -1);
exchange.close();
});
collector.start();
}
@AfterEach
void stopCollector() {
collector.stop(0);
}
@Test
@DisplayName("OTLP endpoint를 주면 HTTP 요청의 span이 그 주소로 나가고 trace id가 응답 meta와 같다")
void aRequestSpanIsExportedToTheConfiguredEndpointUnderTheResponseTraceId() throws Exception {
// given
String endpoint = "http://127.0.0.1:" + collector.getAddress().getPort();
String metaTraceId;
String traceparent;
try (ConfigurableApplicationContext context =
start("--OTEL_EXPORTER_OTLP_ENDPOINT=" + endpoint)) {
// when
HttpResponse<String> response = get(context, "/api/tracing-probe");
metaTraceId = metaTraceId(response.body());
traceparent = response.headers().firstValue("traceparent").orElseThrow();
assertThat(beanNamesOfType(context, "io.opentelemetry.sdk.trace.export.SpanExporter"))
.isNotEmpty();
} // closing the context shuts the tracer provider down, which flushes the batch
// then
assertThat(traceparent).contains(metaTraceId);
byte[] traceIdBytes = HexFormat.of().parseHex(metaTraceId);
assertThat(receivedTraceExports)
.as("an OTLP trace export reached %s%s", endpoint, TRACES_PATH)
.isNotEmpty()
.anySatisfy(body -> assertThat(indexOf(body, traceIdBytes)).isNotNegative());
}
@Test
@DisplayName("OTLP endpoint가 비어 있으면 span exporter 없이 기동하고 아무것도 내보내지 않는다")
void withoutAnEndpointNothingIsExported() throws Exception {
// given
try (ConfigurableApplicationContext context = start("--OTEL_EXPORTER_OTLP_ENDPOINT=")) {
// when
get(context, "/api/tracing-probe");
// then
assertThat(beanNamesOfType(context, "io.opentelemetry.sdk.trace.export.SpanExporter"))
.isEmpty();
}
assertThat(receivedTraceExports).isEmpty();
}
private static ConfigurableApplicationContext start(String... extra) {
String[] arguments =
Stream.of(
ShippedCompositionHarness.requiredOperatorInputs(),
ShippedCompositionHarness.allOffExcept("--app.tracing.enabled=true"),
new String[] {"--server.port=0", "--management.server.port=0"},
extra)
.flatMap(Arrays::stream)
.toArray(String[]::new);
return ShippedCompositionHarness.shippedComposition("local")
.web(WebApplicationType.SERVLET)
.run(arguments);
}
private static HttpResponse<String> get(ConfigurableApplicationContext context, String path)
throws IOException, InterruptedException {
String port = context.getEnvironment().getRequiredProperty("local.server.port");
try (HttpClient client = HttpClient.newHttpClient()) {
return client.send(
HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + path)).GET().build(),
HttpResponse.BodyHandlers.ofString());
}
}
private static String metaTraceId(String body) {
Matcher matcher = META_TRACE_ID.matcher(body);
assertThat(matcher.find()).as("response envelope carries meta.traceId: %s", body).isTrue();
return matcher.group(1);
}
private static List<String> beanNamesOfType(ConfigurableApplicationContext context, String type) {
ClassLoader loader = context.getClassLoader();
try {
return List.of(context.getBeanNamesForType(Class.forName(type, false, loader)));
} catch (ClassNotFoundException absent) {
return List.of();
}
}
private static int indexOf(byte[] haystack, byte[] needle) {
outer:
for (int i = 0; i + needle.length <= haystack.length; i++) {
for (int j = 0; j < needle.length; j++) {
if (haystack[i + j] != needle[j]) {
continue outer;
}
}
return i;
}
return -1;
}
}
@@ -44,8 +44,6 @@ import org.springframework.context.annotation.Import;
"app.tracing.enabled=true",
"app.tracing.sample-rate=",
"app.tracing.exporter.otlp-endpoint=",
// Spring Boot management.tracing: enable for this slice
"management.tracing.enabled=true",
"spring.application.name=tracing-test"
})
class TracingActivationContextTest {
@@ -62,7 +60,7 @@ class TracingActivationContextTest {
@Test
void tracerBeanIsPresent() {
// Tracer bean provided by micrometer-tracing-bridge-otel autoconfiguration
// Tracer bean provided by Boot's OpenTelemetry tracing auto-configuration
assertThat(context.getBean(Tracer.class))
.as("Tracer bean must be present after adding micrometer-tracing-bridge-otel")
.isNotNull();
@@ -83,7 +81,7 @@ class TracingActivationContextTest {
@Test
void contextLoadsWithBlankExporterEndpoint() {
// Validates that blank OTEL_EXPORTER_OTLP_ENDPOINT does not cause startup failure.
// The OTel exporter autoconfiguration silently disables the exporter when endpoint is blank.
// A blank endpoint never reaches Boot's exporter key, so no exporter is created.
assertThat(context).isNotNull();
}