index.ts

/* eslint-disable @typescript-eslint/no-explicit-any */
import { createDebug } from '../../debug'
const debug = createDebug('signalk-server:api:ble')

import cookie from 'cookie'
import fs from 'fs'
import { IRouter, NextFunction, Request, Response } from 'express'
import { Value } from '@sinclair/typebox/value'
import {
  BLESettingsRequestSchema,
  BLEMacParamSchema
} from '@signalk/server-api/typebox'
import { WithSecurityStrategy } from '../../security'
import { SignalKMessageHub, WithConfig } from '../../app'
import WebSocket from 'ws'
import { writeSettingsFile } from '../../config/config'
import { LocalBLEProvider } from './localProvider'
import { RemoteGatewayProvider } from './remoteProvider'
import { bleVendorName } from './bleCompanyIds'

import {
  BLEProvider,
  BLEProviders,
  BLEAdvertisement,
  BLEDeviceInfo,
  BLEConsumerInfo,
  BLEApi as IBLEApi,
  GATTSubscriptionDescriptor,
  GATTSubscriptionHandle,
  BLEGattConnection,
  isBLEProvider
} from '@signalk/server-api'

const BLE_API_PATH = `/signalk/v2/api/vessels/self/ble`

// Devices not seen for this long are pruned from the device table
export const DEVICE_STALE_MS = 120_000

interface BLEApplication
  extends WithSecurityStrategy, SignalKMessageHub, WithConfig, IRouter {
  server?: any // HTTP server for WebSocket upgrade
}

interface BLESettings {
  localBluetoothManaged: boolean
  localAdapters: string[] // [] = auto-enumerate all available adapters
  localMaxGATTSlots: number
}

/**
 * Internal extension of GATTSubscriptionHandle: providers may attach
 * `_fireDisconnect` so the server can deliver disconnect callbacks when
 * the underlying transport is already dead and `close()` cannot fire them.
 */
type InternalGATTSubscriptionHandle = GATTSubscriptionHandle & {
  _fireDisconnect?: () => void
}

interface GATTClaim {
  pluginId: string
  providerId: string
  handle: InternalGATTSubscriptionHandle
  keepAliveTimer?: ReturnType<typeof setInterval>
}

const DEFAULT_BLE_SETTINGS: BLESettings = {
  localBluetoothManaged: false,
  localAdapters: [],
  localMaxGATTSlots: 3
}

export class BLEApi implements IBLEApi {
  private bleProviders: Map<string, BLEProvider> = new Map()
  private providerUnsubscribers: Map<string, () => void> = new Map()
  private deviceTable: Map<string, BLEDeviceInfo> = new Map()
  private gattClaims: Map<string, GATTClaim> = new Map()
  private pendingGattClaims: Set<string> = new Set()
  private advertisementCallbacks: Map<string, (adv: BLEAdvertisement) => void> =
    new Map()
  private wsClients: Set<WebSocket> = new Set()
  private localProviders: Map<string, LocalBLEProvider> = new Map() // key = providerId
  private localProviderErrors: Map<string, string> = new Map() // key = adapterName
  // Tracks an initLocalProviders() attempt still in flight for a given
  // providerId, from before provider.init() resolves through to
  // register()/startDiscovery() (or the catch-block rollback). Without
  // this, two overlapping initLocalProviders() calls for the same adapter
  // (e.g. start() racing a PUT /settings-triggered reinit) can both pass
  // the `localProviders.has(providerId)` skip-check before either await
  // completes, each construct their own LocalBLEProvider, and the later
  // one's register() ends up displacing the earlier one's registration -
  // but the earlier LocalBLEProvider instance keeps running its own
  // discovery loop, now unreferenced by localProviders and therefore
  // unreachable by shutdown.
  private localProviderInitializations: Map<string, Promise<void>> = new Map()
  private defaultProviderId: string | null = null
  private settings: BLESettings
  private remoteGatewayProvider: RemoteGatewayProvider | null = null
  private devicePruneTimer?: ReturnType<typeof setInterval>

  get localBluetoothManaged(): boolean {
    return this.settings.localBluetoothManaged
  }

  get localAdapters(): string[] {
    return this.settings.localAdapters
  }

