@mieweb/pulsevault 0.4.1 → 0.5.0

package/dist/lib/capability-token.d.ts

@@ -24,7 +24,18 @@ export type CapabilityTokenClaims = {
      * capability token an upload uses.
      */
     use?: 'view';
+    /**
+     * Opaque host data (`issueCapabilityToken`'s `context`): who the upload is for, where it goes.
+     * Signed with the rest, so it can't be changed by whoever holds the token; stored with the
+     * artifact at create and handed back to every hook. JSON, at most `MAX_CONTEXT_BYTES` encoded.
+     */
+    ctx?: unknown;
 };
+/**
+ * Cap on the encoded `context` claim. The token travels in a QR code and in every request's
+ * `Authorization` header, so a context is an owner and a destination, not a record.
+ */
+export declare const MAX_CONTEXT_BYTES = 1024;
 export type IssueCapabilityTokenOptions = {
     /** Key id this token is signed under. Required so rotation has an explicit overlap window. */
     keyId: string;
@@ -32,6 +43,13 @@ export type IssueCapabilityTokenOptions = {
     issuer: string;
     /** Token lifetime in seconds. Defaults to 1800 (30 minutes). */
     expirySeconds?: number;
+    /**
+     * Opaque host data signed into the token (`ctx` claim): the owner, the destination — whatever
+     * the host would otherwise keep in a table keyed by artifactId. PulseVault stores it with the
+     * artifact at create and hands it to `authorize`, `onUploadComplete`, `getStatus` and
+     * `getPulse`, so most hosts need no lookup table of their own. JSON, at most 1 KiB encoded.
+     */
+    context?: unknown;
 };
 /**
  * Mint a stateless, HMAC-signed capability token scoped to one artifact (or
@@ -64,6 +82,13 @@ export type VerifyCapabilityTokenOptions = {
     issuer: string;
     /** Clock-skew tolerance in seconds applied to both `iat` and `exp` checks. Defaults to 30. */
     clockToleranceSeconds?: number;
+    /**
+     * Whether `createCapabilityAuthorize` holds a create to the shape of a pulse: a video only
+     * under the token's own `artifactId` (with no `relatedTo`), and a thumbnail, beat manifest or
+     * captions only under another id, `relatedTo` the token's. Defaults to `true`, matching the
+     * core's `pulseShape` option; set `false` there and here for non-Pulse uploads.
+     */
+    pulseShape?: boolean;
 };
 /**
  * Verify a token minted by `issueCapabilityToken`. Returns the authorized
@@ -75,6 +100,7 @@ export type VerifyCapabilityTokenOptions = {
  */
 export declare function verifyCapabilityToken(token: string, lookupSecret: LookupSecret, opts: VerifyCapabilityTokenOptions): {
     artifactId: string;
+    context?: unknown;
 } | null;
 /**
  * Verify a view token minted by `issueViewToken`. Returns the `artifactId` it opens and its

package/dist/lib/capability-token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-token.d.ts","sourceRoot":"","sources":["../../src/lib/capability-token.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAA8B,MAAM,gBAAgB,CAAC;AAEtF;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AA+BF,MAAM,MAAM,2BAA2B,GAAG;IACxC,8FAA8F;IAC9F,KAAK,EAAE,MAAM,CAAC;IACd,qGAAqG;IACrG,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,2BAA2B,GAChC,MAAM,CAWR;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,qBAAqB,GAC1B,MAAM,CAgBR;AAED,0GAA0G;AAC1G,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAExE,MAAM,MAAM,4BAA4B,GAAG;IACzC,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAoDF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,4BAA4B,GACjC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAG/B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,4BAA4B,GACjC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAE5C;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,4BAA4B,GACjC,mBAAmB,CAgBrB"}
+{"version":3,"file":"capability-token.d.ts","sourceRoot":"","sources":["../../src/lib/capability-token.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAA8B,MAAM,gBAAgB,CAAC;AAEtF;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAgDtC,MAAM,MAAM,2BAA2B,GAAG;IACxC,8FAA8F;IAC9F,KAAK,EAAE,MAAM,CAAC;IACd,qGAAqG;IACrG,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,2BAA2B,GAChC,MAAM,CAaR;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,qBAAqB,GAC1B,MAAM,CAgBR;AAED,0GAA0G;AAC1G,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAExE,MAAM,MAAM,4BAA4B,GAAG;IACzC,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAiEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,4BAA4B,GACjC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAOlD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,4BAA4B,GACjC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAE5C;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,4BAA4B,GACjC,mBAAmB,CA2CrB"}

package/dist/lib/capability-token.js

@@ -1,6 +1,31 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 const DEFAULT_EXPIRY_SECONDS = 1800; // 30 minutes — long enough for one upload session.
 const DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+/**
+ * Cap on the encoded `context` claim. The token travels in a QR code and in every request's
+ * `Authorization` header, so a context is an owner and a destination, not a record.
+ */
+export const MAX_CONTEXT_BYTES = 1024;
+/** `JSON.stringify` a context, refusing anything that isn't plain JSON or is too large. */
+function encodeContext(context) {
+    if (context === undefined) {
+        throw new TypeError('`context` must be JSON (an object, array, string, number, boolean or null)');
+    }
+    let encoded;
+    try {
+        encoded = JSON.stringify(context);
+    }
+    catch {
+        throw new TypeError('`context` must be JSON-serializable');
+    }
+    if (encoded === undefined) {
+        throw new TypeError('`context` must be JSON (an object, array, string, number, boolean or null)');
+    }
+    if (Buffer.byteLength(encoded, 'utf8') > MAX_CONTEXT_BYTES) {
+        throw new TypeError(`\`context\` must encode to at most ${MAX_CONTEXT_BYTES} bytes of JSON`);
+    }
+    return encoded;
+}
 function base64urlEncode(input) {
     return Buffer.from(input, 'utf8').toString('base64url');
 }
