@strav/devtools 0.1.0

package/src/devtools_manager.ts

@@ -0,0 +1,242 @@
+import { inject, Configuration, Emitter, ConfigurationError } from '@stravigor/kernel'
+import { Database } from '@stravigor/database'
+import type { DevtoolsConfig, CollectorOptions } from './types.ts'
+
+import EntryStore from './storage/entry_store.ts'
+import AggregateStore from './storage/aggregate_store.ts'
+
+import type Collector from './collectors/collector.ts'
+import RequestCollector from './collectors/request_collector.ts'
+import QueryCollector from './collectors/query_collector.ts'
+import ExceptionCollector from './collectors/exception_collector.ts'
+import LogCollector from './collectors/log_collector.ts'
+import JobCollector from './collectors/job_collector.ts'
+
+import type Recorder from './recorders/recorder.ts'
+import SlowRequestsRecorder from './recorders/slow_requests.ts'
+import SlowQueriesRecorder from './recorders/slow_queries.ts'
+
+/**
+ * Central DI hub for the devtools package.
+ *
+ * Resolved once via the DI container — reads devtools config, creates
+ * storage instances, boots collectors and recorders, and exposes the
+ * middleware and dashboard APIs.
+ *
+ * @example
+ * app.singleton(DevtoolsManager)
+ * app.resolve(DevtoolsManager)
+ *
+ * // Use the request-tracking middleware
+ * router.use(DevtoolsManager.middleware())
+ */
+@inject
+export default class DevtoolsManager {
+  private static _config: DevtoolsConfig
+  private static _entryStore: EntryStore
+  private static _aggregateStore: AggregateStore
+  private static _collectors: Collector[] = []
+  private static _recorders: Recorder[] = []
+  private static _requestCollector: RequestCollector
+  private static _queryCollector: QueryCollector
+  private static _currentBatchId: string = crypto.randomUUID()
+  private static _booted = false
+
+  constructor(db: Database, config: Configuration) {
+    if (DevtoolsManager._booted) return
+
+    DevtoolsManager._config = {
+      enabled: config.get('devtools.enabled', true) as boolean,
+      storage: {
+        pruneAfter: config.get('devtools.storage.pruneAfter', 24) as number,
+      },
+      collectors: {
+        request: config.get('devtools.collectors.request', {
+          enabled: true,
+          sizeLimit: 64,
+        }) as CollectorOptions & { sizeLimit: number },
+        query: config.get('devtools.collectors.query', {
+          enabled: true,
+          slow: 100,
+        }) as CollectorOptions & { slow: number },
+        exception: config.get('devtools.collectors.exception', {
+          enabled: true,
+        }) as CollectorOptions,
+        log: config.get('devtools.collectors.log', {
+          enabled: true,
+          level: 'debug',
+        }) as CollectorOptions & { level: string },
+        job: config.get('devtools.collectors.job', { enabled: true }) as CollectorOptions,
+      },
+      recorders: {
+        slowRequests: config.get('devtools.recorders.slowRequests', {
+          enabled: true,
+          threshold: 1000,
+          sampleRate: 1.0,
+        }) as any,
+        slowQueries: config.get('devtools.recorders.slowQueries', {
+          enabled: true,
+          threshold: 1000,
+          sampleRate: 1.0,
+        }) as any,
+      },
+    }
+
+    if (!DevtoolsManager._config.enabled) return
+
+    // Initialize storage (use the app's DB connection)
+    const sql = db.sql
+    DevtoolsManager._entryStore = new EntryStore(sql)
+    DevtoolsManager._aggregateStore = new AggregateStore(sql)
+
+    // Boot collectors
+    const getBatchId = () => DevtoolsManager._currentBatchId
+
+    DevtoolsManager._requestCollector = new RequestCollector(
+      DevtoolsManager._entryStore,
+      DevtoolsManager._config.collectors.request
+    )
+
+    DevtoolsManager._queryCollector = new QueryCollector(
+      DevtoolsManager._entryStore,
+      DevtoolsManager._config.collectors.query as any,
+      getBatchId
+    )
+
+    const exceptionCollector = new ExceptionCollector(
+      DevtoolsManager._entryStore,
+      DevtoolsManager._config.collectors.exception,
+      getBatchId
+    )
+
+    const logCollector = new LogCollector(
+      DevtoolsManager._entryStore,
+      DevtoolsManager._config.collectors.log as any,
+      getBatchId
+    )
+
+    const jobCollector = new JobCollector(
+      DevtoolsManager._entryStore,
+      DevtoolsManager._config.collectors.job,
+      getBatchId
+    )
+
+    DevtoolsManager._collectors = [
+      DevtoolsManager._requestCollector,
+      DevtoolsManager._queryCollector,
+      exceptionCollector,
+      logCollector,
+      jobCollector,
+    ]
+
+    // Boot recorders
+    const slowRequests = new SlowRequestsRecorder(
+      DevtoolsManager._aggregateStore,
+      DevtoolsManager._config.recorders.slowRequests
+    )
+
+    const slowQueries = new SlowQueriesRecorder(
+      DevtoolsManager._aggregateStore,
+      DevtoolsManager._config.recorders.slowQueries
+    )
+
+    DevtoolsManager._recorders = [slowRequests, slowQueries]
+
+    // Register all listeners
+    for (const collector of DevtoolsManager._collectors) {
+      collector.register()
+    }
+    for (const recorder of DevtoolsManager._recorders) {
+      recorder.register()
+    }
+
+    // Install the SQL query proxy
+    const proxied = DevtoolsManager._queryCollector.installProxy(sql)
+
+    // Replace the connection on the Database class
+    // We use Object.defineProperty because Database._connection is private
+    // but we need to swap it with our proxied version
+    ;(db as any).connection = proxied
+    ;(db.constructor as any)._connection = proxied
+
+    DevtoolsManager._booted = true
+  }
+
+  static get config(): DevtoolsConfig {
+    if (!DevtoolsManager._config) {
+      throw new ConfigurationError(
+        'DevtoolsManager not configured. Resolve it through the container first.'
+      )
+    }
+    return DevtoolsManager._config
+  }
+
+  static get entryStore(): EntryStore {
+    return DevtoolsManager._entryStore
+  }
+
+  static get aggregateStore(): AggregateStore {
+    return DevtoolsManager._aggregateStore
+  }
+
+  /** Returns the request-tracking middleware. */
+  static middleware() {
+    return DevtoolsManager._requestCollector.middleware()
+  }
+
+  /** Set the current batch ID (called by the request middleware). */
+  static setBatchId(id: string): void {
+    DevtoolsManager._currentBatchId = id
+  }
+
+  /** Get the current batch ID. */
+  static get batchId(): string {
+    return DevtoolsManager._currentBatchId
+  }
+
+  /** Create the storage tables. Called during setup or first boot. */
+  static async ensureTables(): Promise<void> {
+    await DevtoolsManager._entryStore.ensureTable()
+    await DevtoolsManager._aggregateStore.ensureTable()
+  }
+
+  /** Emit internal events for recorders. Called by the request collector. */
+  static emitRequest(data: {
+    path: string
+    method: string
+    duration: number
+    status: number
+  }): void {
+    if (Emitter.listenerCount('devtools:request') > 0) {
+      Emitter.emit('devtools:request', data).catch(() => {})
+    }
+  }
+
+  /** Emit internal events for recorders. Called by the query collector. */
+  static emitQuery(data: { sql: string; duration: number }): void {
+    if (Emitter.listenerCount('devtools:query') > 0) {
+      Emitter.emit('devtools:query', data).catch(() => {})
+    }
+  }
+
+  /** Tear down all collectors and recorders. */
+  static teardown(): void {
+    for (const collector of DevtoolsManager._collectors) {
+      collector.teardown()
+    }
+    for (const recorder of DevtoolsManager._recorders) {
+      recorder.teardown()
+    }
+    DevtoolsManager._collectors = []
+    DevtoolsManager._recorders = []
+    DevtoolsManager._booted = false
+  }
+
+  /** Reset all static state. For testing only. */
+  static reset(): void {
+    DevtoolsManager.teardown()
+    DevtoolsManager._config = undefined as any
+    DevtoolsManager._entryStore = undefined as any
+    DevtoolsManager._aggregateStore = undefined as any
+  }
+}