  constructor(private app: BLEApplication) {
    const appSettings = (this.app.config?.settings as any) ?? {}
    if (!appSettings.bleApi) {
      appSettings.bleApi = { ...DEFAULT_BLE_SETTINGS }
    }
    this.settings = {
      ...DEFAULT_BLE_SETTINGS,
      ...appSettings.bleApi
    }
  }

  async start() {
    this.initApiEndpoints()
    this.initWebSocketEndpoint()

    // Prune independently of REST polling so the device table cannot
    // grow without bound when no client requests /devices
    this.devicePruneTimer = setInterval(
      () => this.pruneStaleDevices(),
      DEVICE_STALE_MS
    )
    this.devicePruneTimer.unref()

    this.remoteGatewayProvider = new RemoteGatewayProvider(
      this.app,
      this.register.bind(this),
      this.unRegister.bind(this),
      this.releaseGATTClaimsForProvider.bind(this)
    )
    this.remoteGatewayProvider.attach(this.app)

    if (this.settings.localBluetoothManaged) {
      await this.initLocalProviders()
    }
  }

  // Local Bluetooth adapter support requires Linux + BlueZ. Not available on
  // macOS or Windows (no DBus/BlueZ). See docs/develop/rest-api/ble_api.md.
  private isLocalBLESupported(): boolean {
    return process.platform === 'linux'
  }

  private async getAvailableAdapters(): Promise<string[]> {
    // /sys/class/bluetooth is populated by the kernel for every BT adapter.
    // Empty or absent means no hardware — skip to avoid DBus stack traces.
    try {
      const entries = fs.readdirSync('/sys/class/bluetooth')
      if (entries.length === 0) {
        debug('No Bluetooth hardware detected — skipping local BLE')
        return []
      }
    } catch {
      debug('No Bluetooth hardware detected — skipping local BLE')
      return []
    }

    try {
      // eslint-disable-next-line @typescript-eslint/no-require-imports
      const { createBluetooth } = require('@naugehyde/node-ble')
      const { bluetooth, destroy } = createBluetooth()
      const adapters = await bluetooth.activeAdapters()
      destroy()
      return adapters.map((a: any) => a.adapter as string)
    } catch {
      return []
    }
  }

  private async initLocalProviders() {
    if (!this.isLocalBLESupported()) {
      debug('Local Bluetooth not supported on this platform — skipping')
      return
    }

    let adapterNames = this.settings.localAdapters
    if (adapterNames.length === 0) {
      adapterNames = await this.getAvailableAdapters()
      if (adapterNames.length === 0) adapterNames = ['hci0']
    }

    for (const adapterName of adapterNames) {
      const providerId = `_localBLE:${adapterName}`
      if (this.localProviders.has(providerId)) continue

      // Serialize against a concurrent initLocalProviders() call already
      // in flight for this same adapter (see
      // localProviderInitializations's comment) - await its result
      // instead of racing it with a second LocalBLEProvider construction.
      const inFlight = this.localProviderInitializations.get(providerId)
      if (inFlight) {
        await inFlight
        continue
      }

      const initialization = this.initOneLocalProvider(
        adapterName,
        providerId
      )
      this.localProviderInitializations.set(providerId, initialization)
      try {
        await initialization
      } finally {
        if (this.localProviderInitializations.get(providerId) === initialization) {
          this.localProviderInitializations.delete(providerId)
        }
      }
    }
  }

