homebridge-lib 5.2.3-0 → 5.3.1

package/index.js

@@ -196,6 +196,13 @@ class homebridgeLib {
     */
   static get SystemInfo () { return require('./lib/SystemInfo') }
 
+  /** Server for dynamic configuration settings through Homebridge UI.
+    * <br>See {@link UiServer}.
+    * @type {Class}
+    * @memberof module:homebridgeLib
+    */
+  static get UiServer () { return require('./lib/UiServer') }
+
   /** Universal Plug and Play client.
     * <br>See {@link UpnpClient}.
     * @type {Class}

package/lib/CommandLineTool.js

@@ -150,8 +150,9 @@ class CommandLineTool {
     return !!this._options.debug
   }
 
-  /* Usage string.
-   */
+  /** Usage string.
+    * @type {string}
+    */
   get usage () { return this._usage }
   set usage (usage) {
     this._usage = usage
@@ -167,6 +168,9 @@ class CommandLineTool {
   // ===== Logging =============================================================
 
   /** Print debug message to stderr.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
     */
   debug (format, ...args) {
     if (this._options.debug) {
@@ -175,12 +179,18 @@ class CommandLineTool {
   }
 
   /** Print error message to stderr.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
     */
   error (format, ...args) {
     this._log({ label: 'error', chalk: chalk.bold.red }, format, ...args)
   }
 
   /** Print error message to stderr and abort program.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
     */
   async fatal (format, ...args) {
     this._log({ label: 'fatal', chalk: chalk.bold.red }, format, ...args)
@@ -195,24 +205,36 @@ class CommandLineTool {
   }
 
   /** Print log message to stderr.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
     */
   log (format, ...args) {
     this._log({}, format, ...args)
   }
 
   /** Print log message continuation to stderr.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
     */
   logc (format, ...args) {
     this._log({ noLabel: true }, format, ...args)
   }
 
   /** Print message to stdout.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
     */
   print (format, ...args) {
     this._log({ noLabel: true, stdout: true }, format, ...args)
   }
 
   /** Print verbose debug message to stderr.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
     */
   vdebug (format, ...args) {
     if (this._options.vdebug) {
@@ -221,6 +243,9 @@ class CommandLineTool {
   }
 
   /** Print very verbose debug message to stderr.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
     */
   vvdebug (format, ...args) {
     if (this._options.vvdebug) {
@@ -229,6 +254,9 @@ class CommandLineTool {
   }
 
   /** Print warning message to stderr.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
     */
   warn (format, ...args) {
     this._log({ label: 'warning', chalk: chalk.yellow }, format, ...args)

package/lib/Platform.js

@@ -9,8 +9,10 @@ const homebridgeLib = require('../index')
 
 const events = require('events')
 const fs = require('fs')
+const http = require('http')
 const semver = require('semver')
 const util = require('util')
+
 const libPackageJson = require('../package.json')
 
 const uuid = /^[0-9A-F]{8}-[0-9A-F]{4}-[1-5][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/
@@ -37,7 +39,8 @@ const context = {
   * the plugin through Homebridge;
   * - Persist HomeKit accessories across Homebridge restarts;
   * - Support for device polling by providing a heartbeat;
-  * - Support for UPnP device discovery.
+  * - Support for UPnP device discovery;
+  * - Support dynamic configuration through the Homebridge UI.
   * @abstract
   * @extends Delegate
   */
@@ -172,11 +175,7 @@ class Platform extends homebridgeLib.Delegate {
     this.log('os: %s', this.systemInfo.osInfo.prettyName)
     this._heartbeatStart = new Date()
     setTimeout(() => { this._beat(-1) }, 1000)
-    this.on('exit', () => {
-      this.debug('flush cachedAccessories')
-      this._homebridge.updatePlatformAccessories()
-      this.log('goodbye')
-    })
+    this.on('exit', () => { this._flushCachedAccessories() })
 
     const n = Object.keys(this._accessories).length
     if (n > 0) {
@@ -188,7 +187,13 @@ class Platform extends homebridgeLib.Delegate {
     if (this.listenerCount('upnpDeviceFound') > 0) {
       this._upnpMonitor.search()
     }
+    if (typeof this.onUiRequest === 'function') {
+      try {
+        await this._createUiServer()
+      } catch (error) { this.error(error) }
+    }
     await events.once(this, 'initialised')
+    this._flushCachedAccessories()
     for (const id in this._accessories) {
       if (this._accessoryDelegates[id] == null) {
         const accessory = this._accessories[id]
@@ -205,6 +210,12 @@ class Platform extends homebridgeLib.Delegate {
     }
   }
 
+  // Write `cachedAccessories` to disk.
+  _flushCachedAccessories () {
+    this.debug('flush cachedAccessories')
+    this._homebridge.updatePlatformAccessories()
+  }
+
   // Called every second.
   _beat (beat) {
     beat += 1
@@ -221,9 +232,7 @@ class Platform extends homebridgeLib.Delegate {
     }, 1000 - drift)
 
     if (beat % context.saveInterval === 30) {
-      // Persist dynamic platform accessories to cachedAccessories
-      this.debug('flush cachedAccessories')
-      this._homebridge.updatePlatformAccessories()
+      this._flushCachedAccessories()
     }
 
     if (beat % context.checkInterval === 0) {
@@ -255,6 +264,9 @@ class Platform extends homebridgeLib.Delegate {
     this._shuttingDown = true
     this.removeAllListeners('upnpDeviceAlive')
     this.removeAllListeners('upnpDeviceFound')
+    if (this._ui != null && this._ui.abortController != null) {
+      this._ui.abortController.abort()
+    }
     for (const id in this._accessoryDelegates) {
       /** Emitted when Homebridge is shutting down.
         *
@@ -545,6 +557,97 @@ class Platform extends homebridgeLib.Delegate {
       })
   }
 
+  // ===== Dynamic Configuration through Homebridge UI =========================
+
+  /** Handler for requests from the Homebridge Plugin UI Server.
+    * @function Platform#onUiRequest
+    * @async
+    * @abstract
+    * @param {string} method - The request method.
+    * @param {string} resource - The request resource.
+    * @param {*} body - The request body.
+    * @returns {*} - The response body.
+    */
+
+  // Create HTTP server for Homebridge Plugin UI Settings.
+  async _createUiServer () {
+    this._ui = {}
+    this._ui.server = new http.Server()
+    this._ui.server
+      .on('listening', () => {
+        this._ui.port = this._ui.server.address().port
+        this.log('ui server: listening on http://127.0.0.1:%d/', this._ui.port)
+        for (const id in this._accessoryDelegates) {
+          this._accessoryDelegates[id]._context.uiPort = this._ui.port
+        }
+      })
+      .on('error', (error) => { this.error(error) })
+      .on('close', () => {
+        this.debug('ui server: closed port %d', this._ui.port)
+      })
+      .on('request', async (request, response) => {
+        let buffer = ''
+        request.on('data', (data) => { buffer += data })
+        request.on('end', async () => {
+          try {
+            if (buffer !== '') {
+              try {
+                request.body = JSON.parse(buffer)
+              } catch (error) {
+                this.log(
+                  'ui request %s: %s %s %s', ++this._ui.requestId,
+                  request.method, request.url, buffer
+                )
+                this.warn('ui request %d: %s', this._ui.requestId, error.message)
+                response.writeHead(400) // Bad Request
+                response.end()
+                return
+              }
+              this.debug(
+                'ui request %s: %s %s %j', ++this._ui.requestId,
+                request.method, request.url, request.body
+              )
+            } else {
+              this.debug(
+                'ui request %s: %s %s', ++this._ui.requestId,
+                request.method, request.url
+              )
+            }
+            const { status, body } =
+              request.method === 'GET' && request.url === '/ping'
+                ? { status: 200, body: 'pong' }
+                : await this.onUiRequest(
+                  request.method, request.url, request.body
+                )
+            this.debug(
+              'ui request %d: %d %s', this._ui.requestId,
+              status, http.STATUS_CODES[status]
+            )
+            if (status === 200) {
+              this.vdebug('ui request %d: response: %j', this._ui.requestId, body)
+              response.writeHead(status, { 'Content-Type': 'application/json' })
+              response.end(JSON.stringify(body))
+            } else {
+              response.writeHead(status)
+              response.end()
+            }
+          } catch (error) {
+            this.warn('ui request %d: %s', this._ui.requestId, error)
+            response.writeHead(500) // Internal Server Error
+            response.end()
+          }
+        })
+      })
+    this._ui.abortController = new AbortController() // eslint-disable-line no-undef
+    this._ui.requestId = 0
+    this._ui.server.listen({
+      port: 0,
+      host: '127.0.0.1',
+      signal: this._ui.abortController.signal
+    })
+    await events.once(this._ui.server, 'listening')
+  }
+
   // ===== Logging =============================================================
 
   // Do the heavy lifting for debug(), error(), fatal(), log(), and warn(),

package/lib/UiServer.js

@@ -0,0 +1,237 @@
+// homebridge-deconz/homebridge-lib/UiServer.js
+//
+// Library for Homebridge plugins.
+// Copyright © 2022 Erik Baauw. All rights reserved.
+
+'use strict'
+
+const {
+  HomebridgePluginUiServer // , RequestError
+} = require('@homebridge/plugin-ui-utils')
+const { HttpClient, formatError } = require('../index')
+const chalk = require('chalk')
+const fs = require('fs/promises')
+const path = require('path')
+const util = require('util')
+
+/** Server for handling Homebridge Plugin UI requests.
+  *
+  * See {@link https://github.com/homebridge/plugin-ui-utils plugin-ui-utils}.
+  *
+  * The Homebridge Plugin UI Server runs in a separate process, which is spawned
+  * by the Homebridge UI when the plugin _Settings_ are opened.
+  * It implements an {@link HttpClient} to connect to the HTTP server provided
+  * by {@link Platform} to change plugin settings dynamically.
+  *
+  * `UiServer` implemensts the following requests, which are documented as events:
+  * - {@link UiServer#event:get get} - Send a GET request to the plugin instance.
+  * - {@link UiServer#event:put put} - Send a put request to the plugin instance.
+  * - {@link UiServer#event:cachedAccessories cachedAccessories} - Get the
+  * cachedAccessories for a (child) bridge instance.
+  * @extends HomebridgePluginUiServer
+  */
+class UiServer extends HomebridgePluginUiServer {
+  constructor () {
+    super()
+    this.clients = {}
+
+    /** Do a GET request to the plugin instance.
+      * @event UiServer#get
+      * @type {object}
+      * @property {integer} uiPort - The port of the plugin instance UI server.
+      * @property {string} resource - The requested resource.
+      * @returns {*} - The response body.
+      */
+    this.onRequest('get', async (params) => {
+      try {
+        const { uiPort, path } = params
+        const client = this._getClient(uiPort)
+        const { body } = await client.get(path)
+        return body
+      } catch (error) {
+        if (!(error instanceof HttpClient.HttpError)) {
+          this.error(error)
+        }
+      }
+    })
+
+    /** Do a PUT request to the plugin instance.
+      * @event UiServer#put
+      * @param {object}
+      * @property {integer} uiPort - The port of the plugin instance UI server.
+      * @property {string} resource - The requested resource.
+      * @property {*} body - The body of the request.
+      * @returns {HttpResponse} - The response.
+      */
+    this.onRequest('put', async (params) => {
+      try {
+        const { uiPort, path, body } = params
+        const client = this._getClient(uiPort)
+        const response = await client.put(path, JSON.stringify(body))
+        return response
+      } catch (error) {
+        if (!(error instanceof HttpClient.HttpError)) {
+          this.error(error)
+        }
+      }
+    })
+
+    /** Get the cached accessories for a single (child) bridge instance.
+      *
+      * This endpoint is needed because `homebridge.getCachedAccessories()` from
+      * `plugin-ui-utils` doesn't indicate to which child bridge an accessory
+      * belongs.
+      * @event UiServer#cachedAccessories
+      * @type {object}
+      * @property {?string} username - The virtual MAC address of the child
+      * bridge.  Use `null` for the main bridge.
+      * @returns {Object} cachedAccessories - The cached accessories.
+      */
+    this.onRequest('cachedAccessories', async (params) => {
+      try {
+        const { username } = params
+        let fileName = 'cachedAccessories'
+        if (username != null) {
+          fileName += '.' + username.replace(/:/g, '').toUpperCase()
+        }
+        const fullFileName = path.join(
+          this.homebridgeStoragePath,
+          'accessories',
+          fileName
+        )
+        const json = await fs.readFile(fullFileName)
+        const cachedAccessories = JSON.parse(json)
+        return cachedAccessories
+      } catch (error) {
+        this.error(error)
+      }
+      return []
+    })
+  }
+
+  _getClient (uiPort) {
+    if (this.clients[uiPort] == null) {
+      this.clients[uiPort] = new HttpClient({
+        host: 'localhost:' + uiPort,
+        json: true,
+        keepAlive: true
+      })
+      this.clients[uiPort]
+        .on('error', (error) => {
+          this.warn('request %d: %s', error.request.id, error)
+        })
+        .on('request', (request) => {
+          if (request.body == null) {
+            this.debug(
+              'request %d: %s %s', request.id, request.method, request.resource
+            )
+          } else {
+            this.debug(
+              'request %d: %s %s %j', request.id,
+              request.method, request.resource, request.body
+            )
+          }
+        })
+        .on('response', (response) => {
+          this.vdebug(
+            'request %d: response: %j', response.request.id, response.body
+          )
+          this.debug(
+            'request %d: %s %s', response.request.id,
+            response.statusCode, response.statusMessage
+          )
+        })
+    }
+    return this.clients[uiPort]
+  }
+
+  // ===== Logging =============================================================
+
+  /** Print debug message to stdout.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
+    */
+  debug (format, ...args) {
+    this._log({ chalk: chalk.grey }, format, ...args)
+  }
+
+  /** Print error message to stdout.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
+    */
+  error (format, ...args) {
+    this._log({ label: 'error', chalk: chalk.bold.red }, format, ...args)
+  }
+
+  /** Print log message to stdout.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
+    */
+  log (format, ...args) {
+    this._log({}, format, ...args)
+  }
+
+  /** Print verbose debug message to stdout.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
+    */
+  vdebug (format, ...args) {
+    this._log({ chalk: chalk.grey }, format, ...args)
+  }
+
+  /** Print very verbose debug message to stdout.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
+    */
+  vvdebug (format, ...args) {
+    this._log({ chalk: chalk.grey }, format, ...args)
+  }
+
+  /** Print warning message to stdout.
+    * @param {string|Error} format - The printf-style message or an instance of
+    * [Error](https://nodejs.org/dist/latest-v14.x/docs/api/errors.html#errors_class_error).
+    * @param {...string} args - Arguments to the printf-style message.
+    */
+  warn (format, ...args) {
+    this._log({ label: 'warning', chalk: chalk.yellow }, format, ...args)
+  }
+
+  // Do the heavy lifting for debug(), error(), fatal(), log(), and warn(),
+  // taking into account the options, and errors vs exceptions.
+  _log (params = {}, ...args) {
+    const output = process.stdout
+    let message = ''
+
+    // If last argument is Error convert it to string.
+    if (args.length > 0) {
+      let lastArg = args.pop()
+      if (lastArg instanceof Error) {
+        lastArg = formatError(lastArg, true)
+      }
+      args.push(lastArg)
+    }
+
+    // Format message.
+    if (args[0] == null) {
+      message = ''
+    } else if (typeof args[0] === 'string') {
+      message = util.format(...args)
+    } else {
+      message = util.format('%o', ...args)
+    }
+
+    // Handle colours.
+    if (params.chalk != null) {
+      message = params.chalk(message)
+    }
+
+    output.write(message)
+  }
+}
+
+module.exports = UiServer

package/package.json

@@ -3,7 +3,7 @@
   "description": "Library for homebridge plugins",
   "author": "Erik Baauw",
   "license": "Apache-2.0",
-  "version": "5.2.3-0",
+  "version": "5.3.1",
   "keywords": [
     "homekit",
     "homebridge"
@@ -22,9 +22,10 @@
   },
   "engines": {
     "homebridge": "^1.4.0",
-    "node": "^16.14.0"
+    "node": "^16.14.2"
   },
   "dependencies": {
+    "@homebridge/plugin-ui-utils": "~0.0.19",
     "bonjour-hap": "^3.6.3",
     "chalk": "^4.1.2",
     "semver": "^7.3.5"