@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213

package/src/nats/nats-provider.tsx

@@ -0,0 +1,146 @@
+'use client'
+
+import * as React from 'react'
+import type { NatsClient, NatsStatus } from './nats'
+import {
+  acquireClient,
+  releaseClient,
+  startConnectionLifecycle,
+  type AcquireClientOptions,
+  type NatsReconnectionBackoff,
+} from './shared-connection'
+
+export type { NatsReconnectionBackoff } from './shared-connection'
+
+export interface NatsProviderProps {
+  children: React.ReactNode
+  /** Return the current NATS WebSocket URL (or null when not yet available, e.g. unauthenticated). */
+  getWsUrl: () => string | null
+  /** Called before each reconnect attempt. */
+  onBeforeReconnect?: () => Promise<void> | void
+  clientConfig?: AcquireClientOptions
+  reconnectionBackoff?: NatsReconnectionBackoff
+  /**
+   * Bump this to force re-evaluating `getWsUrl()` (e.g. when auth state flips).
+   * Provider does not subscribe to external auth state by itself.
+   */
+  urlRevision?: unknown
+}
+
+export interface NatsContextValue {
+  client: NatsClient | null
+  status: NatsStatus
+  isReady: boolean
+  reconnectionCount: number
+}
+
+const NatsContext = React.createContext<NatsContextValue | null>(null)
+
+export function NatsProvider({
+  children,
+  getWsUrl,
+  onBeforeReconnect,
+  clientConfig,
+  reconnectionBackoff,
+  urlRevision,
+}: NatsProviderProps) {
+  const [client, setClient] = React.useState<NatsClient | null>(null)
+  const [status, setStatus] = React.useState<NatsStatus>('closed')
+  const [reconnectionCount, setReconnectionCount] = React.useState(0)
+
+  const getWsUrlRef = React.useRef(getWsUrl)
+  React.useEffect(() => {
+    getWsUrlRef.current = getWsUrl
+  }, [getWsUrl])
+
+  const onBeforeReconnectRef = React.useRef(onBeforeReconnect)
+  React.useEffect(() => {
+    onBeforeReconnectRef.current = onBeforeReconnect
+  }, [onBeforeReconnect])
+
+  const reconnectionBackoffRef = React.useRef(reconnectionBackoff)
+  React.useEffect(() => {
+    reconnectionBackoffRef.current = reconnectionBackoff
+  }, [reconnectionBackoff])
+
+  const clientConfigRef = React.useRef(clientConfig)
+  React.useEffect(() => {
+    clientConfigRef.current = clientConfig
+  }, [clientConfig])
+
+  const heldUrlRef = React.useRef<string | null>(null)
+  const hadConnectionBeforeRef = React.useRef(false)
+
+  React.useEffect(() => {
+    const wsUrl = getWsUrlRef.current()
+
+    if (!wsUrl) {
+      if (heldUrlRef.current) {
+        releaseClient(heldUrlRef.current)
+        heldUrlRef.current = null
+        setClient(null)
+        setStatus('closed')
+      }
+      return
+    }
+
+    if (heldUrlRef.current && heldUrlRef.current !== wsUrl) {
+      releaseClient(heldUrlRef.current)
+      heldUrlRef.current = null
+    }
+
+    const conn = acquireClient(wsUrl, clientConfigRef.current)
+    heldUrlRef.current = wsUrl
+    setClient(conn.client)
+    setStatus(conn.client.isConnected() ? 'connected' : 'connecting')
+
+    const lifecycle = startConnectionLifecycle({
+      conn,
+      wsUrl,
+      onBeforeReconnect: () => onBeforeReconnectRef.current?.(),
+      backoff: reconnectionBackoffRef.current,
+      getFreshUrl: () => getWsUrlRef.current(),
+      onStatusChange: (newStatus) => {
+        setStatus(newStatus)
+        if (newStatus === 'connected') {
+          if (hadConnectionBeforeRef.current) {
+            setReconnectionCount((c) => c + 1)
+          }
+          hadConnectionBeforeRef.current = true
+        }
+      },
+    })
+
+    return () => {
+      lifecycle.stop()
+      if (heldUrlRef.current) {
+        releaseClient(heldUrlRef.current)
+        heldUrlRef.current = null
+      }
+      setClient(null)
+      setStatus('closed')
+    }
+  }, [urlRevision])
+
+  const value = React.useMemo<NatsContextValue>(
+    () => ({
+      client,
+      status,
+      isReady: status === 'connected' && client !== null,
+      reconnectionCount,
+    }),
+    [client, status, reconnectionCount],
+  )
+
+  return <NatsContext.Provider value={value}>{children}</NatsContext.Provider>
+}
+
+export function useNats(): NatsContextValue {
+  const ctx = React.useContext(NatsContext)
+  if (!ctx) throw new Error('useNats must be used inside <NatsProvider>')
+  return ctx
+}
+
+export function useOptionalNats(): NatsContextValue | null {
+  return React.useContext(NatsContext)
+}

