@tetherto/mdk-worker 0.0.0 → 0.12.1

package/lib/param-validator.js

@@ -0,0 +1,54 @@
+'use strict'
+
+/**
+ * Validate command params against the contract's declared `params` list
+ * ({ name, type, required?, enum?, min?, max? } per mdk-contract.schema.json)
+ * before they reach a handler. The Kernel runs a similar check, but the worker
+ * is reachable on its own RPC key, so it must not trust the caller to have.
+ *
+ * Undeclared keys pass through (the Kernel admits them too); a declared key
+ * that is absent, or null, is only an error when it is `required`.
+ *
+ * Returns null when params are valid, or an ERR_PARAM_* string naming the
+ * first offending param.
+ */
+function validateParams (declared, params) {
+  if (!params || typeof params !== 'object' || Array.isArray(params)) return 'ERR_PARAMS_INVALID'
+  if (!Array.isArray(declared)) return null
+
+  for (const def of declared) {
+    if (!def || typeof def.name !== 'string') continue
+    const value = Object.hasOwn(params, def.name) ? params[def.name] : undefined
+
+    if (value === undefined || value === null) {
+      if (def.required === true) return `ERR_PARAM_REQUIRED: ${def.name}`
+      continue
+    }
+
+    if (def.type && !_isType(value, def.type)) return `ERR_PARAM_TYPE: ${def.name} must be ${def.type}`
+
+    if (Array.isArray(def.enum) && !def.enum.includes(value)) return `ERR_PARAM_ENUM: ${def.name}`
+
+    if (typeof value === 'number') {
+      if (typeof def.min === 'number' && value < def.min) return `ERR_PARAM_RANGE: ${def.name} below min ${def.min}`
+      if (typeof def.max === 'number' && value > def.max) return `ERR_PARAM_RANGE: ${def.name} above max ${def.max}`
+    }
+  }
+  return null
+}
+
+function _isType (value, type) {
+  switch (type) {
+    case 'number': return typeof value === 'number' && Number.isFinite(value)
+    case 'string': return typeof value === 'string'
+    case 'boolean': return typeof value === 'boolean'
+    // The schema has no `array` type, so list params (switchSocket's `args`,
+    // setupPools' `pools`) are declared `object`: arrays must pass.
+    case 'object': return typeof value === 'object'
+    // An unknown declared type is a contract problem, not a caller one; the
+    // schema restricts `type`, so there is nothing safe to check here.
+    default: return true
+  }
+}
+
+module.exports = { validateParams }

package/lib/plugin-loader.js

