prismcast 1.10.2 → 1.11.0

package/dist/browser/hlsPlaylistObserver.js

@@ -0,0 +1,132 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * hlsPlaylistObserver.ts: HLS-aware observer layered on top of the tab-wide network observer.
+ */
+import { LOG, chromeFetch } from "../utils/index.js";
+import { classifyHlsPlaylist, extractChildPlaylistUrls, isLiveMediaPlaylist } from "../native/probe.js";
+import { observeTabResponses } from "./tabNetworkObserver.js";
+/* This module is the HLS-aware layer on top of tabNetworkObserver. Its job is to deliver every recognized HLS playlist (URL + kind) observed anywhere in the tab
+ * to a single callback. It encapsulates:
+ *
+ *   - URL filter: only `.m3u8` URLs (query string ignored) are eligible
+ *   - Body fetch: Node-side fetch via chromeFetch (CDP's Network.getResponseBody is unreliable because Chrome's network cache can evict response bodies)
+ *   - Classification: dispatch to classifyHlsPlaylist() to decide master vs media vs unknown
+ *   - Per-URL deduplication: the same `.m3u8` URL fired multiple times during the observation window (typical: hls.js re-polling the chunklist every ~2s)
+ *     produces exactly one body fetch and exactly one callback delivery
+ *
+ * It does not know about manifest selection policy - the channel-selection epoch, playlist membership, the liveness override, finalize semantics, or
+ * predicate-based verification - those are consumer concerns and live in manifestInterceptor.ts (the long-lived interception path and the short-lived
+ * predicate-match path). This module is the single source of truth for "given a tab, observe its HLS playlists"; any future feature that needs the same primitive
+ * (debug logging of every observed playlist, playlist content archiving, etc.) consumes this module rather than re-implementing the filter + fetch + classify
+ * pipeline.
+ *
+ * Dedup rationale. During a typical interception window the hls.js player inside an OOPIF re-polls its chunklist multiple times. Without dedup we would fetch
+ * and classify the chunklist body once per poll, wasting CPU and network. Dedup is applied at the URL gate (before fetch is initiated) so an in-flight fetch is
+ * not duplicated by a near-simultaneous second observation. URLs are kept in the set across both successful and failed fetches: a manifest URL that failed to
+ * fetch is unlikely to succeed on an immediate retry, and the interceptor timeout in the consumer is the safety net for genuinely missed manifests. A consumer
+ * that needs different dedup semantics (e.g., refetch every N seconds) constructs its own observer rather than parameterizing this one.
+ */
+// Timeout for the per-response manifest body fetch. The body is fed to classifyHlsPlaylist() to determine whether it is a master playlist; if Chrome's network
+// cache evicts the body or the CDN serves a slow response, we abandon and treat the response as unclassifiable.
+const MANIFEST_BODY_FETCH_TIMEOUT = 5000;
+/**
+ * Installs an HLS playlist observer on the given page. The callback fires once per unique recognized HLS playlist URL observed across the tab's entire target
+ * tree (top frame, iframes including OOPIFs, workers, service workers). The OOPIF-aware transport is provided by tabNetworkObserver underneath; this observer
+ * adds the HLS-specific filter, body fetch, classification dispatch, and per-URL dedup.
+ *
+ * Returns null when the underlying tab network observer could not be installed (page closed, root CDP session creation failed).
+ *
+ * @param page - The puppeteer page to observe.
+ * @param options - Observer options including the playlist callback and the debug log category.
+ * @returns The observer handle, or null if installation failed.
+ */
+export async function observeHlsPlaylists(page, options) {
+    const { logCategory, onPlaylist } = options;
+    let disposed = false;
+    // Wire-arrival sequence counter. Each eligible unique URL is assigned the next ordinal synchronously at the dedup gate - before its body fetch begins - so the
+    // ordinal reflects the order responses arrived on the wire rather than the order their independent, racing body fetches happen to resolve. Sequences start at 1,
+    // so a currentSequence() of 0 means nothing has been observed yet and an epoch fenced at 0 reads every later observation as post-epoch. The honest bound: the
+    // ordinal reflects CDP-event arrival order at the client, and Chrome does not guarantee cross-session event ordering for OOPIF targets, so the fence approximates
+    // wire order within event-delivery latency - a residual window of milliseconds, in place of the seconds-wide body-fetch race a delivery-time ordering would carry.
+    let sequenceCounter = 0;
+    // Per-URL dedup state. We add a URL to seenUrls the moment we decide to fetch it - before the asynchronous chromeFetch resolves - so a second observation of
+    // the same URL arriving while the first fetch is in flight does not initiate a duplicate fetch. URLs remain in the set for the observer's lifetime; the
+    // consumer's interception window timeout bounds the memory footprint.
+    const seenUrls = new Set();
+    // Handles a single response delivered by the tab network observer. Filters to .m3u8 URLs, applies per-URL dedup, fetches the body for classification, and
+    // dispatches the kind to the consumer callback. Wrapped in try/catch so a body-fetch failure on one URL does not interfere with subsequent responses arriving
+    // on other URLs.
+    const handleResponse = async (url) => {
+        if (disposed) {
+            return;
+        }
+        // Strip query parameters before checking the extension. Many CDNs append cache-busting or tokenization query strings to .m3u8 URLs.
+        const urlPath = url.split("?")[0] ?? "";
+        if (!urlPath.endsWith(".m3u8")) {
+            return;
+        }
+        // Dedup gate. We use the full URL (with query string) as the dedup key so two different tokenized URLs to the same playlist do not collapse. The chunklist
+        // poll case - where hls.js fires the same exact URL repeatedly - is the workload this optimization targets.
+        if (seenUrls.has(url)) {
+            return;
+        }
+        seenUrls.add(url);
+        // Assign the wire-arrival ordinal synchronously, immediately past the dedup gate and before the first await, so it reflects the order this response arrived
+        // rather than the order its body fetch resolves against every other in-flight fetch. The local rides through the fetch and is delivered on the observation.
+        const sequence = ++sequenceCounter;
+        LOG.debug(logCategory, "Observed .m3u8 response (seq %s): %s.", sequence, url.slice(0, 120));
+        try {
+            const response = await chromeFetch(url, { signal: AbortSignal.timeout(MANIFEST_BODY_FETCH_TIMEOUT) });
+            if (!response.ok) {
+                LOG.debug(logCategory, "Manifest fetch returned HTTP %s for %s.", response.status, url.slice(0, 120));
+                return;
+            }
+            const body = await response.text();
+            // Delegate the master/media decision to the canonical classifier. Recognized kinds (master, media) are forwarded to the callback together with the kind
+            // label; consumers apply their own filter. Both consumers (installManifestInterceptor and awaitMatchingManifest) maintain their own resolved-flag guards,
+            // but we still gate locally on the disposed flag so a callback that arrives after dispose is never invoked even if the consumer guard were absent.
+            const kind = classifyHlsPlaylist(body);
+            if (kind === "unknown") {
+                LOG.debug(logCategory, "Skipping .m3u8 classified as unknown (no recognizable HLS directives).");
+                return;
+            }
+            // The disposed flag may have flipped during the awaits above. Closure-captured mutation across awaits is invisible to ESLint's flow analysis (which is why
+            // the next line carries an explicit disable), but it is observable at runtime and matters for race-safety: we never deliver a callback after dispose, full
+            // stop. This guard lives here because race safety is the observer's responsibility, not the consumer's - consumers should not have to repeat it.
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (disposed) {
+                return;
+            }
+            // Build the arm the consumer sees. The per-kind facts are computed here, in the single pass over a body already fetched: a master carries its declared
+            // children (for membership judgment upstream), a media carries its liveness (whether it may still grow). Both helpers never throw, so a degraded fact never
+            // drops the whole observation.
+            const playlist = (kind === "master") ?
+                { childUrls: extractChildPlaylistUrls(body, url), kind: "master", sequence, url } :
+                { kind: "media", live: isLiveMediaPlaylist(body), sequence, url };
+            onPlaylist(playlist);
+        }
+        catch (error) {
+            LOG.debug(logCategory, "Could not fetch .m3u8 body: %s.", String(error));
+        }
+    };
+    const tabObserver = await observeTabResponses(page, {
+        onResponse: (response) => { void handleResponse(response.url); }
+    });
+    if (!tabObserver) {
+        return null;
+    }
+    LOG.debug(logCategory, "HLS playlist observer installed.");
+    // Reports the most recently assigned wire-arrival ordinal (0 before any observation). Consumers stamp an epoch against this so observations that arrive after
+    // the stamp read as post-epoch, without racing the in-flight body-fetch deliveries that would arrive out of order under delivery-time ordering.
+    const currentSequence = () => sequenceCounter;
+    const dispose = () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        tabObserver.dispose();
+        seenUrls.clear();
+    };
+    return { currentSequence, dispose, [Symbol.dispose]: dispose };
+}
+//# sourceMappingURL=hlsPlaylistObserver.js.map

