fix(browser-transfer): map each upload() failure recovery to one caller action (01-05)
ABORT_PENDING and a checkpoint CAS race returned the same failure, and some recoveries (REISSUE_CAPABILITY, RESTART for a replayed create) named actions the caller cannot take or that repeat the failure. The port now documents a five-value recovery table and upload() returns only those values. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
5a6665a61f
commit
426b6b8eec
@@ -683,6 +683,18 @@ analytics는 제품 presentation이 소유한다.
|
||||
| network/429/모든 5xx | `UNAVAILABLE` | bounded retry/backoff |
|
||||
| complete 응답 유실·진행 중 | `UNAVAILABLE`(`UPLOAD_COMPLETE`, retryable) | 같은 파일로 `upload()` 재호출, 또는 `abort()`가 resourceId와 함께 `ALREADY_COMPLETED` 반환(4.3) |
|
||||
|
||||
`ResumableUploadPort.upload()` 실패의 `recovery`는 호출자가 할 행동 하나를
|
||||
가리킨다(`resumable-upload.ts` port 주석, `resumable-upload-runtime.ts`
|
||||
`toUploadAction`). 이 다섯 값 밖의 값은 `upload()`에서 나오지 않는다.
|
||||
|
||||
| recovery | 호출자 행동 |
|
||||
| --- | --- |
|
||||
| `RESUME` | 같은 파일·key로 `upload()`를 다시 부른다. `retryable:true`면 자동 재시도해도 된다. capability 재발급이 필요한 실패도 여기로 온다 |
|
||||
| `RECONCILE` | `upload()`를 다시 부른다. 서버 상태를 먼저 읽는다(예: 다른 문맥이 checkpoint를 먼저 씀) |
|
||||
| `RESTART` | `abort()` 뒤 `upload()`로 새 session을 연다. abort가 남아 있음(operation `UPLOAD_ABORT`), 읽을 수 없는 checkpoint 행, 서버 part가 파일과 다름 |
|
||||
| `RESELECT` | 파일을 다시 고르거나, 다른 파일이면 새 key를 쓴다 |
|
||||
| `NONE` | 이 요청으로 할 행동이 없다. 잘못된 입력, 상한·정책·권한 거절, 호출자 자신의 abort, 다시 불러도 같은 답이 오는 서버 응답(정책보다 긴 session 등) |
|
||||
|
||||
관측성에는 operation, safe outcome, byte/part/candidate bucket, retry bucket과
|
||||
failure code만 기록한다. capability ID, URL, query, asset/resource/session ID,
|
||||
file name, digest, raw ETag, receipt와 backend message는 log/diagnostics/telemetry에
|
||||
|
||||
@@ -131,6 +131,15 @@ const RECOVERIES: ReadonlySet<string> = new Set([
|
||||
"RECONCILE",
|
||||
]);
|
||||
|
||||
/** 01-05. The recoveries `ResumableUploadPort.upload()` documents. */
|
||||
const UPLOAD_ACTIONS: ReadonlySet<BrowserDataRecovery> = new Set([
|
||||
"RESUME",
|
||||
"RECONCILE",
|
||||
"RESTART",
|
||||
"RESELECT",
|
||||
"NONE",
|
||||
]);
|
||||
|
||||
export function createResumableUploadRuntime<Capability>(
|
||||
inputDependencies: ResumableUploadRuntimeDependencies<Capability>,
|
||||
): ResumableUploadRuntime {
|
||||
@@ -197,12 +206,14 @@ export function createResumableUploadRuntime<Capability>(
|
||||
request.uploadKey,
|
||||
operationScope.signal,
|
||||
async () =>
|
||||
await executeUpload(
|
||||
dependencies,
|
||||
Object.freeze({
|
||||
...request,
|
||||
signal: operationScope.signal,
|
||||
}),
|
||||
toUploadAction(
|
||||
await executeUpload(
|
||||
dependencies,
|
||||
Object.freeze({
|
||||
...request,
|
||||
signal: operationScope.signal,
|
||||
}),
|
||||
),
|
||||
),
|
||||
);
|
||||
// Tracked until terminal settlement so dispose() can prove quiescence.
|
||||
@@ -375,7 +386,14 @@ async function executeUpload<Capability>(
|
||||
request.uploadKey,
|
||||
request.signal,
|
||||
);
|
||||
if (!stored.ok) return remapResult(stored, "UPLOAD_RECONCILE");
|
||||
if (!stored.ok) {
|
||||
// 01-05. A row this build cannot read is cleared only by `abort()`.
|
||||
return stored.error.code === "CORRUPT_DATA"
|
||||
? browserDataFailure("CORRUPT_DATA", "UPLOAD_RECONCILE", {
|
||||
recovery: "RESTART",
|
||||
})
|
||||
: remapResult(stored, "UPLOAD_RECONCILE");
|
||||
}
|
||||
if (
|
||||
stored.value &&
|
||||
(!sameFingerprint(
|
||||
@@ -389,8 +407,10 @@ async function executeUpload<Capability>(
|
||||
});
|
||||
}
|
||||
if (stored.value?.state === "ABORT_PENDING") {
|
||||
return browserDataFailure("CONFLICT", "UPLOAD_RECONCILE", {
|
||||
recovery: "RECONCILE",
|
||||
// 01-05. Only `abort()` finishes a pending abort; this must not look like
|
||||
// a checkpoint write race, which `upload()` itself resolves.
|
||||
return browserDataFailure("CONFLICT", "UPLOAD_ABORT", {
|
||||
recovery: "RESTART",
|
||||
});
|
||||
}
|
||||
|
||||
@@ -1676,6 +1696,26 @@ function reportProgress(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 01-05. `upload()` failures carry only the recoveries the port documents as
|
||||
* caller actions. Provider vocabulary the caller cannot act on itself (a
|
||||
* capability to reissue, a request to retry) means "call `upload()` again";
|
||||
* anything else outside the table has no caller action.
|
||||
*/
|
||||
function toUploadAction<Value>(
|
||||
result: BrowserDataResult<Value>,
|
||||
): BrowserDataResult<Value> {
|
||||
if (result.ok || UPLOAD_ACTIONS.has(result.error.recovery)) return result;
|
||||
return browserDataFailure(result.error.code, result.error.operation, {
|
||||
retryable: result.error.retryable,
|
||||
recovery:
|
||||
result.error.recovery === "REISSUE_CAPABILITY" ||
|
||||
result.error.recovery === "RETRY"
|
||||
? "RESUME"
|
||||
: "NONE",
|
||||
});
|
||||
}
|
||||
|
||||
function mapLockFailure(
|
||||
error: unknown,
|
||||
operation: BrowserDataOperation,
|
||||
|
||||
@@ -110,7 +110,7 @@ export function validateStatus<Capability>(
|
||||
return browserDataFailure(
|
||||
"INTEGRITY_FAILED",
|
||||
"UPLOAD_RECONCILE",
|
||||
{ recovery: "RECONCILE" },
|
||||
{ recovery: "RESTART" },
|
||||
);
|
||||
}
|
||||
const receipts = validateServerReceipts(
|
||||
@@ -153,7 +153,7 @@ export function validateStatus<Capability>(
|
||||
return browserDataFailure(
|
||||
"INTEGRITY_FAILED",
|
||||
"UPLOAD_RECONCILE",
|
||||
{ recovery: "RECONCILE" },
|
||||
{ recovery: "RESTART" },
|
||||
);
|
||||
}
|
||||
return browserDataSuccess(
|
||||
@@ -177,7 +177,7 @@ export function validateStatus<Capability>(
|
||||
value.requestBindingSha256 !== checkpoint.requestBindingSha256
|
||||
) {
|
||||
return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_RECONCILE", {
|
||||
recovery: "RECONCILE",
|
||||
recovery: "RESTART",
|
||||
});
|
||||
}
|
||||
return browserDataSuccess(
|
||||
@@ -221,18 +221,22 @@ export function validateSession<Capability>(
|
||||
value.maxConcurrency > dependencies.policy.maxConcurrency ||
|
||||
!Number.isSafeInteger(value.expiresAtEpochMs)
|
||||
) {
|
||||
// 01-05. A create is replayed under the same key, so neither calling
|
||||
// `upload()` again nor restarting changes what the server answers.
|
||||
return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_SESSION", {
|
||||
recovery: "RECONCILE",
|
||||
recovery: "NONE",
|
||||
});
|
||||
}
|
||||
const now = safeNow(dependencies, "UPLOAD_SESSION");
|
||||
if (!now.ok) return now;
|
||||
if (
|
||||
requireActiveExpiry &&
|
||||
(value.expiresAtEpochMs <= now.value ||
|
||||
value.expiresAtEpochMs - now.value >
|
||||
dependencies.policy.maxSessionLifetimeMs)
|
||||
value.expiresAtEpochMs - now.value >
|
||||
dependencies.policy.maxSessionLifetimeMs
|
||||
) {
|
||||
return browserDataFailure("POLICY_REJECTED", "UPLOAD_SESSION");
|
||||
}
|
||||
if (requireActiveExpiry && value.expiresAtEpochMs <= now.value) {
|
||||
return browserDataFailure("EXPIRED_RESOURCE", "UPLOAD_SESSION", {
|
||||
recovery: "RESTART",
|
||||
});
|
||||
@@ -266,7 +270,7 @@ function validateServerReceipts(
|
||||
!verifyPartAgainstManifest(receipt, manifest)
|
||||
) {
|
||||
return browserDataFailure("INTEGRITY_FAILED", operation, {
|
||||
recovery: "RECONCILE",
|
||||
recovery: "RESTART",
|
||||
});
|
||||
}
|
||||
previousPart = receipt.partNumber;
|
||||
|
||||
@@ -101,6 +101,25 @@ export type UploadAbortOutcome = Readonly<{
|
||||
}>;
|
||||
|
||||
export interface ResumableUploadPort {
|
||||
/**
|
||||
* 01-05. A failure's `recovery` names exactly one caller action:
|
||||
*
|
||||
* | recovery | caller action |
|
||||
* | ----------- | ---------------------------------------------------------- |
|
||||
* | `RESUME` | Call `upload()` again with the same file and key. With |
|
||||
* | | `retryable: true` it may be retried automatically. |
|
||||
* | `RECONCILE` | Call `upload()` again; it reads the server state first. |
|
||||
* | `RESTART` | Call `abort()`, then `upload()` for a fresh session: an |
|
||||
* | | abort is pending (operation `UPLOAD_ABORT`), the stored |
|
||||
* | | row is unreadable, or the server's parts disagree with the |
|
||||
* | | file. |
|
||||
* | `RESELECT` | Select the file again, or use a new key for another file. |
|
||||
* | `NONE` | No action on this request: invalid input, a limit, a |
|
||||
* | | policy or permission refusal, the caller's own abort, or |
|
||||
* | | a server answer that a new call would only replay. |
|
||||
*
|
||||
* No other recovery value is returned from `upload()`.
|
||||
*/
|
||||
upload(
|
||||
request: ResumableUploadRequest,
|
||||
): Promise<BrowserDataResult<QuarantinedUpload>>;
|
||||
|
||||
@@ -238,7 +238,8 @@ describe("resumable upload runtime server response validation", () => {
|
||||
error: {
|
||||
code: "INTEGRITY_FAILED",
|
||||
operation: "UPLOAD_SESSION",
|
||||
recovery: "RECONCILE",
|
||||
// 01-05. The create key replays the same answer.
|
||||
recovery: "NONE",
|
||||
},
|
||||
});
|
||||
});
|
||||
@@ -251,7 +252,7 @@ describe("resumable upload runtime server response validation", () => {
|
||||
});
|
||||
});
|
||||
|
||||
it("restarts a session whose lifetime exceeds the policy ceiling", async () => {
|
||||
it("refuses a session whose lifetime exceeds the policy ceiling", async () => {
|
||||
const harness = createControlHarness();
|
||||
const create = harness.control.createSession.bind(harness.control);
|
||||
harness.control.createSession = async (input) => {
|
||||
@@ -265,10 +266,12 @@ describe("resumable upload runtime server response validation", () => {
|
||||
};
|
||||
await expect(upload(dependencies(harness))).resolves.toMatchObject({
|
||||
ok: false,
|
||||
// 01-05. A restart gets the same session back, so there is no caller
|
||||
// action; this is a server/policy mismatch.
|
||||
error: {
|
||||
code: "EXPIRED_RESOURCE",
|
||||
code: "POLICY_REJECTED",
|
||||
operation: "UPLOAD_SESSION",
|
||||
recovery: "RESTART",
|
||||
recovery: "NONE",
|
||||
},
|
||||
});
|
||||
});
|
||||
@@ -285,10 +288,11 @@ describe("resumable upload runtime server response validation", () => {
|
||||
});
|
||||
await expect(upload(dependencies(harness))).resolves.toMatchObject({
|
||||
ok: false,
|
||||
// 01-05. The caller's action for a capability refusal is upload().
|
||||
error: {
|
||||
code: "CORRUPT_DATA",
|
||||
operation: "UPLOAD_PART",
|
||||
recovery: "REISSUE_CAPABILITY",
|
||||
recovery: "RESUME",
|
||||
},
|
||||
});
|
||||
});
|
||||
@@ -307,7 +311,7 @@ describe("resumable upload runtime server response validation", () => {
|
||||
error: {
|
||||
code: "POLICY_REJECTED",
|
||||
operation: "UPLOAD_PART",
|
||||
recovery: "REISSUE_CAPABILITY",
|
||||
recovery: "RESUME",
|
||||
},
|
||||
});
|
||||
});
|
||||
@@ -326,7 +330,7 @@ describe("resumable upload runtime server response validation", () => {
|
||||
error: {
|
||||
code: "INTEGRITY_FAILED",
|
||||
operation: "UPLOAD_RECONCILE",
|
||||
recovery: "RECONCILE",
|
||||
recovery: "RESTART",
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
@@ -702,3 +702,166 @@ describe("resumable upload part time limit (01-03)", () => {
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("upload() failure recovery maps to one caller action (01-05)", () => {
|
||||
/** The port's recovery → action table (`ResumableUploadPort.upload`). */
|
||||
const UPLOAD_ACTIONS = new Set([
|
||||
"RESUME",
|
||||
"RECONCILE",
|
||||
"RESTART",
|
||||
"RESELECT",
|
||||
"NONE",
|
||||
]);
|
||||
|
||||
function runtimeFor(
|
||||
harness: ReturnType<typeof createControlHarness>,
|
||||
overrides: Partial<
|
||||
Parameters<typeof createResumableUploadRuntime<TestCapability>>[0]
|
||||
> = {},
|
||||
) {
|
||||
return createResumableUploadRuntime({
|
||||
controlPlane: harness.control,
|
||||
partExecutor: executorFor(harness),
|
||||
checkpoints: new MemoryCheckpointStore(),
|
||||
mutationLock: noContentionLock,
|
||||
crypto,
|
||||
policy: runtimePolicy({ maxRetries: 0 }),
|
||||
now: () => 1_000,
|
||||
sleep: async () => {},
|
||||
...overrides,
|
||||
});
|
||||
}
|
||||
|
||||
const scenarios = {
|
||||
"an abort is still pending": async () => {
|
||||
const harness = createControlHarness();
|
||||
harness.control.complete = async () =>
|
||||
browserDataFailure("UNAVAILABLE", "UPLOAD_COMPLETE", {
|
||||
retryable: true,
|
||||
recovery: "RESUME",
|
||||
});
|
||||
harness.control.abort = async () =>
|
||||
browserDataFailure("UNAVAILABLE", "UPLOAD_ABORT", {
|
||||
retryable: true,
|
||||
recovery: "RESUME",
|
||||
});
|
||||
const runtime = runtimeFor(harness);
|
||||
const key = "upload_key_abort_pending";
|
||||
await runtime.upload(request(key));
|
||||
await runtime.abort({ uploadKey: key, signal: activeSignal });
|
||||
return await runtime.upload(request(key));
|
||||
},
|
||||
"another context wrote the checkpoint first": async () => {
|
||||
const checkpoints = new MemoryCheckpointStore();
|
||||
checkpoints.compareAndSwap = async () =>
|
||||
browserDataFailure("CONFLICT", "UPLOAD_RECONCILE", {
|
||||
recovery: "RECONCILE",
|
||||
});
|
||||
return await runtimeFor(createControlHarness(), { checkpoints }).upload(
|
||||
request("upload_key_cas_conflict"),
|
||||
);
|
||||
},
|
||||
"the server status disagrees with the file": async () =>
|
||||
await runtimeFor(
|
||||
createControlHarness({
|
||||
statusParts: (_session, accepted) =>
|
||||
[...accepted.values()].map((part) => ({
|
||||
...part,
|
||||
checksumSha256: "e".repeat(64),
|
||||
})),
|
||||
}),
|
||||
).upload(request("upload_key_status_mismatch")),
|
||||
"the checkpoint row is unreadable": async () => {
|
||||
const checkpoints = new MemoryCheckpointStore();
|
||||
checkpoints.read = async () =>
|
||||
browserDataFailure("CORRUPT_DATA", "UPLOAD_RECONCILE", {
|
||||
recovery: "RECONCILE",
|
||||
});
|
||||
return await runtimeFor(createControlHarness(), { checkpoints }).upload(
|
||||
request("upload_key_unreadable"),
|
||||
);
|
||||
},
|
||||
"the server session outlives the policy": async () => {
|
||||
const harness = createControlHarness();
|
||||
const create = harness.control.createSession.bind(harness.control);
|
||||
harness.control.createSession = async (input) => {
|
||||
const created = await create(input);
|
||||
return created.ok
|
||||
? browserDataSuccess({
|
||||
...created.value,
|
||||
expiresAtEpochMs: 1_000 + 20_000,
|
||||
})
|
||||
: created;
|
||||
};
|
||||
return await runtimeFor(harness).upload(request("upload_key_long_session"));
|
||||
},
|
||||
"every PUT refuses the capability": async () =>
|
||||
await runtimeFor(createControlHarness(), {
|
||||
partExecutor: { uploadPart: async () => putForbidden() },
|
||||
}).upload(request("upload_key_refused_put")),
|
||||
"the key belongs to another file": async () => {
|
||||
const checkpoints = new MemoryCheckpointStore();
|
||||
const harness = createControlHarness();
|
||||
harness.control.complete = async () =>
|
||||
browserDataFailure("UNAVAILABLE", "UPLOAD_COMPLETE", {
|
||||
retryable: true,
|
||||
recovery: "RESUME",
|
||||
});
|
||||
const runtime = runtimeFor(harness, { checkpoints });
|
||||
const key = "upload_key_other_file";
|
||||
await runtime.upload(request(key));
|
||||
return await runtime.upload({
|
||||
...request(key),
|
||||
source: rangeSource(new Uint8Array([9, 9, 9, 9])),
|
||||
});
|
||||
},
|
||||
} as const;
|
||||
|
||||
it.each([
|
||||
["an abort is still pending", "CONFLICT", "UPLOAD_ABORT", "RESTART"],
|
||||
[
|
||||
"another context wrote the checkpoint first",
|
||||
"CONFLICT",
|
||||
"UPLOAD_RECONCILE",
|
||||
"RECONCILE",
|
||||
],
|
||||
[
|
||||
"the server status disagrees with the file",
|
||||
"INTEGRITY_FAILED",
|
||||
"UPLOAD_RECONCILE",
|
||||
"RESTART",
|
||||
],
|
||||
[
|
||||
"the checkpoint row is unreadable",
|
||||
"CORRUPT_DATA",
|
||||
"UPLOAD_RECONCILE",
|
||||
"RESTART",
|
||||
],
|
||||
[
|
||||
"the server session outlives the policy",
|
||||
"POLICY_REJECTED",
|
||||
"UPLOAD_SESSION",
|
||||
"NONE",
|
||||
],
|
||||
[
|
||||
"every PUT refuses the capability",
|
||||
"PERMISSION_DENIED",
|
||||
"UPLOAD_PART",
|
||||
"RESUME",
|
||||
],
|
||||
[
|
||||
"the key belongs to another file",
|
||||
"STALE_RESULT",
|
||||
"UPLOAD_RECONCILE",
|
||||
"RESELECT",
|
||||
],
|
||||
] as const)("%s → %s/%s/%s", async (scenario, code, operation, recovery) => {
|
||||
const result = await scenarios[scenario]();
|
||||
|
||||
expect(result).toMatchObject({
|
||||
ok: false,
|
||||
error: { code, operation, recovery },
|
||||
});
|
||||
if (!result.ok) expect(UPLOAD_ACTIONS.has(result.error.recovery)).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -371,12 +371,14 @@ describe("production resumable upload runtime", () => {
|
||||
source: rangeSource(new Uint8Array([1, 2, 3, 4])),
|
||||
signal: activeSignal,
|
||||
});
|
||||
// 01-05. Calling upload() again reads the same server parts, so the way
|
||||
// out is abort() and a fresh session.
|
||||
expect(result).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
code: "INTEGRITY_FAILED",
|
||||
operation: "UPLOAD_RECONCILE",
|
||||
recovery: "RECONCILE",
|
||||
recovery: "RESTART",
|
||||
},
|
||||
});
|
||||
expect(partExecutor.uploadPart).not.toHaveBeenCalled();
|
||||
|
||||
Reference in New Issue
Block a user