@mantiq/heartbeat 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# @mantiq/heartbeat
+
+Observability, APM, and request/query/exception tracing for MantiqJS. Self-contained dashboard at `/_heartbeat`.
+
+Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+
+## Installation
+
+```bash
+bun add @mantiq/heartbeat
+```
+
+## Documentation
+
+See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@mantiq/heartbeat",
+  "version": "0.0.1",
+  "description": "Observability, APM & queue monitoring for MantiqJS",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/heartbeat",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "directory": "packages/heartbeat"
+  },
+  "bugs": {
+    "url": "https://github.com/abdullahkhan/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "heartbeat"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@mantiq/core": "workspace:*",
+    "@mantiq/cli": "workspace:*",
+    "@mantiq/queue": "workspace:*",
+    "@mantiq/events": "workspace:*",
+    "@mantiq/database": "workspace:*",
+    "@mantiq/logging": "workspace:*"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/Heartbeat.ts

@@ -0,0 +1,152 @@
+import type { HeartbeatConfig } from './contracts/HeartbeatConfig.ts'
+import type { EntryType, PendingEntry } from './contracts/Entry.ts'
+import type { Watcher } from './contracts/Watcher.ts'
+import { HeartbeatStore } from './storage/HeartbeatStore.ts'
+import { RecordHeartbeatEntries } from './jobs/RecordHeartbeatEntries.ts'
+import { shouldSample } from './helpers/sampling.ts'
+import type { Tracer } from './tracing/Tracer.ts'
+import type { DatabaseConnection } from '@mantiq/database'
+
+const ERROR_TYPES = new Set<EntryType>(['exception'])
+
+/**
+ * Central orchestrator for the Heartbeat observability system.
+ *
+ * Manages watchers, buffers telemetry entries, and flushes them
+ * as batched queue jobs to the dedicated heartbeat queue.
+ */
+export class Heartbeat {
+  readonly store: HeartbeatStore
+  readonly config: HeartbeatConfig
+
+  private buffer: PendingEntry[] = []
+  private flushTimer: ReturnType<typeof setTimeout> | null = null
+  private watchers: Watcher[] = []
+  private pruneTimer: ReturnType<typeof setInterval> | null = null
+  private _tracer: Tracer | null = null
+
+  constructor(config: HeartbeatConfig, connection: DatabaseConnection) {
+    this.config = config
+    this.store = new HeartbeatStore(connection)
+    this.store.setupModels()
+  }
+
+  // ── Tracer ──────────────────────────────────────────────────────────────
+
+  get tracer(): Tracer | null {
+    return this._tracer
+  }
+
+  setTracer(tracer: Tracer): void {
+    this._tracer = tracer
+  }
+
+  // ── Watcher Management ──────────────────────────────────────────────────
+
+  addWatcher(watcher: Watcher): void {
+    watcher.setHeartbeat(this)
+    this.watchers.push(watcher)
+  }
+
+  getWatchers(): Watcher[] {
+    return this.watchers
+  }
+
+  // ── Entry Recording ─────────────────────────────────────────────────────
+
+  /**
+   * Record a telemetry entry. Called by watchers.
+   * Entries are buffered and flushed as batched queue jobs.
+   */
+  record(type: EntryType, content: Record<string, any>, tags?: string[]): void {
+    if (!this.config.enabled) return
+
+    const isError = ERROR_TYPES.has(type)
+    if (!shouldSample(this.config, isError)) return
+
+    const entry: PendingEntry = {
+      type,
+      content,
+      tags,
+      requestId: this._tracer?.currentRequestId() ?? null,
+      createdAt: Date.now(),
+    }
+
+    this.buffer.push(entry)
+
+    if (this.buffer.length >= this.config.queue.batchSize) {
+      this.flush()
+    } else if (!this.flushTimer) {
+      this.flushTimer = setTimeout(() => this.flush(), this.config.queue.flushInterval)
+    }
+  }
+
+  /**
+   * Flush the entry buffer by dispatching a RecordHeartbeatEntries job.
+   * Falls back to direct store insert if the queue is unavailable.
+   */
+  flush(): void {
+    if (this.buffer.length === 0) return
+
+    const entries = this.buffer.splice(0)
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer)
+      this.flushTimer = null
+    }
+
+    // Check if queue system is available — if not, write directly (async, fire-and-forget)
+    let queueAvailable = false
+    try {
+      const { getQueueManager } = require('@mantiq/queue')
+      getQueueManager() // throws if not initialized
+      queueAvailable = true
+    } catch {
+      // Queue not available
+    }
+
+    if (queueAvailable) {
+      try {
+        const { dispatch } = require('@mantiq/queue')
+        dispatch(new RecordHeartbeatEntries(entries))
+          .onQueue(this.config.queue.queue)
+          .onConnection(this.config.queue.connection)
+          .send()
+          .catch(() => {
+            this.store.insertEntries(entries).catch(() => { /* swallow */ })
+          })
+      } catch {
+        this.store.insertEntries(entries).catch(() => { /* swallow */ })
+      }
+    } else {
+      // Direct write — async fire-and-forget fallback
+      this.store.insertEntries(entries).catch(() => { /* swallow */ })
+    }
+  }
+
+  // ── Pruning ─────────────────────────────────────────────────────────────
+
+  startPruning(): void {
+    if (this.pruneTimer) return
+    this.pruneTimer = setInterval(() => {
+      this.store.prune(this.config.storage.retention).catch(() => { /* swallow */ })
+    }, this.config.storage.pruneInterval * 1000)
+  }
+
+  stopPruning(): void {
+    if (this.pruneTimer) {
+      clearInterval(this.pruneTimer)
+      this.pruneTimer = null
+    }
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────────────────────
+
+  shutdown(): void {
+    this.flush()
+    this.stopPruning()
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer)
+      this.flushTimer = null
+    }
+  }
+}

