prismcast 1.10.2 → 1.11.0

package/dist/hdhr/protocol.js

@@ -0,0 +1,264 @@
+import { crc32 } from "node:zlib";
+// Packet type codes from libhdhomerun's hdhomerun_pkt.h. The protocol uses a single GETSET_REQ code (0x0004) for both Get and Set requests; the two are
+// distinguished by the presence or absence of a value TLV in the payload, not by a separate packet code. Discover/Get are the request-reply pairs PrismCast
+// actually answers; Upgrade requests fall through to the transport layer's unsupported handler. The PACKET_UPGRADE_REPLY code is included for completeness
+// even though PrismCast never receives nor emits upgrade replies.
+export const PACKET_DISCOVER_REQUEST = 0x0002;
+export const PACKET_DISCOVER_REPLY = 0x0003;
+export const PACKET_GET_REQUEST = 0x0004;
+export const PACKET_GET_REPLY = 0x0005;
+export const PACKET_UPGRADE_REQUEST = 0x0006;
+export const PACKET_UPGRADE_REPLY = 0x0007;
+// TLV tag identifiers. The numeric values are part of the wire protocol; do not renumber. Discover packets carry the device-class TLVs (0x01, 0x02, 0x10, 0x2A);
+// Get/Set packets carry the name/value/error TLVs (0x03, 0x04, 0x05). The tags match the canonical values published in libhdhomerun's hdhomerun_pkt.h - there
+// is no standard tag for a discrete lineup URL, so clients derive it by appending "/lineup.json" to the base URL.
+export const TLV_DEVICE_TYPE = 0x01;
+export const TLV_DEVICE_ID = 0x02;
+export const TLV_GETSET_NAME = 0x03;
+export const TLV_GETSET_VALUE = 0x04;
+export const TLV_ERROR = 0x05;
+export const TLV_TUNER_COUNT = 0x10;
+export const TLV_BASE_URL = 0x2A;
+// Wildcard sentinel for Discover requests. Clients that want any device send these to filter neither by type nor by id.
+export const HDHR_WILDCARD = 0xFFFFFFFF;
+/**
+ * Parses an incoming packet. Returns null when the packet is structurally malformed (too short, length mismatch, bad CRC). Otherwise returns the discriminated
+ * record describing the packet's intent. Unknown TLVs within a known packet type are silently skipped - the protocol allows extension TLVs that PrismCast does
+ * not understand.
+ * @param buf - The raw datagram bytes.
+ * @returns The parsed packet or null on malformed input.
+ */
+export function parsePacket(buf) {
+    // Minimum packet size is the 4-byte header plus the 4-byte CRC. A datagram smaller than that cannot encode a valid packet.
+    if (buf.length < 8) {
+        return null;
+    }
+    const packetType = buf.readUInt16BE(0);
+    const payloadLength = buf.readUInt16BE(2);
+    const expectedSize = 4 + payloadLength + 4;
+    // A packet whose declared length does not match the datagram size is corrupt - either fragmentation or a malformed sender.
+    if (buf.length !== expectedSize) {
+        return null;
+    }
+    // The CRC covers the header and payload but not the CRC field itself. We compute over slice(0, header + payload) and compare to the trailing little-endian u32.
+    const computedCrc = crc32(buf.subarray(0, 4 + payloadLength));
+    const declaredCrc = buf.readUInt32LE(4 + payloadLength);
+    if (computedCrc !== declaredCrc) {
+        return null;
+    }
+    const payload = buf.subarray(4, 4 + payloadLength);
+    const tlvs = decodeTlvs(payload);
+    if (tlvs === null) {
+        return null;
+    }
+    switch (packetType) {
+        case PACKET_DISCOVER_REQUEST: {
+            // Discover requests may include device-type and device-id filters. Both default to wildcard when missing so a request with no filters matches everything.
+            const requestedDeviceType = readU32Tlv(tlvs, TLV_DEVICE_TYPE) ?? HDHR_WILDCARD;
+            const requestedDeviceId = readU32Tlv(tlvs, TLV_DEVICE_ID) ?? HDHR_WILDCARD;
+            return { requestedDeviceId, requestedDeviceType, type: "discover" };
+        }
+        case PACKET_GET_REQUEST: {
+            const name = readStringTlv(tlvs, TLV_GETSET_NAME);
+            if (name === null) {
+                return null;
+            }
+            const value = readStringTlv(tlvs, TLV_GETSET_VALUE);
+            // Get requests carry only a name; Set requests carry both a name and a value. The protocol uses the same 0x0004 packet type for both - the presence of
+            // the value TLV distinguishes them. This is unusual but documented in libhdhomerun's source.
+            if (value !== null) {
+                return { name, type: "set", value };
+            }
+            return { name, type: "get" };
+        }
+        default: {
+            return { packetType, type: "unsupported" };
+        }
+    }
+}
+/**
+ * Builds a Discover reply packet. The reply is short enough to fit in a single datagram even with all fields populated; the largest contributor is the base
+ * URL string which is typically under 50 bytes.
+ * @param fields - The device-identity values to serialize.
+ * @returns A complete wire-formatted packet ready to send via socket.send.
+ */
+export function buildDiscoverReply(fields) {
+    // Pre-compute each TLV so we can compose them in tag order. The wire order is conventional but not strictly required by the protocol - listing tags in
+    // ascending tag order matches real HDHomeRun reply traces and avoids client implementations that assume a specific order. TunerCount is encoded as an 8-bit
+    // value because real HDHR devices report it that way (real-world tuner counts fit in a byte; the wire format reflects that).
+    const tlvs = [
+        encodeU32Tlv(TLV_DEVICE_TYPE, fields.deviceType),
+        encodeU32Tlv(TLV_DEVICE_ID, fields.deviceId),
+        encodeU8Tlv(TLV_TUNER_COUNT, fields.tunerCount),
+        encodeStringTlv(TLV_BASE_URL, fields.baseUrl)
+    ];
+    return buildPacket(PACKET_DISCOVER_REPLY, Buffer.concat(tlvs));
+}
+/**
+ * Builds a Get reply packet carrying a name/value pair. Used when answering a known Get key with a real value.
+ * @param name - The Get key being answered (echoed back in the reply).
+ * @param value - The value returned for that key.
+ * @returns A complete wire-formatted packet.
+ */
+export function buildGetReply(name, value) {
+    const payload = Buffer.concat([
+        encodeStringTlv(TLV_GETSET_NAME, name),
+        encodeStringTlv(TLV_GETSET_VALUE, value)
+    ]);
+    return buildPacket(PACKET_GET_REPLY, payload);
+}
+/**
+ * Builds a Get reply packet carrying an error string. Used when answering a Get for an unknown key or rejecting a Set or Upgrade request. Real HDHomeRun
+ * firmware uses "ERROR: ..." prose for the error TLV; we follow the same convention so client error messages remain familiar to operators.
+ * @param name - The key being answered (echoed back).
+ * @param error - The error string. Should begin with "ERROR: " per HDHR convention.
+ * @returns A complete wire-formatted packet.
+ */
+export function buildErrorReply(name, error) {
+    const payload = Buffer.concat([
+        encodeStringTlv(TLV_GETSET_NAME, name),
+        encodeStringTlv(TLV_ERROR, error)
+    ]);
+    return buildPacket(PACKET_GET_REPLY, payload);
+}
+/**
+ * Composes a complete packet: 4-byte header, payload, 4-byte little-endian CRC of header + payload. The CRC is computed last so the packet body is valid bytes
+ * before sealing.
+ * @param packetType - The packet type code.
+ * @param payload - The TLV-encoded payload bytes.
+ * @returns The complete packet.
+ */
+function buildPacket(packetType, payload) {
+    const header = Buffer.alloc(4);
+    header.writeUInt16BE(packetType, 0);
+    header.writeUInt16BE(payload.length, 2);
+    const body = Buffer.concat([header, payload]);
+    const checksum = Buffer.alloc(4);
+    checksum.writeUInt32LE(crc32(body), 0);
+    return Buffer.concat([body, checksum]);
+}
+/**
+ * Encodes a 32-bit unsigned integer TLV. The four-byte value is written big-endian to match the wire protocol.
+ * @param tag - The TLV tag.
+ * @param value - The unsigned 32-bit value.
+ * @returns The TLV bytes (tag + length + value).
+ */
+function encodeU32Tlv(tag, value) {
+    const buf = Buffer.alloc(6);
+    buf.writeUInt8(tag, 0);
+    buf.writeUInt8(4, 1);
+    buf.writeUInt32BE(value >>> 0, 2);
+    return buf;
+}
+/**
+ * Encodes an 8-bit unsigned integer TLV. Used for fields like tuner count whose values fit in a single byte and are documented as one-byte on the wire.
+ * @param tag - The TLV tag.
+ * @param value - The unsigned 8-bit value.
+ * @returns The TLV bytes (tag + length + value).
+ */
+function encodeU8Tlv(tag, value) {
+    const buf = Buffer.alloc(3);
+    buf.writeUInt8(tag, 0);
+    buf.writeUInt8(1, 1);
+    buf.writeUInt8(value & 0xFF, 2);
+    return buf;
+}
+/**
+ * Encodes a string TLV. The string is serialized as UTF-8 with a trailing NUL byte (HDHomeRun convention), so a 10-character string occupies 11 bytes of value.
+ * Values longer than 127 bytes use the two-byte length encoding; PrismCast never emits values that long, but the encoder remains correct if a future field
+ * exceeds the threshold.
+ * @param tag - The TLV tag.
+ * @param value - The string value.
+ * @returns The TLV bytes (tag + length + UTF-8 bytes + NUL).
+ */
+function encodeStringTlv(tag, value) {
+    const bodyBytes = Buffer.from(value + "\0", "utf8");
+    const length = bodyBytes.length;
+    // Length under 128 fits in the single-byte form. The two-byte form is included for correctness even though our outgoing values never need it.
+    if (length < 128) {
+        const buf = Buffer.alloc(2 + length);
+        buf.writeUInt8(tag, 0);
+        buf.writeUInt8(length, 1);
+        bodyBytes.copy(buf, 2);
+        return buf;
+    }
+    // Two-byte length form: first byte has high bit set carrying low 7 bits of length; second byte carries the high 8 bits. Little-endian.
+    const buf = Buffer.alloc(3 + length);
+    buf.writeUInt8(tag, 0);
+    buf.writeUInt8((length & 0x7F) | 0x80, 1);
+    buf.writeUInt8((length >>> 7) & 0xFF, 2);
+    bodyBytes.copy(buf, 3);
+    return buf;
+}
+/**
+ * Decodes a TLV-encoded payload into a list of records. Returns null when the payload is structurally malformed (a length field that overruns the remaining
+ * bytes). Unknown tags pass through; the caller decides whether to use them.
+ * @param payload - The raw payload bytes (header and CRC already stripped).
+ * @returns The decoded TLVs or null on malformed input.
+ */
+function decodeTlvs(payload) {
+    const tlvs = [];
+    let offset = 0;
+    while (offset < payload.length) {
+        // Need at least tag + first length byte to make progress; anything shorter is truncation.
+        if ((offset + 2) > payload.length) {
+            return null;
+        }
+        const tag = payload.readUInt8(offset);
+        const lengthByte = payload.readUInt8(offset + 1);
+        let length;
+        let headerSize;
+        // High bit set on the length byte signals the two-byte length form; clear means single-byte length 0-127.
+        if ((lengthByte & 0x80) !== 0) {
+            if ((offset + 3) > payload.length) {
+                return null;
+            }
+            length = (lengthByte & 0x7F) | (payload.readUInt8(offset + 2) << 7);
+            headerSize = 3;
+        }
+        else {
+            length = lengthByte;
+            headerSize = 2;
+        }
+        const valueStart = offset + headerSize;
+        const valueEnd = valueStart + length;
+        if (valueEnd > payload.length) {
+            return null;
+        }
+        tlvs.push({ tag, value: payload.subarray(valueStart, valueEnd) });
+        offset = valueEnd;
+    }
+    return tlvs;
+}
+/**
+ * Looks up a 32-bit unsigned integer TLV by tag. Returns null when the tag is missing or its value is not exactly four bytes. The big-endian read matches the
+ * wire format.
+ * @param tlvs - The decoded TLV list.
+ * @param tag - The tag to look up.
+ * @returns The 32-bit value or null.
+ */
+function readU32Tlv(tlvs, tag) {
+    const entry = tlvs.find((t) => (t.tag === tag));
+    if (entry?.value.length !== 4) {
+        return null;
+    }
+    return entry.value.readUInt32BE(0);
+}
+/**
+ * Looks up a string TLV by tag. Returns null when the tag is missing. The trailing NUL byte (HDHomeRun convention) is stripped before decoding so callers
+ * receive the bare string.
+ * @param tlvs - The decoded TLV list.
+ * @param tag - The tag to look up.
+ * @returns The string value or null.
+ */
+function readStringTlv(tlvs, tag) {
+    const entry = tlvs.find((t) => (t.tag === tag));
+    if (!entry) {
+        return null;
+    }
+    // Strip a single trailing NUL if present; senders that omit the NUL still produce a valid string. .at(-1) returns undefined on an empty buffer, so the zero-
+    // length case is handled by the strict-equality check without a separate length guard.
+    const trimmed = (entry.value.at(-1) === 0) ? entry.value.subarray(0, -1) : entry.value;
+    return trimmed.toString("utf8");
+}
+//# sourceMappingURL=protocol.js.map

