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

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

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type LockdownState, type MediaVideoRendition } from '@aglyn/aglyn/server';
+import { type LockdownState, type MediaCdnVersion, type MediaVideoRendition } from '@aglyn/aglyn/server';
 import { type MediaCdnScope } from '@aglyn/aglyn/app-utils/media-cdn-scope';
 import type { NextApiRequest, NextApiResponse } from 'next';
 /**
@@ -115,6 +115,64 @@ export declare const MEDIA_CDN_STABLE_CACHE_CONTROL = "public, max-age=60, s-max
  * asset precisely because small ones are the ones that get cached.
  */
 export declare const MEDIA_CDN_STABLE_EDGE_BYPASS_CACHE_CONTROL = "private, max-age=60";
+/**
+ * The VERSIONED stable URL's policy (AGL-3485): `?v={contentHash}.{encoder}`
+ * on the stable path, answered while the token names the asset's current
+ * bytes and current variants.
+ *
+ * The browser keeps it for a year, `immutable`, which is the whole point: the
+ * 60-second window above made every repeat view of every published image a
+ * conditional request, and Lighthouse reports that policy against each one.
+ * It is safe for the reason the content-hashed form never was in a page
+ * (AGL-2798): the page names this URL only while the token is current, the
+ * composition reads the token off the media document on every render, and a
+ * replace or a regeneration therefore moves the page to a new URL instead of
+ * leaving it on a pinned copy of the old bytes.
+ *
+ * The EDGE keeps the stable URL's hour and its revalidation, deliberately not
+ * a year: the edge is the copy a takedown or a lockdown has to outrun for
+ * every new visitor (`media-takedown-reach.ts`), and an hour is the bound the
+ * product states for it. Other visitors still get the edge's copy within that
+ * hour, which is what `s-maxage` is for. Images only — every other type keeps
+ * the stable policy, for the AGL-1515 reasons above.
+ */
+export declare const MEDIA_CDN_VERSIONED_CACHE_CONTROL = "public, max-age=31536000, s-maxage=3600, stale-while-revalidate=86400, immutable";
+/**
+ * Whether a versioned request may be answered with
+ * {@link MEDIA_CDN_VERSIONED_CACHE_CONTROL} (AGL-3485).
+ *
+ * Only when everything the token promises is true of what is being served:
+ *
+ * - the token's content hash is the document's CURRENT one. A stale token is
+ *   served the current bytes under the stable URL's short policy — a stale
+ *   page shows the new picture, and nothing pins it;
+ * - the representation is the original or a `?w=` variant. A poster or a
+ *   rendition keeps its own policy;
+ * - for a `?w=` request, the variant itself is what is served. A width the
+ *   asset has no variant for falls back to another representation, and a
+ *   fallback is not something to keep for a year: the variant may be
+ *   generated later;
+ * - and the asset's delivery copies were made by the encoder generation the
+ *   token names, which is the one this code runs. The media document records
+ *   which generation made them (`MEDIA_VARIANT_ENCODER_VERSION_FIELD`, absent
+ *   meaning the first). A page rendered after the encoder moved on names the
+ *   new generation before the asset has been regenerated; answering that
+ *   request with the old encode for a year would hide the regeneration behind
+ *   the very URL that was minted to reach it. Asked of every request, not
+ *   only `?w=`, because the encoder makes what the bare URL serves too.
+ */
+export declare function mediaCdnVersionIsCurrent(options: {
+    token: MediaCdnVersion | null;
+    currentHash: string;
+    /** A `?w=` was asked for. */
+    widthRequested: boolean;
+    /** The `?w=` variant itself is what will be served. */
+    variantServed: boolean;
+    /** A poster or a rendition was selected instead of the image. */
+    otherRepresentation: boolean;
+    /** The document's {@link MEDIA_VARIANT_ENCODER_VERSION_FIELD}. */
+    documentEncoderVersion: unknown;
+}): boolean;
 /** The immutable content-hashed URL's policy for edge-cacheable (image) types. */
 export declare const MEDIA_CDN_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
 /**
@@ -287,6 +345,16 @@ export declare function mediaCdnServeBlock(scope: MediaCdnScope, asset: {
  * separate edge entry for identical bytes; two is enough.
  */
 export declare function wantsMediaDownload(value: unknown): boolean;
+/**
+ * The display copy a media document records (AGL-3486), or null when it has
+ * none. Only the type is needed to serve it — the object path is derived — and
+ * a record whose type is not an image is treated as no record: the display
+ * copy is always an image, and serving its object under another type would be
+ * a document field choosing a response's `Content-Type`.
+ */
+export declare function mediaCdnDisplayCopy(value: unknown): {
+    contentType: string;
+} | null;
 /**
  * Whether `?poster=1` was asked for (AGL-2743).
  *