문제: pin(45d2a478)이 백엔드 main보다 한참 뒤라 drift 검사가 exit 1이다. 그사이 백엔드가 폴더를 다시 배치하고(scaffold 원본 셋의 경로) 샘플을 지웠다. 계약 문서 6.1절 근거 파일 넷과 위치 목록이 main에 없고, 매뉴얼 04는 pin과 다른 bbe944bd를 기준이라 적는다. Fileserver 업로드 client의 게시 전 5xx 표는 pin 대조 밖이다(1105/01-02). 백엔드 697e62e8c부터 fileserver의 permit·pool 포화가 429에서 503 SERVER_BUSY로 바뀌어, client는 작업 전에 거절된 업로드를 결과 불명으로 읽는다. 고른 방법(R9-D4): - pin, 답 표 source, 표 사본(--write-excerpt)을 d32b4b53으로 옮긴다. §4의 새 행 404 OPERATION_NOT_FOUND는 durable operation 조회의 답이라 notCopied에 이유와 함께 둔다. - scaffold 원본 세 경로를 새 위치로 고친다(내용 0줄 변경 확인). - pin에 backend.codeSources를 더한다. Fileserver code 파일과 게시 전 5xx 표(codes)를 적고, readers에 fileserver-upload.ts를 넣는다. drift 검사가 그 파일들의 변경과, pin 커밋에 없는 경로(옮겨진 파일)를 알린다. pin 시험이 client 표와 pin 사본을 양쪽으로 대조한다. - NOT_APPLIED_5XX_CODES에 SERVER_BUSY를 더한다. raise 자리 둘 (TransferAdmissionController, BlockingTransferExecutor)이 모두 작업 전이다. - 6.1절 표의 백엔드 파일:줄을 d32b4b53에서 다시 찾았다. 판정은 같다. 샘플과 함께 사라진 근거(참조 도메인 행, WorkLogWebMapper 등)는 뺐고, 새 출처(PatchBodies, 알림 컨트롤러 필드 거절)를 적었다. - 매뉴얼 04의 기준을 pin으로 바꾸고 백엔드 경로 셋을 고친다. 버린 대안: 문서만 옛 pin 기준으로 맞추기 — drift 검사는 계속 막힌다. 위험·한계: V3 경로의 503 SERVER_BUSY는 상태만 정해진 모든 503에도 붙어 code로 단계를 가를 수 없다. 그래서 V3 표에 넣지 않고 결과 불명 쪽에 둔다(6.1절). 백엔드 main은 계속 움직이므로 다음 백엔드 병합 뒤 drift가 다시 1일 수 있다(설계된 신호). 검증: 노트북, 공유 clone(d32b4b53)으로 node scripts/check-backend-contract-drift.ts --backend <clone>: 옮기기 전 exit 1(문서·scaffold 4건), 옮긴 뒤 exit 0. desktop RED — pin·drift· 업로드 표 시험이 고치기 전 코드에서 실패 (/tmp/claude-gates/r9b-pr1-red/exec_node.log). merge 단계는 PR 본문. Refs: 1112/02-05, 1112/08-18, 1105/01-02
39 lines
3.9 KiB
JSON
39 lines
3.9 KiB
JSON
{
|
|
"schemaVersion": 1,
|
|
"source": {
|
|
"repository": "clean-architecture-backend-template",
|
|
"commit": "d32b4b53de734aca7d76dc08acf6e97bea899672",
|
|
"document": "docs/web/http-contract.md"
|
|
},
|
|
"sections": {
|
|
"2": [
|
|
[
|
|
"| 경우 | 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` | 없음 | 문법에 맞는 키를 붙여 다시 보낸다 |"
|
|
],
|
|
[
|
|
"| 경우 | 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`)에 따라 새 키로 다시 보낸다 |"
|
|
]
|
|
],
|
|
"4": [
|
|
[
|
|
"| 코드 | status | category | `retryable` | `Retry-After` | 언제 |",
|
|
"| --- | --- | --- | --- | --- | --- |",
|
|
"| `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. 그 밖의 503(필터의 `sendError(503)` 등)은 공용 `SERVER_BUSY`다. 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 제공자가 계약과 맞지 않음 |",
|
|
"| `OPERATION_NOT_FOUND` | 404 | `NOT_FOUND` | `false` | 없음 | durable operation 조회(`DurableOperationController`)에서 그 operation이 없거나 다른 호출자의 것이다. 둘을 가르지 않는다 |"
|
|
]
|
|
]
|
|
}
|
|
}
|