package/src/devtools_provider.ts

@@ -0,0 +1,54 @@
+import { ServiceProvider } from '@stravigor/kernel'
+import type { Application } from '@stravigor/kernel'
+import type { Context } from '@stravigor/http'
+import { Router } from '@stravigor/http'
+import DevtoolsManager from './devtools_manager.ts'
+import { registerDashboard } from './dashboard/routes.ts'
+
+export interface DevtoolsProviderOptions {
+  /** Auto-create the devtools tables. Default: `true` */
+  ensureTables?: boolean
+  /** Auto-register the request-tracking middleware on the router. Default: `true` */
+  middleware?: boolean
+  /** Auto-register the dashboard routes at `/_devtools`. Default: `true` */
+  dashboard?: boolean
+  /** Custom auth guard for the dashboard. Receives the request context, returns boolean. */
+  guard?: (ctx: Context) => boolean | Promise<boolean>
+}
+
+export default class DevtoolsProvider extends ServiceProvider {
+  readonly name = 'devtools'
+  override readonly dependencies = ['database']
+
+  constructor(private options?: DevtoolsProviderOptions) {
+    super()
+  }
+
+  override register(app: Application): void {
+    app.singleton(DevtoolsManager)
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(DevtoolsManager)
+
+    if (this.options?.ensureTables !== false) {
+      await DevtoolsManager.ensureTables()
+    }
+
+    if (!DevtoolsManager.config.enabled) return
+
+    const router = app.resolve(Router)
+
+    if (this.options?.middleware !== false) {
+      router.use(DevtoolsManager.middleware())
+    }
+
+    if (this.options?.dashboard !== false) {
+      registerDashboard(router, this.options?.guard)
+    }
+  }
+
+  override shutdown(): void {
+    DevtoolsManager.teardown()
+  }
+}

