@quazardous/qdadm 2.32.0 → 2.33.0

package/src/composables/useLogStream.ts

@@ -0,0 +1,264 @@
+/**
+ * useLogStream - the line buffer behind LogStream (#4110)
+ *
+ * Reads a backend log as it is written, from one of four sources the app
+ * picks, and keeps the lines parsed once (ANSI styles, error flag) so the
+ * view only slices them.
+ *
+ * ```ts
+ * // Offsets: GET /tasks/42/log?from=<n> → { lines, next, done }
+ * useLogStream({ poll: (from) => api.get(`/tasks/42/log`, { params: { from } }).then((r) => r.data) })
+ *
+ * // Server-sent events, one line (or several, newline-separated) per message
+ * useLogStream({ sse: '/tasks/42/log/stream', endEvent: 'end' })
+ *
+ * // Anything that pushes: an SSEBridge event, a WebSocket…
+ * useLogStream({ subscribe: ({ push, end }) => bridge.onEvent('task:log', (p) => push(p.data.lines)) })
+ *
+ * // A finished log
+ * useLogStream({ lines: text.split('\n') })
+ * ```
+ */
+
+import { shallowRef, ref, onScopeDispose, getCurrentScope, type Ref, type ShallowRef } from 'vue'
+import { parseAnsiLine, stripAnsi, type AnsiSegment, type AnsiStyle } from '../utils/ansi'
+
+export interface LogPollResult {
+  lines: string[]
+  /** Offset to ask for next. Defaults to the previous one plus the lines received. */
+  next?: number
+  /** True once the log is complete: polling stops. */
+  done?: boolean
+}
+
+export interface LogPushApi {
+  push: (lines: string | string[]) => void
+  end: () => void
+  fail: (error: unknown) => void
+}
+
+export type LogSource =
+  | { poll: (from: number) => Promise<LogPollResult>; intervalMs?: number; from?: number }
+  | {
+      sse: string | (() => EventSource)
+      /** Event carrying lines. Default `message`. */
+      event?: string
+      /** Event that closes the log. Default `end`. */
+      endEvent?: string
+      /** Turn a message's data into lines. Default: JSON `{ lines, done }` or plain text split on newlines. */
+      parse?: (data: string) => string[] | LogPollResult
+    }
+  | { subscribe: (api: LogPushApi) => (() => void) | void }
+  | { lines: string[] }
+
+export interface LogLine {
+  /** 1-based number in the whole log, kept when old lines are dropped. */
+  n: number
+  raw: string
+  /** The line without ANSI escapes: what search, errors and download read. */
+  text: string
+  segments: AnsiSegment[]
+  error: boolean
+}
+
+export type LogStreamStatus = 'idle' | 'streaming' | 'done' | 'error'
+
+export interface UseLogStreamOptions {
+  /** Lines matching it are flagged as errors. */
+  errorPattern?: RegExp | string | null
+  /** Oldest lines are dropped past this count. Default 100 000. */
+  maxLines?: number
+  /** Start reading at once. Default true. */
+  immediate?: boolean
+}
+
+export interface UseLogStreamReturn {
+  lines: ShallowRef<LogLine[]>
+  status: Ref<LogStreamStatus>
+  error: Ref<string | null>
+  /** Lines dropped from the start because of maxLines. */
+  dropped: Ref<number>
+  start: () => void
+  stop: () => void
+  /** Empty the buffer and read the source again from its start. */
+  restart: () => void
+  /** Add lines by hand (used by the push sources, open to the app). */
+  append: (lines: string | string[]) => void
+}
+
+const MAX_BACKOFF_MS = 30_000
+
+function toRegExp(pattern: RegExp | string | null | undefined): RegExp | null {
+  if (!pattern) return null
+  if (typeof pattern === 'string') return new RegExp(pattern, 'i')
+  // A global or sticky regex keeps lastIndex between test() calls and skips lines.
+  return new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''))
+}
+
+function splitLines(chunk: string | string[]): string[] {
+  const list = Array.isArray(chunk) ? chunk : [chunk]
+  return list.flatMap((l) => String(l).replace(/\r\n?/g, '\n').split('\n'))
+}
+
+function defaultParse(data: string): string[] | LogPollResult {
+  const trimmed = data.trimStart()
+  if (trimmed.startsWith('{')) {
+    try {
+      const parsed = JSON.parse(data)
+      if (parsed && Array.isArray(parsed.lines)) return parsed as LogPollResult
+    } catch {
+      // not JSON: a line that happens to start with a brace
+    }
+  }
+  return splitLines(data)
+}
+
+export function useLogStream(source: LogSource, options: UseLogStreamOptions = {}): UseLogStreamReturn {
+  const { maxLines = 100_000, immediate = true } = options
+  const errorRe = toRegExp(options.errorPattern)
+
+  const lines = shallowRef<LogLine[]>([])
+  const status = ref<LogStreamStatus>('idle')
+  const error = ref<string | null>(null)
+  const dropped = ref(0)
+
+  let ansiState: AnsiStyle = {}
+  let counter = 0
+  let teardown: (() => void) | null = null
+  // A restart must not let a poll answer from the previous run append.
+  let run = 0
+
+  function append(chunk: string | string[]): void {
+    const incoming = splitLines(chunk)
+    if (incoming.length === 0) return
+    const parsed: LogLine[] = incoming.map((raw) => {
+      const { segments, state } = parseAnsiLine(raw, ansiState)
+      ansiState = state
+      const text = stripAnsi(raw)
+      return { n: ++counter, raw, text, segments, error: errorRe ? errorRe.test(text) : false }
+    })
+    let next = lines.value.concat(parsed)
+    if (next.length > maxLines) {
+      dropped.value += next.length - maxLines
+      next = next.slice(next.length - maxLines)
+    }
+    lines.value = next
+  }
+
+  function finish(): void {
+    status.value = 'done'
+    teardown?.()
+    teardown = null
+  }
+
+  function fail(err: unknown): void {
+    error.value = err instanceof Error ? err.message : String(err)
+    status.value = 'error'
+  }
+
+  function startPoll(src: Extract<LogSource, { poll: unknown }>): void {
+    const interval = src.intervalMs ?? 1000
+    const current = run
+    let offset = src.from ?? 0
+    let delay = interval
+    let timer: ReturnType<typeof setTimeout> | null = null
+    let stopped = false
+
+    const tick = async () => {
+      if (stopped || current !== run) return
+      try {
+        const result = await src.poll(offset)
+        if (stopped || current !== run) return
+        const received = result?.lines ?? []
+        append(received)
+        offset = result?.next ?? offset + received.length
+        status.value = 'streaming'
+        error.value = null
+        delay = interval
+        if (result?.done) return finish()
+      } catch (err) {
+        if (stopped || current !== run) return
+        fail(err)
+        delay = Math.min(delay * 2, MAX_BACKOFF_MS)
+      }
+      timer = setTimeout(tick, delay)
+    }
+    teardown = () => {
+      stopped = true
+      if (timer) clearTimeout(timer)
+    }
+    void tick()
+  }
+
+  function startSse(src: Extract<LogSource, { sse: unknown }>): void {
+    const es = typeof src.sse === 'string' ? new EventSource(src.sse) : src.sse()
+    const parse = src.parse ?? defaultParse
+    const onLines = (event: Event) => {
+      const result = parse(String((event as MessageEvent).data ?? ''))
+      if (Array.isArray(result)) append(result)
+      else {
+        append(result.lines ?? [])
+        if (result.done) finish()
+      }
+    }
+    const onEnd = () => finish()
+    const onError = () => {
+      // EventSource reconnects by itself; only a closed source is a failure.
+      if (es.readyState === 2) fail('The log stream closed')
+    }
+    es.addEventListener(src.event ?? 'message', onLines)
+    es.addEventListener(src.endEvent ?? 'end', onEnd)
+    es.addEventListener('error', onError)
+    teardown = () => es.close()
+  }
+
+  function startSubscribe(src: Extract<LogSource, { subscribe: unknown }>): void {
+    const current = run
+    const guard = <A extends unknown[]>(fn: (...args: A) => void) => (...args: A) => {
+      if (current === run && status.value === 'streaming') fn(...args)
+    }
+    const unsubscribe = src.subscribe({ push: guard(append), end: guard(finish), fail: guard(fail) })
+    if (status.value === 'streaming' && current === run) {
+      teardown = () => unsubscribe?.()
+    } else {
+      unsubscribe?.()
+    }
+  }
+
+  function start(): void {
+    if (teardown || status.value === 'streaming' || status.value === 'done') return
+    run++
+    error.value = null
+    if ('lines' in source) {
+      append(source.lines)
+      status.value = 'done'
+      return
+    }
+    status.value = 'streaming'
+    if ('poll' in source) startPoll(source)
+    else if ('sse' in source) startSse(source)
+    else startSubscribe(source)
+  }
+
+  function stop(): void {
+    run++
+    teardown?.()
+    teardown = null
+    if (status.value === 'streaming') status.value = 'idle'
+  }
+
+  function restart(): void {
+    stop()
+    lines.value = []
+    dropped.value = 0
+    counter = 0
+    ansiState = {}
+    status.value = 'idle'
+    start()
+  }
+
+  if (getCurrentScope()) onScopeDispose(stop)
+  if (immediate) start()
+
+  return { lines, status, error, dropped, start, stop, restart, append }
+}

