@quazardous/qdadm 2.26.1 → 2.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.26.1",
+  "version": "2.27.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/composables/useEntityItemFormPage.ts

@@ -273,7 +273,14 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
     }
   }
 
+  // Only the latest load may write (#2666): moving quickly between records, a
+  // slow answer for the previous one would otherwise land in this record's form.
+  let loadSeq = 0
+
   async function load(): Promise<void> {
+    const seq = ++loadSeq
+    const isLatest = (): boolean => seq === loadSeq
+
     if (!isEdit.value) {
       data.value = deepClone(initialData) as T
       takeSnapshot()
@@ -285,6 +292,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
       // The item itself, never a cached list row: a list row may be a summary,
       // and whatever this form shows empty it saves back empty (#2484).
       const responseData = await manager.get(entityId.value!, undefined, { listCache: false })
+      if (!isLatest()) return
       const transformed = transformLoad(responseData)
       if (debug) reportMissingFields(transformed as Record<string, unknown>)
       data.value = transformed as T
@@ -298,6 +306,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
         await onLoadSuccess(transformed as T)
       }
     } catch (error) {
+      if (!isLatest()) return
       const axiosError = error as AxiosError
       toast.add({
         severity: 'error',
@@ -306,7 +315,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
         life: 5000,
       })
     } finally {
-      loading.value = false
+      if (isLatest()) loading.value = false
     }
   }
 

package/src/composables/useEntityItemPage.ts

@@ -315,7 +315,15 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
    * @param id - Optional ID override (defaults to route param)
    * @returns Loaded entity data or null on error
    */