package/src/errors.ts

@@ -0,0 +1,3 @@
+import { ConfigurationError } from '@stravigor/kernel'
+
+export class DevtoolsError extends ConfigurationError {}

package/src/helpers.ts

@@ -0,0 +1,82 @@
+import DevtoolsManager from './devtools_manager.ts'
+import type { Middleware } from '@stravigor/http'
+import type { EntryRecord, AggregateRecord, EntryType, AggregateFunction } from './types.ts'
+
+/**
+ * Devtools helper — the primary convenience API.
+ *
+ * @example
+ * import { devtools } from '@stravigor/devtools'
+ *
+ * // Add the middleware to capture requests
+ * router.use(devtools.middleware())
+ *
+ * // Query entries
+ * const requests = await devtools.entries('request', 50)
+ * const entry = await devtools.find(uuid)
+ * const related = await devtools.batch(batchId)
+ */
+export const devtools = {
+  /** Returns the request-tracking middleware. */
+  middleware(): Middleware {
+    return DevtoolsManager.middleware()
+  },
+
+  /** Create storage tables (idempotent). */
+  async ensureTables(): Promise<void> {
+    return DevtoolsManager.ensureTables()
+  },
+
+  /** List entries, optionally filtered by type. */
+  async entries(type?: EntryType, limit = 50, offset = 0): Promise<EntryRecord[]> {
+    return DevtoolsManager.entryStore.list(type, limit, offset)
+  },
+
+  /** Find a single entry by UUID. */
+  async find(uuid: string): Promise<EntryRecord | null> {
+    return DevtoolsManager.entryStore.find(uuid)
+  },
+
+  /** Find all entries belonging to a batch. */
+  async batch(batchId: string): Promise<EntryRecord[]> {
+    return DevtoolsManager.entryStore.batch(batchId)
+  },
+
+  /** Search entries by tag. */
+  async byTag(tag: string, limit = 50): Promise<EntryRecord[]> {
+    return DevtoolsManager.entryStore.byTag(tag, limit)
+  },
+
+  /** Query aggregated metrics. */
+  async aggregates(
+    type: string,
+    period: number,
+    aggregate: AggregateFunction,
+    limit = 24
+  ): Promise<AggregateRecord[]> {
+    return DevtoolsManager.aggregateStore.query(type, period, aggregate, limit)
+  },
+
+  /** Top keys by aggregated value. */
+  async topKeys(
+    type: string,
+    period: number,
+    aggregate: AggregateFunction,
+    limit = 10
+  ): Promise<AggregateRecord[]> {
+    return DevtoolsManager.aggregateStore.topKeys(type, period, aggregate, limit)
+  },
+
+  /** Prune old entries and aggregates. */
+  async prune(hours?: number): Promise<{ entries: number; aggregates: number }> {
+    const h = hours ?? DevtoolsManager.config.storage.pruneAfter
+    const entries = await DevtoolsManager.entryStore.prune(h)
+    const aggregates = await DevtoolsManager.aggregateStore.prune(h)
+    return { entries, aggregates }
+  },
+
+  /** Count entries, optionally by type. */
+  async count(type?: EntryType): Promise<number> {
+    return DevtoolsManager.entryStore.count(type)
+  },
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+// Manager
+export { default, default as DevtoolsManager } from './devtools_manager.ts'
+
+// Provider
+export { default as DevtoolsProvider } from './devtools_provider.ts'
+export type { DevtoolsProviderOptions } from './devtools_provider.ts'
+
+// Helper
+export { devtools } from './helpers.ts'
+
+// Storage
+export { default as EntryStore } from './storage/entry_store.ts'
+export { default as AggregateStore, PERIODS } from './storage/aggregate_store.ts'
+
+// Collectors
+export { default as Collector } from './collectors/collector.ts'
+export { default as RequestCollector } from './collectors/request_collector.ts'
+export { default as QueryCollector } from './collectors/query_collector.ts'
+export { default as ExceptionCollector } from './collectors/exception_collector.ts'
+export { default as LogCollector } from './collectors/log_collector.ts'
+export { default as JobCollector } from './collectors/job_collector.ts'
+
+// Recorders
+export { default as Recorder } from './recorders/recorder.ts'
+export { default as SlowRequestsRecorder } from './recorders/slow_requests.ts'
+export { default as SlowQueriesRecorder } from './recorders/slow_queries.ts'
+
+// Dashboard
+export { registerDashboard } from './dashboard/routes.ts'
+export { dashboardAuth } from './dashboard/middleware.ts'
+
+// Errors
+export { DevtoolsError } from './errors.ts'
+
+// Types
+export type {
+  DevtoolsEntry,
+  EntryRecord,
+  AggregateRecord,
+  DevtoolsConfig,
+  EntryType,
+  AggregateFunction,
+  CollectorOptions,
+  RecorderOptions,
+} from './types.ts'

package/src/recorders/recorder.ts

@@ -0,0 +1,51 @@
+import type AggregateStore from '../storage/aggregate_store.ts'
+import type { AggregateFunction, RecorderOptions } from '../types.ts'
+
+/**
+ * Base class for all recorders (the Pulse-like component).
+ *
+ * A recorder listens to the same framework events as collectors but
+ * produces aggregated metrics instead of individual entries.
+ */
+export default abstract class Recorder {
+  protected enabled: boolean
+  protected threshold: number
+  protected sampleRate: number
+
+  constructor(
+    protected store: AggregateStore,
+    protected options: RecorderOptions
+  ) {
+    this.enabled = options.enabled !== false
+    this.threshold = options.threshold ?? 1000
+    this.sampleRate = options.sampleRate ?? 1.0
+  }
+
+  /** Register event listeners. Called once during DevtoolsManager boot. */
+  abstract register(): void
+
+  /** Remove event listeners. Called during teardown. */
+  abstract teardown(): void
+
+  /** Check if this event should be sampled (for high-traffic apps). */
+  protected shouldSample(): boolean {
+    if (this.sampleRate >= 1.0) return true
+    return Math.random() < this.sampleRate
+  }
+
+  /** Record a metric value into the aggregate store. */
+  protected async aggregate(
+    type: string,
+    key: string,
+    value: number,
+    aggregates: AggregateFunction[] = ['count', 'max', 'avg']
+  ): Promise<void> {
+    if (!this.enabled || !this.shouldSample()) return
+
+    try {
+      await this.store.record(type, key, value, aggregates)
+    } catch {
+      // Recorders must never crash the app
+    }
+  }
+}

package/src/recorders/slow_queries.ts

@@ -0,0 +1,44 @@
+import { Emitter } from '@stravigor/kernel'
+import type { Listener } from '@stravigor/kernel'
+import Recorder from './recorder.ts'
+import type AggregateStore from '../storage/aggregate_store.ts'
+import type { RecorderOptions } from '../types.ts'
+
+/**
+ * Records aggregated metrics for slow database queries.
+ *
+ * Listens to the `devtools:query` event emitted by the QueryCollector
+ * after each query. Only records queries that exceed the configured threshold.
+ */
+export default class SlowQueriesRecorder extends Recorder {
+  private listener: Listener | null = null
+
+  constructor(store: AggregateStore, options: RecorderOptions) {
+    super(store, options)
+  }
+
+  register(): void {
+    if (!this.enabled) return
+
+    this.listener = (payload: { sql: string; duration: number }) => {
+      if (payload.duration < this.threshold) return
+
+      // Normalize SQL for grouping (strip specific values)
+      const normalized = payload.sql
+        .replace(/\$\d+/g, '$?')
+        .replace(/'[^']*'/g, "'?'")
+        .slice(0, 200)
+
+      this.aggregate('slow_query', normalized, payload.duration)
+    }
+
+    Emitter.on('devtools:query', this.listener)
+  }
+
+  teardown(): void {
+    if (this.listener) {
+      Emitter.off('devtools:query', this.listener)
+      this.listener = null
+    }
+  }
+}

package/src/recorders/slow_requests.ts

@@ -0,0 +1,44 @@
+import { Emitter } from '@stravigor/kernel'
+import type { Listener } from '@stravigor/kernel'
+import Recorder from './recorder.ts'
+import type AggregateStore from '../storage/aggregate_store.ts'
+import type { RecorderOptions } from '../types.ts'
+
+/**
+ * Records aggregated metrics for slow HTTP requests.
+ *
+ * Listens to the `devtools:request` event emitted by the RequestCollector
+ * after each request. Only records requests that exceed the configured threshold.
+ */
+export default class SlowRequestsRecorder extends Recorder {
+  private listener: Listener | null = null
+
+  constructor(store: AggregateStore, options: RecorderOptions) {
+    super(store, options)
+  }
+
+  register(): void {
+    if (!this.enabled) return
+
+    this.listener = (payload: {
+      path: string
+      method: string
+      duration: number
+      status: number
+    }) => {
+      if (payload.duration < this.threshold) return
+
+      const key = `${payload.method} ${payload.path}`
+      this.aggregate('slow_request', key, payload.duration)
+    }
+
+    Emitter.on('devtools:request', this.listener)
+  }
+
+  teardown(): void {
+    if (this.listener) {
+      Emitter.off('devtools:request', this.listener)
+      this.listener = null
+    }
+  }
+}