prismcast 1.13.0 → 1.14.0

package/dist/app.d.ts

@@ -1,9 +1,22 @@
-import type { IncomingMessage } from "node:http";
-import type { Nullable } from "./types/index.ts";
+import type { ChangeRejection, ConfigChange } from "./config/reactivity.ts";
+import type { Config, LoggingConfig, Nullable } from "./types/index.ts";
+import type { Express, RequestHandler } from "express";
+import type { IncomingMessage, Server } from "node:http";
+import type { Clock } from "homebridge-plugin-utils";
 import type { ParsedArgs } from "./index.ts";
+import type { StreamOptions } from "morgan";
 /**
- * Records a request's arrival time. Registered ahead of the logger so both readers of the elapsed time measure from the moment the request reached the app rather
- * than from whenever the logger happened to see it.
+ * Closes the main HTTP server, graceful shutdown's step for the listener the boot's tail bound. Connections are destroyed first because the status and log SSE
+ * streams (routes/streams.ts and routes/logs.ts) hold their sockets open with a heartbeat, and the close waits on every one of them; the CDP proxy's WebSocket
+ * clients have already closed themselves with 1001 in response to the browser disconnect shutdown awaits before this step. An in-flight request ends with the
+ * process, because the exit follows immediately. The server reference is taken and cleared before the close, so a close that runs again finds no server.
+ * @param clock - The clock the close bound runs on, the system clock in production and a test clock in a row that crosses the bound.
+ * @returns A promise that resolves once the server closes or its bound lapses, and at once when no server is bound.
+ */
+export declare function closeMainServer(clock?: Clock): Promise<void>;
+/**
+ * Records a request's arrival time. The request logger's middleware calls it as a request arrives, before handing the request to morgan, so every reader of the
+ * elapsed time measures from the request's arrival rather than from whenever morgan happened to see it.
  * @param req - The incoming request.
  * @param _res - The response, unused.
  * @param next - The next middleware in the chain.
@@ -40,6 +53,31 @@ export declare function skipInFilteredMode(request: {
     statusCode: number;
     url: string;
 }): boolean;
+/**
+ * Decides whether the request log skips a request at the given level: "none" skips every request, "all" logs every one, and "errors" and "filtered" apply their
+ * own rules. The switch is exhaustive, and no running level reaches its default arm, because every configuration the server builds corrects a level it does not
+ * recognize.
+ * @param options - The level in force, the elapsed milliseconds (null when unstamped), whether a Retry-After header is present, the response status, and the
+ *   request URL.
+ * @returns True when the request should not be logged.
+ */
+export declare function skipRequestLog(options: {
+    elapsedMs: Nullable<number>;
+    hasRetryAfter: boolean;
+    level: LoggingConfig["httpLogLevel"];
+    statusCode: number;
+    url: string;
+}): boolean;
+/**
+ * Builds the request logger: one morgan logger behind one middleware, each reading the configured HTTP log level per request, so a saved level applies from the
+ * next request. Whether a request is observed is decided when it arrives: under "none" the middleware hands it on at once, at the cost of one property read, and
+ * the request is never stamped or seen by morgan. Whether an observed request is logged is decided by the level in force when it finishes, because morgan makes
+ * its skip decision as the response completes. So a long-lived stream that arrived under "none" is never logged, and one that arrived under another level is
+ * judged by the level in force at its close.
+ * @param stream - The stream morgan writes each line to.
+ * @returns The request-logging middleware.
+ */
+export declare function createRequestLogger(stream: StreamOptions): RequestHandler;
 /**
  * Releases the server instance slot if this process owns it. Called during graceful shutdown and from the process exit handler. The ownership check is
  * structural (release() reads the on-disk record and refuses to remove a file belonging to a different PID), so a rejected-duplicate startup whose exit
@@ -48,8 +86,52 @@ export declare function skipInFilteredMode(request: {
  */
 export declare function releaseInstanceSlot(): void;
 /**
- * Initializes and starts the HTTP server. Before accepting connections, we validate configuration, clean up stale Chrome processes, and warm up the browser
- * instance.
+ * Applies a saved log size limit to the open log file. The composition root owns the handler because it wires the file logger, and the file logger, a utility
+ * the configuration layer builds on, cannot import that layer back. The limit comes from the candidate, because the reconcile commits CONFIG only after its
+ * handlers run. The size check is started rather than awaited: the save needs only the limit, which the setter assigns before its first await, so a save never
+ * waits on log-file I/O.
+ * @param _changes - The change to the log size limit; the candidate carries the limit, so the handler reads that instead.
+ * @param next - The candidate running configuration.
+ * @returns No rejections.
+ */
+export declare function applyLogSizeChanges(_changes: readonly ConfigChange[], next: Readonly<Config>): Promise<readonly ChangeRejection[]>;
+export interface BootServicesDeps {
+    readonly attachCdpUpgradeHandler: (server: Server) => void;
+    readonly buildApp: () => Express;
+    readonly isGracefulShutdown: () => boolean;
+    readonly listenMainServer: (app: Express) => Promise<Server>;
+    readonly startBackgroundServices: () => void;
+    readonly startHdhrServer: () => Promise<void>;
+}
+export declare const defaultBootServicesDeps: BootServicesDeps;
+/**
+ * Arms what the server runs for the life of the process, in order: the background services, the Express application and its listener, the CDP upgrade handler,
+ * and HDHomeRun emulation. The signal handlers are installed well before the boot reaches this point, so a signal can run shutdown against a background stack, a
+ * listener and an HDHomeRun surface that do not exist yet, and a boot that armed them afterwards would leave them running in a process that is shutting down. The
+ * boot therefore reads the shutdown state before it arms the stack, and again after the bind, the await a later arming step follows, and arms nothing once
+ * shutdown has begun. The check after the bind decides only where that await yields to the event loop - a hostname host's lookup - and elsewhere the first check
+ * decides. The limit is an await already in flight when the signal lands: it completes, and the process exit at the end of shutdown ends whatever it started.
+ * @param deps - The boot's steps: the real ones in production, and recording stubs in a test.
+ * @returns A promise that resolves once the boot's tail completes or stops for a shutdown, and rejects when the build or the bind fails.
+ */
+export declare function startBootServices(deps?: BootServicesDeps): Promise<void>;
+/**
+ * Initializes the server and starts it: we validate configuration, clean up stale Chrome processes and warm up the browser instance, then hand the rest of the
+ * boot to startBootServices, which arms the background services, builds the Express application and binds its listener, and starts HDHomeRun emulation.
  * @param parsedArgs - Parsed command-line arguments containing flags and override values.
  */
 export declare function startServer(parsedArgs: ParsedArgs): Promise<void>;
+export interface StartupFailureDeps {
+    readonly exit: (code: number) => void;
+    readonly isGracefulShutdown: () => boolean;
+}
+export declare const defaultStartupFailureDeps: StartupFailureDeps;
+/**
+ * Ends a startup that failed, the entry point's catch for startServer. A failure that lands once shutdown has begun is one shutdown caused, such as the browser
+ * warm-up's launch that shutdown superseded, so it is shutdown's to end: shutdown owns the exit, and a second exit racing it here would cut its drain short with the
+ * wrong code, so the handler logs the superseded startup and leaves the exit to it. The entry point's unhandled-rejection handler reads the same state for the
+ * same reason. Any other failure is fatal, and the process exits with a failure code so a process manager sees it.
+ * @param error - The error startServer rejected with.
+ * @param deps - The shutdown reader and the exit: the real ones in production, and recording stubs in a test.
+ */
+export declare function handleStartupFailure(error: unknown, deps?: StartupFailureDeps): void;