prismcast 1.12.0 → 1.13.0

package/dist/streaming/hls.d.ts

@@ -1,5 +1,11 @@
-import type { Nullable, ResolvedChannel } from "../types/index.ts";
+import type { SetupFailureStatus } from "./registry.ts";
+import type { Nullable, ResolvedChannel, ResolvedSiteProfile } from "../types/index.ts";
 import type { Request, Response } from "express";
+import { createPageWithCapture } from "./setup.ts";
+import { unregisterManagedPage } from "../browser/index.ts";
+import type { ResumeData } from "./hlsResume.ts";
+import type { SegmenterContinuity } from "./fmp4Segmenter.ts";
+import type { TabReplacementResult } from "./recovery.ts";
 /**
  * Result of channel validation. On success, contains the resolved channel and service key. On failure, contains the HTTP error details. The body field carries
  * either a plain string (for text error responses) or an object (for JSON error responses), so callers can use typeof to pick res.send() vs res.json().
@@ -32,9 +38,29 @@ export declare function sendValidationError(validation: {
     body: Record<string, string> | string;
     statusCode: number;
 }, res: Response): void;
+/**
+ * Describes a stream setup failure as the status and message the client is answered with. A StreamSetupError carries its own status and user-facing text, which is
+ * the meaning the setup path assigned to the failure; anything else is unexpected and the client learns nothing beyond a 500.
+ * @param error - The error a setup path produced.
+ * @returns The status and message this failure answers with.
+ */
+export declare function describeSetupFailure(error: unknown): SetupFailureStatus;
+/**
+ * Sends a described setup failure to the client. Every streaming route answers a setup failure through here, so one failure means one response shape no matter
+ * which route the client arrived on.
+ *
+ * A 503 carries both back-off headers on every route: Channels DVR reads Retry-After and waits instead of retrying in a tight loop, and an HDHomeRun client reads
+ * X-HDHomeRun-Error to tell a busy tuner apart from a broken one. A response whose headers are already flushed can carry no status at all, so it is ended and the
+ * client sees the connection close.
+ *
+ * Logging stays with the callers: each route describes its own failure in its own words and at its own level.
+ * @param failure - The described failure, from describeSetupFailure or from a literal the caller composed.
+ * @param res - Express response object.
+ */
+export declare function sendSetupFailure(failure: SetupFailureStatus, res: Response): void;
 /**
  * Pure predicate for the concurrent-stream capacity decision. Returns true when a new stream may be admitted given the current active count and the configured
- * limit. Extracted as a standalone function so the boundary arithmetic is pinned by a unit test without driving a browser. The count passed in must be the count
+ * limit. Extracted as a standalone function so the boundary arithmetic is asserted by a unit test without driving a browser. The count passed in must be the count
  * BEFORE the new stream's pending entry is registered, so the new stream is naturally excluded from its own capacity check; admitting the final slot
  * (active === maxConcurrent - 1) returns true.
  * @param activeCount - Number of streams currently registered, excluding the stream being admitted.
@@ -102,6 +128,39 @@ export declare function handleHLSVariantPlaylist(req: Request, res: Response): v
  * @param res - Express response object.
  */
 export declare function handlePlayStream(req: Request, res: Response): Promise<void>;
