dsh-device-fleet 0.0.0-stage → 0.1.0-dev.10

package/src/net/discovery.js

@@ -0,0 +1,105 @@
+// LAN discovery over UDP multicast. Announcements carry only a fleet hash,
+// device id, display name and the direct listening port; the real trust
+// decision happens in the secure-channel handshake.
+import dgram from 'node:dgram'
+import { EventEmitter } from 'node:events'
+import { fleetHash } from './identity.js'
+
+export const DEFAULT_DISCOVERY_GROUP = '239.255.42.99'
+export const DEFAULT_DISCOVERY_PORT = 47833
+
+export class LanDiscovery extends EventEmitter {
+  constructor({
+    fleetId,
+    deviceId,
+    name = 'device',
+    directPort,
+    group = DEFAULT_DISCOVERY_GROUP,
+    port = DEFAULT_DISCOVERY_PORT,
+    intervalMs = 3_000,
+  }) {
+    super()
+    this.fleetId = fleetId
+    this.deviceId = deviceId
+    this.name = name
+    this.directPort = directPort
+    this.group = group
+    this.port = port
+    this.intervalMs = intervalMs
+    this.socket = null
+    this.timer = null
+    this.closed = false
+    this.peers = new Map()
+  }
+
+  start() {
+    if (this.socket) return
+    this.socket = dgram.createSocket({ type: 'udp4', reuseAddr: true })
+    this.socket.on('message', (buffer, rinfo) => this.onMessage(buffer, rinfo))
+    this.socket.on('error', (error) => this.emit('error', error))
+    this.socket.bind(this.port, () => {
+      try {
+        this.socket.addMembership(this.group)
+        this.socket.setMulticastTTL(1)
+        this.socket.setMulticastLoopback(true)
+      } catch (error) {
+        this.emit('error', error)
+      }
+      this.announce()
+      this.timer = setInterval(() => this.announce(), this.intervalMs)
+      this.timer.unref?.()
+      this.emit('listening', { group: this.group, port: this.port })
+    })
+  }
+
+  announce() {
+    if (!this.socket || this.closed) return
+    const payload = Buffer.from(
+      JSON.stringify({
+        v: 1,
+        fleetHash: fleetHash(this.fleetId),
+        deviceId: this.deviceId,
+        name: this.name,
+        port: this.directPort,
+        ts: Date.now(),
+      }),
+    )
+    this.socket.send(payload, 0, payload.length, this.port, this.group, () => {})
+  }
+
+  onMessage(buffer, rinfo) {
+    if (this.closed) return
+    let message
+    try {
+      message = JSON.parse(buffer.toString('utf8'))
+    } catch {
+      return
+    }
+    if (message?.v !== 1) return
+    if (message.fleetHash !== fleetHash(this.fleetId)) return
+    if (typeof message.deviceId !== 'string' || message.deviceId === this.deviceId) return
+    if (typeof message.port !== 'number' || message.port <= 0) return
+    const peer = {
+      deviceId: message.deviceId,
+      name: typeof message.name === 'string' ? message.name : 'device',
+      host: rinfo.address,
+      port: message.port,
+      lastSeen: Date.now(),
+    }
+    this.peers.set(peer.deviceId, peer)
+    this.emit('peer', peer)
+  }
+
+  close() {
+    this.closed = true
+    clearInterval(this.timer)
+    if (this.socket) {
+      try {
+        this.socket.close()
+      } catch {
+        /* ignore */
+      }
+      this.socket = null
+    }
+  }
+}

package/src/net/fleet-node.js

