@prenta/admin 2.6.1 → 2.8.0

package/src/views/Jobs/useJobsFeed.ts

@@ -0,0 +1,249 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { Job, JobWorkerStatus } from '@prenta/core'
+import { JOBS_LIST_LIMIT, getJobWorker, listJobs } from '../../lib/jobs-service.js'
+
+/** The list refreshes every 5 seconds while Live is on and the tab is visible (JOBS.md). */
+const POLL_MS = 5000
+/** The longest a failing refresh waits before trying again. */
+const MAX_BACKOFF_MS = 60_000
+/** The longest a `Retry-After` is honoured, so a bad header can't stop the list for good. */
+const MAX_RETRY_AFTER_MS = 5 * 60_000
+/** A refresh with no answer by then is abandoned and counts as a failure. */
+const REQUEST_TIMEOUT_MS = 10_000
+/**
+ * The worker status changes once a minute, when a tick ends, so it isn't
+ * fetched with every list refresh: once a few seconds after the tick it
+ * expects, again every 30s while that tick is late, and at least once a
+ * minute. All admin requests share one 100-a-minute budget per IP.
+ */
+const WORKER_MAX_AGE_MS = 60_000
+const WORKER_AFTER_TICK_MS = 5_000
+const WORKER_LATE_RETRY_MS = 30_000
+/** The `Date` header has whole seconds; smaller clock differences are noise. */
+const SKEW_THRESHOLD_MS = 2_000
+
+interface FeedState {
+  jobs: Job[]
+  worker: JobWorkerStatus | null
+  /** When `jobs` was fetched, on the server's clock. Relative times are measured from it. */
+  fetchedAt: number
+  /** The server's clock minus the browser's, when they differ by more than 2s. */
+  skewMs: number
+  /** `error` only until the first list arrives; after that a failed refresh keeps the rows. */
+  status: 'loading' | 'ready' | 'error'
+  /** Why the last list refresh failed, or null when it worked. */
+  error: string | null
+  /** Why the last worker status request failed. The strip shows it; the list doesn't. */
+  workerError: string | null
+}
+
+export interface JobsFeed extends FeedState {
+  reload: () => Promise<void>
+  /** Show a job the server just returned (from run, retry or cancel) before the next refresh. */
+  upsert: (job: Job) => void
+}
+
+/** `document.visibilityState`, as state. */
+export function usePageVisible(): boolean {
+  const [visible, setVisible] = useState(
+    () => typeof document === 'undefined' || document.visibilityState !== 'hidden',
+  )
+  useEffect(() => {
+    const onChange = () => setVisible(document.visibilityState !== 'hidden')
+    document.addEventListener('visibilitychange', onChange)
+    return () => document.removeEventListener('visibilitychange', onChange)
+  }, [])
+  return visible
+}
+
+/** `Date.now()`, updated every `intervalMs` while `running`; frozen otherwise. */
+export function useNow(running: boolean, intervalMs = 1000): number {
+  const [now, setNow] = useState(() => Date.now())
+  useEffect(() => {
+    if (!running) return
+    setNow(Date.now())
+    const timer = window.setInterval(() => setNow(Date.now()), intervalMs)
+    return () => window.clearInterval(timer)
+  }, [running, intervalMs])
+  return now
+}
+
+/** The wait before the next refresh, after `failures` failed ones in a row. */
+function nextDelay(failures: number, retryAfterMs: number | null): number {
+  if (failures === 0) return POLL_MS
+  const backoff = Math.min(POLL_MS * 2 ** failures, MAX_BACKOFF_MS)
+  return retryAfterMs === null
+    ? backoff
+    : Math.max(backoff, Math.min(retryAfterMs, MAX_RETRY_AFTER_MS))
+}
+
+/**
+ * The newest 50 jobs and the worker status, loaded on mount and refreshed
+ * every 5 seconds while `polling` is true. Coming back from paused or hidden
+ * refreshes at once. Failed refreshes back off (10s, 20s, 40s, then every
+ * minute, or longer when a 429 says so) and a success returns to 5 seconds.
+ * A request times out after 10 seconds, and a response older than one
+ * already shown is dropped.
+ */
+export function useJobsFeed(polling: boolean): JobsFeed {
+  const [state, setState] = useState<FeedState>(() => ({
+    jobs: [],
+    worker: null,
+    fetchedAt: Date.now(),
+    skewMs: 0,
+    status: 'loading',
+    error: null,
+    workerError: null,
+  }))
+  const mounted = useRef(false)
+  const issued = useRef(0)
+  /** Responses to requests issued before this id are stale. */
+  const oldestFresh = useRef(0)
+  const inFlight = useRef(0)
+  const controllers = useRef(new Set<AbortController>())
+  const timer = useRef<number | null>(null)
+  const pollingRef = useRef(polling)
+  const failures = useRef(0)
+  const skew = useRef(0)
+  const worker = useRef<JobWorkerStatus | null>(null)
+  /** When the worker status was last asked for, on the browser's clock. */
+  const workerAskedAt = useRef<number | null>(null)
+
+  useEffect(() => {
+    mounted.current = true
+    const pending = controllers.current
+    return () => {
+      mounted.current = false
+      for (const controller of pending) controller.abort()
+      // An aborted request never delivered the worker status; a remount asks again.
+      workerAskedAt.current = null
+      if (timer.current !== null) window.clearTimeout(timer.current)
+      timer.current = null
+    }
+  }, [])
+
+  const workerDue = useCallback((now: number): boolean => {
+    const asked = workerAskedAt.current
+    if (asked === null || now - asked >= WORKER_MAX_AGE_MS) return true
+    const nextTick = worker.current?.nextTickAt
+    if (!nextTick) return false
+    const after = Date.parse(nextTick) - skew.current + WORKER_AFTER_TICK_MS
+    return now >= after && (asked < after || now - asked >= WORKER_LATE_RETRY_MS)
+  }, [])
+
+  // `schedule` and `reload` call each other, so the timer callback reads `reload` from a ref.
+  const reloadRef = useRef<() => Promise<void>>(async () => {})
+  const schedule = useCallback((delay: number) => {
+    if (timer.current !== null) window.clearTimeout(timer.current)
+    timer.current = null
+    if (!mounted.current || !pollingRef.current) return
+    timer.current = window.setTimeout(() => {
+      timer.current = null
+      if (inFlight.current > 0) schedule(POLL_MS)
+      else void reloadRef.current()
+    }, delay)
+  }, [])
+
+  const reload = useCallback(async () => {
+    const id = ++issued.current
+    inFlight.current += 1
+    const controller = new AbortController()
+    controllers.current.add(controller)
+    let timedOut = false
+    const timeout = window.setTimeout(() => {
+      timedOut = true
+      controller.abort()
+    }, REQUEST_TIMEOUT_MS)
+    const startedAt = Date.now()
+    const askWorker = workerDue(startedAt)
+    const askedBefore = workerAskedAt.current
+    if (askWorker) workerAskedAt.current = startedAt
+    // A dropped response never showed its worker status, so the next refresh asks again.
+    const drop = () => {
+      if (askWorker && workerAskedAt.current === startedAt) workerAskedAt.current = askedBefore
+    }
+    try {
+      const [jobs, workerRes] = await Promise.all([
+        listJobs(JOBS_LIST_LIMIT, controller.signal),
+        askWorker ? getJobWorker(controller.signal) : Promise.resolve(null),
+      ])
+      // Aborted by unmount (or React's development remount), not by the timeout.
+      if ((controller.signal.aborted && !timedOut) || !mounted.current) return drop()
+      if (id < oldestFresh.current) return drop()
+      oldestFresh.current = id
+      const receivedAt = Date.now()
+
+      if (jobs.ok && jobs.serverTime !== null) {
+        // Whole seconds, so the middle of that second, against the middle of the request.
+        const measured = jobs.serverTime + 500 - (startedAt + receivedAt) / 2
+        if (Math.abs(measured - skew.current) > SKEW_THRESHOLD_MS) skew.current = measured
+      }
+      if (workerRes?.ok) worker.current = workerRes.value
+      const workerError = workerRes === null ? undefined : workerRes.ok ? null : workerRes.error
+
+      let retryAfter: number | null = null
+      if (jobs.ok) {
+        failures.current = 0
+      } else {
+        failures.current += 1
+        retryAfter = jobs.retryAfterMs
+      }
+      const listError = jobs.ok
+        ? null
+        : timedOut
+          ? `The server didn’t answer within ${REQUEST_TIMEOUT_MS / 1000} seconds`
+          : jobs.error
+
+      setState((prev) => ({
+        jobs: jobs.ok ? jobs.value : prev.jobs,
+        worker: worker.current,
+        fetchedAt: jobs.ok ? receivedAt + skew.current : prev.fetchedAt,
+        skewMs: skew.current,
+        status: jobs.ok || prev.status === 'ready' ? 'ready' : 'error',
+        error: listError,
+        workerError: workerError === undefined ? prev.workerError : workerError,
+      }))
+      schedule(nextDelay(failures.current, retryAfter))
+    } finally {
+      window.clearTimeout(timeout)
+      controllers.current.delete(controller)
+      inFlight.current -= 1
+    }
+  }, [schedule, workerDue])
+  useEffect(() => {
+    reloadRef.current = reload
+  }, [reload])
+
+  const upsert = useCallback((job: Job) => {
+    // A refresh already on its way was read before this change.
+    oldestFresh.current = issued.current + 1
+    setState((prev) => ({
+      ...prev,
+      jobs: prev.jobs.some((row) => row.id === job.id)
+        ? prev.jobs.map((row) => (row.id === job.id ? job : row))
+        : [job, ...prev.jobs].slice(0, JOBS_LIST_LIMIT),
+    }))
+  }, [])
+
+  useEffect(() => {
+    void reload()
+  }, [reload])
+
+  const wasPolling = useRef<boolean | null>(null)
+  useEffect(() => {
+    pollingRef.current = polling
+    const resumed = wasPolling.current === false
+    wasPolling.current = polling
+    if (!polling) return
+    if (resumed) void reload()
+    else if (timer.current === null && inFlight.current === 0) schedule(POLL_MS)
+    return () => {
+      if (timer.current !== null) window.clearTimeout(timer.current)
+      timer.current = null
+    }
+  }, [polling, reload, schedule])
+
+  return { ...state, reload, upsert }
+}

