@stravigor/devtools 0.1.0

package/src/storage/aggregate_store.ts

@@ -0,0 +1,195 @@
+import type { SQL } from 'bun'
+import type { AggregateRecord, AggregateFunction } from '../types.ts'
+
+/** Aggregation periods in seconds. */
+export const PERIODS = {
+  ONE_HOUR: 3600,
+  SIX_HOURS: 21600,
+  ONE_DAY: 86400,
+  SEVEN_DAYS: 604800,
+} as const
+
+/**
+ * Stores and queries pre-aggregated metric buckets in `_strav_devtools_aggregates`.
+ *
+ * Used by recorders to store slow request counts, slow query counts, etc.
+ * The dashboard reads these for time-series charts without scanning raw entries.
+ */
+export default class AggregateStore {
+  constructor(private sql: SQL) {}
+
+  /** Create the aggregates table if it doesn't exist. */
+  async ensureTable(): Promise<void> {
+    await this.sql`
+      CREATE TABLE IF NOT EXISTS "_strav_devtools_aggregates" (
+        "id" BIGSERIAL PRIMARY KEY,
+        "bucket" INT NOT NULL,
+        "period" INT NOT NULL,
+        "type" VARCHAR(30) NOT NULL,
+        "key" TEXT NOT NULL DEFAULT '',
+        "aggregate" VARCHAR(10) NOT NULL,
+        "value" NUMERIC(20, 2) NOT NULL DEFAULT 0,
+        "count" INT,
+        UNIQUE ("bucket", "period", "type", "aggregate", "key")
+      )
+    `
+
+    await this.sql`
+      CREATE INDEX IF NOT EXISTS "idx_strav_devtools_aggregates_lookup"
+        ON "_strav_devtools_aggregates" ("type", "period", "bucket" DESC)
+    `
+  }
+
+  /**
+   * Record a value into the appropriate time buckets.
+   * Updates existing bucket rows via upsert (INSERT ... ON CONFLICT).
+   */
+  async record(
+    type: string,
+    key: string,
+    value: number,
+    aggregates: AggregateFunction[]
+  ): Promise<void> {
+    const now = Math.floor(Date.now() / 1000)
+
+    for (const period of Object.values(PERIODS)) {
+      const bucket = Math.floor(now / period) * period
+
+      for (const agg of aggregates) {
+        await this.upsert(bucket, period, type, key, agg, value)
+      }
+    }
+  }
+
+  /** Query aggregated data for a type over a time range. */
+  async query(
+    type: string,
+    period: number,
+    aggregate: AggregateFunction,
+    limit = 24
+  ): Promise<AggregateRecord[]> {
+    const rows = await this.sql`
+      SELECT * FROM "_strav_devtools_aggregates"
+      WHERE "type" = ${type}
+        AND "period" = ${period}
+        AND "aggregate" = ${aggregate}
+      ORDER BY "bucket" DESC
+      LIMIT ${limit}
+    `
+    return rows.map(hydrateAggregate)
+  }
+
+  /** Query top keys by aggregate value for a type. */
+  async topKeys(
+    type: string,
+    period: number,
+    aggregate: AggregateFunction,
+    limit = 10
+  ): Promise<AggregateRecord[]> {
+    const now = Math.floor(Date.now() / 1000)
+    const since = now - period
+
+    const rows = await this.sql`
+      SELECT "key", SUM("value") AS "value", SUM("count") AS "count",
+             MAX("bucket") AS "bucket", ${period}::int AS "period",
+             ${type} AS "type", ${aggregate} AS "aggregate", 0 AS "id"
+      FROM "_strav_devtools_aggregates"
+      WHERE "type" = ${type}
+        AND "period" = ${period}
+        AND "aggregate" = ${aggregate}
+        AND "bucket" >= ${since}
+      GROUP BY "key"
+      ORDER BY SUM("value") DESC
+      LIMIT ${limit}
+    `
+    return rows.map(hydrateAggregate)
+  }
+
+  /** Delete aggregates older than the given number of hours. */
+  async prune(hours: number): Promise<number> {
+    const cutoff = Math.floor(Date.now() / 1000) - hours * 3600
+
+    const rows = await this.sql`
+      DELETE FROM "_strav_devtools_aggregates"
+      WHERE "bucket" < ${cutoff}
+    `
+    return rows.count
+  }
+
+  private async upsert(
+    bucket: number,
+    period: number,
+    type: string,
+    key: string,
+    aggregate: AggregateFunction,
+    value: number
+  ): Promise<void> {
+    switch (aggregate) {
+      case 'count':
+        await this.sql`
+          INSERT INTO "_strav_devtools_aggregates" ("bucket", "period", "type", "key", "aggregate", "value", "count")
+          VALUES (${bucket}, ${period}, ${type}, ${key}, 'count', 1, 1)
+          ON CONFLICT ("bucket", "period", "type", "aggregate", "key")
+          DO UPDATE SET "value" = "_strav_devtools_aggregates"."value" + 1,
+                        "count" = COALESCE("_strav_devtools_aggregates"."count", 0) + 1
+        `
+        break
+
+      case 'sum':
+        await this.sql`
+          INSERT INTO "_strav_devtools_aggregates" ("bucket", "period", "type", "key", "aggregate", "value", "count")
+          VALUES (${bucket}, ${period}, ${type}, ${key}, 'sum', ${value}, 1)
+          ON CONFLICT ("bucket", "period", "type", "aggregate", "key")
+          DO UPDATE SET "value" = "_strav_devtools_aggregates"."value" + ${value},
+                        "count" = COALESCE("_strav_devtools_aggregates"."count", 0) + 1
+        `
+        break
+
+      case 'max':
+        await this.sql`
+          INSERT INTO "_strav_devtools_aggregates" ("bucket", "period", "type", "key", "aggregate", "value", "count")
+          VALUES (${bucket}, ${period}, ${type}, ${key}, 'max', ${value}, 1)
+          ON CONFLICT ("bucket", "period", "type", "aggregate", "key")
+          DO UPDATE SET "value" = GREATEST("_strav_devtools_aggregates"."value", ${value}),
+                        "count" = COALESCE("_strav_devtools_aggregates"."count", 0) + 1
+        `
+        break
+
+      case 'min':
+        await this.sql`
+          INSERT INTO "_strav_devtools_aggregates" ("bucket", "period", "type", "key", "aggregate", "value", "count")
+          VALUES (${bucket}, ${period}, ${type}, ${key}, 'min', ${value}, 1)
+          ON CONFLICT ("bucket", "period", "type", "aggregate", "key")
+          DO UPDATE SET "value" = LEAST("_strav_devtools_aggregates"."value", ${value}),
+                        "count" = COALESCE("_strav_devtools_aggregates"."count", 0) + 1
+        `
+        break
+
+      case 'avg':
+        await this.sql`
+          INSERT INTO "_strav_devtools_aggregates" ("bucket", "period", "type", "key", "aggregate", "value", "count")
+          VALUES (${bucket}, ${period}, ${type}, ${key}, 'avg', ${value}, 1)
+          ON CONFLICT ("bucket", "period", "type", "aggregate", "key")
+          DO UPDATE SET "value" = (
+                          "_strav_devtools_aggregates"."value" * COALESCE("_strav_devtools_aggregates"."count", 1)
+                          + ${value}
+                        ) / (COALESCE("_strav_devtools_aggregates"."count", 1) + 1),
+                        "count" = COALESCE("_strav_devtools_aggregates"."count", 0) + 1
+        `
+        break
+    }
+  }
+}
+
+function hydrateAggregate(row: Record<string, unknown>): AggregateRecord {
+  return {
+    id: Number(row.id),
+    bucket: Number(row.bucket),
+    period: Number(row.period),
+    type: row.type as string,
+    key: row.key as string,
+    aggregate: row.aggregate as AggregateFunction,
+    value: Number(row.value),
+    count: row.count != null ? Number(row.count) : null,
+  }
+}