@@ -0,0 +1,94 @@
+'use strict'
+
+const path = require('path')
+const debug = require('debug')('mdk:worker:plugin-loader')
+
+const SECTIONS = ['telemetry', 'commands']
+
+/**
+ * Validate a Worker Plugin ({ contract, dir, connect, disconnect? }) and
+ * eagerly require every handler declared in the contract. Any missing module,
+ * non-function export, missing `handler` field or duplicate name aborts with
+ * an ERR_PLUGIN_* error — nothing is loaded lazily at request time.
+ *
+ * Returns { contract, publishedContract, handlers, connect, disconnect }.
+ * `publishedContract` is a copy with `handler` fields stripped — handler
+ * paths are plugin-internal and never leave the process on capability pulls.
+ *
+ * `plugin.loadHandler` (optional) replaces the `require` used to bind each
+ * handler: it is called with (absoluteFile, { section, name }) and must return
+ * the function to publish. It is the seam for hosts that bind handlers
+ * per device rather than once per process — contract-loader.js resolves paths
+ * through it without executing them, and worker-runtime-v2.js binds shims.
+ */
+function loadPlugin (plugin) {
+  if (!plugin || typeof plugin !== 'object') throw new Error('ERR_PLUGIN_REQUIRED')
+  if (typeof plugin.connect !== 'function') throw new Error('ERR_PLUGIN_CONNECT_NOT_FUNCTION')
+  if (plugin.disconnect !== undefined && typeof plugin.disconnect !== 'function') {
+    throw new Error('ERR_PLUGIN_DISCONNECT_NOT_FUNCTION')
+  }
+  if (plugin.loadHandler !== undefined && typeof plugin.loadHandler !== 'function') {
+    throw new Error('ERR_PLUGIN_LOAD_HANDLER_NOT_FUNCTION')
+  }
+  if (typeof plugin.dir !== 'string' || !plugin.dir) throw new Error('ERR_PLUGIN_DIR_MISSING')
+
+  const contract = plugin.contract
+  if (!contract || typeof contract !== 'object') throw new Error('ERR_PLUGIN_CONTRACT_MISSING')
+  // The Kernel terminates workers whose capability payload lacks either object.
+  if (!contract.metadata || typeof contract.metadata !== 'object') throw new Error('ERR_PLUGIN_CONTRACT_METADATA_MISSING')
+  if (!contract.capabilities || typeof contract.capabilities !== 'object') throw new Error('ERR_PLUGIN_CONTRACT_CAPABILITIES_MISSING')
+
+  const handlers = {}
+  for (const section of SECTIONS) {
+    handlers[section] = _loadSection(contract, plugin.dir, section, plugin.loadHandler || require)
+  }
+
+  return {
+    contract,
+    publishedContract: _stripHandlers(contract),
+    handlers,
+    connect: plugin.connect,
+    disconnect: plugin.disconnect || null
+  }
+}
+
+function _loadSection (contract, dir, section, load) {
+  const entries = contract.capabilities[section] || []
+  if (!Array.isArray(entries)) throw new Error(`ERR_PLUGIN_SECTION_NOT_ARRAY: ${section}`)
+
+  const loaded = new Map()
+  for (const entry of entries) {
+    if (!entry || typeof entry.name !== 'string' || !entry.name) {
+      throw new Error(`ERR_PLUGIN_ENTRY_NAME_MISSING: ${section}`)
+    }
+    if (loaded.has(entry.name)) throw new Error(`ERR_PLUGIN_DUPLICATE_NAME: ${section}.${entry.name}`)
+    if (typeof entry.handler !== 'string' || !entry.handler) {
+      throw new Error(`ERR_PLUGIN_HANDLER_MISSING: ${section}.${entry.name}`)
+    }
+
+    const file = path.resolve(dir, entry.handler)
+    let fn
+    try {
+      fn = load(file, { section, name: entry.name })
+    } catch (err) {
+      throw new Error(`ERR_PLUGIN_HANDLER_NOT_FOUND: ${section}.${entry.name}: ${file}: ${err.message}`)
+    }
+    if (typeof fn !== 'function') {
+      throw new Error(`ERR_PLUGIN_HANDLER_NOT_FUNCTION: ${section}.${entry.name}: ${file}`)
+    }
+
+    loaded.set(entry.name, fn)
+    debug('loaded %s handler %s from %s', section, entry.name, entry.handler)
+  }
+  return loaded
+}
+
+function _stripHandlers (contract) {
+  const copy = JSON.parse(JSON.stringify(contract))
+  for (const section of SECTIONS) {
+    for (const entry of copy.capabilities[section] || []) delete entry.handler
+  }
+  return copy
+}
+
+module.exports = { loadPlugin }

package/lib/service-builtins.js

