@smarterhomeapp/homebridge-vantage 1.0.5 → 1.0.7

package/README.md

@@ -12,6 +12,7 @@ This plugin replaces the one sold on smarterhome.io allowing anyone to download
 - **Real-time Updates**: Live status updates from your InFusion controller
 - **SSL Support**: Secure connections to your controller
 - **Device Filtering**: Include/exclude specific devices by VID range
+- **Safe Configuration Cache**: Downloads fresh controller configuration on every startup while keeping a persistent last-known-good fallback
 
 ## Installation
 
@@ -52,10 +53,18 @@ npm install -g @smarterhomeapp/homebridge-vantage
 | `ipaddress` | string | Yes | IP address of your InFusion controller |
 | `username` | string | No | Username for authentication |
 | `password` | string | No | Password for authentication |
-| `usecache` | boolean | No | Use cached configuration (default: true) |
+| `usecache` | boolean | No | Maintain a persistent last-known-good configuration fallback while still attempting fresh controller discovery on every startup (default: true) |
 | `omit` | string | No | Comma-separated list of VIDs to exclude |
 | `range` | string | No | Comma-separated VID range (min,max) |
 
+## Configuration Discovery and Cache
+
+On each Homebridge startup, the plugin first attempts to download the current Vantage controller configuration. If the downloaded configuration is valid and complete, it is used immediately and saved atomically as the persistent last-known-good configuration.
+
+When `usecache` is enabled, the persistent cache is only a fallback. If the controller is offline, returns malformed XML, returns an empty configuration, or returns a suspiciously incomplete configuration, the plugin preserves the existing cache and uses the last-known-good configuration instead.
+
+The cache is stored under Homebridge's configured storage directory in a plugin-specific `vantage` folder. Cache filenames are keyed by controller IP, for example `vantage-10.0.0.100.dc`, so multiple platform instances using different VID ranges for the same controller share one full-controller cache. Restarts naturally pick up controller/DC changes; users do not need to manually clear the cache.
+
 ## Supported Devices
 
 ### Lighting
@@ -92,7 +101,7 @@ npm run build
 
 4. Link for development:
 ```bash
-npm run dev
+npm link
 ```
 
 ## Troubleshooting
@@ -109,7 +118,7 @@ npm run dev
 
 ### Performance Issues
 - Reduce the number of devices by using the `omit` parameter
-- Disable cache if configuration changes frequently
+- Restart Homebridge to force a fresh controller configuration download
 - Consider using device ranges to limit discovery
 
 ## License

package/dist/platform.d.ts

@@ -12,6 +12,8 @@ export declare class VantagePlatform implements DynamicPlatformPlugin {
     constructor(log: Logger, config: PlatformConfig, api: API);
     configureAccessory(accessory: PlatformAccessory): void;
     private syncAccessories;
+    private shouldSkipStaleRemoval;
+    private rebuildAccessoryVidMap;
     private wireRealtimeListeners;
     private finalizeLogs;
     getInfusion(): VantageInfusion;

package/dist/platform.js

@@ -26,6 +26,7 @@ class VantagePlatform {
             omit: config.omit ?? '',
             range: config.range ?? '0,999999999',
             forceSSL: config.forceSSL ?? false,
+            storagePath: this.api.user.storagePath(),
             log: this.log,
         });
         // ----- Standard HB boot path -----
