qdadm 0.29.0 → 0.31.0

package/src/kernel/SSEBridge.js

@@ -0,0 +1,354 @@
+/**
+ * SSEBridge - Server-Sent Events to SignalBus bridge
+ *
+ * Manages a single SSE connection and emits all events to SignalBus.
+ * Components subscribe via signals.on('sse:eventName', handler) instead of
+ * managing their own EventSource connections.
+ *
+ * Benefits:
+ * - Single SSE connection per app (vs. one per component)
+ * - Decoupled event handling via SignalBus
+ * - Automatic reconnection with configurable delay
+ * - Connection status available via signals
+ *
+ * Signal naming:
+ * - `sse:connected` - Emitted when connection established
+ * - `sse:disconnected` - Emitted when connection lost
+ * - `sse:error` - Emitted on connection error
+ * - `sse:{eventName}` - SSE event forwarded (e.g., sse:task:completed)
+ *
+ * Usage in Kernel:
+ * ```js
+ * new Kernel({
+ *   sse: {
+ *     url: '/api/events',
+ *     reconnectDelay: 5000,
+ *     signalPrefix: 'sse',
+ *     autoConnect: true
+ *   }
+ * })
+ * ```
+ *
+ * Usage in components:
+ * ```js
+ * const signals = inject('qdadmSignals')
+ *
+ * // Subscribe to specific SSE events
+ * signals.on('sse:task:completed', ({ data }) => {
+ *   console.log('Task completed:', data)
+ * })
+ *
+ * // Subscribe to all SSE events via wildcard
+ * signals.on('sse:*', ({ event, data }) => {
+ *   console.log(`SSE event ${event}:`, data)
+ * })
+ * ```
+ */
+
+export const SSE_SIGNALS = {
+  CONNECTED: 'sse:connected',
+  DISCONNECTED: 'sse:disconnected',
+  ERROR: 'sse:error',
+  MESSAGE: 'sse:message'
+}
+
+export class SSEBridge {
+  /**
+   * @param {object} options
+   * @param {SignalBus} options.signals - SignalBus instance
+   * @param {string} options.url - SSE endpoint URL
+   * @param {number} options.reconnectDelay - Delay before reconnect (ms), 0 to disable
+   * @param {string} options.signalPrefix - Prefix for emitted signals (default: 'sse')
+   * @param {boolean} options.autoConnect - Connect immediately (default: false, waits for auth:login)
+   * @param {boolean} options.withCredentials - Include credentials in request
+   * @param {string} options.tokenParam - Query param name for auth token
+   * @param {function} options.getToken - Function to get auth token
+   * @param {boolean} options.debug - Enable debug logging
+   */
+  constructor(options) {
+    const {
+      signals,
+      url,
+      reconnectDelay = 5000,
+      signalPrefix = 'sse',
+      autoConnect = false,
+      withCredentials = false,
+      tokenParam = 'token',
+      getToken = null,
+      debug = false
+    } = options
+
+    if (!signals) {
+      throw new Error('[SSEBridge] signals (SignalBus) is required')
+    }
+    if (!url) {
+      throw new Error('[SSEBridge] url is required')
+    }
+
+    this._signals = signals
+    this._url = url
+    this._reconnectDelay = reconnectDelay
+    this._signalPrefix = signalPrefix
+    this._withCredentials = withCredentials
+    this._tokenParam = tokenParam
+    this._getToken = getToken
+    this._debug = debug
+
+    this._eventSource = null
+    this._reconnectTimer = null
+    this._connected = false
+    this._reconnecting = false
+
+    // Auto-connect or wait for auth:login
+    if (autoConnect) {
+      this.connect()
+    } else {
+      // Wait for auth:login signal to connect
+      this._signals.once('auth:login').then(() => {
+        this._log('Received auth:login, connecting SSE')
+        this.connect()
+      })
+    }
+
+    // Disconnect on auth:logout
+    this._signals.on('auth:logout', () => {
+      this._log('Received auth:logout, disconnecting SSE')
+      this.disconnect()
+    })
+  }
+
+  /**
+   * Build signal name with prefix
+   * @param {string} eventName - Event name
+   * @returns {string} Full signal name
+   */
+  _buildSignal(eventName) {
+    return `${this._signalPrefix}:${eventName}`
+  }
+
+  /**
+   * Debug logging
+   */
+  _log(...args) {
+    if (this._debug) {
+      console.debug('[SSEBridge]', ...args)
+    }
+  }
+
+  /**
+   * Build SSE URL with auth token
+   * @returns {string}
+   */
+  _buildUrl() {
+    const token = this._getToken?.()
+    const sseUrl = new URL(this._url, window.location.origin)
+
+    if (token && this._tokenParam) {
+      sseUrl.searchParams.set(this._tokenParam, token)
+    }
+
+    return sseUrl.toString()
+  }
+
+  /**
+   * Connect to SSE endpoint
+   */
+  connect() {
+    // Clean up existing
+    if (this._eventSource) {
+      this._eventSource.close()
+      this._eventSource = null
+    }
+
+    // Clear pending reconnect
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer)
+      this._reconnectTimer = null
+    }
+
+    try {
+      const url = this._buildUrl()
+      this._log('Connecting to', url)
+
+      this._eventSource = new EventSource(url, {
+        withCredentials: this._withCredentials
+      })
+
+      this._eventSource.onopen = () => {
+        this._connected = true
+        this._reconnecting = false
+        this._log('Connected')
+
+        this._signals.emit(SSE_SIGNALS.CONNECTED, {
+          url: this._url,
+          timestamp: new Date()
+        })
+      }
+
+      this._eventSource.onerror = (err) => {
+        this._connected = false
+        this._log('Connection error')
+
+        this._signals.emit(SSE_SIGNALS.ERROR, {
+          error: 'Connection error',
+          timestamp: new Date()
+        })
+
+        // Close broken connection
+        if (this._eventSource) {
+          this._eventSource.close()
+          this._eventSource = null
+        }
+
+        this._signals.emit(SSE_SIGNALS.DISCONNECTED, {
+          timestamp: new Date()
+        })
+
+        // Schedule reconnect
+        this._scheduleReconnect()
+      }
+
+      // Handle generic message events (event: message)
+      this._eventSource.onmessage = (event) => {
+        this._handleEvent('message', event)
+      }
+
+      // For named events, we need to add listeners dynamically
+      // Since EventSource doesn't expose event names, we use a wrapper approach:
+      // The server should send events with `event:` field, we handle them generically
+
+      // Note: Named events require explicit addEventListener.
+      // To support arbitrary event names, the app should either:
+      // 1. Use `message` event type and include event name in data
+      // 2. Pre-register known event names via registerEvents()
+
+    } catch (err) {
+      this._log('Connect error:', err.message)
+      this._signals.emit(SSE_SIGNALS.ERROR, {
+        error: err.message,
+        timestamp: new Date()
+      })
+      this._scheduleReconnect()
+    }
+  }
+
+  /**
+   * Register listeners for specific SSE event types
+   * Required because EventSource requires explicit addEventListener for named events.
+   *
+   * @param {string[]} eventNames - Event names to listen for
+   */
+  registerEvents(eventNames) {
+    if (!this._eventSource) {
+      this._log('Cannot register events: not connected')
+      return
+    }
+
+    for (const eventName of eventNames) {
+      this._eventSource.addEventListener(eventName, (event) => {
+        this._handleEvent(eventName, event)
+      })
+      this._log('Registered event:', eventName)
+    }
+  }
+
+  /**
+   * Handle incoming SSE event
+   * @param {string} eventName - Event name
+   * @param {MessageEvent} event - SSE event
+   */
+  _handleEvent(eventName, event) {
+    let data
+    try {
+      data = JSON.parse(event.data)
+    } catch {
+      data = event.data
+    }
+
+    const signal = this._buildSignal(eventName)
+    this._log(`Emitting ${signal}:`, data)
+
+    this._signals.emit(signal, {
+      event: eventName,
+      data,
+      timestamp: new Date(),
+      lastEventId: event.lastEventId
+    })
+  }
+
+  /**
+   * Schedule reconnection
+   */
+  _scheduleReconnect() {
+    if (this._reconnectDelay <= 0) return
+    if (this._reconnectTimer) return
+
+    this._reconnecting = true
+    this._log(`Reconnecting in ${this._reconnectDelay}ms`)
+
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null
+      if (!this._connected) {
+        this.connect()
+      }
+    }, this._reconnectDelay)
+  }
+
+  /**
+   * Disconnect from SSE endpoint
+   */
+  disconnect() {
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer)
+      this._reconnectTimer = null
+    }
+
+    if (this._eventSource) {
+      this._eventSource.close()
+      this._eventSource = null
+    }
+
+    if (this._connected) {
+      this._connected = false
+      this._signals.emit(SSE_SIGNALS.DISCONNECTED, {
+        timestamp: new Date()
+      })
+    }
+
+    this._reconnecting = false
+    this._log('Disconnected')
+  }
+
+  /**
+   * Reconnect (disconnect + connect)
+   */
+  reconnect() {
+    this.disconnect()
+    this.connect()
+  }
+
+  /**
+   * Check if connected
+   * @returns {boolean}
+   */
+  isConnected() {
+    return this._connected
+  }
+
+  /**
+   * Check if reconnecting
+   * @returns {boolean}
+   */
+  isReconnecting() {
+    return this._reconnecting
+  }
+}
+
+/**
+ * Factory function to create SSEBridge
+ * @param {object} options - SSEBridge options
+ * @returns {SSEBridge}
+ */
+export function createSSEBridge(options) {
+  return new SSEBridge(options)
+}

