@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/media-delivery.d.ts

@@ -0,0 +1,267 @@
+/**
+ * @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 MediaVideoRendition } from '@aglyn/aglyn/app-utils/media-ref';
+import type { ReleaseFlagKey } from '@aglyn/aglyn/app-utils/release-flags';
+import { type MediaDeliveryClaims, type MediaDeliveryProvider } from '@aglyn/aglyn/plugin-manager/media-delivery-provider';
+/**
+ * Video delivered from the configured delivery provider (AGL-2824): the
+ * platform's half.
+ *
+ * `serveMediaCdn` keeps every access decision it has always made. When a
+ * video request passes all of them, and this module finds a current copy of
+ * the requested representation at the delivery provider, the CDN answers
+ * with a `302` to a short-lived signed URL on the provider's host instead of
+ * streaming the bytes itself. The commerce stream mints the same URL for a
+ * buyer. Everything else — images, posters, downloads, and every video with
+ * no current copy — serves exactly as it did.
+ *
+ * ## Three switches, all of which must be on
+ *
+ * 1. **A provider.** A plugin registers one against core's contract
+ *    (`media-delivery-provider`), and it must be configured for the
+ *    capability in question: `store` to copy or remove, `deliver` to mint.
+ *    With none, every function here returns before any I/O.
+ * 2. **The release flag**, per org: {@link MEDIA_DELIVERY_RELEASE_FLAG}. It
+ *    gates the COPY as well as the redirect, because a copy is customer data
+ *    at the provider. Removal is never gated: a copy made while the flag was
+ *    on must still go when its asset does.
+ * 3. **A current copy**, recorded on the media document under
+ *    {@link MEDIA_DELIVERY_COPIES_FIELD}. A copy is current when it was made
+ *    from the asset's present `contentHash` and its key is the one this
+ *    module derives for the asset. A replace changes the hash, so every copy
+ *    of the previous bytes stops being served in the same write, before
+ *    anything at the provider is removed.
+ *
+ * ## The platform stays the system of record
+ *
+ * The bucket keeps every byte it kept before, and the storage counter moves
+ * exactly as it did: a copy's size is recorded on the copy and never added to
+ * `counters/media`, so storage is billed once. Making the provider's copy the
+ * only one is a later step, and the storage cost model depends on it (see
+ * AGL-2825); nothing here deletes a platform object.
+ *
+ * ## Keys carry the content hash
+ *
+ * `{hosts|orgs}/{scopeId}/{mediaId}/{sourceHash}/{representation}/{objectHash}`.
+ * The source hash is the asset's `contentHash`; the object hash is the
+ * copied object's own digest (for the master the two are the same). A
+ * replaced file or a re-encoded rendition therefore gets a new key, so a URL
+ * minted for old bytes can never be answered with new ones, and the whole
+ * asset is one prefix for removal. The record is written by the server only,
+ * but the key it holds is checked against the derivation before it is used:
+ * a record copied onto another document names a key that is not that
+ * document's own, and is ignored.
+ */
+/** The per-org release flag both halves — copy and redirect — ask. */
+export declare const MEDIA_DELIVERY_RELEASE_FLAG: ReleaseFlagKey;
+/** The media document field that records the copies at the provider. */
+export declare const MEDIA_DELIVERY_COPIES_FIELD = "deliveryCopies";
+/** The representation name of the uploaded file itself. */
+export declare const MEDIA_DELIVERY_MASTER = "master";
+/**
+ * The shortest delivery URL lifetime. A delivery URL is a bearer capability,
+ * so it is short, but a player sends its range requests to the URL it was
+ * redirected to, so it must outlive a sitting: seeking, pausing and resuming
+ * all reuse it.
+ */
+export declare const MEDIA_DELIVERY_MIN_TTL_MS: number;
+/** The lifetime when the film's duration is unknown. */
+export declare const MEDIA_DELIVERY_DEFAULT_TTL_MS: number;
+/** The longest lifetime, shared with every other signed media link. */
+export declare const MEDIA_DELIVERY_MAX_TTL_MS: number;
+/**
+ * How long a delivery URL for a film of `durationMs` lives: twice the film,
+ * so a viewer who pauses halfway still finishes it, between
+ * {@link MEDIA_DELIVERY_MIN_TTL_MS} and {@link MEDIA_DELIVERY_MAX_TTL_MS}.
+ */
+export declare function mediaDeliveryTtlMs(durationMs: unknown): number;
+/** The asset a copy belongs to. */
+export interface MediaDeliveryAsset {
+    collection: 'hosts' | 'orgs';
+    scopeId: string;
+    mediaId: string;
+}
+/** The representation a rendition (or the master, for none) is copied as. */
+export declare function mediaDeliveryRepresentation(rendition: Pick<MediaVideoRendition, 'key'> | null | undefined): string;
+/**
+ * The prefix every copy of one asset lives under, or null for an asset whose
+ * identity does not fit the grammar. Ends in `/`, so one asset's prefix is
+ * never another's.
+ */
+export declare function mediaDeliveryAssetPrefix(asset: MediaDeliveryAsset): string | null;
+/** The prefix every copy of one library lives under, for an erasure. */
+export declare function mediaDeliveryScopePrefix(collection: 'hosts' | 'orgs', scopeId: string): string | null;
+/** The object key of one copy, or null when a part does not fit the grammar. */
+export declare function mediaDeliveryObjectKey(asset: MediaDeliveryAsset, copy: {
+    sourceHash: string;
+    representation: string;
+    objectHash: string;
+}): string | null;
+/** One copy at the provider, as the media document records it. */
+export interface MediaDeliveryCopy {
+    key: string;
+    /** The asset's `contentHash` when the copy was made. */
+    sourceHash: string;
+    /** The copied object's own digest. */
+    objectHash: string;
+    contentType: string;
+    sizeBytes: number;
+    copiedAtMs: number;
+}
+/** The recorded copies of one asset, by representation. */
+export type MediaDeliveryCopies = Record<string, MediaDeliveryCopy>;
+/**
+ * The copies a media document records that belong to THIS asset: each entry
+ * well formed, and its key exactly the one {@link mediaDeliveryObjectKey}
+ * derives from its own fields. Anything else is dropped rather than trusted.
+ */
+export declare function parseMediaDeliveryCopies(raw: unknown, asset: MediaDeliveryAsset): MediaDeliveryCopies;
+/** Whether a served type is one this module delivers: video, nothing else. */
+export declare function isMediaDeliveryType(contentType: unknown): boolean;
+/** Drops the host → org cache. Tests need it between cases. */
+export declare function invalidateMediaDeliveryOrgCache(): void;
+/**
+ * The org that owns a library: the id itself for an org library, and the
+ * host's `hostIndex` entry for a site's. Cached for a minute, like the
+ * release-flag reads it feeds; a failed read answers null, which the flag
+ * treats as "no org" and so refuses anything short of a full release.
+ */
+export declare function mediaDeliveryOrgIdFor(collection: 'hosts' | 'orgs', scopeId: string): Promise<string | null>;
+/** The flag verdict for one org. */
+export declare function mediaDeliveryEnabledForOrg(orgId: string | null): Promise<boolean>;
+export interface MediaDeliveryRedirect {
+    location: string;
+    expiresAtMs: number;
+    key: string;
+}
+/**
+ * The delivery URL for one representation of one asset, or null when the
+ * request must be served the way it always was.
+ *
+ * Called only after the caller has made every access decision. Null for: a
+ * type that is not video; an asset with no current copy of this
+ * representation; the flag off for the owning org; a lifetime that has
+ * already run out; and a provider that fails to mint. The cheap answers come
+ * first, so an asset with no copy costs no read at all.
+ */
+export declare function mediaDeliveryRedirect(input: {
+    provider: MediaDeliveryProvider;
+    asset: MediaDeliveryAsset;
+    document: {
+        get(field: string): unknown;
+    };
+    /** The rendition being served, or none for the master. */
+    rendition?: Pick<MediaVideoRendition, 'key'> | null;
+    servedType: unknown;
+    claims: Omit<MediaDeliveryClaims, 'orgId'>;
+    /** The owning org, asked only once a current copy is found. */
+    orgId: () => Promise<string | null>;
+    /** Defaults to the release flag. */
+    deliveryEnabled?: (orgId: string | null) => Promise<boolean>;
+    /** The URL may not outlive this, e.g. the signature the request carried. */
+    notAfterMs?: number;
+    /** A fixed lifetime; otherwise {@link mediaDeliveryTtlMs} of the film. */
+    ttlMs?: number;
+    nowMs?: number;
+}): Promise<MediaDeliveryRedirect | null>;
+/** The slice of a Storage file the copy reads. */
+export interface MediaDeliverySourceFile {
+    getMetadata(): Promise<unknown>;
+    createReadStream(): NodeJS.ReadableStream;
+}
+/** The slice of a Storage bucket the copy reads. */
+export interface MediaDeliverySourceBucket {
+    file(path: string): MediaDeliverySourceFile;
+}
+export type MediaDeliverySyncStatus = 'no-provider' | 'no-asset' | 'not-video' | 'no-hash' | 'disabled' | 'replaced' | 'synced';
+export interface MediaDeliverySyncResult {
+    status: MediaDeliverySyncStatus;
+    /** Representations copied by this call. */
+    copied: string[];
+    /** Representations whose current copy was already there. */
+    kept: string[];
+    /** Keys removed from the provider because nothing current names them. */
+    removed: string[];
+    /** Representations whose copy failed; they keep serving from the platform. */
+    failed: string[];
+}
+/**
+ * Brings the provider's copies of one video in line with its document: every
+ * representation the document serves — the master and each recorded
+ * rendition — gets a copy made from its current bytes, and a copy nothing
+ * current names is removed.
+ *
+ * Every copy path runs through here: an upload's finalize, a replace, a
+ * restore and the rendition producer. It is safe to run again at any time.
+ * The master's copy is current when it was made from the asset's
+ * `contentHash`; a rendition's when it was made from that hash AND from the
+ * rendition object Storage holds now, since the producer can encode a key
+ * again without the master changing.
+ *
+ * The record is written in a transaction that re-reads the document, and
+ * only while the asset still has the content hash the copies were made from.
+ * An asset replaced or deleted while its copies were uploading keeps that
+ * state, and the copies just made are removed rather than recorded against
+ * bytes they are not.
+ */
+export declare function syncMediaDeliveryCopies(options: {
+    docRef: FirebaseFirestore.DocumentReference;
+    asset: MediaDeliveryAsset;
+    bucket: MediaDeliverySourceBucket;
+    /** The owning org, when the caller has it; otherwise resolved. */
+    orgId?: string | null;
+    /** Defaults to the registered provider configured to store. */
+    provider?: MediaDeliveryProvider | null;
+    /** Defaults to the release flag. */
+    deliveryEnabled?: (orgId: string | null) => Promise<boolean>;
+    nowMs?: () => number;
+}): Promise<MediaDeliverySyncResult>;
+/**
+ * Removes every copy of one asset from the provider: a delete, a takedown and
+ * a replace all end the life of the bytes the copies were made from.
+ *
+ * By prefix rather than by the document's record, so a copy the record lost
+ * track of goes too. Never gated on the flag, since copies made while it was
+ * on must still go, and never throws: the caller's own action has already
+ * happened and must not be reported as failed because a copy lingered. Null
+ * when no provider is configured to store.
+ */
+export declare function removeMediaDeliveryCopies(options: {
+    asset: MediaDeliveryAsset;
+    provider?: MediaDeliveryProvider | null;
+}): Promise<{
+    removed: number;
+    failed: boolean;
+} | null>;
+/**
+ * Removes every copy a library holds at the provider — the erasure of a site
+ * or an org. Same posture as {@link removeMediaDeliveryCopies}.
+ */
+export declare function eraseMediaDeliveryScope(options: {
+    collection: 'hosts' | 'orgs';
+    scopeId: string;
+    provider?: MediaDeliveryProvider | null;
+}): Promise<{
+    removed: number;
+    failed: boolean;
+} | null>;
+/**
+ * A media document without its copy record, for a restore: the delete that
+ * made the tombstone removed the copies, so the record describes objects
+ * that are gone.
+ */
+export declare function withoutMediaDeliveryCopies(media: Record<string, unknown>): Record<string, unknown>;