package/dist/browser/hlsPlaylistObserver.js.map

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

package/dist/browser/index.d.ts

@@ -2,6 +2,15 @@ import type { Browser, LaunchOptions, Page } from "puppeteer-core";
 import { clearLoginState, isLoginModeActive } from "./login.ts";
 import { getStream } from "puppeteer-stream";
 import type { Nullable } from "../types/index.ts";
+import type { ProcessInfo } from "../utils/index.ts";
+type CaptureProbe = (browser: Browser) => Promise<void>;
+/**
+ * Injects the capture-readiness probe used as the capability tier of the launch gate. Called once from streaming/setup.ts at module load (which always precedes any
+ * launch, since the streaming layer is imported during server startup). Separating the wiring from the call keeps browser/index.ts free of a streaming-layer import.
+ * @param probe - The probe to run against a freshly-launched browser; it resolves when the browser can capture and rejects otherwise (or exits the process for the
+ *   unrecoverable stale-mutex case).
+ */
+export declare function setCaptureProbe(probe: CaptureProbe): void;
 /**
  * Returns true if graceful shutdown is in progress.
  */
@@ -11,7 +20,9 @@ export declare function isGracefulShutdown(): boolean;
  */
 export declare function setGracefulShutdown(value: boolean): void;
 export { clearLoginState, isLoginModeActive };
