Files
clean-architecture-frontend…/src/adapters/browser-files/object-url-lease.ts
T
DongHyeonkaandClaude Opus 5.5 0b41cb38af fix(browser-files): report exhausted object URL leases as retryable (02-04)
Preview and download share one lease registry and download leases stay for a
30 s grace, so running out of slots clears on its own. Only a Blob above the
single-lease ceiling stays LIMIT_EXCEEDED without retry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:08:33 +09:00

360 lines
11 KiB
TypeScript

import type {
FilePolicyReference,
FileVerificationReceipt,
LocalFileRef,
PreviewLease,
TransientPreviewPort,
} from "../../application/ports/browser-file-storage/file.ts";
import type { BrowserDataResult } from "../../application/ports/browser-file-storage/shared.ts";
import { isValidByteLength } from "../../application/ports/browser-file-storage/shared.ts";
import {
abortedResult,
browserDataFailure,
browserDataSuccess,
mapBrowserDataException,
} from "../browser-file-storage/result.ts";
import type { NativeVerifiedFileResolver } from "./browser-file-vault.ts";
import {
byteBucket,
observeBrowserFile,
type BrowserFileObserver,
} from "./file-observer.ts";
import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts";
import { EXACT_MEDIA_TYPE, isPositiveSafeInteger } from "./file-policy.ts";
export type ObjectUrlApi = Readonly<{
createObjectURL(blob: Blob): string;
revokeObjectURL(url: string): void;
}>;
export type ObjectUrlLease = Readonly<{
url: string;
release(): void;
}>;
export type ObjectUrlLeaseLimits = Readonly<{
hardMaxActiveLeases: number;
hardMaxSingleLeaseBytes: number;
hardMaxAggregateLeaseBytes: number;
}>;
const DEFAULT_OBJECT_URL_LEASE_LIMITS: ObjectUrlLeaseLimits =
Object.freeze({
hardMaxActiveLeases: 16,
hardMaxSingleLeaseBytes: 64 * 1024 * 1024,
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<never> {
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.
*/
export class ObjectUrlLeaseRegistry {
readonly #createObjectURL: ObjectUrlApi["createObjectURL"];
readonly #revokeObjectURL: ObjectUrlApi["revokeObjectURL"];
readonly #limits: ObjectUrlLeaseLimits;
readonly #active = new Map<
string,
Readonly<{ release(): void; byteLength: number }>
>();
#aggregateByteLength = 0;
constructor(
urlApi: ObjectUrlApi = URL,
limits: ObjectUrlLeaseLimits = DEFAULT_OBJECT_URL_LEASE_LIMITS,
) {
const createObjectURL = urlApi.createObjectURL;
const revokeObjectURL = urlApi.revokeObjectURL;
if (
typeof createObjectURL !== "function" ||
typeof revokeObjectURL !== "function"
) {
throw new TypeError("Object URL API is invalid.");
}
this.#createObjectURL = createObjectURL.bind(urlApi);
this.#revokeObjectURL = revokeObjectURL.bind(urlApi);
this.#limits = Object.freeze({
hardMaxActiveLeases: limits.hardMaxActiveLeases,
hardMaxSingleLeaseBytes: limits.hardMaxSingleLeaseBytes,
hardMaxAggregateLeaseBytes:
limits.hardMaxAggregateLeaseBytes,
});
if (
!isPositiveSafeInteger(this.#limits.hardMaxActiveLeases) ||
!isPositiveSafeInteger(
this.#limits.hardMaxSingleLeaseBytes,
) ||
!isPositiveSafeInteger(
this.#limits.hardMaxAggregateLeaseBytes,
) ||
this.#limits.hardMaxSingleLeaseBytes >
this.#limits.hardMaxAggregateLeaseBytes
) {
throw new TypeError("Object URL lease limits are invalid.");
}
}
create(blob: Blob): ObjectUrlLease {
if (
!isValidByteLength(blob.size) ||
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(
"Object URL allocation failed",
"InvalidStateError",
);
}
if (this.#active.has(url)) {
throw new DOMException(
"Object URL allocation was not unique",
"InvalidStateError",
);
}
let released = false;
const release = (): void => {
if (released) return;
released = true;
if (this.#active.delete(url)) {
this.#aggregateByteLength -= blob.size;
}
try {
this.#revokeObjectURL(url);
} catch {
// Revocation is best effort and must remain idempotent.
}
};
this.#active.set(
url,
Object.freeze({ release, byteLength: blob.size }),
);
this.#aggregateByteLength += blob.size;
return Object.freeze({ url, release });
}
dispose(): void {
for (const lease of Array.from(this.#active.values())) {
lease.release();
}
}
get activeLeaseCount(): number {
return this.#active.size;
}
get aggregateLeaseByteLength(): number {
return this.#aggregateByteLength;
}
}
export type TransientPreviewOptions = Readonly<{
files: NativeVerifiedFileResolver;
policies: BrowserFilePolicyRegistry;
/**
* Runtime-owned absolute ceiling. Feature callers may request a lower
* maxPreviewBytes but can never raise this limit.
*/
hardMaxPreviewBytes: number;
leases?: ObjectUrlLeaseRegistry;
hardForbiddenMediaTypes?: ReadonlySet<string>;
observer?: BrowserFileObserver;
}>;
const DEFAULT_ACTIVE_CONTENT = new Set([
"application/pdf",
"application/xhtml+xml",
"application/xml",
"image/svg+xml",
"text/html",
"text/xml",
]);
export class BrowserTransientPreview implements TransientPreviewPort {
readonly #resolveVerifiedFile:
NativeVerifiedFileResolver["resolveVerifiedFile"];
readonly #resolvePreview:
BrowserFilePolicyRegistry["resolvePreview"];
readonly #createLease: ObjectUrlLeaseRegistry["create"];
readonly #disposeLeases: ObjectUrlLeaseRegistry["dispose"];
readonly #hardMaxPreviewBytes: number;
readonly #hardForbiddenMediaTypes: ReadonlySet<string>;
readonly #observer: BrowserFileObserver | undefined;
#disposed = false;
constructor(options: TransientPreviewOptions) {
this.#resolveVerifiedFile =
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);
this.#hardMaxPreviewBytes = options.hardMaxPreviewBytes;
this.#hardForbiddenMediaTypes = new Set([
...Array.from(
DEFAULT_ACTIVE_CONTENT,
(mediaType) => mediaType.toLowerCase(),
),
...Array.from(
options.hardForbiddenMediaTypes ?? [],
(mediaType) => mediaType.toLowerCase(),
),
]);
this.#observer = options.observer;
if (
!isValidByteLength(this.#hardMaxPreviewBytes) ||
this.#hardMaxPreviewBytes === 0
) {
throw new TypeError("Preview hard byte limit is invalid.");
}
}
async create(input: {
ref: LocalFileRef;
verificationReceipt: FileVerificationReceipt;
policy: FilePolicyReference;
maxPreviewBytes?: number;
signal: AbortSignal;
}): Promise<BrowserDataResult<PreviewLease>> {
if (this.#disposed) {
return this.#observe(
browserDataFailure("UNAVAILABLE", "PREVIEW"),
);
}
const cancelled = abortedResult(input.signal, "PREVIEW");
if (cancelled) return this.#observe(cancelled);
const resolvedPolicy = this.#resolvePreview(
input.policy,
input.maxPreviewBytes,
);
if (!resolvedPolicy.ok) return this.#observe(resolvedPolicy);
const policy = resolvedPolicy.value;
if (policy.maxPreviewBytes > this.#hardMaxPreviewBytes) {
return this.#observe(
browserDataFailure("LIMIT_EXCEEDED", "PREVIEW"),
);
}
try {
const resolved = await this.#resolveVerifiedFile({
ref: input.ref,
verificationReceipt: input.verificationReceipt,
verificationPolicyBindingId:
policy.verificationPolicyBindingId,
signal: input.signal,
});
if (!resolved.ok) return this.#observe(resolved);
if (this.#disposed) {
return this.#observe(
browserDataFailure("UNAVAILABLE", "PREVIEW"),
);
}
// 02-01. The caller may abort while the file resolves; a lease created
// after that would never be released because the caller drops the result.
const abortedWhileResolving = abortedResult(input.signal, "PREVIEW");
if (abortedWhileResolving) return this.#observe(abortedWhileResolving);
const mediaType = resolved.value.mediaType.trim().toLowerCase();
if (
!EXACT_MEDIA_TYPE.test(mediaType) ||
!policy.allowedMediaTypes.has(mediaType) ||
this.#hardForbiddenMediaTypes.has(mediaType)
) {
return this.#observe(
browserDataFailure("POLICY_REJECTED", "PREVIEW"),
);
}
if (resolved.value.file.size > policy.maxPreviewBytes) {
return this.#observe(
browserDataFailure("LIMIT_EXCEEDED", "PREVIEW"),
);
}
// A typed slice prevents the untrusted File.type from controlling how
// the object URL is interpreted.
const typedBlob = resolved.value.file.slice(
0,
resolved.value.file.size,
mediaType,
);
const lease = this.#createLease(typedBlob);
const preview: PreviewLease = Object.freeze({
url: lease.url,
mediaType,
release: lease.release,
});
observeBrowserFile(this.#observer, {
operation: "PREVIEW",
outcome: "SUCCESS",
byteBucket: byteBucket(resolved.value.file.size),
});
return browserDataSuccess(preview);
} catch (error) {
if (
error instanceof DOMException &&
error.name === "FileTooLargeError"
) {
return this.#observe(objectUrlLimitFailure(error, "PREVIEW"));
}
return this.#observe(mapBrowserDataException(error, "PREVIEW"));
}
}
dispose(): void {
if (this.#disposed) return;
this.#disposed = true;
this.#disposeLeases();
}
#observe<Value>(
result: BrowserDataResult<Value>,
): BrowserDataResult<Value> {
if (!result.ok) {
observeBrowserFile(this.#observer, {
operation: "PREVIEW",
outcome: "FAILED",
failureCode: result.error.code,
});
}
return result;
}
}