package/src/storage/entry_store.ts

@@ -0,0 +1,160 @@
+import type { SQL } from 'bun'
+import type { DevtoolsEntry, EntryRecord, EntryType } from '../types.ts'
+
+/**
+ * Stores and queries raw devtools entries in `_strav_devtools_entries`.
+ *
+ * Each entry represents a single recorded event (request, query, exception, etc.)
+ * and belongs to a batch (all entries from a single request/job share a batchId).
+ */
+export default class EntryStore {
+  constructor(private sql: SQL) {}
+
+  /** Create the entries table if it doesn't exist. */
+  async ensureTable(): Promise<void> {
+    await this.sql`
+      CREATE TABLE IF NOT EXISTS "_strav_devtools_entries" (
+        "id" BIGSERIAL PRIMARY KEY,
+        "uuid" UUID NOT NULL,
+        "batch_id" UUID NOT NULL,
+        "type" VARCHAR(30) NOT NULL,
+        "family_hash" VARCHAR(64),
+        "content" JSONB NOT NULL DEFAULT '{}',
+        "tags" TEXT[] NOT NULL DEFAULT '{}',
+        "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `
+
+    await this.sql`
+      CREATE INDEX IF NOT EXISTS "idx_strav_devtools_entries_batch"
+        ON "_strav_devtools_entries" ("batch_id")
+    `
+
+    await this.sql`
+      CREATE INDEX IF NOT EXISTS "idx_strav_devtools_entries_type_created"
+        ON "_strav_devtools_entries" ("type", "created_at" DESC)
+    `
+
+    await this.sql`
+      CREATE INDEX IF NOT EXISTS "idx_strav_devtools_entries_family_hash"
+        ON "_strav_devtools_entries" ("family_hash")
+        WHERE "family_hash" IS NOT NULL
+    `
+  }
+
+  /** Insert one or more entries. */
+  async store(entries: DevtoolsEntry[]): Promise<void> {
+    if (entries.length === 0) return
+
+    for (const entry of entries) {
+      const tagsLiteral = `{${entry.tags.map(t => `"${t.replace(/"/g, '\\"')}"`).join(',')}}`
+      await this.sql`
+        INSERT INTO "_strav_devtools_entries"
+          ("uuid", "batch_id", "type", "family_hash", "content", "tags", "created_at")
+        VALUES (
+          ${entry.uuid},
+          ${entry.batchId},
+          ${entry.type},
+          ${entry.familyHash},
+          ${JSON.stringify(entry.content)},
+          ${tagsLiteral}::TEXT[],
+          ${entry.createdAt}
+        )
+      `
+    }
+  }
+
+  /** List entries by type, most recent first. */
+  async list(type?: EntryType, limit = 50, offset = 0): Promise<EntryRecord[]> {
+    let rows
+
+    if (type) {
+      rows = await this.sql`
+        SELECT * FROM "_strav_devtools_entries"
+        WHERE "type" = ${type}
+        ORDER BY "created_at" DESC
+        LIMIT ${limit} OFFSET ${offset}
+      `
+    } else {
+      rows = await this.sql`
+        SELECT * FROM "_strav_devtools_entries"
+        ORDER BY "created_at" DESC
+        LIMIT ${limit} OFFSET ${offset}
+      `
+    }
+
+    return rows.map(hydrateEntry)
+  }
+
+  /** Find a single entry by UUID. */
+  async find(uuid: string): Promise<EntryRecord | null> {
+    const rows = await this.sql`
+      SELECT * FROM "_strav_devtools_entries"
+      WHERE "uuid" = ${uuid}
+      LIMIT 1
+    `
+    return rows.length > 0 ? hydrateEntry(rows[0] as Record<string, unknown>) : null
+  }
+
+  /** Find all entries in a batch, for cross-referencing. */
+  async batch(batchId: string): Promise<EntryRecord[]> {
+    const rows = await this.sql`
+      SELECT * FROM "_strav_devtools_entries"
+      WHERE "batch_id" = ${batchId}
+      ORDER BY "created_at" ASC
+    `
+    return rows.map(hydrateEntry)
+  }
+
+  /** Search entries by tag. */
+  async byTag(tag: string, limit = 50): Promise<EntryRecord[]> {
+    const rows = await this.sql`
+      SELECT * FROM "_strav_devtools_entries"
+      WHERE ${tag} = ANY("tags")
+      ORDER BY "created_at" DESC
+      LIMIT ${limit}
+    `
+    return rows.map(hydrateEntry)
+  }
+
+  /** Delete entries older than the given number of hours. */
+  async prune(hours: number): Promise<number> {
+    const rows = await this.sql`
+      DELETE FROM "_strav_devtools_entries"
+      WHERE "created_at" < NOW() - MAKE_INTERVAL(hours => ${hours})
+    `
+    return rows.count
+  }
+
+  /** Count entries, optionally filtered by type. */
+  async count(type?: EntryType): Promise<number> {
+    if (type) {
+      const rows = await this.sql`
+        SELECT COUNT(*)::int AS count FROM "_strav_devtools_entries"
+        WHERE "type" = ${type}
+      `
+      return (rows[0] as Record<string, unknown>).count as number
+    }
+
+    const rows = await this.sql`
+      SELECT COUNT(*)::int AS count FROM "_strav_devtools_entries"
+    `
+    return (rows[0] as Record<string, unknown>).count as number
+  }
+}
+
+function hydrateEntry(row: Record<string, unknown>): EntryRecord {
+  return {
+    id: Number(row.id),
+    uuid: row.uuid as string,
+    batchId: row.batch_id as string,
+    type: row.type as EntryType,
+    familyHash: (row.family_hash as string) ?? null,
+    content: (typeof row.content === 'string' ? JSON.parse(row.content) : row.content) as Record<
+      string,
+      unknown
+    >,
+    tags: (row.tags ?? []) as string[],
+    createdAt: row.created_at as Date,
+  }
+}

