@quazardous/qdadm 2.13.0 → 2.15.0

package/src/kernel/LiveEntityRouter.ts

@@ -0,0 +1,189 @@
+/**
+ * LiveEntityRouter — turns "something changed elsewhere" into cache
+ * invalidation for the right EntityManager (#1888 lot C, reported in #1887).
+ *
+ * The transport is deliberately not part of this class. Its entry point is
+ * `notify()`, a plain fact: *this entity changed, possibly this record*. SSE is
+ * wired on top by `attachSignalTransport()`, and a WebSocket or a
+ * `BroadcastChannel` between two tabs of the same admin would attach the same
+ * way — see docs/adr/0009-live-entities.md.
+ *
+ * Two boundaries the ADR fixes and this class enforces:
+ *
+ * - **The event carries a fact, never an instruction.** Nothing in the payload
+ *   may tell the front what to do; the payload says what changed and the front
+ *   decides what that implies.
+ * - **The security scope is the front's.** An event never causes a request the
+ *   current user could not have issued: an entity they cannot read is dropped
+ *   rather than refetched, otherwise every pushed event sprays 401/403.
+ *
+ * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
+ */
+
+import type { SignalBus } from './SignalBus'
+
+/** The actions a live event can report. */
+export type LiveEntityAction = 'created' | 'updated' | 'deleted'
+
+/**
+ * Which entities the app declares as having an external writer.
+ * `true` / `'*'` accepts every registered entity.
+ */
+export type LiveEntitiesDeclaration = string[] | true | '*'
+
+/** Minimal orchestrator surface this router needs. */
+export interface LiveOrchestratorLike {
+  has(name: string): boolean
+  get(name: string): { canRead?: () => boolean } | undefined
+}
+
+export interface LiveEntityRouterOptions {
+  signals: SignalBus
+  /** Entities declared as externally written. */
+  entities: LiveEntitiesDeclaration
+  /** Used to resolve the manager for the permission check. */
+  orchestrator?: LiveOrchestratorLike | null
+  /** Signal prefix the transport publishes under (default: 'sse'). */
+  signalPrefix?: string
+  debug?: boolean
+}
+
+/** Payload shape a transport frame is expected to carry. */
+interface LiveFramePayload {
+  entity?: string
+  id?: string | number
+  action?: LiveEntityAction
+}
+
+const ACTION_BY_EVENT: Record<string, LiveEntityAction> = {
+  'entity:created': 'created',
+  'entity:updated': 'updated',
+  'entity:deleted': 'deleted',
+}
+
+export class LiveEntityRouter {
+  private _signals: SignalBus
+  private _entities: LiveEntitiesDeclaration
+  private _orchestrator: LiveOrchestratorLike | null
+  private _signalPrefix: string
+  private _debug: boolean
+  private _cleanups: Array<() => void> = []
+  /** Entities seen on the wire but never declared — warned about once each. */
+  private _warned = new Set<string>()
+
+  constructor(options: LiveEntityRouterOptions) {
+    const {
+      signals,
+      entities,
+      orchestrator = null,
+      signalPrefix = 'sse',
+      debug = false,
+    } = options
+
+    if (!signals) throw new Error('[LiveEntityRouter] signals (SignalBus) is required')
+
+    this._signals = signals
+    this._entities = entities
+    this._orchestrator = orchestrator
+    this._signalPrefix = signalPrefix
+    this._debug = debug
+  }
+
+  /** Is this entity declared as externally written? */
+  isDeclared(entity: string): boolean {
+    if (this._entities === true || this._entities === '*') return true
+    return Array.isArray(this._entities) && this._entities.includes(entity)
+  }
+
+  /**
+   * Report an external change. Transport-agnostic entry point.
+   *
+   * @returns true when the change was routed, false when it was dropped
+   *   (undeclared entity, unknown manager, or one the user cannot read).
+   */
+  notify(entity: string, action: LiveEntityAction = 'updated', id?: string | number): boolean {
+    if (!entity) return false
+
+    if (!this.isDeclared(entity)) {
+      // Not an error: a stream carries more than entity mutations. But a
+      // silently dropped frame is the hardest kind of bug to find, so say it
+      // once per entity in dev.
+      if (!this._warned.has(entity)) {
+        this._warned.add(entity)
+        this._log(
+          `Ignoring a live event for "${entity}": not declared in sse.entities. ` +
+            `Add it there if this backend writes to it out of session.`
+        )
+      }
+      return false
+    }
+
+    // has() first: Orchestrator.get() THROWS for an unknown name (it is built
+    // to catch developer typos loudly). Letting that escape would blow up
+    // inside the signal bus on every incoming frame — a declared entity whose
+    // module is lazily loaded, or a typo in sse.entities, must degrade to a
+    // dropped event, not to an exception storm.
+    let manager: { canRead?: () => boolean } | undefined
+    if (this._orchestrator) {
+      if (!this._orchestrator.has(entity)) {
+        this._log(`Ignoring a live event for "${entity}": no manager registered under that name.`)
+        return false
+      }
+      manager = this._orchestrator.get(entity)
+    }
+
+    // The security scope is the front's: never refetch what this user could not
+    // have asked for in the first place.
+    if (manager?.canRead && !manager.canRead()) {
+      this._log(`Ignoring a live event for "${entity}": current user cannot read it.`)
+      return false
+    }
+
+    this._signals.emit('entity:data-invalidate', {
+      entity,
+      action,
+      id,
+      source: 'remote',
+    })
+    this._signals.emitEntity?.(entity, action, { id, source: 'remote' })
+
+    this._log(`Routed ${action} on "${entity}"${id !== undefined ? ` (id ${id})` : ''}`)
+    return true
+  }
+
+  /**
+   * Subscribe to the transport's frames on the signal bus.
+   *
+   * Recognises `{prefix}:entity:{created,updated,deleted}` carrying
+   * `{ entity, id? }` — the contract validated downstream in #1887.
+   */
+  attachSignalTransport(): void {
+    for (const [event, action] of Object.entries(ACTION_BY_EVENT)) {
+      const signal = `${this._signalPrefix}:${event}`
+      this._cleanups.push(
+        this._signals.on(signal, (received: { name: string; data: unknown }) => {
+          const frame = (received?.data ?? {}) as { data?: LiveFramePayload }
+          // Transports wrap the decoded body in `data` (see SSEBridge); accept
+          // a bare payload too so a non-SSE caller isn't forced to fake it.
+          const payload = (frame.data ?? frame) as LiveFramePayload
+          if (!payload?.entity) return
+          this.notify(payload.entity, payload.action ?? action, payload.id)
+        })
+      )
+    }
+  }
+
+  /** Drop every subscription. */
+  destroy(): void {
+    this._cleanups.forEach((off) => off())
+    this._cleanups = []
+  }
+
+  private _log(...args: unknown[]): void {
+    if (this._debug) console.debug('[LiveEntityRouter]', ...args)
+  }
+}
+
+export function createLiveEntityRouter(options: LiveEntityRouterOptions): LiveEntityRouter {
+  return new LiveEntityRouter(options)
+}