-export { type LoginStatus, endLoginMode, getLoginPage, getLoginStatus, startLoginMode } from "./login.ts";
+export type { LoginStatus } from "./login.ts";
+export { endLoginMode, getLoginPage, getLoginStatus, setLoginModeEndObserver, startLoginMode } from "./login.ts";
+export { BrowserSupersededError, BrowserUnavailableError } from "./browserSupervisor.ts";
 /**
  * Computes the current system status and emits it to SSE subscribers. Called when browser state changes significantly or when streams are added/removed.
  */
@@ -23,8 +34,12 @@ export declare function emitCurrentSystemStatus(): Promise<void>;
  * Each registered page receives a unique ID that persists for the page's lifetime. This ID is used for comparison and staleness tracking, avoiding potential
  * issues with Page object reference identity.
  * @param page - The Puppeteer Page to register.
+ * @param options - Registration options. Set inFlightSetup when stream setup owns the page but has not yet recorded that ownership in the stream registry, so the
+ *   stale page cleanup never closes a page whose stream is still being established.
  */
-export declare function registerManagedPage(page: Page): void;
+export declare function registerManagedPage(page: Page, options?: {
+    inFlightSetup?: boolean;
+}): void;
 /**
  * Unregisters a page from PrismCast's management. This should be called when a page is being closed intentionally (during stream cleanup). Unregistering prevents the
  * stale page cleanup from racing with intentional page closure.
@@ -41,30 +56,38 @@ export declare function unregisterManagedPage(page: Page): void;
  */
 export declare function ensureDataDirectory(): Promise<void>;
 /**
- * Ensures a clean slate for browser launch by terminating any stale Chrome processes and removing orphaned profile lock files. Chrome locks its profile directory
- * while running, and if a previous instance crashed without releasing the lock, we cannot launch a new browser with the same profile. This function uses the
- * saved Chrome PID to find and terminate the process via process.kill(), then polls for exit using signal 0. This approach is fully cross-platform - it does not
- * rely on Unix-only tools like pkill or pgrep.
+ * Identifies Chrome processes that this PrismCast instance is responsible for terminating. The filter has two stages: command-line discovery (anything using
+ * our profile directory) followed by ownership verification (we spawned it, or its parent is no longer alive). The ownership stage is structural - we do not
+ * rely on an in-memory flag; the parent-child relationship in the OS process table IS the ownership proof, which means this function is safe to call from any
+ * code path, including from a rejected-duplicate startup's exit handler.
+ *
+ * Why ownership matters. A duplicate PrismCast that the instance guard rejects must NOT signal Chrome that belongs to the legitimate holder. Process-table
+ * discovery lets the OS itself tell us who owns what: a Chrome whose ppid is a live unrelated PID belongs to that parent, not to us.
+ * @param processes - The current process table snapshot.
+ * @param profileDir - The Chrome user-data-dir to match against.
+ * @param ownPid - The current process's PID (anything whose parent is us is ours to kill).
+ * @param isProcessAlive - Predicate that returns true when the given PID is currently a live process. Injected so tests do not depend on real PIDs.
+ * @returns The PIDs to terminate, in process-table order.
+ */
+export declare function findChromeProcessesUsingProfile(processes: readonly ProcessInfo[], profileDir: string, ownPid: number, isProcessAlive: (pid: number) => boolean): number[];
+/**
+ * Ensures a clean slate for browser launch by terminating any stale Chrome processes and removing orphaned profile lock files. Chrome locks its profile
+ * directory while running; if a previous instance crashed without releasing the lock, we cannot launch a new browser with the same profile. Discovery is done
+ * via the OS process table (utils/processInspector) and filtered to Chrome processes using our profile directory whose ownership belongs to us - either because
+ * we spawned them (ppid === process.pid) or because their parent is no longer alive (orphaned from a previous instance).
  *
  * The termination strategy escalates from SIGTERM to SIGKILL. SIGTERM is sent first, giving Chrome up to 5 seconds to flush its profile databases (LevelDB,
  * extension state, session storage) and exit cleanly. If Chrome does not exit, SIGKILL is sent as a fallback. This escalation is critical when called from the
- * process exit handler - Chrome may be running normally (e.g., after a capture probe timeout), and an immediate SIGKILL would corrupt its profile databases,
+ * process exit handler: Chrome may be running normally (e.g., after a capture probe timeout) and an immediate SIGKILL would corrupt its profile databases,
  * poisoning the Docker volume for subsequent container restarts.
  *
- * If no PID is available (first run or clean shutdown where the PID file was already removed), process killing is skipped entirely and only lock file cleanup
- * runs. When a PID file does exist but the process is gone (Docker restart with a mounted volume - the PID belongs to the previous container's PID namespace),
- * process.kill() throws ESRCH, which is caught gracefully.
+ * The ownership filter makes this function safe to call from any context, including a rejected-duplicate startup's exit handler: a duplicate that never
+ * spawned Chrome will find nothing matching its ownership criteria and signal nothing.
  *
- * This is called at startup before launching the browser and from the process exit handler as a crash recovery fallback. It's safe to call even when no stale
- * processes or files exist.
+ * Called at startup before launching the browser and from the process exit handler as a crash recovery fallback. Safe to call when no stale processes or files
+ * exist - the discovery and lock-file cleanup are both no-ops in the empty case.
  */
 export declare function killStaleChrome(): void;
