@wandelbots/nova-js 3.12.0 → 3.13.0-pr.307.0c31cef

package/src/experimental/nats/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Experimental typed NATS client for the Wandelbots NOVA messaging API,
+ * generated from src/asyncapi.yaml (see scripts/generate-nats-client.ts).
+ *
+ * This API is experimental and may change without a major version bump.
+ */
+export type {
+  NatsOperationParams,
+  NatsReplyPayloads,
+  NatsRequestPayloads,
+  NatsRequestSubject,
+  NatsSubscribePayloads,
+  NatsSubscribeSubject,
+} from "../../lib/experimental/nats/generated/operations.ts"
+export { NovaNatsClient } from "../../lib/experimental/nats/NovaNatsClient.ts"
+export type { NovaNatsClientConfig } from "../../lib/experimental/nats/NovaNatsClient.ts"

package/src/lib/experimental/nats/NovaNatsClient.ts

@@ -0,0 +1,101 @@
+import {
+  type ConnectionOptions,
+  type Msg,
+  type NatsConnection,
+  wsconnect,
+} from "@nats-io/nats-core"
+import { buildSubject } from "./buildSubject.ts"
+import type {
+  NatsOperationParams,
+  NatsReplyPayloads,
+  NatsRequestPayloads,
+  NatsRequestSubject,
+  NatsSubscribePayloads,
+  NatsSubscribeSubject,
+} from "./generated/operations.ts"
+
+export type NovaNatsClientConfig = ConnectionOptions
+
+/**
+ * Typed NATS client for the Wandelbots NOVA messaging API, generated from
+ * src/asyncapi.yaml (see scripts/generate-nats-client.ts).
+ *
+ * Connects over WebSocket via `@nats-io/nats-core`'s `wsconnect`.
+ */
+export class NovaNatsClient {
+  readonly config: NovaNatsClientConfig
+  connection: NatsConnection | null = null
+
+  constructor(config: NovaNatsClientConfig) {
+    this.config = config
+  }
+
+  /** Connects to NATS if not already connected, and returns the connection. */
+  async connect(): Promise<NatsConnection> {
+    if (!this.connection) {
+      this.connection = await wsconnect(this.config)
+    }
+    return this.connection
+  }
+
+  /** Closes the underlying NATS connection, if open. */
+  async close(): Promise<void> {
+    await this.connection?.close()
+    this.connection = null
+  }
+
+  /**
+   * Subscribes to a NATS subject published by the server, invoking `handler`
+   * with the JSON-decoded payload of every message received.
+   *
+   * `subject` is the subject template as it appears on the wire, e.g.
+   * `"nova.v2.cells.{cell}"`, with `{param}` placeholders filled in from
+   * `params`.
+   *
+   * Returns a function that unsubscribes when called.
+   */
+  async subscribe<K extends NatsSubscribeSubject>(
+    subject: K,
+    params: NatsOperationParams[K],
+    handler: (payload: NatsSubscribePayloads[K], msg: Msg) => void,
+  ): Promise<() => void> {
+    const nc = await this.connect()
+    const resolvedSubject = buildSubject(subject, params)
+    const sub = nc.subscribe(resolvedSubject)
+
+    ;(async () => {
+      for await (const msg of sub) {
+        handler(msg.json<NatsSubscribePayloads[K]>(), msg)
+      }
+    })().catch((err: unknown) => {
+      console.error(
+        `Error handling NATS subscription for "${resolvedSubject}"`,
+        err,
+      )
+    })
+
+    return () => sub.unsubscribe()
+  }
+
+  /**
+   * Sends a request payload for a NATS subject the server receives, and
+   * waits for the JSON-decoded reply.
+   *
+   * `subject` is the subject template as it appears on the wire, e.g.
+   * `"nova.v2.cells.{cell}.bus-ios.ios.set"`, with `{param}` placeholders
+   * filled in from `params`.
+   */
+  async request<K extends NatsRequestSubject>(
+    subject: K,
+    params: NatsOperationParams[K],
+    payload: NatsRequestPayloads[K],
+    opts: { timeout?: number } = {},
+  ): Promise<NatsReplyPayloads[K]> {
+    const nc = await this.connect()
+    const resolvedSubject = buildSubject(subject, params)
+    const msg = await nc.request(resolvedSubject, JSON.stringify(payload), {
+      timeout: opts.timeout ?? 5000,
+    })
+    return msg.json<NatsReplyPayloads[K]>()
+  }
+}

