@aglyn/tenant-data-admin 1.0.0-beta.221 → 1.0.0-beta.223

package/src/lib/server/live-page-drops.js

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * HOW THIS PROCESS DROPS ONE SITE'S CACHED PAGES, for a write that worked out
+ * which of them it made stale (AGL-3113, AGL-3080).
+ *
+ * A record write — a dataset row, a collection entry — refreshes the pages
+ * that show it, and nothing else. Working out WHICH pages is the writer's: the
+ * data plugin walks the pages that repeat over a dataset, the collection scan
+ * the pages that list an entry. HOW a page is dropped is the runtime's, and
+ * the two runtimes do it differently: the tenant drops its own caches in
+ * process, and the console announces over the shared secret and passes its own
+ * dropper at the call site. So the deployment that owns the caches registers
+ * the dropper here, and a writer reads it; neither names the other.
+ *
+ * ## One per process, on `globalThis`
+ *
+ * The tenant registers from `instrumentation.ts`, by name, at boot. Next
+ * compiles that file apart from the routes, so a dropper held in a module
+ * `let` was set in the boot's copy of this module and read as missing by
+ * every route's copy — a form submission or an automation step that wrote a
+ * row logged `no-live-page-dropper` and left the pages stale for the rest of
+ * their window (AGL-3412 was the same split for the plugin services). Keyed on
+ * `globalThis` under `Symbol.for`, every copy in a realm reads the one slot.
+ */ /** One site's share of a change: the pages on it that must be dropped. */ const DROPPER_KEY = Symbol.for('@aglyn/tenant-data-admin:live-page-dropper');
+const globalScope = globalThis;
+/**
+ * Registers the dropper for this process, replacing any previous one. Returns
+ * the unregister, which removes it only if it is still the one registered.
+ *
+ * Called from a function the platform calls BY NAME at boot, never from a
+ * module's top level: a bundler deletes a module imported only for its side
+ * effect when its package says it has none (AGL-3025).
+ */ export function registerLivePageDropper(drop) {
+    globalScope[DROPPER_KEY] = drop;
+    return ()=>{
+        if (globalScope[DROPPER_KEY] === drop) delete globalScope[DROPPER_KEY];
+    };
+}
+/** The dropper this process registered, or `undefined` when none did. */ export function registeredLivePageDropper() {
+    return globalScope[DROPPER_KEY];
+}
+
+//# sourceMappingURL=live-page-drops.js.map

package/src/lib/server/live-page-drops.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/live-page-drops.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * HOW THIS PROCESS DROPS ONE SITE'S CACHED PAGES, for a write that worked out\n * which of them it made stale (AGL-3113, AGL-3080).\n *\n * A record write — a dataset row, a collection entry — refreshes the pages\n * that show it, and nothing else. Working out WHICH pages is the writer's: the\n * data plugin walks the pages that repeat over a dataset, the collection scan\n * the pages that list an entry. HOW a page is dropped is the runtime's, and\n * the two runtimes do it differently: the tenant drops its own caches in\n * process, and the console announces over the shared secret and passes its own\n * dropper at the call site. So the deployment that owns the caches registers\n * the dropper here, and a writer reads it; neither names the other.\n *\n * ## One per process, on `globalThis`\n *\n * The tenant registers from `instrumentation.ts`, by name, at boot. Next\n * compiles that file apart from the routes, so a dropper held in a module\n * `let` was set in the boot's copy of this module and read as missing by\n * every route's copy — a form submission or an automation step that wrote a\n * row logged `no-live-page-dropper` and left the pages stale for the rest of\n * their window (AGL-3412 was the same split for the plugin services). Keyed on\n * `globalThis` under `Symbol.for`, every copy in a realm reads the one slot.\n */\n\n/** One site's share of a change: the pages on it that must be dropped. */\nexport interface LivePageTarget {\n  hostId: string\n  /** The tenant keys its cache on this, never on `hostId`. */\n  subdomain: string\n  /** The attached custom domain, whose pages live under a second cache key. */\n  cname?: string\n  /** Site-absolute addresses (`/`, `/team`) the change makes stale. */\n  paths: string[]\n  /** The site held more documents than the scan read, so `paths` is partial. */\n  truncated: boolean\n}\n\n/**\n * Drops one site's cached pages. Returns whether the drop landed. It must\n * never throw: everything above it has already been written.\n */\nexport type LivePageDropper = (target: LivePageTarget) => Promise<boolean>\n\nconst DROPPER_KEY = Symbol.for('@aglyn/tenant-data-admin:live-page-dropper')\n\nconst globalScope = globalThis as typeof globalThis & {\n  [DROPPER_KEY]?: LivePageDropper\n}\n\n/**\n * Registers the dropper for this process, replacing any previous one. Returns\n * the unregister, which removes it only if it is still the one registered.\n *\n * Called from a function the platform calls BY NAME at boot, never from a\n * module's top level: a bundler deletes a module imported only for its side\n * effect when its package says it has none (AGL-3025).\n */\nexport function registerLivePageDropper(drop: LivePageDropper): () => void {\n  globalScope[DROPPER_KEY] = drop\n  return () => {\n    if (globalScope[DROPPER_KEY] === drop) delete globalScope[DROPPER_KEY]\n  }\n}\n\n/** The dropper this process registered, or `undefined` when none did. */\nexport function registeredLivePageDropper(): LivePageDropper | undefined {\n  return globalScope[DROPPER_KEY]\n}\n"],"names":["DROPPER_KEY","Symbol","for","globalScope","globalThis","registerLivePageDropper","drop","registeredLivePageDropper"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;CAsBC,GAED,wEAAwE,GAmBxE,MAAMA,cAAcC,OAAOC,GAAG,CAAC;AAE/B,MAAMC,cAAcC;AAIpB;;;;;;;CAOC,GACD,OAAO,SAASC,wBAAwBC,IAAqB;IAC3DH,WAAW,CAACH,YAAY,GAAGM;IAC3B,OAAO;QACL,IAAIH,WAAW,CAACH,YAAY,KAAKM,MAAM,OAAOH,WAAW,CAACH,YAAY;IACxE;AACF;AAEA,uEAAuE,GACvE,OAAO,SAASO;IACd,OAAOJ,WAAW,CAACH,YAAY;AACjC"}

