docs(contract): declare the provider key header, the shared 429 and 503, and the request id

[Eomdahyeon]

Refs #994

#1023(#1000) 위에 쌓은 PR 이다 (그 PR 은 #1022 위에 있다). base 를 그 브랜치로 잡아 이 PR 의 diff 만 보이게 했다. 과부하 503 의 code 가 #1023 에서 생기기 때문이다.

이 PR 이 하는 것 — #1009 가 "이 PR 에 없는 것"으로 남긴 세 항목 중 둘

1. X-Provider-Key 를 header 파라미터로 선언 — components.parameters.ProviderKey. 프로바이더를 호출하는 다섯 operation(previewBuild, createBuild, submitBuild, getProviderStatus, testProviderConnection)에 참조를 달았다. Studio 가 이 헤더를 보내는 호출과 같은 다섯이다.
2. 429 auth_throttled, 과부하 503, X-Request-ID — 어느 operation 에서나 나올 수 있으므로 SignupNotApproved 와 같은 방식(x-status 를 가진 공용 응답)으로 선언했다: components.responses.AuthThrottled, ServerOverloaded, 그리고 components.headers.RequestId.

계약 1.79.0 → 1.80.0. wire 는 바뀌지 않는다(선언만). response fixture 를 생성기로 다시 만들었다.

하지 않은 것

3. _DISPATCH_ROUTES 를 라우트 어댑터에서 생성 — docs(contract): declare the publish recovery routes #1009 본문이 적은 대로 라우트가 if 연쇄라 표로 바꾸는 리팩터링이 먼저다. 이 PR 범위에 넣지 않았다. 그래서 Refs.

X-Request-ID 는 헤더 컴포넌트로만 선언했고 각 operation 의 응답마다 참조를 달지는 않았다 — 모든 응답(수백 개)에 다는 것은 계약을 읽기 어렵게 만든다고 판단했다. 설명에 "핸들러가 쓰는 모든 응답에 실린다"고 적었다.

검증 — 선언과 실제를 대조한다

tests/unit/test_contract_shared_declarations.py:

• 파라미터의 이름이 코드의 PROVIDER_KEY_HEADER 와 같고, 참조한 operation 집합이 정확히 위 다섯이다
• _overloaded_response() 의 상태·본문·헤더가 ServerOverloaded 선언과 같다
• 인증 실패 한도를 넘긴 실제 응답의 상태·키·code 가 AuthThrottled 선언과 같다
• 실제 HTTP 응답에 X-Request-ID 가 있다

계약 관련 테스트 파일: 424 passed. check_contract_compat.py: origin/main 대비 1.77.0 -> 1.80.0 호환. ruff, mypy 통과. 전체 스위트는 CI 가 돌린다.

#1009 와의 관계

#1009 는 지금 main 과 충돌 상태다 — 내가 #1010 을 머지하면서 main 이 1.77.0 이 됐고, #1009 도 1.77.0 을 쓴다. 이 스택(#1022 → #1023 → 이 PR)은 1.78.0 ~ 1.80.0 을 쓴다. 어느 쪽이 먼저 들어가든 나중 쪽이 버전 줄을 다시 맞춰야 하니, 순서를 정해 주면 내 쪽을 그에 맞추겠다.

🤖 Generated with Claude Code

[Eomdahyeon]

머지 순서 주의. 이 PR 이 추가하는 에러 예시와 code 는 Studio 의 드리프트 검사(ERROR_READERS)가 아직 모른다. Builder main 에 들어가면 Studio 의 모든 PR 에서 Builder contract drift 가 실패한다 — 이 스택의 계약으로 Studio 드리프트 테스트를 돌려 확인했다(7개 실패). kpubdata-lab/kpubdata-studio#743 이 그 항목들을 버전 조건과 함께 추가하므로, #743 을 먼저 머지한 뒤 이 PR 을 넣어야 한다. #743 은 지금 Builder main(1.77.0)에서도 통과한다.

[yeongseon]

리뷰 (코멘트 — #1023 위에 쌓인 PR 이고 체크가 도는 중이라 승인은 그 뒤에).

diff 를 읽었고 걸리는 점이 없습니다. 선언마다 실제 응답과 대조하는 테스트가 있고(_overloaded_response() 의 상태·본문·헤더, 한도를 넘긴 실제 429, 실제 HTTP 응답의 X-Request-ID), ProviderKey 를 참조하는 operation 집합을 정확히 다섯으로 고정했습니다. X-Request-ID 를 응답마다 달지 않고 헤더 컴포넌트로만 둔 판단도 동의합니다.

본문이 물은 순서 — 이 스택을 먼저 넣습니다. #1022 → (studio#743) → #1023 → #1024 순으로 1.78.0 ~ 1.80.0 을 쓰고, #1009 는 그 뒤에 리베이스해서 다음 번호(1.81.0)를 씁니다. #1009 는 어차피 지금 충돌 상태라 다시 손봐야 하고, 이 스택은 그대로 들어갈 수 있습니다. 이쪽 버전 줄은 바꿀 필요 없습니다.

로컬에서 테스트를 돌리지는 않았습니다.