# HTTP wire 계약 이 백엔드의 HTTP 응답을 읽는 클라이언트(짝 프론트, 파생 서비스의 다른 앱)가 기대해도 되는 것을 한 곳에 적는다. 응답 모양과 멱등성 응답의 뜻은 이 문서가 정본이다. 다른 문서(web README 예외 표, `docs/web/runbook.md`, `docs/registries/error-codes.yaml` 주석)는 이 문서를 가리키고 같은 문장을 쓴다. 코드가 이 문서를 지키는지는 다음 테스트가 확인한다. - 응답 원문의 키 집합: `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeWireShapeTest.java` - 핸들러 밖 오류(`/error` 디스패치)의 실패 Envelope: 실제 컨테이너에서 `WebContractAssertions` (`TomcatWebContractIT`·Jetty lane), 기본 JWT 체인에서 `JwtChainErrorDispatchIT` - 멱등성 응답의 status·code·retryable·`Retry-After`: `IdempotencyExceptionMappingTest`, `RetryAfterAdvisorTest`, `OperationalErrorTest`, 키 형식은 `IdempotencyKeyHeaderTest`, 실행 전 거부와 결과 불명의 구분은 `IdempotencyExecutorTest`, lease 하한은 `IdempotencySettingsTest` - 헤더 규칙(3절): `WebMvcRequestIdFilterTest`, `CorsSecurityFilterIntegrationTest` - web 전용 코드(4절): `TransportErrorHandlingTest`, `IdempotencyKeyHeaderTest`, web-advanced `WebAdvancedErrorMappingTest` ## 1. Envelope 키 존재 규칙 JSON 응답은 모두 `Envelope` 하나의 모양이다(소유자 결정 2). **값이 `null`인 필드는 키째 생략한다.** 빈 목록(`[]`)은 `null`이 아니므로 생략하지 않는다. | 응답 | 최상위 키 | 없는 키 | | --- | --- | --- | | 성공 | `success`(=`true`), `data`, `meta` | `error` | | 실패 | `success`(=`false`), `error`, `meta` | `data` | | bulk 전체 성공 | `success`(=`true`), `results`, `meta` | `error` | | bulk 부분 실패 | `success`(=`false`), `error`(`code=BATCH_PARTIAL_FAILURE`, `details`=항목별 결과), `meta` | `results` | - `success`가 판별자다. 클라이언트는 `success`로 갈라 읽고, 키가 있는지로 판단하지 않는다. - 성공인데 `data`가 `null`이면 `data` 키도 없다. 본문이 아예 없는 응답(204)은 Envelope가 아니다. - 컨트롤러가 `String`을 반환해도 JSON을 요청하면(`Accept: application/json`) 같은 Envelope로 나간다 (`"data": "<문자열>"`). 텍스트를 요청하면 문자열 그대로다. - 빈 컬렉션 결과는 `"data": []`, 빈 bulk 결과는 `"results": []`, 항목 없는 부분 실패는 `"details": []`로 나간다. ### `error` 키 | 키 | 항상 있음 | 뜻 | | --- | --- | --- | | `code` | 예 | 안정된 기계용 식별자. 클라이언트는 이것으로 분기한다 | | `category` | 예 | `Category` enum 이름(`VALIDATION`, `CONFLICT` …) | | `message` | 예 | 사용자에게 보여도 되는 한국어 문구(`ClientErrorMessages`). 분기에 쓰지 않는다 | | `retryable` | 예 | 같은 요청을 다시 보내도 안전하고 의미가 있는지 | | `details` | 아니오 | 코드별 구조 정보(검증 실패 필드 목록, bulk 항목 결과). 없으면 키도 없다 | ### `meta` 키 | 키 | 언제 있나 | | --- | --- | | `requestId` | 요청 id 필터(`WebMvcRequestIdFilter`)를 지난 모든 응답 | | `traceId` | 위와 같음. 추적이 꺼져 있어도 필터가 만든 W3C trace id가 들어간다 | | `correlationId` | 위와 같음. 값이 없으면 키가 없다 | | `page` | 페이지 목록 응답에만. `number`·`size`·`total`·`sort`(미정렬이면 `sort: null`) | 컨트롤러에 닿기 전에 거부된 요청(보안 방화벽이 막은 경로, 필터의 `sendError`, 필터가 던진 예외)도 같은 실패 Envelope다. 컨테이너가 `/error`로 넘긴 요청을 `EnvelopeErrorController`가 status에 맞는 코드로 답한다. 본문에 요청 경로나 시각을 싣지 않는다. 기본 JWT 체인에서도 익명 400이 401로 바뀌지 않는다(재리뷰 RR-02-02). 다만 요청 id 필터를 지나기 전에 끊긴 응답은 `meta`의 id 키가 빠질 수 있다. 클라이언트는 `meta`의 모르는 키를 무시한다. status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간다: 401·403·404·405·406·412·413·414·415·429·503. 표에 없는 status는 그 class의 코드로 접힌다 — 4xx(408·409·410·422 등)는 `BAD_PARAMETER` 400, 5xx(501·502·504 등)는 `INTERNAL_ERROR` 500(재리뷰 RR-01-13, `EnvelopeErrorControllerTest`). `error.code`와 status가 registry (`docs/registries/error-codes.yaml`)와 어긋나지 않게 하려는 것이다. 클라이언트는 status가 아니라 `error.code`로 가르기 때문이다. 필터가 다른 status를 내야 하면 `sendError` 대신 그 status의 코드로 `EnvelopeResponseWriter`를 쓰거나, 표에 행을 더한다. 4xx·5xx status로 나가는 본문은 `success:true`로 감싸지 않는다. 실패 Envelope가 아닌 본문을 오류 status로 돌려주는 핸들러는 그 본문이 그대로 나간다. ### 왜 이렇게 나가는가 `Envelope`·`BulkEnvelope`·`ApiError`·`ResponseMeta`는 `shared-contract`에 있고, 이 leaf는 Java 표준 라이브러리 외에는 의존하지 않는다. 그래서 `@JsonInclude`를 타입에 붙이지 않고, web 어댑터의 `EnvelopeWireFormatConfig`가 Jackson mix-in으로 같은 규칙을 Boot의 `JsonMapper`에 등록한다. 이 어댑터의 모든 HTTP writer(MVC 변환기, 보안 entry point, rate-limit interceptor)가 그 `JsonMapper`를 쓴다. GraphQL·STOMP·gRPC는 이 타입들을 직렬화하지 않으므로 이 규칙의 영향을 받지 않는다. ## 2. 멱등성 응답 `Idempotency-Key`를 받는 쓰기 엔드포인트(KEYED)는 `IdempotencyExecutor`를 거친다. 같은 키로 다시 보낸 요청은 서버가 아래 넷 중 하나로 판정한다. 키는 인증 주체와 operation 범위 안에서만 같은 키다. | 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 | | --- | --- | --- | --- | --- | --- | | 재생(replay): 같은 키·같은 본문, 첫 요청 완료 | 첫 요청과 같은 성공 status | — (성공 Envelope) | — | 없음 | 첫 요청의 결과로 받아들인다. `meta`의 id는 이번 요청의 것이다 | | 처리 중(in-flight): 같은 키, 첫 요청이 아직 실행 중(Redis 저장소. PostgreSQL 저장소는 409 대신 첫 요청이 끝날 때까지 기다린다 — 아래 "첫 시도가 lease보다 오래 걸릴 때") | 409 | `IDEMPOTENT_IN_FLIGHT` | `true` | `2` | 결과 불명. **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송한다. **새 키 금지** | | 본문 불일치(mismatch): 같은 키·다른 본문 | 422 | `IDEMPOTENT_REQUEST_MISMATCH` | `false` | 없음 | 클라이언트 버그. 다시 보내지 않는다. 새 작업이면 새 키를 만든다 | | 키 누락·형식 오류 | 400 | `IDEMPOTENCY_KEY_INVALID` (`details.reason` = `MISSING`/`MALFORMED`) | `false` | 없음 | 문법에 맞는 키를 붙여 다시 보낸다 | - **처리 중을 `retryable=true`로 두는 이유.** 같은 키 재전송은 서버가 재생·처리 중·불일치로 안전하게 판정하므로, 다시 보내는 것이 맞는 행동이다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못해, 첫 요청이 끝나면 같은 작업이 두 번 적용된다. - **`Retry-After: 2`의 근거.** 기본 processing lease(`app.capabilities.idempotency.processing-lease`, 30s)보다 짧아, 첫 시도가 아직 끝날 수 있는 동안 다시 묻는다. 너무 이르면 409를 한 번 더 받을 뿐이고 결과가 바뀌지는 않는다. 값은 `IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER` 하나이고 `RetryAfterAdvisor`가 그 값을 쓴다. `processing-lease`를 이 값(2초) 이하로 설정하면 기동이 실패한다(`IdempotencySettings`, 재리뷰 RR-02-05). - executor는 기다리지 않는다. 처리 중이면 바로 409를 돌려준다. 키로 결과를 조회하는 엔드포인트는 없다. - **키 문법**: 보이는 ASCII(`0x21`–`0x7E`) 1~256자. 서버는 trim하거나 고치지 않는다. 짝 프론트의 `isValidIdempotencyKey`와 같은 규칙이다. KEYED 엔드포인트는 모두 `IdempotencyKeyHeader.parse`로 헤더를 읽어 같은 코드로 거부한다(리뷰 02-12). 키 원문은 응답에 돌려 쓰지 않는다. 키를 요구하지 않는 엔드포인트는 키 없이 보호 없이 실행된다. 같은 executor가 내는 나머지 세 실패. 저장소가 응답하지 않은 경우는 **언제** 멈췄는지로 코드가 갈린다. | 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 | | --- | --- | --- | --- | --- | --- | | 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음. 또는 claim의 processing lease가 작업 시작 전에 끝나 저장소가 시작을 거절함 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다(다음 요청이 그 claim을 넘겨받아 실행한다) | | 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | "적용되지 않았다"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 | | 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 자동 재시도하지 않는다. 같은 키 재전송은 안전하다 — 서버는 효과가 있었을 수 있는 작업을 다시 돌리지 않고, 첫 시도가 늦게 끝났으면 그 결과를 재생하며, 효과 없이 끝났으면 실행하고, 아니면 다시 500이다. 결과는 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차(`docs/runbooks/idempotency-unavailable.md`)에 따라 새 키로 다시 보낸다 | - **결과 불명이 무엇을 뜻하나.** 작업은 이미 돌았다. 유스케이스가 executor를 쓰기 트랜잭션 안에서 불렀다면 그 트랜잭션의 DB 변경은 예외와 함께 롤백된다. 작업이 자기 트랜잭션을 따로 커밋했다면 그 변경은 남는다. 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 일어났을 수 있다. 그래서 실행 전 거부와 같은 503이어도 code가 다르다. 클라이언트는 status가 아니라 `error.code`로 가른다. - **같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다.** 결과가 실제로는 기록됐으면 재생(첫 요청의 성공 응답), 첫 시도의 processing lease(`processing-lease`, 기본 30s)가 아직 남았으면 409 `IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. 이것은 Redis 저장소의 판정이다. PostgreSQL 저장소는 아래처럼 첫 요청이 끝날 때까지 기다린 뒤 판정한다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못한다(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정 RR-01-11). - **첫 시도가 lease보다 오래 걸릴 때 — 저장소마다 다르다.** executor는 lease를 늘리지 않으므로 30s를 넘는 정상 요청도 lease가 지난다(재리뷰 2026-11-04 RR5-01-05). - Redis: lease가 지난 실행 기록을 다음 요청이 만나면 500으로 답하고 기록은 건드리지 않는다. 첫 시도가 그 뒤에 끝나면 결과가 그대로 기록되고, 첫 요청은 자기 응답을 정상으로 받는다. 그 뒤 같은 키 요청은 그 결과를 재생한다. 첫 시도가 실패를 보고하면 먼저 온 보고 하나가 기록된다(효과 불명이면 계속 500, 효과 없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다). 기록이 이미 사라진 뒤에 끝나면 결과를 기록하지 못해 첫 요청도 500 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받는다(2026-11-04 소유자 결정). - PostgreSQL: 템플릿처럼 executor를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면 claim 기록은 그 트랜잭션이 끝날 때 함께 커밋되거나 롤백된다. 그래서 같은 키 요청은 409나 500을 받지 않고 그 기록에서 기다린다. 첫 트랜잭션이 커밋되면 재생을, 롤백되면 새 실행을 받는다. lease가 지나도 같다. 작업이 실패해 예외로 끝난 요청은 executor가 남긴 실패 기록도 함께 롤백되므로, 효과 불명 실패도 다음 같은 키 요청이 다시 실행한다. 또 쓰기 트랜잭션 제한(`app.persistence-jpa.transaction.write-timeout`, 기본 30s — 기본 lease와 같다, 업그레이드 안내 B-21)이 두 요청에 모두 걸린다. 첫 요청이 그보다 오래 걸리면 취소되고 claim 기록도 함께 롤백된다(503 `DB_QUERY_CANCELED`). 기다리던 요청도 자기 제한을 넘기면 같은 코드로 끝난다. 어느 경우든 롤백된 DB 변경은 남지 않지만, 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 다음 같은 키 요청에서 두 번 일어날 수 있다. 이 저장소가 막는 중복은 같은 트랜잭션 안의 DB 효과다 (`PostgreSqlIdempotencyIntegrationTest`). - **서버가 기억하는 기간.** 위 판정은 기록이 남아 있는 동안만 선다. 기록이 사라지면 같은 키는 새 요청으로 실행된다. 기록의 수명은 시도가 어떻게 끝났는지로 갈린다. - 완료된 응답: 완료부터 `replay-ttl`(`APP_IDEMPOTENCY_TTL`, 기본 24h). - 끝나지 않은 시도: claim부터 processing lease + `replay-ttl`. lease가 지난 실행 기록도 이 수명을 그대로 쓴다. 그 사이 첫 시도가 끝나면 그때부터 위(완료)나 아래(실패)의 수명으로 바뀐다. - 실패로 표시된 시도: 작업이 예외를 던졌거나 효과 불명으로 끝나 포기(abandoned)된 시도, 효과 없이 재시도 가능으로 끝난 시도. 표시한 때부터 `failure-retention`(`APP_IDEMPOTENCY_FAILURE_RETENTION`, 기본 24h). PostgreSQL 저장소를 쓰기 트랜잭션 하나 안에서 쓰면 실패 기록은 요청의 롤백과 함께 사라져 남지 않는다(위 PostgreSQL 항목). `replay-ttl`이 `processing-lease`보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11). `failure-retention`이 `replay-ttl`보다 짧아도 기동이 실패한다. 더 짧으면 효과 불명으로 포기한 기록이 그만큼 먼저 사라지고, 그 뒤 같은 키 재전송은 작업을 다시 돌린다(재리뷰 2026-11-04 RR3-03-02, 2026-11-04 소유자 결정). ## 3. 헤더 ### 요청 id·correlation id | 헤더 | 방향 | 규칙 | | --- | --- | --- | | `X-Request-Id` | 응답(항상) | 서버가 만든다. 신뢰 설정(`app.web.mvc.trust-inbound-request-id`)일 때만 요청 값을 받는다 | | `X-Correlation-Id` | 요청·응답(항상) | 요청 값이 `[A-Za-z0-9._-]{1,128}`(앞뒤 공백 제거 후)이면 그대로 잇고, 아니면 서버가 새로 만든다. 고치지 않고 바꾼다 | | `traceparent` | 요청·응답(항상) | 유효한 W3C 값이면 잇고, 아니면 새로 만든다 | 세 값은 응답 `meta`의 `requestId`·`correlationId`·`traceId`와 같다. 셋 다 짝 프론트의 `[A-Za-z0-9._:-]{1,128}` 안에 든다. ### 브라우저가 읽을 수 있는 응답 헤더(CORS) CORS가 켜져 있으면(`app.cors.enabled=true`) cross-origin 실제 응답의 `Access-Control-Expose-Headers`에 아래가 들어간다. 이 목록 밖의 헤더(안전 목록 `Cache-Control`·`Content-Type` 등 제외)는 브라우저 코드에서 `null`로 보인다. - 플랫폼(`CorsExposedHeaders.PLATFORM`): `Retry-After`, `X-Request-Id`, `X-Correlation-Id`, `traceparent`, `Location`, `ETag`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` - fileserver를 실은 배포: `Tus-Resumable`, `Tus-Version`, `Tus-Extension`, `Tus-Max-Size`, `Upload-Offset`, `Upload-Length`, `Upload-Defer-Length`, `Upload-Expires`, `Upload-Complete`, `Upload-Limit`, `Content-Disposition`, `Accept-Ranges` 새 응답 헤더를 쓰는 모듈은 `CorsExposedHeaders` bean으로 자기 헤더를 기여한다. ## 4. web 전용 오류 코드 `OperationalError`(`docs/registries/error-codes.yaml`) 밖에서 HTTP 어댑터가 내는 코드다. | 코드 | status | category | `retryable` | `Retry-After` | 언제 | | --- | --- | --- | --- | --- | --- | | `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. GraphQL도 같은 이름을 쓰지만 그쪽 `category`는 GraphQL 전용 어휘 `TIMEOUT`이다(`src/adapter/inbound/graphql/README.md`) | | `IDEMPOTENCY_KEY_INVALID` | 400 | `VALIDATION` | `false` | 없음 | 2절 | | `RATE_LIMIT_UNAVAILABLE` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 있음 | rate-limit 저장소 응답 없음(`docs/web/runbook.md`) | | `RATE_LIMIT_INCOMPATIBLE` | 503 | `INTERNAL` | `false` | 없음 | rate-limit 제공자가 계약과 맞지 않음 | - 컨트롤러 파라미터 제약 위반(`@RequestParam @Max(10)`)은 요청 본문 위반과 같은 `400 VALIDATION_FAILED`이고 `details`는 `[{field, code, message}]`다. 거절된 값은 싣지 않는다. - web-advanced를 실은 서비스의 예외 코드(`ADMISSION_REFUSED` 503 등 10종)는 `src/adapter/inbound/web-advanced/README.md` 「오류 응답」이 정본이다. - 직접 쓰는 거부 응답(401·403·429·503)도 컨트롤러 응답과 같이 `application/json;charset=UTF-8`이다. ## 5. 바꿀 때 - 응답 키를 더하거나 빼면 `EnvelopeWireShapeTest`와 이 문서 1절을 같이 고친다. - 응답 헤더를 새로 쓰면 `CorsExposedHeaders`에 넣고 3절을 고친다. - 멱등성 코드의 status·retryable·`Retry-After`를 바꾸면 `OperationalError`, `RetryAfterAdvisor`, `docs/registries/error-codes.yaml`, 이 문서 2절을 같은 변경에서 고친다. 공유 코드의 `retryable`은 gRPC trailer(`error-retryable`)와 GraphQL extension(`retryable`)에도 그대로 나가므로 그 둘의 README와 매핑 테스트(`GrpcStatusMapperTest`, `GraphQlWireErrorMapperTest`)도 같이 본다. - 짝 프론트의 백엔드 계약 문서(`clean-architecture-frontend-template` `docs/architecture/backend-api-and-server-state-contract.md` §4.1·§6)는 이 문서를 가리켜야 한다.