@@ -0,0 +1,509 @@
+// FleetNode: one device's networking facade.
+//
+// It owns the identity, the fleet roster, a direct listener, optional LAN
+// discovery, an optional relay client, and the RPC layer that runs over
+// authenticated SecureChannels.
+import { EventEmitter } from 'node:events'
+import { randomUUID } from 'node:crypto'
+import { createDirectServer, connectDirect } from './direct.js'
+import { LanDiscovery } from './discovery.js'
+import { RelayClient } from './relay-client.js'
+import { SecureChannel } from './secure-channel.js'
+import {
+  FRAME,
+  PROTOCOL_VERSION,
+  eventFrame,
+  rpcError,
+  rpcRequest,
+  rpcResult,
+  serializeError,
+} from './protocol.js'
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 12_000
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
+
+export class FleetNode extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {object} options.identity device identity (generateIdentity)
+   * @param {{fleetId: string, fleetKey: string, name?: string}} options.fleet
+   * @param {string} [options.name]
+   * @param {string|null} [options.accountFingerprint]
+   * @param {{host?: string, port?: number}|false} [options.direct] direct listener (false disables)
+   * @param {false|{group?: string, port?: number, intervalMs?: number}} [options.discovery]
+   * @param {null|{host: string, port: number, dataPort: number, reconnect?: object}} [options.relay]
+   * @param {Array<{deviceId: string, edPublic: string, xPublic: string, name?: string}>} [options.roster]
+   * @param {boolean} [options.trustOnFirstUse]
+   * @param {boolean} [options.acceptRelayConnections]
+   */
+  constructor({
+    identity,
+    fleet,
+    name = identity?.name ?? 'device',
+    accountFingerprint = null,
+    direct = { host: '127.0.0.1', port: 0 },
+    discovery = false,
+    relay = null,
+    roster = [],
+    peerHints = [],
+    trustOnFirstUse = true,
+    acceptRelayConnections = true,
+    connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+    pluginVersion = '0.1.0',
+    dshVersion = 'unknown',
+    capabilities = [],
+  } = {}) {
+    super()
+    if (!identity?.deviceId || !identity.edPrivate || !identity.edPublic) throw new Error('FleetNode needs an identity')
+    if (!fleet?.fleetId || !fleet?.fleetKey) throw new Error('FleetNode needs a fleet')
+    this.identity = identity
+    this.fleet = fleet
+    this.name = name
+    this.accountFingerprint = accountFingerprint
+    this.directConfig = direct
+    this.discoveryConfig = discovery
+    this.relayConfig = relay
+    this.trustOnFirstUse = trustOnFirstUse
+    this.acceptRelayConnections = acceptRelayConnections
+    this.connectTimeoutMs = connectTimeoutMs
+    this.requestTimeoutMs = requestTimeoutMs
+    this.pluginVersion = pluginVersion
+    this.dshVersion = dshVersion
+    this.capabilities = capabilities
+
+    this.roster = new Map()
+    for (const entry of roster) this.roster.set(entry.deviceId, { name: 'device', ...entry })
+    this.discovered = new Map()
+    this.peerHints = []
+    for (const hint of peerHints) this.addPeerHint(hint)
+    this.hintTimer = null
+    this.hintAttempt = 0
+    this.channels = new Map()
+    this.pendingRpc = new Map()
+    this.requestHandler = null
+    this.eventHandler = null
+
+    this.directServer = null
+    this.discovery = null
+    this.relayClient = null
+    this.started = false
+    this.closed = false
+  }
+
+  get directPort() {
+    return this.directAddress?.port ?? null
+  }
+
+  rosterEntries() {
+    return [...this.roster.values()]
+  }
+
+  upsertRoster(entry) {
+    const existing = this.roster.get(entry.deviceId)
+    this.roster.set(entry.deviceId, { ...existing, name: 'device', ...entry })
+    this.emit('roster', this.rosterEntries())
+  }
+
+  onRequest(handler) {
+    this.requestHandler = handler
+  }
+
+  onEvent(handler) {
+    this.eventHandler = handler
+  }
+
+  async start() {
+    if (this.started) return this
+    this.started = true
+
+    if (this.directConfig !== false) {
+      this.directServer = createDirectServer({
+        host: this.directConfig.host ?? '0.0.0.0',
+        port: this.directConfig.port ?? 0,
+      })
+      this.directAddress = await this.directServer.ready
+      this.directServer.server.on('connection', (socket) => this.acceptInbound(socket, 'direct'))
+    }
+
+    if (this.discoveryConfig !== false && this.discoveryConfig !== undefined) {
+      if (!this.directAddress) throw new Error('discovery needs the direct listener')
+      const config = this.discoveryConfig === true ? {} : this.discoveryConfig
+      this.discovery = new LanDiscovery({
+        fleetId: this.fleet.fleetId,
+        deviceId: this.identity.deviceId,
+        name: this.name,
+        directPort: this.directAddress.port,
+        group: config.group,
+        port: config.port,
+        intervalMs: config.intervalMs,
+      })
+      this.discovery.on('peer', (peer) => {
+        this.discovered.set(peer.deviceId, peer)
+        this.emit('discovered', peer)
+      })
+      this.discovery.on('error', (error) => this.emit('warning', error))
+      this.discovery.start()
+    }
+
+    if (this.relayConfig) {
+      this.relayClient = new RelayClient({
+        host: this.relayConfig.host,
+        port: this.relayConfig.port,
+        dataPort: this.relayConfig.dataPort,
+        fleetId: this.fleet.fleetId,
+        deviceId: this.identity.deviceId,
+        fleetKey: this.fleet.fleetKey,
+        reconnect: this.relayConfig.reconnect,
+      })
+      this.relayClient.on('online', () => this.emit('relay-online'))
+      this.relayClient.on('offline', () => this.emit('relay-offline'))
+      this.relayClient.on('relay-error', (error) => this.emit('warning', error))
+      this.relayClient.on('incoming', (controller) => this.acceptIncomingRelay(controller))
+      try {
+        await this.relayClient.start(5_000)
+      } catch (error) {
+        this.emit('warning', error)
+      }
+    }
+
+    this.emit('started', { direct: this.directAddress ?? null })
+    this.scheduleHintConnects()
+    return this
+  }
+
+  /** Remember an address hint for a peer (from an invite or a manual `fleet_connect`). */
+  addPeerHint(hint) {
+    if (!hint || typeof hint.host !== 'string' || !Number.isInteger(hint.port) || hint.port <= 0) return
+    const entry = {
+      deviceId: typeof hint.deviceId === 'string' ? hint.deviceId : undefined,
+      host: hint.host,
+      port: hint.port,
+    }
+    if (entry.deviceId === this.identity.deviceId) return
+    const exists = this.peerHints.some(
+      (item) => item.host === entry.host && item.port === entry.port && item.deviceId === entry.deviceId,
+    )
+    if (!exists) this.peerHints.push(entry)
+  }
+
+  /** Connect to a raw address; learns the peer id from the handshake. */
+  async connectAddress(host, port, { expectedDeviceId = null, timeoutMs = this.connectTimeoutMs } = {}) {
+    if (!host || !Number.isInteger(port) || port <= 0) throw new Error('connectAddress needs host and port')
+    const expected = expectedDeviceId ? { deviceId: expectedDeviceId } : null
+    const socket = await connectDirect({ host, port, timeoutMs })
+    const channel = this.createInitiator(socket, expected)
+    await this.waitReady(channel, timeoutMs)
+    return channel.peer
+  }
+
+  /** Retry the invite/manual hints in the background until one peer connects. */
+  scheduleHintConnects() {
+    if (this.hintTimer || this.closed) return
+    const attempt = async () => {
+      this.hintTimer = null
+      if (this.closed) return
+      if (this.peerHints.length === 0 || this.channels.size > 0) return
+      try {
+        for (const hint of this.peerHints) {
+          if (this.closed || this.channels.size > 0) return
+          try {
+            const peer = await this.connectAddress(hint.host, hint.port, { expectedDeviceId: hint.deviceId })
+            this.emit('hint-connected', { hint, peer })
+            return
+          } catch {
+            // try the next hint; the timer below retries
+          }
+        }
+      } finally {
+        if (!this.closed && this.channels.size === 0) {
+          this.hintAttempt += 1
+          const delay = Math.min(10_000, 1000 * 2 ** Math.min(this.hintAttempt, 4))
+          this.hintTimer = setTimeout(() => void attempt(), delay)
+          this.hintTimer.unref?.()
+        }
+      }
+    }
+    this.hintTimer = setTimeout(() => void attempt(), 1500)
+    this.hintTimer.unref?.()
+  }
+
+  status() {
+    return {
+      deviceId: this.identity.deviceId,
+      name: this.name,
+      pluginVersion: this.pluginVersion,
+      dshVersion: this.dshVersion,
+      direct: this.directAddress ? { host: this.directAddress.host, port: this.directAddress.port } : null,
+      relay: this.relayClient ? { online: this.relayClient.online === true } : null,
+      discovery: this.discovery ? { enabled: true, peers: [...this.discovered.keys()] } : { enabled: false, peers: [] },
+      roster: this.rosterEntries().map((entry) => ({ deviceId: entry.deviceId, name: entry.name ?? 'device' })),
+      connected: this.peerIds(),
+      peerHints: [...this.peerHints],
+    }
+  }
+
+  async acceptIncomingRelay(controller) {
+    if (!this.acceptRelayConnections) {
+      controller.reject()
+      return
+    }
+    try {
+      const socket = await controller.accept()
+      this.acceptInbound(socket, 'relay')
+    } catch (error) {
+      this.emit('warning', error)
+    }
+  }
+
+  acceptInbound(socket, via) {
+    const channel = new SecureChannel({
+      socket,
+      identity: this.identity,
+      fleet: this.fleet,
+      role: 'responder',
+      accountFingerprint: this.accountFingerprint,
+      verifyPeer: (peer) => this.authorizePeer(peer),
+      pluginVersion: this.pluginVersion,
+      dshVersion: this.dshVersion,
+      capabilities: this.capabilities,
+    })
+    this.attachChannel(channel, via)
+  }
+
+  attachChannel(channel, via) {
+    channel.on('error', (error) => this.emit('warning', error))
+    channel.on('ready', (peer) => {
+      this.registerChannel(peer, channel, via)
+    })
+    channel.on('close', () => {
+      const current = this.channels.get(channel.peer?.deviceId)
+      if (current === channel) this.channels.delete(channel.peer.deviceId)
+      this.rejectPendingForChannel(channel, Object.assign(new Error('peer connection closed'), { code: 'peer-offline' }))
+      this.emit('peer-disconnected', { deviceId: channel.peer?.deviceId, via })
+      // Recover automatically: the peer may have restarted or moved; retry the
+      // known addresses instead of waiting for the next process start.
+      if (!this.closed && this.channels.size === 0 && this.peerHints.length > 0) {
+        clearTimeout(this.hintTimer)
+        this.hintTimer = null
+        this.hintAttempt = 0
+        this.scheduleHintConnects()
+      }
+    })
+  }
+
+  registerChannel(peer, channel, via) {
+    this.channels.set(peer.deviceId, channel)
+    channel.on('frame', (message) => this.onFrame(peer.deviceId, message, channel))
+    this.emit('peer', { deviceId: peer.deviceId, name: peer.name, via, channel })
+  }
+
+  authorizePeer(peer) {
+    const existing = this.roster.get(peer.deviceId)
+    if (existing) {
+      return existing.edPublic === peer.edPublic && existing.xPublic === peer.xPublic
+    }
+    if (!this.trustOnFirstUse) return false
+    this.roster.set(peer.deviceId, {
+      deviceId: peer.deviceId,
+      name: peer.name ?? 'device',
+      edPublic: peer.edPublic,
+      xPublic: peer.xPublic,
+      addedAt: Date.now(),
+    })
+    this.emit('roster', this.rosterEntries())
+    return true
+  }
+
+  async connect(deviceId, { host, port, timeoutMs = this.connectTimeoutMs } = {}) {
+    if (typeof deviceId !== 'string' || deviceId === '') throw new Error('connect needs a device id')
+    if (deviceId === this.identity.deviceId) throw new Error('cannot connect to self')
+    const existing = this.channels.get(deviceId)
+    if (existing && !existing.closed) return existing
+
+    const expected = this.roster.get(deviceId) ?? { deviceId }
+    const discovered = this.discovered.get(deviceId)
+    const hinted = this.peerHints.find((entry) => entry.deviceId === deviceId)
+    const endpoint =
+      host && port
+        ? { host, port }
+        : discovered
+          ? { host: discovered.host, port: discovered.port }
+          : hinted
+            ? { host: hinted.host, port: hinted.port }
+            : null
+    let directError = null
+    if (endpoint) {
+      try {
+        const socket = await connectDirect({ host: endpoint.host, port: endpoint.port, timeoutMs })
+        const channel = this.createInitiator(socket, expected)
+        await this.waitReady(channel, timeoutMs)
+        return channel
+      } catch (error) {
+        directError = error
+      }
+    }
+    if (this.relayClient) {
+      try {
+        const socket = await this.relayClient.requestConnect(deviceId, timeoutMs)
+        const channel = this.createInitiator(socket, expected)
+        await this.waitReady(channel, timeoutMs)
+        return channel
+      } catch (error) {
+        throw Object.assign(new Error(`cannot reach ${deviceId} via relay: ${String(error.message)}`), {
+          code: 'unreachable',
+          cause: error,
+        })
+      }
+    }
+    throw Object.assign(
+      new Error(`cannot reach ${deviceId}${directError ? `: ${String(directError.message)}` : ' (no endpoint)'}`),
+      { code: 'unreachable', cause: directError ?? undefined },
+    )
+  }
+
+  createInitiator(socket, expectedPeer) {
+    const channel = new SecureChannel({
+      socket,
+      identity: this.identity,
+      fleet: this.fleet,
+      role: 'initiator',
+      expectedPeer,
+      accountFingerprint: this.accountFingerprint,
+      verifyPeer: (peer) => this.authorizePeer(peer),
+      pluginVersion: this.pluginVersion,
+      dshVersion: this.dshVersion,
+      capabilities: this.capabilities,
+    })
+    this.attachChannel(channel, 'outbound')
+    return channel
+  }
+
+  waitReady(channel, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      if (channel.authenticated) return resolve(channel)
+      const timer = setTimeout(() => {
+        cleanup()
+        reject(Object.assign(new Error('secure channel handshake timed out'), { code: 'handshake-timeout' }))
+        channel.destroy()
+      }, timeoutMs)
+      timer.unref?.()
+      const onReady = () => {
+        cleanup()
+        resolve(channel)
+      }
+      const onClose = () => {
+        cleanup()
+        reject(Object.assign(new Error('secure channel closed during handshake'), { code: 'handshake-closed' }))
+      }
+      const cleanup = () => {
+        clearTimeout(timer)
+        channel.off('ready', onReady)
+        channel.off('close', onClose)
+      }
+      channel.once('ready', onReady)
+      channel.once('close', onClose)
+    })
+  }
+
+  onFrame(deviceId, message, channel) {
+    switch (message.t) {
+      case FRAME.RPC_REQUEST: {
+        const handler = this.requestHandler
+        if (typeof handler !== 'function') {
+          channel.sendFrame(rpcError({ id: message.id, code: 'no-handler', message: 'no request handler' }))
+          return
+        }
+        Promise.resolve()
+          .then(() => handler({ deviceId, method: message.method, params: message.params }))
+          .then((result) => channel.sendFrame(rpcResult({ id: message.id, result })))
+          .catch((error) => {
+            channel.sendFrame(rpcError({ id: message.id, ...serializeError(error) }))
+          })
+        return
+      }
+      case FRAME.RPC_RESULT: {
+        const pending = this.pendingRpc.get(message.id)
+        if (!pending) return
+        this.pendingRpc.delete(message.id)
+        clearTimeout(pending.timer)
+        pending.resolve(message.result)
+        return
+      }
+      case FRAME.RPC_ERROR: {
+        const pending = this.pendingRpc.get(message.id)
+        if (!pending) return
+        this.pendingRpc.delete(message.id)
+        clearTimeout(pending.timer)
+        const error = new Error(message.error?.message ?? 'remote error')
+        error.code = message.error?.code ?? 'remote-error'
+        error.data = message.error?.data ?? null
+        pending.reject(error)
+        return
+      }
+      case FRAME.EVENT: {
+        this.emit('event', { deviceId, topic: message.topic, data: message.data })
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  rejectPendingForChannel(channel, error) {
+    for (const [id, pending] of this.pendingRpc) {
+      if (pending.channel === channel) {
+        this.pendingRpc.delete(id)
+        clearTimeout(pending.timer)
+        pending.reject(error)
+      }
+    }
+  }
+
+  async request(deviceId, method, params, { timeoutMs = this.requestTimeoutMs } = {}) {
+    const channel = await this.connect(deviceId)
+    const id = randomUUID()
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRpc.delete(id)
+        reject(Object.assign(new Error(`request ${method} to ${deviceId} timed out`), { code: 'timeout' }))
+      }, timeoutMs)
+      timer.unref?.()
+      this.pendingRpc.set(id, { resolve, reject, timer, channel })
+      try {
+        channel.sendFrame(rpcRequest({ id, method, params }))
+      } catch (error) {
+        this.pendingRpc.delete(id)
+        clearTimeout(timer)
+        reject(error)
+      }
+    })
+  }
+
+  async sendEvent(deviceId, topic, data) {
+    const channel = await this.connect(deviceId)
+    channel.sendFrame(eventFrame({ topic, data }))
+  }
+
+  peerIds() {
+    return [...this.channels.keys()]
+  }
+
+  async close() {
+    this.closed = true
+    clearTimeout(this.hintTimer)
+    this.hintTimer = null
+    for (const channel of this.channels.values()) channel.close()
+    this.channels.clear()
+    for (const [id, pending] of this.pendingRpc) {
+      this.pendingRpc.delete(id)
+      clearTimeout(pending.timer)
+      pending.reject(Object.assign(new Error('node closed'), { code: 'closed' }))
+    }
+    this.relayClient?.close()
+    this.discovery?.close()
+    if (this.directServer) await this.directServer.close()
+  }
+}
+
+export { PROTOCOL_VERSION }