From 0f35c985d8c965359d00e5ecd88727206176ff64 Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Sun, 27 Sep 2026 13:47:35 +0900 Subject: [PATCH] fix(browser-transfer): release the vault slot on every exit of put() and open() (01-07) Early returns before resolve (invalid input, pre-aborted signal, byte-length mismatch) left the capability registered, so maxActiveCapabilities: 1 refused the next issuance. The public methods now release it once in a finally. Co-Authored-By: Claude Opus 5.5 --- .../presigned-transfer-and-image-cdn.md | 8 +- .../presigned/presigned-transfer-executor.ts | 67 +++++++--- .../unit/presigned-transfer-download.test.ts | 16 ++- tests/unit/presigned-transfer-upload.test.ts | 117 ++++++++++++++++++ 4 files changed, 186 insertions(+), 22 deletions(-) diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index a4bd9231..4fa8595b 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -174,9 +174,11 @@ URL을 발급하면 안 된다. 더 빠르면 그 기기에서는 capability가 만료로 보인다. - 만료/403은 임의 retry가 아니라 control plane의 새 capability 발급으로 복구한다. - ambiguous network failure 뒤 upload part를 새 bytes로 덮어쓰지 않는다. -- 실행기는 resolve한 capability를 어떤 경로로 끝나든 vault에서 뺀다. 성공하면 - `consume()`이, 바인딩 거절·만료·replay claim 실패·digest 중단이나 불일치로 - 끝나면 `revoke()`가 뺀다(`presigned-transfer-executor.ts`). 실행기에 닿기 전에 +- 실행기의 `put()`·`open()`은 받은 capability를 어떤 경로로 끝나든 vault에서 + 뺀다. 성공하면 `consume()`이 빼고, 그 밖의 모든 경로(잘못된 입력, 이미 중단된 + signal, 바이트 길이 불일치, 바인딩 거절, 만료, replay claim 실패, digest 중단이나 + 불일치, 전송 실패)는 공개 메서드의 `finally`가 `revoke()`로 뺀다 + (`presigned-transfer-executor.ts`의 `release`). 실행기에 닿기 전에 버려진 capability(runtime 응답 검증 실패, part 실행기 사전 검사 실패, fail-fast로 `put()` 전에 멈춘 형제 worker)는 만료까지 `maxActiveCapabilities` 자리를 차지하고, 다음 `register()`가 만료 항목을 정리한다. diff --git a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts index 5f945094..eab0cea0 100644 --- a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts +++ b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts @@ -104,10 +104,20 @@ export function createPresignedTransferExecutor( ): PresignedTransferExecutor { const resolve = options.vault.resolve.bind(options.vault); const consume = options.vault.consume.bind(options.vault); - // 01-07. A resolved identity that is never consumed is retired on the way - // out, so a refused, expired or aborted transfer does not hold a vault slot - // until its expiry. Idempotent after consume(). - const revoke = options.vault.revoke.bind(options.vault); + // 01-07. The capability a call was handed is retired on the way out of + // `open()` and `put()`, whichever path ends the call, so an invalid, + // pre-aborted, refused, expired or failed transfer does not hold a vault + // slot until its expiry. Idempotent after consume() and for identities the + // vault never issued. + const revokeVault = options.vault.revoke.bind(options.vault); + function release(capability: unknown): void { + if (capability === UNREADABLE_CAPABILITY) return; + try { + revokeVault(capability as PresignedTransferCapability); + } catch { + // Release is best effort; the entry still expires in the vault. + } + } const claim = options.replayGuard.claim.bind(options.replayGuard); const hardMaxTransferBytes = positiveSafeInteger( options.hardMaxTransferBytes, @@ -159,13 +169,12 @@ export function createPresignedTransferExecutor( async function openDownload( input: Parameters[0], + capability: PresignedDownloadCapability, ): Promise> { let resourceId: string; - let capability: PresignedDownloadCapability; let signal: AbortSignal; try { resourceId = input.resourceId; - capability = input.capability; signal = input.signal; if (!isAbortSignal(signal)) { throw new TypeError("Abort signal is invalid."); @@ -187,7 +196,6 @@ export function createPresignedTransferExecutor( capability.binding.resourceId !== resourceId || !validCommonBinding(binding, capability, hardMaxTransferBytes) ) { - revoke(capability); return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER"); } const active = validateExpiry( @@ -195,11 +203,9 @@ export function createPresignedTransferExecutor( minimumRemainingLifetimeMs, now(), ); - const claimed = active.ok ? claim(capability) : active; - if (!claimed.ok) { - revoke(capability); - return claimed; - } + if (!active.ok) return active; + const claimed = claim(capability); + if (!claimed.ok) return claimed; const consumed = consume(capability); if (!consumed.ok) return consumed; @@ -247,8 +253,8 @@ export function createPresignedTransferExecutor( async function putUploadPart( input: Parameters[0], + capability: PresignedUploadPartCapability, ): Promise> { - let capability: PresignedUploadPartCapability; let bytes: Uint8Array; let request: Readonly<{ sessionId: string; @@ -262,7 +268,6 @@ export function createPresignedTransferExecutor( signal: AbortSignal; }>; try { - capability = input.capability; if (!(input.bytes instanceof Uint8Array)) { throw new TypeError("Upload bytes are invalid."); } @@ -325,7 +330,6 @@ export function createPresignedTransferExecutor( capability.expectedSha256 !== request.checksumSha256 || bytes.byteLength !== capability.byteLength ) { - revoke(capability); return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER"); } // TR-RR-02. The abort scope is created first, so the digest — which can be @@ -421,7 +425,6 @@ export function createPresignedTransferExecutor( return transferFailure(request.signal, scope.timedOut()); } finally { scope.release(); - revoke(capability); } } @@ -430,8 +433,12 @@ export function createPresignedTransferExecutor( input: Parameters[0], ) { let result: BrowserDataResult; + const capability = readCapability(input); try { - result = await openDownload(input); + result = + capability === UNREADABLE_CAPABILITY + ? browserDataFailure("INVALID_INPUT", "PRESIGNED_TRANSFER") + : await openDownload(input, capability); } catch { result = browserDataFailure( "UNAVAILABLE", @@ -441,6 +448,8 @@ export function createPresignedTransferExecutor( recovery: "REISSUE_CAPABILITY", }, ); + } finally { + release(capability); } observeTransferResult( observer, @@ -459,8 +468,12 @@ export function createPresignedTransferExecutor( input: Parameters[0], ) { let result: BrowserDataResult; + const capability = readCapability(input); try { - result = await putUploadPart(input); + result = + capability === UNREADABLE_CAPABILITY + ? browserDataFailure("INVALID_INPUT", "PRESIGNED_TRANSFER") + : await putUploadPart(input, capability); } catch { result = browserDataFailure( "UNAVAILABLE", @@ -470,6 +483,8 @@ export function createPresignedTransferExecutor( recovery: "REISSUE_CAPABILITY", }, ); + } finally { + release(capability); } // 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. @@ -1108,6 +1123,22 @@ async function digestSha256WithWebCrypto( ).join(""); } +/** + * 01-07. Reads the caller's capability once, so the identity released on the + * way out is the one the call resolved even if `capability` is an accessor. + */ +const UNREADABLE_CAPABILITY: unique symbol = Symbol("unreadable capability"); + +function readCapability( + input: Readonly<{ capability: T }>, +): T | typeof UNREADABLE_CAPABILITY { + try { + return input.capability; + } catch { + return UNREADABLE_CAPABILITY; + } +} + function safeInputByteLength(value: unknown): number | undefined { try { if (!value || typeof value !== "object") return undefined; diff --git a/tests/unit/presigned-transfer-download.test.ts b/tests/unit/presigned-transfer-download.test.ts index 2cd336f1..71854699 100644 --- a/tests/unit/presigned-transfer-download.test.ts +++ b/tests/unit/presigned-transfer-download.test.ts @@ -662,9 +662,23 @@ describe("presigned download stream lifecycle", () => { ok: false, error: { code: "INVALID_INPUT" }, }); + // 01-07. The refused open released the capability from the vault. + expect( + await executor.downloadSources.open({ + resourceId: "resource-1", + capability: issuedDownload.value, + signal: new AbortController().signal, + }), + ).toMatchObject({ ok: false, error: { code: "POLICY_REJECTED" } }); + const reissuedDownload = await provider.issueDownload({ + resourceId: "resource-1", + signal: new AbortController().signal, + }); + expect(reissuedDownload.ok).toBe(true); + if (!reissuedDownload.ok) return; const opened = await executor.downloadSources.open({ resourceId: "resource-1", - capability: issuedDownload.value, + capability: reissuedDownload.value, signal: new AbortController().signal, }); expect(opened.ok).toBe(true); diff --git a/tests/unit/presigned-transfer-upload.test.ts b/tests/unit/presigned-transfer-upload.test.ts index 3cc43f07..b3a3111b 100644 --- a/tests/unit/presigned-transfer-upload.test.ts +++ b/tests/unit/presigned-transfer-upload.test.ts @@ -723,6 +723,123 @@ describe("presigned vault slot release (01-07)", () => { }, ); + const earlyExits = { + "the caller signal is already aborted": { + override: { signal: AbortSignal.abort() }, + code: "ABORTED", + }, + "the byte length does not match the bytes": { + override: { byteLength: 4 }, + code: "INTEGRITY_FAILED", + }, + "the input is invalid": { + override: { idempotencyKey: "" }, + code: "INVALID_INPUT", + }, + "the signal is not an AbortSignal": { + override: { signal: {} as AbortSignal }, + code: "INVALID_INPUT", + }, + } as const; + + it.each(Object.keys(earlyExits) as (keyof typeof earlyExits)[])( + "frees the only vault slot when put() returns early because %s", + async (name) => { + const bytes = new Uint8Array([9, 8, 7]); + const checksum = sha256Hex(bytes); + let issued = 0; + const fetcher = vi.fn(async (input: RequestInfo | URL) => { + if (String(input) !== CONTROL_ENDPOINT) { + throw new Error("no PUT is expected"); + } + issued += 1; + return jsonResponse( + uploadCapabilityPayload( + { bytes, checksum }, + { capabilityReceipt: `capability-upload-${issued}` }, + ), + ); + }) as unknown as typeof fetch; + const { provider, executor } = createHarness({ + fetcher, + maxActiveCapabilities: 1, + }); + const issue = async () => + await provider.issueUploadPart({ + sessionId: UPLOAD_SESSION_ID, + requestBindingSha256: REQUEST_BINDING_SHA256, + uploadBindingSha256: "b".repeat(64), + partNumber: 1, + offset: 0, + byteLength: bytes.byteLength, + checksumSha256: checksum, + mediaType: "application/octet-stream", + idempotencyKey: "part-attempt-1", + signal: new AbortController().signal, + }); + const first = await issue(); + if (!first.ok) throw new Error("issue failed"); + + const { override, code } = earlyExits[name]; + const put = await executor.uploadParts.put({ + capability: first.value, + sessionId: UPLOAD_SESSION_ID, + requestBindingSha256: REQUEST_BINDING_SHA256, + uploadBindingSha256: "b".repeat(64), + partNumber: 1, + offset: 0, + byteLength: bytes.byteLength, + checksumSha256: checksum, + idempotencyKey: "part-attempt-1", + bytes, + signal: new AbortController().signal, + ...override, + }); + expect(put).toMatchObject({ ok: false, error: { code } }); + + expect((await issue()).ok).toBe(true); + }, + ); + + it.each([ + ["the caller signal is already aborted", AbortSignal.abort(), "ABORTED"], + ["the signal is not an AbortSignal", {} as AbortSignal, "INVALID_INPUT"], + ] as const)( + "frees the only vault slot when open() returns early because %s", + async (_name, signal, code) => { + const bytes = new Uint8Array([1, 2, 3]); + let issued = 0; + const fetcher = vi.fn(async () => { + issued += 1; + return jsonResponse( + downloadCapabilityPayload(bytes, { + capabilityReceipt: `capability-download-${issued}`, + }), + ); + }) as unknown as typeof fetch; + const { provider, executor } = createHarness({ + fetcher, + maxActiveCapabilities: 1, + }); + const issue = async () => + await provider.issueDownload({ + resourceId: "resource-1", + signal: new AbortController().signal, + }); + const first = await issue(); + if (!first.ok) throw new Error("issue failed"); + + const opened = await executor.downloadSources.open({ + resourceId: "resource-1", + capability: first.value, + signal, + }); + expect(opened).toMatchObject({ ok: false, error: { code } }); + + expect((await issue()).ok).toBe(true); + }, + ); + it("frees the only vault slot when a download open is refused", async () => { const bytes = new Uint8Array([1, 2, 3]); let issued = 0;