package/dist/hdhr/protocol.js.map

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

package/dist/hdhr/tunerState.d.ts

@@ -0,0 +1,24 @@
+import type { Nullable } from "../types/index.ts";
+/**
+ * Slot-indexed projection of stream state. Every configured tuner slot produces one entry; active slots carry channel and client info while idle slots carry
+ * only the resource name. Wire-format conversion (to JSON for HTTP, to plain strings or space-delimited key=value strings for UDP Get replies) happens in
+ * the consumer.
+ */
+export interface TunerState {
+    readonly active: boolean;
+    readonly channelName: Nullable<string>;
+    readonly channelNumber: Nullable<number>;
+    readonly clientAddress: Nullable<string>;
+    readonly resource: string;
+    readonly slot: number;
+}
+/**
+ * Returns the current slot-indexed projection of stream state. Active streams (sorted by stream id) take the first N slots; remaining slots through the
+ * configured maxConcurrentStreams are returned as idle entries. The array length is max(maxConcurrentStreams, activeStreams): in the normal case it equals
+ * maxConcurrentStreams, but if the active stream count exceeds the configured limit - reachable by lowering maxConcurrentStreams while streams are running,
+ * since live streams are not terminated by a limit change - every active stream is still reported and there are simply no idle entries. We never drop an
+ * active tuner and never report fewer slots than there are active streams, because a real HDHomeRun cannot have fewer tuners than it has active recordings.
+ * @returns Slot-indexed array of TunerState records.
+ */
+export declare function getTunerStates(): readonly TunerState[];
+//# sourceMappingURL=tunerState.d.ts.map