package/src/lib/experimental/nats/buildSubject.ts

@@ -0,0 +1,68 @@
+/**
+ * Builds a NATS subject from an AsyncAPI-style channel address template
+ * (e.g. `"{instance}.v2.cells.{cell}"`) by substituting each `{param}`
+ * placeholder with the corresponding value from `params`.
+ */
+
+function isValidSubjectChar(char: string): boolean {
+  const code = char.charCodeAt(0)
+  return (
+    (code >= 48 && code <= 57) || // 0-9
+    (code >= 65 && code <= 90) || // A-Z
+    (code >= 97 && code <= 122) || // a-z
+    char === "-" ||
+    char === "_"
+  )
+}
+
+function isValidSubjectValue(value: string): boolean {
+  if (value.length === 0) return false
+  for (const char of value) {
+    if (!isValidSubjectChar(char)) return false
+  }
+  return true
+}
+
+export function buildSubject(
+  template: string,
+  params: Record<string, string>,
+): string {
+  // Scanned manually (rather than with a regex like /\{([^}]+)\}/g) to avoid
+  // a polynomial-time backtracking blowup on pathological input, e.g. a
+  // template consisting of many "{" characters with no closing "}".
+  let result = ""
+  let cursor = 0
+
+  while (cursor < template.length) {
+    const openIndex = template.indexOf("{", cursor)
+    if (openIndex === -1) {
+      result += template.slice(cursor)
+      break
+    }
+
+    const closeIndex = template.indexOf("}", openIndex + 1)
+    if (closeIndex === -1) {
+      result += template.slice(cursor)
+      break
+    }
+
+    result += template.slice(cursor, openIndex)
+    const paramName = template.slice(openIndex + 1, closeIndex)
+    const value = params[paramName]
+    if (value === undefined) {
+      throw new Error(
+        `Missing value for subject parameter "${paramName}" in template "${template}"`,
+      )
+    }
+    if (!isValidSubjectValue(value)) {
+      throw new Error(
+        `Invalid value for subject parameter "${paramName}": "${value}" (must be non-empty and contain only letters, digits, "-", and "_")`,
+      )
+    }
+    result += value
+
+    cursor = closeIndex + 1
+  }
+
+  return result
+}

package/src/lib/experimental/nats/generated/operations.ts