package/src/HeartbeatServiceProvider.ts

@@ -0,0 +1,211 @@
+import { ServiceProvider, ConfigRepository, RouterImpl, HttpKernel, CacheManager } from '@mantiq/core'
+import type { EventDispatcher } from '@mantiq/core'
+import { DatabaseManager, SQLiteConnection } from '@mantiq/database'
+import type { HeartbeatConfig } from './contracts/HeartbeatConfig.ts'
+import { DEFAULT_CONFIG } from './contracts/HeartbeatConfig.ts'
+import { Heartbeat } from './Heartbeat.ts'
+import { HEARTBEAT, setHeartbeat } from './helpers/heartbeat.ts'
+import { Tracer } from './tracing/Tracer.ts'
+import { MetricsCollector } from './metrics/MetricsCollector.ts'
+import { RequestMetrics } from './metrics/RequestMetrics.ts'
+import { QueueMetrics } from './metrics/QueueMetrics.ts'
+import { SystemMetrics } from './metrics/SystemMetrics.ts'
+import { RequestWatcher } from './watchers/RequestWatcher.ts'
+import { QueryWatcher } from './watchers/QueryWatcher.ts'
+import { ExceptionWatcher } from './watchers/ExceptionWatcher.ts'
+import { CacheWatcher } from './watchers/CacheWatcher.ts'
+import { JobWatcher } from './watchers/JobWatcher.ts'
+import { EventWatcher } from './watchers/EventWatcher.ts'
+import { ModelWatcher } from './watchers/ModelWatcher.ts'
+import { LogWatcher } from './watchers/LogWatcher.ts'
+import { ScheduleWatcher } from './watchers/ScheduleWatcher.ts'
+import { CreateHeartbeatTables } from './migrations/CreateHeartbeatTables.ts'
+import { DashboardController } from './dashboard/DashboardController.ts'
+import { HeartbeatMiddleware } from './middleware/HeartbeatMiddleware.ts'
+import type { Watcher } from './contracts/Watcher.ts'
+import { SimpleEventBus } from './helpers/SimpleEventBus.ts'
+
+export class HeartbeatServiceProvider extends ServiceProvider {
+  override register(): void {
+    this.app.singleton(Heartbeat, (c) => {
+      const config = c.make(ConfigRepository).get<HeartbeatConfig>('heartbeat', DEFAULT_CONFIG)
+
+      // Resolve connection — undefined means use app's default database connection
+      const dbManager = c.make(DatabaseManager)
+      const connection = dbManager.connection(config.storage.connection)
+
+      const heartbeat = new Heartbeat(config, connection)
+      setHeartbeat(heartbeat)
+      return heartbeat
+    })
+
+    this.app.alias(Heartbeat, HEARTBEAT)
+
+    // Singletons for tracing and metrics
+    this.app.singleton(Tracer, () => new Tracer())
+    this.app.singleton(MetricsCollector, () => new MetricsCollector())
+  }
+
+  override async boot(): Promise<void> {
+    const heartbeat = this.app.make(Heartbeat)
+    const config = heartbeat.config
+
+    if (!config.enabled) return
+
+    // Run heartbeat migration to ensure tables exist
+    const migration = new CreateHeartbeatTables()
+    const connection = heartbeat.store.getConnection()
+    await migration.up(connection.schema(), connection)
+
+    // Set up tracer
+    const tracer = this.app.make(Tracer)
+    tracer.setStore(heartbeat.store)
+    heartbeat.setTracer(tracer)
+
+    // Set up metrics
+    const metrics = this.app.make(MetricsCollector)
+    metrics.setStore(heartbeat.store)
+
+    this.app.instance(RequestMetrics, new RequestMetrics(metrics))
+    this.app.instance(QueueMetrics, new QueueMetrics(metrics))
+    this.app.instance(SystemMetrics, new SystemMetrics(metrics))
+
+    // Set up event bus for watcher event listeners
+    const eventBus = this.setupEventBus()
+
+    // Register watchers
+    const requestWatcher = this.registerWatchers(heartbeat, config, eventBus)
+
+    // Start periodic systems
+    metrics.start()
+    heartbeat.startPruning()
+
+    const systemMetrics = this.app.make(SystemMetrics)
+    systemMetrics.start()
+
+    // Register HeartbeatMiddleware as first global middleware
+    this.registerMiddleware(heartbeat, tracer, requestWatcher, metrics)
+
+    // Register dashboard routes
+    if (config.dashboard.enabled) {
+      this.registerDashboardRoutes(heartbeat, metrics, config)
+    }
+  }
+
+  private registerMiddleware(
+    heartbeat: Heartbeat,
+    tracer: Tracer,
+    requestWatcher: RequestWatcher | null,
+    metrics: MetricsCollector,
+  ): void {
+    const kernel = this.app.make(HttpKernel)
+
+    // Register the middleware instance in the container
+    const middleware = new HeartbeatMiddleware(heartbeat, tracer, requestWatcher, metrics)
+    this.app.instance(HeartbeatMiddleware, middleware)
+
+    // Register alias and prepend to global middleware
+    kernel.registerMiddleware('heartbeat', HeartbeatMiddleware)
+    kernel.prependGlobalMiddleware('heartbeat')
+  }
+
+  private registerDashboardRoutes(heartbeat: Heartbeat, metrics: MetricsCollector, config: HeartbeatConfig): void {
+    const router = this.app.make(RouterImpl)
+    const basePath = config.dashboard.path
+    const env = this.app.make(ConfigRepository).get<string>('app.env', 'production')
+    const controller = new DashboardController(heartbeat.store, metrics, basePath)
+
+    // Register catch-all route for the dashboard
+    // The DashboardController handles sub-routing internally
+    router.any(`${basePath}`, (request) => {
+      return this.gateDashboard(env, request, controller)
+    })
+
+    router.any(`${basePath}/*`, (request) => {
+      return this.gateDashboard(env, request, controller)
+    })
+  }
+
+  private async gateDashboard(env: string, request: any, controller: DashboardController): Promise<Response> {
+    // Gate: allow in development/local/testing, block in production
+    if (env !== 'development' && env !== 'local' && env !== 'testing') {
+      return new Response('Forbidden — Heartbeat dashboard is disabled in production.', {
+        status: 403,
+        headers: { 'Content-Type': 'text/plain' },
+      })
+    }
+
+    return controller.handle(request.raw())
+  }
+
+  /**
+   * Set up an event bus for watchers.
+   *
+   * If @mantiq/events Dispatcher is already in the container, reuse it.
+   * Otherwise, create a SimpleEventBus and hook it into SQLiteConnection,
+   * CacheManager, and RouterImpl so events flow even without the events package.
+   */
+  private setupEventBus(): SimpleEventBus {
+    // Check if a full dispatcher already exists
+    const existingDispatcher = SQLiteConnection._dispatcher
+    if (existingDispatcher && typeof (existingDispatcher as any).on === 'function') {
+      // Wrap the existing dispatcher's on/onAny into our SimpleEventBus
+      // so watchers register on the same dispatcher that fires events
+      const bus = new SimpleEventBus()
+      // Proxy: listeners registered on our bus also get registered on the real dispatcher
+      const realOn = (existingDispatcher as any).on.bind(existingDispatcher)
+      const realOnAny = (existingDispatcher as any).onAny?.bind(existingDispatcher)
+      const origOn = bus.on.bind(bus)
+      const origOnAny = bus.onAny.bind(bus)
+      bus.on = (eventClass: any, handler: any) => { origOn(eventClass, handler); realOn(eventClass, handler) }
+      if (realOnAny) {
+        bus.onAny = (handler: any) => { origOnAny(handler); realOnAny(handler) }
+      }
+      return bus
+    }
+
+    // No existing dispatcher — create our own and hook it into framework statics
+    const bus = new SimpleEventBus()
+    SQLiteConnection._dispatcher = bus as any
+    CacheManager._dispatcher = bus as any
+    RouterImpl._dispatcher = bus as any
+    return bus
+  }
+
+  /**
+   * Register watchers and return the RequestWatcher instance (if enabled).
+   */
+  private registerWatchers(heartbeat: Heartbeat, config: HeartbeatConfig, eventBus: SimpleEventBus): RequestWatcher | null {
+    let requestWatcher: RequestWatcher | null = null
+
+    const watcherMap: Array<[keyof HeartbeatConfig['watchers'], Watcher]> = [
+      ['request', new RequestWatcher()],
+      ['query', new QueryWatcher()],
+      ['exception', new ExceptionWatcher()],
+      ['cache', new CacheWatcher()],
+      ['job', new JobWatcher()],
+      ['event', new EventWatcher()],
+      ['model', new ModelWatcher()],
+      ['log', new LogWatcher()],
+      ['schedule', new ScheduleWatcher()],
+    ]
+
+    const on = eventBus.on.bind(eventBus)
+    const onAny = eventBus.onAny.bind(eventBus)
+
+    for (const [key, watcher] of watcherMap) {
+      const watcherConfig = config.watchers[key]
+      if (!watcherConfig.enabled) continue
+
+      watcher.configure(watcherConfig as Record<string, any>)
+      heartbeat.addWatcher(watcher)
+      watcher.register(on, onAny)
+
+      if (key === 'request') {
+        requestWatcher = watcher as RequestWatcher
+      }
+    }
+
+    return requestWatcher
+  }
+}