package/src/kernel/SignalBus.js

@@ -25,6 +25,14 @@ export const SIGNALS = {
   ENTITY_UPDATED: 'entity:updated',
   ENTITY_DELETED: 'entity:deleted',
 
+  // Auth lifecycle signals
+  AUTH_LOGIN: 'auth:login',
+  AUTH_LOGOUT: 'auth:logout',
+  AUTH_EXPIRED: 'auth:expired',  // Emitted on 401/403 API responses
+
+  // API error signals
+  API_ERROR: 'api:error',  // Emitted on any API error { status, message, url }
+
   // Pattern for entity-specific signals
   // Use buildSignal(entityName, action) for these
 }
@@ -118,13 +126,8 @@ export class SignalBus {
    * @returns {Promise<void>}
    */
   async emitEntity(entityName, action, data) {
-    const specificSignal = buildSignal(entityName, action)
-    const genericSignal = buildSignal('entity', action)
-
-    // Emit both specific and generic signals
-    // Specific first, then generic
-    await this.emit(specificSignal, { entity: entityName, data })
-    await this.emit(genericSignal, { entity: entityName, data })
+    const signal = buildSignal('entity', action)
+    await this.emit(signal, { entity: entityName, data })
   }
 
   /**

package/src/kernel/index.js

@@ -16,3 +16,22 @@ export {
   EventRouter,
   createEventRouter,
 } from './EventRouter.js'
+export {
+  SSEBridge,
+  createSSEBridge,
+  SSE_SIGNALS,
+} from './SSEBridge.js'
+export {
+  Module,
+} from './Module.js'
+export {
+  KernelContext,
+  createKernelContext,
+} from './KernelContext.js'
+export {
+  ModuleLoader,
+  createModuleLoader,
+  ModuleNotFoundError,
+  CircularDependencyError,
+  ModuleLoadError,
+} from './ModuleLoader.js'

package/src/toast/ToastBridgeModule.js

@@ -0,0 +1,70 @@
+/**
+ * ToastBridgeModule - Bridges signal bus to PrimeVue Toast
+ *
+ * This module integrates toast functionality via the signal bus:
+ * - Registers ToastListener component to handle toast:* signals
+ * - Provides useSignalToast() composable for emitting toasts
+ *
+ * Usage in modules:
+ *   import { useSignalToast } from 'qdadm'
+ *   const toast = useSignalToast()
+ *   toast.success('Saved!', 'Your changes have been saved')
+ *   toast.error('Error', 'Something went wrong')
+ *
+ * @example
+ * import { createKernel, ToastBridgeModule } from 'qdadm'
+ *
+ * const kernel = createKernel()
+ * kernel.use(new ToastBridgeModule())
+ * await kernel.boot()
+ */
+
+import { Module } from '../kernel/Module.js'
+import ToastListener from './ToastListener.vue'
+
+/**
+ * Zone name for toast listener component
+ * Prefixed with _ to hide from ZonesCollector (internal zone)
+ */
+export const TOAST_ZONE = '_app:toasts'
+
+/**
+ * ToastBridgeModule - Handles toast notifications via signals
+ */
+export class ToastBridgeModule extends Module {
+  /**
+   * Module identifier
+   * @type {string}
+   */
+  static name = 'toast-bridge'
+
+  /**
+   * No dependencies
+   * @type {string[]}
+   */
+  static requires = []
+
+  /**
+   * High priority - should load early
+   * @type {number}
+   */
+  static priority = 10
+
+  /**
+   * Connect module to kernel
+   * @param {import('../kernel/KernelContext.js').KernelContext} ctx
+   */
+  async connect(ctx) {
+    // Define the toast zone
+    ctx.zone(TOAST_ZONE)
+
+    // Register ToastListener component in the zone
+    ctx.block(TOAST_ZONE, {
+      id: 'toast-listener',
+      component: ToastListener,
+      weight: 0
+    })
+  }
+}
+
+export default ToastBridgeModule

package/src/toast/ToastListener.vue

@@ -0,0 +1,47 @@
+<script setup>
+/**
+ * ToastListener - Bridges signal bus to PrimeVue Toast
+ *
+ * Invisible component that listens to toast:* signals and displays
+ * them using PrimeVue's Toast component.
+ *
+ * This component should be registered in a zone via ToastBridgeModule.
+ */
+import { onMounted, onUnmounted, inject } from 'vue'
+import { useToast } from 'primevue/usetoast'
+
+const toast = useToast()
+const signals = inject('qdadmSignals')
+
+let unsubscribe = null
+
+onMounted(() => {
+  if (!signals) {
+    console.warn('[ToastListener] No signals bus injected')
+    return
+  }
+
+  // Listen to all toast signals
+  unsubscribe = signals.on('toast:*', (event) => {
+    const severity = event.name.split(':')[1] // toast:success -> success
+    toast.add({
+      severity,
+      summary: event.data?.summary,
+      detail: event.data?.detail,
+      life: event.data?.life ?? 3000
+    })
+  })
+})
+
+onUnmounted(() => {
+  if (unsubscribe) {
+    unsubscribe()
+    unsubscribe = null
+  }
+})
+</script>
+
+<template>
+  <!-- Invisible listener component -->
+  <span style="display: none" />
+</template>

package/src/toast/index.js

@@ -0,0 +1,15 @@
+/**
+ * Toast Module - Signal-based toast notifications
+ *
+ * Provides toast notifications that go through the signal bus,
+ * allowing for proper debugging and interception.
+ *
+ * Components:
+ * - ToastBridgeModule: Registers ToastListener for handling signals
+ * - ToastListener: Vue component that displays toasts via PrimeVue
+ * - useSignalToast: Composable for emitting toast signals
+ */
+
+export { ToastBridgeModule, TOAST_ZONE } from './ToastBridgeModule.js'
+export { useSignalToast } from './useSignalToast.js'
+export { default as ToastListener } from './ToastListener.vue'

package/src/toast/useSignalToast.js

@@ -0,0 +1,113 @@
+/**
+ * useSignalToast - Composable for emitting toast notifications via signals
+ *
+ * This composable provides a simple API for showing toasts that go through
+ * the signal bus. Works with ToastBridgeModule which handles displaying
+ * the toasts via PrimeVue.
+ *
+ * @example
+ * import { useSignalToast } from 'qdadm'
+ *
+ * // With explicit emitter name
+ * const toast = useSignalToast('MyComponent')
+ * toast.success('Saved!', 'Your changes have been saved')
+ *
+ * // Without emitter (defaults to 'unknown')
+ * const toast = useSignalToast()
+ * toast.error('Error', 'Something went wrong')
+ */
+
+import { inject, getCurrentInstance } from 'vue'
+
+/**
+ * Composable for emitting toast notifications via signal bus
+ * @param {string} [emitter] - Identifier for the toast source (component/module name)
+ * @returns {object} Toast API
+ */
+export function useSignalToast(emitter) {
+  const signals = inject('qdadmSignals')
+
+  // Try to auto-detect emitter from current component if not provided
+  const instance = getCurrentInstance()
+  const resolvedEmitter =
+    emitter || instance?.type?.name || instance?.type?.__name || 'unknown'
+
+  if (!signals) {
+    console.warn('[useSignalToast] No signals bus injected - toasts will not work')
+    // Return no-op functions
+    return {
+      success: () => {},
+      error: () => {},
+      info: () => {},
+      warn: () => {},
+      add: () => {}
+    }
+  }
+
+  /**
+   * Show a toast notification
+   * @param {string} severity - Toast severity (success, info, warn, error)
+   * @param {string} summary - Toast title
+   * @param {string} [detail] - Toast detail message
+   * @param {number} [life=3000] - Duration in ms (0 for sticky)
+   */
+  function add(severity, summary, detail, life = 3000) {
+    signals.emit(`toast:${severity}`, { summary, detail, life, emitter: resolvedEmitter })
+  }
+
+  return {
+    /**
+     * Show success toast
+     * @param {string} summary - Toast title
+     * @param {string} [detail] - Toast detail message
+     * @param {number} [life=3000] - Duration in ms
+     */
+    success(summary, detail, life = 3000) {
+      add('success', summary, detail, life)
+    },
+
+    /**
+     * Show error toast
+     * @param {string} summary - Toast title
+     * @param {string} [detail] - Toast detail message
+     * @param {number} [life=5000] - Duration in ms (longer for errors)
+     */
+    error(summary, detail, life = 5000) {
+      add('error', summary, detail, life)
+    },
+
+    /**
+     * Show info toast
+     * @param {string} summary - Toast title
+     * @param {string} [detail] - Toast detail message
+     * @param {number} [life=3000] - Duration in ms
+     */
+    info(summary, detail, life = 3000) {
+      add('info', summary, detail, life)
+    },
+
+    /**
+     * Show warning toast
+     * @param {string} summary - Toast title
+     * @param {string} [detail] - Toast detail message
+     * @param {number} [life=4000] - Duration in ms
+     */
+    warn(summary, detail, life = 4000) {
+      add('warn', summary, detail, life)
+    },
+
+    /**
+     * Generic add method (compatible with PrimeVue toast.add)
+     * @param {object} options - Toast options
+     * @param {string} options.severity - Toast severity
+     * @param {string} options.summary - Toast title
+     * @param {string} [options.detail] - Toast detail
+     * @param {number} [options.life] - Duration in ms
+     */
+    add(options) {
+      add(options.severity || 'info', options.summary, options.detail, options.life)
+    }
+  }
+}
+
+export default useSignalToast