package/src/views/Jobs/useReviewItems.ts

@@ -0,0 +1,187 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { JobReviewItem } from '@prenta/core'
+import { appendReviewItems, mergeReviewItems } from '../../lib/job-drawer.js'
+import {
+  REVIEW_PAGE_MAX,
+  REVIEW_PAGE_SIZE,
+  listReviewItems,
+  type JobsOutcome,
+  type ReviewPage,
+} from '../../lib/jobs-service.js'
+
+interface ReviewItemsState {
+  items: JobReviewItem[]
+  nextCursor: string | null
+  /** `denied`: a 403, because this person can't read the suggested changes. */
+  status: 'loading' | 'ready' | 'error' | 'denied'
+  /** Why the last read failed. With `ready`, the loaded changes stay. */
+  error: string | null
+  loadingMore: boolean
+}
+
+export interface ReviewItems extends ReviewItemsState {
+  /** The next 20 changes. */
+  loadMore: () => void
+  /**
+   * Read the loaded changes again, plus new ones up to the end of their page.
+   * Resolves once the read is shown (or failed).
+   */
+  refresh: () => Promise<void>
+  /** Show the copy of a change a decision just returned. */
+  replace: (item: JobReviewItem) => void
+}
+
+const INITIAL: ReviewItemsState = {
+  items: [],
+  nextCursor: null,
+  status: 'loading',
+  error: null,
+  loadingMore: false,
+}
+
+/**
+ * The loaded changes again, from the first: `count` rounded up to whole pages
+ * of 20, so a short last page also picks up changes that arrived since.
+ */
+async function readLoaded(
+  jobId: string,
+  count: number,
+  signal: AbortSignal,
+): Promise<JobsOutcome<ReviewPage>> {
+  const want = Math.max(1, Math.ceil(count / REVIEW_PAGE_SIZE)) * REVIEW_PAGE_SIZE
+  const items: JobReviewItem[] = []
+  let cursor: string | null = null
+  do {
+    const res = await listReviewItems(
+      jobId,
+      { cursor, limit: Math.min(REVIEW_PAGE_MAX, want - items.length) },
+      signal,
+    )
+    if (!res.ok) return res
+    items.push(...res.value.items)
+    cursor = res.value.nextCursor
+  } while (cursor && items.length < want && !signal.aborted)
+  return { ok: true, value: { items, nextCursor: cursor } }
+}
+
+/**
+ * A batch job's suggested changes for the drawer's Review tab, 20 at a time
+ * (TRACKING P-18). The first page loads as soon as the drawer opens, so a
+ * 403 hides the tab before anyone picks it. While `watching` (the tab is
+ * open), the loaded changes are read again whenever `version` changes: the
+ * job's `updatedAt` and its number of changes, so new suggestions show up as
+ * the job runs. Reads run one at a time.
+ *
+ * Edits in progress live with the drawer, not here, so a read never touches
+ * them. A change decided here after a read started keeps the decision's copy.
+ */
+export function useReviewItems(
+  jobId: string,
+  options: { enabled: boolean; watching: boolean; version: string },
+): ReviewItems {
+  const { enabled, watching, version } = options
+  const [state, setState] = useState<ReviewItemsState>(INITIAL)
+  /** The state as last set, for reads that start after a render. */
+  const current = useRef<ReviewItemsState>(INITIAL)
+  const queue = useRef<Promise<void>>(Promise.resolve())
+  const signal = useRef<AbortSignal | null>(null)
+  /** Bumped by every decision shown here; a read keeps changes touched after it began. */
+  const seq = useRef(0)
+  const touched = useRef(new Map<string, number>())
+  /** The `version` the loaded changes were read at; null until the first read. */
+  const readAt = useRef<string | null>(null)
+
+  const update = useCallback((patch: Partial<ReviewItemsState>) => {
+    current.current = { ...current.current, ...patch }
+    setState(current.current)
+  }, [])
+
+  useEffect(() => {
+    const controller = new AbortController()
+    signal.current = controller.signal
+    // React's development remount aborts the first read, so the remount reads again.
+    readAt.current = null
+    return () => controller.abort()
+  }, [])
+
+  /** Run `task` after the reads before it; resolves when it's done. */
+  const enqueue = useCallback((task: (signal: AbortSignal) => Promise<void>): Promise<void> => {
+    queue.current = queue.current
+      .then(() => {
+        const active = signal.current
+        return active && !active.aborted ? task(active) : undefined
+      })
+      .catch(() => undefined)
+    return queue.current
+  }, [])
+
+  const refresh = useCallback(() => {
+    return enqueue(async (abort) => {
+      const startedAt = seq.current
+      const res = await readLoaded(jobId, current.current.items.length, abort)
+      if (abort.aborted) return
+      if (!res.ok) {
+        if (res.status === 403) update({ status: 'denied', error: res.error })
+        else
+          update({
+            status: current.current.status === 'ready' ? 'ready' : 'error',
+            error: res.error,
+          })
+        return
+      }
+      const keep = new Set<string>()
+      for (const [id, at] of touched.current) if (at > startedAt) keep.add(id)
+      update({
+        items: mergeReviewItems(res.value.items, current.current.items, keep),
+        nextCursor: res.value.nextCursor,
+        status: 'ready',
+        error: null,
+      })
+    })
+  }, [enqueue, jobId, update])
+
+  const loadMore = useCallback(() => {
+    if (!current.current.nextCursor || current.current.loadingMore) return
+    update({ loadingMore: true })
+    enqueue(async (abort) => {
+      const cursor = current.current.nextCursor
+      if (!cursor) {
+        update({ loadingMore: false })
+        return
+      }
+      const res = await listReviewItems(jobId, { cursor }, abort)
+      if (abort.aborted) return
+      update(
+        res.ok
+          ? {
+              items: appendReviewItems(current.current.items, res.value.items),
+              nextCursor: res.value.nextCursor,
+              loadingMore: false,
+              error: null,
+            }
+          : { loadingMore: false, error: res.error },
+      )
+    })
+  }, [enqueue, jobId, update])
+
+  const replace = useCallback(
+    (item: JobReviewItem) => {
+      seq.current += 1
+      touched.current.set(item.id, seq.current)
+      update({ items: current.current.items.map((row) => (row.id === item.id ? item : row)) })
+    },
+    [update],
+  )
+
+  useEffect(() => {
+    // A 403 won't change while the drawer is open.
+    if (!enabled || current.current.status === 'denied') return
+    if (readAt.current !== null && (!watching || readAt.current === version)) return
+    readAt.current = version
+    void refresh()
+  }, [enabled, watching, version, refresh])
+
+  return { ...state, loadMore, refresh, replace }
+}