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:
DongHyeonka
2026-09-25 22:22:27 +09:00
co-authored by Claude Opus 5.5
parent 5a6665a61f
commit 426b6b8eec
7 changed files with 269 additions and 25 deletions
@@ -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>>;