package/src/lib/server/media-bandwidth-cap.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The Free cap, engaged by the media CDN (AGL-3474).
+ *
+ * The cap's marker (`orgs/{id}.bandwidthCap`) had two writers, and both are
+ * driven by PAGES: the analytics beacon, on a sample of page views, and the
+ * daily usage sweep. Video and files count against the same band now, but a
+ * film or a PDF linked from somewhere else is served with no page view at
+ * all — so a Free org whose traffic is its media would cross its band and
+ * keep serving until the next morning's sweep. A day of one popular clip is
+ * hundreds of gigabytes.
+ *
+ * So the CDN is a third writer, on the same terms as the other two: the same
+ * `bandwidthCapShouldEngage` predicate, the same marker fields, the same UTC
+ * month key, and a write only when the marker does not already name this
+ * month. A reader cannot tell which writer stamped a marker.
+ *
+ * ## The month it totals
+ *
+ * Org-wide, because the band is: every site's page views and counted media,
+ * plus the org library's media, read from the same analytics day documents
+ * the invoice reads, through the same {@link analyticsBandwidthReading}.
+ *
+ * ## What it costs
+ *
+ * Nothing for a paying org: the CDN asks only for an org whose plan the cap
+ * stops (`bandwidthCapApplies`, decided off the org document its delivery
+ * verdict already holds). For those, one evaluation per
+ * {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} an instance serves — the org
+ * document, its site ids and the month's day documents, a few dozen reads
+ * against about three cents of delivery.
+ *
+ * ## The slop, stated
+ *
+ * Each instance evaluates on its first counted request for an org and then
+ * once per {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES}, so the cap engages at
+ * most that much per instance past the band, and the CDN's own verdict cache
+ * takes up to fifteen seconds to see the marker. The beacon's slop is the
+ * same shape, measured in views.
+ */
+/** How many counted bytes an instance serves an org between evaluations. */
+export declare const MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES: number;
+/** Drop the per-instance state. Tests need it between cases. */
+export declare function invalidateMediaBandwidthCapState(): void;
+/**
+ * Note `bytes` counted for `orgId`, and say whether this instance should now
+ * total the org's month.
+ *
+ * Due on the first counted request an instance sees for the org — a cold
+ * instance under a spike evaluates at once, which is when it matters — and
+ * then each time another {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} has
+ * gone out. Never due again in a month this instance has seen it engaged.
+ */
+export declare function mediaBandwidthEvaluationDue(orgId: string, bytes: number, now?: Date): boolean;
+/**
+ * Total `orgId`'s month and engage the cap if it is past the band. Answers
+ * whether THIS call engaged it.
+ *
+ * Best-effort, like the beacon's writer: it runs beside a delivery that has
+ * already been decided, and a failure here is logged and costs the request
+ * nothing.
+ */
+export declare function engageMediaBandwidthCap(orgId: string, now?: Date): Promise<boolean>;

package/src/lib/server/media-bandwidth-cap.js