package/src/nats/nats.ts

@@ -9,6 +9,8 @@ import type {
   Subscription,
 } from 'nats.ws'
 
+export type { JsMsg, Msg, Subscription } from 'nats.ws'
+
 export type JetStreamDeliverPolicy = 'new' | 'byStartSequence'
 
 export interface JetStreamOrderedSubscribeOptions {

package/src/nats/shared-connection.ts

@@ -0,0 +1,285 @@
+import { createNatsClient, type NatsClient, type NatsStatus, type NatsStatusEvent } from './nats'
+
+export const NATS_DEFAULTS = {
+  SHARED_CLOSE_DELAY_MS: 3000,
+  CONNECT_TIMEOUT_MS: 10_000,
+  PING_INTERVAL_MS: 30_000,
+  MAX_PING_OUT: 3,
+  RETRY_INITIAL_DELAY_MS: 1000,
+  RETRY_MAX_DELAY_MS: 30_000,
+  RETRY_MULTIPLIER: 2,
+} as const
+
+export interface NatsReconnectionBackoff {
+  /** Number of fast retries before exponential phase kicks in. Default: 0. */
+  fastRetries?: number
+  /** Delay used during the fast-retry phase. Default: RETRY_INITIAL_DELAY_MS. */
+  fastRetryDelayMs?: number
+  /** Base delay for the exponential phase. Default: RETRY_INITIAL_DELAY_MS. */
+  initialDelayMs?: number
+  /** Upper cap on any single retry delay. Default: RETRY_MAX_DELAY_MS. */
+  maxDelayMs?: number
+  /** Per-attempt multiplier during exponential phase. Default: RETRY_MULTIPLIER. */
+  multiplier?: number
+}
+
+export interface SharedConnection {
+  wsUrl: string
+  client: NatsClient
+  connectPromise: Promise<void> | null
+  refCount: number
+  closeTimer: ReturnType<typeof setTimeout> | null
+  retryTimer: ReturnType<typeof setTimeout> | null
+  /**
+   * Identity of the consumer driving reconnect. When set, other consumers
+   * should observe status only and skip their own scheduleRetry — otherwise
+   * each disconnect triggers multiple concurrent connect() calls racing over
+   * connectPromise.
+   */
+  retryOwner: object | null
+}
+
+export interface AcquireClientOptions {
+  name?: string
+  user?: string
+  pass?: string
+  connectTimeoutMs?: number
+  pingIntervalMs?: number
+  maxPingOut?: number
+}
+
+export interface ReleaseClientOptions {
+  delayMs?: number
+}
+
+let shared: SharedConnection | null = null
+
+export function getSharedConnection(): SharedConnection | null {
+  return shared
+}
+
+export function acquireClient(url: string, opts?: AcquireClientOptions): SharedConnection {
+  if (shared?.wsUrl !== url) {
+    if (shared) {
+      if (shared.closeTimer) clearTimeout(shared.closeTimer)
+      const old = shared
+      shared = null
+      void old.client.close().catch(() => {})
+    }
+
+    const {
+      name = 'openframe-frontend',
+      user = 'machine',
+      pass = '',
+      connectTimeoutMs = NATS_DEFAULTS.CONNECT_TIMEOUT_MS,
+      pingIntervalMs = NATS_DEFAULTS.PING_INTERVAL_MS,
+      maxPingOut = NATS_DEFAULTS.MAX_PING_OUT,
+    } = opts ?? {}
+
+    const client = createNatsClient({
+      servers: url,
+      name,
+      user,
+      pass,
+      connectTimeoutMs,
+      reconnect: false,
+      pingIntervalMs,
+      maxPingOut,
+    })
+
+    shared = {
+      wsUrl: url,
+      client,
+      connectPromise: null,
+      refCount: 0,
+      closeTimer: null,
+      retryTimer: null,
+      retryOwner: null,
+    }
+  }
+
+  shared.refCount += 1
+  if (shared.closeTimer) {
+    clearTimeout(shared.closeTimer)
+    shared.closeTimer = null
+  }
+  return shared
+}
+
+export function releaseClient(url: string, opts?: ReleaseClientOptions): void {
+  if (!shared || shared.wsUrl !== url) return
+
+  shared.refCount = Math.max(0, shared.refCount - 1)
+  if (shared.refCount > 0) return
+
+  const delay = opts?.delayMs ?? NATS_DEFAULTS.SHARED_CLOSE_DELAY_MS
+  shared.closeTimer = setTimeout(() => {
+    const s = shared
+    shared = null
+    if (s) {
+      if (s.retryTimer) {
+        clearTimeout(s.retryTimer)
+        s.retryTimer = null
+      }
+      void s.client.close().catch(() => {})
+    }
+  }, delay)
+}
+
+export function getSharedConnectionFor(url: string | null | undefined): SharedConnection | null {
+  if (!url) return null
+  return shared && shared.wsUrl === url ? shared : null
+}
+
+// ---------------------------------------------------------------------------
+// Connection lifecycle: retry + status loop, shared by NatsProvider and the
+// chat hooks. Each consumer that wants to drive reconnect creates an
+// ownerToken and calls startConnectionLifecycle(). The first caller to claim
+// retryOwner runs the actual retry loop; subsequent claimants observe status
+// only. When the owner unmounts and releases retryOwner, the next status
+// event lets a surviving consumer pick up ownership opportunistically.
+// ---------------------------------------------------------------------------
+
+export interface ConnectionLifecycleOptions {
+  conn: SharedConnection
+  wsUrl: string
+  onBeforeReconnect?: () => Promise<void> | void
+  backoff?: NatsReconnectionBackoff
+  getFreshUrl: () => string | null
+  /** Called on every status change (after closed-guard). */
+  onStatusChange?: (status: NatsStatus, evt: NatsStatusEvent) => void
+  /**
+   * Decide which statuses should trigger a retry attempt. Defaults to closed +
+   * disconnected. Override to skip 'error' (JetStream protocol errors that
+   * don't close the WS) or include it.
+   */
+  shouldRetryOn?: (status: NatsStatus) => boolean
+}
+
+export interface ConnectionLifecycleHandle {
+  /** Stop observing status, clear any pending retry, release ownership if held. */
+  stop(): void
+}
+
+const defaultShouldRetryOn = (status: NatsStatus) => status === 'closed' || status === 'disconnected'
+
+export function startConnectionLifecycle(options: ConnectionLifecycleOptions): ConnectionLifecycleHandle {
+  const { conn, wsUrl } = options
+  // Each lifecycle gets its own identity for retry ownership. The first lifecycle to claim
+  // an unowned connection drives reconnect; later attachers observe status only until the
+  // owner releases (see opportunistic claim in scheduleRetry).
+  const ownerToken = {}
+  if (!conn.retryOwner) conn.retryOwner = ownerToken
+
+  let closed = false
+  let retryAttempt = 0
+
+  function emitSynthetic(status: NatsStatus) {
+    if (closed) return
+    options.onStatusChange?.(status, { status })
+    if (status === 'connected') {
+      retryAttempt = 0
+    }
+  }
+
+  function scheduleRetry() {
+    if (closed) return
+    if (getSharedConnectionFor(wsUrl) !== conn) return
+    if (!conn.retryOwner) conn.retryOwner = ownerToken
+    if (conn.retryOwner !== ownerToken) return
+
+    if (conn.retryTimer) {
+      clearTimeout(conn.retryTimer)
+      conn.retryTimer = null
+    }
+
+    const cfg = options.backoff ?? {}
+    const fastRetries = cfg.fastRetries ?? 0
+    const fastDelay = cfg.fastRetryDelayMs ?? NATS_DEFAULTS.RETRY_INITIAL_DELAY_MS
+    const baseDelay = cfg.initialDelayMs ?? NATS_DEFAULTS.RETRY_INITIAL_DELAY_MS
+    const maxDelay = cfg.maxDelayMs ?? NATS_DEFAULTS.RETRY_MAX_DELAY_MS
+    const multiplier = cfg.multiplier ?? NATS_DEFAULTS.RETRY_MULTIPLIER
+
+    const delay =
+      retryAttempt < fastRetries
+        ? fastDelay
+        : Math.min(baseDelay * multiplier ** (retryAttempt - fastRetries), maxDelay)
+    const jitteredDelay = delay * (0.5 + Math.random() * 0.5)
+    retryAttempt++
+
+    conn.retryTimer = setTimeout(async () => {
+      conn.retryTimer = null
+      if (closed) return
+      if (getSharedConnectionFor(wsUrl) !== conn) return
+
+      try {
+        await options.onBeforeReconnect?.()
+      } catch {
+        // continue regardless of token-refresh outcome
+      }
+      if (closed) return
+      if (getSharedConnectionFor(wsUrl) !== conn) return
+
+      const freshUrl = options.getFreshUrl()
+      if (freshUrl !== wsUrl) return
+
+      try {
+        conn.connectPromise = null
+        conn.connectPromise = conn.client.connect()
+        await conn.connectPromise
+        if (!closed && getSharedConnectionFor(wsUrl) === conn) {
+          retryAttempt = 0
+        }
+      } catch {
+        conn.connectPromise = null
+        if (!closed && getSharedConnectionFor(wsUrl) === conn) {
+          scheduleRetry()
+        }
+      }
+    }, jitteredDelay)
+  }
+
+  const shouldRetryOn = options.shouldRetryOn ?? defaultShouldRetryOn
+
+  const unsubStatus = conn.client.onStatus((evt) => {
+    if (closed) return
+    options.onStatusChange?.(evt.status, evt)
+    if (evt.status === 'connected') {
+      retryAttempt = 0
+    }
+    if (shouldRetryOn(evt.status)) {
+      scheduleRetry()
+    }
+  })
+
+  if (conn.client.isConnected()) {
+    emitSynthetic('connected')
+  }
+
+  void (async () => {
+    try {
+      conn.connectPromise ||= conn.client.connect()
+      await conn.connectPromise
+    } catch {
+      conn.connectPromise = null
+      if (closed) return
+
+      emitSynthetic('disconnected')
+      scheduleRetry()
+    }
+  })()
+
+  return {
+    stop() {
+      closed = true
+      unsubStatus()
+      if (conn.retryTimer) {
+        clearTimeout(conn.retryTimer)
+        conn.retryTimer = null
+      }
+      if (conn.retryOwner === ownerToken) {
+        conn.retryOwner = null
+      }
+    },
+  }
+}

package/src/nats/use-nats-subscription.ts

@@ -0,0 +1,99 @@
+'use client'
+
+import * as React from 'react'
+import type { JsMsg, Msg, NatsSubscribeOptions } from './nats'
+import { useOptionalNats } from './nats-provider'
+
+export interface UseNatsSubscriptionOptions extends NatsSubscribeOptions {
+  enabled?: boolean
+}
+
+export interface UseNatsSubscriptionReturn {
+  isSubscribed: boolean
+  isReady: boolean
+}
+
+/**
+ * Subscribe to a NATS subject using the shared connection from <NatsProvider>.
+ * Automatically (re)subscribes when the connection becomes ready, when the
+ * subject changes, and after reconnections.
+ */
+export function useNatsSubscription(
+  subject: string | null,
+  onMessage: (msg: Msg) => void | Promise<void>,
+  options?: UseNatsSubscriptionOptions,
+): UseNatsSubscriptionReturn {
+  const nats = useOptionalNats()
+  const handlerRef = React.useRef(onMessage)
+  React.useEffect(() => {
+    handlerRef.current = onMessage
+  }, [onMessage])
+
+  const [isSubscribed, setIsSubscribed] = React.useState(false)
+
+  const enabled = options?.enabled !== false
+  const queue = options?.queue
+  const max = options?.max
+  const reconnectionCount = nats?.reconnectionCount ?? 0
+  const isReady = !!nats?.isReady
+  const client = nats?.client ?? null
+
+  React.useEffect(() => {
+    if (!client || !isReady || !subject || !enabled) {
+      setIsSubscribed(false)
+      return
+    }
+
+    const sub = client.subscribeBytes(
+      subject,
+      (msg) => handlerRef.current(msg),
+      { queue, max },
+    )
+    setIsSubscribed(true)
+
+    return () => {
+      setIsSubscribed(false)
+      try {
+        sub.unsubscribe()
+      } catch {
+        // ignore
+      }
+    }
+    // reconnectionCount intentionally in deps: re-subscribe after reconnect
+  }, [client, isReady, subject, enabled, queue, max, reconnectionCount])
+
+  return { isSubscribed, isReady }
+}
+
+export type UseNatsJsonSubscriptionOptions = UseNatsSubscriptionOptions
+
+export function useNatsJsonSubscription<T = unknown>(
+  subject: string | null,
+  onPayload: (payload: T, msg: Msg) => void | Promise<void>,
+  options?: UseNatsJsonSubscriptionOptions,
+): UseNatsSubscriptionReturn {
+  const handlerRef = React.useRef(onPayload)
+  React.useEffect(() => {
+    handlerRef.current = onPayload
+  }, [onPayload])
+
+  const decoderRef = React.useRef<TextDecoder | null>(null)
+  if (!decoderRef.current && typeof TextDecoder !== 'undefined') {
+    decoderRef.current = new TextDecoder()
+  }
+
+  const wrapped = React.useCallback(async (msg: Msg) => {
+    const decoder = decoderRef.current
+    if (!decoder) return
+    try {
+      const parsed = JSON.parse(decoder.decode(msg.data)) as T
+      await handlerRef.current(parsed, msg)
+    } catch {
+      // ignore malformed payloads
+    }
+  }, [])
+
+  return useNatsSubscription(subject, wrapped, options)
+}
+
+export type NatsJsMsg = JsMsg