homebridge-plugin-utils 1.35.0 → 2.0.0

package/dist/ffmpeg/rtp.d.ts

@@ -1,205 +1,262 @@
+import type { HomebridgePluginLogging } from "../util.ts";
+import type { IpFamily } from "./dgram-util.ts";
 /**
- * RTP and RTCP packet demultiplexer and UDP port management for FFmpeg-based HomeKit livestreaming.
+ * Construction-time options for {@link RtpDemuxer}.
  *
- * This module supplies classes and helpers to support realtime streaming via FFmpeg in Homebridge and similar HomeKit environments. It enables the demultiplexing of RTP
- * and RTCP packets on a single UDP port, as required by HomeKit and RFC 5761, working around FFmpeg’s lack of native support for RTP/RTCP multiplexing. It also manages
- * the allocation and tracking of UDP ports for RTP and RTCP, helping prevent conflicts in dynamic, multi-session streaming scenarios.
+ * @property inactivityTimeout - Optional inactivity watchdog window, in milliseconds. The timer arms during construction (immediately after the bind call is issued)
+ *                               and re-arms on every received datagram. When the window lapses without traffic, the demuxer aborts with `HbpuAbortError("timeout")`.
+ *                               Omit to disable the watchdog entirely.
+ * @property inputPort         - Required. The UDP port to bind to. Typically a value previously reserved via {@link RtpPortAllocator.reserve}. Pass `0` to request
+ *                               kernel-assigned ephemeral allocation: the bind succeeds atomically against whichever port the kernel hands out, eliminating the
+ *                               reserve-then-rebind race that a separate reservation step would carry. The assigned port is then observable via
+ *                               {@link RtpDemuxer.inputPort} once {@link RtpDemuxer.ready} resolves.
+ * @property ipFamily          - Optional. `"ipv4"` or `"ipv6"`. Defaults to `"ipv4"`.
+ * @property log               - Optional logger. Used for debug tracing of socket lifecycle and heartbeat events, and for error-path diagnostics. The signal's reason
+ *                               on abort remains the authoritative notification channel; logging is a convenience for operators.
+ * @property rtcpPort          - Required. The destination UDP port (on the loopback interface) for classified RTCP packets. Typically FFmpeg's RTCP input port.
+ * @property rtpPort           - Required. The destination UDP port (on the loopback interface) for classified RTP packets. Typically FFmpeg's RTP input port. The
+ *                               heartbeat replay also targets this port - FFmpeg ignores the RTCP shape on its RTP input, but the arriving traffic keeps that input
+ *                               fed during quiet periods.
+ * @property signal            - Optional parent {@link AbortSignal} to compose with the demuxer's internal controller. When the parent aborts, the demuxer tears down.
  *
- * Key features:
- *
- * - Demultiplexes RTP and RTCP packets received on a single UDP port, forwarding them to the correct FFmpeg destinations for HomeKit livestream compatibility.
- * - Injects periodic heartbeat messages to keep two-way audio streams alive with FFmpeg’s strict timeout requirements.
- * - Dynamically allocates and reserves UDP ports for RTP/RTCP, supporting consecutive port pairing for correct FFmpeg operation.
- * - Event-driven architecture for integration with plugin or automation logic.
- *
- * Designed for plugin developers and advanced users implementing HomeKit livestreaming, audio/video bridging, or similar applications requiring precise RTP/RTCP handling
- * with FFmpeg.
- *
- * @module
+ * @category FFmpeg
  */