@@ -0,0 +1,203 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT.
+ * Generated from src/asyncapi.yaml by scripts/generate-nats-client.ts.
+ * Run `pnpm generate:nats` to regenerate.
+ */
+
+import type {
+  App,
+  AppCreatedEvent,
+  AppDeletedEvent,
+  AppUpdatedEvent,
+  BusIOsState,
+  Cell,
+  CellCreatedEvent,
+  CellCycleEvent,
+  CellDeletedEvent,
+  CellUpdatedEvent,
+  CollisionSetup,
+  ListIOValuesResponse,
+  MotionGroupDescription,
+  NatsErrorPayload,
+  NetworkStatusChangedEvent,
+  ProgramStatus,
+  RobotController,
+  RobotControllerCreatedEvent,
+  RobotControllerDeletedEvent,
+  RobotControllerState,
+  RobotControllerUpdatedEvent,
+  SelectIOs,
+  ServiceStatusList,
+  StreamIOValuesResponse,
+  SystemUpdateCompletedEvent,
+  SystemUpdateStartedEvent,
+} from "./types.ts"
+
+/** Subject parameters required by each NATS subject, e.g. "nova.v2.cells.{cell}". */
+export interface NatsOperationParams {
+  /** publishCell */
+  "nova.v2.cells.{cell}": { cell: string }
+  /** publishApp */
+  "nova.v2.cells.{cell}.apps.{app}": { cell: string; app: string }
+  /** publishProgramStatus */
+  "nova.v2.cells.{cell}.programs": { cell: string }
+  /** publishRobotController */
+  "nova.v2.cells.{cell}.controllers.{controller}": {
+    cell: string
+    controller: string
+  }
+  /** publishCellStatus */
+  "nova.v2.cells.{cell}.status": { cell: string }
+  /** publishCellCycle */
+  "nova.v2.cells.{cell}.cycle": { cell: string }
+  /** publishSystemStatus */
+  "nova.v2.system.status": Record<string, never>
+  /** publishCollisionSetup */
+  "nova.v2.cells.{cell}.collision.setups.{setup}": {
+    cell: string
+    setup: string
+  }
+  /** publishBUSIOStatus */
+  "nova.v2.cells.{cell}.bus-ios.status": { cell: string }
+  /** publishBUSIOsIOs */
+  "nova.v2.cells.{cell}.bus-ios.ios": { cell: string }
+  /** setBUSIOsIOs */
+  "nova.v2.cells.{cell}.bus-ios.ios.set": { cell: string }
+  /** selectRobotControllerIOs */
+  "nova.v2.cells.{cell}.controllers.{controller}.ios.select": {
+    cell: string
+    controller: string
+  }
+  /** publishRobotControllerIOs */
+  "nova.v2.cells.{cell}.controllers.{controller}.ios": {
+    cell: string
+    controller: string
+  }
+  /** publishRobotControllersState */
+  "nova.v2.cells.{cell}.controllers.{controller}.state": {
+    cell: string
+    controller: string
+  }
+  /** publishMotionGroupDescription */
+  "nova.v2.cells.{cell}.controllers.{controller}.motion-groups.{motion-group}.description": {
+    cell: string
+    controller: string
+    "motion-group": string
+  }
+  /** eventSystemUpdateStarted */
+  "nova.v2.events.system.update.started": Record<string, never>
+  /** eventSystemUpdateCompleted */
+  "nova.v2.events.system.update.completed": Record<string, never>
+  /** eventSystemNetworkStatusChanged */
+  "nova.v2.events.system.network.status.changed": Record<string, never>
+  /** eventCellCreated */
+  "nova.v2.events.cells.{cell}.created": { cell: string }
+  /** eventCellUpdated */
+  "nova.v2.events.cells.{cell}.updated": { cell: string }
+  /** eventCellDeleted */
+  "nova.v2.events.cells.{cell}.deleted": { cell: string }
+  /** eventAppCreated */
+  "nova.v2.events.cells.{cell}.apps.{app}.created": {
+    cell: string
+    app: string
+  }
+  /** eventAppUpdated */
+  "nova.v2.events.cells.{cell}.apps.{app}.updated": {
+    cell: string
+    app: string
+  }
+  /** eventAppDeleted */
+  "nova.v2.events.cells.{cell}.apps.{app}.deleted": {
+    cell: string
+    app: string
+  }
+  /** eventRobotControllerCreated */
+  "nova.v2.events.cells.{cell}.controllers.{controller}.created": {
+    cell: string
+    controller: string
+  }
+  /** eventRobotControllerUpdated */
+  "nova.v2.events.cells.{cell}.controllers.{controller}.updated": {
+    cell: string
+    controller: string
+  }
+  /** eventRobotControllerDeleted */
+  "nova.v2.events.cells.{cell}.controllers.{controller}.deleted": {
+    cell: string
+    controller: string
+  }
+}
+
+/** Payload types for subjects the server publishes and the client subscribes to. */
+export interface NatsSubscribePayloads {
+  /** publishCell */
+  "nova.v2.cells.{cell}": Cell
+  /** publishApp */
+  "nova.v2.cells.{cell}.apps.{app}": App
+  /** publishProgramStatus */
+  "nova.v2.cells.{cell}.programs": ProgramStatus
+  /** publishRobotController */
+  "nova.v2.cells.{cell}.controllers.{controller}": RobotController
+  /** publishCellStatus */
+  "nova.v2.cells.{cell}.status": ServiceStatusList
+  /** publishCellCycle */
+  "nova.v2.cells.{cell}.cycle": CellCycleEvent
+  /** publishSystemStatus */
+  "nova.v2.system.status": ServiceStatusList
+  /** publishCollisionSetup */
+  "nova.v2.cells.{cell}.collision.setups.{setup}": CollisionSetup
+  /** publishBUSIOStatus */
+  "nova.v2.cells.{cell}.bus-ios.status": BusIOsState
+  /** publishBUSIOsIOs */
+  "nova.v2.cells.{cell}.bus-ios.ios": ListIOValuesResponse
+  /** publishRobotControllerIOs */
+  "nova.v2.cells.{cell}.controllers.{controller}.ios": StreamIOValuesResponse
+  /** publishRobotControllersState */
+  "nova.v2.cells.{cell}.controllers.{controller}.state": RobotControllerState
+  /** publishMotionGroupDescription */
+  "nova.v2.cells.{cell}.controllers.{controller}.motion-groups.{motion-group}.description": MotionGroupDescription
+  /** eventSystemUpdateStarted */
+  "nova.v2.events.system.update.started": SystemUpdateStartedEvent
+  /** eventSystemUpdateCompleted */
+  "nova.v2.events.system.update.completed": SystemUpdateCompletedEvent
+  /** eventSystemNetworkStatusChanged */
+  "nova.v2.events.system.network.status.changed": NetworkStatusChangedEvent
+  /** eventCellCreated */
+  "nova.v2.events.cells.{cell}.created": CellCreatedEvent
+  /** eventCellUpdated */
+  "nova.v2.events.cells.{cell}.updated": CellUpdatedEvent
+  /** eventCellDeleted */
+  "nova.v2.events.cells.{cell}.deleted": CellDeletedEvent
+  /** eventAppCreated */
+  "nova.v2.events.cells.{cell}.apps.{app}.created": AppCreatedEvent
+  /** eventAppUpdated */
+  "nova.v2.events.cells.{cell}.apps.{app}.updated": AppUpdatedEvent
+  /** eventAppDeleted */
+  "nova.v2.events.cells.{cell}.apps.{app}.deleted": AppDeletedEvent
+  /** eventRobotControllerCreated */
+  "nova.v2.events.cells.{cell}.controllers.{controller}.created": RobotControllerCreatedEvent
+  /** eventRobotControllerUpdated */
+  "nova.v2.events.cells.{cell}.controllers.{controller}.updated": RobotControllerUpdatedEvent
+  /** eventRobotControllerDeleted */
+  "nova.v2.events.cells.{cell}.controllers.{controller}.deleted": RobotControllerDeletedEvent
+}
+
+export type NatsSubscribeSubject = keyof NatsSubscribePayloads
+
+/** Request payload types for subjects the client sends requests to. */
+export interface NatsRequestPayloads {
+  /** setBUSIOsIOs */
+  "nova.v2.cells.{cell}.bus-ios.ios.set": ListIOValuesResponse
+  /** selectRobotControllerIOs */
+  "nova.v2.cells.{cell}.controllers.{controller}.ios.select": SelectIOs
+}
+
+/** Reply payload types for request/reply subjects. */
+export interface NatsReplyPayloads {
+  /** setBUSIOsIOs */
+  "nova.v2.cells.{cell}.bus-ios.ios.set": NatsErrorPayload
+  /** selectRobotControllerIOs */
+  "nova.v2.cells.{cell}.controllers.{controller}.ios.select": NatsErrorPayload
+}
+
+export type NatsRequestSubject = keyof NatsRequestPayloads