Merge remote-tracking branch 'origin/claude/t3-error-codes-loglevel-fcf427' into claude/integration-r7
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
# Registry: Error Codes
|
||||
# Schema owner: feature-contract-registry-governance
|
||||
# Category enum owner: feature-operational-error-observability-foundation
|
||||
# Last updated: 2026-09-28
|
||||
# Last updated: 2026-11-06
|
||||
# Scope: skeleton-wide OperationalError SSOT. Product/fork ApiErrorCode enums own local registries/contracts.
|
||||
#
|
||||
# Schema (per row):
|
||||
@@ -15,7 +15,6 @@
|
||||
# owner_layer: presentation | application | domain | infrastructure | crosscut
|
||||
# client_safe_message: = shared-contract ClientErrorMessages.of(category) — category별 한국어 문구 표
|
||||
# 하나(소유자 결정 11). no token / no principal raw / no internal path / no stack trace
|
||||
# log_level: ERROR | WARN | INFO
|
||||
# runbook_link: runbook://area/scenario OR null (client-error만 null 허용)
|
||||
# compatibility_impact: none | additive | behavior-change | breaking
|
||||
# required_test: owning contract test identifier
|
||||
@@ -25,6 +24,13 @@
|
||||
# TRANSIENT_DEPENDENCY, PERMANENT_DEPENDENCY} ⇒ runbook_link 필수.
|
||||
# VALIDATION/NOT_FOUND/CONFLICT/DATA_INTEGRITY는 client-error로 runbook 면제 가능.
|
||||
# retryable=true 인 모든 row는 runbook_link 필수.
|
||||
#
|
||||
# 로그 레벨은 행의 칸이 아니다. 레벨은 오류 코드가 아니라 실패의 종류와 경로가 정한다.
|
||||
# shared-contract ServerFailureLog — 모든 전송이 쓴다. 영속성·의존성 carrier와 5xx carrier는 ERROR,
|
||||
# 4xx carrier는 남기지 않는다. IllegalArgumentException(BAD_PARAMETER)은 WARN.
|
||||
# web AuthErrorResponseWriter — 보안 필터. 5xx는 ERROR, 4xx는 WARN.
|
||||
# 행에 log_level을 두면 OperationalErrorRegistryContractTest가 실패한다.
|
||||
# 결정: docs/superpowers/specs/2026-11-06-error-code-log-level-design.md 7·10절.
|
||||
|
||||
errors:
|
||||
|
||||
@@ -41,7 +47,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://auth/token-missing"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -55,7 +60,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://auth/token-malformed"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -69,7 +73,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://auth/token-expired"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -83,7 +86,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://auth/token-invalid-signature"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -97,7 +99,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://auth/issuer-mismatch"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -111,7 +112,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://auth/audience-mismatch"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -126,7 +126,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://auth/kid-unknown"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -140,7 +139,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://auth/jwks-unavailable"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -154,7 +152,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://auth/claim-mapping-failed"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -172,7 +169,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "이 작업을 수행할 권한이 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://authz/insufficient-permission"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:authz-category
|
||||
@@ -186,7 +182,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "이 작업을 수행할 권한이 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://authz/tenant-mismatch"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:authz-category
|
||||
@@ -204,7 +199,6 @@ errors:
|
||||
owner_branch: feature-security-operational-baseline
|
||||
owner_layer: crosscut
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://auth/public-path-misconfiguration"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:auth-category
|
||||
@@ -218,7 +212,6 @@ errors:
|
||||
owner_branch: feature-container-runtime-contract
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://runtime/jvm-oom"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:container-runtime-oom
|
||||
@@ -236,7 +229,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://db/unavailable"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:persistence-mapping
|
||||
@@ -250,7 +242,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://db/serialization-failure"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:persistence-mapping
|
||||
@@ -264,7 +255,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://db/deadlock"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:persistence-mapping
|
||||
@@ -278,7 +268,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:persistence-mapping
|
||||
@@ -292,7 +281,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:persistence-mapping
|
||||
@@ -306,7 +294,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:persistence-mapping
|
||||
@@ -320,7 +307,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:persistence-mapping
|
||||
@@ -334,7 +320,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://db/idle-in-tx-timeout"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:persistence-mapping
|
||||
@@ -348,7 +333,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://db/query-canceled"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:persistence-mapping
|
||||
@@ -362,7 +346,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: additive
|
||||
required_test: persistence-jpa:JpaPersistenceExceptionCodeTest
|
||||
@@ -376,7 +359,6 @@ errors:
|
||||
owner_branch: feature-persistence-failure-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: null
|
||||
compatibility_impact: additive
|
||||
required_test: persistence-jpa:JpaPersistenceExceptionCodeTest
|
||||
@@ -394,7 +376,6 @@ errors:
|
||||
owner_branch: feature-rate-limit-idempotency-contract
|
||||
owner_layer: presentation
|
||||
client_safe_message: "요청이 너무 잦습니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://rate-limit/exceeded"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:rate-limit
|
||||
@@ -412,7 +393,6 @@ errors:
|
||||
owner_branch: feature-rate-limit-idempotency-contract
|
||||
owner_layer: application
|
||||
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: behavior-change
|
||||
required_test: contract-verification:idempotency
|
||||
@@ -426,7 +406,6 @@ errors:
|
||||
owner_branch: feature-rate-limit-idempotency-contract
|
||||
owner_layer: application
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:idempotency
|
||||
@@ -440,7 +419,6 @@ errors:
|
||||
owner_branch: feature-rate-limit-idempotency-contract
|
||||
owner_layer: application
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://idempotency/unavailable"
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:idempotency
|
||||
@@ -456,7 +434,6 @@ errors:
|
||||
owner_branch: feature-rate-limit-idempotency-contract
|
||||
owner_layer: application
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://idempotency/unavailable"
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:idempotency
|
||||
@@ -470,7 +447,6 @@ errors:
|
||||
owner_branch: feature-rate-limit-idempotency-contract
|
||||
owner_layer: application
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://idempotency/unavailable"
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:idempotency
|
||||
@@ -498,7 +474,6 @@ errors:
|
||||
owner_branch: feature-api-contract-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:api-contract-status-mapping
|
||||
@@ -512,7 +487,6 @@ errors:
|
||||
owner_branch: feature-api-contract-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:api-contract-status-mapping
|
||||
@@ -526,7 +500,6 @@ errors:
|
||||
owner_branch: feature-api-contract-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:api-contract-status-mapping
|
||||
@@ -540,7 +513,6 @@ errors:
|
||||
owner_branch: feature-api-contract-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:api-contract-status-mapping
|
||||
@@ -557,7 +529,6 @@ errors:
|
||||
owner_branch: feature-api-contract-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:api-contract-status-mapping
|
||||
@@ -571,7 +542,6 @@ errors:
|
||||
owner_branch: feature-api-contract-baseline
|
||||
owner_layer: presentation
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:api-contract-status-mapping
|
||||
@@ -609,7 +579,6 @@ errors:
|
||||
owner_branch: feature-outbound-http-client-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://dependency/timeout"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:outbound-http
|
||||
@@ -623,7 +592,6 @@ errors:
|
||||
owner_branch: feature-outbound-http-client-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://dependency/connect-failed"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:outbound-http
|
||||
@@ -637,7 +605,6 @@ errors:
|
||||
owner_branch: feature-outbound-http-client-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://dependency/dns-failed"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:outbound-http
|
||||
@@ -651,7 +618,6 @@ errors:
|
||||
owner_branch: feature-outbound-http-client-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://dependency/4xx-client"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:outbound-http
|
||||
@@ -665,7 +631,6 @@ errors:
|
||||
owner_branch: feature-outbound-http-client-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://dependency/5xx-server"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:outbound-http
|
||||
@@ -679,7 +644,6 @@ errors:
|
||||
owner_branch: feature-outbound-http-client-baseline
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://dependency/circuit-open"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:outbound-http
|
||||
@@ -697,7 +661,6 @@ errors:
|
||||
owner_branch: feature-domain-event-outbox-contract
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://outbox/publish-failed"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:outbox-publish
|
||||
@@ -711,7 +674,6 @@ errors:
|
||||
owner_branch: feature-domain-event-outbox-contract
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://outbox/dead-letter"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:outbox-dlq
|
||||
@@ -729,7 +691,6 @@ errors:
|
||||
owner_branch: feature-background-job-async-contract
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://job/executor-rejected"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:async-saturation
|
||||
@@ -743,7 +704,6 @@ errors:
|
||||
owner_branch: feature-background-job-async-contract
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://job/timeout"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:async-timeout
|
||||
@@ -757,7 +717,6 @@ errors:
|
||||
owner_branch: feature-background-job-async-contract
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://job/dead-letter"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:async-dlq
|
||||
@@ -782,7 +741,6 @@ errors:
|
||||
owner_branch: feature-distributed-lock-contract
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://lock/acquisition-timeout"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:lock-acquisition-timeout
|
||||
@@ -800,7 +758,6 @@ errors:
|
||||
owner_branch: feature-integration-adapter-templates
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://adapter/adapter-disabled"
|
||||
compatibility_impact: none
|
||||
required_test: adapter-contract:adapter-disabled-runtime-call
|
||||
@@ -819,7 +776,6 @@ errors:
|
||||
owner_branch: feature-management-actuator-security-contract
|
||||
owner_layer: presentation
|
||||
client_safe_message: "이 작업을 수행할 권한이 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://management/actuator-forbidden"
|
||||
compatibility_impact: none
|
||||
required_test: contract-verification:management-actuator
|
||||
@@ -838,7 +794,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: application
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
@@ -851,7 +806,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: presentation
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
@@ -864,7 +818,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: presentation
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
@@ -877,7 +830,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: application
|
||||
client_safe_message: "요청 값이 올바르지 않습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
@@ -890,7 +842,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: crosscut
|
||||
client_safe_message: "요청을 처리할 수 없습니다."
|
||||
log_level: ERROR
|
||||
runbook_link: "runbook://internal/error-spike"
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
@@ -903,7 +854,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://auth/token-missing"
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
@@ -916,7 +866,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: presentation
|
||||
client_safe_message: "인증이 필요합니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://auth/token-malformed"
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
@@ -929,7 +878,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: presentation
|
||||
client_safe_message: "이 작업을 수행할 권한이 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: "runbook://authz/insufficient-permission"
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
@@ -942,7 +890,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: presentation
|
||||
client_safe_message: "요청한 리소스를 찾을 수 없습니다."
|
||||
log_level: INFO
|
||||
runbook_link: null
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
@@ -955,7 +902,6 @@ errors:
|
||||
owner_branch: 2026-09-21-core-web-review-remediation
|
||||
owner_layer: infrastructure
|
||||
client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다."
|
||||
log_level: WARN
|
||||
runbook_link: null
|
||||
compatibility_impact: additive
|
||||
required_test: contract-verification:operational-error-registry
|
||||
|
||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [AUTH_JWKS_UNAVAILABLE]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-06
|
||||
status: stub
|
||||
---
|
||||
|
||||
@@ -13,6 +13,8 @@ status: stub
|
||||
## Symptoms
|
||||
|
||||
- HTTP 503 with `error.code=AUTH_JWKS_UNAVAILABLE`
|
||||
- ERROR log line `security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=…`
|
||||
(logger `AuthErrorResponseWriter`)
|
||||
- All authentication failing; JWKS refresh attempts failing
|
||||
|
||||
## Diagnosis
|
||||
|
||||
@@ -4,7 +4,7 @@ category: INTERNAL
|
||||
error_codes: [INTERNAL_AUTH_MISCONFIGURATION]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-06
|
||||
status: stub
|
||||
---
|
||||
|
||||
@@ -13,6 +13,8 @@ status: stub
|
||||
## Symptoms
|
||||
|
||||
- HTTP 500 with `error.code=INTERNAL_AUTH_MISCONFIGURATION`
|
||||
- ERROR log line `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…`
|
||||
(logger `AuthErrorResponseWriter`)
|
||||
- Security filter misconfiguration detected at runtime
|
||||
|
||||
## Diagnosis
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTH
|
||||
error_codes: [AUTH_TOKEN_INVALID_SIGNATURE]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-06
|
||||
status: stub
|
||||
---
|
||||
|
||||
@@ -13,7 +13,9 @@ status: stub
|
||||
## Symptoms
|
||||
|
||||
- HTTP 401 with `error.code=AUTH_TOKEN_INVALID_SIGNATURE`
|
||||
- `log_level=ERROR` — may indicate forged tokens or wrong signing key
|
||||
- WARN log line `security failure: code=AUTH_TOKEN_INVALID_SIGNATURE category=AUTH method=… path=…`
|
||||
(logger `AuthErrorResponseWriter`). It is a WARN because the caller sent the token; search by
|
||||
`code=`, not by level. A burst of these may indicate forged tokens or a wrong signing key
|
||||
|
||||
## Diagnosis
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ category: AUTHZ
|
||||
error_codes: [AUTHZ_TENANT_MISMATCH]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
last_updated: 2026-11-06
|
||||
status: stub
|
||||
---
|
||||
|
||||
@@ -13,7 +13,9 @@ status: stub
|
||||
## Symptoms
|
||||
|
||||
- HTTP 403 with `error.code=AUTHZ_TENANT_MISMATCH`
|
||||
- `log_level=ERROR` — cross-tenant access attempt detected
|
||||
- The template does not emit this code; the service that decides cross-tenant access does. A 403
|
||||
carrier is answered without a log line (`ServerFailureLog`), so that service logs
|
||||
`code=AUTHZ_TENANT_MISMATCH` where it decides, if this runbook is to find the attempt
|
||||
|
||||
## Diagnosis
|
||||
|
||||
|
||||
@@ -0,0 +1,245 @@
|
||||
# `error-codes.yaml`의 `log_level` 칸 — 설계 메모
|
||||
|
||||
- 상태: **확정** (2026-11-06, 소유자 답 "권하는 안대로"). 결정은 10절이다. 아래 1~9절은 결정 전에 쓴 그대로 둔다.
|
||||
- 기준 커밋: `06f520e6` (`refactor/maturity-review-2026-11`)
|
||||
- 크기: 중간(brief). 이 메모가 고르는 안을 실제로 적용하는 일은 **큼**이다. 오류 코드 레지스트리는 공개 계약이라
|
||||
파일 하나여도 큼이다(`docs/work/README.md` 2절). 그래서 이 메모는 대안 비교까지 하고 멈춘다. 코드와 yaml은
|
||||
바꾸지 않았다.
|
||||
- 요청(총괄 brief 원문): "`docs/registries/error-codes.yaml`의 `log_level` 칸은 읽는 코드가 없고, 값이 코드와 다른
|
||||
곳이 있다(`IDEMPOTENCY_UNAVAILABLE`: 문서 WARN, 코드 ERROR). 이 칸을 어떻게 할지 설계 메모를 쓰고 소유자 결정을
|
||||
묻는다."
|
||||
- 처음 나온 곳: 재리뷰 round6이 "규범인지 판단하지 않았다"로 남긴 항목
|
||||
(`docs/reviews/2026-11-03-rereview/round6/02-idempotency-outbound.md:217`).
|
||||
|
||||
## 1. 결론
|
||||
|
||||
권하는 안은 **A — 칸을 지운다**이다. 로그 레벨은 오류 코드 하나가 아니라 실패의 종류와 경로가 정하고, 그 규칙은
|
||||
이미 코드 한 곳(`ServerFailureLog`)에 있다. 레지스트리 머리말은 그 규칙을 가리키기만 한다. 칸 값을 증상으로 적은
|
||||
런북 2곳은 실제 로그 줄로 고친다.
|
||||
|
||||
칸과 별개로 동작 질문이 둘 남는다. 보안 필터가 5xx 두 코드를 WARN으로 남기는 것(결정 2), 문서가 ERROR로 의도한 401
|
||||
세 코드(결정 3)다.
|
||||
|
||||
## 2. 지금 어떻게 되어 있나
|
||||
|
||||
### 2.1 칸을 읽는 곳
|
||||
|
||||
- 스키마: `docs/registries/error-codes.yaml:18` `log_level: ERROR | WARN | INFO`. 60행 모두 값이 있다(ERROR 25,
|
||||
WARN 26, INFO 9).
|
||||
- 코드와 테스트: 읽는 곳이 없다. `src`·`scripts`의 java·py·gradle·sh에서 `log_level`·`logLevel` 검색 결과 0건이다.
|
||||
- 테스트가 읽는 칸: `category`·`http_status`·`retryable`·`client_safe_message`·`runbook_link`·`owner_branch`·
|
||||
`compatibility_impact`·`required_test`다(테스트 코드의 `get("<칸>")` 집계). `log_level`과 `owner_layer`만
|
||||
아무도 읽지 않는다.
|
||||
- 스키마 검사(`ContractRegistrySchemaGovernanceTest`, `RegistryGovernanceCatalog.java:217, 247-253`)는 필수 칸만 본다.
|
||||
모르는 칸을 막지 않는다.
|
||||
- 값의 이력: `git log -S log_level`의 네 커밋(`821fe00c`, `9da00eb7`, `c4a066df`, `bbe944bd`)은 행을 넣거나 뺐다.
|
||||
있던 행의 레벨 값이 바뀐 적은 없다(커밋 사이 코드별 값 비교 결과 차이 0).
|
||||
- 런북: 두 곳이 칸 값을 증상으로 적는다.
|
||||
- `docs/runbooks/auth-token-invalid-signature.md:16`: "`log_level=ERROR` — may indicate forged tokens"
|
||||
- `docs/runbooks/authz-tenant-mismatch.md:16`: "`log_level=ERROR`"
|
||||
- 경보: `docs/registries/metrics.yaml`의 경보 기준은 모두 지표다(error_rate, p99 등). 로그 레벨을 세는 경보는 없다
|
||||
(`logback_events`·`level=error` 검색 0건).
|
||||
- 파생 서비스 `tech-log-backend`(`a000f87`): 자기 `error-codes.yaml` 96행에 `log_level`을 채운다. 설계서가 새 행마다
|
||||
이 칸을 채우라고 적는다(`docs/superpowers/specs/2026-08-18-techlog-studio-backend-design.md:382`). 그쪽에도 이
|
||||
칸을 읽는 코드는 없다(`git grep log_level`, java·gradle·yaml·sh 0건).
|
||||
|
||||
### 2.2 코드가 로그 레벨을 정하는 방식
|
||||
|
||||
레벨은 오류 코드가 아니라 **실패의 종류와 경로**가 정한다.
|
||||
|
||||
```text
|
||||
요청 실패 ─┬─ 보안 필터(401·403·JWKS·인증 설정) ─ AuthErrorResponseWriter ─────────── 늘 WARN
|
||||
├─ IllegalArgumentException ─────────── ServerFailureLog.refusedArgument ─── WARN
|
||||
├─ ApiErrorCarrier ─ ServerFailureLog.of ─┬─ PersistenceFailureException ── ERROR (상태 무관)
|
||||
│ ├─ DependencyFailureException ── ERROR (상태 무관)
|
||||
│ ├─ 그 밖의 5xx ───────────────── ERROR
|
||||
│ └─ 4xx ───────────────────────── 남기지 않음
|
||||
├─ Spring MVC 예외 ─ handleExceptionInternal ── 5xx면 ERROR, 4xx면 남기지 않음
|
||||
└─ 그 밖의 예외 ─ handleUnknown ── INTERNAL_ERROR로 답하고 ERROR
|
||||
배경 작업 ─ outbox 실패 보고, executor 거절 ── ERROR
|
||||
```
|
||||
|
||||
출처:
|
||||
|
||||
- 규칙: `src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java:54-79`.
|
||||
4xx를 남기지 않는 이유는 같은 파일 25행 "A client-side carrier is not logged: it is an answer, not an incident"다.
|
||||
IAE WARN은 91-96행이다.
|
||||
- 네 전송이 같은 줄을 쓴다.
|
||||
- carrier ERROR: web `GlobalExceptionHandler.java:173-176`, gRPC `GrpcExceptionHandlingInterceptor.java:135-136`,
|
||||
GraphQL `GraphQlWireErrorMapper.java:134-135`, STOMP `StompHandlerFailureLog.java:35-36`
|
||||
- IAE WARN: web `GlobalExceptionHandler.java:96-97`, gRPC `:139-140`, GraphQL `:137-138`, STOMP `:40-41`
|
||||
- 보안 필터: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java:32`
|
||||
`log.warn("security failure: code={} …")`. 인증 진입점과 접근 거부 처리기가 둘 다 이 writer를 쓴다.
|
||||
- Spring MVC: `GlobalExceptionHandler.java:397-401`. 그 밖의 예외: 같은 파일 195-203행.
|
||||
- 배경 작업: `Slf4jOutboxRelayFailureReportAdapter.java`의 `atError()`, `LoggingAbortPolicy.java:35`.
|
||||
- 이 규칙은 리뷰를 거쳐 정한 설계다. 네 전송이 한 정책을 쓰게 했고(`ServerFailureLog` Javadoc 첫 문단), IAE를 네
|
||||
전송에서 같은 WARN 한 줄로 남기게 했다(RR6-01-06, `docs/reviews/2026-11-03-rereview/README.md` 17절 r10-01).
|
||||
|
||||
그래서 레벨은 오류 코드 하나에 값 하나로 떨어지지 않는다.
|
||||
|
||||
- 같은 `BAD_PARAMETER`라도 IAE에서 오면 WARN이다. 타입 변환 실패에서 오면 남기지 않는다
|
||||
(`GlobalExceptionHandler.java:108-116`).
|
||||
- 같은 409라도 영속성 실패면 ERROR다. 멱등 in-flight면 남기지 않는다.
|
||||
|
||||
### 2.3 60행 대조
|
||||
|
||||
방법: 행마다 main 코드에서 그 코드를 내는 곳을 찾았다(`grep -rlw <CODE> src --include='*.java'` 중 `/main/`). 그 경로에
|
||||
2.2의 규칙을 대어 레벨을 정했다. 코드를 읽은 결과이고, 실행 탐침은 돌리지 않았다(이유는 6절 가정 4).
|
||||
|
||||
| 결과 | 행 | 코드 |
|
||||
| --- | --- | --- |
|
||||
| 같다 | 14 | WARN: `AUTH_TOKEN_MISSING`, `AUTH_TOKEN_MALFORMED`, `AUTH_TOKEN_EXPIRED`, `AUTH_KID_UNKNOWN`. ERROR: `DB_UNAVAILABLE`, `DB_IDLE_IN_TX_TIMEOUT`, `DB_COMPLETION_UNKNOWN`, `IDEMPOTENCY_COMPLETION_UNKNOWN`, `IDEMPOTENCY_RECOVERY_REQUIRED`, `ADAPTER_DISABLED`, `INTERNAL_ERROR`, `OUTBOX_PUBLISH_FAILED`, `OUTBOX_DEAD_LETTER`, `JOB_EXECUTOR_REJECTED` |
|
||||
| 문서 ERROR, 코드 WARN | 5 | `AUTH_TOKEN_INVALID_SIGNATURE`, `AUTH_ISSUER_MISMATCH`, `AUTH_AUDIENCE_MISMATCH`(401), `AUTH_JWKS_UNAVAILABLE`(503), `INTERNAL_AUTH_MISCONFIGURATION`(500). 보안 필터가 모두 WARN으로 남긴다 |
|
||||
| 문서 WARN, 코드 ERROR | 10 | `IDEMPOTENCY_UNAVAILABLE`(503 carrier). 영속성 실패 9개: `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK`, `DB_NULL_VIOLATION`, `DB_FK_VIOLATION`, `DB_UNIQUE_VIOLATION`, `DB_CHECK_VIOLATION`, `DB_OPTIMISTIC_CONFLICT`, `DB_LOCK_TIMEOUT`(409), `DB_QUERY_CANCELED`(503). JPA 예외는 모두 `PersistenceFailureException`의 하위 타입이다(`JpaPersistenceException.java:22`) |
|
||||
| 문서는 레벨, 코드는 남기지 않음 | 15 | `IDEMPOTENT_IN_FLIGHT`, `IDEMPOTENT_REQUEST_MISMATCH`, `MAPPING_FAILED`, `VALIDATION_FAILED`, `PRECONDITION_FAILED`, `METHOD_NOT_ALLOWED`, `NOT_ACCEPTABLE`, `PAYLOAD_TOO_LARGE`, `URI_TOO_LONG`, `UNSUPPORTED_MEDIA_TYPE`, `ROUTE_NOT_FOUND`, `RATE_LIMIT_EXCEEDED`, `INVALID_TOKEN`, `FORBIDDEN`, `BATCH_PARTIAL_FAILURE` |
|
||||
| 경로마다 다름 | 3 | `BAD_PARAMETER`(문서 INFO; IAE면 WARN, 타입 변환이면 없음). `AUTHZ_INSUFFICIENT_PERMISSION`(문서 WARN; 필터면 WARN, controller method security면 `handleForbidden`이라 없음). `UNAUTHENTICATED`(문서 WARN; web은 없음, gRPC는 인증 정책이 예외를 던질 때만 WARN — `GrpcAuthenticationInterceptor.java:55`) |
|
||||
| 템플릿 main에 내는 곳 없음 | 13 | `AUTH_CLAIM_MAPPING_FAILED`, `AUTHZ_TENANT_MISMATCH`, `JVM_OOM`, `DEPENDENCY_TIMEOUT`, `DEPENDENCY_CONNECT_FAILED`, `DEPENDENCY_DNS_FAILED`, `DEPENDENCY_4XX_CLIENT`, `DEPENDENCY_5XX_SERVER`, `DEPENDENCY_CIRCUIT_OPEN`, `JOB_TIMEOUT`, `JOB_DEAD_LETTER`, `ACTUATOR_FORBIDDEN`, `LOCK_ACQUISITION_TIMEOUT` |
|
||||
|
||||
- 내는 곳이 있는 47행 중 33행이 문서와 다르다. brief가 든 `IDEMPOTENCY_UNAVAILABLE`은 그중 하나다.
|
||||
- `DEPENDENCY_*`: 파생 서비스의 어댑터가 `DependencyFailureException`으로 던지면 ERROR가 된다. 그때는 문서가 WARN인
|
||||
`DEPENDENCY_CIRCUIT_OPEN`도 어긋난다.
|
||||
- `LOCK_ACQUISITION_TIMEOUT`은 레벨과 별개의 문제가 있다(9절).
|
||||
|
||||
### 2.4 어긋남이 실제로 해를 끼치는 곳
|
||||
|
||||
- **런북 증상이 틀렸다.** `auth-token-invalid-signature.md`는 `log_level=ERROR`를 증상으로 적는다. 실제 줄은
|
||||
WARN `security failure: code=AUTH_TOKEN_INVALID_SIGNATURE …`다. ERROR로 거르는 운영자는 이 사건을 못 본다.
|
||||
- **칸을 채우는 일이 헛수고다.** 새 코드를 만드는 사람이 칸을 채워도 동작이 바뀌지 않는다. 파생 서비스는 96행에
|
||||
값을 골라 적었다.
|
||||
- 경보는 로그 레벨을 쓰지 않는다. 그래서 이 어긋남으로 경보가 빠지지는 않는다.
|
||||
|
||||
## 3. 선행 사례
|
||||
|
||||
| 출처 | 1차/2차 | 그들이 한 것 | 한계 | 가져올 것 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 이 repo `client_safe_message` 칸 (`c4a066df`, 소유자 결정 11) | 1차 | 행마다 다르던 문구를 Category별 문구 표 하나(`ClientErrorMessages`)로 코드에 두었다. 칸은 그 값과 같아야 한다고 테스트로 고정했다(`OperationalErrorRegistryContractTest.everyRegistryClientMessageIsTheSharedCategoryMessage`) | 문구가 category만으로 정해져서 고정이 쉬웠다 | 코드가 원본이고 칸은 테스트가 고정한다. 레벨은 코드 하나로 정해지지 않는다는 점이 다르다(2.2) |
|
||||
| 이 repo `category`·`http_status`·`retryable` | 1차 | enum이 원본이다. yaml을 enum과 테스트로 대조한다(`theEnumAndTheRegistryAgree`) | — | 레지스트리 칸은 코드가 읽거나 테스트가 고정한다는 이 repo의 관행 |
|
||||
| 이 repo `env-keys.yaml`의 `required_when` (`0a6dd0e4`) | 1차 | 런타임이 강제한 적 없는 요구("app.redis.mode=sentinel")를 지우고 실제 동작에 맞췄다(`docs/registries/env-keys.yaml:2269-2273`) | — | 강제하지 않는 레지스트리 문장을 규범처럼 두지 않는다. 실제 동작으로 고친다 |
|
||||
| JBoss Logging Tools (Hibernate·WildFly가 씀) | 1차, <https://jboss-logging.github.io/jboss-logging-tools/> | 메시지 id와 레벨을 코드의 annotation 한 곳에 둔다(`@Message(id = …)`, `@LogMessage(level = ERROR)`). 보고서(id, 해결 문서 링크, 메시지, 레벨)는 annotation에서 만든다(AsciiDoc·XML) | 메시지마다 레벨이 하나인 모델이다. 경로마다 레벨이 다른 우리 설계에는 그대로 맞지 않는다 | 레벨을 문서로 보이고 싶으면 손으로 쓴 칸이 아니라 코드에서 뽑는다 |
|
||||
| Spring Framework `AbstractHandlerExceptionResolver` | 1차, `spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerExceptionResolver.java`(main) | 예외 처리 로그는 처리기 코드가 정한다. 기본은 남기지 않고, `setWarnLogCategory`로 켜면 WARN 한 레벨로 남긴다 | 오류 코드별 레벨 표는 없다 | 처리된 클라이언트 오류는 기본으로 남기지 않는다. `ServerFailureLog`의 "4xx는 답이지 사건이 아니다"와 같은 판단이다 |
|
||||
|
||||
## 4. 대안
|
||||
|
||||
### A. 칸을 지운다
|
||||
|
||||
- 머리말 스키마에서 `log_level` 줄을 뺀다. 대신 "로그 레벨은 오류 코드가 아니라 실패 종류와 경로가 정한다. 규칙은
|
||||
`ServerFailureLog` Javadoc과 `AuthErrorResponseWriter`"라고 적는다.
|
||||
- 60행에서 `log_level:` 줄을 지운다.
|
||||
- 런북 2곳의 증상 줄을 실제 로그 줄로 고친다.
|
||||
- `docs/upgrade/`에 파생 서비스 안내를 한 줄 더한다.
|
||||
- 선택(결정 1-b): 칸이 다시 생기지 않게 "행에 `log_level`이 없다"는 단언을 레지스트리 테스트에 둔다. 두면 파생
|
||||
서비스도 자기 행에서 칸을 지워야 merge 뒤 테스트가 통과한다.
|
||||
|
||||
### B. 칸을 남기고 코드에 맞춘 뒤 테스트로 고정한다
|
||||
|
||||
- 값 집합에 `NONE`(남기지 않음)과 `BY_PATH`(경로마다 다름)를 더한다. 60행을 2.3 표대로 고친다.
|
||||
- 테스트는 `ServerFailureLog` 규칙을 다시 구현한 표(코드 → 기대 레벨)와 yaml을 대조한다.
|
||||
- 문제: 레벨이 코드만으로 정해지지 않아서, 표가 규칙의 손 사본이 된다. 예외 종류(영속성·의존성 carrier)는 행에
|
||||
없으므로, 테스트가 "`DB_*`면 ERROR"를 이름 접두어로 짐작해야 한다. 템플릿 main에 내는 곳이 없는 13행은 기대값을
|
||||
정할 근거가 없다.
|
||||
|
||||
### C. 칸을 규범으로 만들고 코드가 읽는다
|
||||
|
||||
- `ApiErrorCode`에 `logLevel()`을 더한다. `OperationalError`는 값을 갖고, 파생 enum은 default 메서드로 지금 규칙을 쓴다.
|
||||
- 네 전송, 보안 필터, 배경 작업이 그 값으로 남긴다. yaml은 enum과 테스트로 대조한다.
|
||||
- 동작이 바뀐다. 2.3의 33행이 지금과 다른 레벨이 된다.
|
||||
- 문서가 INFO·WARN인 4xx 15행이 새로 로그를 남긴다. 404·400·429마다 한 줄씩이라, 스캐너·공격 트래픽이 로그
|
||||
양을 정한다.
|
||||
- 409 영속성 실패는 ERROR에서 WARN으로 내려간다.
|
||||
- `ServerFailureLog`의 "4xx는 남기지 않는다"와 RR6-01-06 결정을 뒤집는다. 다시 열 조건(`docs/work/reference/decisions.md`
|
||||
1절)에 맞는 새 근거가 없다.
|
||||
- `ApiErrorCode`는 shared-contract의 공개 인터페이스다. 파생 서비스의 enum이 영향을 받는다.
|
||||
|
||||
### 버린 기준선: 주석만 달기
|
||||
|
||||
칸에 "참고용"이라 적고 `IDEMPOTENCY_UNAVAILABLE` 한 행만 고치는 안이다. 틀린 33행 중 1행만 고쳐지고 런북은 여전히
|
||||
틀린 증상을 적는다. 버린다.
|
||||
|
||||
### 비교
|
||||
|
||||
| 대안 | 효과 | 비용 | 되돌리기 | 파생 서비스 영향 | 기존 결정과 충돌 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| A 지움 | 틀린 값 33행과 틀린 런북 증상 2곳이 사라진다. 레벨의 원본이 코드 하나로 준다 | yaml 머리말·60줄, 런북 2곳, upgrade 1줄. 코드 변경 0 (1-b면 테스트 단언 1개) | 쉽다(revert) | 1-b 없으면 할 일 없음. 1-b면 자기 96행에서 칸을 지운다 | 없다. `client_safe_message`·`env-keys` 선례와 같은 방향 |
|
||||
| B 맞추고 고정 | 칸이 맞는 값이 된다 | yaml 33행, 스키마, 새 테스트(규칙의 손 사본). 규칙을 바꿀 때마다 두 곳을 고친다 | 쉽다 | 같은 테스트가 파생 행도 읽으면 자기 행도 맞춰야 한다 | 없다. 다만 규칙 사본을 하나 더 만든다 |
|
||||
| C 규범화 | 소유자가 코드마다 레벨을 고를 수 있다 | shared-contract 인터페이스, 전송 넷, 보안 필터, 배경 작업, 테스트. 로그 양이 는다 | 어렵다(공개 인터페이스, 운영 로그 모양) | `ApiErrorCode` 구현 enum, 로그 수집 규칙 | `ServerFailureLog` 설계, RR6-01-06 |
|
||||
|
||||
## 5. 권하는 안: A
|
||||
|
||||
- 이 칸이 담으려던 정보("이 코드가 얼마나 시끄러운가")는 코드가 이미 실패 종류로 정한다. 그 규칙은 리뷰를 거쳐 네
|
||||
전송에 하나로 모였다. 코드별 칸은 그 규칙을 담을 모양이 아니다(2.2).
|
||||
- B는 그 규칙의 손 사본을 테스트에 하나 더 만든다. 사본은 고칠 곳만 늘린다. 내는 곳이 없는 13행에는 고정할 값도
|
||||
없다.
|
||||
- C는 코드가 맞고 문서가 틀린 상황에서 코드를 문서에 맞춘다. 문서 값은 행을 처음 넣을 때 적은 뒤 한 번도 고친 적이
|
||||
없다(2.1). 레벨을 따져 본 리뷰를 거친 쪽은 코드다.
|
||||
- 이 repo의 관행은 "칸은 코드가 읽거나 테스트가 고정한다"이다. 이 관행에 맞는 길은 A와 B인데, B는 고정할 값이
|
||||
없다. 그래서 A다.
|
||||
|
||||
## 6. 반증할 수 있는 가정, 반론과 답
|
||||
|
||||
### 가정
|
||||
|
||||
1. **템플릿과 파생 서비스 밖에서 이 칸을 읽는 도구가 없다.** 틀렸다면: 로그 파이프라인이나 대시보드가 이 yaml을
|
||||
읽고 있다면 칸 삭제가 그것을 깨뜨린다. 확인한 범위는 두 repo의 추적 파일이다. repo 밖 운영 도구는 모른다(결정 4).
|
||||
2. **레벨은 오류 코드 하나로 정해지지 않는다.** 틀렸다면 B의 비용이 크게 준다. 확인:
|
||||
`GlobalExceptionHandler.java:96-97`(IAE, WARN)과 `:108-116`(타입 변환, 로그 없음)가 같은 `BAD_PARAMETER`를 낸다.
|
||||
3. **4xx를 남기지 않는 것은 의도다.** 틀렸다면, 즉 소유자가 4xx를 줄 단위로 추적하길 원하면 C가 맞다. 근거:
|
||||
`ServerFailureLog.java:25`의 문장. 4xx 양은 `http.server.requests`의 `status=4xx` 지표로 이미 보인다
|
||||
(`metrics.yaml:18-40`).
|
||||
4. **2.3 표는 코드 읽기로 충분하다.** 틀렸다면: 다른 경로가 같은 코드를 다른 레벨로 남기면 표 칸이 바뀐다. 결론
|
||||
("대부분 다르다")은 33행 중 몇 행이 바뀌어도 유지된다. 탐침을 돌리지 않은 이유는 둘이다.
|
||||
- 각 경로는 레벨을 바꾸는 분기가 없는 `log.error`/`log.warn` 한 줄이다.
|
||||
- 기존 테스트가 같은 레벨을 고정한다: `GrpcExceptionHandlingInterceptorTest`·`StompHandlerFailureLogTest`·
|
||||
`GraphQlWireErrorMapperTest`의 `Level.ERROR`/`Level.WARN` 단언,
|
||||
`GlobalExceptionHandlerTest.anIllegalArgumentIsLoggedAtWarnByItsTypeWithoutItsMessage`.
|
||||
|
||||
### 반론과 답
|
||||
|
||||
- **"레벨을 문서에서 한눈에 보는 가치가 있다."** 그 가치는 값이 맞을 때만 있다. 지금은 47행 중 33행이 틀렸다.
|
||||
꼭 보이고 싶다면 JBoss Logging처럼 코드에서 뽑아야 한다. 그것은 레벨이 코드별 값이 된 뒤(C)에나 가능하다.
|
||||
- **"보안 쪽 ERROR(위조 토큰 의심)는 의도였다."** 의도는 런북 문장에 남아 있지만 구현된 적이 없다. 401 서명 실패를
|
||||
ERROR로 남기면 공격자가 ERROR 양을 정하게 된다. 감지가 필요하면 결정 3에서 따로 고른다.
|
||||
- **"칸을 지우면 파생 서비스가 upstream merge 때 할 일이 생긴다."** 1-b를 두지 않으면 할 일이 없다. 1-b를 두면
|
||||
지울 일이 생기지만, 같은 거짓 칸이 파생 서비스 96행에 남지 않는다.
|
||||
|
||||
## 7. 소유자가 정할 것
|
||||
|
||||
| # | 항목 | 선택지 | 권하는 안과 이유 | 정할 사람 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | `log_level` 칸 | A 지움 / B 코드 규칙에 맞추고 테스트로 고정 / C 규범화(코드가 읽음) | **A**. 5절 | 소유자 |
|
||||
| 1-b | A일 때 칸이 다시 생기는 것을 막는 단언 | 둔다(파생 서비스도 자기 행에서 지운다) / 두지 않는다 | **둔다**. 칸이 거짓인 것은 파생 서비스 행도 같다. upgrade 안내 "반드시 할 일"에 한 줄 | 소유자 |
|
||||
| 2 | 보안 필터가 5xx 두 코드(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)를 WARN으로 남기는 것 | ERROR로 올림 / WARN 유지 | **ERROR로 올림**. 다른 모든 경로가 5xx를 ERROR로 남긴다. 둘 다 서버 쪽 고장(키 서버 장애, 설정 오류)이다. 1번과 관계없이 동작 변경이라 별도 개선 작업으로 한다 | 소유자 |
|
||||
| 3 | 401 서명·issuer·audience 불일치(문서가 ERROR로 의도) | WARN 유지, 런북은 WARN 줄의 code로 찾게 고침 / ERROR로 올림 / WARN 유지 + 코드별 인증 실패 지표를 새로 둠 | **WARN 유지**. 클라이언트가 만드는 실패라 ERROR로 올리면 공격 트래픽이 ERROR 양을 정한다. 경보가 필요하면 세 번째 안이다. 지금은 코드별 인증 실패 지표가 없다(`metrics.yaml`) | 소유자 |
|
||||
| 4 | repo 밖에서 이 칸을 읽는 도구 | 있음 / 없음 | **모름**. 두 repo의 추적 파일에는 없다. 있으면 A를 다시 본다 | 소유자 |
|
||||
|
||||
## 8. 결정 뒤 할 일 (이 메모에서는 하지 않았다)
|
||||
|
||||
- A를 고르면: `docs/registries/error-codes.yaml` 머리말과 60행, 런북 2곳, `docs/upgrade/` 안내 한 줄, (1-b면)
|
||||
레지스트리 테스트 단언. 공개 계약 변경이라 크기는 큼이고 `docs/work/improve.md`로 한다. 결정은
|
||||
`docs/work/reference/decisions.md`에 기록한다.
|
||||
- 결정 2를 고르면: `AuthErrorResponseWriter`의 레벨 분기와 테스트(RED → GREEN).
|
||||
- B나 C를 고르면 이 메모의 4절을 계획서로 옮겨 다시 크기를 잡는다.
|
||||
|
||||
## 9. 이 조사 중 본 별개 문제 (범위 밖, 고치지 않았다)
|
||||
|
||||
- `LockAcquisitionTimeoutException`은 `ApiErrorCarrier`를 구현하지 않는다
|
||||
(`src/application-core/src/main/java/dev/caskeleton/application/lock/LockAcquisitionTimeoutException.java:13`).
|
||||
inbound 어디에도 이 예외의 처리기가 없다(`grep -rln LockAcquisitionTimeoutException src`: persistence-jpa와 테스트뿐).
|
||||
- Javadoc은 "The web adapter maps it to 409"라고 적는다. 하지만 web은 `handleUnknown`을 거쳐 `INTERNAL_ERROR` 500으로
|
||||
답할 것으로 읽힌다(`GlobalExceptionHandler.java:195-203`).
|
||||
- `LockAcquisitionTimeoutClassificationContractTest`가 막으려는 "500 INTERNAL로 뭉개기"(D7)와 같은 모양이다. 그
|
||||
테스트는 enum과 레지스트리만 보고 전송 경로는 보지 않는다.
|
||||
- 코드 읽기 결과이고 탐침은 돌리지 않았다. 결함 후보로 `docs/work/improve.md` 절차에 넘긴다.
|
||||
|
||||
## 10. 결정 (2026-11-06)
|
||||
|
||||
소유자 답은 "권하는 안대로"다(총괄 세션 전달, 2026-11-06). 7절 각 항목은 이렇게 정해졌다.
|
||||
|
||||
| # | 결정 | 적용한 곳 |
|
||||
| --- | --- | --- |
|
||||
| 1 | A. `log_level` 칸을 지운다. 레지스트리 머리말이 레벨을 정하는 코드(`ServerFailureLog`, `AuthErrorResponseWriter`)를 가리킨다 | `docs/registries/error-codes.yaml` 머리말과 60행 |
|
||||
| 1-b | 칸이 다시 생기지 않게 단언을 둔다. 파생 서비스는 자기 행에서도 지운다 | `OperationalErrorRegistryContractTest.noRegistryRowCarriesALogLevel`(태그 `document-contract`), `docs/upgrade/2026-11-maturity-review.md` 「반드시 할 일」 17·B-44 |
|
||||
| 2 | 보안 필터는 5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)를 ERROR로 남긴다 | `AuthErrorResponseWriter`(5xx ERROR, 4xx WARN), `EnvelopeAuthenticationEntryPointTest`, web README, 런북 2곳, upgrade 5절 |
|
||||
| 3 | 401 서명·issuer·audience 불일치는 WARN으로 둔다. 런북은 WARN 줄의 `code=`로 찾게 고친다 | `docs/runbooks/auth-token-invalid-signature.md`, 서명 실패 WARN을 고정한 테스트 |
|
||||
| 4 | repo 밖에서 이 칸을 읽는 도구는 없는 것으로 본다 | — |
|
||||
|
||||
결정 색인: `docs/work/reference/decisions.md` 2.3절 「오류 코드 로그 레벨」.
|
||||
@@ -37,6 +37,7 @@
|
||||
| 14 | 자기 테스트 코드에 `./gradlew testQualityCheck`를 돌려 보고, 발견을 고치거나 이유를 단 Match로 뺀다(B-40) | `mainCheck`가 실패 | 테스트 코드가 있는 모든 서비스 |
|
||||
| 15 | staging·prod 배포 마이그레이션 도구에 `flyway.postgresql.transactional.lock=false`(환경 변수 `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`)를 넣는다. 자기 Flyway stream은 `Flyway.configure()` 대신 `FlywaySchemaPolicy.configure()`로 만든다(5절 「Flyway 잠금」) | `CREATE INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY` 마이그레이션에서 배포가 오류 없이 멈춘다. 자기 stream이 `Flyway.configure()`를 부르면 `:app-bootstrap:architectureTest` 실패 | persistence-jpa 선택 + 배포 도구로 마이그레이션하거나 자기 stream을 둔 서비스 |
|
||||
| 16 | 자기 성능 lane(`performance()`)에서 `performance.assertions.enabled`를 `false`로 두는 `systemProperty` 줄을 지우고, 그 속성을 읽어 상한 단언을 건너뛰던 테스트는 항상 단언하게 고친다. 성능 lane의 `@Disabled`·assumption skip을 없앤다(B-43) | `performanceCheck`가 테스트 전에 실패(`its test JVM would get performance.assertions.enabled=false`)하거나 skip 때문에 실패(`forbids skipped tests`) | 자기 성능 lane이 있는 서비스 |
|
||||
| 17 | 자기 `docs/registries/error-codes.yaml` 행에서 `log_level:` 줄을 지운다(B-44) | `mainCheck`의 `:app-bootstrap:documentContractTest`가 실패(`docs/registries/error-codes.yaml rows with a log_level; the code decides the level, not the registry`) | `error-codes.yaml`에 자기 행을 더한 서비스 |
|
||||
|
||||
### 되돌릴 수 없는 것
|
||||
|
||||
@@ -111,6 +112,7 @@
|
||||
| B-40 | 테스트 코드 정적 분석 `testQualityCheck`: SpotBugs·FindSecBugs를 main 밖 모든 source set(test, testFixtures, integrationTest, systemTest 등)에 돌린다. 테스트용 제외 목록은 `config/spotbugs/exclude-test.xml`(보안 범주·내부 상태 노출·생성자 예외·반환값 null 역참조·아키텍처 위반 fixture). 분석 classpath가 그 source set의 runtime classpath로 넓어졌고, 분석이 불완전하면(빠진 클래스) 실패한다. main 빌드는 `mainCheck`(`qualificationCheck`), optional 빌드는 `ci` | 자기 테스트 코드의 SpotBugs 발견(예: `CountDownLatch.await` 반환값 무시, 공유 변수 비원자 쓰기, 닫지 않은 `Statement`)이 main 단계를 막는다. 테스트 classpath에 없는 타입을 참조하면 `SpotBugs analysis incomplete` | 고치거나, 클래스·메서드로 좁힌 Match를 이유와 함께 `exclude-test.xml`에 더한다. 빠진 타입은 그 테스트 suite 의존성에 넣는다 | `2678955c` · `src/build-logic/.../quality/QualityConventionsPlugin.java`, `src/config/spotbugs/exclude-test.xml`, `src/build.gradle` |
|
||||
| B-42 | shared-contract 패키지 규칙 `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가 실제로 검사한다. 대상은 `dev.caskeleton.shared..`뿐이고, 허용은 목록의 패키지(`concurrency digest error metrics observability ratelimit request response retry runtime security tracing`)와 그 아래, 뿌리 패키지에는 `package-info`만이다. 전에는 뿌리를 허용 목록에 넣고 접두어로 비교해서 모듈 안은 아무것도 잡지 못했고, 다른 leaf의 `..shared..` 패키지를 잡았다 | `dev.caskeleton.shared`에 목록에 없는 패키지나 뿌리 클래스를 둔 파생 서비스는 architectureTest 실패. 다른 leaf의 `shared` 패키지는 더는 걸리지 않는다 | 업무 개념이면 그것을 소유하는 모듈로 옮긴다. 운영 계약이면 `ForbiddenApiArchitectureTest.SHARED_CONTRACT_PACKAGES`와 shared-contract CLAUDE.md 「Responsibility」에 함께 더한다 | r10 · `src/app-bootstrap/src/architectureTest/.../ForbiddenApiArchitectureTest.java`, `SharedContractPackageRuleTest.java` |
|
||||
| B-43 | 성능 lane 단언 상시화: `performance()` lane은 convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣는다. 빌드가 `-P`·`GRADLE_OPTS`(`-Dorg.gradle.project.…`)로 `true` 아닌 값을 주거나, lane `systemProperty`·`jvmArgs`(`-D…`)·task 설정이 테스트 JVM 값을 `true` 아닌 값으로 덮으면 테스트 전에 실패한다. 성능 lane은 `rejectSkipped` 없이도 skip된 테스트가 있으면 실패한다. httpclient·Mongo leaf의 속성 선언과 `integration-main.yml` `performance-check`·`release.yml` `httpclient-release-gate`의 `GRADLE_OPTS` 줄을 지웠다. 측정만 하는 모드는 만들지 않았다(JMH가 그 용도) | `performanceCheck`·`:<leaf>:performanceTestLaneCheck`가 `is a performance lane, and this build sets performance.assertions.enabled=false`, `its test JVM would get performance.assertions.enabled=false`, `forbids skipped tests … a skipped test is a bound nobody measured` 중 하나로 실패 | `-Pperformance.assertions.enabled=false`를 지운다. 자기 lane의 그 `systemProperty`·`jvmArgs` 줄을 지우고, 그 속성을 읽던 테스트는 항상 단언하게 고친다. 성능 lane의 skip은 없애거나 그 테스트를 다른 lane으로 옮긴다. `GRADLE_OPTS=-Dorg.gradle.project.performance.assertions.enabled=true`·`-P…=true`는 받아 주므로 그대로 둬도 된다 | B4(2026-11-06) · `src/build-logic/.../strictlane/StrictTestLanePlugin.java`, `.../strictlane/StrictTestLaneConventionTest.java`(test), `docs/testing/TESTING_STRATEGY.md` 6절 |
|
||||
| B-44 | `docs/registries/error-codes.yaml`에서 `log_level` 칸을 지웠다. 행에 `log_level`이 있으면 `OperationalErrorRegistryContractTest.noRegistryRowCarriesALogLevel`(태그 `document-contract`, `mainCheck`)이 실패한다. 칸을 읽는 코드는 없었고 값 대부분이 실제 로그 레벨과 달랐다. 레벨은 실패 종류·경로가 정한다(`ServerFailureLog`, 보안 필터 `AuthErrorResponseWriter`) | 자기 행에 `log_level`이 남은 서비스는 `mainCheck` 실패(`… rows with a log_level; the code decides the level, not the registry`와 그 행의 code 목록) | 자기 행에서 `log_level:` 줄을 지운다. 레벨을 바꾸려면 그 실패를 로그로 남기는 코드를 고친다. 자기 설계서가 "행마다 `log_level`을 채운다"고 적었으면 그 문장도 지운다 | 설계 메모 2026-11-06 7절 결정 1·1-b · `docs/registries/error-codes.yaml` 머리말, `src/app-bootstrap/src/test/.../contract/OperationalErrorRegistryContractTest.java` |
|
||||
|
||||
### 3.5 모듈 registry·새 leaf
|
||||
|
||||
@@ -243,6 +245,7 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur
|
||||
| sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` |
|
||||
| Flyway 잠금 | Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션 대신 세션에 둔다. Spring Boot의 Flyway는 module-defaults `spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway(멱등성·알림·sample stream, schema-per-tenant, testkit `MigrationContractRunner`)는 `FlywaySchemaPolicy.configure()`, messaging inbox stream은 같은 값을 직접 넣는다. 운영 코드의 `Flyway.configure()` 직접 호출은 `JpaProductionArchitectureTest`가 거부한다 | Flyway 기본값에서는 동시 인덱스 마이그레이션이 Flyway 자신의 열린 트랜잭션을 기다려 끝나지 않았다. 이제 끝난다. 마이그레이션은 잠금을 잡은 연결 하나로 돈다. transaction 모드 PgBouncer 뒤에서는 잠금 해제가 다른 서버 연결로 가 다음 배포가 기다릴 수 있으니 마이그레이션은 직접 연결이나 session 모드 pool로 돌린다. 배포 도구는 이 repo 밖이라 2절 15번으로 맞춘다 | 재리뷰 round6 RR6-03-01 · `persistence-jpa.yml`, `.../migration/FlywaySchemaPolicy.java`, `docs/jpa/migration-guide.md` "Who may change the schema"·"Concurrent index builds" |
|
||||
| 성능 lane(HTTP client·Mongo) | httpclient `LargeBodyResourceTest`의 힙 상한(32 MiB 스트리밍 중 힙 증가 16 MiB 미만)을 매번 단언한다. 전에는 `-Pperformance.assertions.enabled=true`일 때만 단언하고 아니면 건너뛴다는 줄만 찍었다. Mongo `MongoResourceBudgetLaneTest`는 표준 gate 전체(p99 500ms, pool 대기 250ms, 힙 512 MiB, examined/returned 10, spill 금지)를 Gradle 밖 실행에서도 단언한다(B-43) | 손으로 돌린 `performanceCheck`가 상한을 실제로 재므로, 전에는 통과하던 느린 기계에서 실패할 수 있다 | B4(2026-11-06) · `LargeBodyResourceTest`, `MongoResourceBudgetLaneTest` |
|
||||
| 보안 필터 로그 레벨 | 보안 필터(`AuthErrorResponseWriter`)의 `security failure` 줄을 5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)면 ERROR, 4xx면 WARN으로 남긴다. 전에는 모두 WARN이었다. 다른 경로가 5xx를 ERROR로 남기는 규칙(`ServerFailureLog`)과 같아졌다 | ERROR로 거르는 로그 경보·대시보드에 JWKS 장애와 인증 설정 오류가 새로 잡힌다. 401·403은 그대로 WARN | 설계 메모 2026-11-06 7절 결정 2 · `src/adapter/inbound/web/.../auth/AuthErrorResponseWriter.java`, `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md` |
|
||||
|
||||
## 6. 따라오는 순서
|
||||
|
||||
|
||||
@@ -81,6 +81,7 @@
|
||||
| GraphQL DataLoader 키 실패 | 등록된 `ApiErrorCode`만 노출 | 소유자 | 결정 25 |
|
||||
| Draft-12 offset 불일치 | problem 문서는 프로토콜 예외로 유지 | 소유자 | 결정 12 |
|
||||
| 알림 category 생략 | 거부(400), 판정은 유스케이스 | 소유자 | 결정 13 |
|
||||
| 오류 코드 로그 레벨 | `error-codes.yaml`에 `log_level` 칸을 두지 않는다. 레벨은 실패 종류·경로가 정한다(`ServerFailureLog`, 보안 필터 `AuthErrorResponseWriter`). 칸이 다시 생기면 `OperationalErrorRegistryContractTest`가 실패한다. 보안 필터는 5xx(`AUTH_JWKS_UNAVAILABLE`·`INTERNAL_AUTH_MISCONFIGURATION`)를 ERROR, 4xx를 WARN으로 남긴다. 401 서명·issuer·audience 불일치는 WARN | 소유자 | 2026-11-06, `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md` 10절 |
|
||||
|
||||
### 2.4 멱등성
|
||||
|
||||
|
||||
@@ -115,6 +115,10 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
|
||||
코드의 일반 `client_safe_message` 만 담고, 원시 예외 텍스트·`Authorization` 헤더·issuer·audience 는
|
||||
절대 포함하지 않는다. 로그 라인엔 code/category/요청 path 만 기록하고 bearer token 은 절대 로깅하지
|
||||
않는다(leak 테스트가 강제하는 계약). 전체 로그 마스킹 필터는 별도 log-management 영역에서 다룬다.
|
||||
- **로그 레벨.** 4xx(토큰 누락·만료·서명·issuer·audience·kid 실패, 권한 부족)는 호출자 쪽 실패라 WARN이다.
|
||||
5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)는 서버 쪽 고장이라 ERROR다. 다른
|
||||
경로가 5xx를 ERROR로 남기는 규칙(shared-contract `ServerFailureLog`)과 같다. 레벨은 오류 코드 레지스트리의
|
||||
칸이 아니라 이 코드가 정한다(설계 메모 `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md`).
|
||||
- **WWW-Authenticate(RFC 9110 §15.5.2).** 401 응답은 반드시 WWW-Authenticate 헤더를 갖되, `error_description`
|
||||
으로 issuer/token 세부가 새지 않도록 최소한으로 유지한다.
|
||||
|
||||
|
||||
+11
-7
@@ -8,6 +8,7 @@ import jakarta.servlet.http.HttpServletResponse;
|
||||
import java.io.IOException;
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
import org.slf4j.event.Level;
|
||||
import org.springframework.http.HttpHeaders;
|
||||
import tools.jackson.databind.ObjectMapper;
|
||||
|
||||
@@ -28,13 +29,16 @@ class AuthErrorResponseWriter {
|
||||
|
||||
void write(HttpServletRequest request, HttpServletResponse response, OperationalError code)
|
||||
throws IOException {
|
||||
// Log only safe metadata — never the token or the raw failure message.
|
||||
log.warn(
|
||||
"security failure: code={} category={} method={} path={}",
|
||||
code.code(),
|
||||
code.category(),
|
||||
request.getMethod(),
|
||||
request.getRequestURI());
|
||||
// Log only safe metadata — never the token or the raw failure message. A 5xx is the server's
|
||||
// own failure (the key service is down, the decoder is misconfigured) and is an ERROR, as a 5xx
|
||||
// is on every other path (ServerFailureLog); a 4xx is the caller's and stays a WARN.
|
||||
log.atLevel(code.httpStatus() >= 500 ? Level.ERROR : Level.WARN)
|
||||
.log(
|
||||
"security failure: code={} category={} method={} path={}",
|
||||
code.code(),
|
||||
code.category(),
|
||||
request.getMethod(),
|
||||
request.getRequestURI());
|
||||
|
||||
// A 401 response carries a minimal WWW-Authenticate header (no issuer / token detail).
|
||||
if (code.httpStatus() == 401) {
|
||||
|
||||
+86
@@ -2,17 +2,23 @@ package dev.caskeleton.adapter.inbound.web.auth;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import ch.qos.logback.classic.Logger;
|
||||
import ch.qos.logback.classic.spi.ILoggingEvent;
|
||||
import ch.qos.logback.core.read.ListAppender;
|
||||
import dev.caskeleton.shared.error.Category;
|
||||
import dev.caskeleton.shared.error.ClientErrorMessages;
|
||||
import java.io.IOException;
|
||||
import java.util.List;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.api.extension.ExtendWith;
|
||||
import org.slf4j.LoggerFactory;
|
||||
import org.springframework.boot.test.system.CapturedOutput;
|
||||
import org.springframework.boot.test.system.OutputCaptureExtension;
|
||||
import org.springframework.http.HttpHeaders;
|
||||
import org.springframework.mock.web.MockHttpServletRequest;
|
||||
import org.springframework.mock.web.MockHttpServletResponse;
|
||||
import org.springframework.security.authentication.InsufficientAuthenticationException;
|
||||
import org.springframework.security.core.AuthenticationException;
|
||||
import org.springframework.security.oauth2.core.OAuth2Error;
|
||||
import org.springframework.security.oauth2.core.OAuth2ErrorCodes;
|
||||
import org.springframework.security.oauth2.jwt.BadJwtException;
|
||||
@@ -106,6 +112,86 @@ class EnvelopeAuthenticationEntryPointTest {
|
||||
.isEqualTo("AUTH_JWKS_UNAVAILABLE");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aKeyServiceOutageIsLoggedAtError() throws Exception {
|
||||
// given
|
||||
AuthenticationException outage =
|
||||
new InvalidBearerTokenException(
|
||||
"invalid",
|
||||
new JwtDecoderConfig.AuthenticationKeyServiceUnavailableException(
|
||||
new IOException("connect timed out")));
|
||||
|
||||
// when
|
||||
List<ILoggingEvent> lines = writerLinesFor(outage);
|
||||
|
||||
// then
|
||||
assertThat(lines)
|
||||
.singleElement()
|
||||
.extracting(event -> event.getLevel().toString(), ILoggingEvent::getFormattedMessage)
|
||||
.containsExactly(
|
||||
"ERROR",
|
||||
"security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY"
|
||||
+ " method=GET path=/v1/things");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aDecoderMisconfigurationIsLoggedAtError() throws Exception {
|
||||
// given
|
||||
AuthenticationException misconfiguration =
|
||||
new InvalidBearerTokenException(
|
||||
"invalid",
|
||||
new JwtDecoderConfig.AuthenticationDecoderMisconfigurationException(
|
||||
new IllegalStateException("issuer metadata does not match")));
|
||||
|
||||
// when
|
||||
List<ILoggingEvent> lines = writerLinesFor(misconfiguration);
|
||||
|
||||
// then
|
||||
assertThat(lines)
|
||||
.singleElement()
|
||||
.extracting(event -> event.getLevel().toString(), ILoggingEvent::getFormattedMessage)
|
||||
.containsExactly(
|
||||
"ERROR",
|
||||
"security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL"
|
||||
+ " method=GET path=/v1/things");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aRejectedSignatureStaysAtWarn() throws Exception {
|
||||
// given
|
||||
AuthenticationException rejected =
|
||||
new InvalidBearerTokenException(
|
||||
"invalid", new BadJwtException("Signed JWT rejected: Invalid signature"));
|
||||
|
||||
// when
|
||||
List<ILoggingEvent> lines = writerLinesFor(rejected);
|
||||
|
||||
// then
|
||||
assertThat(lines)
|
||||
.singleElement()
|
||||
.extracting(event -> event.getLevel().toString(), ILoggingEvent::getFormattedMessage)
|
||||
.containsExactly(
|
||||
"WARN",
|
||||
"security failure: code=AUTH_TOKEN_INVALID_SIGNATURE category=AUTH"
|
||||
+ " method=GET path=/v1/things");
|
||||
}
|
||||
|
||||
/** The lines the security writer logs while the entry point answers {@code failure}. */
|
||||
private List<ILoggingEvent> writerLinesFor(AuthenticationException failure) throws Exception {
|
||||
Logger logger = (Logger) LoggerFactory.getLogger(AuthErrorResponseWriter.class);
|
||||
ListAppender<ILoggingEvent> appender = new ListAppender<>();
|
||||
appender.start();
|
||||
logger.addAppender(appender);
|
||||
try {
|
||||
entryPoint.commence(
|
||||
new MockHttpServletRequest("GET", "/v1/things"), new MockHttpServletResponse(), failure);
|
||||
} finally {
|
||||
logger.detachAppender(appender);
|
||||
appender.stop();
|
||||
}
|
||||
return appender.list;
|
||||
}
|
||||
|
||||
@Test
|
||||
void tokenValueNeverLeaksIntoResponseBodyOrLogs(CapturedOutput output) throws Exception {
|
||||
// §테스트 계약: a JWT value must never appear in the response or the log output.
|
||||
|
||||
+19
@@ -98,6 +98,25 @@ class OperationalErrorRegistryContractTest {
|
||||
assertThat(actual).isNotEmpty().isEqualTo(expected);
|
||||
}
|
||||
|
||||
/**
|
||||
* The log level is not a registry column. The failure's kind and path decide it — {@code
|
||||
* ServerFailureLog} on every transport, {@code AuthErrorResponseWriter} in the security filter —
|
||||
* not the code, so a per-row value can only drift from what is logged, as the column that was
|
||||
* removed did (docs/superpowers/specs/2026-11-06-error-code-log-level-design.md).
|
||||
*/
|
||||
@Test
|
||||
void noRegistryRowCarriesALogLevel() {
|
||||
List<String> rowsWithALogLevel =
|
||||
registryRows().stream()
|
||||
.filter(row -> row.containsKey("log_level"))
|
||||
.map(row -> String.valueOf(row.get("code")))
|
||||
.toList();
|
||||
|
||||
assertThat(rowsWithALogLevel)
|
||||
.as("%s rows with a log_level; the code decides the level, not the registry", REGISTRY)
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@SuppressWarnings("unchecked")
|
||||
private static List<Map<String, Object>> registryRows() {
|
||||
Object loaded = new Yaml(new SafeConstructor(new LoaderOptions())).load(read(REGISTRY));
|
||||
|
||||
Reference in New Issue
Block a user