-import { EventEmitter } from "node:events";
-import type { HomebridgePluginLogging } from "../util.js";
+export interface RtpDemuxerInit {
+    inactivityTimeout?: number;
+    inputPort: number;
+    ipFamily?: IpFamily;
+    log?: HomebridgePluginLogging;
+    rtcpPort: number;
+    rtpPort: number;
+    signal?: AbortSignal;
+}
 /**
- * Utility for demultiplexing RTP and RTCP packets on a single UDP port for HomeKit compatibility.
+ * Signal-driven RTP/RTCP demultiplexer with FFmpeg keepalive heartbeat.
  *
- * FFmpeg does not support multiplexing RTP and RTCP data on a single UDP port (RFC 5761) and HomeKit requires this for livestreaming. This class listens on a UDP port
- * and demultiplexes RTP and RTCP traffic, forwarding them to separate RTP and RTCP ports as required by FFmpeg.
+ * The class owns one bound UDP socket. Inbound datagrams are classified by an internal {@link RtpPacketParser} and forwarded through the same socket to the configured
+ * `rtpPort` (RTP-classified) or `rtcpPort` (RTCP-classified) on the loopback interface. Sharing the bound socket between receive and send gives the relay two
+ * load-bearing properties:
  *
- * Credit to [dgreif](https://github.com/dgreif), [brandawg93](https://github.com/brandawg93), and [Sunoo](https://github.com/Sunoo) for foundational ideas and
- * collaboration.
+ *   1. **Source-endpoint symmetry.** Every forwarded datagram leaves the bound socket with source = `loopback:inputPort`. Because the demuxer holds an exclusive
+ *      kernel bind on that port, no other non-root process can spoof that source endpoint - downstream receivers (typically FFmpeg) can therefore enforce source
+ *      filtering against locally-injected traffic without coordinating ephemeral allocations with the demuxer.
+ *   2. **Minimized bound-port footprint.** Exactly one kernel-tracked socket exists per demuxer instance; a dual-socket design would bind a second ephemeral port for
+ *      the duration of the session, expanding the attack surface and the kernel-resource count for no architectural benefit.
+ *
+ * A self-rearming {@link Watchdog} replays the last observed RTCP packet to `rtpPort` whenever the gap between inbound RTCP arrivals exceeds the configured
+ * {@link RTCP_HEARTBEAT_INTERVAL}. The heartbeat is part of the demuxer's invariant contract - FFmpeg-bound two-way audio is the only use case that constructs this
+ * class, and that use case relies on the keepalive to keep inbound traffic arriving at FFmpeg's RTP input during legitimate quiet periods on the camera's audio
+ * backchannel. No FFmpeg input-timeout flag (`-timeout` / `rw_timeout`) is configured anywhere - the keepalive is a defensive guard against any FFmpeg-side idle
+ * handling of a quiet UDP/RTP input, not a timeout this code sets. The cadence is the single exported constant {@link RTCP_HEARTBEAT_INTERVAL}.
+ *
+ * An optional second {@link Watchdog} aborts the demuxer with `HbpuAbortError("timeout")` when no inbound traffic arrives within a caller-supplied window. Both
+ * watchdogs compose against the same lifetime signal, so disposal cleans them up uniformly.
  *
  * @example
  *
  * ```ts
- * // Create an RtpDemuxer to split packets for FFmpeg compatibility.
- * const demuxer = new RtpDemuxer("ipv4", 50000, 50002, 50004, log);
+ * await using demuxer = new RtpDemuxer({
+ *
+ *   inactivityTimeout: 5_000,
+ *   inputPort: audioIncomingPort,
+ *   ipFamily: "ipv4",
+ *   log,
+ *   rtcpPort: audioIncomingRtcpPort,
+ *   rtpPort: audioIncomingRtpPort,
+ *   signal: session.signal
+ * });
+ *
+ * try {
  *
- * // Close the demuxer when finished.
- * demuxer.close();
+ *   await demuxer.mediaReady;
+ * } catch {
+ *
+ *   // Demuxer aborted before any inbound RTP arrived; abandon the return-audio setup.
+ *   return;
+ * }
+ *
+ * // Media is now flowing - safe to launch the consuming FFmpeg process.
  * ```
  *
- * @see {@link https://tools.ietf.org/html/rfc5761 | RFC 5761}
- * @see {@link https://github.com/homebridge/homebridge-camera-ffmpeg | homebridge-camera-ffmpeg}
+ * @see RtpPacketParser
+ * @see RTCP_HEARTBEAT_INTERVAL
  *
  * @category FFmpeg
  */
