diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index 7018f740..a4bd9231 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -645,6 +645,14 @@ probe는 decode 크기가 primary 후보의 pixel 크기와 정확히 같아야 - private rendition은 짧은 expiry와 필수 `no-store`를 쓴다. - CDN cache hit 여부는 authorization이나 asset safety proof가 아니다. +`PRIMARY_REQUIRED` preset(private asset은 항상)의 `resolve()`는 primary candidate를 +preset의 encoded·decoded 예산까지 내려받아 decode한다. private 응답은 `no-store`라 +``가 같은 URL을 한 번 더 받는다. 그래서 runtime은 같은 asset reference와 +preset에 대해 통과한 probe를 capability가 유효한 동안 재사용하고, 동시에 도는 +probe를 `maxConcurrentProbes`(기본 4, 최대 32)개로 제한한다. 넘는 호출은 자리를 +기다리며, 기다리다 abort하면 자리를 차지하지 않는다(`image-cdn-runtime.ts` +`passedProbes`, `acquireProbeSlot`). + image probe의 단일 bounded deadline은 response header fetch, streamed body read와 native decode 전체를 포함한다. timeout/cancel/error 시 reader를 cancel하고, abort 뒤 늦게 resolve한 response body도 cancel하며 늦게 생성된 `ImageBitmap`도 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 717356bd..d27c41ce 100644 --- a/src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts +++ b/src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts @@ -43,6 +43,13 @@ export type ImageCdnRuntimeDependencies = Readonly<{ capabilityVerificationTimeoutMs?: number; capabilityVerificationScheduler?: ImageCapabilityVerificationScheduler; probe?: ImageResourceProbePort; + /** + * 01-11. Most probes in flight at once. Each downloads and decodes up to the + * preset's encoded and decoded byte budgets, so a screen of private images + * would otherwise hold all of them in memory together. Later calls wait for + * a slot. Default 4, at most 32. + */ + maxConcurrentProbes?: number; observer?: BrowserDataObserver; }>; @@ -188,6 +195,41 @@ export function createImageCdnRuntime( ); const probe = dependencies.probe?.probe.bind(dependencies.probe); + const maxConcurrentProbes = dependencies.maxConcurrentProbes ?? 4; + if ( + !Number.isSafeInteger(maxConcurrentProbes) || + maxConcurrentProbes < 1 || + maxConcurrentProbes > 32 + ) { + throw new TypeError("Image probe concurrency is invalid."); + } + let activeProbes = 0; + const probeWaiters: (() => void)[] = []; + const acquireProbeSlot = (): Promise => { + if (activeProbes < maxConcurrentProbes) { + activeProbes += 1; + return Promise.resolve(); + } + return new Promise((resolve) => { + probeWaiters.push(() => { + activeProbes += 1; + resolve(); + }); + }); + }; + const releaseProbeSlot = (): void => { + activeProbes -= 1; + probeWaiters.shift()?.(); + }; + /** + * 01-11. Asset+preset pairs whose primary candidate already passed a probe. + * `resolve()` re-checks capability expiry on every call, so a pass is reused + * only while the capability is still valid. + */ + const passedProbes = new WeakMap< + AssetSnapshot, + Set + >(); const observer = snapshotObserver(dependencies.observer); let acceptedAssets = new WeakMap(); @@ -542,7 +584,10 @@ export function createImageCdnRuntime( return browserDataFailure("POLICY_REJECTED", "IMAGE_RESOLVE"); } - if (preset.probeMode === "PRIMARY_REQUIRED") { + if ( + preset.probeMode === "PRIMARY_REQUIRED" && + !passedProbes.get(asset)?.has(preset) + ) { if (!probe || !request.signal) { return browserDataFailure("UNSUPPORTED", "IMAGE_RESOLVE"); } @@ -550,9 +595,16 @@ export function createImageCdnRuntime( let probeResult: BrowserDataResult; const probeScope = openOperation(request.signal); try { - probeResult = await raceImageRuntime( - probeScope, - probe({ + const slot = await probeScope.race( + acquireProbeSlot(), + releaseProbeSlot, + ); + if (slot.kind !== "VALUE") { + throw capabilityVerificationAbortException(); + } + let task: Promise>; + try { + task = Promise.resolve(probe({ absoluteUrl: descriptor.src, expectedMediaType: descriptor.fallbackMediaType, expectedWidth: primary.pixelWidth, @@ -565,8 +617,14 @@ export function createImageCdnRuntime( asset.origin.minimumPublicMaxAgeSeconds, referrerPolicy: descriptor.referrerPolicy, signal: probeScope.signal, - }), - ); + })); + } catch (error) { + task = Promise.reject(error); + } + // The slot belongs to the raw probe, not to this wrapper (as for + // capability verification, TR-RR-07). + void task.then(releaseProbeSlot, releaseProbeSlot); + probeResult = await raceImageRuntime(probeScope, task); } catch { probeResult = closed ? imageRuntimeClosedFailure() @@ -612,6 +670,10 @@ export function createImageCdnRuntime( hardLimits.minCapabilityRemainingMs, ); if (postProbeExpiry) return postProbeExpiry; + passedProbes.set( + asset, + (passedProbes.get(asset) ?? new Set()).add(preset), + ); } if (closed) return imageRuntimeClosedFailure(); diff --git a/src/application/ports/browser-transfer/image-cdn.ts b/src/application/ports/browser-transfer/image-cdn.ts index 1dfebf76..fd5e51e3 100644 --- a/src/application/ports/browser-transfer/image-cdn.ts +++ b/src/application/ports/browser-transfer/image-cdn.ts @@ -172,6 +172,14 @@ export interface ImageCdnPresentationPort { * missing signal as a runtime `UNSUPPORTED` result - a hidden preset * precondition. Requiring it at the type level removes that hidden rule * instead of discovering it at runtime. + * + * 01-11. Cost. With a `PRIMARY_REQUIRED` preset (always the case for private + * assets) the first call for an asset reference and preset downloads and + * decodes the primary candidate, up to the preset's encoded and decoded + * byte budgets. A private response is `no-store`, so `` fetches the + * same URL again. A passed probe is reused for that reference and preset + * while the capability is valid, and a bounded number of probes run at + * once; later calls wait for a slot. */ resolve(request: Readonly<{ asset: ImageAssetReference; diff --git a/tests/unit/image-cdn-runtime.test.ts b/tests/unit/image-cdn-runtime.test.ts index 1a851044..cc9f3b48 100644 --- a/tests/unit/image-cdn-runtime.test.ts +++ b/tests/unit/image-cdn-runtime.test.ts @@ -1440,3 +1440,139 @@ describe("production image CDN runtime", () => { ]); }); }); + +describe("image probe cost (01-11)", () => { + const preset = imageCdnPresetReference("probe-cost", "render-probed"); + const policies = () => + createPolicies([ + createPreset(preset, { + bindingId: "probe-cost-v1", + probeMode: "PRIMARY_REQUIRED", + }), + ]); + const receipt = (request: ImageProbeRequest) => ({ + ok: true as const, + value: { + absoluteUrl: request.absoluteUrl, + mediaType: request.expectedMediaType, + encodedBytes: 1_024, + decodedWidth: request.expectedWidth, + decodedHeight: request.expectedHeight, + }, + }); + + it("reuses a passed probe for the same asset and preset", async () => { + let fail = true; + const probe = vi.fn(async (request: ImageProbeRequest) => { + if (fail) { + fail = false; + return { + ok: false as const, + error: { + code: "UNAVAILABLE" as const, + operation: "IMAGE_RESOLVE" as const, + retryable: true, + recovery: "RETRY" as const, + }, + }; + } + return receipt(request); + }); + const runtime = createImageCdnRuntime({ + policies: policies(), + probe: { probe }, + }); + const accepted = runtime.assets.acceptPublicImmutable(publicAsset()); + if (!accepted.ok) throw new Error("accept failed"); + const resolve = async () => + await runtime.presentation.resolve({ + asset: accepted.value, + preset, + signal: new AbortController().signal, + }); + + // A failed probe is not remembered; the first pass is. + expect((await resolve()).ok).toBe(false); + const first = await resolve(); + const second = await resolve(); + + expect(first.ok && second.ok).toBe(true); + expect(second).toEqual(first); + expect(probe).toHaveBeenCalledTimes(2); + }); + + it("never runs more probes at once than maxConcurrentProbes", async () => { + let active = 0; + let peak = 0; + const releases: (() => void)[] = []; + const probe = vi.fn(async (request: ImageProbeRequest) => { + active += 1; + peak = Math.max(peak, active); + await new Promise((resolve) => releases.push(resolve)); + active -= 1; + return receipt(request); + }); + const runtime = createImageCdnRuntime({ + policies: policies(), + probe: { probe }, + maxConcurrentProbes: 2, + }); + const pending = Array.from({ length: 5 }, () => { + const accepted = runtime.assets.acceptPublicImmutable(publicAsset()); + if (!accepted.ok) throw new Error("accept failed"); + return runtime.presentation.resolve({ + asset: accepted.value, + preset, + signal: new AbortController().signal, + }); + }); + for (let released = 0; released < 5; released += 1) { + await vi.waitFor(() => expect(releases.length).toBeGreaterThan(0)); + releases.shift()?.(); + } + const results = await Promise.all(pending); + + expect(results.every((result) => result.ok)).toBe(true); + expect(probe).toHaveBeenCalledTimes(5); + expect(peak).toBe(2); + }); + + it("gives a waiting caller's slot back when it aborts before its turn", async () => { + const releases: (() => void)[] = []; + const probe = vi.fn(async (request: ImageProbeRequest) => { + await new Promise((resolve) => releases.push(resolve)); + return receipt(request); + }); + const runtime = createImageCdnRuntime({ + policies: policies(), + probe: { probe }, + maxConcurrentProbes: 1, + }); + const resolveNew = (signal: AbortSignal) => { + const accepted = runtime.assets.acceptPublicImmutable(publicAsset()); + if (!accepted.ok) throw new Error("accept failed"); + return runtime.presentation.resolve({ + asset: accepted.value, + preset, + signal, + }); + }; + const holder = resolveNew(new AbortController().signal); + await vi.waitFor(() => expect(releases).toHaveLength(1)); + const waiting = new AbortController(); + const abandoned = resolveNew(waiting.signal); + waiting.abort(); + expect(await abandoned).toMatchObject({ + ok: false, + error: { code: "ABORTED" }, + }); + releases.shift()?.(); + expect((await holder).ok).toBe(true); + + const next = resolveNew(new AbortController().signal); + await vi.waitFor(() => expect(releases).toHaveLength(1)); + releases.shift()?.(); + expect((await next).ok).toBe(true); + expect(probe).toHaveBeenCalledTimes(2); + }); +});