fix(browser-transfer): record one UPLOAD_PART per part with an attempt bucket (01-10)

The executor and the runtime both recorded UPLOAD_PART, so a part retried once
became one FAILED and two SUCCEEDED records, and no retry bucket existed. PUT
attempts are now PRESIGNED_TRANSFER; the runtime records the part once with
its attempt count as countBucket.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:40:12 +09:00
co-authored by Claude Opus 5.5
parent 1eee2ac580
commit b3981f9eb7
7 changed files with 183 additions and 106 deletions
@@ -724,11 +724,17 @@ analytics는 제품 presentation이 소유한다.
| `RESELECT` | 파일을 다시 고르거나, 다른 파일이면 새 key를 쓴다 |
| `NONE` | 이 요청으로 할 행동이 없다. 잘못된 입력, 상한·정책·권한 거절, 호출자 자신의 abort, 다시 불러도 같은 답이 오는 서버 응답(정책보다 긴 session 등) |
관측성에는 operation, safe outcome, byte/part/candidate bucket, retry bucket과
관측성에는 operation, safe outcome, byte/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에
기록하지 않는다. 앞 절의 strict checkpoint allowlist만 durable 예외다.
같은 observer를 두 계층에 넘겨도 한 사건은 한 번만 센다. resumable runtime은
part마다 최종 결과 하나를 `UPLOAD_PART`로 남기고, 그 part에 쓴 시도 수를
`countBucket`에 넣는다(retry bucket). presigned 실행기의 PUT 시도 하나하나는
`PRESIGNED_TRANSFER`로 따로 남는다(`resumable-upload-runtime.ts`
`transferMissingParts`, `presigned-transfer-executor.ts` `uploadParts.put`).
## 8. 조합 조건
현재 `src/adapters/browser-transfer/index.ts`는 개별 presigned, upload와 Image CDN
@@ -25,6 +25,7 @@ import {
snapshotAbortTimers,
type AbortableOperation,
} from "../../platform/abortable-operation.ts";
import { countBucket } from "../presigned/http-common.ts";
import {
IMAGE_FORMAT_MEDIA_TYPE,
type ImageCandidateGeometry,
@@ -1150,16 +1151,6 @@ function observeImageTerminal<Value>(
return result;
}
function countBucket(
value: number,
): "ZERO" | "ONE" | "TWO_TO_TEN" | "ELEVEN_TO_HUNDRED" | "GT_HUNDRED" {
if (value <= 0) return "ZERO";
if (value === 1) return "ONE";
if (value <= 10) return "TWO_TO_TEN";
if (value <= 100) return "ELEVEN_TO_HUNDRED";
return "GT_HUNDRED";
}
function byteBucket(
value: number,
): "ZERO" | "LT1MIB" | "1_TO_9MIB" | "10_TO_99MIB" | "GTE100MIB" {
@@ -227,12 +227,14 @@ export function isAbortSignal(value: unknown): value is AbortSignal {
/**
* One terminal observation for presigned and resumable transfers. An absent or
* invalid byte length leaves `byteBucket` out rather than guessing one.
* 01-10. `attempts`, when given, is the retry count as a `countBucket`.
*/
export function observeTransferResult(
observer: BrowserDataObserver | undefined,
operation: BrowserDataOperation,
result: Result<unknown, Readonly<{ code: BrowserDataFailureCode }>>,
byteLength?: number,
attempts?: number,
): void {
const bucket = byteBucket(byteLength);
observeBrowserData(observer, {
@@ -240,5 +242,16 @@ export function observeTransferResult(
outcome: result.ok ? "SUCCEEDED" : "FAILED",
...(!result.ok ? { failureCode: result.error.code } : {}),
...(bucket !== undefined ? { byteBucket: bucket } : {}),
...(attempts !== undefined ? { countBucket: countBucket(attempts) } : {}),
});
}
export function countBucket(
value: number,
): "ZERO" | "ONE" | "TWO_TO_TEN" | "ELEVEN_TO_HUNDRED" | "GT_HUNDRED" {
if (value <= 0) return "ZERO";
if (value === 1) return "ONE";
if (value <= 10) return "TWO_TO_TEN";
if (value <= 100) return "ELEVEN_TO_HUNDRED";
return "GT_HUNDRED";
}
@@ -472,9 +472,11 @@ export function createPresignedTransferExecutor(
},
);
}
// 01-10. One PUT attempt. The resumable runtime records the part's final
// result as UPLOAD_PART, so the two layers never count the same event.
observeTransferResult(
observer,
"UPLOAD_PART",
"PRESIGNED_TRANSFER",
result,
result.ok
? result.value.bytesWritten
@@ -820,6 +820,7 @@ async function transferMissingParts<Capability>(
fail(bytes);
return;
}
const attempts = { count: 0 };
const uploaded = await uploadPartWithRetry(
dependencies,
transferRequest,
@@ -827,12 +828,14 @@ async function transferMissingParts<Capability>(
checkpoint,
part,
bytes.value,
attempts,
);
observeTransferResult(
dependencies.observer,
"UPLOAD_PART",
uploaded,
part.byteLength,
attempts.count,
);
if (!uploaded.ok) {
fail(uploaded);
@@ -883,6 +886,7 @@ async function transferMissingParts<Capability>(
});
if (!verified.ok) return verified;
if (accepted.has(part.partNumber)) continue;
const attempts = { count: 0 };
const uploaded = await uploadPartWithRetry(
dependencies,
request,
@@ -890,12 +894,14 @@ async function transferMissingParts<Capability>(
checkpoint,
part,
verified.value,
attempts,
);
observeTransferResult(
dependencies.observer,
"UPLOAD_PART",
uploaded,
part.byteLength,
attempts.count,
);
if (!uploaded.ok) return uploaded;
const persisted = await persistReceipt(uploaded.value);
@@ -913,6 +919,8 @@ async function uploadPartWithRetry<Capability>(
checkpoint: ResumableUploadCheckpoint,
part: UploadPartDescriptor,
bytes: Uint8Array,
/** 01-10. Counts the attempts made, for the part's single observation. */
attempts: { count: number },
): Promise<BrowserDataResult<UploadPartReceipt>> {
const idempotencyKey = await deriveUploadIdempotencyKey({
label: "PART",
@@ -958,6 +966,7 @@ async function uploadPartWithRetry<Capability>(
);
if (!delayed.ok) return delayed;
}
attempts.count += 1;
const issued = await invokeProviderAttempt(
dependencies,
"UPLOAD_PART",
+3 -1
View File
@@ -526,8 +526,10 @@ describe("presigned upload part execution", () => {
outcome: "SUCCEEDED",
byteBucket: "LT1MIB",
},
// 01-10. A PUT attempt is PRESIGNED_TRANSFER; UPLOAD_PART is the
// resumable runtime's one record per part.
{
operation: "UPLOAD_PART",
operation: "PRESIGNED_TRANSFER",
outcome: "SUCCEEDED",
byteBucket: "LT1MIB",
},
@@ -1,5 +1,6 @@
import { describe, expect, it, vi } from "vitest";
import type { BrowserDataObservation } from "../../src/application/ports/browser-file-storage/shared.ts";
import type { PresignedUploadPartCapability } from "../../src/application/ports/browser-transfer/presigned-transfer.ts";
import type {
ResumableUploadControlPlane,
@@ -49,6 +50,116 @@ const putForbidden = () =>
recovery: "REISSUE_CAPABILITY",
});
/**
* The runtime composed with the real presigned provider, vault and executor,
* over a fake BFF and object store. `putStatuses` are the object store's
* answers to successive PUTs.
*/
function presignedRuntime(
putStatuses: readonly number[],
observer?: Readonly<{ record(observation: BrowserDataObservation): void }>,
) {
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,
},
),
);
}
const status = putStatuses[puts] ?? 200;
puts += 1;
return responseWithUrl(
status === 200
? new Response(null, {
status: 200,
headers: {
[POLICY_HEADER]: "v1",
"Content-Length": "0",
ETag: "\"part-etag-reissued\"",
},
})
: new Response(null, { status }),
String(input),
);
},
) as unknown as typeof fetch;
const { provider, executor } = createHarness({
fetcher,
...(observer ? { observer } : {}),
});
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 () => {},
...(observer ? { observer } : {}),
});
return {
runtime,
harness,
issuance: () => issuance,
puts: () => puts,
};
}
describe("resumable upload capability reissue (01-01)", () => {
it("reissues the capability after an object-store PUT 403 and completes", async () => {
const harness = createControlHarness();
@@ -140,104 +251,16 @@ describe("resumable upload capability reissue (01-01)", () => {
});
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 real = presignedRuntime([403, 200]);
const result = await runtime.upload(request("upload_key_real_put_403"));
const result = await real.runtime.upload(request("upload_key_real_put_403"));
expect(result).toMatchObject({ ok: true, value: { state: "QUARANTINED" } });
expect(harness.completedParts).toEqual([
expect(real.harness.completedParts).toEqual([
[expect.objectContaining({ receiptToken: "part-etag-reissued" })],
]);
expect(issuance).toBe(2);
expect(puts).toBe(2);
expect(real.issuance()).toBe(2);
expect(real.puts()).toBe(2);
});
});
@@ -974,3 +997,34 @@ describe("resume after a policy change (01-08)", () => {
expect(checkpoints.rows.size).toBe(0);
});
});
describe("upload part observation (01-10)", () => {
it("records a part that succeeded on its second attempt as one UPLOAD_PART", async () => {
const observations: BrowserDataObservation[] = [];
// One observer for both layers, as a composition naturally wires it.
const real = presignedRuntime([503, 200], {
record: (observation) => observations.push(observation),
});
const result = await real.runtime.upload(request("upload_key_observed"));
expect(result.ok).toBe(true);
expect(
observations.filter(({ operation }) => operation === "UPLOAD_PART"),
).toEqual([
{
operation: "UPLOAD_PART",
outcome: "SUCCEEDED",
byteBucket: "LT1MIB",
countBucket: "TWO_TO_TEN",
},
]);
// The executor's own PUT attempts stay visible under their own name.
expect(
observations.filter(
({ operation, outcome }) =>
operation === "PRESIGNED_TRANSFER" && outcome === "FAILED",
),
).toHaveLength(1);
});
});