  private async initOneLocalProvider(adapterName: string, providerId: string) {
    let provider: LocalBLEProvider | undefined
    let registeredProvider: BLEProvider | undefined
    try {
      provider = new LocalBLEProvider(
        adapterName,
        this.settings.localMaxGATTSlots,
        providerId
      )
      await provider.init()
      this.localProviders.set(providerId, provider)
      this.localProviderErrors.delete(adapterName)
      // Register (which wires up onAdvertisement -> _handleAdvertisement,
      // populating deviceTable) before starting discovery. Discovery's
      // first pass emits advertisements for every already-known device
      // synchronously as part of startDiscovery(), and LocalBLEProvider's
      // emitDeviceAdvertisement drops advertisements entirely when nobody
      // has subscribed yet - registering afterward silently lost that
      // whole first batch, leaving those devices absent from the device
      // table (and therefore unreachable via subscribeGATT) until BlueZ
      // happened to re-report one of their properties later.
      registeredProvider = {
        name: `Local Bluetooth (${adapterName})`,
        methods: provider.getMethods()
      }
      this.register(providerId, registeredProvider)
      await provider.startDiscovery()
      debug.enabled &&
        debug(`Local BLE provider registered and scanning: ${providerId}`)
    } catch (e: any) {
      // Roll back any partial state if init and/or register succeeded but
      // startDiscovery failed. Only touch state that's still this
      // provider's - localProviderInitializations already prevents a
      // concurrent initLocalProviders() call for the same adapter from
      // running at the same time as this one, but the identity checks
      // stay as defense in depth (e.g. a caller invoking
      // initOneLocalProvider directly, or a future refactor that removes
      // the serialization).
      if (this.localProviders.get(providerId) === provider) {
        if (this.bleProviders.get(providerId) === registeredProvider) {
          this.unRegister(providerId)
        }
        this.localProviders.delete(providerId)
      }
      if (provider) {
        try {
          provider.shutdown()
        } catch (_e) {
          /* ignore */
        }
      }
      const msg = `Local BLE adapter ${adapterName} unavailable: ${e.message}`
      debug(msg)
      // Suppress console.log for expected "no hardware / no BlueZ" errors
      const isExpected =
        e.message?.includes('org.freedesktop.DBus.Error.ServiceUnknown') ||
        e.message?.includes('not provided by any .service files') ||
        e.message?.includes('ENOENT') ||
        e.message?.includes('ECONNREFUSED')
      if (!isExpected) {
        console.log(`[BLE API] ${msg}`)
      }
      this.localProviderErrors.set(adapterName, e.message)
    }
  }

  private async shutdownLocalProviders() {
    // Wait out any initOneLocalProvider() calls still in flight before
    // tearing anything down. Without this, a call still awaiting
    // provider.startDiscovery() (DBus) can resolve *after* this method
    // has already run - at that point it finishes registering/logging
    // for a provider this method just unregistered and shut down, and
    // its now-orphaned discovery loop is left running (unreferenced by
    // localProviders, so a later shutdown can no longer find it either).
    // Waiting first means initOneLocalProvider's own try/catch has always
    // fully settled localProviders/bleProviders for a given providerId by
    // the time the loop below runs, so there's nothing left in flight to
    // race against.
    //
    // A single Promise.all() snapshot isn't enough: initLocalProviders()
    // could still be running concurrently (e.g. a settings change firing
    // again mid-shutdown) and add a *new* entry to
    // localProviderInitializations while this method's own await is
    // pending, and that new entry wouldn't be in the snapshot. Re-check
    // and re-await until the map is actually empty, so a fresh entry
    // added during the wait still gets caught before teardown proceeds.
    while (this.localProviderInitializations.size > 0) {
      await Promise.all(this.localProviderInitializations.values())
    }

    for (const [providerId, provider] of this.localProviders) {
      // One misbehaving adapter must not keep the others registered
      try {
        this.unRegister(providerId)
        provider.shutdown()
        debug.enabled && debug(`Local BLE provider shut down: ${providerId}`)
      } catch (e: any) {
        debug.enabled &&
          debug(
            `Local BLE provider shutdown failed: ${providerId}: ${e.message}`
          )
      }
    }
    this.localProviders.clear()
    this.localProviderErrors.clear()
  }

  // -------------------------------------------------------------------
  // Provider registration
  // -------------------------------------------------------------------

  register(pluginId: string, provider: BLEProvider) {
    if (!pluginId || !provider) {
      throw new Error(`Error registering BLE provider ${pluginId}!`)
    }
    if (!isBLEProvider(provider)) {
      throw new Error(`${pluginId} is missing BLEProvider properties/methods!`)
    }
    debug.enabled &&
      debug.enabled &&
      debug(`Registering BLE provider: ${pluginId} "${provider.name}"`)

    if (this.bleProviders.has(pluginId)) {
      this.unRegister(pluginId)
    }
    this.bleProviders.set(pluginId, provider)

    const unsub = provider.methods.onAdvertisement((adv: BLEAdvertisement) => {
      // Advertisements are routed by providerId; never trust the provider
      // to stamp its own id correctly
      if (adv.providerId !== pluginId) {
        adv = { ...adv, providerId: pluginId }
      }
      this._handleAdvertisement(adv)
    })
    this.providerUnsubscribers.set(pluginId, unsub)

    debug.enabled &&
      debug(`BLE providers registered: ${this.bleProviders.size}`)
  }

