# Registry: HTTP Headers # Schema owner: feature-contract-registry-governance # Last updated: 2026-05-22 # # 표기 규칙 # - HTTP 헤더 이름: kebab-case (X-Request-Id, X-Correlation-Id) # - W3C 표준 헤더: 소문자 (traceparent, tracestate) # - mdc_key: snake_case (foundation이 정본) # - envelope_meta_field: camelCase (envelope이 정본) # - 행은 코드가 실제로 읽거나 쓰는 헤더다. `source`는 셋 중 하나다(HeaderRegistryRuntimeAlignmentTest가 대조한다). # - main 파일 경로: 그 이름 글자를 가지고 실제로 쓰는 파일. 이름이 상수면 그 상수를 쓰는 곳이 있어야 한다. # - `service: <경로>`: 서비스 controller가 읽으라고 둔 `ApiHeaders` 상수다. 템플릿 main은 그 상수를 쓰지 않는다 # (파일 서버는 If-Match·If-None-Match를 Spring `HttpHeaders` 상수로 읽는다). 시험이 정한 헤더만 이 출처를 쓴다. # - `framework: …`: Spring·라이브러리가 읽거나 쓴다. headers: # source: feature-operational-error-observability-foundation.md L97 # "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id" - name: X-Request-Id direction: both type: uuid-or-caller-token format: "UUID; 받는 값은 [A-Za-z0-9._-]{1,128}" required: false generated_if_missing: true mdc_key: request_id envelope_meta_field: requestId owner_branch: feature-operational-error-observability-foundation case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java" # source: feature-api-contract-baseline.md L77 / feature-rate-limit-idempotency-contract.md L66-67 # "idempotency header 이름은 Idempotency-Key" / "기본 scope는 (authenticatedPrincipal, idempotencyKey, useCaseName)" - name: Idempotency-Key direction: inbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: feature-rate-limit-idempotency-contract case_style: kebab compatibility_impact: additive required_test: contract-verification:idempotency-replay source: "service: src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" # source: feature-rate-limit-idempotency-contract.md L85 / foundation L85 # "RATE_LIMIT | ... | 429 | true (Retry-After 이후)" / "retry-after 기준 없이 429를 반환하면 실패" - name: Retry-After direction: outbound type: duration-seconds required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: feature-rate-limit-idempotency-contract case_style: kebab compatibility_impact: additive required_test: contract-verification:rate-limit-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) # app.rate-limit.enabled=true인 요청 경로에서만 생성되는 rate-limit 응답 표면 - name: X-RateLimit-Limit direction: outbound type: numeric required: false generated_if_missing: true mdc_key: null envelope_meta_field: null owner_branch: feature-rate-limit-idempotency-contract case_style: kebab compatibility_impact: additive required_test: contract-verification:rate-limit-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) - name: X-RateLimit-Remaining direction: outbound type: numeric required: false generated_if_missing: true mdc_key: null envelope_meta_field: null owner_branch: feature-rate-limit-idempotency-contract case_style: kebab compatibility_impact: additive required_test: contract-verification:rate-limit-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" # source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준) - name: X-RateLimit-Reset direction: outbound type: rfc3339-date required: false generated_if_missing: true mdc_key: null envelope_meta_field: null owner_branch: feature-rate-limit-idempotency-contract case_style: kebab compatibility_impact: additive required_test: contract-verification:rate-limit-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" # source: feature-distributed-tracing-contract.md L64, L85 # "propagation header는 W3C traceparent default" / "HTTP | traceparent, tracestate (W3C)" - name: traceparent direction: both type: string required: false generated_if_missing: true mdc_key: trace_id envelope_meta_field: traceId owner_branch: feature-distributed-tracing-contract case_style: kebab compatibility_impact: none required_test: contract-verification:trace-propagation source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java" # source: feature-distributed-tracing-contract.md L66, L85 # "propagation format = W3C traceparent + tracestate only. B3 propagation은 forbidden" - name: tracestate direction: both type: comma-separated required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: feature-distributed-tracing-contract case_style: kebab compatibility_impact: none required_test: contract-verification:trace-propagation source: "framework: Micrometer Tracing(OTel)의 W3C 전파가 traceparent와 함께 읽고 쓴다" # source: feature-operational-error-observability-foundation.md L100 # "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id" - name: X-Correlation-Id direction: both type: uuid-or-caller-token format: "UUID; 받는 값은 [A-Za-z0-9._-]{1,128}" required: false generated_if_missing: true mdc_key: correlation_id envelope_meta_field: correlationId owner_branch: feature-operational-error-observability-foundation case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java" # source: feature-security-operational-baseline.md L66 # "JWT Resource Server를 baseline security model로 둠" (Authorization 헤더의 Bearer 토큰) - name: Authorization direction: inbound type: bearer-token required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: feature-security-operational-baseline case_style: kebab compatibility_impact: none required_test: contract-verification:jwt-resource-server source: "framework: Spring Security bearer token resolver가 읽는다" # source: feature-security-operational-baseline.md L83-90 (AuthN/AuthZ Decision Matrix) # 401 응답 시 WWW-Authenticate (Bearer realm/error) — Spring Security JWT Resource Server의 표준 challenge 헤더 - name: WWW-Authenticate direction: outbound type: string required: false generated_if_missing: true mdc_key: null envelope_meta_field: null owner_branch: feature-security-operational-baseline case_style: kebab compatibility_impact: none required_test: contract-verification:jwt-resource-server source: "framework: HttpHeaders.WWW_AUTHENTICATE(AuthErrorResponseWriter가 401에 쓴다)" # === web 응답·조건부 요청 (adapter:inbound:web) === # 모든 응답에 no-store(CacheControlFilter). 파일 다운로드는 자기 값을 쓴다. - name: Cache-Control direction: outbound type: string required: false generated_if_missing: true mdc_key: null envelope_meta_field: null owner_branch: web-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" - name: Vary direction: outbound type: comma-separated required: false generated_if_missing: true mdc_key: null envelope_meta_field: null owner_branch: web-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" # 405 응답(GlobalExceptionHandler). - name: Allow direction: outbound type: comma-separated required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: web-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "framework: Spring HttpHeaders.setAllow — GlobalExceptionHandler가 405 응답에 쓴다(ApiHeaders.ALLOW는 쓰지 않는다)" # 201 생성 응답(durable operation, 파일 업로드). - name: Location direction: outbound type: uri required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: web-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" - name: ETag direction: outbound type: entity-tag required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: web-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" - name: If-Match direction: inbound type: entity-tag required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: web-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "service: src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" - name: If-None-Match direction: inbound type: entity-tag required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: web-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "service: src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java" # Redis 세션(쿠키) 모드의 CSRF 헤더 기본 이름. - name: X-XSRF-TOKEN direction: inbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: web-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/settings/SecuritySettings.java" # === 파일 서버 업로드·다운로드 (composition:fileserver-platform을 켤 때) === # Range·If-Range·Content-Range·Accept-Ranges·Content-Disposition·Last-Modified·If-Modified-Since·If-Unmodified-Since는 # HTTP 표준 헤더를 Spring HttpHeaders 상수로 쓴다(MvcDownloadResponseWriter, MvcConditionalRequestFactory). 아래는 이 플랫폼이 # 이름을 정한 헤더다. - name: Tus-Resumable direction: both type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java" - name: Tus-Version direction: outbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java" - name: Tus-Extension direction: outbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java" - name: Tus-Max-Size direction: outbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java" - name: Upload-Defer-Length direction: inbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java" - name: Upload-Metadata direction: inbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java" - name: Upload-Expires direction: outbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java" - name: Upload-Checksum direction: inbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java" - name: Upload-Offset direction: both type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java" - name: Upload-Length direction: both type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java" - name: Upload-Complete direction: both type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java" - name: Upload-Limit direction: outbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java" # raw·draft-12 업로드의 원래 파일 이름. - name: X-Filename direction: inbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12UploadController.java" - name: X-Content-Sha256 direction: inbound type: string required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/mapper/RawUploadRequestMapper.java" # 앞단 nginx에만 주는 내부 헤더다. nginx가 지우고 client에는 가지 않는다. - name: X-Accel-Redirect direction: outbound type: uri required: false generated_if_missing: false mdc_key: null envelope_meta_field: null owner_branch: fileserver-platform case_style: kebab compatibility_impact: none required_test: contract-verification:envelope-headers source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/nginx/NginxDownloadStrategy.java"