@@ -0,0 +1,180 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { analyticsBandwidthReading, bandwidthCapApplies, bandwidthCapMonthKey, bandwidthCapShouldEngage, bandwidthGbFromPageViews, ORIGIN_MEDIA_BANDWIDTH_WEIGHT, pageViewsFromBandwidthGb, resolveOrgEntitlements } from "@aglyn/aglyn/server";
+import { firebaseAdmin } from "./firebase-admin.js";
+import { notifyHostManagers } from "./notifications.js";
+/**
+ * The Free cap, engaged by the media CDN (AGL-3474).
+ *
+ * The cap's marker (`orgs/{id}.bandwidthCap`) had two writers, and both are
+ * driven by PAGES: the analytics beacon, on a sample of page views, and the
+ * daily usage sweep. Video and files count against the same band now, but a
+ * film or a PDF linked from somewhere else is served with no page view at
+ * all — so a Free org whose traffic is its media would cross its band and
+ * keep serving until the next morning's sweep. A day of one popular clip is
+ * hundreds of gigabytes.
+ *
+ * So the CDN is a third writer, on the same terms as the other two: the same
+ * `bandwidthCapShouldEngage` predicate, the same marker fields, the same UTC
+ * month key, and a write only when the marker does not already name this
+ * month. A reader cannot tell which writer stamped a marker.
+ *
+ * ## The month it totals
+ *
+ * Org-wide, because the band is: every site's page views and counted media,
+ * plus the org library's media, read from the same analytics day documents
+ * the invoice reads, through the same {@link analyticsBandwidthReading}.
+ *
+ * ## What it costs
+ *
+ * Nothing for a paying org: the CDN asks only for an org whose plan the cap
+ * stops (`bandwidthCapApplies`, decided off the org document its delivery
+ * verdict already holds). For those, one evaluation per
+ * {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} an instance serves — the org
+ * document, its site ids and the month's day documents, a few dozen reads
+ * against about three cents of delivery.
+ *
+ * ## The slop, stated
+ *
+ * Each instance evaluates on its first counted request for an org and then
+ * once per {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES}, so the cap engages at
+ * most that much per instance past the band, and the CDN's own verdict cache
+ * takes up to fifteen seconds to see the marker. The beacon's slop is the
+ * same shape, measured in views.
+ */ /** How many counted bytes an instance serves an org between evaluations. */ export const MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES = 32 * 1024 * 1024;
+/** Sites totalled per org. The cap is for Free, which has one. */ const MEDIA_BANDWIDTH_MAX_HOSTS = 100;
+/** Bound on the per-instance maps, whose keys come from served requests. */ const MAX_TRACKED_ORGS = 5000;
+/** Counted bytes since an org's last evaluation, on this instance. */ const bytesSinceEvaluation = new Map();
+/** Orgs this instance has seen engaged, by the month they were engaged for. */ const engagedOrgs = new Map();
+/** Drop the per-instance state. Tests need it between cases. */ export function invalidateMediaBandwidthCapState() {
+    bytesSinceEvaluation.clear();
+    engagedOrgs.clear();
+}
+/**
+ * Note `bytes` counted for `orgId`, and say whether this instance should now
+ * total the org's month.
+ *
+ * Due on the first counted request an instance sees for the org — a cold
+ * instance under a spike evaluates at once, which is when it matters — and
+ * then each time another {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} has
+ * gone out. Never due again in a month this instance has seen it engaged.
+ */ export function mediaBandwidthEvaluationDue(orgId, bytes, now = new Date()) {
+    if (!orgId || !(bytes > 0)) return false;
+    if (engagedOrgs.get(orgId) === bandwidthCapMonthKey(now)) return false;
+    if (bytesSinceEvaluation.size > MAX_TRACKED_ORGS) bytesSinceEvaluation.clear();
+    const since = bytesSinceEvaluation.get(orgId);
+    if (since === undefined || since + bytes >= MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES) {
+        bytesSinceEvaluation.set(orgId, 0);
+        return true;
+    }
+    bytesSinceEvaluation.set(orgId, since + bytes);
+    return false;
+}
+/** `YYYY-MM` as the day it rolls over, the way a notice prints it. */ function monthRolloverLabel(month) {
+    const [year, monthIndex] = month.split('-').map(Number);
+    return new Date(Date.UTC(year, monthIndex, 1)).toLocaleDateString('en-US', {
+        month: 'long',
+        day: 'numeric',
+        timeZone: 'UTC'
+    });
+}
+/**
+ * Total `orgId`'s month and engage the cap if it is past the band. Answers
+ * whether THIS call engaged it.
+ *
+ * Best-effort, like the beacon's writer: it runs beside a delivery that has
+ * already been decided, and a failure here is logged and costs the request
+ * nothing.
+ */ export async function engageMediaBandwidthCap(orgId, now = new Date()) {
+    const month = bandwidthCapMonthKey(now);
+    if (!orgId || engagedOrgs.get(orgId) === month) return false;
+    try {
+        var _orgSnapshot_data;
+        var _org_bandwidthCap;
+        const firestore = firebaseAdmin.app().firestore();
+        const orgRef = firestore.collection('orgs').doc(orgId);
+        const orgSnapshot = await orgRef.get();
+        if (!orgSnapshot.exists) return false;
+        const org = (_orgSnapshot_data = orgSnapshot.data()) != null ? _orgSnapshot_data : {};
+        if (!bandwidthCapApplies(org)) return false;
+        if (((_org_bandwidthCap = org.bandwidthCap) == null ? void 0 : _org_bandwidthCap.month) === month) {
+            rememberEngaged(orgId, month);
+            return false;
+        }
+        const documentId = firebaseAdmin.firestore.FieldPath.documentId();
+        // The query `report-usage` and the beacon run, per scope: a cap that
+        // counted a different month from the invoice would refuse traffic nobody
+        // was charged for.
+        const monthOf = (ref)=>ref.collection('analytics').where(documentId, '>=', `${month}-01`).where(documentId, '<=', `${month}-31`).get();
+        const hosts = await firestore.collection('hosts').where('orgId', '==', orgId).select().limit(MEDIA_BANDWIDTH_MAX_HOSTS).get();
+        const months = await Promise.all([
+            monthOf(orgRef),
+            ...hosts.docs.map((host)=>monthOf(host.ref))
+        ]);
+        const reading = analyticsBandwidthReading(months.flatMap((days)=>days.docs));
+        const includedBandwidthGb = resolveOrgEntitlements(org).bandwidthGb;
+        if (!bandwidthCapShouldEngage({
+            org,
+            usedBandwidthGb: bandwidthGbFromPageViews(reading.meteredPageViews),
+            includedBandwidthGb
+        })) {
+            return false;
+        }
+        // Stamped inside a transaction that re-reads the marker, so two instances
+        // crossing the band together stamp it, and tell the owner, once.
+        const stamped = await firestore.runTransaction(async (transaction)=>{
+            var _current_get;
+            const current = await transaction.get(orgRef);
+            if (((_current_get = current.get('bandwidthCap')) == null ? void 0 : _current_get.month) === month) return false;
+            // `merge: true`: one field on a document that carries the plan, the
+            // subscription and the sites. A set without it would delete the org.
+            transaction.set(orgRef, {
+                bandwidthCap: {
+                    month,
+                    engagedAt: now.getTime(),
+                    pageViews: Math.round(reading.meteredPageViews),
+                    includedPageViews: Math.round(pageViewsFromBandwidthGb(includedBandwidthGb))
+                }
+            }, {
+                merge: true
+            });
+            return true;
+        });
+        rememberEngaged(orgId, month);
+        if (!stamped) return false;
+        const included = includedBandwidthGb.toLocaleString('en-US', {
+            maximumFractionDigits: 2
+        });
+        // Every site's managers, because the cap pauses every site in the org.
+        // `{site}` is filled by `notifyHostManagers` from the host it reads.
+        await Promise.all(hosts.docs.map((host)=>notifyHostManagers(host.id, {
+                type: 'system.bandwidthCapEngaged',
+                title: '{site} paused — monthly traffic limit reached',
+                body: `{site} has used the ${included} GB of traffic its plan includes ` + 'this month. Video, audio and files served from your media library ' + `count ${ORIGIN_MEDIA_BANDWIDTH_WEIGHT}× toward it, as well as page ` + 'views, so visitors see a temporary notice instead of its pages, ' + 'and its video and files do not load, ' + `until ${monthRolloverLabel(month)}. Nothing is charged for the ` + 'extra traffic. The site comes back on its own then, or as soon as ' + 'you upgrade in Billing.',
+                link: `/${host.id}`
+            })));
+        return true;
+    } catch (error) {
+        console.error('[media-cdn] bandwidth cap evaluation failed', orgId, error);
+        return false;
+    }
+}
+function rememberEngaged(orgId, month) {
+    if (engagedOrgs.size > MAX_TRACKED_ORGS) engagedOrgs.clear();
+    engagedOrgs.set(orgId, month);
+}
+
+//# sourceMappingURL=media-bandwidth-cap.js.map