package/dist/hdhr/tunerState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunerState.d.ts","sourceRoot":"","sources":["../../src/hdhr/tunerState.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAKlD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAGzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAIzB,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAGvC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAGzC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAGzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,SAAS,UAAU,EAAE,CA+CtD"}

package/dist/hdhr/tunerState.js

@@ -0,0 +1,67 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * tunerState.ts: HDHomeRun tuner-slot state for PrismCast.
+ *
+ * Real HDHomeRun devices expose a fixed number of "tuner" slots indexed from zero. PrismCast does not have RF tuners but emulates the model: the configured
+ * maxConcurrentStreams becomes the slot count, and each active stream binds to the next free slot in stream-ID order. Two HDHR consumers need the same slot-
+ * indexed view of current state:
+ *
+ *   1. The HTTP /status.json endpoint serves it to monitoring dashboards (Home Assistant, Homepage) as a JSON array of HDHR-shaped tuner entries.
+ *   2. The UDP control plane on port 65001 serves it to clients that issue Get requests for /tuner<N>/channel, /tuner<N>/status, /tuner<N>/target, etc.
+ *
+ * This module is the single source of truth for the slot-indexed projection. It returns format-neutral TunerState records; each consumer formats them into the
+ * wire shape its protocol expects (JSON keys for HTTP, plain strings and space-delimited key=value pairs for UDP). Keeping the projection here means the
+ * channel-map merge logic, the fallback-to-stream-name handling, and the client-address normalization live in one place, so an HDHR feature gap or a
+ * refactor of the underlying registry surfaces in exactly one location.
+ */
+import { CONFIG } from "../config/index.js";
+import { buildChannelMap } from "./channelMap.js";
+import { getAllStreams } from "../streaming/registry.js";
+import { normalizeClientAddress } from "../utils/index.js";
+/**
+ * Returns the current slot-indexed projection of stream state. Active streams (sorted by stream id) take the first N slots; remaining slots through the
+ * configured maxConcurrentStreams are returned as idle entries. The array length is max(maxConcurrentStreams, activeStreams): in the normal case it equals
+ * maxConcurrentStreams, but if the active stream count exceeds the configured limit - reachable by lowering maxConcurrentStreams while streams are running,
+ * since live streams are not terminated by a limit change - every active stream is still reported and there are simply no idle entries. We never drop an
+ * active tuner and never report fewer slots than there are active streams, because a real HDHomeRun cannot have fewer tuners than it has active recordings.
+ * @returns Slot-indexed array of TunerState records.
+ */
+export function getTunerStates() {
+    const channelMap = buildChannelMap();
+    const channelByKey = new Map(channelMap.map((entry) => [entry.key, entry]));
+    const streams = getAllStreams().toSorted((a, b) => a.id - b.id);
+    // Slot count is the larger of the configured limit and the live active-stream count. Clamping to the configured limit would drop real active tuners from the
+    // projection when the operator lowers maxConcurrentStreams mid-stream; taking the max keeps every active stream visible and lets the idle-fill loop below be
+    // a no-op in the oversubscribed case rather than producing a negative range.
+    const tunerCount = Math.max(CONFIG.streaming.maxConcurrentStreams, streams.length);
+    const states = [];
+    // Active slots: one entry per running stream, in stream-id order. Channel info merges from the lineup with a fallback to stream.channelName.
+    for (const [slot, stream] of streams.entries()) {
+        const channelEntry = channelByKey.get(stream.info.storeKey);
+        const channelName = channelEntry?.name ?? stream.channelName ?? null;
+        const channelNumber = channelEntry ? channelEntry.number : null;
+        const clientAddress = stream.clientAddress ? normalizeClientAddress(stream.clientAddress) : null;
+        states.push({
+            active: true,
+            channelName,
+            channelNumber,
+            clientAddress,
+            resource: "tuner" + String(slot),
+            slot
+        });
+    }
+    // Idle slots fill the remaining capacity up to tunerCount. When oversubscribed (active streams exceed the configured limit) tunerCount equals the active
+    // count, so this loop runs zero times and the array is all-active - never a negative range, never a dropped tuner.
+    for (let slot = streams.length; slot < tunerCount; slot++) {
+        states.push({
+            active: false,
+            channelName: null,
+            channelNumber: null,
+            clientAddress: null,
+            resource: "tuner" + String(slot),
+            slot
+        });
+    }
+    return states;
+}
+//# sourceMappingURL=tunerState.js.map