  unRegister(pluginId: string) {
    if (!pluginId) return
    debug.enabled && debug(`Unregistering BLE provider: ${pluginId}`)

    const unsub = this.providerUnsubscribers.get(pluginId)
    if (unsub) {
      unsub()
      this.providerUnsubscribers.delete(pluginId)
    }

    for (const [mac, claim] of this.gattClaims) {
      if (claim.providerId === pluginId) {
        claim.handle.close().catch(() => {})
        this.gattClaims.delete(mac)
      }
    }

    this.bleProviders.delete(pluginId)
    debug.enabled && debug(`BLE providers remaining: ${this.bleProviders.size}`)
  }

  // -------------------------------------------------------------------
  // Advertisement handling
  // -------------------------------------------------------------------

  onAdvertisement(
    pluginId: string,
    callback: (adv: BLEAdvertisement) => void
  ): () => void {
    this.advertisementCallbacks.set(pluginId, callback)
    return () => {
      this.advertisementCallbacks.delete(pluginId)
    }
  }

  private _handleAdvertisement(adv: BLEAdvertisement) {
    const mac = adv.mac.toUpperCase()

    let device = this.deviceTable.get(mac)
    if (!device) {
      device = {
        mac,
        name: adv.name,
        rssi: adv.rssi,
        lastSeen: adv.timestamp,
        connectable: adv.connectable ?? false,
        seenBy: []
      }
      this.deviceTable.set(mac, device)
    }

    const providerEntry = device.seenBy.find(
      (s) => s.providerId === adv.providerId
    )
    if (providerEntry) {
      providerEntry.rssi = adv.rssi
      providerEntry.lastSeen = adv.timestamp
    } else {
      device.seenBy.push({
        providerId: adv.providerId,
        rssi: adv.rssi,
        lastSeen: adv.timestamp
      })
    }

    // Prefer advertised name; fall back to Bluetooth SIG company ID lookup
    if (adv.name) {
      device.name = adv.name
    } else if (!device.name) {
      const companyId = Object.keys(adv.manufacturerData ?? {})[0]
      if (companyId !== undefined) {
        device.name = bleVendorName(parseInt(companyId)) ?? undefined
      }
    }
    if (adv.connectable) device.connectable = true
    if (adv.addressType) device.addressType = adv.addressType

    // Prune providers that haven't reported this device recently
    const seenByCutoff = Date.now() - DEVICE_STALE_MS
    device.seenBy = device.seenBy.filter((s) => s.lastSeen > seenByCutoff)

    if (device.seenBy.length > 0) {
      device.rssi = Math.max(...device.seenBy.map((s) => s.rssi))
      device.lastSeen = Math.max(...device.seenBy.map((s) => s.lastSeen))
    }

    const claim = this.gattClaims.get(mac)
    device.gattClaimedBy = claim?.pluginId

    for (const cb of this.advertisementCallbacks.values()) {
      try {
        cb(adv)
      } catch (e: any) {
        debug.enabled && debug(`Advertisement callback error: ${e.message}`)
      }
    }

    if (this.wsClients.size > 0) {
      const json = JSON.stringify(adv)
      for (const ws of this.wsClients) {
        if (ws.readyState === WebSocket.OPEN) {
          ws.send(json)
        }
      }
    }
  }

  // -------------------------------------------------------------------
  // Device queries
  // -------------------------------------------------------------------