@@ -0,0 +1,268 @@
+'use strict'
+
+/**
+ * Legacy worker-infra surface served by the runtime from injected services —
+ * the query types and commands the adapter-era workers answered from the
+ * manager's store rather than the device. Each entry is active only when its backing
+ * service is present in the runtime's `services` object:
+ *
+ *   logHistory   → telemetry `logs`, `historical_logs`, `logs_multi`
+ *   settings     → telemetry `settings`, command `saveSettings`
+ *   provisioning → telemetry `thing_config`, `list`, `count`, `config`,
+ *                  commands `registerThing`, `updateThing`, `forgetThings`
+ *   stats        → telemetry `stats`
+ *   comments     → commands `saveComment`, `editComment`, `deleteComment`
+ *   actions      → `write.calls.request`
+ *   pool         → telemetry `ext_data` (scheduler-driven pool workers)
+ *
+ * These never reach plugin handlers: they are worker infrastructure, not
+ * device translation.
+ *
+ * Telemetry handlers receive (services, deviceId, params, rt) where rt is
+ * runtime context: { workerId, metadata, deviceIds }. When provisioning is
+ * present, `list` shadows the runtime's bare devices list with the legacy
+ * thing list ({ things: [{ id, code, type, tags, info, comments, last? }] })
+ * that adapter-era gateways read.
+ */
+
+// Upper bound on caller-supplied device id lists (logs_multi, stats): each
+// id costs a store walk, so an unbounded list is a cheap way to pin the worker.
+const MAX_DEVICE_IDS = 1000
+
+const TELEMETRY_BUILTINS = {
+  logs: {
+    service: 'logHistory',
+    handle: async (services, deviceId, params) => ({
+      logs: await services.logHistory.tailLog(_addressed(params, 'thingId', deviceId))
+    })
+  },
+  historical_logs: {
+    service: 'logHistory',
+    handle: async (services, deviceId, params) => ({
+      logs: await services.logHistory.getHistoricalLogs(_addressed(params, 'thingId', deviceId))
+    })
+  },
+  logs_multi: {
+    service: 'logHistory',
+    handle: async (services, deviceId, params, rt) => {
+      const deviceIds = params.deviceIds !== undefined
+        ? _deviceIdList(params.deviceIds)
+        : (deviceId ? [deviceId] : rt.deviceIds)
+      const allLogs = []
+      for (const id of deviceIds) {
+        try {
+          const logs = await services.logHistory.tailLog({ ...params, thingId: id })
+          allLogs.push(...(Array.isArray(logs) ? logs : []))
+        } catch (e) {
+          // one unreadable device log must not fail the multi-pull
+        }
+      }
+      return { logs: allLogs }
+    }
+  },
+  settings: {
+    service: 'settings',
+    handle: async (services) => ({
+      settings: await services.settings.getSettings()
+    })
+  },
+  thing_config: {
+    service: 'provisioning',
+    handle: async (services, deviceId, params) => ({
+      config: await services.provisioning.getThingConf(_addressed(params, 'thingId', deviceId))
+    })
+  },
+  list: {
+    service: 'provisioning',
+    handle: async (services, deviceId, params, rt) => {
+      const devices = services.provisioning.listDevices({
+        ...params,
+        offset: params.offset ?? 0,
+        limit: params.limit ?? 100
+      })
+      const things = devices.map((dev) => ({
+        id: dev.id,
+        code: dev.code,
+        type: dev.type,
+        tags: dev.tags,
+        info: dev.info,
+        rack: rt.workerId,
+        comments: dev.comments,
+        address: dev.opts && dev.opts.address,
+        port: dev.opts && dev.opts.port,
+        ...(params.status && services.snaps ? { last: services.snaps.getLast(dev.id) || {} } : {})
+      }))
+      return { things }
+    }
+  },
+  count: {
+    service: 'provisioning',
+    handle: async (services) => ({
+      count: services.provisioning.listDeviceIds().length
+    })
+  },
+  config: {
+    service: 'provisioning',
+    handle: async (services, deviceId, params, rt) => ({
+      config: { workerId: rt.workerId, contract: rt.metadata }
+    })
+  },
+  stats: {
+    service: 'stats',
+    handle: async (services, deviceId, params) => ({
+      stats: await services.stats.aggrStats(
+        params.deviceIds === undefined ? undefined : _deviceIdList(params.deviceIds),
+        params.opts || {}
+      )
+    })
+  },
+  ext_data: {
+    service: 'pool',
+    handle: async (services, deviceId, params) => ({
+      extData: await services.pool.getWrkExtData({ query: params })
+    })
+  }
+}
+
+const COMMAND_BUILTINS = {
+  registerThing: {
+    service: 'provisioning',
+    handle: (services, deviceId, params) => services.provisioning.registerThing(params)
+  },
+  updateThing: {
+    service: 'provisioning',
+    handle: (services, deviceId, params) => services.provisioning.updateThing(_addressed(params, 'id', deviceId))
+  },
+  forgetThings: {
+    service: 'provisioning',
+    handle: async (services, deviceId, params) => ({ removed: await services.provisioning.forgetThings(params) })
+  },
+  saveSettings: {
+    service: 'settings',
+    handle: (services, deviceId, params) => services.settings.saveSettingsEntries(params)
+  },
+  saveComment: {
+    service: 'comments',
+    handle: (services, deviceId, params) => services.comments.saveThingComment(_addressed(params, 'thingId', deviceId))
+  },
+  editComment: {
+    service: 'comments',
+    handle: (services, deviceId, params) => services.comments.editThingComment(_addressed(params, 'thingId', deviceId))
+  },
+  deleteComment: {
+    service: 'comments',
+    handle: (services, deviceId, params) => services.comments.deleteThingComment(_addressed(params, 'thingId', deviceId))
+  }
+}
+
+// Contract entries for the built-in commands, merged into the published
+// capability payload — the Kernel dispatcher rejects commands that are not
+// declared (ERR_COMMAND_NOT_IN_CAPABILITIES).
+const COMMAND_CONTRACT_ENTRIES = {
+  registerThing: {
+    name: 'registerThing',
+    description: 'Register a new device config. Takes effect on runtime restart.',
+    params: [
+      { name: 'info', type: 'object' },
+      { name: 'opts', type: 'object' }
+    ]
+  },
+  updateThing: {
+    name: 'updateThing',
+    description: 'Update a persisted device config. Takes effect on runtime restart.',
+    params: [
+      { name: 'info', type: 'object' },
+      { name: 'opts', type: 'object' }
+    ]
+  },
+  forgetThings: {
+    name: 'forgetThings',
+    description: 'Remove persisted device configs. Takes effect on runtime restart.',
+    params: [
+      { name: 'query', type: 'object' }
+    ]
+  },
+  saveSettings: {
+    name: 'saveSettings',
+    description: 'Update worker settings.',
+    params: []
+  },
+  saveComment: {
+    name: 'saveComment',
+    description: 'Add a comment to a device.',
+    params: [
+      { name: 'comment', type: 'string' },
+      { name: 'user', type: 'string' }
+    ]
+  },
+  editComment: {
+    name: 'editComment',
+    description: 'Edit an existing comment.',
+    params: [
+      { name: 'id', type: 'string' },
+      { name: 'comment', type: 'string' },
+      { name: 'user', type: 'string' }
+    ]
+  },
+  deleteComment: {
+    name: 'deleteComment',
+    description: 'Delete a comment.',
+    params: [
+      { name: 'id', type: 'string' },
+      { name: 'user', type: 'string' }
+    ]
+  }
+}
+
+// The envelope's deviceId addresses the request, so it wins over a same-named
+// key smuggled into params. Worker-scoped requests (deviceId null) keep the
+// caller's key, which is how provisioning names the device it updates.
+function _addressed (params, key, deviceId) {
+  return deviceId ? { ...params, [key]: deviceId } : { ...params }
+}
+
+function _deviceIdList (ids) {
+  if (!Array.isArray(ids) || !ids.every((id) => typeof id === 'string')) {
+    throw new Error('ERR_PARAM_TYPE: deviceIds must be an array of strings')
+  }
+  if (ids.length > MAX_DEVICE_IDS) throw new Error(`ERR_PARAM_RANGE: deviceIds above max ${MAX_DEVICE_IDS}`)
+  return ids
+}
+
+function telemetryBuiltin (services, type) {
+  if (!services) return null
+  const entry = Object.hasOwn(TELEMETRY_BUILTINS, type) ? TELEMETRY_BUILTINS[type] : null
+  return entry && services[entry.service] ? entry : null
+}
+
+function commandBuiltin (services, command) {
+  if (!services) return null
+  const entry = Object.hasOwn(COMMAND_BUILTINS, command) ? COMMAND_BUILTINS[command] : null
+  return entry && services[entry.service] ? entry : null
+}
+
+/**
+ * Returns the contract to publish: the plugin contract plus one command
+ * entry per active built-in. The input contract is not mutated; without
+ * services (or when every built-in is inactive) it is returned as-is.
+ */
+function mergeBuiltinCommands (contract, services) {
+  if (!services) return contract
+
+  const extra = Object.keys(COMMAND_BUILTINS)
+    .filter((name) => commandBuiltin(services, name))
+    .map((name) => COMMAND_CONTRACT_ENTRIES[name])
+  if (!extra.length) return contract
+
+  const copy = JSON.parse(JSON.stringify(contract))
+  copy.capabilities.commands = [...(copy.capabilities.commands || []), ...extra]
+  return copy
+}
+
+// Declared params of an active built-in command, for the runtime's param
+// validation (the same list the capability payload publishes).
+function builtinCommandParams (command) {
+  return Object.hasOwn(COMMAND_CONTRACT_ENTRIES, command) ? COMMAND_CONTRACT_ENTRIES[command].params : null
+}
+
+module.exports = { telemetryBuiltin, commandBuiltin, mergeBuiltinCommands, builtinCommandParams, MAX_DEVICE_IDS }