package/src/email/index.ts

@@ -0,0 +1,46 @@
+/**
+ * qdadm/email - raw MIME parsing for EmailPreview (#4113), through postal-mime
+ *
+ * Import from '@quazardous/qdadm/email' only if the app shows raw MIME
+ * messages (an .eml, a sink that returns the source). postal-mime is an
+ * optional peer dependency: install it to use this entry point. A parsed
+ * email ({ headers, html, text, attachments }) needs neither.
+ *
+ * Usage:
+ *   import { parseMime } from '@quazardous/qdadm/email'
+ *   <EmailPreview :raw="capture.source" :parser="parseMime" />
+ */
+import PostalMime from 'postal-mime'
+import type { EmailAddress, ParsedEmail } from '../utils/email'
+
+type PostalAddress = { name: string; address?: string; group?: Array<{ name: string; address: string }> }
+
+function flatten(list: PostalAddress[] | PostalAddress | undefined): EmailAddress[] {
+  const items = !list ? [] : Array.isArray(list) ? list : [list]
+  return items.flatMap((a): Array<{ name: string; address?: string }> => (a.group ? a.group : [a])).map((a) => ({ name: a.name || null, address: a.address ?? null }))
+}
+
+/** Parse a raw MIME message. The source is kept for the Source tab. */
+export async function parseMime(raw: string | ArrayBuffer | Uint8Array): Promise<ParsedEmail> {
+  const email = await new PostalMime({ attachmentEncoding: 'base64' }).parse(raw)
+  return {
+    from: flatten(email.from as PostalAddress | undefined)[0] ?? null,
+    to: flatten(email.to as PostalAddress[] | undefined),
+    cc: flatten(email.cc as PostalAddress[] | undefined),
+    replyTo: flatten(email.replyTo as PostalAddress[] | undefined),
+    subject: email.subject ?? null,
+    date: email.date ?? null,
+    messageId: email.messageId ?? null,
+    headers: email.headers.map((h) => ({ key: h.originalKey ?? h.key, value: h.value })),
+    html: email.html ?? null,
+    text: email.text ?? null,
+    raw: typeof raw === 'string' ? raw : new TextDecoder().decode(raw),
+    attachments: email.attachments.map((a) => ({
+      filename: a.filename,
+      contentType: a.mimeType,
+      content: a.content as string,
+      contentId: a.contentId ?? null,
+      disposition: a.disposition,
+    })),
+  }
+}