package/src/lib/server/media-bandwidth-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/media-bandwidth-cap.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  type AglynOrgBilling,\n  analyticsBandwidthReading,\n  bandwidthCapApplies,\n  bandwidthCapMonthKey,\n  bandwidthCapShouldEngage,\n  bandwidthGbFromPageViews,\n  ORIGIN_MEDIA_BANDWIDTH_WEIGHT,\n  pageViewsFromBandwidthGb,\n  resolveOrgEntitlements,\n} from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from './firebase-admin'\nimport { notifyHostManagers } from './notifications'\n\n/**\n * The Free cap, engaged by the media CDN (AGL-3474).\n *\n * The cap's marker (`orgs/{id}.bandwidthCap`) had two writers, and both are\n * driven by PAGES: the analytics beacon, on a sample of page views, and the\n * daily usage sweep. Video and files count against the same band now, but a\n * film or a PDF linked from somewhere else is served with no page view at\n * all — so a Free org whose traffic is its media would cross its band and\n * keep serving until the next morning's sweep. A day of one popular clip is\n * hundreds of gigabytes.\n *\n * So the CDN is a third writer, on the same terms as the other two: the same\n * `bandwidthCapShouldEngage` predicate, the same marker fields, the same UTC\n * month key, and a write only when the marker does not already name this\n * month. A reader cannot tell which writer stamped a marker.\n *\n * ## The month it totals\n *\n * Org-wide, because the band is: every site's page views and counted media,\n * plus the org library's media, read from the same analytics day documents\n * the invoice reads, through the same {@link analyticsBandwidthReading}.\n *\n * ## What it costs\n *\n * Nothing for a paying org: the CDN asks only for an org whose plan the cap\n * stops (`bandwidthCapApplies`, decided off the org document its delivery\n * verdict already holds). For those, one evaluation per\n * {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} an instance serves — the org\n * document, its site ids and the month's day documents, a few dozen reads\n * against about three cents of delivery.\n *\n * ## The slop, stated\n *\n * Each instance evaluates on its first counted request for an org and then\n * once per {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES}, so the cap engages at\n * most that much per instance past the band, and the CDN's own verdict cache\n * takes up to fifteen seconds to see the marker. The beacon's slop is the\n * same shape, measured in views.\n */\n\n/** How many counted bytes an instance serves an org between evaluations. */\nexport const MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES = 32 * 1024 * 1024\n\n/** Sites totalled per org. The cap is for Free, which has one. */\nconst MEDIA_BANDWIDTH_MAX_HOSTS = 100\n\n/** Bound on the per-instance maps, whose keys come from served requests. */\nconst MAX_TRACKED_ORGS = 5_000\n\n/** Counted bytes since an org's last evaluation, on this instance. */\nconst bytesSinceEvaluation = new Map<string, number>()\n\n/** Orgs this instance has seen engaged, by the month they were engaged for. */\nconst engagedOrgs = new Map<string, string>()\n\n/** Drop the per-instance state. Tests need it between cases. */\nexport function invalidateMediaBandwidthCapState(): void {\n  bytesSinceEvaluation.clear()\n  engagedOrgs.clear()\n}\n\n/**\n * Note `bytes` counted for `orgId`, and say whether this instance should now\n * total the org's month.\n *\n * Due on the first counted request an instance sees for the org — a cold\n * instance under a spike evaluates at once, which is when it matters — and\n * then each time another {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} has\n * gone out. Never due again in a month this instance has seen it engaged.\n */\nexport function mediaBandwidthEvaluationDue(\n  orgId: string,\n  bytes: number,\n  now: Date = new Date(),\n): boolean {\n  if (!orgId || !(bytes > 0)) return false\n  if (engagedOrgs.get(orgId) === bandwidthCapMonthKey(now)) return false\n  if (bytesSinceEvaluation.size > MAX_TRACKED_ORGS) bytesSinceEvaluation.clear()\n  const since = bytesSinceEvaluation.get(orgId)\n  if (since === undefined || since + bytes >= MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES) {\n    bytesSinceEvaluation.set(orgId, 0)\n    return true\n  }\n  bytesSinceEvaluation.set(orgId, since + bytes)\n  return false\n}\n\n/** `YYYY-MM` as the day it rolls over, the way a notice prints it. */\nfunction monthRolloverLabel(month: string): string {\n  const [year, monthIndex] = month.split('-').map(Number)\n  return new Date(Date.UTC(year, monthIndex, 1)).toLocaleDateString('en-US', {\n    month: 'long',\n    day: 'numeric',\n    timeZone: 'UTC',\n  })\n}\n\n/**\n * Total `orgId`'s month and engage the cap if it is past the band. Answers\n * whether THIS call engaged it.\n *\n * Best-effort, like the beacon's writer: it runs beside a delivery that has\n * already been decided, and a failure here is logged and costs the request\n * nothing.\n */\nexport async function engageMediaBandwidthCap(\n  orgId: string,\n  now: Date = new Date(),\n): Promise<boolean> {\n  const month = bandwidthCapMonthKey(now)\n  if (!orgId || engagedOrgs.get(orgId) === month) return false\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    const orgRef = firestore.collection('orgs').doc(orgId)\n    const orgSnapshot = await orgRef.get()\n    if (!orgSnapshot.exists) return false\n    const org = (orgSnapshot.data() ?? {}) as Partial<AglynOrgBilling>\n    if (!bandwidthCapApplies(org)) return false\n    if (org.bandwidthCap?.month === month) {\n      rememberEngaged(orgId, month)\n      return false\n    }\n    const documentId = firebaseAdmin.firestore.FieldPath.documentId()\n    // The query `report-usage` and the beacon run, per scope: a cap that\n    // counted a different month from the invoice would refuse traffic nobody\n    // was charged for.\n    const monthOf = (ref: FirebaseFirestore.DocumentReference) =>\n      ref\n        .collection('analytics')\n        .where(documentId, '>=', `${month}-01`)\n        .where(documentId, '<=', `${month}-31`)\n        .get()\n    const hosts = await firestore\n      .collection('hosts')\n      .where('orgId', '==', orgId)\n      .select()\n      .limit(MEDIA_BANDWIDTH_MAX_HOSTS)\n      .get()\n    const months = await Promise.all([\n      monthOf(orgRef),\n      ...hosts.docs.map((host) => monthOf(host.ref)),\n    ])\n    const reading = analyticsBandwidthReading(months.flatMap((days) => days.docs))\n    const includedBandwidthGb = resolveOrgEntitlements(org).bandwidthGb\n    if (\n      !bandwidthCapShouldEngage({\n        org,\n        usedBandwidthGb: bandwidthGbFromPageViews(reading.meteredPageViews),\n        includedBandwidthGb,\n      })\n    ) {\n      return false\n    }\n    // Stamped inside a transaction that re-reads the marker, so two instances\n    // crossing the band together stamp it, and tell the owner, once.\n    const stamped = await firestore.runTransaction(async (transaction) => {\n      const current = await transaction.get(orgRef)\n      if (current.get('bandwidthCap')?.month === month) return false\n      // `merge: true`: one field on a document that carries the plan, the\n      // subscription and the sites. A set without it would delete the org.\n      transaction.set(\n        orgRef,\n        {\n          bandwidthCap: {\n            month,\n            engagedAt: now.getTime(),\n            pageViews: Math.round(reading.meteredPageViews),\n            includedPageViews: Math.round(\n              pageViewsFromBandwidthGb(includedBandwidthGb),\n            ),\n          },\n        },\n        { merge: true },\n      )\n      return true\n    })\n    rememberEngaged(orgId, month)\n    if (!stamped) return false\n    const included = includedBandwidthGb.toLocaleString('en-US', {\n      maximumFractionDigits: 2,\n    })\n    // Every site's managers, because the cap pauses every site in the org.\n    // `{site}` is filled by `notifyHostManagers` from the host it reads.\n    await Promise.all(\n      hosts.docs.map((host) =>\n        notifyHostManagers(host.id, {\n          type: 'system.bandwidthCapEngaged',\n          title: '{site} paused — monthly traffic limit reached',\n          body:\n            `{site} has used the ${included} GB of traffic its plan includes ` +\n            'this month. Video, audio and files served from your media library ' +\n            `count ${ORIGIN_MEDIA_BANDWIDTH_WEIGHT}× toward it, as well as page ` +\n            'views, so visitors see a temporary notice instead of its pages, ' +\n            'and its video and files do not load, ' +\n            `until ${monthRolloverLabel(month)}. Nothing is charged for the ` +\n            'extra traffic. The site comes back on its own then, or as soon as ' +\n            'you upgrade in Billing.',\n          link: `/${host.id}`,\n        }),\n      ),\n    )\n    return true\n  } catch (error) {\n    console.error('[media-cdn] bandwidth cap evaluation failed', orgId, error)\n    return false\n  }\n}\n\nfunction rememberEngaged(orgId: string, month: string): void {\n  if (engagedOrgs.size > MAX_TRACKED_ORGS) engagedOrgs.clear()\n  engagedOrgs.set(orgId, month)\n}\n"],"names":["analyticsBandwidthReading","bandwidthCapApplies","bandwidthCapMonthKey","bandwidthCapShouldEngage","bandwidthGbFromPageViews","ORIGIN_MEDIA_BANDWIDTH_WEIGHT","pageViewsFromBandwidthGb","resolveOrgEntitlements","firebaseAdmin","notifyHostManagers","MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES","MEDIA_BANDWIDTH_MAX_HOSTS","MAX_TRACKED_ORGS","bytesSinceEvaluation","Map","engagedOrgs","invalidateMediaBandwidthCapState","clear","mediaBandwidthEvaluationDue","orgId","bytes","now","Date","get","size","since","undefined","set","monthRolloverLabel","month","year","monthIndex","split","map","Number","UTC","toLocaleDateString","day","timeZone","engageMediaBandwidthCap","orgSnapshot","org","firestore","app","orgRef","collection","doc","exists","data","bandwidthCap","rememberEngaged","documentId","FieldPath","monthOf","ref","where","hosts","select","limit","months","Promise","all","docs","host","reading","flatMap","days","includedBandwidthGb","bandwidthGb","usedBandwidthGb","meteredPageViews","stamped","runTransaction","transaction","current","engagedAt","getTime","pageViews","Math","round","includedPageViews","merge","included","toLocaleString","maximumFractionDigits","id","type","title","body","link","error","console"],"mappings":"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"}

package/src/lib/server/media-cdn-icon.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type SiteIconSpec } from '@aglyn/aglyn/app-utils/site-icon-set';
+import type { NextApiRequest, NextApiResponse } from 'next';
+import type { MediaCdnRateLimitRefusal } from './media-cdn-rate-limit';
+/**
+ * The `?icon=` representation of a media CDN URL (AGL-3484): one icon of a
+ * site's derived set, drawn from the asset's current bytes.
+ *
+ * `serveMediaCdn` calls this only after every gate it applies to the bytes —
+ * scope, lockdown, quarantine, the private signature and the stale-pin
+ * redirect — so an icon is served exactly where its source would be.
+ *
+ * ## Derived once, cached by version
+ *
+ * The URL a page names carries `v`, the asset's `contentHash`. While `v` is
+ * current the icon is drawn once and held for a year by the edge and the
+ * browser (`immutable`): the same URL can never need different bytes, because
+ * a DAM Replace changes the hash and so the URL the next render names. A
+ * stale `v` 302s to the current one under the stable URL's revalidated policy,
+ * which is how a page rendered before a Replace reaches the new icon. A URL
+ * with no `v` (the source's hash is unknown) is served under the stable
+ * policy with an ETag keyed on the hash, exactly as the asset itself is.
+ *
+ * ## Anything the renderer cannot draw falls back to the original
+ *
+ * A non-image, an ICO (which `sharp` cannot decode), a source over the
+ * variant generator's fetch ceiling, or a file that fails to decode: each
+ * 302s to the asset's plain URL. A favicon link must never be the reason a
+ * tab shows nothing.
+ */
+/** The fields of a stored asset this representation reads. */
+export interface MediaCdnIconSource {
+    /** The media document's `contentType`. */
+    contentType: unknown;
+    /** The media document's `contentHash`; `''` for a legacy asset. */
+    contentHash: string;
+    /** `/api/media/cdn/{scope}/{mediaId}` — the asset's stable URL. */
+    stablePath: string;
+    /** The Storage object, as far as this reads it. */
+    file: {
+        getMetadata(): Promise<[{
+            size?: string | number;
+        } | null | undefined]>;
+        download(): Promise<[Buffer]>;
+    };
+}
+/** The `ETag` of one derived icon: the source's hash plus the representation. */
+export declare function mediaCdnIconEtag(contentHash: string, spec: SiteIconSpec, background: string | undefined): string | null;
+export declare function serveMediaCdnIcon(options: {
+    req: NextApiRequest;
+    res: NextApiResponse;
+    spec: SiteIconSpec;
+    source: MediaCdnIconSource;
+    /** Forces `private, no-store` on a signed asset, as the handler's does. */
+    setCacheControl: (value: string) => void;
+    cacheControl: {
+        stable: string;
+        immutable: string;
+    };
+    /** The caller's delivery count; `null` means serve. */
+    rateLimit: () => Promise<MediaCdnRateLimitRefusal | null>;
+}): Promise<void>;

