diff --git a/docs/registries/error-codes.yaml b/docs/registries/error-codes.yaml index d569b16b..6b29101f 100644 --- a/docs/registries/error-codes.yaml +++ b/docs/registries/error-codes.yaml @@ -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 diff --git a/docs/runbooks/auth-token-invalid-signature.md b/docs/runbooks/auth-token-invalid-signature.md index ce057a1f..02051f53 100644 --- a/docs/runbooks/auth-token-invalid-signature.md +++ b/docs/runbooks/auth-token-invalid-signature.md @@ -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 diff --git a/docs/runbooks/authz-tenant-mismatch.md b/docs/runbooks/authz-tenant-mismatch.md index 1bd30beb..47747cd9 100644 --- a/docs/runbooks/authz-tenant-mismatch.md +++ b/docs/runbooks/authz-tenant-mismatch.md @@ -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 diff --git a/docs/superpowers/specs/2026-11-06-error-code-log-level-design.md b/docs/superpowers/specs/2026-11-06-error-code-log-level-design.md index dc736ed0..4392d283 100644 --- a/docs/superpowers/specs/2026-11-06-error-code-log-level-design.md +++ b/docs/superpowers/specs/2026-11-06-error-code-log-level-design.md @@ -1,6 +1,6 @@ # `error-codes.yaml`의 `log_level` 칸 — 설계 메모 -- 상태: **소유자 결정 대기** (2026-11-06). 결정할 것은 7절이다. +- 상태: **확정** (2026-11-06, 소유자 답 "권하는 안대로"). 결정은 10절이다. 아래 1~9절은 결정 전에 쓴 그대로 둔다. - 기준 커밋: `06f520e6` (`refactor/maturity-review-2026-11`) - 크기: 중간(brief). 이 메모가 고르는 안을 실제로 적용하는 일은 **큼**이다. 오류 코드 레지스트리는 공개 계약이라 파일 하나여도 큼이다(`docs/work/README.md` 2절). 그래서 이 메모는 대안 비교까지 하고 멈춘다. 코드와 yaml은 @@ -229,3 +229,17 @@ - `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절 「오류 코드 로그 레벨」. diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index 4c768e01..8bc96132 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -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`·`::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 diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 227e493b..c5ec382a 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -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 멱등성 diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/OperationalErrorRegistryContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/OperationalErrorRegistryContractTest.java index 5f561936..2e043b83 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/OperationalErrorRegistryContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/OperationalErrorRegistryContractTest.java @@ -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 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> registryRows() { Object loaded = new Yaml(new SafeConstructor(new LoaderOptions())).load(read(REGISTRY));