apiforgejs 0.1.0

package/src/database.js

@@ -0,0 +1,298 @@
+'use strict';
+
+// Suppress the built-in SQLite experimental warning before the first require —
+// we intentionally depend on this API and the warning adds noise to user logs.
+process.on('warning', function _sqLiteWarnFilter(w) {
+  if (w.name === 'ExperimentalWarning' && w.message.startsWith('SQLite')) {
+    process.off('warning', _sqLiteWarnFilter);
+  }
+});
+
+// node:sqlite is built into Node.js 22.5+ — no native addon required
+const { DatabaseSync } = require('node:sqlite');
+
+class ApiForgeDatabase {
+  constructor(dbPath) {
+    this.db = new DatabaseSync(dbPath);
+    this._init();
+  }
+
+  _init() {
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec("PRAGMA synchronous = NORMAL");
+
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS known_routes (
+        route      TEXT NOT NULL,
+        method     TEXT NOT NULL,
+        first_seen INTEGER NOT NULL DEFAULT (unixepoch()),
+        PRIMARY KEY (route, method)
+      );
+
+      CREATE TABLE IF NOT EXISTS api_metrics (
+        id          INTEGER PRIMARY KEY AUTOINCREMENT,
+        bucket_ts   INTEGER NOT NULL,
+        route       TEXT NOT NULL,
+        method      TEXT NOT NULL,
+        env         TEXT NOT NULL DEFAULT 'production',
+        release_tag TEXT,
+        status_2xx  INTEGER NOT NULL DEFAULT 0,
+        status_4xx  INTEGER NOT NULL DEFAULT 0,
+        status_5xx  INTEGER NOT NULL DEFAULT 0,
+        total_calls INTEGER NOT NULL DEFAULT 0,
+        lat_p50     REAL,
+        lat_p90     REAL,
+        lat_p99     REAL,
+        lat_min     REAL,
+        lat_max     REAL
+      );
+      CREATE INDEX IF NOT EXISTS idx_route_ts  ON api_metrics (route, method, bucket_ts);
+      CREATE INDEX IF NOT EXISTS idx_bucket_ts ON api_metrics (bucket_ts);
+      CREATE INDEX IF NOT EXISTS idx_release   ON api_metrics (release_tag) WHERE release_tag IS NOT NULL;
+    `);
+
+    this._stmtInsert = this.db.prepare(`
+      INSERT INTO api_metrics
+        (bucket_ts, route, method, env, release_tag,
+         status_2xx, status_4xx, status_5xx, total_calls,
+         lat_p50, lat_p90, lat_p99, lat_min, lat_max)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    this._begin    = this.db.prepare('BEGIN');
+    this._commit   = this.db.prepare('COMMIT');
+    this._rollback = this.db.prepare('ROLLBACK');
+  }
+
+  insertBatch(rows) {
+    this._begin.run();
+    try {
+      for (const r of rows) {
+        this._stmtInsert.run(
+          r.bucket_ts, r.route, r.method, r.env, r.release_tag ?? null,
+          r.status_2xx, r.status_4xx, r.status_5xx, r.total_calls,
+          r.lat_p50, r.lat_p90, r.lat_p99, r.lat_min, r.lat_max
+        );
+      }
+      this._commit.run();
+    } catch (err) {
+      this._rollback.run();
+      throw err;
+    }
+  }
+
+  getSummary() {
+    const since24h = nowSec() - 86_400;
+    const since7d  = nowSec() - 604_800;
+
+    const recent = this.db.prepare(`
+      SELECT
+        SUM(total_calls) as calls_total,
+        SUM(status_2xx)  as calls_2xx,
+        SUM(status_4xx)  as calls_4xx,
+        SUM(status_5xx)  as calls_5xx,
+        AVG(lat_p90)     as avg_p90,
+        AVG(lat_p99)     as avg_p99
+      FROM api_metrics WHERE bucket_ts >= ?
+    `).get(since24h);
+
+    const baseline = this.db.prepare(`
+      SELECT AVG(lat_p90) as baseline_p90
+      FROM api_metrics WHERE bucket_ts >= ? AND bucket_ts < ?
+    `).get(since7d, since24h);
+
+    const activeRoutes = this.db.prepare(`
+      SELECT COUNT(DISTINCT route || '|' || method) as n
+      FROM api_metrics WHERE bucket_ts >= ?
+    `).get(since24h);
+
+    const totalRoutes = this.db.prepare(`
+      SELECT COUNT(DISTINCT route || '|' || method) as n
+      FROM api_metrics
+    `).get();
+
+    return {
+      recent,
+      baseline,
+      activeRoutes: activeRoutes?.n ?? 0,
+      totalRoutes: totalRoutes?.n ?? 0,
+    };
+  }
+
+  getRoutes(hours = 24) {
+    const since = nowSec() - hours * 3600;
+    return this.db.prepare(`
+      SELECT
+        route, method,
+        SUM(total_calls) as calls,
+        SUM(status_2xx)  as calls_2xx,
+        SUM(status_4xx)  as calls_4xx,
+        SUM(status_5xx)  as calls_5xx,
+        AVG(lat_p50)     as p50,
+        AVG(lat_p90)     as p90,
+        AVG(lat_p99)     as p99,
+        MAX(lat_max)     as lat_max
+      FROM api_metrics
+      WHERE bucket_ts >= ?
+      GROUP BY route, method
+      ORDER BY calls DESC
+      LIMIT 50
+    `).all(since);
+  }
+
+  getTimeSeries(route, method, hours = 24) {
+    const since = nowSec() - hours * 3600;
+    return this.db.prepare(`
+      SELECT
+        bucket_ts,
+        SUM(total_calls) as calls,
+        AVG(lat_p50) as p50,
+        AVG(lat_p90) as p90,
+        AVG(lat_p99) as p99,
+        SUM(status_5xx) as errors
+      FROM api_metrics
+      WHERE route = ? AND method = ? AND bucket_ts >= ?
+      GROUP BY bucket_ts
+      ORDER BY bucket_ts ASC
+    `).all(route, method, since);
+  }
+
+  getDeadCandidates(inactiveDays = 21) {
+    const cutoff = nowSec() - inactiveDays * 86_400;
+    return this.db.prepare(`
+      SELECT route, method, MAX(bucket_ts) as last_seen
+      FROM api_metrics
+      GROUP BY route, method
+      HAVING last_seen < ?
+      ORDER BY last_seen ASC
+    `).all(cutoff);
+  }
+
+  getReleaseComparison() {
+    const latestRelease = this.db.prepare(`
+      SELECT release_tag, MIN(bucket_ts) as release_ts
+      FROM api_metrics
+      WHERE release_tag IS NOT NULL AND release_tag != ''
+      GROUP BY release_tag
+      ORDER BY release_ts DESC
+      LIMIT 1
+    `).get();
+
+    if (!latestRelease) return null;
+
+    const { release_tag, release_ts } = latestRelease;
+    const windowBefore = release_ts - 86_400;
+
+    const before = this.db.prepare(`
+      SELECT route, method, AVG(lat_p90) as avg_p90, SUM(total_calls) as calls
+      FROM api_metrics
+      WHERE bucket_ts >= ? AND bucket_ts < ?
+      GROUP BY route, method
+    `).all(windowBefore, release_ts);
+
+    const after = this.db.prepare(`
+      SELECT route, method, AVG(lat_p90) as avg_p90, SUM(total_calls) as calls
+      FROM api_metrics
+      WHERE bucket_ts >= ? AND release_tag = ?
+      GROUP BY route, method
+    `).all(release_ts, release_tag);
+
+    return { release_tag, release_ts, before, after };
+  }
+
+  getLatencyAnomalyData() {
+    const since1h = nowSec() - 3_600;
+    const since7d  = nowSec() - 604_800;
+
+    const recent = this.db.prepare(`
+      SELECT route, method, AVG(lat_p99) as avg_p99
+      FROM api_metrics
+      WHERE bucket_ts >= ?
+      GROUP BY route, method
+    `).all(since1h);
+
+    const baselineRows = this.db.prepare(`
+      SELECT route, method, lat_p99
+      FROM api_metrics
+      WHERE bucket_ts >= ? AND bucket_ts < ? AND lat_p99 IS NOT NULL
+    `).all(since7d, since1h);
+
+    return { recent, baselineRows };
+  }
+
+  // Called once at startup with all routes discovered in the Express router
+  upsertKnownRoutes(routes) {
+    const stmt = this.db.prepare(`
+      INSERT INTO known_routes (route, method) VALUES (?, ?)
+      ON CONFLICT (route, method) DO NOTHING
+    `);
+    this._begin.run();
+    try {
+      for (const r of routes) stmt.run(r.route, r.method);
+      this._commit.run();
+    } catch (err) {
+      this._rollback.run();
+      throw err;
+    }
+  }
+
+  // Routes declared in Express but with zero traffic ever recorded
+  getUntrackedRoutes() {
+    return this.db.prepare(`
+      SELECT k.route, k.method, k.first_seen
+      FROM known_routes k
+      WHERE NOT EXISTS (
+        SELECT 1 FROM api_metrics m
+        WHERE m.route = k.route AND m.method = k.method
+      )
+      ORDER BY k.method, k.route
+    `).all();
+  }
+
+  // All known routes with their traffic status (for dashboard routes table)
+  getKnownRoutes() {
+    return this.db.prepare(`
+      SELECT route, method FROM known_routes ORDER BY method, route
+    `).all();
+  }
+
+  getReleases() {
+    return this.db.prepare(`
+      SELECT release_tag,
+             MIN(bucket_ts) as release_ts,
+             COUNT(DISTINCT route || '|' || method) as routes_affected
+      FROM api_metrics
+      WHERE release_tag IS NOT NULL AND release_tag != ''
+      GROUP BY release_tag
+      ORDER BY release_ts DESC
+      LIMIT 20
+    `).all();
+  }
+
+  getGlobalTimeSeries(hours = 24) {
+    const since = nowSec() - hours * 3600;
+    return this.db.prepare(`
+      SELECT
+        bucket_ts,
+        SUM(total_calls) as calls,
+        AVG(lat_p50) as p50,
+        AVG(lat_p90) as p90,
+        AVG(lat_p99) as p99,
+        SUM(status_5xx) as errors
+      FROM api_metrics
+      WHERE bucket_ts >= ?
+      GROUP BY bucket_ts
+      ORDER BY bucket_ts ASC
+    `).all(since);
+  }
+
+  close() {
+    this.db.close();
+  }
+}
+
+function nowSec() {
+  return Math.floor(Date.now() / 1000);
+}
+
+module.exports = { ApiForgeDatabase };