@@ -40,6 +65,8 @@ export function issueCapabilityToken(artifactId, secret, opts) {
         exp: now + (opts.expirySeconds ?? DEFAULT_EXPIRY_SECONDS),
         kid: opts.keyId,
         issuer: opts.issuer,
+        // Round-tripped through JSON so the claim is exactly what a verifier will read back.
+        ...(opts.context !== undefined ? { ctx: JSON.parse(encodeContext(opts.context)) } : {}),
     };
     const payload = base64urlEncode(JSON.stringify(claims));
     return `${payload}.${sign(payload, secret)}`;
@@ -113,7 +140,21 @@ function verifyToken(token, lookupSecret, opts, use) {
         return null;
     if (claims.issuer !== opts.issuer)
         return null;
-    return { artifactId: claims.artifactId, exp: claims.exp };
+    // The signature already covers `ctx`; the size cap is enforced on the way in, and checked
+    // again here so a token minted elsewhere with the same secret can't carry a huge context.
+    if (claims.ctx !== undefined) {
+        try {
+            encodeContext(claims.ctx);
+        }
+        catch {
+            return null;
+        }
+    }
+    return {
+        artifactId: claims.artifactId,
+        exp: claims.exp,
+        ...(claims.ctx !== undefined ? { context: claims.ctx } : {}),
+    };
 }
 /**
  * Verify a token minted by `issueCapabilityToken`. Returns the authorized
@@ -125,7 +166,12 @@ function verifyToken(token, lookupSecret, opts, use) {
  */
 export function verifyCapabilityToken(token, lookupSecret, opts) {
     const verified = verifyToken(token, lookupSecret, opts, 'upload');
-    return verified && { artifactId: verified.artifactId };
+    if (!verified)
+        return null;
+    return {
+        artifactId: verified.artifactId,
+        ...(verified.context !== undefined ? { context: verified.context } : {}),
+    };
 }
 /**
  * Verify a view token minted by `issueViewToken`. Returns the `artifactId` it opens and its
@@ -171,19 +217,41 @@ function extractToken(request, ctx) {
  * can't be used to change anything or to extend itself.
  */
 export function createCapabilityAuthorize(lookupSecret, opts) {
+    const pulseShape = opts.pulseShape ?? true;
     return async (request, ctx) => {
         const token = extractToken(request, ctx);
         if (!token) {
             throw Object.assign(new Error('Missing capability token'), { statusCode: 401 });
         }
-        const verified = verifyCapabilityToken(token, lookupSecret, opts) ??
-            (ctx.phase === 'resolve' ? verifyViewToken(token, lookupSecret, opts) : null);
+        const readOnly = ctx.phase === 'resolve' || ctx.phase === 'status';
+        const capability = verifyCapabilityToken(token, lookupSecret, opts);
+        const verified = capability ?? (readOnly ? verifyViewToken(token, lookupSecret, opts) : null);
         if (!verified) {
             throw Object.assign(new Error('Invalid or expired capability token'), { statusCode: 403 });
         }
-        if (ctx.artifactId !== verified.artifactId && ctx.relatedTo !== verified.artifactId) {
+        if (pulseShape && ctx.phase === 'create') {
+            // The shape of a pulse: the token names the video, and only the video is created under
+            // that id. Everything else is created under its own id, `relatedTo` the token's. Without
+            // this, a token could create any number of videos under ids of the client's choosing, or
+            // take the video's own id with a thumbnail so the real video can never land.
+            const ok = ctx.kind === 'video'
+                ? ctx.artifactId === verified.artifactId && ctx.relatedTo === undefined
+                : ctx.relatedTo === verified.artifactId && ctx.artifactId !== verified.artifactId;
+            if (!ok) {
+                throw Object.assign(new Error(ctx.kind === 'video'
+                    ? 'A video is uploaded under the token’s own artifactId, with no relatedTo'
+                    : `A ${ctx.kind} is uploaded under its own artifactId, relatedTo the token’s`), { statusCode: 403 });
+            }
+        }
+        else if (ctx.artifactId !== verified.artifactId && ctx.relatedTo !== verified.artifactId) {
             throw Object.assign(new Error('Token does not authorize this artifact'), { statusCode: 403 });
         }
+        // The token's context is stored with the artifact it creates, so every later hook, status
+        // read and replay gets it without a host lookup.
+        if (ctx.phase === 'create' && capability?.context !== undefined) {
+            return { context: capability.context };
+        }
+        return undefined;
     };
 }
 //# sourceMappingURL=capability-token.js.map

package/dist/lib/capability-token.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability-token.js","sourceRoot":"","sources":["../../src/lib/capability-token.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"capability-token.js","sourceRoot":"","sources":["../../src/lib/capability-token.ts"],"names":[],"mappings":"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"}

