From b3981f9eb706b1deb38293ea7578a8743cb32e08 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:40:12 +0900 Subject: [PATCH] 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 --- .../presigned-transfer-and-image-cdn.md | 8 +- .../image-cdn/image-cdn-runtime.ts | 11 +- .../browser-transfer/presigned/http-common.ts | 13 + .../presigned/presigned-transfer-executor.ts | 4 +- .../resumable-upload-runtime.ts | 9 + tests/unit/presigned-transfer-upload.test.ts | 4 +- .../resumable-upload-runtime-recovery.test.ts | 240 +++++++++++------- 7 files changed, 183 insertions(+), 106 deletions(-) diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index e083071c..7018f740 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -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 diff --git a/src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts b/src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts index 22b84f66..717356bd 100644 --- a/src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts +++ b/src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts @@ -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( 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" { diff --git a/src/adapters/browser-transfer/presigned/http-common.ts b/src/adapters/browser-transfer/presigned/http-common.ts index 885d6771..93afad49 100644 --- a/src/adapters/browser-transfer/presigned/http-common.ts +++ b/src/adapters/browser-transfer/presigned/http-common.ts @@ -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>, 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"; +} diff --git a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts index 0fc2af90..e6f8aeee 100644 --- a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts +++ b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts @@ -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 diff --git a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts index f6461efd..e2b3c5e2 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -820,6 +820,7 @@ async function transferMissingParts( fail(bytes); return; } + const attempts = { count: 0 }; const uploaded = await uploadPartWithRetry( dependencies, transferRequest, @@ -827,12 +828,14 @@ async function transferMissingParts( 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( }); 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( 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( checkpoint: ResumableUploadCheckpoint, part: UploadPartDescriptor, bytes: Uint8Array, + /** 01-10. Counts the attempts made, for the part's single observation. */ + attempts: { count: number }, ): Promise> { const idempotencyKey = await deriveUploadIdempotencyKey({ label: "PART", @@ -958,6 +966,7 @@ async function uploadPartWithRetry( ); if (!delayed.ok) return delayed; } + attempts.count += 1; const issued = await invokeProviderAttempt( dependencies, "UPLOAD_PART", diff --git a/tests/unit/presigned-transfer-upload.test.ts b/tests/unit/presigned-transfer-upload.test.ts index 6e68313d..8c550e9a 100644 --- a/tests/unit/presigned-transfer-upload.test.ts +++ b/tests/unit/presigned-transfer-upload.test.ts @@ -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", }, diff --git a/tests/unit/resumable-upload-runtime-recovery.test.ts b/tests/unit/resumable-upload-runtime-recovery.test.ts index effb5181..3df38960 100644 --- a/tests/unit/resumable-upload-runtime-recovery.test.ts +++ b/tests/unit/resumable-upload-runtime-recovery.test.ts @@ -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>; + }>; + 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>; - }>; - 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); + }); +});