-/**
- * Returns whether this process has taken ownership of Chrome cleanup by running killStaleChrome() during startup. Used by the exit handler to avoid killing
- * Chrome that belongs to another running PrismCast instance.
- * @returns True if killStaleChrome() has run in this process.
- */
-export declare function canCleanupChrome(): boolean;
 /**
  * Locates the Google Chrome executable on the system. The CHROME_BIN environment variable takes precedence, allowing operators to specify a non-standard
  * installation. Otherwise, we search common installation paths across macOS, Linux, and Windows.
@@ -84,15 +107,27 @@ export declare function getExecutablePath(): string;
  */
 export declare function buildLaunchOptions(): LaunchOptions;
 /**
- * Provides access to the shared browser instance, launching one if needed. The browser is a shared resource used by all streaming sessions. This function handles:
+ * Invalidates a specific browser that is still connected but can no longer capture - a mid-life capture death that no "disconnected" event would surface. This is the
+ * single recovery action generalized to the alive-but-incapable case: relinquish readiness and terminate the browser's streams (exactly as a disconnect does),
+ * then additionally close the still-running Chrome so a leaked process is not left behind. The lifecycle is already absent after relinquish, so the next request
+ * relaunches a fresh, gate-verified browser through the supervisor. Exported for the streaming layer's passive mid-life detector to call once its probe confirms the
+ * browser cannot capture. noteReadinessLost stays internal: callers signal intent through this function, never the supervisor directly.
  *
- * - Returning the existing browser if it's still connected
- * - Launching a new browser if none exists or the previous one disconnected
- * - Serializing concurrent callers so only one launch occurs at a time
- * - Waiting for the puppeteer-stream extension to initialize
- * - Setting up disconnect handlers for crash recovery
- * @returns The browser instance.
- * @throws If the browser cannot be launched.
+ * The caller passes the exact instance it verified, and we invalidate only if it is still the published browser. The detector's probe runs in the background for
+ * seconds, during which the verified browser could have disconnected and been replaced by a fresh relaunch; without this identity guard we would tear down that
+ * new, healthy browser on the strength of a probe against the old, dead one.
+ * @param browser - The specific browser instance the caller verified as unable to capture.
+ * @param reason - A short description of why the browser is being invalidated, for the alarm log.
+ */
+export declare function invalidateBrowser(browser: Browser, reason: string): Promise<void>;
+/**
+ * Provides access to the capture-ready browser, launching one if needed. This is the single gated entry point for all browser access: it delegates to the
+ * supervisor's acquire(), which returns the ready browser, joins an in-flight launch (single-flight, so concurrent callers never contend on Chrome's profile lock),
+ * lazily launches when absent, or - while the relaunch governor is cooling after repeated failures - rejects fast with a BrowserUnavailableError WITHOUT spawning
+ * Chrome (the loop bound). The launch it drives runs the readiness gate, so a returned browser is verified capture-ready, not merely connected.
+ * @returns The capture-ready browser instance.
+ * @throws BrowserUnavailableError while the governor is cooling, BrowserSupersededError if an in-flight launch was abandoned by a readiness-loss, or the underlying
+ *   launch error when a launch attempt fails.
  */
 export declare function getCurrentBrowser(): Promise<Browser>;
 /**
@@ -121,23 +156,14 @@ export declare function isBrowserConnected(): boolean;
  */
 export declare function minimizeBrowserWindow(): Promise<void>;
 /**
- * Gets all open browser pages (tabs). This is used by the health check endpoint to report page count and by stale page cleanup to find orphaned pages.
+ * Gets all open browser pages (tabs). This is used by the health check endpoint to report page count.
  * @returns Array of pages, or empty array if the browser is not connected.
  */
 export declare function getBrowserPages(): Promise<Page[]>;
 /**
- * Closes the browser and cleans up resources. This is called during graceful shutdown to ensure Chrome exits cleanly. After this call, the browser reference is
- * cleared and any subsequent stream requests will launch a fresh browser.
- *
- * Chrome termination uses Puppeteer's ChildProcess handle and its `exit` event for detection:
- *
- * - browserRef.close() sends CDP Browser.close and waits for WebSocket teardown, which hangs 3-5 seconds even after Chrome exits.
- * - browserRef.disconnect() drops the WebSocket instantly but orphans Chrome as a Node child process, creating a zombie that process.kill(pid, 0) cannot detect.
- * - Synchronous polling (Atomics.wait) blocks the event loop, preventing Node from processing SIGCHLD to reap the child - Chrome becomes a zombie regardless
- *   of how SIGTERM was sent.
- *
- * Instead, we send SIGTERM through the ChildProcess handle and listen for the `exit` event. This keeps the event loop running so Node can process SIGCHLD and
- * reap Chrome properly. The exit event fires only after the process is fully reaped - no zombies, no polling, no event loop blocking.
+ * Closes the browser and cleans up resources during full server shutdown. After this call the supervisor reports absent and any subsequent stream request launches
+ * a fresh browser. It retires the current instance from the lifecycle (so an in-flight launch is superseded and the metadata is cleared), then delegates the actual
+ * Chrome teardown to closeBrowserInstance. The graceful-shutdown flag is set so handleBrowserDisconnect, if it runs for any reason, stays quiet.
  */
 export declare function closeBrowser(): Promise<void>;
 /**
@@ -146,7 +172,7 @@ export declare function closeBrowser(): Promise<void>;
  *
  * The cleanup uses a multi-stage filtering process:
  * 1. Only consider pages we created (in managedPageIds)
- * 2. Exclude pages associated with active streams
+ * 2. Exclude pages associated with active streams, and pages whose stream setup is still in flight
  * 3. Apply a grace period before closing (to handle race conditions)
  * 4. Preserve at least one page to keep the browser alive
  */
@@ -180,3 +206,4 @@ export declare function stopBrowserRestartChecking(): void;
  */
 export declare function prepareExtension(): Promise<void>;
 export { getStream };
+//# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"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"}