package/dist/lib/completion.d.ts

@@ -0,0 +1,135 @@
+import { type WebReadyOptions, type WebReadyResult } from './web-ready.js';
+import { type PulseVaultLogger, type PulseVaultRequest } from './request.js';
+import type { PulseVaultStorage, UploadKind } from '../storage/types.js';
+/**
+ * What `onUploadComplete` is told about a finished upload. Everything the client sent in
+ * `Upload-Metadata` and everything the token carried, so a host can map the file to its own
+ * record without reading storage back.
+ */
+export type PulseVaultUploadCompleteContext = {
+    artifactId: string;
+    kind: UploadKind;
+    /** Bytes stored. `0` on a replay when the adapter can't tell. */
+    size: number;
+    /** tus's upload id (`<kind>/<artifactId><ext>`). */
+    uploadId: string;
+    /** Original filename from `Upload-Metadata.filename`. */
+    filename: string;
+    /** Lowercase extension of `filename`, with the leading dot. */
+    ext: string;
+    /** The video this artifact belongs to (`Upload-Metadata.relatedTo`), for a thumbnail, beat manifest or captions. */
+    relatedTo?: string;
+    /** The display name from `Upload-Metadata.name` (the draft's title), when sent. */
+    name?: string;
+    /** The uploading app's version, when sent. */
+    appVersion?: string;
+    /** The host data the capability token carried (`issueCapabilityToken`'s `context`). */
+    context?: unknown;
+    /**
+     * `true` when PulseVault is firing this completion again: the hook threw, or the process
+     * stopped, before it recorded the first one. Hosts must treat completion as at-least-once —
+     * check their own record before writing it again.
+     */
+    replay: boolean;
+    /** With `webReady.completeAfter`, what the conversion did — the hook runs once it has finished. */
+    webReady?: WebReadyResult;
+};
+export type PulseVaultOnUploadComplete = (request: PulseVaultRequest, ctx: PulseVaultUploadCompleteContext) => void | Promise<void>;
+/**
+ * Fired at low-frequency, audit-worthy moments — never per chunk — so an
+ * operator can wire one hook to get both ops metrics and a compliance audit
+ * trail without hand-rolling both from the lower-level hooks. `remove` fires
+ * after PulseVault removed an artifact: a `DELETE /artifacts/:id` or a TUS
+ * `DELETE` (`reason: "deleted"`), the `retention` sweep (`reason: "abandoned"`),
+ * or a create that reclaimed an idle, unfinished upload (`reason: "reclaimed"`)
+ * — so a host keeping its own index of artifacts can drop it. `processed`
+ * fires when a web-ready conversion has finished, with what it did.
+ */
+export type PulseVaultArtifactEvent = {
+    phase: 'authorize' | 'complete' | 'reject' | 'remove' | 'processed';
+    artifactId: string;
+    kind: UploadKind;
+    size?: number;
+    reason?: string;
+    /** The uploading app's version, from `Upload-Metadata.appVersion` (`complete`/`reject` only). */
+    appVersion?: string;
+    /** What the conversion did (`processed` only). */
+    webReady?: WebReadyResult;
+};
+export type PulseVaultOnArtifactEvent = (event: PulseVaultArtifactEvent) => void | Promise<void>;
+/**
+ * Web-ready conversion of every finished video: a lossless faststart remux, or an H.264
+ * transcode for a codec browsers can't play (`ensureWebReady`), run after the final `PATCH` is
+ * answered so the client never waits on ffmpeg. Local storage only; on an adapter without
+ * `getLocalPath` the option is refused at boot.
+ */
+export type PulseVaultWebReadyOptions = WebReadyOptions & {
+    /** How many conversions run at once. A transcode is CPU-bound; defaults to 1. */
+    concurrency?: number;
+    /**
+     * Call `onUploadComplete` only once the conversion has finished, with `ctx.webReady` saying
+     * what it did — so a host that publishes from the hook never publishes a video that's still
+     * being rewritten. Defaults to `false`: the hook runs at once and the conversion follows.
+     */
+    completeAfter?: boolean;
+};
+export type PulseVaultReplayOptions = {
+    /**
+     * How often PulseVault settles finished artifacts it isn't done with: the host's
+     * `onUploadComplete` never returned (it threw, or the process stopped first), or a conversion
+     * never finished. The first pass runs shortly after start. Defaults to 300 seconds.
+     */
+    intervalSeconds?: number;
+};
+export type CompletionRunnerOptions = {
+    storage: PulseVaultStorage;
+    onUploadComplete?: PulseVaultOnUploadComplete;
+    onArtifactEvent?: PulseVaultOnArtifactEvent;
+    webReady?: PulseVaultWebReadyOptions | boolean;
+    replay?: PulseVaultReplayOptions | false;
+    logger?: PulseVaultLogger;
+};
+export type FinishedUpload = {
+    artifactId: string;
+    kind: UploadKind;
+    size: number;
+    uploadId: string;
+};
+export type CompletionRunner = {
+    /**
+     * Settle an upload whose bytes are stored and marked ready. Resolves once the final request
+     * may be answered: after `onUploadComplete` when it runs inline (and rejects when the hook
+     * threw, so the client gets a non-2xx), or at once when the hook waits for the conversion.
+     */
+    complete(request: PulseVaultRequest, upload: FinishedUpload): Promise<void>;
+    /**
+     * One pass over storage: settle every finished artifact that still needs something — a hook
+     * that never returned, a conversion that never finished. Resolves the artifactIds it settled.
+     * Needs `storage.listArtifacts` and `describeArtifact`; resolves `[]` without them.
+     */
+    replay(): Promise<string[]>;
+    /** Whether a web-ready conversion applies to an artifact of this kind: `webReady` is on and it's a video. */
+    converts(kind: UploadKind): boolean;
+    /** Start the periodic replay (no-op when replay is off). The timer never keeps the process alive. */
+    start(): void;
+    /** Stop the periodic replay and wait for conversions and hooks in progress. */
+    stop(): Promise<void>;
+};
+/** Fail at boot on a setting that can't work, rather than silently doing nothing later. */
+export declare function validateCompletionOptions(opts: Pick<CompletionRunnerOptions, 'storage' | 'webReady' | 'replay'>): void;
+/**
+ * The completion pipeline shared by the core and the Fastify plugin. Everything it knows is on
+ * the artifact's sidecar: `converted` (the web-ready pass finished; written `false` at reserve)
+ * and `acknowledged` (the host's `onUploadComplete` returned). One rule settles a finished
+ * artifact, whether its final chunk just landed, a retried request finished it a second time,
+ * or a replay found it after a throw or a restart:
+ *
+ *   1. if a conversion applies and it isn't converted, convert (idempotent), then record it;
+ *   2. if it isn't acknowledged, run the hook — after 1 with `completeAfter`, otherwise at
+ *      once — then record it.
+ *
+ * The only thing kept in memory is which artifacts are being settled right now, so the same
+ * artifact isn't settled twice at once.
+ */
+export declare function createCompletionRunner(opts: CompletionRunnerOptions): CompletionRunner;
+//# sourceMappingURL=completion.d.ts.map

