homebridge-bluos 0.1.0

package/dist/poller.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview One long-poll loop per player zone.
+ *
+ * The loop holds a `/SyncStatus?timeout=100&etag=…` request open and is woken by
+ * the player the moment that zone's state changes. Verified against firmware
+ * 4.16.6: with a current etag the request holds for exactly the requested window,
+ * with a stale etag it answers in 44 ms, and the etag is per-zone — a sibling zone
+ * on the same chassis changing volume does not wake this poll. That last point is
+ * why one loop per zone is correct rather than wasteful.
+ *
+ * The set/poll race is handled with a generation counter. A response that was
+ * computed before a local write cannot be distinguished from a fresh one by its
+ * contents, so any response that arrives across a write is discarded and replaced
+ * by an immediate re-read. That costs one cheap request — a stale etag answers
+ * immediately — and removes the class of bug where a HomeKit slider springs back
+ * to its old position a moment after being moved.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevicePoller = void 0;
+const settings_1 = require("./settings");
+const utils_1 = require("./utils");
+/**
+ * Marks a read that this plugin cancelled on purpose.
+ *
+ * A write, a refresh request or an address change drops the poll in flight, and
+ * the resulting rejection is indistinguishable from a network failure by its
+ * type. Counting it as one would be actively harmful: three writes in a row
+ * would trip the unreachable threshold and show every accessory for that player
+ * as No Response, and each write would pay a backoff delay before the state it
+ * just changed could be read back.
+ */
+class PollInterrupted extends Error {
+    constructor() {
+        super('poll interrupted');
+        this.name = 'PollInterrupted';
+    }
+}
+/** Drives one player zone. */
+class DevicePoller {
+    options;
+    currentEndpoint;
+    observation;
+    /** Opaque long-poll token. Cleared to force a plain read next time round. */
+    etag;
+    /** Incremented by every local write, to invalidate responses that predate it. */
+    generation = 0;
+    consecutiveFailures = 0;
+    lastRediscoveryAt = 0;
+    stopped = false;
+    loop;
+    abort;
+    /** Resolves the current backoff sleep early when a refresh is requested. */
+    wake;
+    constructor(options) {
+        this.options = options;
+        this.currentEndpoint = options.endpoint;
+    }
+    get endpoint() {
+        return this.currentEndpoint;
+    }
+    get lastObservation() {
+        return this.observation;
+    }
+    /** Point this poller at a new address, dropping any request in flight. */
+    setEndpoint(endpoint) {
+        if (endpoint.host === this.currentEndpoint.host && endpoint.port === this.currentEndpoint.port) {
+            return;
+        }
+        this.options.log.info(`${(0, utils_1.forLog)(this.options.displayName)} moved to ${endpoint.host}:${endpoint.port}`);
+        this.currentEndpoint = endpoint;
+        this.etag = undefined;
+        this.options.onEndpointChanged?.(endpoint);
+        this.interrupt();
+    }
+    /** Begin polling. Safe to call more than once. */
+    start() {
+        if (this.loop !== undefined) {
+            return;
+        }
+        this.stopped = false;
+        // The loop is deliberately not awaited by its caller, so its promise needs a
+        // rejection handler of its own. Without one, an unexpected throw anywhere in
+        // the loop becomes an unhandled rejection, which on Node 20+ terminates the
+        // process — taking Homebridge and every other plugin down with it.
+        this.loop = this.run().catch((error) => {
+            this.options.log.error(`${this.label()} polling stopped after an unexpected error, so its state will `
+                + `no longer update until Homebridge restarts: ${(0, utils_1.describeError)(error)}`);
+        });
+    }
+    /** Stop polling and drop any request in flight. */
+    async stop() {
+        this.stopped = true;
+        this.interrupt();
+        const loop = this.loop;
+        this.loop = undefined;
+        if (loop !== undefined) {
+            await loop;
+        }
+    }
+    /**
+     * Adopt the state a write reported, and invalidate anything in flight.
+     *
+     * The player's answer to a write is authoritative — it clamps the level into
+     * its own configured range — so this is both the fastest and the most accurate
+     * update available.
+     */
+    adoptWriteResult(result) {
+        this.generation += 1;
+        const previous = this.observation;
+        const merged = {
+            ...(previous ?? {
+                name: this.options.displayName,
+                fixedVolume: false,
+                muted: false,
+                syncRole: 'standalone',
+            }),
+            fixedVolume: result.fixedVolume,
+            muted: result.muted,
+        };
+        if (result.level !== undefined) {
+            merged.volume = result.level;
+        }
+        if (result.muteVolume !== undefined) {
+            merged.muteVolume = result.muteVolume;
+        }
+        else if (!result.muted) {
+            // The firmware only publishes muteVolume while muted, so carrying the old
+            // one forward past an unmute would let a stale pre-mute level win the
+            // restore decision in restoreLevelFrom and jump the room loud.
+            delete merged.muteVolume;
+        }
+        if (result.db !== undefined) {
+            merged.db = result.db;
+        }
+        // The etag from a /Volume response is not a /SyncStatus etag, so the next
+        // poll starts from a plain read rather than a token from the wrong resource.
+        this.etag = undefined;
+        this.observation = merged;
+        this.options.onObservation(merged, 'post-set');
+        this.interrupt();
+    }
+    /** Cancel the request in flight and wake any backoff sleep. */
+    interrupt() {
+        this.abort?.abort();
+        this.abort = undefined;
+        this.wake?.();
+        this.wake = undefined;
+    }
+    async run() {
+        let first = true;
+        while (!this.stopped) {
+            const generation = this.generation;
+            try {
+                const observation = await this.readOnce();
+                if (this.stopped) {
+                    return;
+                }
+                if (this.generation !== generation) {
+                    // A write landed while this was in flight, so the response may describe
+                    // the state before it. Discard and re-read rather than risk showing the
+                    // user their change being undone.
+                    this.options.log.debug(`${(0, utils_1.forLog)(this.options.displayName)} discarding a poll response that crossed a write`);
+                    this.etag = undefined;
+                    continue;
+                }
+                this.consecutiveFailures = 0;
+                this.etag = observation.etag;
+                this.observation = observation;
+                this.options.onObservation(observation, first ? 'startup' : 'poll');
+                first = false;
+            }
+            catch (error) {
+                if (this.stopped) {
+                    return;
+                }
+                if (error instanceof PollInterrupted) {
+                    // Our own doing, so it is not a failure: start a fresh read at once.
+                    this.etag = undefined;
+                    continue;
+                }
+                await this.handleFailure(error);
+            }
+        }
+    }
+    async readOnce() {
+        const etag = this.etag;
+        if (etag === undefined) {
+            return this.options.client.readSyncStatus(this.currentEndpoint);
+        }
+        const abort = new AbortController();
+        this.abort = abort;
+        try {
+            return await this.options.client.pollSyncStatus(this.currentEndpoint, etag, abort.signal);
+        }
+        catch (error) {
+            throw abort.signal.aborted ? new PollInterrupted() : error;
+        }
+        finally {
+            if (this.abort === abort) {
+                this.abort = undefined;
+            }
+        }
+    }
+    async handleFailure(error) {
+        this.consecutiveFailures += 1;
+        // A failed long-poll leaves the token untrustworthy; the next attempt starts
+        // from a plain read so a stale etag cannot mask a recovered player.
+        this.etag = undefined;
+        if (this.consecutiveFailures === 1) {
+            this.options.log.debug(`${this.label()} poll failed: ${(0, utils_1.describeError)(error)}`);
+        }
+        // Two separate policies, deliberately read from two constants: how long
+        // before HomeKit is told the truth, and how long before we go looking for a
+        // new address.
+        if (this.consecutiveFailures >= settings_1.POLL_FAILURES_BEFORE_UNKNOWN) {
+            this.options.onUnreachable(error);
+        }
+        if (this.consecutiveFailures >= settings_1.FAILURES_BEFORE_REDISCOVERY) {
+            const moved = await this.tryRediscovery();
+            if (moved) {
+                // The address is known to have changed, so there is nothing to wait for:
+                // sleeping out a backoff that may already be at its one-minute ceiling
+                // would delay recovery for no reason.
+                this.consecutiveFailures = 0;
+                return;
+            }
+        }
+        if (this.stopped) {
+            return;
+        }
+        const exponent = Math.min(this.consecutiveFailures - 1, 10);
+        const ceiling = Math.min(settings_1.POLL_BACKOFF_MAX_MS, settings_1.POLL_BACKOFF_BASE_MS * 2 ** exponent);
+        // Full jitter, so a rebooting fleet does not synchronise its retries into a
+        // burst against the network.
+        const delay = Math.round(ceiling * (0.5 + Math.random() * 0.5));
+        await this.sleepInterruptibly(delay);
+    }
+    /**
+     * Look for a new address for this player. True when the address changed.
+     *
+     * Rate-limited: a player that is switched off would otherwise trigger a
+     * multicast sweep on every backoff cycle.
+     */
+    async tryRediscovery() {
+        const now = Date.now();
+        if (this.stopped || now - this.lastRediscoveryAt < settings_1.REDISCOVERY_MIN_INTERVAL_MS) {
+            return false;
+        }
+        this.lastRediscoveryAt = now;
+        try {
+            const found = await this.options.resolveEndpoint(this.options.deviceId);
+            // A sweep can outlive a shutdown request, and re-pointing a stopping poller
+            // would persist an address change nobody asked for.
+            if (this.stopped || found === undefined) {
+                return false;
+            }
+            const moved = found.host !== this.currentEndpoint.host
+                || found.port !== this.currentEndpoint.port;
+            this.setEndpoint(found);
+            return moved;
+        }
+        catch (error) {
+            this.options.log.debug(`${this.label()} address lookup failed: ${(0, utils_1.describeError)(error)}`);
+            return false;
+        }
+    }
+    /**
+     * Name plus stable id, for a log line someone has to act on.
+     *
+     * Two players can share a display name — the configuration validator warns
+     * about it rather than refusing it — so a failure line naming only the name
+     * cannot be traced back to a player.
+     */
+    label() {
+        return `${(0, utils_1.forLog)(this.options.displayName)} [${(0, utils_1.forLog)(this.options.deviceId)}]`;
+    }
+    /**
+     * Sleep, but return early if a write, refresh or shutdown arrives.
+     *
+     * The timer is cleared rather than left to expire, so stopping the plugin does
+     * not have to wait out a backoff delay that no longer matters.
+     */
+    async sleepInterruptibly(ms) {
+        const pending = (0, utils_1.interruptibleSleep)(ms);
+        this.wake = () => pending.interrupt();
+        try {
+            await pending.promise;
+        }
+        finally {
+            this.wake = undefined;
+        }
+    }
+}
+exports.DevicePoller = DevicePoller;