  async getDevices(): Promise<BLEDeviceInfo[]> {
    this.pruneStaleDevices()
    // Ensure every GATT-claimed device is in the table, even if it stopped
    // advertising after connection (GATT devices typically do).
    for (const [mac, claim] of this.gattClaims) {
      if (!this.deviceTable.has(mac)) {
        this.deviceTable.set(mac, {
          mac,
          rssi: 0,
          lastSeen: Date.now(),
          connectable: true,
          seenBy: [
            { providerId: claim.providerId, rssi: 0, lastSeen: Date.now() }
          ]
        })
      }
      const device = this.deviceTable.get(mac)!
      device.gattClaimedBy = claim.pluginId
    }
    for (const [mac, device] of this.deviceTable) {
      if (!this.gattClaims.has(mac)) {
        device.gattClaimedBy = undefined
      }
    }
    return Array.from(this.deviceTable.values())
  }

  async getDevice(mac: string): Promise<BLEDeviceInfo | null> {
    mac = mac.toUpperCase()
    const device = this.deviceTable.get(mac)
    if (!device) return null
    device.gattClaimedBy = this.gattClaims.get(mac)?.pluginId
    return device
  }

  private pruneStaleDevices() {
    const cutoff = Date.now() - DEVICE_STALE_MS
    for (const [mac, device] of this.deviceTable) {
      // Never prune a device that has an active GATT claim
      if (this.gattClaims.has(mac)) continue
      if (device.lastSeen < cutoff) {
        this.deviceTable.delete(mac)
      }
    }
  }

  // -------------------------------------------------------------------
  // GATT
  // -------------------------------------------------------------------

  /**
   * Reserve a MAC before the provider call awaits, so two concurrent
   * subscribeGATT/connectGATT calls for the same device cannot both pass
   * the claim check. Throws when the device is claimed or being claimed.
   */
  private reserveGATTClaim(mac: string) {
    const existing = this.gattClaims.get(mac)
    if (existing) {
      throw new Error(`Device ${mac} already claimed by ${existing.pluginId}`)
    }
    if (this.pendingGattClaims.has(mac)) {
      throw new Error(`Device ${mac} has a GATT claim in progress`)
    }
    this.pendingGattClaims.add(mac)
  }

  async subscribeGATT(
    descriptor: GATTSubscriptionDescriptor,
    pluginId: string,
    callback: (charUuid: string, data: Buffer) => void
  ): Promise<GATTSubscriptionHandle> {
    const mac = descriptor.mac.toUpperCase()
    this.reserveGATTClaim(mac)
    try {
      const providerId = this.selectGATTProvider(mac)
      if (!providerId) {
        throw new Error(
          `No provider with GATT support and available slots can see ${mac}`
        )
      }

      const provider = this.bleProviders.get(providerId)!
      const handle = await provider.methods.subscribeGATT(descriptor, callback)

      debug.enabled &&
        debug(`GATT claim: ${mac} → ${pluginId} via ${providerId}`)

      // Ensure the device exists in the table — GATT devices may stop advertising
      // once connected, so they would otherwise be pruned.
      if (!this.deviceTable.has(mac)) {
        this.deviceTable.set(mac, {
          mac,
          rssi: 0,
          lastSeen: Date.now(),
          connectable: true,
          seenBy: [{ providerId, rssi: 0, lastSeen: Date.now() }]
        })
      }
      // Keep lastSeen fresh for the duration of the claim so the device
      // is not pruned while GATT is active (GATT devices stop advertising).
      const keepAliveTimer = setInterval(() => {
        const d = this.deviceTable.get(mac)
        if (d) d.lastSeen = Date.now()
      }, DEVICE_STALE_MS / 2)
      keepAliveTimer.unref()

      const claimEntry: GATTClaim = {
        pluginId,
        providerId,
        handle,
        keepAliveTimer
      }
      this.gattClaims.set(mac, claimEntry)

      const origClose = handle.close.bind(handle)
      handle.close = async () => {
        clearInterval(keepAliveTimer)
        this.gattClaims.delete(mac)
        debug.enabled && debug(`GATT released: ${mac} (was ${pluginId})`)
        return origClose()
      }

      return handle
    } finally {
      this.pendingGattClaims.delete(mac)
    }
  }

