diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/architecture/browser-file-and-origin-storage.md index 8c8abe85..abe95cd4 100644 --- a/docs/architecture/browser-file-and-origin-storage.md +++ b/docs/architecture/browser-file-and-origin-storage.md @@ -353,6 +353,13 @@ digest 또는 별도 검토된 streaming hash adapter를 사용한다. - one-shot 작은 download는 click handoff 뒤 cross-engine scheduling을 위해 기본 30초 grace를 두고 revoke한다. feature/runtime dispose는 grace를 기다리지 않고 모든 active lease를 즉시 revoke한다. +- preview와 download는 runtime 하나의 lease registry를 같이 쓴다 + (`src/adapters/browser-files/create-browser-file-runtime.ts:154`, `:163`). + lease 개수나 합계 바이트 한도가 차면 둘 다 `LIMIT_EXCEEDED`를 + `retryable: true`, `recovery: "RETRY"`로 반환한다 + (`src/adapters/browser-files/object-url-lease.ts:48-73`, `:131-139`). download + lease는 grace(`download-delivery-adapter.ts:149`)가 끝나면 풀리므로 잠시 뒤 + 다시 시도하면 된다. Blob 하나가 단일 lease 상한을 넘으면 재시도 불가다. - URL을 global state, IndexedDB, query cache, log, analytics에 보관하지 않는다. - Service Worker에서 object URL을 사용하지 않는다. - 로그아웃·계정 전환에서는 runtime 전체를 dispose한다. browser file runtime은 diff --git a/src/adapters/browser-files/download-delivery-adapter.ts b/src/adapters/browser-files/download-delivery-adapter.ts index 8e3eeed4..eaf478f2 100644 --- a/src/adapters/browser-files/download-delivery-adapter.ts +++ b/src/adapters/browser-files/download-delivery-adapter.ts @@ -31,6 +31,7 @@ import { } from "./file-observer.ts"; import { ObjectUrlLeaseRegistry, + objectUrlLimitFailure, type ObjectUrlLease, } from "./object-url-lease.ts"; import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts"; @@ -1032,7 +1033,7 @@ function mapDownloadException( return browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD"); } if (error.name === "FileTooLargeError") { - return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD"); + return objectUrlLimitFailure(error, "DOWNLOAD"); } } return mapBrowserDataException(error, "DOWNLOAD"); diff --git a/src/adapters/browser-files/object-url-lease.ts b/src/adapters/browser-files/object-url-lease.ts index fe7e24c4..41784fbe 100644 --- a/src/adapters/browser-files/object-url-lease.ts +++ b/src/adapters/browser-files/object-url-lease.ts @@ -45,6 +45,31 @@ const DEFAULT_OBJECT_URL_LEASE_LIMITS: ObjectUrlLeaseLimits = hardMaxAggregateLeaseBytes: 256 * 1024 * 1024, }); +/** + * 02-04. Every lease slot or the aggregate byte budget is in use. Leases free + * up when released (a download after its revoke grace), so unlike one Blob + * above the single-lease ceiling this is reported as retryable. + */ +class ObjectUrlLeasesExhaustedError extends DOMException { + constructor() { + super("Object URL leases exhausted", "FileTooLargeError"); + } +} + +/** Maps a `FileTooLargeError` from the registry or a byte cap. */ +export function objectUrlLimitFailure( + error: DOMException, + operation: "PREVIEW" | "DOWNLOAD", +): BrowserDataResult { + return browserDataFailure( + "LIMIT_EXCEEDED", + operation, + error instanceof ObjectUrlLeasesExhaustedError + ? { retryable: true, recovery: "RETRY" } + : {}, + ); +} + /** * The only low-level owner of object URL creation/revocation. Every lease is * idempotent and dispose() is a final safety net for route/runtime teardown. @@ -97,17 +122,21 @@ export class ObjectUrlLeaseRegistry { create(blob: Blob): ObjectUrlLease { if ( !isValidByteLength(blob.size) || - blob.size > this.#limits.hardMaxSingleLeaseBytes || - this.#active.size >= this.#limits.hardMaxActiveLeases || - !Number.isSafeInteger(this.#aggregateByteLength + blob.size) || - this.#aggregateByteLength + blob.size > - this.#limits.hardMaxAggregateLeaseBytes + blob.size > this.#limits.hardMaxSingleLeaseBytes ) { throw new DOMException( "Object URL lease limit exceeded", "FileTooLargeError", ); } + if ( + this.#active.size >= this.#limits.hardMaxActiveLeases || + !Number.isSafeInteger(this.#aggregateByteLength + blob.size) || + this.#aggregateByteLength + blob.size > + this.#limits.hardMaxAggregateLeaseBytes + ) { + throw new ObjectUrlLeasesExhaustedError(); + } const url = this.#createObjectURL(blob); if (typeof url !== "string" || url.length === 0) { throw new DOMException( @@ -303,9 +332,7 @@ export class BrowserTransientPreview implements TransientPreviewPort { error instanceof DOMException && error.name === "FileTooLargeError" ) { - return this.#observe( - browserDataFailure("LIMIT_EXCEEDED", "PREVIEW"), - ); + return this.#observe(objectUrlLimitFailure(error, "PREVIEW")); } return this.#observe(mapBrowserDataException(error, "PREVIEW")); } diff --git a/tests/unit/browser-file-content.test.ts b/tests/unit/browser-file-content.test.ts index ea59c774..80a4d1fe 100644 --- a/tests/unit/browser-file-content.test.ts +++ b/tests/unit/browser-file-content.test.ts @@ -634,6 +634,38 @@ describe("browser file content policy", () => { expect(revoked).toEqual([]); }); + it("reports a preview that finds every lease slot in use as retryable (02-04)", async () => { + let urlSequence = 0; + const leases = new ObjectUrlLeaseRegistry( + { + createObjectURL: () => `blob:slot-${urlSequence++}`, + revokeObjectURL() {}, + }, + { + hardMaxActiveLeases: 1, + hardMaxSingleLeaseBytes: 16, + hardMaxAggregateLeaseBytes: 16, + }, + ); + const { preview, request } = await verifiedPngPreview(leases); + const held = leases.create(new Blob([new Uint8Array(1)])); + + expect( + await preview.create(request(new AbortController().signal)), + ).toMatchObject({ + ok: false, + error: { + code: "LIMIT_EXCEEDED", + retryable: true, + recovery: "RETRY", + }, + }); + held.release(); + expect( + await preview.create(request(new AbortController().signal)), + ).toMatchObject({ ok: true }); + }); + it("cannot weaken the built-in active-content preview denylist", async () => { const htmlPolicy = browserFilePolicyReference( "active-content", diff --git a/tests/unit/browser-file-runtime.test.ts b/tests/unit/browser-file-runtime.test.ts index 62b71ab1..78155222 100644 --- a/tests/unit/browser-file-runtime.test.ts +++ b/tests/unit/browser-file-runtime.test.ts @@ -176,6 +176,72 @@ describe("browser file runtime hard limits and disposal", () => { expect(revoked).toEqual(["blob:runtime-download"]); }); + it("reports exhausted object URL leases as retryable until the grace ends (02-04)", async () => { + const scheduled: Array<() => void> = []; + let urlSequence = 0; + const runtime = createBrowserFileRuntime({ + input: fileInput(), + policies, + limits: { + hardMaxPreviewBytes: 8, + hardMaxObjectUrlBytes: 8, + hardMaxTransferBytes: 16, + hardMaxActiveObjectUrls: 2, + }, + objectUrlApi: { + createObjectURL: () => `blob:runtime-download-${urlSequence++}`, + revokeObjectURL() {}, + }, + download: { + host: { handoff: vi.fn() }, + browserManagedCapabilities: + unusedBrowserManagedCapabilities, + scheduler: { + setTimeout(callback) { + scheduled.push(callback); + return scheduled.length; + }, + }, + }, + }); + const deliver = () => + runtime.downloads.deliver({ + policy: downloadPolicy, + source: { + kind: "GENERATED", + bytes: { + byteLength: 3, + async *stream() { + yield { ok: true, value: new Uint8Array([1, 2, 3]) }; + }, + }, + }, + suggestedFileName: "artifact", + signal: new AbortController().signal, + onProgress() {}, + }); + + // Each handoff keeps its lease for the revoke grace, so the third + // download inside that window finds every slot in use. + expect(await deliver()).toMatchObject({ ok: true }); + expect(await deliver()).toMatchObject({ ok: true }); + expect(await deliver()).toMatchObject({ + ok: false, + error: { + code: "LIMIT_EXCEEDED", + retryable: true, + recovery: "RETRY", + }, + }); + + for (const release of scheduled.splice(0)) release(); + expect(await deliver()).toMatchObject({ + ok: true, + value: { kind: "BROWSER_HANDOFF" }, + }); + runtime.dispose(); + }); + it("aborts a pending native picker and prevents event resurrection", async () => { const input = fileInput(); Object.defineProperty(input, "click", {