+  let loadSeq = 0
+
   async function load(id: string | number | null = entityId.value): Promise<T | null> {
+    // Only the latest call may write (#2666). Live reloads and id changes can
+    // overlap; an older answer landing last would put a past state on screen.
+    // A superseded call resolves to null and touches nothing.
+    const seq = ++loadSeq
+    const isLatest = (): boolean => seq === loadSeq
+
     if (!id) {
       error.value = 'No entity ID provided'
       return null
@@ -326,6 +334,7 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
 
     try {
       const responseData = await manager.get(id)
+      if (!isLatest()) return null
 
       if (!responseData) {
         error.value = `${manager.label || entity} not found`
@@ -344,6 +353,7 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
 
       return transformed
     } catch (err) {
+      if (!isLatest()) return null
       console.error(`[useEntityItemPage] Failed to load ${entity}:`, err)
       const axiosError = err as { response?: { data?: { detail?: string } }; message?: string }
       error.value =
@@ -357,7 +367,7 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
 
       return null
     } finally {
-      loading.value = false
+      if (isLatest()) loading.value = false
     }
   }
 

package/src/composables/useLiveEntity.ts

@@ -15,8 +15,11 @@
  * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
  */
 
-import { inject, onUnmounted } from 'vue'
+import { inject, onUnmounted, watch } from 'vue'
 import type { SignalBus } from '../kernel/SignalBus'
+import { useApiClient } from '../api/apiClient'
+import type { HttpClient } from '../entity/storage/ApiStorage'
+import { SSE_SUBSCRIPTIONS_KEY, type SseSubscriptions } from '../kernel/sseSubscriptions'
 
 export interface UseLiveEntityOptions {
   /**
@@ -37,7 +40,8 @@ interface LivePolicy {
  *
  * @param entityName - entity to watch
  * @param manager - its manager, read for the `live` policy (may be null)
- * @param reload - what to run; coalesced, never called concurrently by us
+ * @param reload - what to run; coalesced, and never called while a previous
+ *   call's promise is still pending — changes arriving meanwhile cause one more call
  * @returns unsubscribe function (also called automatically on unmount)
  */
 export function useLiveEntity(
@@ -60,10 +64,44 @@ export function useLiveEntity(
   let timer: ReturnType<typeof setTimeout> | null = null
   let disposed = false
 
+  // Never two reloads at once (#2666), as this composable promises: an event
+  // arriving while one is in flight marks it dirty, and exactly one more runs
+  // when it settles — no overlapping requests, and the last state lands.
+  let inFlight = false
+  let dirty = false
+
+  const settle = (): void => {
+    inFlight = false
+    if (dirty && !disposed) {
+      dirty = false
+      run()
+    }
+  }
+
+  // Only a reload that returns a promise is in flight: a synchronous one is done
+  // when it returns. A failure — thrown or rejected — must not stop the next one;
+  // the page reports its own load errors.
+  const run = (): void => {
+    let result: void | Promise<void>
+    try {
+      result = reload()
+    } catch {
+      return
+    }
+    if (result && typeof (result as Promise<void>).then === 'function') {
+      inFlight = true
+      ;(result as Promise<void>).then(settle, settle)
+    }
+  }
+
   const fire = (): void => {
     timer = null
     if (disposed) return
-    void reload()
+    if (inFlight) {
+      dirty = true
+      return
+    }
+    run()
   }
 
   const off = signals.on('entity:data-invalidate', (event: { name: string; data: unknown }) => {
@@ -100,6 +138,15 @@ export function useLiveEntity(
     timer = setTimeout(fire, coalesceMs)
   })
 
+  // Per-record subscription (#2664): a detail page asks the backend to send
+  // this record's changes to this tab, for as long as it shows the record.
+  const subscriptions = inject<SseSubscriptions | null>(SSE_SUBSCRIPTIONS_KEY, null)
+  const apiClient = subscriptions && options.id ? useApiClient() : null
+  const stopSubscription =
+    subscriptions && apiClient && options.id
+      ? followRecord(subscriptions, apiClient, entityName, options.id, inject<boolean>('qdadmDebug', false))
+      : () => {}
+
   const stop = (): void => {
     disposed = true
     if (timer) {
@@ -107,9 +154,84 @@ export function useLiveEntity(
       timer = null
     }
     off()
+    stopSubscription()
   }
 
   onUnmounted(stop)
 
   return stop
 }
+
+/**
+ * Keep a subscription to the record `id()` points at: POST when it is shown,
+ * renew at half of `expires_in`, DELETE when it changes or the page leaves.
+ *
+ * Never throws into the page — without a subscription the page still works, it
+ * just does not hear about changes. Failures are said in debug mode only.
+ */
+function followRecord(
+  subscriptions: SseSubscriptions,
+  api: HttpClient,
+  entity: string,
+  id: () => string | number | null | undefined,
+  debug: boolean
+): () => void {
+  let current: string | null = null
+  let renewTimer: ReturnType<typeof setTimeout> | null = null
+  let stopped = false
+
+  const body = (recordId: string) => ({ session: subscriptions.session, entity, id: recordId })
+
+  const report = (what: string, recordId: string, error: unknown): void => {
+    if (!debug) return
+    const status = (error as { response?: { status?: number } })?.response?.status
+    const reason = status ?? (error as { message?: string })?.message ?? String(error)
+    console.warn(`[qdadm] live subscription ${what} failed for ${entity} #${recordId} (${reason}) — the page will not update on its own`)
+  }
+
+  const clearRenewal = (): void => {
+    if (renewTimer) clearTimeout(renewTimer)
+    renewTimer = null
+  }
+
+  const subscribe = async (recordId: string, retryAfterMs: number | null = null): Promise<void> => {
+    try {
+      const { data } = await api.post<{ expires_in?: number }>(subscriptions.url, body(recordId))
+      if (stopped || current !== recordId) return
+      const seconds = Number(data?.expires_in)
+      if (seconds > 0) renewTimer = setTimeout(() => void subscribe(recordId, (seconds * 1000) / 2), (seconds * 1000) / 2)
+    } catch (error) {
+      report('subscribe', recordId, error)
+      // A renewal that fails is tried again at the same pace: the subscription is about to lapse.
+      if (!stopped && current === recordId && retryAfterMs) {
+        renewTimer = setTimeout(() => void subscribe(recordId, retryAfterMs), retryAfterMs)
+      }
+    }
+  }
+
+  const unsubscribe = (recordId: string): void => {
+    api
+      .request({ method: 'DELETE', url: subscriptions.url, data: body(recordId) })
+      .catch((error: unknown) => report('unsubscribe', recordId, error))
+  }
+
+  const follow = (raw: string | number | null | undefined): void => {
+    const next = raw == null || raw === '' ? null : String(raw)
+    if (next === current) return
+    clearRenewal()
+    if (current) unsubscribe(current)
+    current = next
+    if (next) void subscribe(next)
+  }
+
+  const stopWatch = watch(id, follow, { immediate: true })
+
+  return () => {
+    if (stopped) return
+    stopped = true
+    stopWatch()
+    clearRenewal()
+    if (current) unsubscribe(current)
+    current = null
+  }
+}

package/src/kernel/Kernel.registries.ts

@@ -16,6 +16,7 @@ import { Orchestrator } from '../orchestrator/Orchestrator'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { Kernel } from './Kernel'
 import type { SSEConfig } from './Kernel.types'
+import { sseTabSession, withQueryParam } from './sseSubscriptions'
 // #1196 Phase B — this-typing against the real Kernel shape (was Self = any)
 type Self = Kernel
 
@@ -447,6 +448,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
         'getToken',
         'connectOnSignal',
         'disconnectOnSignal',
+        'subscriptions',
       ]),
       {
         getToken:
@@ -454,6 +456,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
           'and query strings reach access logs',
         entities: 'no entity cache will be invalidated from the stream',
         tokenParam: 'the token will be sent under the default name "token"',
+        subscriptions: 'detail pages will not subscribe to their record, and the stream carries no tab session',
       }
     )
   }
@@ -466,6 +469,16 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     this._validateSseConfig(sse)
 
+    // Per-record subscriptions (#2664): the tab id is minted here and put in
+    // the stream URL, so the one the pages subscribe with is the same.
+    let url = sse.url
+    this.sseSubscriptions = null
+    if (sse.subscriptions?.url) {
+      const session = sseTabSession()
+      this.sseSubscriptions = { url: sse.subscriptions.url, session }
+      url = withQueryParam(url, sse.subscriptions.sessionParam ?? 'session', session)
+    }
+
     // An explicit sse.getToken wins — including an explicit null, which means
     // "send no token" and must not fall back to the auth adapter.
     const getToken =
@@ -477,7 +490,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     this.sseBridge = createSSEBridge({
       signals: this.signals!,
-      url: sse.url,
+      url,
       reconnectDelay: sse.reconnectDelay ?? 5000,
       signalPrefix: sse.signalPrefix ?? 'sse',
       autoConnect: sse.autoConnect ?? false,

package/src/kernel/Kernel.ts

@@ -80,6 +80,7 @@ import { isDebugBarKilled } from './debugBarKillSwitch'
 import { applyApiMethods } from './Kernel.api'
 import { applyI18nMethods } from './Kernel.i18n'
 import type { I18n } from '../i18n/I18n'
+import type { SseSubscriptions } from './sseSubscriptions'
 
 export class Kernel {
   options: KernelOptions
@@ -101,6 +102,8 @@ export class Kernel {
   deferred!: DeferredRegistry
   eventRouter: EventRouter | null = null
   sseBridge: SSEBridge | null = null
+  /** Where detail pages subscribe to their record, and as which tab (#2664). Null without `sse.subscriptions`. */
+  sseSubscriptions: SseSubscriptions | null = null
   /** Routes external entity changes to cache invalidation (#1888). */
   liveEntityRouter: LiveEntityRouter | null = null
   layoutComponents: InternalLayoutComponents | null = null

package/src/kernel/Kernel.types.ts

@@ -135,6 +135,23 @@ export interface SSEConfig {
    * See docs/adr/0009-live-entities.md.
    */
   entities?: string[] | true | '*'
+  /**
+   * Per-record subscriptions (#2664): a detail page tells the backend which
+   * record it shows, so the stream carries that record's changes to this tab.
+   *
+   * `url` receives `POST {session, entity, id}` when a detail page shows a
+   * record, answering `{expires_in}` (seconds); qdadm renews at half of it, and
+   * sends `DELETE` with the same body when the page leaves the record. Calls go
+   * through the kernel's `apiClient`, with the app's own auth.
+   *
+   * `session` is a per-tab id qdadm mints and also appends to the stream URL as
+   * `sessionParam` (default `'session'`): the stream and the subscriptions name
+   * the same tab. Do not put your own session parameter in `url`.
+   *
+   * The entity must be declared in `entities`, or its frames are dropped before
+   * any page sees them. Absent: no subscription, no session parameter.
+   */
+  subscriptions?: { url: string; sessionParam?: string }
   /**
    * Token appended to the SSE URL as a query parameter.
    *

package/src/kernel/Kernel.vue.ts

@@ -334,6 +334,8 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
 
     if (this.sseBridge) {
       app.provide('qdadmSSEBridge', this.sseBridge)
+      // Detail pages subscribe to their record through this (#2664); null without sse.subscriptions.
+      app.provide('qdadmSSESubscriptions', this.sseSubscriptions)
     }
 
     app.provide('qdadmHooks', this.hookRegistry)

package/src/kernel/sseSubscriptions.ts

@@ -0,0 +1,54 @@
+/**
+ * Per-record SSE subscriptions (#2664) — the tab's identity, shared by the
+ * stream and the subscription calls.
+ *
+ * A detail page tells the backend which record it shows, so the stream carries
+ * that record's changes to this tab only. The backend has to know which stream
+ * a subscription belongs to, and the only thing both sides can name is the
+ * tab: qdadm mints one id per browser tab, appends it to the stream URL, and
+ * sends the same id with every subscription. One owner, so the two cannot
+ * disagree.
+ */
+
+/** What the kernel hands to `useLiveEntity`: where to subscribe, and as which tab. */
+export interface SseSubscriptions {
+  url: string
+  session: string
+}
+
+/** Injection key under which the kernel provides `SseSubscriptions` (or null). */
+export const SSE_SUBSCRIPTIONS_KEY = 'qdadmSSESubscriptions'
+
+const TAB_SESSION_KEY = 'qdadm:sse-session'
+
+function mintId(): string {
+  // randomUUID only exists in secure contexts; a plain-http deployment still needs an id.
+  const c = typeof crypto !== 'undefined' ? crypto : null
+  if (c && typeof c.randomUUID === 'function') return c.randomUUID()
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`
+}
+
+/**
+ * This tab's id: kept in sessionStorage, so a reload is the same tab and a new
+ * tab is a new one. Storage that throws (blocked site data) still yields an id,
+ * valid for this page load.
+ */
+export function sseTabSession(): string {
+  try {
+    const existing = window.sessionStorage.getItem(TAB_SESSION_KEY)
+    if (existing) return existing
+    const id = mintId()
+    window.sessionStorage.setItem(TAB_SESSION_KEY, id)
+    return id
+  } catch {
+    return mintId()
+  }
+}
+
+/** `url` with `name=value` added to its query string, before any fragment. */
+export function withQueryParam(url: string, name: string, value: string): string {
+  const [base, fragment] = url.split('#', 2)
+  const param = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`
+  const joined = `${base}${base!.includes('?') ? '&' : '?'}${param}`
+  return fragment === undefined ? joined : `${joined}#${fragment}`
+}