package/src/kernel/SSEBridge.ts

@@ -5,6 +5,9 @@
  * shared with qdcms. The auth-aware connect/disconnect behaviour is now
  * configurable via `connectOnSignal` / `disconnectOnSignal` options; defaults
  * remain `'auth:login'` / `'auth:logout'` for backwards compatibility.
+ *
+ * @experimental Signal mapping and reconnection options may change in a minor
+ * release — see docs/API_STABILITY.md.
  */
 
 export { SSEBridge, createSSEBridge, SSE_SIGNALS } from '@quazardous/qdcore'

package/src/query/index.ts

@@ -2,6 +2,13 @@
  * Query Module - MongoDB-like filtering for arrays
  *
  * Provides client-side filtering with the same query syntax used for API calls.
+ *
+ * @experimental Applies to the EXECUTOR CLASSES below, used directly. The query
+ * object syntax they interpret (`{ field: { $in: [...] } }`) is stable — it is
+ * what list filters and EntityManager.query() speak. See
+ * docs/API_STABILITY.md.
+ *
+ * @module query
  */
 
 export { QueryExecutor, getNestedValue } from './QueryExecutor'

package/src/security/pages/RoleList.vue

@@ -5,7 +5,7 @@
 
 import { useListPage, ListPage, useOrchestrator } from '../../index.js'
 import Column from 'primevue/column'
-import Message from 'primevue/message'
+import QdMessage from '../../components/base/QdMessage.vue'
 import Chip from 'primevue/chip'
 
 /**
@@ -49,7 +49,7 @@ const storageCanPersist: boolean = manager?.rolesProvider?.canPersist ?? false
   <ListPage v-bind="list.props.value" v-on="list.events">
     <!-- Read-only Warning -->
     <template #before-table>
-      <Message v-if="!storageCanPersist" severity="info" :closable="false" class="mb-4">
+      <QdMessage v-if="!storageCanPersist" severity="info" :closable="false" class="mb-4">
         <div class="flex align-items-center gap-2">
           <i class="pi pi-info-circle text-xl"></i>
           <span>
@@ -57,7 +57,7 @@ const storageCanPersist: boolean = manager?.rolesProvider?.canPersist ?? false
             Use a PersistableRoleProvider for editing.
           </span>
         </div>
-      </Message>
+      </QdMessage>
     </template>
 
     <template #columns>

package/src/types/index.ts

@@ -164,6 +164,8 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   readOnly?: boolean
   warmup?: boolean
   authSensitive?: boolean
+  /** What this entity does when it changed elsewhere (#1888). */
+  live?: { refresh?: 'mounted' | false; coalesceMs?: number }
   system?: boolean
   scopeWhitelist?: string[] | null
   isOwn?: ((record: T, user: unknown) => boolean) | null