package/src/entity/storage/SdkStorage.ts

@@ -62,6 +62,29 @@ export interface SdkMethods<T extends EntityRecord = EntityRecord> {
   [key: string]: SdkMethodConfig<T> | undefined
 }
 
+/** The options of a path request, as `EntityManager.request` passes them. */
+export interface SdkPathRequestOptions {
+  data?: unknown
+  params?: Record<string, unknown>
+  headers?: Record<string, string>
+}
+
+/**
+ * How a path request (`'GET', 'distinct/status'`) reaches the backend (#4069).
+ *
+ * A generated SDK has no method for an arbitrary path, and no reliable way
+ * to tell its base URL or this entity's endpoint, so the app supplies it —
+ * usually through the SDK's own client.
+ */
+export type SdkPathRequest = (
+  method: string,
+  path: string,
+  options: SdkPathRequestOptions,
+  sdk: SdkInstance
+) => Promise<unknown>
+
+const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'])
+
 /**
  * SdkStorage options
  */
@@ -74,6 +97,8 @@ export interface SdkStorageOptions<T extends EntityRecord = EntityRecord> {
   transforms?: Partial<Record<string, SdkMethodTransforms<T>>>
   responseFormat?: SdkResponseFormat | null
   clientSidePagination?: boolean
+  /** Runs `request(method, path, options)` calls — `optionsEndpoint` filters among them. */
+  request?: SdkPathRequest | null
 }
 
 /**
@@ -101,6 +126,7 @@ export class SdkStorage<T extends EntityRecord = EntityRecord> extends IStorage<
   protected _transformResponse: SdkGlobalResponseTransform<T> | null
   protected _transforms: Partial<Record<string, SdkMethodTransforms<T>>>
   protected _responseFormat: SdkResponseFormat | null
+  protected _pathRequest: SdkPathRequest | null
 
   constructor(options: SdkStorageOptions<T> = {}) {
     super()
@@ -113,6 +139,7 @@ export class SdkStorage<T extends EntityRecord = EntityRecord> extends IStorage<
       transforms = {},
       responseFormat = null,
       clientSidePagination = false,
+      request = null,
     } = options
 
     this._sdk = sdk
@@ -123,6 +150,12 @@ export class SdkStorage<T extends EntityRecord = EntityRecord> extends IStorage<
     this._transforms = transforms
     this._responseFormat = responseFormat
     this.clientSidePagination = clientSidePagination
+    this._pathRequest = request
+  }
+
+  /** Whether `request(method, path)` can run, i.e. a `request` option was given. */
+  get supportsPathRequests(): boolean {
+    return this._pathRequest !== null
   }
 
   get sdk(): SdkInstance {
@@ -335,7 +368,26 @@ export class SdkStorage<T extends EntityRecord = EntityRecord> extends IStorage<
     await this._execute('delete', pathParams)
   }
 