package/src/index.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const { createInterceptor } = require('./interceptor');
+const { Aggregator } = require('./aggregator');
+const { LocalTransport } = require('./transport');
+const { ApiForgeDatabase } = require('./database');
+const { startDashboard } = require('./dashboard');
+
+/**
+ * APIForge Express middleware factory.
+ *
+ * @param {object} options
+ * @param {'local'} options.mode          - Storage mode. Only 'local' (SQLite) in v0.x.
+ * @param {string}  [options.dbPath]      - SQLite file path. Default: '.apiforge.db'
+ * @param {number}  [options.dashboardPort] - Dashboard port. Default: 4242. Set to 0 to disable.
+ * @param {number}  [options.flushInterval] - Aggregation flush interval in ms. Default: 60000.
+ * @param {string}  [options.env]         - Environment label. Default: NODE_ENV or 'production'.
+ * @param {string}  [options.release]     - Release/version tag for deployment correlation.
+ * @param {string}  [options.service]     - Service name for multi-service setups.
+ * @param {number}  [options.sampling]    - Sample rate 0.0–1.0. Default: 1.0.
+ * @param {string[]}[options.ignorePaths] - Paths to skip. Default: ['/favicon.ico'].
+ */
+function apiforge(options = {}) {
+  if (options.mode && options.mode !== 'local') {
+    throw new Error(`[apiforgejs] mode '${options.mode}' is not yet supported. Use 'local'.`);
+  }
+
+  const config = {
+    mode: 'local',
+    dbPath: options.dbPath ?? '.apiforge.db',
+    dashboardPort: options.dashboardPort !== undefined ? options.dashboardPort : 4242,
+    flushInterval: options.flushInterval ?? 60_000,
+    env: options.env ?? process.env.NODE_ENV ?? 'production',
+    release: options.release ?? process.env.APP_VERSION ?? null,
+    service: options.service ?? 'default',
+    sampling: options.sampling ?? 1.0,
+    ignorePaths: options.ignorePaths ?? ['/favicon.ico'],
+  };
+
+  const db = new ApiForgeDatabase(config.dbPath);
+  const transport = new LocalTransport(db);
+  const aggregator = new Aggregator(transport, config.flushInterval);
+
+  aggregator.start();
+
+  if (config.dashboardPort) {
+    startDashboard(db, config.dashboardPort);
+  }
+
+  const middleware = createInterceptor(aggregator, db, config);
+
+  middleware.shutdown = () => {
+    aggregator.stop();
+    db.close();
+  };
+
+  return middleware;
+}
+
+module.exports = { apiforge };