package/src/types.ts

@@ -0,0 +1,81 @@
+/** Types of entries that collectors produce. */
+export type EntryType =
+  | 'request'
+  | 'query'
+  | 'exception'
+  | 'log'
+  | 'job'
+  | 'cache'
+  | 'mail'
+  | 'event'
+  | 'schedule'
+
+/** A single recorded devtools entry, ready for storage. */
+export interface DevtoolsEntry {
+  uuid: string
+  batchId: string
+  type: EntryType
+  familyHash: string | null
+  content: Record<string, unknown>
+  tags: string[]
+  createdAt: Date
+}
+
+/** A row from the _strav_devtools_entries table. */
+export interface EntryRecord {
+  id: number
+  uuid: string
+  batchId: string
+  type: EntryType
+  familyHash: string | null
+  content: Record<string, unknown>
+  tags: string[]
+  createdAt: Date
+}
+
+/** Aggregate function names stored in the aggregates table. */
+export type AggregateFunction = 'count' | 'min' | 'max' | 'sum' | 'avg'
+
+/** A row from the _strav_devtools_aggregates table. */
+export interface AggregateRecord {
+  id: number
+  bucket: number
+  period: number
+  type: string
+  key: string
+  aggregate: AggregateFunction
+  value: number
+  count: number | null
+}
+
+/** Configuration shape for the devtools package. */
+export interface DevtoolsConfig {
+  enabled: boolean
+  storage: {
+    pruneAfter: number
+  }
+  collectors: {
+    request: { enabled: boolean; sizeLimit: number }
+    query: { enabled: boolean; slow: number }
+    exception: { enabled: boolean }
+    log: { enabled: boolean; level: string }
+    job: { enabled: boolean }
+  }
+  recorders: {
+    slowRequests: { enabled: boolean; threshold: number; sampleRate: number }
+    slowQueries: { enabled: boolean; threshold: number; sampleRate: number }
+  }
+}
+
+/** Collector configuration passed to each collector. */
+export interface CollectorOptions {
+  enabled: boolean
+  [key: string]: unknown
+}
+
+/** Recorder configuration passed to each recorder. */
+export interface RecorderOptions {
+  enabled: boolean
+  threshold?: number
+  sampleRate?: number
+}