package/dist/hdhr/tunerState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunerState.js","sourceRoot":"","sources":["../../src/hdhr/tunerState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AA6B3D;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAE5B,MAAM,UAAU,GAAG,eAAe,EAAE,CAAC;IACrC,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAE,CAAC,CAAC,CAAC;IAC9E,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAEhE,6JAA6J;IAC7J,6JAA6J;IAC7J,6EAA6E;IAC7E,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,oBAAoB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACnF,MAAM,MAAM,GAAiB,EAAE,CAAC;IAEhC,6IAA6I;IAC7I,KAAI,MAAM,CAAE,IAAI,EAAE,MAAM,CAAE,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QAEhD,MAAM,YAAY,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5D,MAAM,WAAW,GAAG,YAAY,EAAE,IAAI,IAAI,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC;QACrE,MAAM,aAAa,GAAG,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QAChE,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,sBAAsB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAEjG,MAAM,CAAC,IAAI,CAAC;YAEV,MAAM,EAAE,IAAI;YACZ,WAAW;YACX,aAAa;YACb,aAAa;YACb,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC;YAChC,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IAED,yJAAyJ;IACzJ,mHAAmH;IACnH,KAAI,IAAI,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,GAAG,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC;QAEzD,MAAM,CAAC,IAAI,CAAC;YAEV,MAAM,EAAE,KAAK;YACb,WAAW,EAAE,IAAI;YACjB,aAAa,EAAE,IAAI;YACnB,aAAa,EAAE,IAAI;YACnB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC;YAChC,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/hdhr/udp.d.ts

