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
@@ -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>>;
|
||||
|
||||
Reference in New Issue
Block a user