package/lib/worker-runtime-v2.js

@@ -0,0 +1,113 @@
+'use strict'
+
+const createLogger = require('debug')
+const debug = createLogger('mdk:worker:runtime-v2')
+const WorkerRuntime = require('./worker-runtime')
+const { loadContract } = require('./contract-loader')
+const { createInstance } = require('./instance-loader')
+
+/**
+ * Host for a directory-loaded Worker Plugin — an mdk-contract.json plus handler
+ * files, with no module to require and no connect() to call:
+ *
+ *   const runtime = new WorkerRuntimeV2(pkgDir, { workerId, kernelTopic, devices, env, config, storeDir })
+ *
+ * One HRPC server and one DHT identity for the process regardless of device
+ * count, as in v1; what fans out per device is the plugin's module registry.
+ * Pass `storeDir` (or `store`) so the DHT/RPC seeds — and therefore the
+ * public key published to the Kernel — survive restarts.
+ * Each device gets its own instance (see instance-loader.js), so handlers are
+ * plain (params) functions that read `{ id, opts, env, config }` from the
+ * ambient '@tetherto/mdk-worker/device' instead of taking a ctx argument. The
+ * device list is fixed at construction.
+ *
+ * v1 is inherited whole — deviceId routing, the pull set, envelope wrapping,
+ * param normalization, the service built-ins — because the contract's handler
+ * table is filled with shims that resolve the addressed device's instance.
+ *
+ * Two behavior differences from v1: there is no boot-time probe, so every
+ * declared device reports `online` and an unreachable one surfaces as an error
+ * inside the telemetry payload rather than ERR_DEVICE_UNAVAILABLE; and there is
+ * no disconnect, so whatever a plugin opens at load time lives until the
+ * process exits.
+ *
+ * A builtin `health` telemetry channel is also registered into v1's own
+ * handler table (see the constructor) so every contract-first plugin gets a
+ * `TELEMETRY_PULL { query: { type: 'health' } }` channel with zero contract
+ * changes, answered by `entry.instance.telemetry.get('health')` per device
+ * (auto-injected by instance-loader.js). It routes through the exact same
+ * dispatch v1 already uses for any real telemetry channel — no special
+ * casing here.
+ */
+class WorkerRuntimeV2 extends WorkerRuntime {
+  constructor (dir, opts) {
+    opts = opts || {}
+    if (typeof dir !== 'string' || !dir) throw new Error('ERR_WORKER_DIR_REQUIRED')
+
+    const contract = loadContract(dir)
+    // The shims are v1's handler table, so they must be built during super() —
+    // before `this` exists. They reach the runtime through this holder.
+    const host = {}
+    super({
+      contract: contract.contract,
+      dir,
+      connect: _noConnect,
+      loadHandler: (file, { section, name }) => (ctx, params) => host.runtime._invoke(section, name, ctx, params)
+    }, opts)
+    host.runtime = this
+
+    this._dir = dir
+    this._entries = contract.entries
+    // Resolved by the CLI from mdk.yaml and shared by every device; `config` is
+    // the plugin-defined opaque block, device connection details live in opts.
+    this._env = Object.freeze({ ...(opts.env || {}) })
+    this._config = Object.freeze({ ...(opts.config || {}) })
+
+    // Builtin `health` channel, registered the same way a real contract
+    // entry would be: a shim in v1's own handler table that resolves through
+    // _invoke() to the addressed device's instance. `this` fully exists here
+    // (after super()), so no `host` indirection is needed. Guarded so a
+    // plugin that legitimately declares its own `health` channel keeps it.
+    if (!this._plugin.handlers.telemetry.has('health')) {
+      this._plugin.handlers.telemetry.set('health', (ctx, params) => this._invoke('telemetry', 'health', ctx, params))
+    }
+  }
+
+  async _openContexts () {
+    for (const entry of this._devices.values()) {
+      if (entry.status === 'online') continue
+
+      const device = Object.freeze({
+        id: entry.deviceId,
+        opts: Object.freeze({ ...entry.config }),
+        env: this._env,
+        config: this._config,
+        workerId: this.workerId,
+        logger: createLogger(`mdk:worker:${this.workerId}:${entry.deviceId}`)
+      })
+      // createInstance auto-registers the builtin `health` telemetry entry
+      // (see instance-loader.js's BUILTIN_TELEMETRY) into entry.instance
+      // itself — there is no separate runtime-level snapshot to keep here.
+      entry.instance = createInstance({ dir: this._dir, entries: this._entries, device })
+      // v1 dispatches fn(ctx, params) and the shim routes on ctx.deviceId; the
+      // plugin sees none of this. No `device` key: there is nothing to connect.
+      entry.ctx = Object.freeze({ deviceId: entry.deviceId, config: entry.config, services: this.services })
+      entry.status = 'online'
+      entry.error = null
+      debug('instance opened: %s', entry.deviceId)
+    }
+  }
+
+  _invoke (section, name, ctx, params) {
+    const deviceId = ctx ? ctx.deviceId : null
+    const entry = this._devices.get(deviceId)
+    if (!entry || !entry.instance) throw new Error(`ERR_DEVICE_INSTANCE_MISSING: ${deviceId}`)
+    return entry.instance[section].get(name)(params)
+  }
+}
+
+function _noConnect () {
+  throw new Error('ERR_CONNECT_NOT_SUPPORTED')
+}
+
+module.exports = WorkerRuntimeV2