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);
+ });
+});