package/src/lib/server/media-cdn-icon.js

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { formatSiteIconSpec, normalizeSiteIconBackground, SITE_ICON_BACKGROUND_PARAM, SITE_ICON_PARAM, SITE_ICON_VERSION_PARAM, siteIconSourceTypeDerivable, siteIconUsesBackground, DEFAULT_SITE_ICON_BACKGROUND } from "@aglyn/aglyn/app-utils/site-icon-set";
+import { MEDIA_VARIANT_SOURCE_MAX_BYTES } from "./media-variants.js";
+import { renderSiteIcon } from "./site-icon-render.js";
+const firstValue = (value)=>{
+    const raw = Array.isArray(value) ? value[0] : value;
+    return typeof raw === 'string' && raw !== '' ? raw : undefined;
+};
+/**
+ * The query this representation names, rebuilt from the parameters it reads —
+ * never forwarded whole, for `mediaCdnForwardedQuery`'s reasons. `exp`/`sig`
+ * ride along so a signed asset's redirect still serves.
+ */ function iconQuery(query, pairs) {
+    const params = new URLSearchParams();
+    for (const [key, value] of pairs)if (value) params.set(key, value);
+    for (const key of [
+        'exp',
+        'sig'
+    ]){
+        const value = firstValue(query[key]);
+        if (value) params.set(key, value);
+    }
+    const encoded = params.toString();
+    return encoded ? `?${encoded}` : '';
+}
+/** The `ETag` of one derived icon: the source's hash plus the representation. */ export function mediaCdnIconEtag(contentHash, spec, background) {
+    if (!contentHash) return null;
+    const plate = background ? `-${background}` : '';
+    return `"${contentHash}-icon-${formatSiteIconSpec(spec)}${plate}"`;
+}
+export async function serveMediaCdnIcon(options) {
+    var _normalizeSiteIconBackground, _firstValue, _metadata_size;
+    const { req, res, spec, source, setCacheControl, cacheControl } = options;
+    const background = siteIconUsesBackground(spec) ? (_normalizeSiteIconBackground = normalizeSiteIconBackground(`#${(_firstValue = firstValue(req.query[SITE_ICON_BACKGROUND_PARAM])) != null ? _firstValue : ''}`)) != null ? _normalizeSiteIconBackground : DEFAULT_SITE_ICON_BACKGROUND : undefined;
+    const version = firstValue(req.query[SITE_ICON_VERSION_PARAM]);
+    const { contentHash } = source;
+    const original = (cache)=>{
+        res.removeHeader('ETag');
+        setCacheControl(cache);
+        res.setHeader('Location', `${source.stablePath}${iconQuery(req.query, [])}`);
+        res.status(302).end();
+    };
+    if (!siteIconSourceTypeDerivable(source.contentType)) {
+        original(cacheControl.stable);
+        return;
+    }
+    if (version && contentHash && version !== contentHash) {
+        setCacheControl(cacheControl.stable);
+        res.setHeader('Location', `${source.stablePath}${iconQuery(req.query, [
+            [
+                SITE_ICON_PARAM,
+                formatSiteIconSpec(spec)
+            ],
+            [
+                SITE_ICON_BACKGROUND_PARAM,
+                background
+            ],
+            [
+                SITE_ICON_VERSION_PARAM,
+                contentHash
+            ]
+        ])}`);
+        res.status(302).end();
+        return;
+    }
+    const etag = mediaCdnIconEtag(contentHash, spec, background);
+    setCacheControl(version && version === contentHash ? cacheControl.immutable : cacheControl.stable);
+    if (etag) {
+        res.setHeader('ETag', etag);
+        if (req.headers['if-none-match'] === etag) {
+            res.status(304).end();
+            return;
+        }
+    }
+    const counted = req.method === 'GET' ? options.rateLimit() : null;
+    const [metadata] = await source.file.getMetadata().catch(()=>[
+            null
+        ]);
+    if (!metadata) {
+        res.removeHeader('ETag');
+        setCacheControl('public, max-age=60');
+        res.status(404).json({
+            error: 'Not found'
+        });
+        return;
+    }
+    if (Number((_metadata_size = metadata.size) != null ? _metadata_size : 0) > MEDIA_VARIANT_SOURCE_MAX_BYTES) {
+        original(cacheControl.stable);
+        return;
+    }
+    const refused = await counted;
+    if (refused) {
+        res.removeHeader('ETag');
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('Retry-After', String(refused.retryAfterSeconds));
+        res.status(429).json({
+            error: 'Too many requests'
+        });
+        return;
+    }
+    let icon;
+    try {
+        const [bytes] = await source.file.download();
+        icon = await renderSiteIcon({
+            source: bytes,
+            spec,
+            background
+        });
+    } catch (error) {
+        // A file that will not decode is a property of the upload, not of the
+        // request, but it is not cached either: a Replace must be able to fix it.
+        console.error('[media-cdn] site icon render failed', source.stablePath, error);
+        original('no-store');
+        return;
+    }
+    res.setHeader('Content-Type', icon.contentType);
+    res.setHeader('Content-Length', String(icon.body.length));
+    res.setHeader('Content-Disposition', `inline; filename="icon-${formatSiteIconSpec(spec)}.${spec.plate === 'ico' ? 'ico' : 'png'}"`);
+    if (req.method === 'HEAD') {
+        res.status(200).end();
+        return;
+    }
+    res.status(200).end(icon.body);
+}
+
+//# sourceMappingURL=media-cdn-icon.js.map

