signalk-automation-plugin 0.0.1

package/lib/yaml.js

@@ -0,0 +1,204 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const yaml = require('js-yaml')
+
+const ON_START = ['restore', 'default', 'none']
+const HELPER_TYPES = ['boolean', 'number', 'string', 'select']
+
+function loadYamlDir (dir) {
+  const result = emptyDoc()
+  if (!dir || !fs.existsSync(dir)) {
+    return result
+  }
+  const files = fs
+    .readdirSync(dir)
+    .filter((f) => /\.ya?ml$/i.test(f))
+    .sort()
+  for (const file of files) {
+    const full = path.join(dir, file)
+    let raw
+    try {
+      raw = fs.readFileSync(full, 'utf8')
+    } catch (err) {
+      result.errors.push({ file, message: err.message })
+      continue
+    }
+    const loaded = loadYamlText(raw, file)
+    mergeDoc(result, loaded)
+  }
+  return result
+}
+
+function loadYamlText (text, file) {
+  const result = emptyDoc()
+  result.files.push(file)
+  let parsed
+  try {
+    parsed = yaml.load(text) || {}
+  } catch (err) {
+    result.errors.push({ file, message: err.message })
+    return result
+  }
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+    result.errors.push({ file, message: 'YAML root must be a mapping' })
+    return result
+  }
+  result.rawText[file] = text
+  mergeHelpers(result, parsed.helpers, file)
+  mergeZones(result, parsed.zones, file)
+  mergeAutomations(result, parsed.automations, file)
+  return result
+}
+
+function emptyDoc () {
+  return {
+    helpers: {},
+    zones: {},
+    automations: [],
+    errors: [],
+    files: [],
+    rawText: {}
+  }
+}
+
+function mergeDoc (into, other) {
+  into.files.push.apply(into.files, other.files)
+  into.errors.push.apply(into.errors, other.errors)
+  Object.assign(into.rawText, other.rawText)
+  for (const [id, def] of Object.entries(other.helpers)) {
+    if (into.helpers[id]) {
+      into.errors.push({ file: def.file, message: 'Duplicate helper id: ' + id })
+      continue
+    }
+    into.helpers[id] = def
+  }
+  for (const [id, def] of Object.entries(other.zones)) {
+    if (into.zones[id]) {
+      into.errors.push({ file: def.file, message: 'Duplicate zone id: ' + id })
+      continue
+    }
+    into.zones[id] = def
+  }
+  const seen = new Set(into.automations.map((a) => a.id))
+  for (const auto of other.automations) {
+    if (seen.has(auto.id)) {
+      into.errors.push({ file: auto.file, message: 'Duplicate automation id: ' + auto.id })
+      continue
+    }
+    seen.add(auto.id)
+    into.automations.push(auto)
+  }
+}
+
+function mergeHelpers (result, helpers, file) {
+  if (helpers == null) return
+  if (typeof helpers !== 'object' || Array.isArray(helpers)) {
+    result.errors.push({ file, message: 'helpers must be a mapping' })
+    return
+  }
+  for (const [id, raw] of Object.entries(helpers)) {
+    const def = normalizeHelper(id, raw, file)
+    if (def.error) {
+      result.errors.push({ file, message: def.error })
+      continue
+    }
+    result.helpers[id] = def
+  }
+}
+
+function normalizeHelper (id, raw, file) {
+  const spec = raw && typeof raw === 'object' ? raw : {}
+  const type = spec.type || 'boolean'
+  if (!HELPER_TYPES.includes(type)) {
+    return { error: 'Helper ' + id + ': unknown type ' + type }
+  }
+  const onStart = spec.on_start || spec.onStart || 'none'
+  if (!ON_START.includes(onStart)) {
+    return { error: 'Helper ' + id + ': on_start must be restore|default|none' }
+  }
+  if (type === 'select' && !Array.isArray(spec.options)) {
+    return { error: 'Helper ' + id + ': select requires options' }
+  }
+  return {
+    id,
+    file,
+    type,
+    name: spec.name || id,
+    default: spec.default,
+    on_start: onStart,
+    options: spec.options || [],
+    latch_on_external_put: spec.latch_on_external_put || spec.latchOnExternalPut || null
+  }
+}
+
+function mergeZones (result, zones, file) {
+  if (zones == null) return
+  if (typeof zones !== 'object' || Array.isArray(zones)) {
+    result.errors.push({ file, message: 'zones must be a mapping' })
+    return
+  }
+  for (const [id, raw] of Object.entries(zones)) {
+    const spec = raw || {}
+    const lat = Number(spec.lat)
+    const lon = Number(spec.lon)
+    const radius = Number(spec.radius)
+    if (![lat, lon, radius].every(Number.isFinite)) {
+      result.errors.push({ file, message: 'Zone ' + id + ' needs lat, lon, radius' })
+      continue
+    }
+    result.zones[id] = { id, file, lat, lon, radius, name: spec.name || id }
+  }
+}
+
+function mergeAutomations (result, list, file) {
+  if (list == null) return
+  if (!Array.isArray(list)) {
+    result.errors.push({ file, message: 'automations must be a list' })
+    return
+  }
+  for (const raw of list) {
+    if (!raw || typeof raw !== 'object' || !raw.id) {
+      result.errors.push({ file, message: 'Automation needs an id' })
+      continue
+    }
+    result.automations.push({
+      id: String(raw.id),
+      file,
+      alias: raw.alias || raw.id,
+      enabled: raw.enabled !== false,
+      trigger: asArray(raw.trigger),
+      condition: asArray(raw.condition),
+      action: asArray(raw.action),
+      choose: Array.isArray(raw.choose) ? raw.choose : [],
+      debounceMs: raw.debounceMs || 0,
+      edge: raw.edge || 'rising'
+    })
+  }
+}
+
+function asArray (value) {
+  if (value == null) return []
+  return Array.isArray(value) ? value : [value]
+}
+
+function combinedYaml (doc) {
+  const parts = []
+  for (const file of doc.files) {
+    const text = doc.rawText[file]
+    if (text) {
+      parts.push('# file: ' + file + '\n' + text.trim())
+    }
+  }
+  return parts.join('\n\n---\n\n')
+}
+
+module.exports = {
+  ON_START,
+  HELPER_TYPES,
+  loadYamlDir,
+  loadYamlText,
+  emptyDoc,
+  combinedYaml
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "signalk-automation-plugin",
+  "version": "0.0.1",
+  "description": "Home Assistant-like YAML automations for Signal K",
+  "main": "plugin/index.js",
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-webapp",
+    "signalk-category-digital-switching",
+    "automation"
+  ],
+  "license": "ISC",
+  "author": "hans@defect.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/htool/signalk-automation-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/htool/signalk-automation-plugin/issues"
+  },
+  "homepage": "https://github.com/htool/signalk-automation-plugin#readme",
+  "signalk": {
+    "displayName": "Automations"
+  },
+  "signalk-plugin-enabled-by-default": false,
+  "files": [
+    "plugin",
+    "lib",
+    "public",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js && node scripts/test-npm-publish-check.js"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  }
+}

