fix(browser-transfer): reissue the part capability after a PUT 401/403 or expiry (01-01)

A single object-store refusal ended the whole upload as PERMISSION_DENIED
with retryable:false. The next attempt already issues a fresh capability, so
REISSUE_CAPABILITY PUT failures now retry within maxRetries; BFF issuance
refusals still stop at once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:03:50 +09:00
co-authored by Claude Opus 5.5
parent 926f448fce
commit 648fe4e9f7
3 changed files with 257 additions and 1 deletions
@@ -261,6 +261,9 @@ session state 검사를 대체하지 않는다.
- 429/모든 `5xx`/network retry는 composition의 bounded attempt, bounded
`Retry-After`와 abortable backoff 안에서만 수행한다.
- 만료/authorization failure는 최대 정책 범위 안에서 capability를 재발급한다.
object store PUT의 401/403/409/410과 실행기의 만료 판정(`REISSUE_CAPABILITY`)은
`maxRetries` 안에서 다음 시도가 새 capability로 다시 보낸다. BFF 발급 단계의
401/403은 재시도하지 않는다(`resumable-upload-runtime.ts` `uploadPartWithRetry`).
- upload response의 opaque receipt/ETag를 whole-file digest로 해석하지 않는다.
- PUT capability는 성공 status, receipt header와
`expectedResponseByteLength`를 묶는다. runtime은 exact `Content-Length`를
@@ -1015,7 +1015,19 @@ async function uploadPartWithRetry<Capability>(
);
}
lastFailure = uploaded.error;
if (!canRetry(uploaded.error, attempt, dependencies.policy)) {
// 01-01. A PUT refused with REISSUE_CAPABILITY (401/403, gone, or the
// executor's own expiry check) is what the next attempt's fresh capability
// recovers. A refused issuance above still stops at once.
const reissuable =
uploaded.error.retryable ||
uploaded.error.recovery === "REISSUE_CAPABILITY";
if (
!canRetry(
{ ...uploaded.error, retryable: reissuable },
attempt,
dependencies.policy,
)
) {
return stripProviderFailure(uploaded);
}
}
@@ -0,0 +1,241 @@
import { describe, expect, it, vi } from "vitest";
import type { PresignedUploadPartCapability } from "../../src/application/ports/browser-transfer/presigned-transfer.ts";
import type {
ResumableUploadControlPlane,
UploadPartExecutor,
} from "../../src/application/ports/browser-transfer/resumable-upload.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../../src/adapters/browser-file-storage/result.ts";
import { sha256Hex } from "../../src/adapters/browser-transfer/presigned/incremental-sha256.ts";
import { createPresignedUploadPartExecutor } from "../../src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts";
import { createResumableUploadRuntime } from "../../src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts";
import {
CONTROL_ENDPOINT,
NOW,
POLICY_HEADER,
createHarness,
jsonResponse,
responseWithUrl,
uploadCapabilityPayload,
} from "./presigned-transfer-fixture.ts";
import {
activeSignal,
createControlHarness,
MemoryCheckpointStore,
noContentionLock,
rangeSource,
runtimePolicy,
type TestCapability,
} from "./resumable-upload-runtime-fixture.ts";
const request = (uploadKey: string) =>
({
uploadKey,
purpose: "attachment",
mediaType: "application/octet-stream",
source: rangeSource(new Uint8Array([1, 2, 3, 4])),
signal: activeSignal,
}) as const;
/** What `statusFailure(403)` hands the runtime through the part executor. */
const putForbidden = () =>
browserDataFailure("PERMISSION_DENIED", "PRESIGNED_TRANSFER", {
retryable: false,
recovery: "REISSUE_CAPABILITY",
});
describe("resumable upload capability reissue (01-01)", () => {
it("reissues the capability after an object-store PUT 403 and completes", async () => {
const harness = createControlHarness();
let attempts = 0;
const partExecutor: UploadPartExecutor<TestCapability> = {
async uploadPart(input) {
attempts += 1;
if (attempts === 1) return putForbidden();
const receipt = Object.freeze({
...input.part,
receiptToken: "etag-after-reissue",
});
harness.accepted.set(input.part.partNumber, receipt);
return browserDataSuccess(receipt);
},
};
const runtime = createResumableUploadRuntime({
controlPlane: harness.control,
partExecutor,
checkpoints: new MemoryCheckpointStore(),
mutationLock: noContentionLock,
crypto,
policy: runtimePolicy({ maxRetries: 3 }),
now: () => 1_000,
sleep: async () => {},
});
const result = await runtime.upload(request("upload_key_put_403"));
expect(result).toMatchObject({ ok: true, value: { state: "QUARANTINED" } });
expect(attempts).toBe(2);
expect(harness.issued).toHaveBeenCalledTimes(2);
});
it("stops after maxRetries when every PUT keeps refusing the capability", async () => {
const harness = createControlHarness();
const partExecutor = { uploadPart: vi.fn(async () => putForbidden()) };
const runtime = createResumableUploadRuntime({
controlPlane: harness.control,
partExecutor:
partExecutor as unknown as UploadPartExecutor<TestCapability>,
checkpoints: new MemoryCheckpointStore(),
mutationLock: noContentionLock,
crypto,
policy: runtimePolicy({ maxRetries: 2 }),
now: () => 1_000,
sleep: async () => {},
});
const result = await runtime.upload(request("upload_key_put_403_always"));
expect(result).toMatchObject({
ok: false,
error: { code: "PERMISSION_DENIED", operation: "UPLOAD_PART" },
});
expect(partExecutor.uploadPart).toHaveBeenCalledTimes(3);
expect(harness.issued).toHaveBeenCalledTimes(3);
});
it("does not retry a capability issuance the BFF itself refuses with 403", async () => {
const harness = createControlHarness({
issueCapability: () =>
browserDataFailure("PERMISSION_DENIED", "PRESIGNED_TRANSFER", {
retryable: false,
recovery: "REISSUE_CAPABILITY",
}),
});
const partExecutor = { uploadPart: vi.fn() };
const runtime = createResumableUploadRuntime({
controlPlane: harness.control,
partExecutor:
partExecutor as unknown as UploadPartExecutor<TestCapability>,
checkpoints: new MemoryCheckpointStore(),
mutationLock: noContentionLock,
crypto,
policy: runtimePolicy({ maxRetries: 3 }),
now: () => 1_000,
sleep: async () => {},
});
const result = await runtime.upload(request("upload_key_issue_403"));
expect(result).toMatchObject({
ok: false,
error: { code: "PERMISSION_DENIED", retryable: false },
});
expect(harness.issued).toHaveBeenCalledTimes(1);
expect(partExecutor.uploadPart).not.toHaveBeenCalled();
});
it("recovers a real presigned PUT 403 through a freshly issued capability", async () => {
const bytes = new Uint8Array([1, 2, 3, 4]);
const checksum = sha256Hex(bytes);
let issuance = 0;
let puts = 0;
const fetcher = vi.fn(
async (input: RequestInfo | URL, init?: RequestInit) => {
if (String(input) === CONTROL_ENDPOINT) {
issuance += 1;
const body = JSON.parse(String(init?.body)) as Readonly<{
binding: Readonly<Record<string, unknown>>;
}>;
return jsonResponse(
uploadCapabilityPayload(
{ bytes, checksum },
{
capabilityReceipt: `capability-upload-${issuance}`,
binding: body.binding,
maxBytes: bytes.byteLength,
expiresAtEpochMs: NOW + 4_000,
},
),
);
}
puts += 1;
const href = String(input);
return responseWithUrl(
puts === 1
? new Response(null, { status: 403 })
: new Response(null, {
status: 200,
headers: {
[POLICY_HEADER]: "v1",
"Content-Length": "0",
ETag: "\"part-etag-reissued\"",
},
}),
href,
);
},
) as unknown as typeof fetch;
const { provider, executor } = createHarness({ fetcher });
const harness = createControlHarness({ now: NOW });
const control = harness.control as unknown as ResumableUploadControlPlane<
PresignedUploadPartCapability
>;
control.issuePartCapability = async (input) => {
const issued = await provider.issueUploadPart({
sessionId: input.sessionId,
requestBindingSha256: input.requestBindingSha256,
uploadBindingSha256: input.uploadBindingSha256,
partNumber: input.part.partNumber,
offset: input.part.offset,
byteLength: input.part.byteLength,
checksumSha256: input.part.checksumSha256,
mediaType: input.mediaType,
idempotencyKey: input.idempotencyKey,
signal: input.signal,
});
return issued.ok
? browserDataSuccess({
capability: issued.value,
uploadBindingSha256: input.uploadBindingSha256,
expiresAtEpochMs: issued.value.expiresAtEpochMs,
})
: issued;
};
const realPart = createPresignedUploadPartExecutor(
executor.uploadParts,
() => NOW,
);
const runtime = createResumableUploadRuntime({
controlPlane: control,
partExecutor: {
async uploadPart(input) {
const uploaded = await realPart.uploadPart(input);
// The fake server lists what the object store accepted.
if (uploaded.ok) {
harness.accepted.set(uploaded.value.partNumber, uploaded.value);
}
return uploaded;
},
},
checkpoints: new MemoryCheckpointStore(),
mutationLock: noContentionLock,
crypto,
policy: runtimePolicy({ maxRetries: 3 }),
now: () => NOW,
sleep: async () => {},
});
const result = await runtime.upload(request("upload_key_real_put_403"));
expect(result).toMatchObject({ ok: true, value: { state: "QUARANTINED" } });
expect(harness.completedParts).toEqual([
[expect.objectContaining({ receiptToken: "part-etag-reissued" })],
]);
expect(issuance).toBe(2);
expect(puts).toBe(2);
});
});