  async connectGATT(mac: string, pluginId: string): Promise<BLEGattConnection> {
    mac = mac.toUpperCase()
    this.reserveGATTClaim(mac)
    try {
      const providerId = this.selectGATTProvider(mac)
      if (!providerId) {
        throw new Error(`No provider with GATT support can see ${mac}`)
      }

      const provider = this.bleProviders.get(providerId)!
      if (!provider.methods.connectGATT) {
        throw new Error(
          `Provider ${providerId} does not support raw GATT connections`
        )
      }

      const conn = await provider.methods.connectGATT(mac)

      const syntheticHandle: GATTSubscriptionHandle = {
        read: async () => Buffer.alloc(0),
        write: async () => {},
        close: async () => {
          this.gattClaims.delete(mac)
          await conn.disconnect()
        },
        get connected() {
          return conn.connected
        },
        onDisconnect: (cb) => conn.onDisconnect(cb),
        onConnect: (cb) => {
          // Raw connection is already established when connectGATT returns
          if (conn.connected) cb()
        }
      }
      this.gattClaims.set(mac, {
        pluginId,
        providerId,
        handle: syntheticHandle
      })

      conn.onDisconnect(() => {
        this.gattClaims.delete(mac)
        debug.enabled &&
          debug(`Raw GATT claim auto-released (disconnect): ${mac}`)
      })

      return conn
    } finally {
      this.pendingGattClaims.delete(mac)
    }
  }

  async releaseGATTDevice(mac: string, pluginId: string): Promise<void> {
    mac = mac.toUpperCase()
    const claim = this.gattClaims.get(mac)
    if (!claim) return
    if (claim.pluginId !== pluginId) {
      throw new Error(
        `Device ${mac} is claimed by ${claim.pluginId}, not ${pluginId}`
      )
    }
    await claim.handle.close()
  }

  getGATTClaims(): Map<string, string> {
    const result = new Map<string, string>()
    for (const [mac, claim] of this.gattClaims) {
      result.set(mac, claim.pluginId)
    }
    return result
  }

  private _buildSettingsResponse() {
    const adapterErrors: Record<string, string> = {}
    for (const [k, v] of this.localProviderErrors) {
      adapterErrors[k] = v
    }
    return {
      localBluetoothManaged: this.settings.localBluetoothManaged,
      localAdapters: this.settings.localAdapters,
      localMaxGATTSlots: this.settings.localMaxGATTSlots,
      localBLESupported: this.isLocalBLESupported(),
      activeAdapters: Array.from(this.localProviders.keys()),
      adapterErrors
    }
  }

  /**
   * Release all GATT claims held through the given providerId.
   * Called when a gateway WS disconnects so plugins can re-subscribe
   * via another provider (or the same one when it reconnects).
   */
  releaseGATTClaimsForProvider(providerId: string) {
    for (const [mac, claim] of this.gattClaims) {
      if (claim.providerId === providerId) {
        if (claim.keepAliveTimer) clearInterval(claim.keepAliveTimer)
        this.gattClaims.delete(mac)
        debug.enabled &&
          debug(
            `GATT claim released (gateway offline): ${mac} was ${claim.pluginId} via ${providerId}`
          )
        // Fire disconnect callbacks so the plugin knows to reconnect via
        // another provider. Don't call handle.close() — the WS is already
        // dead and close() does not fire disconnectCallbacks.
        claim.handle._fireDisconnect?.()
      }
    }
  }

  private selectGATTProvider(mac: string): string | undefined {
    const device = this.deviceTable.get(mac)
    if (!device) return undefined

    // Sort providers by RSSI (strongest first), filter to those with
    // GATT support and available slots
    const candidates = device.seenBy
      .filter((s) => {
        const provider = this.bleProviders.get(s.providerId)
        return (
          provider &&
          provider.methods.supportsGATT() &&
          provider.methods.availableGATTSlots() > 0
        )
      })
      .sort((a, b) => b.rssi - a.rssi)

    if (candidates.length === 0) return undefined

    // Prefer the default provider if it is among the candidates
    if (this.defaultProviderId) {
      const preferred = candidates.find(
        (c) => c.providerId === this.defaultProviderId
      )
      if (preferred) return preferred.providerId
    }

    return candidates[0].providerId
  }

  // -------------------------------------------------------------------
  // REST endpoints
  // -------------------------------------------------------------------