+export interface TabReplacementDeps {
+    readonly createPageWithCapture: typeof createPageWithCapture;
+    readonly unregisterManagedPage: typeof unregisterManagedPage;
+}
+/**
+ * Creates a tab replacement handler for recovery from unresponsive browser tabs. The replacement builds before it tears down:
+ *
+ * 1. Create a fresh page and acquire its capture, and tune it, while the existing pipeline keeps producing segments for the client
+ * 2. If anything fails before the swap, discard the fresh page and capture and leave the existing pipeline untouched - a logged recovery miss, not a lost recording
+ * 3. Otherwise swap in one synchronous frame: read the old segmenter's continuity, dispose the old pipeline, close the old page, splice the new one in
+ * 4. Return the new page and context for the monitor to continue on
+ *
+ * Because nothing is disposed until the swap, the monitor's single retry re-reads continuity from the still-live old segmenter on its second attempt, and a
+ * stream whose replacement keeps failing keeps serving its recording while the circuit breaker counts.
+ *
+ * The handler preserves existing HLS segments and marks a discontinuity so clients know the stream parameters may have changed. The cost of the overlap is a
+ * second capture and encoder running for the length of the tune, which the CPU and GPU carry.
+ *
+ * Note: This handler is only invoked for capture-mode streams, plus the native fallback that has already declared a pending capture identity. Native-mode
+ * streams bypass video element monitoring entirely, so evaluate timeouts that trigger tab replacement cannot occur on one.
+ *
+ * @param numericStreamId - The stream's numeric ID for registry lookups.
+ * @param streamId - The stream's string ID for logging.
+ * @param channelName - The channel name (or synthetic ad-hoc key like "play-a1b2c3d4") used as the store key for error callbacks and termination.
+ * @param url - The URL to navigate to.
+ * @param profile - The site profile for video handling.
+ * @param metadataComment - Optional comment to embed in FFmpeg output metadata.
+ * @param onCircuitBreak - Callback for circuit breaker trips during replacement.
+ * @param deps - The injected establishment collaborators; defaults to defaultTabReplacementDeps. Threaded so a test drives the real handler - its phase tracking,
+ *               its discard path, and the swap itself - against a substituted establishment rather than a live Chrome.
+ * @returns A handler function that performs tab replacement, or null if the stream no longer exists.
+ */
+export declare function createTabReplacementHandler(numericStreamId: number, streamId: string, channelName: string, url: string, profile: ResolvedSiteProfile, metadataComment: string | undefined, onCircuitBreak: () => void, deps?: TabReplacementDeps): () => Promise<Nullable<TabReplacementResult>>;
 /**
  * Options for initializing a stream.
  */
@@ -128,9 +187,43 @@ interface InitializeStreamOptions {
  * @throws StreamSetupError if setup fails, or Error for unexpected failures.
  */
 export declare function initializeStream(options: InitializeStreamOptions): Promise<Nullable<number>>;
+/**
+ * Handles stream setup failure by recording the failure's status on the pending entry, marking channel health, terminating the entry, and optionally logging the
+ * error. The blocking path (initializeStream) skips logging because it re-throws for callers to handle. The non-blocking path (ensureChannelStream .catch) logs
+ * because there is no outer handler.
+ *
+ * Exported for unit-test coverage of the ordering the recorded status depends on. Production callers reach this only through the setup paths above, never directly.
+ * @param numericStreamId - The pending entry's numeric stream ID.
+ * @param channelName - The channel key for health tracking and termination.
+ * @param channel - The channel definition, or undefined for ad-hoc streams (no health tracking).
+ * @param error - The error that caused the failure.
+ * @param logError - Whether to log the error. False when the caller will re-throw (blocking path), true when fire-and-forget (non-blocking path).
+ */
+export declare function handleSetupFailure(numericStreamId: number, channelName: string, channel: ResolvedChannel | undefined, error: unknown, logError?: boolean): void;
+/**
+ * What a resuming segmenter is told to continue from.
+ */
+export interface BuildResumeContinuityOptions {
+    readonly baseSegmentIndex: number;
+    readonly prerollSegmentCount: number;
+    readonly resumeData: Nullable<ResumeData>;
+}
+/**
+ * Derives what a segmenter continues from, which on a fresh stream is nothing at all. A resume carries the prior session's timestamps and init version, and its
+ * init segment only when no preroll window precedes it - the preroll init differs from the real one, so a byte match there would suppress a discontinuity the
+ * boundary genuinely needs. Session statistics are deliberately absent: a resume from disk has none, and inventing an empty set would tell the segmenter a live
+ * prior session is continuing and count a tab replacement that never happened. The starting index accounts for both the resume offset and the preroll segment
+ * range whenever either contributes one.
+ *
+ * Each member is present only when this resume genuinely carries it, because the segmenter reads presence rather than value: an absent member and a member set
+ * to an empty or zero stand-in mean different things to it.
+ *
+ * @param options - The resume record and the preroll accounting to derive from.
+ * @returns The continuity the segmenter is constructed with.
+ */
+export declare function buildResumeContinuity(options: BuildResumeContinuityOptions): SegmenterContinuity;
 /**
  * Checks for idle streams and terminates them. Called periodically by the idle detection interval.
  */
 export declare function cleanupIdleStreams(): void;
 export {};
-//# sourceMappingURL=hls.d.ts.map