package/src/insights.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const DEAD_ENDPOINT_DAYS = 21;
+const REGRESSION_THRESHOLD = 0.20; // 20% worse P90 triggers regression insight
+const ANOMALY_Z_THRESHOLD = 2.5;   // Z-score threshold for latency anomaly
+
+function getInsights(db) {
+  const insights = [];
+
+  try {
+    insights.push(...detectLatencyAnomalies(db));
+  } catch (_) {}
+
+  try {
+    insights.push(...detectDeadEndpoints(db));
+  } catch (_) {}
+
+  try {
+    insights.push(...detectReleaseRegressions(db));
+  } catch (_) {}
+
+  try {
+    insights.push(...detectUntrackedRoutes(db));
+  } catch (_) {}
+
+  return insights;
+}
+
+function detectUntrackedRoutes(db) {
+  const untracked = db.getUntrackedRoutes();
+  return untracked.map((r) => ({
+    type: 'UNTRACKED',
+    severity: 'info',
+    route: r.route,
+    method: r.method,
+    message: `\`${r.method} ${r.route}\` est déclaré dans l'application mais n'a reçu aucune requête depuis le début du monitoring.`,
+    data: { first_seen_ts: r.first_seen },
+  }));
+}
+
+function detectLatencyAnomalies(db) {
+  const { recent, baselineRows } = db.getLatencyAnomalyData();
+  if (recent.length === 0 || baselineRows.length === 0) return [];
+
+  // Build baseline stats per route+method
+  const baselineMap = new Map();
+  for (const row of baselineRows) {
+    const key = `${row.method}|${row.route}`;
+    if (!baselineMap.has(key)) baselineMap.set(key, []);
+    baselineMap.get(key).push(row.lat_p99);
+  }
+
+  const insights = [];
+  for (const r of recent) {
+    const key = `${r.method}|${r.route}`;
+    const samples = baselineMap.get(key);
+    if (!samples || samples.length < 5) continue; // not enough baseline data
+
+    const mean = samples.reduce((a, b) => a + b, 0) / samples.length;
+    const variance = samples.reduce((s, v) => s + (v - mean) ** 2, 0) / samples.length;
+    const stdev = Math.sqrt(variance);
+
+    if (stdev === 0) continue;
+    const z = (r.avg_p99 - mean) / stdev;
+
+    if (z >= ANOMALY_Z_THRESHOLD) {
+      insights.push({
+        type: 'ANOMALY',
+        severity: 'warning',
+        route: r.route,
+        method: r.method,
+        message: `La latence P99 de \`${r.method} ${r.route}\` est anormalement élevée cette heure (${fmt(r.avg_p99)} vs moyenne ${fmt(mean)} — Z-score ${z.toFixed(1)}).`,
+        data: { current_p99: r.avg_p99, baseline_p99: mean, z_score: z },
+      });
+    }
+  }
+
+  return insights;
+}
+
+function detectDeadEndpoints(db) {
+  const candidates = db.getDeadCandidates(DEAD_ENDPOINT_DAYS);
+  return candidates.map((row) => {
+    const daysSince = Math.floor((Date.now() / 1000 - row.last_seen) / 86_400);
+    return {
+      type: 'DEAD',
+      severity: 'info',
+      route: row.route,
+      method: row.method,
+      message: `\`${row.method} ${row.route}\` n'a reçu aucune requête depuis ${daysSince} jours. Candidat à la déprécation.`,
+      data: { last_seen_ts: row.last_seen, inactive_days: daysSince },
+    };
+  });
+}
+
+function detectReleaseRegressions(db) {
+  const comparison = db.getReleaseComparison();
+  if (!comparison) return [];
+
+  const { release_tag, before, after } = comparison;
+
+  const beforeMap = new Map(before.map((r) => [`${r.method}|${r.route}`, r]));
+  const insights = [];
+
+  for (const a of after) {
+    const key = `${a.method}|${a.route}`;
+    const b = beforeMap.get(key);
+    if (!b || b.avg_p90 === null || a.avg_p90 === null || b.avg_p90 === 0) continue;
+
+    const delta = (a.avg_p90 - b.avg_p90) / b.avg_p90;
+
+    if (delta >= REGRESSION_THRESHOLD) {
+      insights.push({
+        type: 'PERF',
+        severity: 'error',
+        route: a.route,
+        method: a.method,
+        message: `La latence P90 de \`${a.method} ${a.route}\` a augmenté de ${pct(delta)} depuis le déploiement ${release_tag}. Avant : ${fmt(b.avg_p90)} — Après : ${fmt(a.avg_p90)}.`,
+        data: {
+          release: release_tag,
+          before_p90: b.avg_p90,
+          after_p90: a.avg_p90,
+          delta_pct: delta * 100,
+        },
+      });
+    } else if (delta <= -REGRESSION_THRESHOLD) {
+      insights.push({
+        type: 'OK',
+        severity: 'success',
+        route: a.route,
+        method: a.method,
+        message: `Le déploiement ${release_tag} a amélioré \`${a.method} ${a.route}\` de ${pct(-delta)}. Avant : ${fmt(b.avg_p90)} — Après : ${fmt(a.avg_p90)}.`,
+        data: {
+          release: release_tag,
+          before_p90: b.avg_p90,
+          after_p90: a.avg_p90,
+          delta_pct: delta * 100,
+        },
+      });
+    }
+  }
+
+  return insights;
+}
+
+function computeHealthScore(db) {
+  try {
+    const { recent, baseline, activeRoutes, totalRoutes } = db.getSummary();
+
+    const total = recent?.calls_total || 0;
+    if (total === 0) return null;
+
+    // Availability: 2xx rate (weight 30%)
+    const availability = Math.min(100, ((recent.calls_2xx || 0) / total) * 100);
+
+    // Performance: P90 vs 7d baseline (weight 30%)
+    let performance = 100;
+    if (baseline?.baseline_p90 && recent?.avg_p90 && baseline.baseline_p90 > 0) {
+      const ratio = recent.avg_p90 / baseline.baseline_p90;
+      performance = Math.max(0, Math.min(100, 100 - (ratio - 1) * 100));
+    }
+
+    // Stability: 100 by default at MVP (no complex drift detection)
+    const stability = 100;
+
+    // Quality: active routes vs total ever seen (weight 15%)
+    const quality = totalRoutes > 0 ? Math.min(100, (activeRoutes / totalRoutes) * 100) : 100;
+
+    const score = availability * 0.30 + performance * 0.30 + stability * 0.25 + quality * 0.15;
+    return Math.round(score);
+  } catch (_) {
+    return null;
+  }
+}
+
+function fmt(ms) {
+  if (ms == null) return 'N/A';
+  return `${Math.round(ms)}ms`;
+}
+
+function pct(ratio) {
+  return `${Math.round(ratio * 100)}%`;
+}
+
+module.exports = { getInsights, computeHealthScore };

