@tiuxo/opencode-openrgb 0.0.0-stage → 0.1.0

package/src/client.ts

@@ -0,0 +1,464 @@
+/**
+ * A minimal, dependency-free OpenRGB SDK client.
+ *
+ * Design constraints, in priority order:
+ *
+ *  1. Never throw into the host process. If OpenRGB is not running, is
+ *     restarted, or misbehaves, every operation degrades to a silent no-op and
+ *     the client reconnects in the background.
+ *  2. Protocol 5 has no ACK packets, so writes are fire-and-forget. Only
+ *     `REQUEST_*` packets have responses to await.
+ *  3. Device data is requested one device at a time, as the SDK documentation
+ *     requires, which keeps response correlation trivial.
+ */
+
+import fs from "node:fs"
+import net from "node:net"
+
+import {
+  CLIENT_PROTOCOL_VERSION,
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+  type Device,
+  type Frame,
+  type Mode,
+  ModeFlag,
+  PacketId,
+  decodeDevice,
+  decodeFrames,
+  encodeClientName,
+  encodePacket,
+  encodeProtocolVersion,
+  encodeUpdateLeds,
+  encodeUpdateMode,
+} from "./protocol.js"
+
+export interface Logger {
+  debug(message: string): void
+  warn(message: string): void
+}
+
+export interface ClientOptions {
+  host?: string
+  port?: number
+  /** Name reported to the OpenRGB server; shows up in its client list. */
+  clientName?: string
+  logger?: Logger
+  /** Invoked after the device list is (re)loaded, including on reconnect. */
+  onDevicesReloaded?: (devices: Device[]) => void
+}
+
+const CONNECT_TIMEOUT_MS = 3_000
+const RESPONSE_TIMEOUT_MS = 5_000
+/** Protocol-0 servers never answer the version request; don't wait long. */
+const VERSION_TIMEOUT_MS = 1_000
+const RETRY_MIN_MS = 1_000
+const RETRY_MAX_MS = 30_000
+
+interface Waiter {
+  resolve: (frame: Frame) => void
+  reject: (error: Error) => void
+  timer: NodeJS.Timeout
+}
+
+const noopLogger: Logger = {
+  debug: () => {},
+  warn: () => {},
+}
+
+export class OpenRGBClient {
+  private readonly host: string
+  private readonly port: number
+  private readonly clientName: string
+  private readonly log: Logger
+  private readonly onDevicesReloaded: ((devices: Device[]) => void) | undefined
+
+  private socket: net.Socket | null = null
+  private rxBuf: Buffer = Buffer.alloc(0)
+  private waiters = new Map<number, Waiter[]>()
+
+  private connectPromise: Promise<boolean> | null = null
+  private retryTimer: NodeJS.Timeout | null = null
+  private retryDelay = RETRY_MIN_MS
+
+  private protocol = CLIENT_PROTOCOL_VERSION
+  private devices: Device[] = []
+  private ready = false
+  private disposed = false
+
+  /** Guards against overlapping device reloads triggered by rapid events. */
+  private reloading: Promise<void> | null = null
+
+  constructor(options: ClientOptions = {}) {
+    this.host = options.host ?? DEFAULT_HOST
+    this.port = options.port ?? DEFAULT_PORT
+    this.clientName = options.clientName ?? "opencode"
+    this.log = options.logger ?? noopLogger
+    this.onDevicesReloaded = options.onDevicesReloaded
+  }
+
+  get isReady(): boolean {
+    return this.ready
+  }
+
+  get protocolVersion(): number {
+    return this.protocol
+  }
+
+  getDevices(): readonly Device[] {
+    return this.devices
+  }
+
+  /*-------------------------------------------------------------------------*\
+  | Connection lifecycle                                                      |
+  \*-------------------------------------------------------------------------*/
+
+  /** Resolves true when connected and the device list is loaded. */
+  async ensureReady(): Promise<boolean> {
+    if (this.disposed) return false
+    if (this.ready) return true
+    if (this.connectPromise) return this.connectPromise
+
+    this.connectPromise = this.connect().finally(() => {
+      this.connectPromise = null
+    })
+    return this.connectPromise
+  }
+
+  private async connect(): Promise<boolean> {
+    if (this.disposed) return false
+
+    let socket: net.Socket
+    try {
+      socket = await this.openSocket()
+    } catch (error) {
+      this.log.debug(`connect failed: ${describe(error)}`)
+      this.scheduleRetry()
+      return false
+    }
+
+    this.socket = socket
+    this.rxBuf = Buffer.alloc(0)
+
+    socket.on("data", (chunk) => this.onData(chunk))
+    socket.on("error", (error) => this.onDisconnect(`socket error: ${describe(error)}`))
+    socket.on("close", () => this.onDisconnect("socket closed"))
+
+    try {
+      // The server does not reply to SET_CLIENT_NAME.
+      this.send(0, PacketId.SET_CLIENT_NAME, encodeClientName(this.clientName))
+
+      this.protocol = await this.negotiateProtocol()
+      this.log.debug(`connected, protocol ${this.protocol}`)
+
+      await this.loadDevices()
+
+      this.ready = true
+      this.retryDelay = RETRY_MIN_MS
+      return true
+    } catch (error) {
+      this.log.debug(`handshake failed: ${describe(error)}`)
+      this.teardownSocket()
+      this.scheduleRetry()
+      return false
+    }
+  }
+
+  private openSocket(): Promise<net.Socket> {
+    return new Promise((resolve, reject) => {
+      const socket = net.connect({ host: this.host, port: this.port })
+      socket.setNoDelay(true)
+      // Do not keep the host process alive on our account.
+      socket.unref()
+
+      const timer = setTimeout(() => {
+        socket.destroy()
+        reject(new Error(`connect timeout after ${CONNECT_TIMEOUT_MS}ms`))
+      }, CONNECT_TIMEOUT_MS)
+      timer.unref?.()
+
+      socket.once("connect", () => {
+        clearTimeout(timer)
+        socket.removeAllListeners("error")
+        resolve(socket)
+      })
+      socket.once("error", (error) => {
+        clearTimeout(timer)
+        reject(error)
+      })
+    })
+  }
+
+  private async negotiateProtocol(): Promise<number> {
+    this.send(0, PacketId.REQUEST_PROTOCOL_VERSION, encodeProtocolVersion(CLIENT_PROTOCOL_VERSION))
+    try {
+      const frame = await this.waitFor(PacketId.REQUEST_PROTOCOL_VERSION, VERSION_TIMEOUT_MS)
+      const server = frame.data.length >= 4 ? frame.data.readUInt32LE(0) : 0
+      return Math.min(server, CLIENT_PROTOCOL_VERSION)
+    } catch {
+      // Protocol-0 servers stay silent here. That is a valid answer.
+      this.log.debug("no protocol version response; assuming protocol 0")
+      return 0
+    }
+  }
+
+  private onDisconnect(reason: string): void {
+    if (!this.socket && !this.ready) return
+    this.log.debug(`disconnected: ${reason}`)
+    this.teardownSocket()
+    if (!this.disposed) this.scheduleRetry()
+  }
+
+  private teardownSocket(): void {
+    this.ready = false
+    this.devices = []
+    this.rxBuf = Buffer.alloc(0)
+
+    for (const list of this.waiters.values()) {
+      for (const waiter of list) {
+        clearTimeout(waiter.timer)
+        waiter.reject(new Error("connection lost"))
+      }
+    }
+    this.waiters.clear()
+
+    const socket = this.socket
+    this.socket = null
+    if (socket) {
+      socket.removeAllListeners()
+      socket.destroy()
+    }
+  }
+
+  private scheduleRetry(): void {
+    if (this.disposed || this.retryTimer) return
+
+    const delay = this.retryDelay
+    this.retryDelay = Math.min(this.retryDelay * 2, RETRY_MAX_MS)
+
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null
+      void this.ensureReady()
+    }, delay)
+    this.retryTimer.unref?.()
+  }
+
+  dispose(): void {
+    this.disposed = true
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer)
+      this.retryTimer = null
+    }
+    this.teardownSocket()
+  }
+
+  /*-------------------------------------------------------------------------*\
+  | Framing                                                                   |
+  \*-------------------------------------------------------------------------*/
+
+  private onData(chunk: Buffer): void {
+    this.rxBuf = this.rxBuf.length === 0 ? chunk : Buffer.concat([this.rxBuf, chunk])
+
+    let frames: Frame[]
+    try {
+      const decoded = decodeFrames(this.rxBuf)
+      frames = decoded.frames
+      this.rxBuf = decoded.rest
+    } catch (error) {
+      this.log.warn(`frame decode failed: ${describe(error)}`)
+      this.rxBuf = Buffer.alloc(0)
+      return
+    }
+
+    for (const frame of frames) {
+      if (frame.pktId === PacketId.DEVICE_LIST_UPDATED) {
+        this.log.debug("server reports device list updated")
+        void this.reloadDevices()
+        continue
+      }
+
+      const list = this.waiters.get(frame.pktId)
+      const waiter = list?.shift()
+      if (!waiter) continue
+      clearTimeout(waiter.timer)
+      waiter.resolve(frame)
+    }
+  }
+
+  private waitFor(pktId: number, timeoutMs = RESPONSE_TIMEOUT_MS): Promise<Frame> {
+    return new Promise<Frame>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const list = this.waiters.get(pktId)
+        if (list) {
+          const idx = list.findIndex((w) => w.timer === timer)
+          if (idx !== -1) list.splice(idx, 1)
+        }
+        reject(new Error(`timeout waiting for packet ${pktId}`))
+      }, timeoutMs)
+      timer.unref?.()
+
+      const list = this.waiters.get(pktId)
+      if (list) list.push({ resolve, reject, timer })
+      else this.waiters.set(pktId, [{ resolve, reject, timer }])
+    })
+  }
+
+  private send(devId: number, pktId: number, data?: Buffer, sync = false): boolean {
+    const socket = this.socket
+    if (!socket || socket.destroyed) return false
+
+    const packet = encodePacket(devId, pktId, data)
+
+    if (sync && this.writeSync(packet)) return true
+
+    try {
+      socket.write(packet)
+      return true
+    } catch (error) {
+      this.log.debug(`write failed: ${describe(error)}`)
+      return false
+    }
+  }
+
+  /**
+   * Write straight to the socket's file descriptor, bypassing libuv's queue.
+   *
+   * This exists for one reason: restoring the user's lighting from a
+   * `process.on("exit")` handler. Normal `socket.write` calls only enqueue
+   * data, and the process terminates before the event loop can flush them, so
+   * the restore silently never reaches OpenRGB and the lights stay stuck on
+   * whatever the last state color was.
+   *
+   * Reaching for `_handle.fd` is private API, so every failure path falls back
+   * to a queued write. Returns true only if the bytes were fully written.
+   */
+  private writeSync(packet: Buffer): boolean {
+    const handle = (this.socket as unknown as { _handle?: { fd?: unknown } } | null)?._handle
+    const fd = handle?.fd
+    if (typeof fd !== "number" || fd < 0) return false
+
+    let written = 0
+    // Sockets are non-blocking, so a full kernel buffer surfaces as EAGAIN.
+    // Packets here are tiny (tens of bytes), so a short bounded retry is
+    // plenty, and we must not spin forever inside an exit handler.
+    for (let attempt = 0; attempt < 64 && written < packet.length; attempt++) {
+      try {
+        written += fs.writeSync(fd, packet, written, packet.length - written)
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code
+        if (code === "EAGAIN") continue
+        return false
+      }
+    }
+
+    return written === packet.length
+  }
+
+  /*-------------------------------------------------------------------------*\
+  | Device discovery                                                          |
+  \*-------------------------------------------------------------------------*/
+
+  private async loadDevices(): Promise<void> {
+    this.send(0, PacketId.REQUEST_CONTROLLER_COUNT)
+    const countFrame = await this.waitFor(PacketId.REQUEST_CONTROLLER_COUNT)
+    const count = countFrame.data.length >= 4 ? countFrame.data.readUInt32LE(0) : 0
+
+    const devices: Device[] = []
+    for (let i = 0; i < count; i++) {
+      // Protocol 0 expects an empty body here; 1+ expects the negotiated version.
+      const body = this.protocol >= 1 ? encodeProtocolVersion(this.protocol) : undefined
+      this.send(i, PacketId.REQUEST_CONTROLLER_DATA, body)
+      const frame = await this.waitFor(PacketId.REQUEST_CONTROLLER_DATA)
+      try {
+        devices.push(decodeDevice(frame.data, this.protocol, i))
+      } catch (error) {
+        this.log.warn(`failed to decode device ${i}: ${describe(error)}`)
+      }
+    }
+
+    this.devices = devices
+    this.log.debug(`loaded ${devices.length} device(s)`)
+    this.onDevicesReloaded?.(devices)
+  }
+
+  /** Re-read the device list, e.g. after DEVICE_LIST_UPDATED. */
+  async reloadDevices(): Promise<void> {
+    if (this.reloading) return this.reloading
+    this.reloading = (async () => {
+      if (!this.socket || this.socket.destroyed) return
+      try {
+        await this.loadDevices()
+      } catch (error) {
+        this.log.warn(`device reload failed: ${describe(error)}`)
+      }
+    })().finally(() => {
+      this.reloading = null
+    })
+    return this.reloading
+  }
+
+  /*-------------------------------------------------------------------------*\
+  | Writes (fire-and-forget on protocol 5)                                    |
+  \*-------------------------------------------------------------------------*/
+
+  /**
+   * @param sync Write synchronously, bypassing the event loop. Required when
+   * called from a `process.on("exit")` handler, where queued writes never
+   * flush. Do not use on the hot path.
+   */
+  updateLeds(deviceIndex: number, colors: readonly number[], sync = false): boolean {
+    if (colors.length === 0) return false
+    return this.send(
+      deviceIndex,
+      PacketId.RGBCONTROLLER_UPDATELEDS,
+      encodeUpdateLeds(colors),
+      sync,
+    )
+  }
+
+  /** @param sync See {@link OpenRGBClient.updateLeds}. */
+  updateMode(deviceIndex: number, modeIndex: number, mode: Mode, sync = false): boolean {
+    return this.send(
+      deviceIndex,
+      PacketId.RGBCONTROLLER_UPDATEMODE,
+      encodeUpdateMode(modeIndex, mode, this.protocol),
+      sync,
+    )
+  }
+
+  setCustomMode(deviceIndex: number): boolean {
+    return this.send(deviceIndex, PacketId.RGBCONTROLLER_SETCUSTOMMODE)
+  }
+}
+
+/*---------------------------------------------------------------------------*\
+| Helpers                                                                     |
+\*---------------------------------------------------------------------------*/
+
+/**
+ * Pick the mode to use for direct per-LED control.
+ *
+ * Preference order: a mode literally named "Direct", then any mode advertising
+ * per-LED colors, then nothing (in which case the caller should fall back to
+ * `SETCUSTOMMODE`).
+ */
+export function findDirectMode(device: Device): { index: number; mode: Mode } | null {
+  const named = device.modes.findIndex((m) => /^direct$/i.test(m.name.trim()))
+  if (named !== -1) {
+    const mode = device.modes[named]
+    if (mode) return { index: named, mode }
+  }
+
+  const perLed = device.modes.findIndex((m) => (m.flags & ModeFlag.HAS_PER_LED_COLOR) !== 0)
+  if (perLed !== -1) {
+    const mode = device.modes[perLed]
+    if (mode) return { index: perLed, mode }
+  }
+
+  return null
+}
+
+export function describe(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return String(error)
+}