package/stubs/config/devtools.ts

@@ -0,0 +1,24 @@
+import { env } from '@stravigor/core/helpers'
+
+export default {
+  /** Enable or disable devtools entirely. */
+  enabled: env('DEVTOOLS_ENABLED', 'true').bool(),
+
+  storage: {
+    /** Automatically prune entries older than this many hours. */
+    pruneAfter: 24,
+  },
+
+  collectors: {
+    request: { enabled: true, sizeLimit: 64 },
+    query: { enabled: true, slow: 100 },
+    exception: { enabled: true },
+    log: { enabled: true, level: 'debug' },
+    job: { enabled: true },
+  },
+
+  recorders: {
+    slowRequests: { enabled: true, threshold: 1000, sampleRate: 1.0 },
+    slowQueries: { enabled: true, threshold: 1000, sampleRate: 1.0 },
+  },
+}

package/stubs/schemas/devtools_aggregates.ts

@@ -0,0 +1,14 @@
+import { defineSchema, t, Archetype } from '@stravigor/core/schema'
+
+export default defineSchema('_strav_devtools_aggregates', {
+  archetype: Archetype.Event,
+  fields: {
+    bucket: t.integer().required(),
+    period: t.integer().required(),
+    type: t.varchar(30).required(),
+    key: t.text().required(),
+    aggregate: t.varchar(10).required(),
+    value: t.numeric(20, 2).required(),
+    count: t.integer().nullable(),
+  },
+})

package/stubs/schemas/devtools_entries.ts

@@ -0,0 +1,13 @@
+import { defineSchema, t, Archetype } from '@stravigor/core/schema'
+
+export default defineSchema('_strav_devtools_entries', {
+  archetype: Archetype.Event,
+  fields: {
+    uuid: t.uuid().required(),
+    batchId: t.uuid().required().index(),
+    type: t.varchar(30).required().index(),
+    familyHash: t.varchar(64).nullable().index(),
+    content: t.jsonb().required(),
+    tags: t.text().array().required(),
+  },
+})

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"]
+}