airaknit 1.1.2-rc.9

package/src/server/nats-connector.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect, afterEach } from "bun:test"
+import { NatsServer } from "@lagz0ne/nats-embedded"
+import { NatsConnector } from "./nats-connector"
+
+describe("NatsConnector", () => {
+  let server: NatsServer | null = null
+  let connector: NatsConnector | null = null
+
+  afterEach(async () => {
+    await connector?.dispose()
+    connector = null
+    await server?.stop()
+    server = null
+  })
+
+  test("connects to a running NATS server", async () => {
+    const token = "test-" + Date.now()
+    server = await NatsServer.start({ websocket: true, jetstream: true, token })
+    connector = await NatsConnector.connect({
+      natsUrl: server.url,
+      natsWsUrl: server.wsUrl!,
+      natsWsPort: server.wsPort!,
+      token,
+    })
+    expect(connector.nc).toBeDefined()
+    expect(connector.natsUrl).toBe(server.url)
+    expect(connector.natsWsUrl).toBe(server.wsUrl!)
+    expect(connector.natsWsPort).toBe(server.wsPort!)
+    expect(connector.authToken).toBe(token)
+  })
+
+  test("dispose drains the connection", async () => {
+    server = await NatsServer.start({ token: "t" })
+    connector = await NatsConnector.connect({
+      natsUrl: server.url,
+      natsWsUrl: server.wsUrl ?? "",
+      natsWsPort: server.wsPort ?? 0,
+      token: "t",
+    })
+    await connector.dispose()
+    // After dispose, connection should be closed
+    expect(connector.nc.isClosed()).toBe(true)
+    connector = null // prevent double-dispose in afterEach
+  })
+
+  test("connect without token works on unauthenticated server", async () => {
+    server = await NatsServer.start({})
+    connector = await NatsConnector.connect({
+      natsUrl: server.url,
+      natsWsUrl: "",
+      natsWsPort: 0,
+    })
+    expect(connector.nc).toBeDefined()
+    expect(connector.authToken).toBeUndefined()
+  })
+})

package/src/server/nats-connector.ts

@@ -0,0 +1,71 @@
+import { connect, type NatsConnection } from "@nats-io/transport-node"
+import { LOG_PREFIX } from "../shared/branding"
+
+export interface NatsConnectorOptions {
+  natsUrl: string
+  natsWsUrl: string
+  natsWsPort: number
+  token?: string
+}
+
+export class NatsConnector {
+  readonly natsUrl: string
+  readonly natsWsUrl: string
+  readonly natsWsPort: number
+  readonly authToken: string | undefined
+  readonly nc: NatsConnection
+  private disposed = false
+
+  private constructor(
+    connection: NatsConnection,
+    natsUrl: string,
+    natsWsUrl: string,
+    natsWsPort: number,
+    token?: string
+  ) {
+    this.nc = connection
+    this.natsUrl = natsUrl
+    this.natsWsUrl = natsWsUrl
+    this.natsWsPort = natsWsPort
+    this.authToken = token
+  }
+
+  static async connect(options: NatsConnectorOptions): Promise<NatsConnector> {
+    const tokenOpt = options.token ? { token: options.token } : undefined
+    const connection = await connect({
+      servers: options.natsUrl,
+      ...tokenOpt,
+    })
+
+    console.warn(LOG_PREFIX, `NATS connector connected — ${options.natsUrl}`)
+
+    return new NatsConnector(
+      connection,
+      options.natsUrl,
+      options.natsWsUrl,
+      options.natsWsPort,
+      options.token
+    )
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return
+    this.disposed = true
+    try {
+      await this.nc.drain()
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.warn(LOG_PREFIX, `NATS connection drain failed: ${message}`)
+    }
+    console.warn(LOG_PREFIX, "NATS connector disconnected")
+  }
+
+  getReadiness() {
+    return {
+      ok: !this.disposed && !this.nc.isClosed(),
+      natsUrl: this.natsUrl,
+      natsWsUrl: this.natsWsUrl,
+      natsWsPort: this.natsWsPort,
+    }
+  }
+}

package/src/server/nats-daemon-manager.test.ts