package/src/commands/InstallCommand.ts

@@ -0,0 +1,164 @@
+import { Command } from '@mantiq/cli'
+import type { ParsedArgs } from '@mantiq/cli'
+import { existsSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/**
+ * Publishes the Heartbeat config and service provider into the app.
+ *
+ * Usage:
+ *   bun run mantiq.ts heartbeat:install
+ *
+ * Published files:
+ *   config/heartbeat.ts          — Heartbeat configuration
+ *   app/Providers/HeartbeatServiceProvider.ts — App-level provider (extends package provider)
+ */
+export class InstallCommand extends Command {
+  override name = 'heartbeat:install'
+  override description = 'Install the Heartbeat observability package'
+
+  override async handle(_args: ParsedArgs): Promise<number> {
+    this.io.heading('Installing Heartbeat')
+    this.io.newLine()
+
+    const basePath = process.cwd()
+    let published = 0
+
+    // 1. Publish config
+    published += await this.publishFile(
+      `${basePath}/config/heartbeat.ts`,
+      CONFIG_STUB,
+      'config/heartbeat.ts',
+    )
+
+    // 2. Publish service provider
+    published += await this.publishFile(
+      `${basePath}/app/Providers/HeartbeatServiceProvider.ts`,
+      PROVIDER_STUB,
+      'app/Providers/HeartbeatServiceProvider.ts',
+    )
+
+    this.io.newLine()
+
+    if (published > 0) {
+      this.io.success(`Published ${published} file(s).`)
+    } else {
+      this.io.info('All files already exist. No changes made.')
+    }
+
+    this.io.newLine()
+    this.io.info('Next steps:')
+    this.io.twoColumn('  1.', 'Register the provider in your app bootstrap:')
+    this.io.newLine()
+    this.io.line("     import { HeartbeatServiceProvider } from './app/Providers/HeartbeatServiceProvider.ts'")
+    this.io.newLine()
+    this.io.line("     await app.registerProviders([..., HeartbeatServiceProvider])")
+    this.io.newLine()
+    this.io.twoColumn('  2.', `Visit ${this.io.cyan('/_heartbeat')} to view the dashboard.`)
+    this.io.newLine()
+
+    return 0
+  }
+
+  private async publishFile(filePath: string, content: string, displayPath: string): Promise<number> {
+    if (existsSync(filePath)) {
+      this.io.warn(`${displayPath} already exists, skipping.`)
+      return 0
+    }
+
+    mkdirSync(dirname(filePath), { recursive: true })
+    await Bun.write(filePath, content)
+    this.io.success(`Published ${displayPath}`)
+    return 1
+  }
+}
+
+// ── Stubs ──────────────────────────────────────────────────────────────────────
+
+const CONFIG_STUB = `import { env } from '@mantiq/core'
+
+export default {
+  /**
+   * Master switch — set to false to completely disable Heartbeat.
+   */
+  enabled: env('HEARTBEAT_ENABLED', true),
+
+  /**
+   * Storage settings.
+   *
+   * connection: The database connection to use. Leave undefined to use the
+   *             app's default connection. Set a string to use a dedicated one.
+   * retention:  How long to keep entries (seconds). Default 24h.
+   * pruneInterval: How often to prune old entries (seconds). Default 5 min.
+   */
+  storage: {
+    connection: undefined,
+    retention: 86_400,
+    pruneInterval: 300,
+  },
+
+  /**
+   * Queue settings for non-blocking telemetry writes.
+   *
+   * In development (sync driver), jobs execute immediately.
+   * In production, use an async driver so telemetry doesn't block requests.
+   */
+  queue: {
+    connection: 'sync',
+    queue: 'heartbeat',
+    batchSize: 50,
+    flushInterval: 1_000,
+  },
+
+  /**
+   * Toggle individual watchers and configure their behaviour.
+   */
+  watchers: {
+    request:   { enabled: true, slow_threshold: 1_000, ignore: [] },
+    query:     { enabled: true, slow_threshold: 100, detect_n_plus_one: true },
+    exception: { enabled: true, ignore: [] },
+    cache:     { enabled: true },
+    job:       { enabled: true },
+    event:     { enabled: true, ignore: [] },
+    model:     { enabled: true },
+    log:       { enabled: true, level: 'debug' },
+    schedule:  { enabled: true },
+  },
+
+  /**
+   * Distributed tracing via AsyncLocalStorage.
+   */
+  tracing: { enabled: true, propagate: true },
+
+  /**
+   * Sampling — reduce volume in high-traffic production environments.
+   * rate: 1.0 = record everything, 0.1 = record 10% of requests.
+   */
+  sampling: { rate: 1.0, always_sample_errors: true },
+
+  /**
+   * Dashboard settings.
+   *
+   * path: The URL prefix where the dashboard is served.
+   * enabled: Set to false to disable the dashboard entirely.
+   */
+  dashboard: {
+    path: '/_heartbeat',
+    middleware: [],
+    enabled: true,
+  },
+}
+`
+
+const PROVIDER_STUB = `import { HeartbeatServiceProvider as BaseProvider } from '@mantiq/heartbeat'
+
+/**
+ * App-level Heartbeat service provider.
+ *
+ * Extend the base provider to customise authorisation, add custom watchers,
+ * or hook into Heartbeat lifecycle events.
+ */
+export class HeartbeatServiceProvider extends BaseProvider {
+  //
+}
+`