package/dist/lib/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/lib/completion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAiB,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,KAAK,EAA0B,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjG;;;;GAIG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,oHAAoH;IACpH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,EAAE,+BAA+B,KACjC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;;;;;;;;GASG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,CAAC;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjG;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,eAAe,GAAG;IACxD,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;IAC9C,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC;IAC/C,MAAM,CAAC,EAAE,uBAAuB,GAAG,KAAK,CAAC;IACzC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtG,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5B,6GAA6G;IAC7G,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC,qGAAqG;IACrG,KAAK,IAAI,IAAI,CAAC;IACd,+EAA+E;IAC/E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB,CAAC;AAYF,2FAA2F;AAC3F,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,IAAI,CAAC,uBAAuB,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC,GACrE,IAAI,CA+BN;AAiDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,GAAG,gBAAgB,CAgNtF"}

package/dist/lib/completion.js

@@ -0,0 +1,288 @@
+import { ensureWebReady } from './web-ready.js';
+import { consoleLogger } from './request.js';
+const DEFAULT_REPLAY_INTERVAL_SECONDS = 300;
+/** The first replay after start: late enough for the host to finish booting. */
+const FIRST_REPLAY_DELAY_MS = 5_000;
+/** A request-shaped stand-in for replays, whose original request is long gone. */
+const REPLAY_REQUEST = { headers: {} };
+/** Fail at boot on a setting that can't work, rather than silently doing nothing later. */
+export function validateCompletionOptions(opts) {
+    if (opts.webReady) {
+        if (typeof opts.storage.getLocalPath !== 'function') {
+            throw new TypeError('`webReady` needs a storage adapter with `getLocalPath` (the local adapter): ffmpeg rewrites the file in place');
+        }
+        if (typeof opts.storage.patchArtifact !== 'function') {
+            throw new TypeError('`webReady` needs a storage adapter with `patchArtifact`');
+        }
+        if (typeof opts.webReady === 'object') {
+            const { concurrency } = opts.webReady;
+            if (concurrency !== undefined && !(Number.isInteger(concurrency) && concurrency >= 1)) {
+                throw new TypeError('`webReady.concurrency` must be a positive integer');
+            }
+        }
+    }
+    if (opts.replay) {
+        const { intervalSeconds } = opts.replay;
+        if (intervalSeconds !== undefined && !(intervalSeconds > 0 && Number.isFinite(intervalSeconds))) {
+            throw new TypeError('`replayCompletions.intervalSeconds` must be a positive number of seconds');
+        }
+        // A replay that can find unacknowledged artifacts but can't record an acknowledgement would
+        // run the hook again on every pass, forever.
+        const { listArtifacts, describeArtifact, patchArtifact } = opts.storage;
+        if (typeof listArtifacts === 'function' && typeof describeArtifact === 'function' && typeof patchArtifact !== 'function') {
+            throw new TypeError('`replayCompletions` needs a storage adapter with `patchArtifact` to record what was replayed (or set `replayCompletions: false`)');
+        }
+    }
+}
+/** The hook context for an artifact, from its stored metadata. */
+function contextFor(meta, upload, replay) {
+    return {
+        artifactId: upload.artifactId,
+        kind: upload.kind,
+        size: upload.size,
+        uploadId: upload.uploadId,
+        filename: meta?.filename ?? '',
+        ext: meta?.ext ?? '',
+        ...(meta?.relatedTo ? { relatedTo: meta.relatedTo } : {}),
+        ...(meta?.name ? { name: meta.name } : {}),
+        ...(meta?.appVersion ? { appVersion: meta.appVersion } : {}),
+        ...(meta?.context !== undefined ? { context: meta.context } : {}),
+        replay,
+    };
+}
+/** A bounded set of concurrent jobs: `run` waits for a slot, `drain` waits for every job. */
+function createQueue(concurrency) {
+    let active = 0;
+    const waiting = [];
+    const running = new Set();
+    const run = (job) => {
+        const task = (async () => {
+            if (active >= concurrency)
+                await new Promise((resolve) => waiting.push(resolve));
+            active++;
+            try {
+                await job();
+            }
+            finally {
+                active--;
+                waiting.shift()?.();
+            }
+        })();
+        running.add(task);
+        void task.finally(() => running.delete(task));
+        return task;
+    };
+    const drain = async () => {
+        while (running.size > 0)
+            await Promise.allSettled([...running]);
+    };
+    return { run, drain };
+}
+/**
+ * The completion pipeline shared by the core and the Fastify plugin. Everything it knows is on
+ * the artifact's sidecar: `converted` (the web-ready pass finished; written `false` at reserve)
+ * and `acknowledged` (the host's `onUploadComplete` returned). One rule settles a finished
+ * artifact, whether its final chunk just landed, a retried request finished it a second time,
+ * or a replay found it after a throw or a restart:
+ *
+ *   1. if a conversion applies and it isn't converted, convert (idempotent), then record it;
+ *   2. if it isn't acknowledged, run the hook — after 1 with `completeAfter`, otherwise at
+ *      once — then record it.
+ *
+ * The only thing kept in memory is which artifacts are being settled right now, so the same
+ * artifact isn't settled twice at once.
+ */
+export function createCompletionRunner(opts) {
+    const { storage, onUploadComplete, onArtifactEvent } = opts;
+    const logger = opts.logger ?? consoleLogger;
+    const webReady = opts.webReady
+        ? typeof opts.webReady === 'object'
+            ? opts.webReady
+            : {}
+        : undefined;
+    const completeAfter = webReady?.completeAfter === true;
+    const queue = createQueue(webReady?.concurrency ?? 1);
+    const replayEvery = opts.replay === false ? null : (opts.replay?.intervalSeconds ?? DEFAULT_REPLAY_INTERVAL_SECONDS) * 1000;
+    const converts = (kind) => webReady !== undefined && kind === 'video';
+    const describe = (artifactId) => storage.describeArtifact ? storage.describeArtifact(artifactId) : Promise.resolve(null);
+    const record = async (artifactId, patch) => {
+        try {
+            await storage.patchArtifact?.(artifactId, patch);
+        }
+        catch (err) {
+            // The work was done; a failed record means one extra pass over it, not a lost completion.
+            logger.error({ err, artifactId, patch }, 'pulsevault could not record a completion step');
+        }
+    };
+    /** Rule 1. Never throws: a failed conversion serves the original bytes and is tried again later. */
+    const convert = (ctx) => new Promise((resolve) => {
+        void queue.run(async () => {
+            try {
+                const localPath = await storage.getLocalPath?.(ctx.artifactId);
+                const result = typeof localPath === 'string'
+                    ? await ensureWebReady(localPath, { ...webReady, logger })
+                    : { action: 'skipped', reason: 'no local path for this artifact' };
+                await record(ctx.artifactId, { converted: true });
+                await onArtifactEvent?.({
+                    phase: 'processed',
+                    artifactId: ctx.artifactId,
+                    kind: ctx.kind,
+                    size: ctx.size,
+                    reason: result.reason,
+                    webReady: result,
+                });
+                resolve(result);
+            }
+            catch (err) {
+                logger.error({ err, artifactId: ctx.artifactId }, 'pulsevault web-ready conversion failed');
+                resolve(undefined);
+            }
+        });
+    });
+    /** Rule 2. Rethrows what the hook threw. */
+    const hook = async (request, ctx) => {
+        if (onUploadComplete)
+            await onUploadComplete(request, ctx);
+        await record(ctx.artifactId, { acknowledged: true });
+    };
+    /** One artifact is settled by one caller at a time; a second caller joins the first. */
+    const settling = new Map();
+    /**
+     * Apply the rule to one finished artifact. The request that finished the upload waits on the
+     * result: it rejects when the hook threw, so the client gets a non-2xx — except with
+     * `completeAfter`, where the hook follows the conversion in the background and the request
+     * is answered at once. In the background (a replay, a hook after a conversion) a throw is
+     * logged and left for the next pass.
+     */
+    const settle = (request, meta, upload, replay) => {
+        const running = settling.get(upload.artifactId);
+        if (running)
+            return running;
+        const ctx = contextFor(meta, upload, replay);
+        // An adapter without `describeArtifact` can't say what was done: run everything (the hook
+        // is at-least-once anyway, and the conversion is idempotent).
+        const needsConversion = converts(upload.kind) && !(meta ? meta.converted : false);
+        const needsHook = meta ? !meta.acknowledged : true;
+        if (!needsConversion && !needsHook)
+            return Promise.resolve();
+        let run;
+        if (needsConversion && completeAfter) {
+            // Nothing for the request to wait on: the hook follows the conversion.
+            run = (async () => {
+                const result = await convert(ctx);
+                if (!needsHook)
+                    return;
+                try {
+                    await hook(request, { ...ctx, ...(result ? { webReady: result } : {}) });
+                }
+                catch (err) {
+                    logger.error({ err, artifactId: ctx.artifactId, kind: ctx.kind }, 'pulsevault onUploadComplete failed after web-ready; it will be tried again');
+                }
+            })();
+            settling.set(upload.artifactId, run);
+            void run.finally(() => settling.delete(upload.artifactId));
+            return Promise.resolve();
+        }
+        run = (async () => {
+            const conversion = needsConversion ? convert(ctx) : Promise.resolve(undefined);
+            try {
+                if (needsHook)
+                    await hook(request, ctx);
+            }
+            finally {
+                // The settle covers the conversion too, so a replay doesn't queue it again meanwhile.
+                void conversion.finally(() => settling.delete(upload.artifactId));
+            }
+        })();
+        settling.set(upload.artifactId, run);
+        return run;
+    };
+    const complete = async (request, upload) => settle(request, await describe(upload.artifactId), upload, false);
+    /** The stored size of a finished upload, from tus's own record; `0` when it can't be read. */
+    const storedSize = async (uploadId) => {
+        try {
+            const upload = await storage.datastore.getUpload(uploadId);
+            return upload.size ?? upload.offset ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    };
+    let replaying = null;
+    const replay = () => {
+        if (replaying)
+            return replaying;
+        replaying = (async () => {
+            const replayed = [];
+            if (typeof storage.listArtifacts !== 'function' || typeof storage.describeArtifact !== 'function') {
+                return replayed;
+            }
+            const pending = [];
+            for await (const record of storage.listArtifacts()) {
+                if (!record.ready || settling.has(record.artifactId))
+                    continue;
+                let meta;
+                try {
+                    meta = await storage.describeArtifact(record.artifactId);
+                }
+                catch (err) {
+                    logger.error({ err, artifactId: record.artifactId }, 'pulsevault replay could not read an artifact');
+                    continue;
+                }
+                if (!meta || !meta.ready || settling.has(meta.artifactId))
+                    continue;
+                if (meta.acknowledged && !(converts(meta.kind) && !meta.converted))
+                    continue;
+                const uploadId = `${meta.kind}/${meta.artifactId}${meta.ext}`;
+                const upload = {
+                    artifactId: meta.artifactId,
+                    kind: meta.kind,
+                    size: await storedSize(uploadId),
+                    uploadId,
+                };
+                replayed.push(meta.artifactId);
+                pending.push(settle(REPLAY_REQUEST, meta, upload, true).catch((err) => {
+                    logger.error({ err, artifactId: meta.artifactId, kind: meta.kind }, 'pulsevault onUploadComplete failed on replay; it will be tried again');
+                }));
+            }
+            await Promise.all(pending);
+            return replayed;
+        })().finally(() => {
+            replaying = null;
+        });
+        return replaying;
+    };
+    let timer = null;
+    let stopped = false;
+    const schedule = (delayMs) => {
+        if (stopped || replayEvery === null)
+            return;
+        timer = setTimeout(() => {
+            timer = null;
+            void replay()
+                .catch((err) => logger.error({ err }, 'pulsevault completion replay failed'))
+                .finally(() => schedule(replayEvery));
+        }, delayMs);
+        timer.unref();
+    };
+    return {
+        complete,
+        replay,
+        converts,
+        start: () => {
+            if (timer || stopped)
+                return;
+            schedule(Math.min(FIRST_REPLAY_DELAY_MS, replayEvery ?? FIRST_REPLAY_DELAY_MS));
+        },
+        stop: async () => {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+            await replaying?.catch(() => []);
+            await queue.drain();
+            await Promise.allSettled([...settling.values()]);
+        },
+    };
+}
+//# sourceMappingURL=completion.js.map