@stacksjs/defaults 0.74.3 → 0.74.4

package/app/Actions/Dashboard/Infrastructure/LogIndexAction.ts

@@ -1,16 +1,35 @@
 import type { RequestInstance } from '@stacksjs/types'
+import type { DashboardLogQuery, DashboardLogRange } from './log-provider'
 import { Action } from '@stacksjs/actions'
-import { db } from '@stacksjs/database'
 import { dashboardRequestValue } from '../dashboard-request'
 import { dashboardOperationalError } from '../dashboard-response'
-import { DASHBOARD_LOG_TYPES, normalizeDashboardLog, summarizeDashboardLogTypes } from './log-dashboard'
-
-const RANGES = ['1', '7', '30', '90', 'all'] as const
+import { DASHBOARD_LOG_TYPES } from './log-dashboard'
+import { DASHBOARD_LOG_RANGES, readDashboardLogs } from './log-provider'
 
 function queryValue(request: RequestInstance, key: string): string {
   return dashboardRequestValue(request, key)
 }
 
+/** Reads the filters off the request. Unknown values fall back rather than fail. */
+function logQuery(request: RequestInstance): DashboardLogQuery {
+  const requestedType = queryValue(request, 'type').toLowerCase()
+  const requestedRange = queryValue(request, 'range').toLowerCase()
+
+  return {
+    page: Math.max(1, Number.parseInt(queryValue(request, 'page') || '1', 10) || 1),
+    perPage: Math.min(100, Math.max(10, Number.parseInt(queryValue(request, 'per_page') || '25', 10) || 25)),
+    search: queryValue(request, 'search'),
+    type: DASHBOARD_LOG_TYPES.includes(requestedType as typeof DASHBOARD_LOG_TYPES[number])
+      ? requestedType
+      : '',
+    source: queryValue(request, 'source').toLowerCase(),
+    project: queryValue(request, 'project'),
+    range: DASHBOARD_LOG_RANGES.includes(requestedRange as DashboardLogRange)
+      ? requestedRange as DashboardLogRange
+      : '30',
+  }
+}
+
 export default new Action({
   name: 'LogIndexAction',
   description: 'Returns filtered, paginated Log model records for the dashboard.',
@@ -19,86 +38,7 @@ export default new Action({
 
   async handle(request: RequestInstance) {
     try {
-      const requestedPage = Math.max(1, Number.parseInt(queryValue(request, 'page') || '1', 10) || 1)
-      const perPage = Math.min(100, Math.max(10, Number.parseInt(queryValue(request, 'per_page') || '25', 10) || 25))
-      const search = queryValue(request, 'search')
-      const requestedType = queryValue(request, 'type').toLowerCase()
-      const type = DASHBOARD_LOG_TYPES.includes(requestedType as typeof DASHBOARD_LOG_TYPES[number])
-        ? requestedType
-        : ''
-      const source = queryValue(request, 'source').toLowerCase()
-      const project = queryValue(request, 'project')
-      const requestedRange = queryValue(request, 'range').toLowerCase()
-      const range = RANGES.includes(requestedRange as typeof RANGES[number]) ? requestedRange : '30'
-      const cutoff = range === 'all' ? 0 : Date.now() - Number(range) * 86400000
-      const searchPattern = `%${search}%`
-
-      const applyFilters = <T extends {
-        where: (...args: any[]) => T
-        whereAny: (columns: string[], operator: string, value: unknown) => T
-      }>(query: T): T => {
-        let filtered = query
-        if (cutoff)
-          filtered = filtered.where('timestamp', '>=', cutoff)
-        if (type)
-          filtered = filtered.where('type', '=', type)
-        if (source)
-          filtered = filtered.where('source', '=', source)
-        if (project)
-          filtered = filtered.where('project', '=', project)
-        if (search)
-          filtered = filtered.whereAny(['message', 'project', 'file', 'stacktrace'], 'like', searchPattern)
-        return filtered
-      }
-
-      const [countRow, typeRows, sourceRows, projectRows] = await Promise.all([
-        applyFilters(db.selectFrom('logs').select(db.fn.count('id').as('count')))
-          .executeTakeFirst() as Promise<{ count: number | string } | undefined>,
-        applyFilters(db.selectFrom('logs').select(['type', db.fn.count('id').as('count')]))
-          .groupBy('type')
-          .execute() as Promise<Array<{ type: string, count: number | string }>>,
-        db.selectFrom('logs').select('source').distinct().orderBy('source', 'asc').limit(100).execute() as Promise<Array<{ source: string }>>,
-        db.selectFrom('logs').select('project').distinct().orderBy('project', 'asc').limit(500).execute() as Promise<Array<{ project: string }>>,
-      ])
-
-      const total = Number(countRow?.count || 0)
-      const totalPages = Math.max(1, Math.ceil(total / perPage))
-      const page = Math.min(requestedPage, totalPages)
-      const rows = await applyFilters(db.selectFrom('logs').select([
-        'id',
-        'timestamp',
-        'type',
-        'source',
-        'message',
-        'project',
-        'stacktrace',
-        'file',
-        'created_at',
-        'updated_at',
-      ]))
-        .orderBy('timestamp', 'desc')
-        .orderBy('id', 'desc')
-        .limit(perPage)
-        .offset((page - 1) * perPage)
-        .execute()
-
-      return {
-        logs: rows.map(normalizeDashboardLog),
-        summary: summarizeDashboardLogTypes(typeRows, total),
-        pagination: {
-          page,
-          perPage,
-          total,
-          totalPages,
-        },
-        options: {
-          sources: sourceRows.map(row => row.source).filter(Boolean),
-          projects: projectRows.map(row => row.project).filter(Boolean),
-          types: [...DASHBOARD_LOG_TYPES],
-          ranges: [...RANGES],
-        },
-        generatedAt: new Date().toISOString(),
-      }
+      return await readDashboardLogs(logQuery(request))
     }
     catch (error) {
       return dashboardOperationalError(error, 'Logs could not be loaded.', 'LogIndexAction')

package/app/Actions/Dashboard/Infrastructure/log-provider.ts

@@ -0,0 +1,189 @@
+import type { DashboardProviderUnavailable } from '../dashboard-provider'
+import type { DashboardLogRecord, DashboardLogSummary } from './log-dashboard'
+import { db } from '@stacksjs/database'
+import { HQ_READ_UNAVAILABLE, readThroughProvider, resolveDashboardDriver } from '../dashboard-provider'
+import { DASHBOARD_LOG_TYPES, normalizeDashboardLog, summarizeDashboardLogTypes } from './log-dashboard'
+
+/**
+ * Where the Logs section reads from.
+ *
+ * The local provider is the query that used to sit inside `LogIndexAction`,
+ * moved without changing a line of its logic: the same five statements against
+ * the `logs` table, the same filters, the same ordering, and the same clamp of
+ * a requested page down to the last page that exists.
+ *
+ * The payload deliberately reuses `DashboardLogRecord` and
+ * `DashboardLogSummary` from `log-dashboard.ts`. Three stx components import
+ * those same types, so a provider that returns the wrong shape is a compile
+ * error against the declaration the components themselves consume rather than
+ * a surprise at runtime.
+ */
+
+export const DASHBOARD_LOG_RANGES = ['1', '7', '30', '90', 'all'] as const
+
+export type DashboardLogRange = typeof DASHBOARD_LOG_RANGES[number]
+
+export interface DashboardLogQuery {
+  page: number
+  perPage: number
+  search: string
+  /** One of {@link DASHBOARD_LOG_TYPES}, or empty for every level. */
+  type: string
+  source: string
+  project: string
+  range: DashboardLogRange
+}
+
+export interface DashboardLogPagination {
+  page: number
+  perPage: number
+  total: number
+  totalPages: number
+}
+
+export interface DashboardLogOptions {
+  sources: string[]
+  projects: string[]
+  types: string[]
+  ranges: string[]
+}
+
+export interface DashboardLogPayload extends Partial<DashboardProviderUnavailable> {
+  logs: DashboardLogRecord[]
+  summary: DashboardLogSummary
+  pagination: DashboardLogPagination
+  options: DashboardLogOptions
+  generatedAt: string
+}
+
+export interface DashboardLogsProvider {
+  logs: (query: DashboardLogQuery) => Promise<DashboardLogPayload>
+}
+
+/** An empty page of logs, carrying the reason there is nothing to show. */
+export function emptyLogPayload(reason: string, query?: DashboardLogQuery): DashboardLogPayload {
+  return {
+    logs: [],
+    summary: { total: 0, error: 0, warning: 0, info: 0, success: 0 },
+    pagination: {
+      page: 1,
+      perPage: query?.perPage ?? 25,
+      total: 0,
+      totalPages: 1,
+    },
+    options: {
+      sources: [],
+      projects: [],
+      types: [...DASHBOARD_LOG_TYPES],
+      ranges: [...DASHBOARD_LOG_RANGES],
+    },
+    generatedAt: new Date().toISOString(),
+    unavailable: reason,
+  }
+}
+
+function isLogPayload(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object')
+    return false
+  const candidate = payload as Partial<DashboardLogPayload>
+  return Array.isArray(candidate.logs)
+    && Boolean(candidate.summary)
+    && Boolean(candidate.pagination)
+    && Boolean(candidate.options)
+}
+
+/**
+ * This application's own `logs` table.
+ *
+ * Not wrapped in a catch. A failure here is a local database failure, and the
+ * action has always answered that with its operational error, which is the
+ * behaviour every existing caller and test expects.
+ */
+export const localLogsProvider: DashboardLogsProvider = {
+  async logs(query: DashboardLogQuery): Promise<DashboardLogPayload> {
+    const cutoff = query.range === 'all' ? 0 : Date.now() - Number(query.range) * 86400000
+    const searchPattern = `%${query.search}%`
+
+    const applyFilters = <T extends {
+      where: (...args: any[]) => T
+      whereAny: (columns: string[], operator: string, value: unknown) => T
+    }>(builder: T): T => {
+      let filtered = builder
+      if (cutoff)
+        filtered = filtered.where('timestamp', '>=', cutoff)
+      if (query.type)
+        filtered = filtered.where('type', '=', query.type)
+      if (query.source)
+        filtered = filtered.where('source', '=', query.source)
+      if (query.project)
+        filtered = filtered.where('project', '=', query.project)
+      if (query.search)
+        filtered = filtered.whereAny(['message', 'project', 'file', 'stacktrace'], 'like', searchPattern)
+      return filtered
+    }
+
+    const [countRow, typeRows, sourceRows, projectRows] = await Promise.all([
+      applyFilters(db.selectFrom('logs').select(db.fn.count('id').as('count')))
+        .executeTakeFirst() as Promise<{ count: number | string } | undefined>,
+      applyFilters(db.selectFrom('logs').select(['type', db.fn.count('id').as('count')]))
+        .groupBy('type')
+        .execute() as Promise<Array<{ type: string, count: number | string }>>,
+      db.selectFrom('logs').select('source').distinct().orderBy('source', 'asc').limit(100).execute() as Promise<Array<{ source: string }>>,
+      db.selectFrom('logs').select('project').distinct().orderBy('project', 'asc').limit(500).execute() as Promise<Array<{ project: string }>>,
+    ])
+
+    const total = Number(countRow?.count || 0)
+    const totalPages = Math.max(1, Math.ceil(total / query.perPage))
+    const page = Math.min(query.page, totalPages)
+    const rows = await applyFilters(db.selectFrom('logs').select([
+      'id',
+      'timestamp',
+      'type',
+      'source',
+      'message',
+      'project',
+      'stacktrace',
+      'file',
+      'created_at',
+      'updated_at',
+    ]))
+      .orderBy('timestamp', 'desc')
+      .orderBy('id', 'desc')
+      .limit(query.perPage)
+      .offset((page - 1) * query.perPage)
+      .execute()
+
+    return {
+      logs: rows.map(normalizeDashboardLog),
+      summary: summarizeDashboardLogTypes(typeRows, total),
+      pagination: {
+        page,
+        perPage: query.perPage,
+        total,
+        totalPages,
+      },
+      options: {
+        sources: sourceRows.map(row => row.source).filter(Boolean),
+        projects: projectRows.map(row => row.project).filter(Boolean),
+        types: [...DASHBOARD_LOG_TYPES],
+        ranges: [...DASHBOARD_LOG_RANGES],
+      },
+      generatedAt: new Date().toISOString(),
+    }
+  },
+}
+
+/** Reads the Logs section through whichever provider config selects. */
+export async function readDashboardLogs(query: DashboardLogQuery): Promise<DashboardLogPayload> {
+  const driver = await resolveDashboardDriver('logs')
+
+  if (driver.name === 'local')
+    return localLogsProvider.logs(query)
+
+  return readThroughProvider(
+    'logs',
+    reason => emptyLogPayload(reason, query),
+    async () => emptyLogPayload(HQ_READ_UNAVAILABLE, query),
+    isLogPayload,
+  )
+}

package/app/Actions/Dashboard/dashboard-provider.ts

@@ -0,0 +1,170 @@
+import type { DashboardHqDriverOptions, DashboardProviderName, DashboardProviderSelection } from '@stacksjs/types'
+
+/**
+ * The seam between a dashboard section and the data behind it.
+ *
+ * Every section in the dashboard used to reach for a local store directly:
+ * the Logs page queried the `logs` table, the Errors pages called into
+ * `@stacksjs/commerce`, and web Analytics aggregated the `Request` model. That
+ * works exactly once, for the application the dashboard is running inside. It
+ * cannot show the logs of a fleet, and it gave the hosted products (loghq,
+ * bughq, analyticshq) nowhere to plug in.
+ *
+ * This module resolves which provider a domain reads from. `local` is the
+ * default and is byte-for-byte the behaviour that shipped before the seam
+ * existed, including how it fails: a local provider is never wrapped, so a
+ * database outage still surfaces the same operational error it always did.
+ * Anything else is remote, and remote is wrapped, because a section whose
+ * backend is unreachable has to render empty with a reason rather than take
+ * the page down.
+ *
+ * Read paths only. No provider writes.
+ */
+
+/** The dashboard sections that resolve a provider. */
+export type DashboardProviderDomain = 'logs' | 'errors' | 'analytics'
+
+const PROVIDER_NAMES: readonly DashboardProviderName[] = ['local', 'hq']
+
+/**
+ * Why a section has no data.
+ *
+ * Carried on the payload beside the empty collections rather than thrown, so
+ * the section renders its own empty state instead of an error page. The string
+ * is written for whoever is looking at the dashboard, not for a log file.
+ */
+export interface DashboardProviderUnavailable {
+  unavailable: string
+}
+
+export interface ResolvedDashboardDriver {
+  name: DashboardProviderName
+  options: DashboardHqDriverOptions
+}
+
+const resolved = new Map<DashboardProviderDomain, ResolvedDashboardDriver>()
+
+/**
+ * Forgets every memoized driver choice.
+ *
+ * Resolution is cached per domain so a request does not re-read config on
+ * every query. Tests that walk more than one configuration in a single process
+ * need that cache cleared between cases, and clearing it is much cheaper than
+ * `mock.module`, which replaces the shared module instance for every other
+ * test file in the run and is not undone by `mock.restore()`.
+ */
+export function resetDashboardProviders(): void {
+  resolved.clear()
+}
+
+function readSelection(section: unknown, domain: DashboardProviderDomain): DashboardProviderSelection {
+  if (!section || typeof section !== 'object')
+    return {}
+  const providers = (section as { providers?: unknown }).providers
+  if (!providers || typeof providers !== 'object')
+    return {}
+  const selection = (providers as Record<string, unknown>)[domain]
+  return selection && typeof selection === 'object' ? selection as DashboardProviderSelection : {}
+}
+
+function selectDriverName(value: unknown, domain: DashboardProviderDomain): DashboardProviderName {
+  if (value === undefined || value === null || value === '')
+    return 'local'
+
+  switch (value) {
+    case 'local':
+      return 'local'
+    case 'hq':
+      return 'hq'
+    default:
+      // `satisfies DashboardConfig` is erased at runtime, and config files are
+      // ordinary TypeScript an app can hand-edit, so an unknown name reaches
+      // here as a plain string. Falling back to local keeps the section
+      // rendering; throwing would take it down over a typo.
+      console.warn(
+        `[dashboard/api] config.dashboard.providers.${domain}.driver is `
+        + `"${String(value)}", which is not a known provider. Reading local data instead. `
+        + `Available providers: ${PROVIDER_NAMES.join(', ')}.`,
+      )
+      return 'local'
+  }
+}
+
+/**
+ * Reads a domain's provider choice from config.
+ *
+ * Config is read through `overridesReady`. A read that happens before the
+ * application's own config files have been layered in returns the framework
+ * defaults with no error at all, which would silently resolve `local` in an
+ * application that had asked for something else.
+ */
+export async function resolveDashboardDriver(domain: DashboardProviderDomain): Promise<ResolvedDashboardDriver> {
+  const cached = resolved.get(domain)
+  if (cached)
+    return cached
+
+  let selection: DashboardProviderSelection = {}
+  try {
+    const { config, overridesReady } = await import('@stacksjs/config')
+    // Rejection means boot could not read the application's config at all.
+    // The framework defaults are still a usable answer, and they are local.
+    await overridesReady.catch(() => {})
+    selection = readSelection(config.dashboard, domain)
+  }
+  catch (error) {
+    console.warn(`[dashboard/api] dashboard provider config for ${domain} could not be read, using local:`, error)
+  }
+
+  const driver: ResolvedDashboardDriver = {
+    name: selectDriverName(selection.driver, domain),
+    options: selection.drivers?.hq ?? {},
+  }
+
+  resolved.set(domain, driver)
+  return driver
+}
+
+/**
+ * Runs a remote provider so that it cannot take a section down.
+ *
+ * Three ways a remote read goes wrong, all of which land on the same empty
+ * payload plus a reason: it rejects, it never answers, or it answers with
+ * something that is not the shape the section renders. The last one matters
+ * as much as the first two, because a payload that is merely missing its
+ * array reaches the component and fails there instead, which is a blank page
+ * rather than an empty state.
+ */
+export async function readThroughProvider<T>(
+  domain: DashboardProviderDomain,
+  empty: (reason: string) => T,
+  read: () => Promise<T>,
+  isValid: (payload: unknown) => boolean,
+): Promise<T> {
+  try {
+    const payload = await read()
+    if (!isValid(payload)) {
+      console.error(`[dashboard/api] the ${domain} provider answered with an unexpected shape`)
+      return empty('This section could not be read from its provider.')
+    }
+    return payload
+  }
+  catch (error) {
+    console.error(`[dashboard/api] the ${domain} provider could not be read:`, error)
+    return empty('This section could not be reached. It is configured to read from a hosted provider.')
+  }
+}
+
+/**
+ * The reason an `hq` provider has no data yet.
+ *
+ * Both published SDKs are ingest clients. `@loghq/stacks` and `@bughq/stacks`
+ * send records and expose no function that reads any back, and a project's
+ * ingest key grants no read access by design. The hosted read APIs do exist,
+ * but they authenticate a person rather than a machine, so wiring one needs a
+ * product decision about service credentials before any code here can help.
+ *
+ * Selecting `hq` today therefore yields an empty section that says so, which
+ * is the honest answer and keeps the degrade path real rather than theoretical.
+ */
+export const HQ_READ_UNAVAILABLE
+  = 'No data. The hosted provider has no read API yet, so this section cannot be filled from it.'

package/app/Actions/Monitoring/ErrorGroupAction.ts

@@ -1,6 +1,6 @@
 import { Action } from '@stacksjs/actions'
-import { errors } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
+import { readErrorsByGroup } from './error-provider'
 
 export default new Action({
   name: 'Error Group',
@@ -14,8 +14,6 @@ export default new Action({
       return response.json({ error: 'Both type and message are required' }, 400)
     }
 
-    const results = await errors.fetchByGroup(type, message)
-
-    return response.json({ data: results })
+    return response.json(await readErrorsByGroup(type, message))
   },
 })

package/app/Actions/Monitoring/ErrorIndexAction.ts

@@ -1,14 +1,12 @@
 import { Action } from '@stacksjs/actions'
-import { errors } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
+import { readGroupedErrors } from './error-provider'
 
 export default new Action({
   name: 'Error Index',
   description: 'Fetch all grouped errors (Sentry-like aggregation)',
   method: 'GET',
   async handle() {
-    const results = await errors.fetchGrouped()
-
-    return response.json({ data: results })
+    return response.json(await readGroupedErrors())
   },
 })

package/app/Actions/Monitoring/ErrorShowAction.ts

@@ -1,6 +1,6 @@
 import { Action } from '@stacksjs/actions'
-import { errors } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
+import { readErrorById } from './error-provider'
 
 export default new Action({
   name: 'Error Show',
@@ -13,12 +13,12 @@ export default new Action({
     if (id === null)
       return response.json({ error: 'A numeric error id is required' }, 422)
 
-    const result = await errors.fetchById(id)
+    const result = await readErrorById(id)
 
-    if (!result) {
+    if (!result.data) {
       return response.json({ error: 'Error not found' }, 404)
     }
 
-    return response.json({ data: result })
+    return response.json(result)
   },
 })

package/app/Actions/Monitoring/ErrorStatsAction.ts

@@ -1,14 +1,12 @@
 import { Action } from '@stacksjs/actions'
-import { errors } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
+import { readErrorStats } from './error-provider'
 
 export default new Action({
   name: 'Error Stats',
   description: 'Fetch error statistics',
   method: 'GET',
   async handle() {
-    const stats = await errors.fetchStats()
-
-    return response.json({ data: stats })
+    return response.json(await readErrorStats())
   },
 })

package/app/Actions/Monitoring/ErrorTimelineAction.ts

@@ -1,14 +1,12 @@
 import { Action } from '@stacksjs/actions'
-import { errors } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
+import { readErrorTimeline } from './error-provider'
 
 export default new Action({
   name: 'Error Timeline',
   description: 'Fetch error timeline (hourly counts for last 24 hours)',
   method: 'GET',
   async handle() {
-    const timeline = await errors.fetchTimeline()
-
-    return response.json({ data: timeline })
+    return response.json(await readErrorTimeline())
   },
 })