fix(browser-files): preview와 download의 dispose가 자기 lease만 푼다 (02-01)
문제: runtime은 object URL lease registry 하나를 preview와 download에 같이 넘긴다. 두 쪽의 dispose()가 모두 registry 전체의 dispose()를 불러, 누가 만든 lease인지 구분하지 않고 전부 revoke한다. runtime.previews.dispose()를 부르면 30초 grace 중인 download blob URL까지 바로 revoke된다(E-9). 브라우저가 아직 blob을 읽기 전이면 그 download가 실패할 수 있다. 반대로 download의 dispose()는 다른 화면의 preview URL을 끊는다. registry 주석은 이 dispose를 "route teardown" 에서 쓰라고 읽혔다. 고른 방법(리뷰 5.2절의 (나)): 한도는 같이 쓰고 해제 권한만 나눈다. registry에 scope()를 두어 소비자마다 자기가 만든 lease 집합을 들고, scope의 dispose()는 그것만 release한다. preview와 download adapter는 각자 scope로 lease를 만든다. registry 전체 dispose()는 runtime.dispose()만 부른다. 포트 시그니처는 그대로이고, TransientPreviewPort.dispose()에 효과 범위를 주석으로 적었다. 설계 문서 3.5절에 해제 권한과 route 정리 방법을 적고, 바뀐 줄 번호를 맞췄다. 버린 대안: - 포트 주석만 고친다(가). 함정이 코드에 그대로 남는다. - 소비자마다 registry를 나눈다(다). 해제 범위는 맞지만 탭 전체의 합계 바이트 상한이 두 곳으로 갈라진다. - TransientPreviewPort에서 dispose()를 뺀다(라). 공개 포트 변경이라 이번 범위(포트는 추가만)를 넘는다. (나)와 함께 할 수 있어 남겨 둔다. 위험·한계: - previews.dispose() 뒤 그 runtime의 preview가 계속 UNAVAILABLE인 것(영향 ②)과, previews.dispose()가 다른 화면의 preview lease까지 푸는 것(영향 ①, 같은 소비자 안)은 그대로다. 문서에 route 정리는 lease마다 release()로 하라고 적었다. 완전히 막으려면 (라)가 필요하다. - scope가 들고 있는 release 함수 집합만큼 메모리가 조금 는다. lease release 때 집합에서 빠지므로 lease 수 상한(기본 16)을 넘지 않는다. - file-transfer 레시피 번들이 55,856 → 55,937 gzip bytes가 되어 예산 55,900을 넘었다. 다음 백 단위 규칙대로 56,000으로 올렸다. 검증: - RED(수정 전): browser-file-runtime.test.ts 새 1건 "expected [ 'blob:runtime-download' ] to deeply equal []"(previews.dispose()가 download URL을 revoke). browser-file-download.test.ts 새 1건 "expected [ 'blob:shared-1', 'blob:shared-2' ] to deeply equal [ 'blob:shared-2' ]"(download dispose()가 다른 소비자의 lease를 revoke). - GREEN: browser-file 단위 5파일 64건 통과. runtime dispose가 모든 lease를 즉시 revoke하는 기존 테스트도 통과. - 회귀: browser-file·presigned·json-schema 단위 10파일 168건 통과. tsc app·test·recipes 통과. 바꾼 파일 eslint 통과. check-architecture (exec 전용 shim) 통과, check-adapter-inventory 통과, verify-documentation-readiness PASS_SCOPED, check-optional-recipes(source) file-transfer 55937/56000. Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
This commit is contained in:
@@ -195,7 +195,7 @@
|
||||
"lifecycleMethods": ["release-file-ref", "release-or-dispose-preview-leases", "cancel-via-AbortSignal", "reconcile-or-explicitly-abort-upload", "close-checkpoint-store", "dispose-capability-and-image-runtime", "dispose-browser-file-runtime-on-logout-or-account-switch"],
|
||||
"owner": "project-owner-required",
|
||||
"securityPrivacy": ["Treat file name, extension, MIME and lastModified as untrusted metadata.", "Resolve only exact composition-issued file and image policy object identities; callers cannot raise byte, candidate, pixel, quality, format, lifetime or origin ceilings.", "Use opaque file references and verification receipts bound to an inspected immutable file snapshot and the exact registered profile; reject replay through another profile even when an inspection rule ID matches.", "Treat presigned URLs as bearer capabilities; bind exact method, resource or upload part, offset, length, media type, checksum, origin, path, query, headers and expiry in an in-memory identity vault.", "Use credentials omit, redirect error, no-referrer and no-store for direct data-plane fetch; never persist or observe URL, query, signed header, capability, file name or raw backend message, and never emit digest, raw ETag or receipt values to diagnostics or telemetry.", "A strict account-partitioned upload checkpoint may persist only the protocol-defined SHA-256 file fingerprint, per-part checksum and bounded opaque non-authorizing part receipt token required for server reconciliation; no bearer token or raw signed capability is allowed.", "Persist only strict non-authorizing upload checkpoints and reconcile them with server-authoritative status and re-hashed local parts before completion.", "Require a synchronous server-issued browser-managed download capability whose receipt exactly equals the caller's branded capability receipt and whose resource, media type, safe extension, maximum bytes, optional digest and expiry all match before handoff.", "Expose File, OPFS, Cache and transfer byte streams only as chunk-level closed Results; stop after the first failure, cancel native readers and never throw a raw native exception across the port.", "Accept Image CDN assets only through immutable allowlisted or signature-verified descriptors and registered preset identities; reject active formats, arbitrary transforms, pixel/decode-budget overflow and unsafe cache policy.", "Upload completion remains QUARANTINED until backend scan and promotion; client capability checks are not an authorization boundary.", "Active content preview requires isolation or download-only treatment."],
|
||||
"bundleBudgetGzipBytes": 55900,
|
||||
"bundleBudgetGzipBytes": 56000,
|
||||
"fallback": "Accessible native file input, same-origin authorized server upload/download and a single bounded server-selected image rendition; generated artifacts above the buffer budget move to server-side generation.",
|
||||
"removal": ["Stop new capability and upload-session issuance, then cancel active reads and transfers.", "Reconcile or explicitly abort active multipart sessions and let backend TTL cleanup remove ambiguous orphans.", "Remove non-secret checkpoints according to account and retention policy.", "Release file references, revoke preview object-URL leases and dispose file, capability and image runtimes.", "Remove transfer/image feature facades and composition, then prove browser-transfer sources are absent from the production module inventory."],
|
||||
"serverStatePolicy": "query-cache-metadata-only"
|
||||
|
||||
@@ -351,21 +351,26 @@ digest 또는 별도 검토된 streaming hash adapter를 사용한다.
|
||||
|
||||
- preview 대상 교체, load error, unmount에서 정확히 한 번 revoke한다.
|
||||
- one-shot 작은 download는 click handoff 뒤 cross-engine scheduling을 위해 기본
|
||||
30초 grace를 두고 revoke한다. feature/runtime dispose는 grace를 기다리지 않고
|
||||
30초 grace를 두고 revoke한다. 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`)가 끝나면 풀리므로 잠시 뒤
|
||||
(`src/adapters/browser-files/object-url-lease.ts:48-71`, `:143-151`). download
|
||||
lease는 grace(`download-delivery-adapter.ts:150`)가 끝나면 풀리므로 잠시 뒤
|
||||
다시 시도하면 된다. Blob 하나가 단일 lease 상한을 넘으면 재시도 불가다.
|
||||
- 한도는 같이 쓰지만 해제 권한은 나뉜다. `runtime.previews.dispose()`와
|
||||
download의 `dispose()`는 각자 만든 lease만 revoke한다(`ObjectUrlLeaseScope`).
|
||||
registry 전체를 비우는 것은 `runtime.dispose()`뿐이다. `previews.dispose()`
|
||||
뒤에는 그 runtime의 preview가 계속 `UNAVAILABLE`이므로 route 정리에는 쓰지
|
||||
않고 lease마다 `release()`한다.
|
||||
- URL을 global state, IndexedDB, query cache, log, analytics에 보관하지 않는다.
|
||||
- Service Worker에서 object URL을 사용하지 않는다.
|
||||
- 로그아웃·계정 전환에서는 runtime 전체를 dispose한다. browser file runtime은
|
||||
세션을 모른다(`src/adapters/browser-files/create-browser-file-runtime.ts:93`).
|
||||
`runtime.dispose()`(`:177-185`)가 이전 사용자가 고른 File 참조, preview lease,
|
||||
진행 중 download(`download-delivery-adapter.ts:385-391`)를 한 번에 닫는다.
|
||||
`runtime.dispose()`(`:177-188`)가 이전 사용자가 고른 File 참조, preview lease,
|
||||
진행 중 download(`download-delivery-adapter.ts:390-396`)를 한 번에 닫는다.
|
||||
runtime을 route·feature보다 오래 사는 곳에서 만들었다면 server-state scope
|
||||
reset participant(`src/adapters/query-cache/server-state-scope-runtime.ts:19`,
|
||||
등록 예 `src/bootstrap/runtime-adapters.ts:410-416`)로 `dispose()`를 등록하고
|
||||
|
||||
@@ -181,6 +181,9 @@ export function createBrowserFileRuntime(
|
||||
enhancedPicker?.dispose();
|
||||
downloads.dispose();
|
||||
previews.dispose();
|
||||
// 2026-11-01 02-01. The shared registry is the runtime's alone to end;
|
||||
// previews and downloads above released only their own leases.
|
||||
objectUrls.dispose();
|
||||
vault.dispose();
|
||||
},
|
||||
});
|
||||
|
||||
@@ -33,6 +33,7 @@ import {
|
||||
ObjectUrlLeaseRegistry,
|
||||
objectUrlLimitFailure,
|
||||
type ObjectUrlLease,
|
||||
type ObjectUrlLeaseScope,
|
||||
} from "./object-url-lease.ts";
|
||||
import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts";
|
||||
import { isPositiveSafeInteger, isSafeGeneratedToken } from "./file-policy.ts";
|
||||
@@ -155,7 +156,10 @@ interface DisposableDownloadDeliveryPort extends DownloadDeliveryPort {
|
||||
export function createDownloadDeliveryAdapter(
|
||||
options: DownloadDeliveryAdapterOptions,
|
||||
): DisposableDownloadDeliveryPort {
|
||||
const objectUrls = options.objectUrls ?? new ObjectUrlLeaseRegistry();
|
||||
// 2026-11-01 02-01. dispose() revokes only the URLs this adapter made.
|
||||
const objectUrls = (
|
||||
options.objectUrls ?? new ObjectUrlLeaseRegistry()
|
||||
).scope();
|
||||
const createTransferId =
|
||||
options.createTransferId ??
|
||||
(() => `transfer:${globalThis.crypto.randomUUID()}`);
|
||||
@@ -725,7 +729,7 @@ async function boundedObjectUrlHandoff(context: Readonly<{
|
||||
suggestedFileName: string;
|
||||
transferId: string;
|
||||
options: DownloadDeliveryAdapterOptions;
|
||||
objectUrls: ObjectUrlLeaseRegistry;
|
||||
objectUrls: ObjectUrlLeaseScope;
|
||||
scheduler: DownloadScheduler;
|
||||
releaseDelayMs: number;
|
||||
progress: ProgressReporter;
|
||||
|
||||
@@ -70,9 +70,21 @@ export function objectUrlLimitFailure(
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 2026-11-01 02-01. One consumer's share of a registry: `dispose()` releases
|
||||
* only the leases this scope created. Previews and downloads share one
|
||||
* registry so the tab has one byte budget, but neither may revoke the other's
|
||||
* URLs (a download in its revoke grace, a preview another screen shows).
|
||||
*/
|
||||
export type ObjectUrlLeaseScope = Readonly<{
|
||||
create(blob: Blob): ObjectUrlLease;
|
||||
dispose(): void;
|
||||
}>;
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* idempotent and dispose() is a final safety net for runtime teardown only;
|
||||
* consumers dispose their own `scope()`.
|
||||
*/
|
||||
export class ObjectUrlLeaseRegistry {
|
||||
readonly #createObjectURL: ObjectUrlApi["createObjectURL"];
|
||||
@@ -177,6 +189,24 @@ export class ObjectUrlLeaseRegistry {
|
||||
}
|
||||
}
|
||||
|
||||
scope(): ObjectUrlLeaseScope {
|
||||
const owned = new Set<() => void>();
|
||||
return Object.freeze({
|
||||
create: (blob: Blob): ObjectUrlLease => {
|
||||
const lease = this.create(blob);
|
||||
const release = (): void => {
|
||||
owned.delete(release);
|
||||
lease.release();
|
||||
};
|
||||
owned.add(release);
|
||||
return Object.freeze({ url: lease.url, release });
|
||||
},
|
||||
dispose: (): void => {
|
||||
for (const release of Array.from(owned)) release();
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
get activeLeaseCount(): number {
|
||||
return this.#active.size;
|
||||
}
|
||||
@@ -213,8 +243,8 @@ export class BrowserTransientPreview implements TransientPreviewPort {
|
||||
NativeVerifiedFileResolver["resolveVerifiedFile"];
|
||||
readonly #resolvePreview:
|
||||
BrowserFilePolicyRegistry["resolvePreview"];
|
||||
readonly #createLease: ObjectUrlLeaseRegistry["create"];
|
||||
readonly #disposeLeases: ObjectUrlLeaseRegistry["dispose"];
|
||||
readonly #createLease: ObjectUrlLeaseScope["create"];
|
||||
readonly #disposeLeases: ObjectUrlLeaseScope["dispose"];
|
||||
readonly #hardMaxPreviewBytes: number;
|
||||
readonly #hardForbiddenMediaTypes: ReadonlySet<string>;
|
||||
readonly #observer: BrowserFileObserver | undefined;
|
||||
@@ -225,10 +255,11 @@ export class BrowserTransientPreview implements TransientPreviewPort {
|
||||
options.files.resolveVerifiedFile.bind(options.files);
|
||||
this.#resolvePreview =
|
||||
options.policies.resolvePreview.bind(options.policies);
|
||||
const leases =
|
||||
options.leases ?? new ObjectUrlLeaseRegistry();
|
||||
this.#createLease = leases.create.bind(leases);
|
||||
this.#disposeLeases = leases.dispose.bind(leases);
|
||||
const leases = (
|
||||
options.leases ?? new ObjectUrlLeaseRegistry()
|
||||
).scope();
|
||||
this.#createLease = leases.create;
|
||||
this.#disposeLeases = leases.dispose;
|
||||
this.#hardMaxPreviewBytes = options.hardMaxPreviewBytes;
|
||||
this.#hardForbiddenMediaTypes = new Set([
|
||||
...Array.from(
|
||||
|
||||
@@ -163,6 +163,11 @@ export interface TransientPreviewPort {
|
||||
signal: AbortSignal;
|
||||
}): Promise<BrowserDataResult<PreviewLease>>;
|
||||
|
||||
/**
|
||||
* Revokes every preview lease this port created and refuses later previews
|
||||
* for good. Other consumers' object URLs (downloads) are not touched. Route
|
||||
* teardown releases each lease instead (2026-11-01 02-01).
|
||||
*/
|
||||
dispose(): void;
|
||||
}
|
||||
|
||||
|
||||
@@ -767,6 +767,44 @@ describe("browser download delivery", () => {
|
||||
expect(revoked).toEqual(["blob:download-1"]);
|
||||
});
|
||||
|
||||
it("revokes only its own leases on dispose when the registry is shared (2026-11-01 02-01)", async () => {
|
||||
const revoked: string[] = [];
|
||||
let urlSequence = 0;
|
||||
const leases = new ObjectUrlLeaseRegistry({
|
||||
createObjectURL: () => `blob:shared-${++urlSequence}`,
|
||||
revokeObjectURL: (url) => revoked.push(url),
|
||||
});
|
||||
// Another consumer of the same budget, as previews are in the runtime.
|
||||
const otherLease = leases.create(new Blob(["preview"]));
|
||||
const adapter = createDownloadDeliveryAdapter({
|
||||
...HARD_LIMITS,
|
||||
policies,
|
||||
host: { handoff: vi.fn() },
|
||||
browserManagedCapabilities: capabilityResolver(),
|
||||
objectUrls: leases,
|
||||
scheduler: { setTimeout: () => 1 },
|
||||
userActivation: { isActive: true },
|
||||
});
|
||||
expect(
|
||||
await adapter.deliver(
|
||||
deliveryInput(
|
||||
{
|
||||
kind: "GENERATED",
|
||||
bytes: byteSource([new Uint8Array([1, 2, 3])]),
|
||||
},
|
||||
"BOUNDED_OBJECT_URL",
|
||||
),
|
||||
),
|
||||
).toMatchObject({ ok: true, value: { kind: "BROWSER_HANDOFF" } });
|
||||
|
||||
adapter.dispose();
|
||||
|
||||
expect(revoked).toEqual(["blob:shared-2"]);
|
||||
expect(leases.activeLeaseCount).toBe(1);
|
||||
otherLease.release();
|
||||
expect(revoked).toEqual(["blob:shared-2", "blob:shared-1"]);
|
||||
});
|
||||
|
||||
it("captures object URL methods at registry construction", () => {
|
||||
const originalCreate = vi.fn(() => "blob:captured");
|
||||
const originalRevoke = vi.fn();
|
||||
|
||||
@@ -176,6 +176,56 @@ describe("browser file runtime hard limits and disposal", () => {
|
||||
expect(revoked).toEqual(["blob:runtime-download"]);
|
||||
});
|
||||
|
||||
it("keeps a download URL in its grace period when only previews are disposed (2026-11-01 02-01)", async () => {
|
||||
const revoked: string[] = [];
|
||||
const runtime = createBrowserFileRuntime({
|
||||
input: fileInput(),
|
||||
policies,
|
||||
limits: {
|
||||
hardMaxPreviewBytes: 8,
|
||||
hardMaxObjectUrlBytes: 8,
|
||||
hardMaxTransferBytes: 16,
|
||||
},
|
||||
objectUrlApi: {
|
||||
createObjectURL: () => "blob:runtime-download",
|
||||
revokeObjectURL: (url) => revoked.push(url),
|
||||
},
|
||||
download: {
|
||||
host: { handoff: vi.fn() },
|
||||
browserManagedCapabilities:
|
||||
unusedBrowserManagedCapabilities,
|
||||
// The 30 s grace never ends inside this test.
|
||||
scheduler: { setTimeout: () => 1 },
|
||||
},
|
||||
});
|
||||
|
||||
expect(
|
||||
await runtime.downloads.deliver({
|
||||
policy: downloadPolicy,
|
||||
source: {
|
||||
kind: "GENERATED",
|
||||
bytes: {
|
||||
byteLength: 3,
|
||||
async *stream() {
|
||||
yield { ok: true as const, value: new Uint8Array([1, 2, 3]) };
|
||||
},
|
||||
},
|
||||
},
|
||||
suggestedFileName: "artifact",
|
||||
maxTransferBytes: 8,
|
||||
maxBufferedBytes: 8,
|
||||
signal: new AbortController().signal,
|
||||
onProgress() {},
|
||||
}),
|
||||
).toMatchObject({ ok: true, value: { kind: "BROWSER_HANDOFF" } });
|
||||
|
||||
runtime.previews.dispose();
|
||||
expect(revoked).toEqual([]);
|
||||
|
||||
runtime.dispose();
|
||||
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;
|
||||
|
||||
Reference in New Issue
Block a user