package/src/lib/server/media-cdn-icon.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/media-cdn-icon.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  formatSiteIconSpec,\n  normalizeSiteIconBackground,\n  SITE_ICON_BACKGROUND_PARAM,\n  SITE_ICON_PARAM,\n  SITE_ICON_VERSION_PARAM,\n  siteIconSourceTypeDerivable,\n  siteIconUsesBackground,\n  DEFAULT_SITE_ICON_BACKGROUND,\n  type SiteIconSpec,\n} from '@aglyn/aglyn/app-utils/site-icon-set'\nimport type { NextApiRequest, NextApiResponse } from 'next'\n\nimport type { MediaCdnRateLimitRefusal } from './media-cdn-rate-limit'\nimport { MEDIA_VARIANT_SOURCE_MAX_BYTES } from './media-variants'\nimport { renderSiteIcon } from './site-icon-render'\n\n/**\n * The `?icon=` representation of a media CDN URL (AGL-3484): one icon of a\n * site's derived set, drawn from the asset's current bytes.\n *\n * `serveMediaCdn` calls this only after every gate it applies to the bytes —\n * scope, lockdown, quarantine, the private signature and the stale-pin\n * redirect — so an icon is served exactly where its source would be.\n *\n * ## Derived once, cached by version\n *\n * The URL a page names carries `v`, the asset's `contentHash`. While `v` is\n * current the icon is drawn once and held for a year by the edge and the\n * browser (`immutable`): the same URL can never need different bytes, because\n * a DAM Replace changes the hash and so the URL the next render names. A\n * stale `v` 302s to the current one under the stable URL's revalidated policy,\n * which is how a page rendered before a Replace reaches the new icon. A URL\n * with no `v` (the source's hash is unknown) is served under the stable\n * policy with an ETag keyed on the hash, exactly as the asset itself is.\n *\n * ## Anything the renderer cannot draw falls back to the original\n *\n * A non-image, an ICO (which `sharp` cannot decode), a source over the\n * variant generator's fetch ceiling, or a file that fails to decode: each\n * 302s to the asset's plain URL. A favicon link must never be the reason a\n * tab shows nothing.\n */\n\n/** The fields of a stored asset this representation reads. */\nexport interface MediaCdnIconSource {\n  /** The media document's `contentType`. */\n  contentType: unknown\n  /** The media document's `contentHash`; `''` for a legacy asset. */\n  contentHash: string\n  /** `/api/media/cdn/{scope}/{mediaId}` — the asset's stable URL. */\n  stablePath: string\n  /** The Storage object, as far as this reads it. */\n  file: {\n    getMetadata(): Promise<[{ size?: string | number } | null | undefined]>\n    download(): Promise<[Buffer]>\n  }\n}\n\nconst firstValue = (value: unknown): string | undefined => {\n  const raw = Array.isArray(value) ? value[0] : value\n  return typeof raw === 'string' && raw !== '' ? raw : undefined\n}\n\n/**\n * The query this representation names, rebuilt from the parameters it reads —\n * never forwarded whole, for `mediaCdnForwardedQuery`'s reasons. `exp`/`sig`\n * ride along so a signed asset's redirect still serves.\n */\nfunction iconQuery(\n  query: NextApiRequest['query'],\n  pairs: Array<[string, string | undefined]>,\n): string {\n  const params = new URLSearchParams()\n  for (const [key, value] of pairs) if (value) params.set(key, value)\n  for (const key of ['exp', 'sig']) {\n    const value = firstValue(query[key])\n    if (value) params.set(key, value)\n  }\n  const encoded = params.toString()\n  return encoded ? `?${encoded}` : ''\n}\n\n/** The `ETag` of one derived icon: the source's hash plus the representation. */\nexport function mediaCdnIconEtag(\n  contentHash: string,\n  spec: SiteIconSpec,\n  background: string | undefined,\n): string | null {\n  if (!contentHash) return null\n  const plate = background ? `-${background}` : ''\n  return `\"${contentHash}-icon-${formatSiteIconSpec(spec)}${plate}\"`\n}\n\nexport async function serveMediaCdnIcon(options: {\n  req: NextApiRequest\n  res: NextApiResponse\n  spec: SiteIconSpec\n  source: MediaCdnIconSource\n  /** Forces `private, no-store` on a signed asset, as the handler's does. */\n  setCacheControl: (value: string) => void\n  cacheControl: { stable: string; immutable: string }\n  /** The caller's delivery count; `null` means serve. */\n  rateLimit: () => Promise<MediaCdnRateLimitRefusal | null>\n}): Promise<void> {\n  const { req, res, spec, source, setCacheControl, cacheControl } = options\n  const background = siteIconUsesBackground(spec)\n    ? (normalizeSiteIconBackground(\n        `#${firstValue(req.query[SITE_ICON_BACKGROUND_PARAM]) ?? ''}`,\n      ) ?? DEFAULT_SITE_ICON_BACKGROUND)\n    : undefined\n  const version = firstValue(req.query[SITE_ICON_VERSION_PARAM])\n  const { contentHash } = source\n\n  const original = (cache: string) => {\n    res.removeHeader('ETag')\n    setCacheControl(cache)\n    res.setHeader('Location', `${source.stablePath}${iconQuery(req.query, [])}`)\n    res.status(302).end()\n  }\n\n  if (!siteIconSourceTypeDerivable(source.contentType)) {\n    original(cacheControl.stable)\n    return\n  }\n  if (version && contentHash && version !== contentHash) {\n    setCacheControl(cacheControl.stable)\n    res.setHeader(\n      'Location',\n      `${source.stablePath}${iconQuery(req.query, [\n        [SITE_ICON_PARAM, formatSiteIconSpec(spec)],\n        [SITE_ICON_BACKGROUND_PARAM, background],\n        [SITE_ICON_VERSION_PARAM, contentHash],\n      ])}`,\n    )\n    res.status(302).end()\n    return\n  }\n\n  const etag = mediaCdnIconEtag(contentHash, spec, background)\n  setCacheControl(\n    version && version === contentHash\n      ? cacheControl.immutable\n      : cacheControl.stable,\n  )\n  if (etag) {\n    res.setHeader('ETag', etag)\n    if (req.headers['if-none-match'] === etag) {\n      res.status(304).end()\n      return\n    }\n  }\n\n  const counted = req.method === 'GET' ? options.rateLimit() : null\n  const [metadata] = await source.file.getMetadata().catch(() => [null])\n  if (!metadata) {\n    res.removeHeader('ETag')\n    setCacheControl('public, max-age=60')\n    res.status(404).json({ error: 'Not found' })\n    return\n  }\n  if (Number(metadata.size ?? 0) > MEDIA_VARIANT_SOURCE_MAX_BYTES) {\n    original(cacheControl.stable)\n    return\n  }\n  const refused = await counted\n  if (refused) {\n    res.removeHeader('ETag')\n    res.setHeader('Cache-Control', 'no-store')\n    res.setHeader('Retry-After', String(refused.retryAfterSeconds))\n    res.status(429).json({ error: 'Too many requests' })\n    return\n  }\n\n  let icon: { body: Buffer; contentType: string }\n  try {\n    const [bytes] = await source.file.download()\n    icon = await renderSiteIcon({ source: bytes, spec, background })\n  } catch (error) {\n    // A file that will not decode is a property of the upload, not of the\n    // request, but it is not cached either: a Replace must be able to fix it.\n    console.error('[media-cdn] site icon render failed', source.stablePath, error)\n    original('no-store')\n    return\n  }\n\n  res.setHeader('Content-Type', icon.contentType)\n  res.setHeader('Content-Length', String(icon.body.length))\n  res.setHeader(\n    'Content-Disposition',\n    `inline; filename=\"icon-${formatSiteIconSpec(spec)}.${\n      spec.plate === 'ico' ? 'ico' : 'png'\n    }\"`,\n  )\n  if (req.method === 'HEAD') {\n    res.status(200).end()\n    return\n  }\n  res.status(200).end(icon.body)\n}\n"],"names":["formatSiteIconSpec","normalizeSiteIconBackground","SITE_ICON_BACKGROUND_PARAM","SITE_ICON_PARAM","SITE_ICON_VERSION_PARAM","siteIconSourceTypeDerivable","siteIconUsesBackground","DEFAULT_SITE_ICON_BACKGROUND","MEDIA_VARIANT_SOURCE_MAX_BYTES","renderSiteIcon","firstValue","value","raw","Array","isArray","undefined","iconQuery","query","pairs","params","URLSearchParams","key","set","encoded","toString","mediaCdnIconEtag","contentHash","spec","background","plate","serveMediaCdnIcon","options","metadata","req","res","source","setCacheControl","cacheControl","version","original","cache","removeHeader","setHeader","stablePath","status","end","contentType","stable","etag","immutable","headers","counted","method","rateLimit","file","getMetadata","catch","json","error","Number","size","refused","String","retryAfterSeconds","icon","bytes","download","console","body","length"],"mappings":"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"}