package/dist/settings.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Plugin-wide constants and the plugin version reader.
+ *
+ * Numbers that came from the BluOS Custom Integration API v1.7 specification or
+ * from measurements against real players cite their source, so a future reader
+ * can tell a vendor requirement apart from a judgement call.
+ */
+import type { PluginLogger } from './types';
+/** npm package name. Must match `package.json` `name` for Homebridge to load us. */
+export declare const PLUGIN_NAME = "homebridge-bluos";
+/** Platform alias used in `config.json` and `config.schema.json`. */
+export declare const PLATFORM_NAME = "BluOS";
+/**
+ * Namespace for generated accessory UUIDs.
+ *
+ * Deliberately does not include a host or port: seeding accessory identity with
+ * an address means a DHCP lease change re-creates every accessory and destroys
+ * the rooms, scenes and automations the user built on top of them.
+ */
+export declare const UUID_PREFIX = "homebridge-bluos:";
+/** Reported when `package.json` cannot be read. */
+export declare const UNKNOWN_PLUGIN_VERSION = "0.0.0";
+/** Manufacturer shown when `/SyncStatus` does not report a brand. */
+export declare const DEFAULT_BRAND = "BluOS";
+/** Model shown when `/SyncStatus` does not report one. */
+export declare const DEFAULT_MODEL = "BluOS Player";
+/** Control port for a primary player (API v1.7 section 1). */
+export declare const DEFAULT_BLUOS_PORT = 11000;
+/**
+ * Ports the specification documents for multi-zone chassis.
+ *
+ * API v1.7 section 1: the CI 580 exposes four streamer nodes on one IP, using
+ * 11000, 11010, 11020 and 11030. The CI-S2 uses 11000 and 11010. Ports outside
+ * this set are accepted but warned about, because mDNS SRV records are the
+ * authority on which port a zone actually listens to.
+ */
+export declare const DOCUMENTED_BLUOS_PORTS: readonly number[];
+/** Lowest port number accepted anywhere in configuration. */
+export declare const MIN_PORT = 1;
+/** Highest port number accepted anywhere in configuration. */
+export declare const MAX_PORT = 65535;
+/**
+ * Duration passed as `/SyncStatus?timeout=`.
+ *
+ * The specification recommends 180 s for `/SyncStatus`, and forbids anything
+ * faster than 10 s. 100 s is inside that envelope and halves the worst-case
+ * delay before an unplugged player's socket read times out, which is how a
+ * silent disappearance (as opposed to a connection reset) gets noticed.
+ */
+export declare const LONG_POLL_SEC = 100;
+/** Read headroom beyond the player's own long-poll timeout. */
+export declare const LONG_POLL_READ_SLACK_MS = 5000;
+/**
+ * Minimum gap between two consecutive requests for the same resource.
+ *
+ * API v1.7 section 2 makes this a requirement, not a suggestion: "a client must
+ * not make two consecutive requests for the same resource less than one second
+ * apart, even if the first request returns in less than one second".
+ */
+export declare const SAME_RESOURCE_MIN_GAP_MS = 1000;
+/** Connect timeout. Short so a powered-off player cannot stall startup. */
+export declare const CONNECT_TIMEOUT_MS = 2500;
+/** Total timeout for a control call (`/Volume?level=`, `/Volume?mute=`). */
+export declare const CONTROL_TIMEOUT_MS = 5000;
+/** Total timeout for a plain, non-long-poll status read. */
+export declare const STATUS_TIMEOUT_MS = 6000;
+/** Minimum spacing between control calls to one endpoint. */
+export declare const CONTROL_RATE_LIMIT_MS = 100;
+/** First reconnect delay after a failed poll. Doubles up to the ceiling. */
+export declare const POLL_BACKOFF_BASE_MS = 2000;
+/** Ceiling for poll backoff. */
+export declare const POLL_BACKOFF_MAX_MS = 60000;
+/** Consecutive poll failures before an accessory reports No Response. */
+export declare const POLL_FAILURES_BEFORE_UNKNOWN = 3;
+/** How long before a still-failing player is warned about again. */
+export declare const POLL_FAILURE_REWARN_MS = 3600000;
+/**
+ * How long a HomeKit write may block before HAP gives up on it.
+ *
+ * HAP-NodeJS warns at `Accessory.TIMEOUT_WARNING` (3 s) and abandons the write
+ * at 9 s total, returning `OPERATION_TIMED_OUT` and discarding whatever the
+ * handler eventually returns. A set therefore has to answer well inside that
+ * window and finish any slower work in the background.
+ */
+export declare const HOMEKIT_WRITE_BUDGET_MS = 2500;
+/** Level restored when the slider is switched on and no previous level is known. */
+export declare const DEFAULT_RESTORE_VOLUME = 20;
+/**
+ * Window for coalescing the pair of writes HomeKit sends when a slider moves
+ * from off.
+ *
+ * Dragging a Fanv2 up from zero produces an `Active` write immediately followed
+ * by a `RotationSpeed` write. Acting on both would set the restore level and then
+ * the requested level, which the user hears as a jump. Waiting briefly lets the
+ * second write supersede the first, so one value reaches the player. Short enough
+ * to be imperceptible next to the LAN round trip.
+ */
+export declare const SLIDER_COALESCE_MS = 150;
+/** Lowest BluOS volume level. */
+export declare const VOLUME_MIN = 0;
+/** Highest BluOS volume level. */
+export declare const VOLUME_MAX = 100;
+/**
+ * `volume="-1"` means the player's output level is fixed.
+ *
+ * API v1.7 section 2.2: "-1 means fixed volume". Such a player must not be
+ * given a volume slider; writing a level to it is meaningless.
+ */
+export declare const FIXED_VOLUME_SENTINEL = -1;
+/**
+ * `db="-100"` means silence, and is not a real output level.
+ *
+ * Measured on firmware 4.16.6: muting reports `volume="0" db="-100"` alongside
+ * `muteVolume` and `muteDb` carrying the pre-mute values. Note that writing
+ * `level=0` reports the same `db="-100"` with no `muteVolume`, so this value
+ * cannot be used to detect mute — see `readMuted` in `api/sync-status.ts`.
+ */
+export declare const MUTED_DB_SENTINEL = -100;
+/**
+ * Largest `/SyncStatus` body accepted.
+ *
+ * Real responses measure a few hundred bytes; a fully grouped CI 580 is still
+ * far under a kilobyte. 128 KiB is generous while keeping a hostile or
+ * malfunctioning endpoint from growing the heap.
+ */
+export declare const MAX_XML_BYTES = 131072;
+/** Deepest element nesting accepted. */
+export declare const MAX_XML_DEPTH = 16;
+/** Most elements accepted in one document. */
+export declare const MAX_XML_ELEMENTS = 2000;
+/** Most attributes accepted on one element. */
+export declare const MAX_XML_ATTRIBUTES = 64;
+/** mDNS service type advertised by primary players. */
+export declare const MDNS_SERVICE_PRIMARY = "_musc._tcp.local";
+/**
+ * mDNS service type advertised by secondary zones of a multi-zone chassis.
+ *
+ * API v1.7 appendix 13.1 maps this to LSDP class 0x0003, "BluOS Player
+ * (secondary in multi-zone players such as the CI580)".
+ */
+export declare const MDNS_SERVICE_SECONDARY = "_musp._tcp.local";
+/** Default discovery window, in seconds. */
+export declare const DEFAULT_DISCOVERY_TIMEOUT_SEC = 5;
+/** Shortest configurable discovery window. */
+export declare const MIN_DISCOVERY_TIMEOUT_SEC = 1;
+/** Longest configurable discovery window. */
+export declare const MAX_DISCOVERY_TIMEOUT_SEC = 30;
+/** Consecutive poll failures before the platform tries to re-resolve an address. */
+export declare const FAILURES_BEFORE_REDISCOVERY = 3;
+/** Minimum gap between address re-resolution attempts. */
+export declare const REDISCOVERY_MIN_INTERVAL_MS = 60000;
+/**
+ * Most records of one kind kept from a browse window.
+ *
+ * Anything on the segment can answer a multicast query, and a browse window can
+ * be as long as 30 s, so the maps that accumulate advertisements need a ceiling
+ * they cannot be talked past. A household fleet uses a handful of entries.
+ */
+export declare const MAX_DISCOVERY_RECORDS = 256;
+/**
+ * Most candidate endpoints verified from one browse.
+ *
+ * Verification opens a real connection per candidate, so the count of
+ * advertisements must not decide how many sockets this plugin opens.
+ */
+export declare const MAX_DISCOVERY_CANDIDATES = 64;
+/** Candidate endpoints verified at once. Bounds concurrent sockets during a sweep. */
+export declare const DISCOVERY_VERIFY_CONCURRENCY = 6;
+/** Longest untrusted string interpolated into a log line. */
+export declare const MAX_LOG_FIELD_LENGTH = 100;
+/** Longest accepted HomeKit display name. */
+export declare const MAX_NAME_LENGTH = 64;
+/**
+ * Read this plugin's version from `package.json`.
+ *
+ * Reported to HomeKit as FirmwareRevision, which makes the version visible in
+ * the Home app and therefore in bug reports.
+ */
+export declare function readPluginVersion(log?: PluginLogger): string;