package/plugin/index.js

@@ -0,0 +1,340 @@
+'use strict'
+
+const path = require('path')
+const { Runtime } = require('../lib/runtime')
+const helpers = require('../lib/helpers')
+
+const PLUGIN_ID = 'signalk-automation-plugin'
+
+function sendJson (res, body, status) {
+  res.statusCode = status || 200
+  res.setHeader('Content-Type', 'application/json')
+  res.end(JSON.stringify(body))
+}
+
+function readJson (req) {
+  return new Promise((resolve, reject) => {
+    if (req.body && typeof req.body === 'object' && !Buffer.isBuffer(req.body)) {
+      resolve(req.body)
+      return
+    }
+    let raw = ''
+    req.on('data', (c) => {
+      raw += c
+      if (raw.length > 1e6) {
+        reject(new Error('body too large'))
+      }
+    })
+    req.on('end', () => {
+      if (!raw) {
+        resolve({})
+        return
+      }
+      try {
+        resolve(JSON.parse(raw))
+      } catch (err) {
+        reject(err)
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+module.exports = function (app) {
+  const plugin = {}
+  plugin.id = PLUGIN_ID
+  plugin.name = 'Automations'
+  plugin.description =
+    'YAML automations for Signal K: helpers, path triggers, PUT/notify/script actions, git-live YAML.'
+
+  let runtime = null
+  let options = {}
+  const timers = []
+  const unsubscribes = []
+
+  plugin.schema = {
+    type: 'object',
+    properties: {
+      automationsDir: {
+        type: 'string',
+        title: 'Automations git / YAML directory',
+        description: 'Folder with *.yaml (preferably a git repo). Live snapshot is stored in plugin data.',
+        default: ''
+      },
+      scriptsDir: {
+        type: 'string',
+        title: 'Allowed scripts directory',
+        description: 'run: actions may only execute files under this path (relative paths in YAML).',
+        default: ''
+      },
+      traceCount: {
+        type: 'number',
+        title: 'Decision records to keep per automation',
+        default: 20,
+        minimum: 1
+      },
+      scriptTimeoutSeconds: {
+        type: 'number',
+        title: 'Script timeout (seconds)',
+        default: 30,
+        minimum: 1
+      }
+    }
+  }
+
+  function snapshot () {
+    if (!runtime) {
+      return {
+        started: false,
+        automations: [],
+        helpers: [],
+        errors: [],
+        yaml: '',
+        commits: []
+      }
+    }
+    return runtime.snapshot()
+  }
+
+  function requireRuntime (res) {
+    if (!runtime) {
+      sendJson(res, { error: 'plugin not started' }, 409)
+      return null
+    }
+    return runtime
+  }
+
+  async function handleLive (req, res) {
+    const rt = requireRuntime(res)
+    if (!rt) return
+    try {
+      const body = await readJson(req)
+      const snap = rt.activateCommit(body.sha)
+      sendJson(res, snap)
+    } catch (err) {
+      sendJson(res, { error: err.message }, 400)
+    }
+  }
+
+  async function handleEnabled (req, res, id) {
+    const rt = requireRuntime(res)
+    if (!rt) return
+    try {
+      const body = await readJson(req)
+      rt.setEnabled(id, body.enabled)
+      sendJson(res, { id, enabled: rt.isEnabled({ id, enabled: true }) && body.enabled })
+    } catch (err) {
+      sendJson(res, { error: err.message }, 400)
+    }
+  }
+
+  async function handleHelperPut (req, res, id) {
+    const rt = requireRuntime(res)
+    if (!rt) return
+    try {
+      const body = await readJson(req)
+      const value = rt.setHelper(id, body.value)
+      emitHelper(id, value)
+      sendJson(res, { id, value })
+    } catch (err) {
+      sendJson(res, { error: err.message }, 400)
+    }
+  }
+
+  function handleHelperReset (req, res, id) {
+    const rt = requireRuntime(res)
+    if (!rt) return
+    try {
+      const value = rt.resetHelper(id)
+      emitHelper(id, value)
+      sendJson(res, { id, value: value == null ? null : value })
+    } catch (err) {
+      sendJson(res, { error: err.message }, 400)
+    }
+  }
+
+  plugin.registerWithRouter = function (router) {
+    router.get('/status', (req, res) => sendJson(res, snapshot()))
+    router.get('/yaml', (req, res) => sendJson(res, { yaml: snapshot().yaml, sha: snapshot().activeSha }))
+    router.get('/commits', (req, res) => sendJson(res, { commits: snapshot().commits, activeSha: snapshot().activeSha }))
+    router.get('/automations/:id/traces', (req, res) => {
+      const rt = requireRuntime(res)
+      if (!rt) return
+      sendJson(res, { id: req.params.id, traces: rt.traces(req.params.id) })
+    })
+    router.post('/live', (req, res) => {
+      handleLive(req, res)
+    })
+    router.post('/automations/:id/enabled', (req, res) => {
+      handleEnabled(req, res, req.params.id)
+    })
+    router.put('/helpers/:id', (req, res) => {
+      handleHelperPut(req, res, req.params.id)
+    })
+    router.post('/helpers/:id/reset', (req, res) => {
+      handleHelperReset(req, res, req.params.id)
+    })
+  }
+
+  plugin.signalKApiRoutes = function (router) {
+    const prefix = '/' + PLUGIN_ID
+    router.get(prefix + '/status', (req, res) => sendJson(res, snapshot()))
+    router.get(prefix + '/yaml', (req, res) =>
+      sendJson(res, { yaml: snapshot().yaml, sha: snapshot().activeSha })
+    )
+    router.get(prefix + '/commits', (req, res) =>
+      sendJson(res, { commits: snapshot().commits, activeSha: snapshot().activeSha })
+    )
+    router.get(prefix + '/automations/:id/traces', (req, res) => {
+      if (!runtime) {
+        sendJson(res, { error: 'plugin not started' }, 409)
+        return
+      }
+      sendJson(res, { id: req.params.id, traces: runtime.traces(req.params.id) })
+    })
+    return router
+  }
+
+  function emitHelper (id, value) {
+    const def = runtime && runtime.doc.helpers[id]
+    app.handleMessage(PLUGIN_ID, {
+      updates: [
+        {
+          values: [{ path: helpers.helperPath(id), value: value == null ? null : value }],
+          meta: [
+            {
+              path: helpers.helperPath(id),
+              value: {
+                displayName: def ? def.name : id,
+                supportsPut: true
+              }
+            }
+          ]
+        }
+      ]
+    })
+  }
+
+  function putPath (p, value) {
+    return new Promise((resolve, reject) => {
+      if (typeof app.putSelfPath === 'function') {
+        app.putSelfPath(p, value, (err) => (err ? reject(err) : resolve()))
+        return
+      }
+      app.handleMessage(PLUGIN_ID, {
+        updates: [{ values: [{ path: p, value }] }]
+      })
+      resolve()
+    })
+  }
+
+  function notify (p, state, message) {
+    const npath = String(p).startsWith('notifications.') ? p : 'notifications.' + p
+    app.handleMessage(PLUGIN_ID, {
+      updates: [
+        {
+          values: [
+            {
+              path: npath,
+              value: {
+                state: state || 'alert',
+                message: message || '',
+                method: ['visual', 'sound']
+              }
+            }
+          ]
+        }
+      ]
+    })
+  }
+
+  plugin.start = function (opts) {
+    options = opts || {}
+    const dataDir =
+      (app.getDataDirPath && app.getDataDirPath()) ||
+      path.join(process.cwd(), 'plugin-data', PLUGIN_ID)
+    fsMkdir(dataDir)
+
+    runtime = new Runtime({
+      app,
+      pluginId: PLUGIN_ID,
+      dataDir,
+      automationsDir: options.automationsDir || '',
+      scriptsDir: options.scriptsDir || '',
+      traceCount: options.traceCount,
+      scriptTimeoutSeconds: options.scriptTimeoutSeconds,
+      put: putPath,
+      notify,
+      log: { debug: app.debug ? app.debug.bind(app) : () => {}, error: app.error ? app.error.bind(app) : console.error }
+    })
+    runtime.load()
+
+    for (const [id, value] of Object.entries(runtime.helperValues)) {
+      emitHelper(id, value)
+      if (typeof app.registerPutHandler === 'function') {
+        app.registerPutHandler('vessels.self', helpers.helperPath(id), (context, p, v, cb) => {
+          try {
+            const next = runtime.setHelper(id, v)
+            emitHelper(id, next)
+            if (cb) cb({ state: 'COMPLETED' })
+          } catch (err) {
+            if (cb) cb({ state: 'COMPLETED', statusCode: 400, message: err.message })
+          }
+        })
+      }
+    }
+
+    const paths = require('../lib/engine').collectPaths(runtime.doc)
+    if (paths.length && app.subscriptionmanager) {
+      app.subscriptionmanager.subscribe(
+        {
+          context: 'vessels.self',
+          subscribe: paths.map((p) => ({ path: p }))
+        },
+        unsubscribes,
+        (err) => app.error && app.error(err),
+        (delta) => {
+          const src = delta && delta.updates && delta.updates[0] && delta.updates[0].$source
+          ;(delta.updates || []).forEach((u) => {
+            const source = u.$source || src
+            ;(u.values || []).forEach((v) => {
+              runtime.handlePathChange(v.path, v.value, source).catch((err) => {
+                if (app.error) app.error(err)
+              })
+            })
+          })
+        }
+      )
+    }
+
+    timers.push(setInterval(() => {
+      runtime.tickSchedule().catch((err) => app.error && app.error(err))
+    }, 15000))
+
+    if (app.setPluginStatus) {
+      const n = runtime.doc.automations.length
+      const err = runtime.doc.errors.length
+      app.setPluginStatus(n + ' automations' + (err ? ', ' + err + ' YAML error(s)' : ''))
+    }
+  }
+
+  plugin.stop = function () {
+    timers.splice(0).forEach((t) => clearInterval(t))
+    unsubscribes.splice(0).forEach((f) => {
+      try {
+        f()
+      } catch (_) {}
+    })
+    runtime = null
+  }
+
+  return plugin
+}
+
+function fsMkdir (dir) {
+  const fs = require('fs')
+  fs.mkdirSync(dir, { recursive: true })
+}
+
+module.exports.app = 'app'
+module.exports.options = 'options'