@smarterhomeapp/homebridge-vantage 1.0.6 → 1.0.8

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.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 -----

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,9 @@ 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 */
@@ -33,12 +36,16 @@ export declare class VantageInfusion extends EventEmitter {
     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 writeCacheAtomically;
+    private writePersistentCacheAtomically;
+    private writeLegacyTmpCacheMirror;
+    private validateCandidateAgainstExistingCache;
     private validateExistingCacheForReplacement;
     setBrightness(vid: string, level: number): Promise<void>;
     setHue(vid: string, hue: 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',
@@ -72,15 +71,23 @@ const OBJECT_TYPES = [
     ...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() {
+    getPersistentCachePath() {
         const fileName = `vantage-${this.cacheKeyForIp(this.opts.ipaddress)}.dc`;
-        // Try /tmp first (Linux/macOS), then fall back to user's home directory.
-        const tmpPath = path.join('/tmp', fileName);
-        if (fs.existsSync('/tmp')) {
-            return tmpPath;
-        }
-        return path.join(os.homedir(), fileName);
+        // 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, '_');
@@ -91,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() {
@@ -267,27 +275,44 @@ 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');
-                    const devices = await this.processConfigurationXml(cachedXml, `cached configuration from ${cachePath}`);
-                    this.opts.log.info(`Valid cached configuration loaded from ${cachePath}`);
-                    return devices;
+                    await this.writePersistentCacheAtomically(xml, validation);
                 }
                 catch (error) {
-                    this.opts.log.warn(`Cached configuration rejected from ${cachePath}: ${this.errorMessage(error)}`);
+                    if (error instanceof CandidateConfigurationError) {
+                        throw error;
+                    }
+                    this.opts.log.warn(`Persistent cache update failed; using live configuration for this run: ${this.errorMessage(error)}`);
                 }
+                await this.writeLegacyTmpCacheMirror(xml, validation);
             }
+            // 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)');
-        const devices = await this.processConfigurationXml(xml, 'downloaded configuration');
-        this.opts.log.info('Valid configuration loaded from controller download');
-        return devices;
     }
     async processConfigurationXml(xml, source = 'configuration') {
         const { objects } = await this.parseAndValidateConfigurationXml(xml, source);
@@ -471,6 +496,39 @@ class VantageInfusion extends events_1.EventEmitter {
     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)
@@ -492,32 +550,27 @@ class VantageInfusion extends events_1.EventEmitter {
     }
     pullConfigurationXml() {
         return new Promise((resolve, reject) => {
-            const finishOnce = async (socket, xml) => {
+            const finishOnce = (socket, xml) => {
                 if (finishOnce._done)
                     return;
                 finishOnce._done = true;
-                // Save configuration to cache if usecache is enabled
+                // legacy event
+                this.emit('endDownloadConfiguration', xml);
                 try {
-                    if (this.opts.usecache) {
-                        await this.writeCacheAtomically(xml);
-                    }
-                    // legacy log + event
-                    this.opts.log.debug('VantagePlatform for InFusion Controller (end configuration download)');
-                    this.emit('endDownloadConfiguration', xml);
-                    try {
-                        socket.destroy();
-                    }
-                    catch { /* noop */ }
-                    resolve(xml);
+                    socket.destroy();
                 }
-                catch (error) {
-                    this.opts.log.error(`Downloaded configuration rejected; preserving existing cache: ${this.errorMessage(error)}`);
-                    try {
-                        socket.destroy();
-                    }
-                    catch { /* noop */ }
-                    reject(error);
+                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
@@ -538,7 +591,7 @@ class VantageInfusion extends events_1.EventEmitter {
                     if (readObjects.length && Date.now() - lastProgress > 2000) {
                         const xml = this.buildCacheXml(readObjects);
                         clearInterval(watchdog);
-                        void finishOnce(socket, xml);
+                        finishOnce(socket, xml);
                     }
                 }, 750);
                 const writeOpenFilter = () => {
@@ -647,58 +700,78 @@ class VantageInfusion extends events_1.EventEmitter {
                             const xml = this.buildCacheXml(readObjects);
                             clearLoginFallback();
                             clearInterval(watchdog);
-                            void finishOnce(socket, xml);
+                            finishOnce(socket, xml);
                         }
                     });
                 });
                 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);
-                        void finishOnce(socket, xml);
+                        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);
-                        void finishOnce(socket, xml);
+                        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 writeCacheAtomically(xml) {
-        const cachePath = this.getCacheFilePath();
+    async writePersistentCacheAtomically(xml, candidateValidation) {
+        const cachePath = this.getPersistentCachePath();
         const tmpPath = `${cachePath}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
-        const candidateValidation = await this.parseAndValidateConfigurationXml(xml, 'downloaded configuration');
+        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}`);
-            if (fs.existsSync(cachePath)) {
-                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 existing cache.`;
-                    this.opts.log.error(message);
-                    throw new Error(message);
-                }
-            }
+            await this.validateCandidateAgainstExistingCache(cachePath, validation);
             fs.renameSync(tmpPath, cachePath);
-            this.opts.log.info(`Validated controller configuration accepted and cache replaced atomically at ${cachePath} ` +
+            this.opts.log.info(`Validated controller configuration accepted and persistent cache updated atomically at ${cachePath} ` +
                 `(${validation.relevantObjectCount} relevant objects).`);
         }
         catch (error) {
@@ -712,6 +785,44 @@ class VantageInfusion extends events_1.EventEmitter {
             throw error;
         }
     }
+    async writeLegacyTmpCacheMirror(xml, candidateValidation) {
+        const cachePath = path.join('/tmp', 'vantage.dc');
+        const tmpPath = `${cachePath}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+        try {
+            fs.writeFileSync(tmpPath, xml, 'utf8');
+            const tmpXml = fs.readFileSync(tmpPath, 'utf8');
+            const validation = await this.parseAndValidateConfigurationXml(tmpXml, `legacy temporary cache mirror ${tmpPath}`);
+            if (validation.relevantObjectCount !== candidateValidation.relevantObjectCount) {
+                throw new Error(`legacy cache mirror validation mismatch: ${validation.relevantObjectCount} relevant objects ` +
+                    `vs ${candidateValidation.relevantObjectCount} expected`);
+            }
+            fs.renameSync(tmpPath, cachePath);
+            this.opts.log.debug(`Legacy /tmp Vantage cache mirror updated at ${cachePath}`);
+        }
+        catch (error) {
+            try {
+                if (fs.existsSync(tmpPath))
+                    fs.unlinkSync(tmpPath);
+            }
+            catch {
+                /* preserve original error */
+            }
+            this.opts.log.warn(`Failed to update legacy /tmp Vantage cache mirror: ${this.errorMessage(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');

package/package.json

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