  private initApiEndpoints() {
    debug.enabled && debug(`Initialise ${BLE_API_PATH} endpoints`)

    this.app.use(
      `${BLE_API_PATH}/*`,
      (req: Request, res: Response, next: NextFunction) => {
        if (['PUT', 'POST', 'DELETE'].includes(req.method)) {
          if (
            !this.app.securityStrategy.shouldAllowPut(
              req,
              'vessels.self',
              null,
              'ble'
            )
          ) {
            res.status(403).json({ message: 'Unauthorized' })
            return
          }
        }
        next()
      }
    )

    this.app.get(`${BLE_API_PATH}`, async (_req: Request, res: Response) => {
      res.json({
        devices: {
          description:
            'All visible BLE devices across all providers, deduplicated by MAC'
        },
        providers: {
          description: 'Registered BLE providers'
        },
        gattClaims: {
          description: 'Current GATT connection claims'
        }
      })
    })

    this.app.get(
      `${BLE_API_PATH}/_providers`,
      async (_req: Request, res: Response) => {
        const providers: BLEProviders = {}
        for (const [id, provider] of this.bleProviders) {
          const available = provider.methods.availableGATTSlots()
          const total = provider.methods.totalGATTSlots
            ? provider.methods.totalGATTSlots()
            : available
          providers[id] = {
            name: provider.name,
            supportsGATT: provider.methods.supportsGATT(),
            gattSlots: { total, available }
          }
        }
        res.json(providers)
      }
    )

    this.app.get(
      `${BLE_API_PATH}/_providers/_default`,
      async (_req: Request, res: Response) => {
        res.json({ id: this.defaultProviderId })
      }
    )

    this.app.post(
      `${BLE_API_PATH}/_providers/_default/:id`,
      async (req: Request, res: Response) => {
        const id = req.params.id
        if (!id) {
          res.status(400).json({ error: 'Provider id not supplied' })
          return
        }
        if (this.bleProviders.has(id)) {
          this.defaultProviderId = id
          res.json({
            state: 'COMPLETED',
            message: `Default provider set to ${id}`
          })
        } else {
          res.status(404).json({ error: `Provider ${id} not found` })
        }
      }
    )

    this.app.get(
      `${BLE_API_PATH}/devices`,
      async (_req: Request, res: Response) => {
        const devices = await this.getDevices()
        res.json(devices)
      }
    )

    this.app.get(
      `${BLE_API_PATH}/devices/:mac`,
      async (req: Request, res: Response) => {
        if (!Value.Check(BLEMacParamSchema, req.params.mac)) {
          res.status(400).json({ message: 'Invalid MAC address' })
          return
        }
        const device = await this.getDevice(req.params.mac)
        if (device) {
          res.json(device)
        } else {
          res.status(404).json({ message: 'Device not found' })
        }
      }
    )

    this.app.get(
      `${BLE_API_PATH}/devices/:mac/gatt`,
      async (req: Request, res: Response) => {
        if (!Value.Check(BLEMacParamSchema, req.params.mac)) {
          res.status(400).json({ message: 'Invalid MAC address' })
          return
        }
        const mac = req.params.mac.toUpperCase()
        const claim = this.gattClaims.get(mac)
        res.json({
          claimedBy: claim?.pluginId ?? null
        })
      }
    )

    this.app.get(
      `${BLE_API_PATH}/consumers`,
      async (_req: Request, res: Response) => {
        const consumerMap = new Map<string, BLEConsumerInfo>()

        for (const pluginId of this.advertisementCallbacks.keys()) {
          consumerMap.set(pluginId, {
            pluginId,
            advertisementSubscriber: true,
            gattClaims: []
          })
        }
        for (const [mac, claim] of this.gattClaims) {
          let entry = consumerMap.get(claim.pluginId)
          if (!entry) {
            entry = {
              pluginId: claim.pluginId,
              advertisementSubscriber: false,
              gattClaims: []
            }
            consumerMap.set(claim.pluginId, entry)
          }
          entry.gattClaims.push(mac)
        }

        res.json(Array.from(consumerMap.values()))
      }
    )

    this.app.get(
      `${BLE_API_PATH}/settings`,
      async (_req: Request, res: Response) => {
        res.json(this._buildSettingsResponse())
      }
    )

    this.app.put(
      `${BLE_API_PATH}/settings`,
      async (req: Request, res: Response) => {
        if (!Value.Check(BLESettingsRequestSchema, req.body)) {
          const first = Value.Errors(BLESettingsRequestSchema, req.body).First()
          res.status(400).json({
            message: first
              ? `Invalid settings at ${first.path}: ${first.message}`
              : 'Invalid settings'
          })
          return
        }
        const body = req.body
        if (
          body.localBluetoothManaged === true &&
          !this.isLocalBLESupported()
        ) {
          res.status(400).json({
            message:
              'Local Bluetooth adapter management is only supported on Linux.'
          })
          return
        }

        // Apply to a candidate first: in-memory settings only change
        // after the write to disk has succeeded
        const candidate: BLESettings = { ...this.settings }
        let changed = false
        let providerChange = false
        if (typeof body.localBluetoothManaged === 'boolean') {
          candidate.localBluetoothManaged = body.localBluetoothManaged
          changed = true
          providerChange = true
        }
        if (Array.isArray(body.localAdapters)) {
          candidate.localAdapters = body.localAdapters
          changed = true
          providerChange = true
        }
        if (typeof body.localMaxGATTSlots === 'number') {
          candidate.localMaxGATTSlots = body.localMaxGATTSlots
          changed = true
          providerChange = true
        }

        if (changed) {
          const candidateSettings = structuredClone(
            this.app.config.settings
          ) as any
          candidateSettings.bleApi = { ...candidate }
          try {
            await new Promise<void>((resolve, reject) => {
              writeSettingsFile(
                this.app as any,
                candidateSettings,
                (err: any) => (err ? reject(err) : resolve())
              )
            })
          } catch (err: any) {
            debug.enabled && debug(`Error saving BLE settings: ${err.message}`)
            res
              .status(500)
              .json({ message: `Failed to save settings: ${err.message}` })
            return
          }

          this.settings = candidate
          ;(this.app.config.settings as any).bleApi = { ...candidate }

          if (providerChange) {
            await this.shutdownLocalProviders()
            if (this.settings.localBluetoothManaged) {
              await this.initLocalProviders()
            }
          }
        }

        res.json(this._buildSettingsResponse())
      }
    )
  }