-  async request<R = unknown>(methodName: string, params: unknown = {}): Promise<R> {
+  /**
+   * Two calls share this name. `request('GET', 'distinct/status', options)` is
+   * the path request every storage answers, the one `EntityManager.request`
+   * makes; it goes through the `request` option. `request('getStats', params)`
+   * calls a configured method or an SDK method by name.
+   *
+   * Told apart by the verb: no SDK method is called `GET`, and before #4069
+   * the path form looked one up and failed with "SDK method 'GET' not found".
+   */
+  async request<R = unknown>(methodName: string, params: unknown = {}, options: SdkPathRequestOptions = {}): Promise<R> {
+    if (HTTP_METHODS.has(methodName) && typeof params === 'string') {
+      if (!this._pathRequest) {
+        throw new Error(
+          `SdkStorage cannot run ${methodName} '${params}': a generated SDK has no method for a path. ` +
+            `Pass a request option, e.g. request: (method, url, o, sdk) => sdk.client.request({ method, url, query: o.params, body: o.data })`
+        )
+      }
+      return (await this._pathRequest(methodName, params, options, this.sdk)) as R
+    }
+
     if (this._methods[methodName]) {
       return (await this._execute(methodName, params)) as R
     }

package/src/entity/storage/index.ts

@@ -72,4 +72,6 @@ export type {
   SdkResponseFormat,
   SdkMethods,
   SdkStorageOptions,
+  SdkPathRequest,
+  SdkPathRequestOptions,
 } from './SdkStorage'

package/src/i18n/defaults/core.en.generated.ts

@@ -71,6 +71,91 @@ export default `core:
     notRegistered: not registered
     remove: Remove
     via: "via {origin}"
+  # LogStream (#4110)
+  log:
+    streaming: Streaming
+    done: Complete
+    stopped: Stopped
+    failed: "Failed: {error}"
+    lines: "{count} lines"
+    search: Search the log
+    previous: Previous match
+    next: Next match
+    onlyMatches: Only matching lines
+    errors: "{count} errors"
+    firstError: Go to the next error line
+    wrap: Wrap long lines
+    follow: Follow the end of the log
+    download: Download the log
+    newLines: "{count} new lines, resume"
+    empty: No output yet
+  # EntityTimeline (#4111)
+  timeline:
+    actors: Filter by actor
+    loading: Loading…
+    empty: Nothing happened yet
+    newEvents: "{count} new events"
+    oldestFirst: Oldest first
+    newestFirst: Newest first
+  # PayloadViewer / PayloadDiff (#4112)
+  payload:
+    headers: "Headers ({count})"
+    headerRow: First row is a header
+    copy: Copy
+    copied: Copied to the clipboard
+    copyFailed: Could not copy
+    download: Download
+    showAll: "Show all {count} rows"
+    binary: "Binary content, {size}. First bytes:"
+    malformed: "Not valid {format} ({error}), shown as text"
+    expected: Expected
+    captured: Captured
+    identical: Identical
+    unchanged: "{count} unchanged lines"
+    showSame: "Show {count} unchanged rows"
+    inline: Inline
+    split: Side by side
+  # EmailPreview (#4113)
+  email:
+    from: From
+    to: To
+    cc: Cc
+    replyTo: Reply to
+    date: Date
+    noSubject: (no subject)
+    allHeaders: "All headers ({count})"
+    noParser: "A raw message needs a parser: pass parseMime from @quazardous/qdadm/email. Showing the source."
+    tab:
+      html: HTML
+      text: Text
+      source: Source
+    imagesBlocked: "{count} remote images blocked"
+    loadImages: Load images
+    blockImages: Block images
+    empty: This email has no body
+    unnamed: (unnamed)
+    inline: inline
+    download: Download
+  # TaskRunner (#4114)
+  task:
+    status:
+      starting: Starting
+      queued: Queued
+      running: Running
+      succeeded: Done
+      failed: Failed
+      cancelled: Cancelled
+    cancel: Cancel the task
+    close: Close
+    background: Run in the background
+    open: Open the task
+    readError: "Could not read the task ({error}), still trying"
+    start: Start
+    dontStart: Do not start
+    typeToConfirm: "Type {value} to confirm"
+    tray: "{count} running tasks"
+    trayDone: Recent tasks
+    clear: Clear finished
 # The breadcrumb's View↔Edit toggle (useNavContext).
 breadcrumb:
   view: View

package/src/i18n/defaults/core.en.yml

@@ -69,6 +69,91 @@ core:
     notRegistered: not registered
     remove: Remove
     via: "via {origin}"
+  # LogStream (#4110)
+  log:
+    streaming: Streaming
+    done: Complete
+    stopped: Stopped
+    failed: "Failed: {error}"
+    lines: "{count} lines"
+    search: Search the log
+    previous: Previous match
+    next: Next match
+    onlyMatches: Only matching lines
+    errors: "{count} errors"
+    firstError: Go to the next error line
+    wrap: Wrap long lines
+    follow: Follow the end of the log
+    download: Download the log
+    newLines: "{count} new lines, resume"
+    empty: No output yet
+  # EntityTimeline (#4111)
+  timeline:
+    actors: Filter by actor
+    loading: Loading…
+    empty: Nothing happened yet
+    newEvents: "{count} new events"
+    oldestFirst: Oldest first
+    newestFirst: Newest first
+  # PayloadViewer / PayloadDiff (#4112)
+  payload:
+    headers: "Headers ({count})"
+    headerRow: First row is a header
+    copy: Copy
+    copied: Copied to the clipboard
+    copyFailed: Could not copy
+    download: Download
+    showAll: "Show all {count} rows"
+    binary: "Binary content, {size}. First bytes:"
+    malformed: "Not valid {format} ({error}), shown as text"
+    expected: Expected
+    captured: Captured
+    identical: Identical
+    unchanged: "{count} unchanged lines"
+    showSame: "Show {count} unchanged rows"
+    inline: Inline
+    split: Side by side
+  # EmailPreview (#4113)
+  email:
+    from: From
+    to: To
+    cc: Cc
+    replyTo: Reply to
+    date: Date
+    noSubject: (no subject)
+    allHeaders: "All headers ({count})"
+    noParser: "A raw message needs a parser: pass parseMime from @quazardous/qdadm/email. Showing the source."
+    tab:
+      html: HTML
+      text: Text
+      source: Source
+    imagesBlocked: "{count} remote images blocked"
+    loadImages: Load images
+    blockImages: Block images
+    empty: This email has no body
+    unnamed: (unnamed)
+    inline: inline
+    download: Download
+  # TaskRunner (#4114)
+  task:
+    status:
+      starting: Starting
+      queued: Queued
+      running: Running
+      succeeded: Done
+      failed: Failed
+      cancelled: Cancelled
+    cancel: Cancel the task
+    close: Close
+    background: Run in the background
+    open: Open the task
+    readError: "Could not read the task ({error}), still trying"
+    start: Start
+    dontStart: Do not start
+    typeToConfirm: "Type {value} to confirm"
+    tray: "{count} running tasks"
+    trayDone: Recent tasks
+    clear: Clear finished
 # The breadcrumb's View↔Edit toggle (useNavContext).
 breadcrumb:
   view: View

package/src/i18n/defaults/core.fr.generated.ts

@@ -71,6 +71,91 @@ export default `core:
     notRegistered: non enregistrée
     remove: Retirer
     via: "via {origin}"
+  # LogStream (#4110)
+  log:
+    streaming: En cours
+    done: Terminé
+    stopped: Arrêté
+    failed: "Échec : {error}"
+    lines: "{count} lignes"
+    search: Chercher dans le log
+    previous: Occurrence précédente
+    next: Occurrence suivante
+    onlyMatches: Seulement les lignes trouvées
+    errors: "{count} erreurs"
+    firstError: Aller à la ligne d'erreur suivante
+    wrap: Couper les lignes longues
+    follow: Suivre la fin du log
+    download: Télécharger le log
+    newLines: "{count} nouvelles lignes, reprendre"
+    empty: Rien pour l'instant
+  # EntityTimeline (#4111)
+  timeline:
+    actors: Filtrer par acteur
+    loading: Chargement…
+    empty: Rien ne s'est encore passé
+    newEvents: "{count} nouveaux événements"
+    oldestFirst: Plus anciens d'abord
+    newestFirst: Plus récents d'abord
+  # PayloadViewer / PayloadDiff (#4112)
+  payload:
+    headers: "En-têtes ({count})"
+    headerRow: La première ligne est un en-tête
+    copy: Copier
+    copied: Copié dans le presse-papiers
+    copyFailed: Copie impossible
+    download: Télécharger
+    showAll: "Afficher les {count} lignes"
+    binary: "Contenu binaire, {size}. Premiers octets :"
+    malformed: "{format} invalide ({error}), affiché comme texte"
+    expected: Attendu
+    captured: Capturé
+    identical: Identiques
+    unchanged: "{count} lignes inchangées"
+    showSame: "Afficher les {count} lignes inchangées"
+    inline: En ligne
+    split: Côte à côte
+  # EmailPreview (#4113)
+  email:
+    from: De
+    to: À
+    cc: Cc
+    replyTo: Répondre à
+    date: Date
+    noSubject: (sans objet)
+    allHeaders: "Tous les en-têtes ({count})"
+    noParser: "Un message brut demande un parser : passer parseMime de @quazardous/qdadm/email. La source est affichée."
+    tab:
+      html: HTML
+      text: Texte
+      source: Source
+    imagesBlocked: "{count} images distantes bloquées"
+    loadImages: Charger les images
+    blockImages: Bloquer les images
+    empty: Ce mail n'a pas de contenu
+    unnamed: (sans nom)
+    inline: intégrée
+    download: Télécharger
+  # TaskRunner (#4114)
+  task:
+    status:
+      starting: Démarrage
+      queued: En attente
+      running: En cours
+      succeeded: Terminée
+      failed: Échouée
+      cancelled: Annulée
+    cancel: Annuler la tâche
+    close: Fermer
+    background: Continuer en arrière-plan
+    open: Ouvrir la tâche
+    readError: "Lecture de la tâche impossible ({error}), nouvel essai"
+    start: Lancer
+    dontStart: Ne pas lancer
+    typeToConfirm: "Taper {value} pour confirmer"
+    tray: "{count} tâches en cours"
+    trayDone: Tâches récentes
+    clear: Effacer les terminées
 # The breadcrumb's View↔Edit toggle (useNavContext).
 breadcrumb:
   view: Voir