package/src/interceptor.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const NUMERIC_SEGMENT = /\/\d+/g;
+const UUID_SEGMENT = /\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+
+function normalizePath(path) {
+  return path.replace(UUID_SEGMENT, '/:uuid').replace(NUMERIC_SEGMENT, '/:id');
+}
+
+// Walk Express router stack and return all declared routes
+function extractExpressRoutes(router, prefix = '') {
+  const routes = [];
+  if (!router?.stack) return routes;
+
+  for (const layer of router.stack) {
+    if (layer.route) {
+      const path = prefix + layer.route.path;
+      const methods = Object.keys(layer.route.methods)
+        .filter(m => m !== '_all' && layer.route.methods[m])
+        .map(m => m.toUpperCase());
+      for (const method of methods) {
+        routes.push({ method, route: path || '/' });
+      }
+    } else if (layer.handle?.stack) {
+      // Nested router mounted via app.use(prefix, router)
+      const subPrefix = prefix + routerLayerPath(layer);
+      extractExpressRoutes(layer.handle, subPrefix).forEach(r => routes.push(r));
+    }
+  }
+  return routes;
+}
+
+// Best-effort extraction of the mount path from a router layer's compiled regexp.
+// Works for simple static prefixes (/api, /v1/users, etc.) — skips prefixes with params.
+function routerLayerPath(layer) {
+  if (!layer.regexp || layer.keys?.length > 0) return '';
+  const src = layer.regexp.source;
+  // regexp for app.use('/prefix') looks like: ^\/prefix\/?(?=\/|$)
+  const m = src.match(/^\^\\\/([^?]+?)\\\//);
+  if (!m) return '';
+  return '/' + m[1].replace(/\\\//g, '/');
+}
+
+function createInterceptor(aggregator, db, config) {
+  const { env, release, service, sampling, ignorePaths } = config;
+  const ignoreSet = new Set(ignorePaths);
+
+  let routesScanned = false;
+
+  function scanRoutes(app) {
+    try {
+      const routes = extractExpressRoutes(app._router);
+      if (routes.length > 0) db.upsertKnownRoutes(routes);
+    } catch (_) {
+      // Non-critical — never crash the host app
+    }
+  }
+
+  function middleware(req, res, next) {
+    // Scan all declared Express routes once, after the first request
+    // (guarantees all app.get/post/etc calls have already executed)
+    if (!routesScanned && req.app) {
+      routesScanned = true;
+      setImmediate(() => scanRoutes(req.app));
+    }
+
+    if (ignoreSet.has(req.path)) return next();
+    if (sampling < 1.0 && Math.random() > sampling) return next();
+
+    const startHr = process.hrtime.bigint();
+
+    res.on('finish', () => {
+      try {
+        const durationMs = Number(process.hrtime.bigint() - startHr) / 1_000_000;
+
+        // Use Express matched route pattern — never the concrete URL values
+        const routePattern = req.route
+          ? (req.baseUrl || '') + req.route.path
+          : normalizePath(req.path);
+
+        const contentLength = res.getHeader('content-length');
+
+        aggregator.record({
+          route: routePattern,
+          method: req.method,
+          status: res.statusCode,
+          duration_ms: durationMs,
+          timestamp: new Date().toISOString(),
+          env,
+          release: release || null,
+          service,
+          response_size: contentLength ? parseInt(contentLength, 10) : null,
+        });
+      } catch (_) {
+        // Never let instrumentation crash the host application
+      }
+    });
+
+    next();
+  }
+
+  return middleware;
+}
+
+module.exports = { createInterceptor, extractExpressRoutes };

package/src/transport.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const CIRCUIT_OPEN_MS = 60_000;
+const FAILURE_THRESHOLD = 5;
+
+class LocalTransport {
+  constructor(db) {
+    this.db = db;
+    this._failures = 0;
+    this._openUntil = 0;
+  }
+
+  write(rows) {
+    if (rows.length === 0) return;
+
+    // Circuit breaker: if too many consecutive failures, pause writes temporarily
+    if (Date.now() < this._openUntil) return;
+
+    try {
+      this.db.insertBatch(rows);
+      this._failures = 0;
+    } catch (err) {
+      this._failures++;
+      if (this._failures >= FAILURE_THRESHOLD) {
+        this._openUntil = Date.now() + CIRCUIT_OPEN_MS;
+        this._failures = 0;
+        console.warn(`[apiforgejs] SQLite write failures — pausing for ${CIRCUIT_OPEN_MS / 1000}s. Error: ${err.message}`);
+      }
+    }
+  }
+}
+
+module.exports = { LocalTransport };