@@ -0,0 +1,76 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test"
+import { connect } from "@nats-io/transport-node"
+import { NatsDaemonManager } from "./nats-daemon-manager"
+
+describe("NatsDaemonManager", () => {
+  let manager: NatsDaemonManager | null = null
+  let prevAuthMode: string | undefined
+
+  // These tests exercise the token-mode daemon path (they pass a token and
+  // connect with it). The server default is now NATS_AUTH_MODE=callout, which
+  // spawns the callout daemon (requires NATS_DATA_DIR + key material); the
+  // callout daemon path is covered by src/nats/auth-callout/callout.integration.test.ts.
+  beforeEach(() => {
+    prevAuthMode = process.env.NATS_AUTH_MODE
+    process.env.NATS_AUTH_MODE = "token"
+  })
+
+  afterEach(async () => {
+    await manager?.dispose()
+    manager = null
+    if (prevAuthMode === undefined) delete process.env.NATS_AUTH_MODE
+    else process.env.NATS_AUTH_MODE = prevAuthMode
+  })
+
+  test("ensureDaemon starts daemon and returns connection info", async () => {
+    manager = NatsDaemonManager.embedded()
+    const info = await manager.ensureDaemon({ token: "test-" + Date.now() })
+    expect(info).toHaveProperty("url")
+    expect(info).toHaveProperty("wsUrl")
+    expect(info).toHaveProperty("wsPort")
+    expect(info).toHaveProperty("pid")
+    expect(info.url).toMatch(/^nats:\/\//)
+  })
+
+  test("ensureDaemon returns working NATS connection", async () => {
+    const token = "test-" + Date.now()
+    manager = NatsDaemonManager.embedded()
+    const info = await manager.ensureDaemon({ token })
+
+    const nc = await connect({ servers: info.url, token })
+    expect(nc).toBeDefined()
+    await nc.drain()
+  })
+
+  test("ensureDaemon reuses existing daemon on second call", async () => {
+    const token = "test-" + Date.now()
+    manager = NatsDaemonManager.embedded()
+    const info1 = await manager.ensureDaemon({ token })
+    const info2 = await manager.ensureDaemon({ token })
+    expect(info1.pid).toBe(info2.pid)
+    expect(info1.url).toBe(info2.url)
+  })
+
+  test("dispose kills the daemon process", async () => {
+    const token = "test-" + Date.now()
+    manager = NatsDaemonManager.embedded()
+    const info = await manager.ensureDaemon({ token })
+    const pid = info.pid
+
+    await manager.dispose()
+    manager = null
+
+    // Give OS time to reap
+    await new Promise(r => setTimeout(r, 200))
+
+    // Process should be dead
+    try {
+      process.kill(pid, 0) // signal 0 = check if alive
+      // If we get here, process is still alive — fail
+      expect(true).toBe(false)
+    } catch {
+      // Expected — process is dead
+      expect(true).toBe(true)
+    }
+  })
+})

package/src/server/nats-daemon-manager.ts

@@ -0,0 +1,174 @@
+import { LOG_PREFIX } from "../shared/branding"
+
+export interface NatsDaemonInfo {
+  url: string
+  wsUrl: string
+  wsPort: number
+  pid: number
+}
+
+export interface NatsDaemonReadiness extends NatsDaemonInfo {
+  ok: boolean
+}
+
+export class NatsDaemonManager {
+  private daemonProcess: ReturnType<typeof Bun.spawn> | null = null
+  private info: NatsDaemonInfo | null = null
+  private readonly external: boolean
+
+  private constructor(external: boolean) {
+    this.external = external
+  }
+
+  /** Create a manager that spawns and owns the NATS daemon process. */
+  static embedded(): NatsDaemonManager {
+    return new NatsDaemonManager(false)
+  }
+
+  /** Create a manager that connects to an externally-managed NATS daemon (e.g. separate systemd unit). */
+  static fromExternal(opts: { natsUrl: string; wsPort: number }): NatsDaemonManager {
+    const mgr = new NatsDaemonManager(true)
+    const url = new URL(opts.natsUrl)
+    mgr.info = {
+      url: opts.natsUrl,
+      wsUrl: `ws://${url.hostname}:${opts.wsPort}`,
+      wsPort: opts.wsPort,
+      pid: 0, // external — no PID to track
+    }
+    console.warn(LOG_PREFIX, `Connected to external NATS — url: ${opts.natsUrl}, ws: ${opts.wsPort}`)
+    return mgr
+  }
+
+  async ensureDaemon(options: {
+    token: string
+    host?: string
+  }): Promise<NatsDaemonInfo> {
+    if (this.external && this.info) return this.info
+
+    // Reuse if already running and alive
+    if (this.info && this.daemonProcess) {
+      try {
+        process.kill(this.info.pid, 0) // check alive
+        return this.info
+      } catch {
+        // Process died, restart
+        this.daemonProcess = null
+        this.info = null
+      }
+    }
+
+    const authMode = process.env.NATS_AUTH_MODE ?? "callout"
+    const isCallout = authMode === "callout"
+
+    const daemonScript = isCallout
+      ? new URL("../nats/nats-daemon-callout.ts", import.meta.url).pathname
+      : new URL("../nats/nats-daemon.ts", import.meta.url).pathname
+
+    const {
+      NATS_DATA_DIR: natsDataDir,
+      NATS_URL: _natsUrl,
+      NATS_MODE: _natsMode,
+      NATS_WS_PORT: _natsWsPort,
+      NATS_PORT: natsPort,
+      NATS_STORE_DIR: _natsStoreDir,
+      NATS_HTTP_PORT: _natsHttpPort,
+      ...spawnEnv
+    } = process.env
+
+    const child = Bun.spawn(["bun", "run", daemonScript], {
+      env: {
+        ...spawnEnv,
+        // In callout mode the daemon reads the token secret from disk; NATS_TOKEN
+        // is unused by the callout child but harmless to pass. In token mode it
+        // is the shared auth token.
+        NATS_TOKEN: options.token,
+        ...(options.host ? { NATS_HOST: options.host } : {}),
+        // Callout mode: pass NATS_DATA_DIR so the child can load keys + secret.
+        // Token mode: strip it (was previous behaviour, preserve for compat).
+        ...(isCallout && natsDataDir ? { NATS_DATA_DIR: natsDataDir } : {}),
+        // Pin the NATS TCP port when NATS_PORT is set, so a paired runner's stored
+        // credential (nats://host:port) survives server restarts instead of being
+        // invalidated by a new ephemeral port each boot. Unset => daemon picks an
+        // ephemeral port as before. (decision: docs/stories/nats-port-pin)
+        ...(natsPort ? { NATS_PORT: natsPort } : {}),
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+
+    // Read JSON info from stdout
+    const reader = child.stdout.getReader()
+    const { value } = await reader.read()
+    if (!value) {
+      child.kill("SIGTERM")
+      throw new Error("NATS daemon produced no output")
+    }
+
+    const text = new TextDecoder().decode(value).trim()
+    let info: NatsDaemonInfo
+    try {
+      info = JSON.parse(text) as NatsDaemonInfo
+    } catch (error) {
+      child.kill("SIGTERM")
+      const message = error instanceof Error ? error.message : String(error)
+      throw new Error(`Failed to parse NATS daemon output: ${message}`)
+    }
+
+    this.daemonProcess = child
+    this.info = info
+
+    // Observability (decision 0012): forward the daemon child's stderr (which now
+    // carries the nats-server runtime logs) to this process's console, so it
+    // reaches VictoriaLogs via the console tee. Previously inherited to the
+    // terminal only, leaving the NATS layer invisible in the log store.
+    void (async () => {
+      try {
+        const decoder = new TextDecoder()
+        let buf = ""
+        for await (const chunk of child.stderr as unknown as AsyncIterable<Uint8Array>) {
+          buf += decoder.decode(chunk)
+          const lines = buf.split("\n")
+          buf = lines.pop() ?? ""
+          for (const line of lines) {
+            if (line.trim()) console.warn("[nats-daemon]", line)
+          }
+        }
+      } catch {
+        // daemon exited or stderr closed — nothing to forward
+      }
+    })()
+
+    console.warn(LOG_PREFIX, `NATS daemon started — pid: ${info.pid}, url: ${info.url}`)
+
+    return info
+  }
+
+  getReadiness(): NatsDaemonReadiness | null {
+    if (!this.info) return null
+    if (this.external) {
+      // External daemon: no PID to check — rely on NATS connection health instead
+      return { ...this.info, ok: true }
+    }
+    let ok = false
+    try {
+      process.kill(this.info.pid, 0)
+      ok = true
+    } catch {
+      ok = false
+    }
+    return {
+      ...this.info,
+      ok,
+    }
+  }
+
+  async dispose(): Promise<void> {
+    if (this.external) return // don't kill external daemon
+    if (this.daemonProcess) {
+      this.daemonProcess.kill("SIGTERM")
+      await this.daemonProcess.exited
+      this.daemonProcess = null
+      this.info = null
+      console.warn(LOG_PREFIX, "NATS daemon stopped")
+    }
+  }
+}