@@ -50,10 +51,27 @@ class VantagePlatform {
     // Reconcile cached accessories with current device list
     async syncAccessories(devices) {
         const uuidFor = (d) => this.api.hap.uuid.generate(String(d.vid));
+        if (devices.length === 0 && this.accessories.length > 0) {
+            this.log.error(`Discovery returned 0 devices; preserving ${this.accessories.length} cached accessories ` +
+                'and rebuilding realtime VID map.');
+            this.rebuildAccessoryVidMap();
+            this.wireRealtimeListeners();
+            this.syncedOnce = true;
+            return;
+        }
         // Map current devices
         const wanted = new Map();
         for (const d of devices)
             wanted.set(uuidFor(d), d);
+        const toUnregister = this.accessories.filter((acc) => !wanted.has(acc.UUID));
+        if (toUnregister.length && this.shouldSkipStaleRemoval(devices.length, toUnregister.length)) {
+            this.log.error(`Suspicious partial discovery detected; preserving ${this.accessories.length} cached accessories. ` +
+                `Discovery returned ${devices.length} devices and would remove ${toUnregister.length}.`);
+            this.rebuildAccessoryVidMap();
+            this.wireRealtimeListeners();
+            this.syncedOnce = true;
+            return;
+        }
         // Update existing / mark seen
         const seen = new Set();
         const toUpdate = [];
@@ -93,10 +111,9 @@ class VantagePlatform {
             this.log.info(`Registered ${toRegister.length} new accessories`);
         }
         // Unregister stale
-        const toUnregister = this.accessories.filter((acc) => !wanted.has(acc.UUID));
         if (toUnregister.length) {
             this.api.unregisterPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, toUnregister);
-            this.log.info(`Unregistered ${toUnregister.length} stale accessories`);
+            this.log.info(`Unregistered ${toUnregister.length} stale accessories after successful discovery`);
             // Remove from local cache & VID map
             for (const acc of toUnregister) {
                 const vid = acc?.context?.device?.vid;
@@ -111,6 +128,24 @@ class VantagePlatform {
         this.wireRealtimeListeners();
         this.syncedOnce = true;
     }
+    shouldSkipStaleRemoval(discoveredCount, staleCount) {
+        const cachedCount = this.accessories.length;
+        if (cachedCount === 0 || staleCount === 0)
+            return false;
+        const removalRatio = staleCount / cachedCount;
+        const discoveredRatio = discoveredCount / cachedCount;
+        // Allow small cleanup, but refuse sudden large percentage drops that look like partial discovery.
+        return staleCount >= 5 && removalRatio > 0.5 && discoveredRatio < 0.5;
+    }
+    rebuildAccessoryVidMap() {
+        this.accessoriesByVid.clear();
+        for (const acc of this.accessories) {
+            const vid = acc?.context?.device?.vid;
+            if (vid !== undefined && vid !== null) {
+                this.accessoriesByVid.set(String(vid), acc);
+            }
+        }
+    }
     wireRealtimeListeners() {
         if (this.realtimeWired)
             return;

package/dist/vantageInfusion.d.ts

@@ -9,6 +9,7 @@ interface Options {
     omit: string;
     range: string;
     log: Logger;
+    storagePath: string;
     forceSSL?: boolean;
 }
 export declare class VantageInfusion extends EventEmitter {
@@ -17,7 +18,10 @@ export declare class VantageInfusion extends EventEmitter {
     private command;
     private isInsecureCmd;
     private isInsecureCfg;
-    private getCacheFilePath;
+    private getPersistentCachePath;
+    private getPersistentCacheDirectory;
+    private getLegacyCachePaths;
+    private cacheKeyForIp;
     constructor(opts: Options);
     /** Probe ports and open command session */
     start(): Promise<void>;
@@ -29,11 +33,19 @@ export declare class VantageInfusion extends EventEmitter {
     /** XML/config discovery; returns devices (replaces old Discover/DiscoverSSL) */
     discoverDevices(): Promise<VantageDevice[]>;
     private processConfigurationXml;
+    private parseAndValidateConfigurationXml;
+    private isRelevantConfigObject;
+    private errorMessage;
+    private loadPersistentCache;
+    private migrateLegacyCacheIfNeeded;
     /** Escape text for XML (same as sanitize in index.js). */
     private static escapeXml;
     /** Build cache XML from readObjects (same structure + sanitization as original index.js). */
     private buildCacheXml;
     private pullConfigurationXml;
+    private writePersistentCacheAtomically;
+    private validateCandidateAgainstExistingCache;
+    private validateExistingCacheForReplacement;
     setBrightness(vid: string, level: number): Promise<void>;
     setHue(vid: string, hue: number): Promise<void>;
     setSaturation(vid: string, sat: number): Promise<void>;

package/dist/vantageInfusion.js

@@ -40,7 +40,6 @@ const tls = __importStar(require("tls"));
 const xml2js_1 = require("xml2js");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const os = __importStar(require("os"));
 const TYPE_THERMO = [
     'Thermostat',
     'Vantage.HVAC-Interface_Point_Zone_CHILD',
@@ -71,14 +70,27 @@ const OBJECT_TYPES = [
     ...TYPE_THERMO,
     ...TYPE_BLIND,
 ];
+const DISCOVERABLE_OBJECT_TYPES = OBJECT_TYPES.filter((type) => type !== 'Area');
+class CandidateConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CandidateConfigurationError';
+    }
+}
 class VantageInfusion extends events_1.EventEmitter {
-    getCacheFilePath() {
-        // Try /tmp first (Linux/macOS), then fall back to user's home directory
-        const tmpPath = '/tmp/vantage.dc';
-        if (fs.existsSync('/tmp')) {
-            return tmpPath;
-        }
-        return path.join(os.homedir(), 'vantage.dc');
+    getPersistentCachePath() {
+        const fileName = `vantage-${this.cacheKeyForIp(this.opts.ipaddress)}.dc`;
+        // Controller-level cache is intentionally not range-specific; range-split main/child bridge instances share it.
+        return path.join(this.getPersistentCacheDirectory(), fileName);
+    }
+    getPersistentCacheDirectory() {
+        return path.join(this.opts.storagePath, 'vantage');
+    }
+    getLegacyCachePaths() {
+        return [path.join('/tmp', `vantage-${this.cacheKeyForIp(this.opts.ipaddress)}.dc`)];
+    }
+    cacheKeyForIp(ipaddress) {
+        return ipaddress.replace(/[^a-zA-Z0-9.-]/g, '_');
     }
     constructor(opts) {
         super();
@@ -86,6 +98,7 @@ class VantageInfusion extends events_1.EventEmitter {
         this.xml = new xml2js_1.Parser({ explicitArray: false, mergeAttrs: true, trim: true });
         this.isInsecureCmd = true; // 3001 vs 3010
         this.isInsecureCfg = true; // 2001 vs 2010
+        this.opts.log.debug(`Persistent Vantage cache path: ${this.getPersistentCachePath()}`);
     }
     /** Probe ports and open command session */
     async start() {
@@ -262,30 +275,47 @@ class VantageInfusion extends events_1.EventEmitter {
     }
     /** XML/config discovery; returns devices (replaces old Discover/DiscoverSSL) */
     async discoverDevices() {
-        // Check for cached configuration first
         if (this.opts.usecache) {
-            const cachePath = this.getCacheFilePath();
-            if (fs.existsSync(cachePath)) {
+            await this.migrateLegacyCacheIfNeeded();
+        }
+        try {
+            this.opts.log.info(`Attempting fresh Vantage configuration download from ${this.opts.ipaddress}`);
+            const xml = await this.pullConfigurationXml();
+            const validation = await this.parseAndValidateConfigurationXml(xml, 'downloaded configuration');
+            this.opts.log.info(`Fresh Vantage controller configuration validated successfully (${validation.relevantObjectCount} relevant objects)`);
+            if (this.opts.usecache) {
                 try {
-                    const cachedXml = fs.readFileSync(cachePath, 'utf8');
-                    this.opts.log.info(`Using cached configuration from ${cachePath}`);
-                    return this.processConfigurationXml(cachedXml);
+                    await this.writePersistentCacheAtomically(xml, validation);
                 }
                 catch (error) {
-                    this.opts.log.warn(`Failed to read cached configuration: ${error}`);
+                    if (error instanceof CandidateConfigurationError) {
+                        throw error;
+                    }
+                    this.opts.log.warn(`Persistent cache update failed; using live configuration for this run: ${this.errorMessage(error)}`);
                 }
             }
+            // Legacy: "end configuration download"
+            this.opts.log.debug('VantagePlatform for InFusion Controller (end configuration download)');
+            const devices = await this.processConfigurationXml(xml, 'downloaded configuration');
+            this.opts.log.info('Fresh Vantage controller configuration loaded successfully');
+            return devices;
+        }
+        catch (error) {
+            this.opts.log.warn(`Fresh controller discovery failed; attempting persistent fallback cache: ${this.errorMessage(error)}`);
+            if (this.opts.usecache) {
+                try {
+                    return await this.loadPersistentCache();
+                }
+                catch (cacheError) {
+                    this.opts.log.error(`Persistent cache unavailable; preserving existing Homebridge accessories: ${this.errorMessage(cacheError)}`);
+                }
+            }
+            throw error;
         }
-        const xml = await this.pullConfigurationXml();
-        // Legacy: "end configuration download"
-        this.opts.log.debug('VantagePlatform for InFusion Controller (end configuration download)');
-        return this.processConfigurationXml(xml);
     }
-    async processConfigurationXml(xml) {
-        const sanitized = this.sanitizeXml(xml);
-        const parsed = await this.xml.parseStringPromise(sanitized).catch(() => ({}));
+    async processConfigurationXml(xml, source = 'configuration') {
+        const { objects } = await this.parseAndValidateConfigurationXml(xml, source);
         const devices = [];
-        const objects = parsed?.Project?.Objects?.Object || [];
         const Areas = objects.filter((el) => Object.keys(el)[0] === 'Area');
         const Area = {};
         for (const a of Areas)
@@ -420,6 +450,84 @@ class VantageInfusion extends events_1.EventEmitter {
         }
         return filtered;
     }
+    async parseAndValidateConfigurationXml(xml, source) {
+        const sanitized = this.sanitizeXml(xml);
+        let parsedAny;
+        try {
+            parsedAny = await this.xml.parseStringPromise(sanitized);
+        }
+        catch (error) {
+            const message = `${source} rejected: XML parsing failed: ${this.errorMessage(error)}`;
+            this.opts.log.error(message);
+            throw new Error(message);
+        }
+        const parsed = parsedAny?.smarterHome ?? parsedAny;
+        const objectNode = parsed?.Project?.Objects?.Object;
+        if (!objectNode) {
+            const message = `${source} rejected: missing Project.Objects.Object configuration structure`;
+            this.opts.log.error(message);
+            throw new Error(message);
+        }
+        const objects = Array.isArray(objectNode) ? objectNode : [objectNode];
+        if (objects.length === 0) {
+            const message = `${source} rejected: Project.Objects.Object contains no objects`;
+            this.opts.log.error(message);
+            throw new Error(message);
+        }
+        const relevantObjectCount = objects.filter((object) => this.isRelevantConfigObject(object)).length;
+        if (relevantObjectCount === 0) {
+            const message = `${source} rejected: configuration contains no discoverable Vantage objects`;
+            this.opts.log.error(message);
+            throw new Error(message);
+        }
+        return { objects, relevantObjectCount };
+    }
+    isRelevantConfigObject(raw) {
+        if (!raw || typeof raw !== 'object')
+            return false;
+        const key = Object.keys(raw)[0];
+        const value = raw[key];
+        if (!value || typeof value !== 'object')
+            return false;
+        const objectType = value?.ObjectType ?? key;
+        return DISCOVERABLE_OBJECT_TYPES.includes(key) || DISCOVERABLE_OBJECT_TYPES.includes(objectType);
+    }
+    errorMessage(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    async loadPersistentCache() {
+        const cachePath = this.getPersistentCachePath();
+        if (!fs.existsSync(cachePath)) {
+            throw new Error(`persistent cache not found at ${cachePath}`);
+        }
+        const cachedXml = fs.readFileSync(cachePath, 'utf8');
+        const devices = await this.processConfigurationXml(cachedXml, `persistent last-known-good cache ${cachePath}`);
+        this.opts.log.warn(`Using persistent last-known-good Vantage configuration from ${cachePath}`);
+        return devices;
+    }
+    async migrateLegacyCacheIfNeeded() {
+        const persistentCachePath = this.getPersistentCachePath();
+        if (fs.existsSync(persistentCachePath))
+            return;
+        for (const legacyPath of this.getLegacyCachePaths()) {
+            if (!fs.existsSync(legacyPath))
+                continue;
+            try {
+                const legacyXml = fs.readFileSync(legacyPath, 'utf8');
+                const validation = await this.parseAndValidateConfigurationXml(legacyXml, `legacy cache ${legacyPath}`);
+                await this.writePersistentCacheAtomically(legacyXml, validation);
+                this.opts.log.info(`Migrated legacy Vantage cache from ${legacyPath} to ${persistentCachePath}`);
+                return;
+            }
+            catch (error) {
+                this.opts.log.warn(`Legacy cache rejected from ${legacyPath}: ${this.errorMessage(error)}`);
+            }
+        }
+        const unkeyedLegacyPath = path.join('/tmp', 'vantage.dc');
+        if (fs.existsSync(unkeyedLegacyPath)) {
+            this.opts.log.warn(`Legacy cache ${unkeyedLegacyPath} exists but was not migrated because it is not controller-specific.`);
+        }
+    }
     /** Escape text for XML (same as sanitize in index.js). */
     static escapeXml(s) {
         return String(s)
@@ -440,24 +548,12 @@ class VantageInfusion extends events_1.EventEmitter {
         return `<Project><Objects>${frag}</Objects></Project>`;
     }
     pullConfigurationXml() {
-        return new Promise((resolve) => {
+        return new Promise((resolve, reject) => {
             const finishOnce = (socket, xml) => {
                 if (finishOnce._done)
                     return;
                 finishOnce._done = true;
-                // Save configuration to cache if usecache is enabled
-                if (this.opts.usecache) {
-                    try {
-                        const cachePath = this.getCacheFilePath();
-                        fs.writeFileSync(cachePath, xml);
-                        this.opts.log.info(`Configuration cached to ${cachePath}`);
-                    }
-                    catch (error) {
-                        this.opts.log.warn(`Failed to cache configuration: ${error}`);
-                    }
-                }
-                // legacy log + event
-                this.opts.log.debug('VantagePlatform for InFusion Controller (end configuration download)');
+                // legacy event
                 this.emit('endDownloadConfiguration', xml);
                 try {
                     socket.destroy();
@@ -465,6 +561,16 @@ class VantageInfusion extends events_1.EventEmitter {
                 catch { /* noop */ }
                 resolve(xml);
             };
+            const failOnce = (socket, error) => {
+                if (finishOnce._done)
+                    return;
+                finishOnce._done = true;
+                try {
+                    socket.destroy();
+                }
+                catch { /* noop */ }
+                reject(error);
+            };
             const onData = (socket) => {
                 this.opts.log.info('load dc file'); // legacy
                 let buffer = '';
@@ -599,31 +705,108 @@ class VantageInfusion extends events_1.EventEmitter {
                 });
                 socket.on('end', () => {
                     this.opts.log.info("ending" + shouldBreak);
+                    if (finishOnce._done)
+                        return;
                     if (!finishOnce._done && readObjects.length) {
                         const xml = this.buildCacheXml(readObjects);
                         clearLoginFallback();
                         clearInterval(watchdog);
                         finishOnce(socket, xml);
                     }
+                    else {
+                        clearLoginFallback();
+                        clearInterval(watchdog);
+                        failOnce(socket, new Error('Connection ended before Vantage configuration was downloaded'));
+                    }
                 });
                 socket.on('close', () => {
                     this.opts.log.debug("closing " + shouldBreak);
+                    if (finishOnce._done)
+                        return;
                     if (!finishOnce._done && readObjects.length) {
                         const xml = this.buildCacheXml(readObjects);
                         clearLoginFallback();
                         clearInterval(watchdog);
                         finishOnce(socket, xml);
                     }
+                    else {
+                        clearLoginFallback();
+                        clearInterval(watchdog);
+                        failOnce(socket, new Error('Connection closed before Vantage configuration was downloaded'));
+                    }
+                });
+                socket.on('timeout', () => {
+                    clearLoginFallback();
+                    clearInterval(watchdog);
+                    failOnce(socket, new Error('Timed out while downloading Vantage configuration'));
+                });
+                socket.on('error', (error) => {
+                    clearLoginFallback();
+                    clearInterval(watchdog);
+                    failOnce(socket, error);
                 });
+                socket.setTimeout(30000);
             };
             if (this.isInsecureCfg) {
                 const s = net.connect({ host: this.opts.ipaddress, port: 2001 }, () => onData(s));
+                s.once('error', (error) => failOnce(s, error));
+                s.setTimeout(30000, () => failOnce(s, new Error('Timed out connecting to Vantage configuration port')));
             }
             else {
                 const s = tls.connect(2010, this.opts.ipaddress, { rejectUnauthorized: false, requestCert: true }, () => onData(s));
+                s.once('error', (error) => failOnce(s, error));
+                s.setTimeout(30000, () => failOnce(s, new Error('Timed out connecting to Vantage configuration port')));
             }
         });
     }
+    async writePersistentCacheAtomically(xml, candidateValidation) {
+        const cachePath = this.getPersistentCachePath();
+        const tmpPath = `${cachePath}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+        await this.validateCandidateAgainstExistingCache(cachePath, candidateValidation);
+        try {
+            fs.mkdirSync(this.getPersistentCacheDirectory(), { recursive: true });
+            fs.writeFileSync(tmpPath, xml, 'utf8');
+            const tmpXml = fs.readFileSync(tmpPath, 'utf8');
+            const validation = await this.parseAndValidateConfigurationXml(tmpXml, `temporary cache ${tmpPath}`);
+            await this.validateCandidateAgainstExistingCache(cachePath, validation);
+            fs.renameSync(tmpPath, cachePath);
+            this.opts.log.info(`Validated controller configuration accepted and persistent cache updated atomically at ${cachePath} ` +
+                `(${validation.relevantObjectCount} relevant objects).`);
+        }
+        catch (error) {
+            try {
+                if (fs.existsSync(tmpPath))
+                    fs.unlinkSync(tmpPath);
+            }
+            catch {
+                /* preserve original error */
+            }
+            throw error;
+        }
+    }
+    async validateCandidateAgainstExistingCache(cachePath, candidateValidation) {
+        if (!fs.existsSync(cachePath))
+            return;
+        const existingValidation = await this.validateExistingCacheForReplacement(cachePath);
+        if (existingValidation &&
+            existingValidation.relevantObjectCount >= 20 &&
+            candidateValidation.relevantObjectCount < existingValidation.relevantObjectCount * 0.5) {
+            const message = `Downloaded configuration rejected as incomplete: ${candidateValidation.relevantObjectCount} relevant objects ` +
+                `vs ${existingValidation.relevantObjectCount} in persistent cache.`;
+            this.opts.log.error(message);
+            throw new CandidateConfigurationError(message);
+        }
+    }
+    async validateExistingCacheForReplacement(cachePath) {
+        try {
+            const existingXml = fs.readFileSync(cachePath, 'utf8');
+            return await this.parseAndValidateConfigurationXml(existingXml, `existing cache ${cachePath}`);
+        }
+        catch (error) {
+            this.opts.log.warn(`Existing cache is invalid; replacing it with validated controller configuration: ${this.errorMessage(error)}`);
+            return undefined;
+        }
+    }
     // ===== Commands used by platformAccessory handlers =====
     async setBrightness(vid, level) {
         const lvl = Math.max(0, Math.min(100, Number(level)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smarterhomeapp/homebridge-vantage",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Homebridge plugin for Vantage InFusion (dynamic platform, HB 1.6+ / 2.0 ready)",
   "license": "MIT",
   "keywords": [