-export declare class RtpDemuxer extends EventEmitter {
-    private heartbeatTimer?;
-    private heartbeatMsg?;
-    private _isRunning;
-    private log?;
-    private inputPort;
-    readonly socket: import("node:dgram").Socket;
+export declare class RtpDemuxer implements AsyncDisposable {
+    #private;
     /**
-     * Constructs a new RtpDemuxer for a specified IP family and port set.
-     *
-     * @param ipFamily         - The IP family: "ipv4" or "ipv6".
-     * @param inputPort        - The UDP port to listen on for incoming packets.
-     * @param rtcpPort         - The UDP port to forward RTCP packets to.
-     * @param rtpPort          - The UDP port to forward RTP packets to.
-     * @param log              - Logger instance for debug and error messages.
-     *
-     * @example
-     *
-     * ```ts
-     * const demuxer = new RtpDemuxer("ipv4", 50000, 50002, 50004, log);
-     * ```
+     * The composed abort signal representing this demuxer's lifetime. Aborts exactly once when the socket errors, the inactivity watchdog fires, the parent signal
+     * propagates, or {@link RtpDemuxer.abort} is called; the reason encoded on `signal.reason` names the cause.
      */
-    constructor(ipFamily: ("ipv4" | "ipv6"), inputPort: number, rtcpPort: number, rtpPort: number, log: HomebridgePluginLogging);
+    readonly signal: AbortSignal;
     /**
-     * Sends periodic heartbeat messages to the RTP port to keep the FFmpeg process alive.
+     * Promise that resolves once the underlying UDP socket has finished binding and entered its `"listening"` state. Rejects with `this.signal.reason` when the bind
+     * fails, the parent signal propagates, or any other abort path fires before the socket becomes ready.
      *
-     * This is necessary because FFmpeg times out input streams if it does not receive data for more than five seconds.
-     *
-     * @param port - The RTP port to send the heartbeat to.
+     * The unhandled-rejection tracker is suppressed via {@link markHandled} so consumers that never observe readiness (fire-and-forget demuxers) do not produce warnings;
+     * consumers that do observe rejection receive the same structured abort reason they would from `signal.reason`.
      */
-    private heartbeat;
+    readonly ready: Promise<void>;
     /**
-     * Closes the demuxer, its socket, and any heartbeat timers.
+     * Promise that resolves once the demuxer has forwarded its first RTP-classified packet - the application-level readiness milestone meaning "media is now flowing
+     * through the relay to the downstream consumer." Rejects with `this.signal.reason` if the demuxer aborts before any RTP packet arrives.
      *
-     * @example
+     * Pairs with {@link RtpDemuxer.ready} as a two-tier readiness model: `ready` resolves when the inbound socket has bound (network-level readiness); `mediaReady`
+     * resolves when classified RTP traffic has begun flowing (application-level readiness). The canonical gating pattern for two-way audio is "stand up the return-audio
+     * path, wait for inbound media before launching the consuming FFmpeg process":
      *
      * ```ts
-     * demuxer.close();
+     * try {
+     *   await demuxer.mediaReady;
+     * } catch {
+     *   // Demuxer aborted before any RTP arrived; abandon the return-audio setup.
+     *   return;
+     * }
+     * // Safe to launch the consuming FFmpeg process now that media is flowing.
      * ```
+     *
+     * The unhandled-rejection tracker is suppressed via {@link markHandled} so consumers that never observe this promise produce no warnings.
      */
-    close(): void;
+    readonly mediaReady: Promise<void>;
     /**
-     * Extracts the RTP payload type from a UDP packet.
-     *
-     * Used internally to distinguish RTP from RTCP messages.
-     *
-     * @param message - The UDP packet buffer.
+     * The UDP port the demuxer is bound to. For a specific-port construction (`init.inputPort` non-zero), this equals `init.inputPort` from the moment the constructor
+     * returns; for an ephemeral construction (`init.inputPort === 0`), the value is `0` until the kernel completes the bind, then the kernel-assigned port. Consumers
+     * that need the assigned ephemeral port `await demuxer.ready` before reading this property.
      *
-     * @returns The RTP payload type as a number.
+     * Reads from the cached projection of `socket.address().port` captured at the `"listening"` event so the value reflects what the kernel actually bound, not just what
+     * was requested. The two coincide for specific-port binds; they diverge for ephemeral binds where the requested value is `0` and the bound value is the kernel's pick.
+     */
+    get inputPort(): number;
+    /**
+     * `true` once `this.signal` has aborted. Derived from the signal; no independent state.
      */
-    private getPayloadType;
+    get aborted(): boolean;
     /**
-     * Determines if the provided UDP packet is an RTP message.
+     * `true` when the abort reason indicates a timeout. Matches both the canonical `HbpuAbortError("timeout")` emitted by the inactivity watchdog and the platform
+     * `TimeoutError` emitted by `AbortSignal.timeout()` - consumers discriminate on a single getter regardless of which code path produced the timeout. The discrimination
+     * logic lives in {@link isTimeoutReason} so this getter stays a one-line delegation and every resource class in the library shares one definition of "timeout."
+     */
+    get isTimedOut(): boolean;
+    /**
+     * Construct and bind a new RTP demuxer.
      *
-     * @param message - The UDP packet buffer.
+     * Socket binding happens synchronously as part of construction: by the time the constructor returns, the socket has been asked to bind on the configured port and
+     * the inactivity watchdog (if configured) is already armed. There is no separate `start()` step. The bind itself completes on a later turn; consumers that need to
+     * sequence work against bind completion `await demuxer.ready`.
      *
-     * @returns `true` if the packet is RTP, `false` if RTCP.
+     * @param init - Required init options. See {@link RtpDemuxerInit}.
      */
-    private isRtpMessage;
+    constructor(init: RtpDemuxerInit);
     /**
-     * Indicates if the demuxer is running and accepting packets.
+     * Abort the demuxer and tear it down. Defaults to `HbpuAbortError("shutdown")` when no reason is supplied; explicit reasons pass through unchanged.
      *
-     * @returns `true` if running, otherwise `false`.
+     * Safe to call more than once: subsequent calls are no-ops because the underlying signal only aborts once. Calling `abort()` after a natural error or watchdog
+     * timeout is also safe for the same reason.
      *
-     * @example
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}; platform errors (`TimeoutError`, `AbortError`) also interoperate by convention.
+     */
+    abort(reason?: unknown): void;
+    /**
+     * `AsyncDisposable` implementation. Aborts the demuxer (defaulting to `"shutdown"`) and awaits the socket's `"close"` event so the bound port is releasable by the
+     * time the surrounding `await using` scope's next statement runs. Safe to invoke repeatedly: subsequent disposals collapse onto the same `#closed` promise.
      *
-     * ```ts
-     * if(demuxer.isRunning) {
-     *   // Demuxer is active.
-     * }
-     * ```
+     * @returns A promise that resolves once the kernel has released the bound port.
      */
-    get isRunning(): boolean;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /**
- * Allocates and tracks UDP ports for RTP and RTCP to avoid port conflicts in environments with high network activity.
+ * Construction-time options for {@link RtpPortAllocator.reserve}.
+ *
+ * @property count    - Optional. The number of consecutive UDP ports to reserve. `1` yields a single port, `2` yields the reserved port plus the next port so FFmpeg's
+ *                      "RTP port N implies RTCP port N+1" convention is satisfied. Defaults to `1`.
+ * @property ipFamily - Optional. `"ipv4"` or `"ipv6"`. Defaults to `"ipv4"`.
+ * @property signal   - Optional caller {@link AbortSignal}. Cancels in-flight bind-retry attempts. If the signal aborts while `reserve()` is still looking for
+ *                      consecutive ports, the partially reserved port (if any) is released and the promise rejects with `signal.reason`.
  *
- * This utility class is used to find and reserve available UDP ports for demuxing FFmpeg streams or other network activities.
+ * @category FFmpeg
+ */
+export interface PortReservationInit {
+    count?: 1 | 2;
+    ipFamily?: IpFamily;
+    signal?: AbortSignal;
+}
+/**
+ * AsyncDisposable handle representing one or two reserved UDP ports.
+ *
+ * Ports are held exclusively against the {@link RtpPortAllocator}'s internal pool until `[Symbol.asyncDispose]` is invoked. Callers typically
+ * manage the lifetime with `await using` for scope-bound reservations, or by storing the handle on a session entry and disposing explicitly when the session ends.
+ *
+ * Disposal is idempotent: the first call releases the ports back to the allocator; subsequent calls are no-ops. This guarantees `await using` combined with an
+ * explicit dispose (for example, on an error path that releases early and then falls through the `using` block) does not double-release.
+ *
+ * @property count    - `1` or `2`. A two-port reservation guarantees `port` and `port + 1` are both reserved.
+ * @property ipFamily - `"ipv4"` or `"ipv6"`.
+ * @property port     - The first (and, for single-port reservations, only) reserved UDP port.
+ *
+ * @category FFmpeg
+ */
+export interface PortReservation extends AsyncDisposable {
+    readonly count: 1 | 2;
+    readonly ipFamily: IpFamily;
+    readonly port: number;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Registry that reserves consecutive UDP ports for FFmpeg-based RTP/RTCP sessions.
+ *
+ * The allocator itself is a plugin-singleton registry - it holds no OS resources of its own, only a `Set` of ports marked as in-use. Reservations are the scoped
+ * resource: each successful {@link RtpPortAllocator.reserve} call returns a {@link PortReservation} handle whose disposal releases the held ports back to the pool.
+ *
+ * The reservation bind-retry loop is signal-aware: passing `init.signal` to `reserve()` means an aborting parent signal cancels the pending reservation cleanly, even
+ * when the loop is in the middle of probing candidate ports.
  *
  * @example
  *
  * ```ts
- * const allocator = new RtpPortAllocator();
+ * // Scope-bound: the reservation releases automatically when the block exits.
+ * await using reservation = await allocator.reserve({ count: 2, signal: session.controller.signal });
+ * const rtpPort  = reservation.port;
+ * const rtcpPort = reservation.port + 1;
+ * // ...use rtpPort and rtcpPort for the duration of the session.
+ * ```
  *
- * // Reserve two consecutive ports for RTP and RTCP.
- * const rtpPort = await allocator.reserve("ipv4", 2);
+ * @example
  *
- * // Cancel reservation if not needed.
- * allocator.cancel(rtpPort);
+ * ```ts
+ * // Non-scoped: store the handle on a session entry and dispose explicitly later.
+ * const reservation = await allocator.reserve({ count: 2, signal: session.controller.signal });
+ * session.ports = reservation;
+ * // ...later:
+ * await session.ports[Symbol.asyncDispose]();
  * ```
  *
  * @category FFmpeg
  */
 export declare class RtpPortAllocator {
-    private portsInUse;
-    /**
-     * Instantiates a new RTP port allocator and tracker.
-     */
-    constructor();
-    /**
-     * Finds an available UDP port by attempting to bind a new socket.
-     *
-     * Loops until an available port not already marked as in use is found.
-     *
-     * @param ipFamily         - "ipv4" or "ipv6".
-     * @param port             - Optional. The port to try to bind to. If 0, selects a random port.
-     *
-     * @returns A promise resolving to the available port number, or `-1` on error.
-     */
-    private getPort;
+    #private;
     /**
-     * Internal method to reserve one or two consecutive UDP ports for FFmpeg or network use.
-     *
-     * If two ports are reserved, ensures they are consecutive for RTP and RTCP usage. Returns the first port in the sequence, or `-1` if we're unable to allocate.
-     *
-     * @param ipFamily         - Optional. "ipv4" or "ipv6". Defaults to "ipv4".
-     * @param portCount        - Optional. The number of consecutive ports to reserve (1 or 2). Defaults to 1.
-     * @param attempts         - Internal. The number of allocation attempts. Used for recursion.
+     * The number of UDP ports currently held by live {@link PortReservation} handles. Exposed for operational diagnostics - a plugin that surfaces "how many
+     * reservations are in flight right now" through a status endpoint can read this directly, and it is a useful signal for detecting leaks (a monotonically growing
+     * count across normal session cycles indicates a reservation is not being disposed).
      *
-     * @returns A promise resolving to the first reserved port, or `-1` if unavailable.
+     * @returns The number of reserved ports currently tracked by the allocator.
      */
-    private _reserve;
+    get reservedCount(): number;
     /**
-     * Reserves one or two consecutive UDP ports for FFmpeg or network use.
+     * Reserve one or two consecutive UDP ports.
      *
-     * If two ports are reserved, ensures they are consecutive for RTP and RTCP usage. Returns the first port in the sequence, or `-1` if we're unable to allocate.
+     * For a two-port reservation, the allocator first picks a random free port, then probes the next sequential port. If the sequential port is unavailable (already in
+     * the in-use set or rejected by the OS), the first port is released and the allocator retries from scratch, up to `RESERVE_MAX_ATTEMPTS` attempts.
      *
-     * @param ipFamily         - Optional. "ipv4" or "ipv6". Defaults to "ipv4".
-     * @param portCount        - Optional. The number of consecutive ports to reserve (1 or 2). Defaults to 1.
+     * @param init - Optional init options. See {@link PortReservationInit}.
      *
-     * @returns A promise resolving to the first reserved port, or `-1` if unavailable.
-     *
-     * @remarks FFmpeg currently lacks the ability to specify both the RTP and RTCP ports. FFmpeg always assumes, by convention, that when you specify an RTP port, the RTCP
-     * port is the RTP port + 1. In order to work around that challenge, we need to always ensure that when we reserve multiple ports for RTP (primarily for two-way audio
-     * use cases) that we we are reserving consecutive ports only.
-     *
-     * @example
-     *
-     * ```ts
-     * // Reserve a single port.
-     * const port = await allocator.reserve();
+     * @returns A {@link PortReservation} handle whose disposal releases the reserved ports.
      *
-     * // Reserve two consecutive ports for RTP/RTCP.
-     * const rtpPort = await allocator.reserve("ipv4", 2);
-     * ```
-     */
-    reserve(ipFamily?: ("ipv4" | "ipv6"), portCount?: (1 | 2)): Promise<number>;
-    /**
-     * Cancels and releases a previously reserved port, making it available for future use.
-     *
-     * @param port - The port number to release.
-     *
-     * @example
-     *
-     * ```ts
-     * allocator.cancel(50000);
-     * ```
+     * @throws The caller signal's abort reason, if the signal aborts before a reservation is obtained.
+     * @throws `RangeError` when `count` is anything other than `1` or `2`.
+     * @throws `Error` when no reservation could be obtained within the attempt budget.
      */
-    cancel(port: number): void;
+    reserve(init?: PortReservationInit): Promise<PortReservation>;
 }
+//# sourceMappingURL=rtp.d.ts.map