@@ -0,0 +1,43 @@
+import type { NetworkInterfaceInfo } from "node:os";
+import type { Nullable } from "../types/index.ts";
+export declare const HDHR_DISCOVERY_PORT = 65001;
+/**
+ * Options for UdpSurface.ensureUp. Tests pass an ephemeral port (0) so the kernel picks a free port; production passes the httpPortProvider so Discover replies
+ * advertise the real bound HTTP port.
+ */
+export interface UdpSurfaceOptions {
+    readonly bindAddress?: string;
+    readonly httpPortProvider?: () => Nullable<number>;
+    readonly port?: number;
+}
+/**
+ * A self-disposing HDHomeRun UDP discovery surface. The node owns exactly one responder socket and the captured HTTP-port provider, cycling the socket up and
+ * down via ensureUp/ensureDown as the controller reconciles CONFIG.hdhr. ensureDown is exposed as [Symbol.asyncDispose] so the surface composes with the rest of
+ * the resource-ownership tree; disposal closes the current socket but leaves the node reusable (a later ensureUp rebinds), because this is owner-bounded, not
+ * scope-bounded, disposal.
+ */
+export interface UdpSurface extends AsyncDisposable {
+    readonly boundPort: Nullable<number>;
+    ensureDown(): Promise<void>;
+    ensureUp(options?: UdpSurfaceOptions): Promise<boolean>;
+}
+/**
+ * Creates an HDHomeRun UDP discovery surface node. The returned object fully owns its socket; nothing outside the closure touches it. ensureUp/ensureDown are the
+ * cycling verbs the controller drives; [Symbol.asyncDispose] aliases ensureDown so the surface is a well-formed async-disposable resource.
+ * @returns A UdpSurface node.
+ */
+export declare function createUdpSurface(): UdpSurface;
+/**
+ * Selects the local IPv4 address that is reachable from the requester's subnet. Walks os.networkInterfaces, computes each interface's network address via its
+ * netmask, and returns the matching interface's address. Falls back to the first non-loopback IPv4 address when no subnet matches (typical on hosts whose
+ * routing crosses a layer-3 boundary). Returns "127.0.0.1" as the last resort - clients reaching us on loopback will use it; clients on the LAN that hit this
+ * branch will fail to reach back, but that scenario implies a misconfigured host where LAN advertising would not help anyway.
+ *
+ * Exposed (and parameterized over network interfaces) primarily for tests; the production call site uses os.networkInterfaces() directly via the default
+ * parameter.
+ * @param targetAddress - The requester's IPv4 address (from dgram rinfo).
+ * @param interfaces - Map of interface name to NetworkInterfaceInfo array (defaults to os.networkInterfaces()).
+ * @returns The selected local IPv4 address.
+ */
+export declare function selectLanAddress(targetAddress: string, interfaces?: NodeJS.Dict<NetworkInterfaceInfo[]>): string;
+//# sourceMappingURL=udp.d.ts.map

package/dist/hdhr/udp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"udp.d.ts","sourceRoot":"","sources":["../../src/hdhr/udp.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,oBAAoB,EAA4B,MAAM,SAAS,CAAC;AAI9E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAUlD,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAGhC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAG9B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;IAGnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAW,SAAQ,eAAe;IAIjD,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAGrC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAI5B,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CA2H7C;AAgGD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAuB,GAAG,MAAM,CAiDrI"}