fix(browser-transfer): keep the resourceId of a completed or lost-complete upload (01-02)

A failed checkpoint cleanup after a committed complete returned a failure and
dropped the resourceId, and abort() on ALREADY_COMPLETED returned no id. The
upload now succeeds, abort() reads the id from status first, and the port and
design doc state the in-progress complete contract (429 + Retry-After).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:11:04 +09:00
co-authored by Claude Opus 5.5
parent 5cc1d002d2
commit 7b2cefbd32
4 changed files with 308 additions and 7 deletions
@@ -327,6 +327,42 @@ signed URL이나 receipt를 포함하거나 저장하지 않으며 server state
reconcile에서 server 상태를 확인한다. backend는 만료된 orphan multipart를
정리하는 TTL job을 가져야 한다.
complete 결과를 모를 때 클라이언트는 다음처럼 동작한다.
- complete 응답을 잃으면(시간 초과, 연결 끊김) `upload()`는 같은 COMPLETE key로
`maxRetries`번 다시 보낸 뒤 `UNAVAILABLE/UPLOAD_COMPLETE, retryable:true`를
돌려준다. 모든 part가 수락된 checkpoint는 남는다
(`resumable-upload-runtime.ts` `completeUpload`).
- 같은 파일로 `upload()`를 다시 부르면 `GET_STATUS`가 `QUARANTINED`일 때
resourceId와 `replayed:true`를 돌려준다. `ACTIVE`이면 같은 key로 complete를
다시 보낸다.
- `abort()`에 서버가 `ALREADY_COMPLETED`로 답하면 checkpoint를 지우기 전에
`GET_STATUS`로 resourceId를 읽어 `{ state: "ALREADY_COMPLETED", resourceId }`로
돌려준다. status 조회가 일시적으로 실패하면 `ABORT_PENDING` checkpoint를 남기고
실패를 돌려준다. `abort()`를 다시 부르면 된다. 서버가 session을 모르면(404/410)
resourceId 없이 닫는다(`resumable-upload-runtime.ts` `readCompletedResourceId`).
- 서버가 complete를 반영한 뒤 로컬 checkpoint 삭제가 실패해도(IndexedDB 오류,
complete 직후 caller abort) `upload()`는 성공을 돌려준다. 남은 행은 다음
`upload()`나 `abort()`가 같은 자원으로 정리한다.
서버 계약 — complete 진행 중(`ResumableUploadControlPlane.complete` 주석):
- 같은 COMPLETE key의 complete가 아직 끝나지 않았으면 서버는 `429`와
`Retry-After`로 답한다. 값은 전송과 runtime의 `maxRetryAfterMs`(기본 30초)
이하여야 한다. 클라이언트는 이것을 `UNAVAILABLE, retryable:true`로 읽고 그만큼
기다린 뒤 같은 key로 다시 보낸다(`fetch-json-transport.ts` `statusFailure`).
`Retry-After`가 없거나 상한을 넘으면 재시도하지 않는다. `503`도 재시도되지만
`Retry-After`는 읽지 않는다.
- `409`는 쓰지 않는다. 클라이언트는 `409`를 `CONFLICT, retryable:false`로 읽고
멈춘다.
- 그동안 `GET_STATUS`는 `ACTIVE`(모든 part 수락)를 유지하고, 자원이 확정된 뒤에만
`QUARANTINED`와 resourceId를 준다. 클라이언트 status 계약(`UploadSessionStatus`)에는
"완료 중" 값이 없고, 모르는 state는 `INTEGRITY_FAILED`로 거절한다.
- 서버 문서의 `OPERATION_IN_PROGRESS`(`server-file-capability-infrastructure.md`
8.2, 11.1)는 이 wire 표현으로 내보낸다.
- 재시도가 모두 끝나도 진행 중이면 `upload()`는 `UNAVAILABLE/RESUME`을 돌려주고
checkpoint가 남는다. 다음 `upload()`나 `abort()`가 위 순서로 조정한다.
application-facing upload 성공값은 `state`, opaque `resourceId`, `byteLength`,
`replayed`만 반환한다. control-plane 검증에 사용한 `sessionId`,
`requestBindingSha256`와 file fingerprint는 public outcome에 노출하지 않는다.
@@ -633,6 +669,7 @@ analytics는 제품 presentation이 소유한다.
| image capability verification concurrency ceiling | `LIMIT_EXCEEDED` | 진행 작업 종료 대기 또는 runtime 부하 조사 |
| closed Image CDN runtime 사용 | `UNAVAILABLE` | 새 runtime composition |
| network/429/모든 5xx | `UNAVAILABLE` | bounded retry/backoff |
| complete 응답 유실·진행 중 | `UNAVAILABLE`(`UPLOAD_COMPLETE`, retryable) | 같은 파일로 `upload()` 재호출, 또는 `abort()`가 resourceId와 함께 `ALREADY_COMPLETED` 반환(4.3) |
관측성에는 operation, safe outcome, byte/part/candidate bucket, retry bucket과
failure code만 기록한다. capability ID, URL, query, asset/resource/session ID,