  // -------------------------------------------------------------------
  // WebSocket endpoint for advertisement streaming
  // -------------------------------------------------------------------

  private initWebSocketEndpoint() {
    const wsPath = `${BLE_API_PATH}/advertisements`
    const wss = new WebSocket.Server({ noServer: true })

    wss.on('connection', (ws: WebSocket) => {
      debug('WebSocket client connected for BLE advertisements')
      this.wsClients.add(ws)
      ws.on('close', () => {
        this.wsClients.delete(ws)
        debug('WebSocket client disconnected')
      })
      ws.on('error', () => {
        this.wsClients.delete(ws)
      })
    })

    const tryAttach = () => {
      const server = this.app.server
      if (!server) {
        debug('HTTP server not yet available, retrying in 1s...')
        setTimeout(tryAttach, 1000).unref()
        return
      }

      server.on('upgrade', (request: any, socket: any, head: any) => {
        // A malformed Host header must not throw in the upgrade listener
        let url: URL
        try {
          url = new URL(
            request.url,
            `http://${request.headers.host ?? 'localhost'}`
          )
        } catch {
          socket.write('HTTP/1.1 400 Bad Request\r\n\r\n')
          socket.destroy()
          return
        }
        if (url.pathname !== wsPath) return

        const sec = this.app.securityStrategy as any
        if (sec?.canAuthorizeWS?.()) {
          const query = Object.fromEntries(url.searchParams.entries())
          const headers = request.headers as Record<string, string>
          const cookies = request.headers.cookie
            ? cookie.parse(request.headers.cookie)
            : {}
          try {
            sec.authorizeWS({ query, headers, cookies })
          } catch {
            debug('BLE advertisements WS: unauthorized — rejecting upgrade')
            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n')
            socket.destroy()
            return
          }
        }

        wss.handleUpgrade(request, socket, head, (ws: WebSocket) => {
          wss.emit('connection', ws, request)
        })
      })
      debug.enabled && debug(`WebSocket endpoint ready at ${wsPath}`)
    }

    tryAttach()
  }
}