@henriquecosta/chaos-api 1.0.1 → 1.0.3

package/dist/adapters/express.d.ts

@@ -1,6 +1,7 @@
 import type { NextFunction, Request, Response } from "express";
 import type { Server } from "node:http";
 import { ActivityLog } from "../core/activity-log.js";
+import { type IgnorePathPattern } from "../core/ignore-paths.js";
 import { StateStore } from "../core/state-store.js";
 export interface ChaosOptions {
     /** Bypass the NODE_ENV=production guardrail. Not recommended. */
@@ -9,8 +10,16 @@ export interface ChaosOptions {
     store?: StateStore;
     /** Reuse an existing ActivityLog (e.g. to share state across adapters in tests). */
     activityLog?: ActivityLog;
+    /** Max events kept by the activity feed (docs/PRD.md 6.5). Default 200. Ignored if `activityLog` is passed. */
+    activityLogCapacity?: number;
     /** If set, starts the local control API on this port for the dashboard UI to talk to. */
     controlPort?: number;
+    /** Bind address for the control API. Default `"127.0.0.1"` — keep it off the network unless you mean to expose it. */
+    controlHost?: string;
+    /** `Access-Control-Allow-Origin` for the control API. Default `"*"`. */
+    corsOrigin?: string;
+    /** Paths that always bypass chaos scenarios (glob strings like `"/health*"` or RegExp), e.g. health checks. */
+    ignorePaths?: IgnorePathPattern[];
 }
 export interface ChaosInstance {
     (req: Request, res: Response, next: NextFunction): void;

package/dist/adapters/express.js

@@ -1,14 +1,15 @@
 import { ActivityLog } from "../core/activity-log.js";
+import { isIgnoredPath } from "../core/ignore-paths.js";
 import { ScenarioEngine } from "../core/scenario-engine.js";
 import { StateStore } from "../core/state-store.js";
 import { createControlApi } from "../dashboard/server/control-api.js";
 import { isBlockedByGuardrail } from "../guardrail.js";
 export function chaos(options = {}) {
     const store = options.store ?? new StateStore();
-    const activityLog = options.activityLog ?? new ActivityLog();
+    const activityLog = options.activityLog ?? new ActivityLog(options.activityLogCapacity);
     const engine = new ScenarioEngine(store, activityLog);
     const middleware = ((req, res, next) => {
-        if (isBlockedByGuardrail(options)) {
+        if (isBlockedByGuardrail(options) || isIgnoredPath(req.path, options.ignorePaths)) {
             next();
             return;
         }
@@ -34,7 +35,7 @@ export function chaos(options = {}) {
     middleware.store = store;
     middleware.activityLog = activityLog;
     if (options.controlPort) {
-        middleware.controlApi = createControlApi(store, activityLog).listen(options.controlPort);
+        middleware.controlApi = createControlApi(store, activityLog, { corsOrigin: options.corsOrigin }).listen(options.controlPort, options.controlHost ?? "127.0.0.1");
     }
     return middleware;
 }

package/dist/adapters/fastify.js

@@ -1,15 +1,17 @@
 import { ActivityLog } from "../core/activity-log.js";
+import { isIgnoredPath } from "../core/ignore-paths.js";
 import { ScenarioEngine } from "../core/scenario-engine.js";
 import { StateStore } from "../core/state-store.js";
 import { createControlApi } from "../dashboard/server/control-api.js";
 import { isBlockedByGuardrail } from "../guardrail.js";
 export function chaosFastifyPlugin(options = {}) {
     const store = options.store ?? new StateStore();
-    const activityLog = options.activityLog ?? new ActivityLog();
+    const activityLog = options.activityLog ?? new ActivityLog(options.activityLogCapacity);
     const engine = new ScenarioEngine(store, activityLog);
     const plugin = (async (fastify) => {
         fastify.addHook("onRequest", async (request, reply) => {
-            if (isBlockedByGuardrail(options))
+            const path = request.url.split("?")[0];
+            if (isBlockedByGuardrail(options) || isIgnoredPath(path, options.ignorePaths))
                 return;
             const controller = {
                 status: (code) => {
@@ -22,7 +24,6 @@ export function chaosFastifyPlugin(options = {}) {
                     reply.send(body);
                 },
             };
-            const path = request.url.split("?")[0];
             const result = await engine.resolve({ method: request.method, path }, controller);
             if (result === "terminated" && !reply.sent) {
                 // random-timeout: no response was written on purpose — take Fastify
@@ -38,7 +39,7 @@ export function chaosFastifyPlugin(options = {}) {
     plugin.store = store;
     plugin.activityLog = activityLog;
     if (options.controlPort) {
-        plugin.controlApi = createControlApi(store, activityLog).listen(options.controlPort);
+        plugin.controlApi = createControlApi(store, activityLog, { corsOrigin: options.corsOrigin }).listen(options.controlPort, options.controlHost ?? "127.0.0.1");
     }
     return plugin;
 }

package/dist/adapters/koa.js

@@ -1,4 +1,5 @@
 import { ActivityLog } from "../core/activity-log.js";
+import { isIgnoredPath } from "../core/ignore-paths.js";
 import { ScenarioEngine } from "../core/scenario-engine.js";
 import { StateStore } from "../core/state-store.js";
 import { createControlApi } from "../dashboard/server/control-api.js";
@@ -6,10 +7,10 @@ import { isBlockedByGuardrail } from "../guardrail.js";
 /** docs/PRD.md 6.6 — thin adapter over the shared core, same pattern as adapters/express.ts and adapters/fastify.ts. */
 export function chaosKoaMiddleware(options = {}) {
     const store = options.store ?? new StateStore();
-    const activityLog = options.activityLog ?? new ActivityLog();
+    const activityLog = options.activityLog ?? new ActivityLog(options.activityLogCapacity);
     const engine = new ScenarioEngine(store, activityLog);
     const middleware = (async (ctx, next) => {
-        if (isBlockedByGuardrail(options)) {
+        if (isBlockedByGuardrail(options) || isIgnoredPath(ctx.path, options.ignorePaths)) {
             await next();
             return;
         }
@@ -41,7 +42,7 @@ export function chaosKoaMiddleware(options = {}) {
     middleware.store = store;
     middleware.activityLog = activityLog;
     if (options.controlPort) {
-        middleware.controlApi = createControlApi(store, activityLog).listen(options.controlPort);
+        middleware.controlApi = createControlApi(store, activityLog, { corsOrigin: options.corsOrigin }).listen(options.controlPort, options.controlHost ?? "127.0.0.1");
     }
     return middleware;
 }

package/dist/adapters/nestjs.js

@@ -1,4 +1,5 @@
 import { ActivityLog } from "../core/activity-log.js";
+import { isIgnoredPath } from "../core/ignore-paths.js";
 import { ScenarioEngine } from "../core/scenario-engine.js";
 import { StateStore } from "../core/state-store.js";
 import { createControlApi } from "../dashboard/server/control-api.js";
@@ -10,10 +11,11 @@ import { isBlockedByGuardrail } from "../guardrail.js";
  */
 export function createChaosNestMiddleware(options = {}) {
     const store = options.store ?? new StateStore();
-    const activityLog = options.activityLog ?? new ActivityLog();
+    const activityLog = options.activityLog ?? new ActivityLog(options.activityLogCapacity);
     const engine = new ScenarioEngine(store, activityLog);
     const middleware = ((req, res, next) => {
-        if (isBlockedByGuardrail(options)) {
+        const path = (req.originalUrl ?? req.url).split("?")[0];
+        if (isBlockedByGuardrail(options) || isIgnoredPath(path, options.ignorePaths)) {
             next();
             return;
         }
@@ -34,7 +36,6 @@ export function createChaosNestMiddleware(options = {}) {
                     res.end(typeof body === "string" ? body : JSON.stringify(body));
             },
         };
-        const path = (req.originalUrl ?? req.url).split("?")[0];
         engine
             .resolve({ method: req.method, path }, controller)
             .then((result) => {
@@ -46,7 +47,7 @@ export function createChaosNestMiddleware(options = {}) {
     middleware.store = store;
     middleware.activityLog = activityLog;
     if (options.controlPort) {
-        middleware.controlApi = createControlApi(store, activityLog).listen(options.controlPort);
+        middleware.controlApi = createControlApi(store, activityLog, { corsOrigin: options.corsOrigin }).listen(options.controlPort, options.controlHost ?? "127.0.0.1");
     }
     return middleware;
 }

package/dist/bin/chaos-api.js

@@ -14,20 +14,25 @@ function hasFlag(flag) {
 }
 if (command === "dashboard") {
     const portFlag = flagValue("--port");
-    startDashboard({ port: portFlag ? Number(portFlag) : undefined });
+    const hostFlag = flagValue("--host");
+    startDashboard({ port: portFlag ? Number(portFlag) : undefined, host: hostFlag });
     if (!hasFlag("--no-control-api")) {
         const controlPortFlag = flagValue("--control-port");
+        const controlHostFlag = flagValue("--control-host");
+        const corsOriginFlag = flagValue("--cors-origin");
         const controlPort = controlPortFlag ? Number(controlPortFlag) : DEFAULT_CONTROL_PORT;
+        const controlHost = controlHostFlag ?? "127.0.0.1";
         const store = new StateStore();
         const activityLog = new ActivityLog();
-        createControlApi(store, activityLog).listen(controlPort, () => {
-            console.log(`[chaos-api] standalone control API running at http://localhost:${controlPort} ` +
+        createControlApi(store, activityLog, { corsOrigin: corsOriginFlag }).listen(controlPort, controlHost, () => {
+            console.log(`[chaos-api] standalone control API running at http://${controlHost}:${controlPort} ` +
                 "(demo StateStore, not wired to a real app — pass --no-control-api if your app " +
                 "already runs chaos({ controlPort }) itself)");
         });
     }
 }
 else {
-    console.error(`Unknown command: ${command ?? "(none)"}. Usage: chaos-api dashboard [--port <n>] [--control-port <n>] [--no-control-api]`);
+    console.error(`Unknown command: ${command ?? "(none)"}. Usage: chaos-api dashboard ` +
+        "[--port <n>] [--host <addr>] [--control-port <n>] [--control-host <addr>] [--cors-origin <origin>] [--no-control-api]");
     process.exit(1);
 }

package/dist/core/ignore-paths.d.ts

@@ -0,0 +1,7 @@
+export type IgnorePathPattern = string | RegExp;
+/**
+ * True if `path` matches one of the configured ignore patterns — those requests bypass chaos
+ * scenarios entirely (e.g. health checks, the control API's own routes when mounted on the same
+ * server as the host app). String patterns use the same glob syntax as scenario scopes (`*`).
+ */
+export declare function isIgnoredPath(path: string, patterns?: IgnorePathPattern[]): boolean;

package/dist/core/ignore-paths.js

@@ -0,0 +1,11 @@
+import { globToRegex } from "./state-store.js";
+/**
+ * True if `path` matches one of the configured ignore patterns — those requests bypass chaos
+ * scenarios entirely (e.g. health checks, the control API's own routes when mounted on the same
+ * server as the host app). String patterns use the same glob syntax as scenario scopes (`*`).
+ */
+export function isIgnoredPath(path, patterns) {
+    if (!patterns?.length)
+        return false;
+    return patterns.some((pattern) => (typeof pattern === "string" ? globToRegex(pattern) : pattern).test(path));
+}

package/dist/dashboard/server/control-api.d.ts

@@ -1,9 +1,42 @@
-import { type Server } from "node:http";
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import type { ActivityLog } from "../../core/activity-log.js";
 import type { StateStore } from "../../core/state-store.js";
+export interface ControlApiOptions {
+    /** `Access-Control-Allow-Origin` value. Default `"*"` (dashboard-ui may run on any origin/port). */
+    corsOrigin?: string;
+}
+export type ControlApiNext = (err?: unknown) => void;
 /**
  * Local control API for the scenario StateStore living inside the user's app process.
  * dashboard-ui talks to this directly (CORS-open, localhost-only by convention) — the
  * dashboard-server process only serves static UI files, it does not proxy this API.
+ *
+ * Runs as its own `http.Server` on `controlPort`. If you'd rather not open a second port,
+ * see `createControlApiMiddleware` — it mounts these same routes onto the host app's own
+ * server/port instead.
  */
-export declare function createControlApi(store: StateStore, activityLog?: ActivityLog): Server;
+export declare function createControlApi(store: StateStore, activityLog?: ActivityLog, options?: ControlApiOptions): Server;
+export type ControlApiMiddleware = (req: IncomingMessage, res: ServerResponse, next: ControlApiNext) => void;
+/**
+ * Express/Nest-compatible middleware (`(req, res, next)`) that serves the same routes as
+ * `createControlApi`, but mounted directly onto the host app's own server — no extra port.
+ * Calls `next()` untouched for any request that isn't one of ours, so it can sit alongside the
+ * host's real routes: `app.use(createControlApiMiddleware(store, activityLog))`.
+ *
+ * For Fastify/Koa, use `createControlApiFastifyPlugin` / `createControlApiKoaMiddleware` instead —
+ * their request/response objects aren't raw `http.IncomingMessage`/`ServerResponse`.
+ */
+export declare function createControlApiMiddleware(store: StateStore, activityLog?: ActivityLog, options?: ControlApiOptions): ControlApiMiddleware;
+/**
+ * True if `pathname` targets one of this control API's own resources, wherever it's mounted.
+ * Exported so the Fastify/Koa wrappers (which can't rely on an Express-style `next`) can decide
+ * up front whether a request is ours before touching their request/response objects.
+ */
+export declare function isControlApiRoute(pathname: string): boolean;
+/**
+ * Handles one control API request against raw Node req/res. Exported for framework wrappers
+ * (Fastify's `request.raw`/`reply.raw`, Koa's `ctx.req`/`ctx.res`) that already know — via
+ * `isControlApiRoute` — that the request is ours, so they call this directly instead of going
+ * through the `next`-based fallback in `createControlApiMiddleware`.
+ */
+export declare function handleControlApiRequest(req: IncomingMessage, res: ServerResponse, store: StateStore, activityLog: ActivityLog | undefined, corsOrigin: string, next?: ControlApiNext): Promise<void>;

package/dist/dashboard/server/control-api.js

@@ -1,34 +1,84 @@
 import { createServer } from "node:http";
 import { applyPreset, findPreset, listPresets } from "../../presets/index.js";
 const CORS_HEADERS = {
-    "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET,POST,PATCH,DELETE,OPTIONS",
     "Access-Control-Allow-Headers": "Content-Type",
 };
+/** Resource names this control API owns — anything else isn't ours (see `isControlApiRoute` below). */
+const KNOWN_RESOURCES = ["scenarios", "activity", "presets", "config"];
 /**
  * Local control API for the scenario StateStore living inside the user's app process.
  * dashboard-ui talks to this directly (CORS-open, localhost-only by convention) — the
  * dashboard-server process only serves static UI files, it does not proxy this API.
+ *
+ * Runs as its own `http.Server` on `controlPort`. If you'd rather not open a second port,
+ * see `createControlApiMiddleware` — it mounts these same routes onto the host app's own
+ * server/port instead.
  */
-export function createControlApi(store, activityLog) {
+export function createControlApi(store, activityLog, options = {}) {
+    const corsOrigin = options.corsOrigin ?? "*";
     return createServer((req, res) => {
-        void handleRequest(req, res, store, activityLog);
+        void handleControlApiRequest(req, res, store, activityLog, corsOrigin);
     });
 }
-async function handleRequest(req, res, store, activityLog) {
+/**
+ * Express/Nest-compatible middleware (`(req, res, next)`) that serves the same routes as
+ * `createControlApi`, but mounted directly onto the host app's own server — no extra port.
+ * Calls `next()` untouched for any request that isn't one of ours, so it can sit alongside the
+ * host's real routes: `app.use(createControlApiMiddleware(store, activityLog))`.
+ *
+ * For Fastify/Koa, use `createControlApiFastifyPlugin` / `createControlApiKoaMiddleware` instead —
+ * their request/response objects aren't raw `http.IncomingMessage`/`ServerResponse`.
+ */
+export function createControlApiMiddleware(store, activityLog, options = {}) {
+    const corsOrigin = options.corsOrigin ?? "*";
+    return (req, res, next) => {
+        void handleControlApiRequest(req, res, store, activityLog, corsOrigin, next);
+    };
+}
+/**
+ * True if `pathname` targets one of this control API's own resources, wherever it's mounted.
+ * Exported so the Fastify/Koa wrappers (which can't rely on an Express-style `next`) can decide
+ * up front whether a request is ours before touching their request/response objects.
+ */
+export function isControlApiRoute(pathname) {
+    const segments = pathname.split("/").filter(Boolean);
+    const apiIndex = segments.lastIndexOf("api");
+    return apiIndex !== -1 && KNOWN_RESOURCES.includes(segments[apiIndex + 1] ?? "");
+}
+/**
+ * Handles one control API request against raw Node req/res. Exported for framework wrappers
+ * (Fastify's `request.raw`/`reply.raw`, Koa's `ctx.req`/`ctx.res`) that already know — via
+ * `isControlApiRoute` — that the request is ours, so they call this directly instead of going
+ * through the `next`-based fallback in `createControlApiMiddleware`.
+ */
+export async function handleControlApiRequest(req, res, store, activityLog, corsOrigin, next) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    // When mounted as middleware (`next` present), a non-matching request belongs to the host
+    // app — pass it through untouched instead of claiming it with our own CORS headers/404.
+    if (next && !isControlApiRoute(url.pathname)) {
+        next();
+        return;
+    }
+    res.setHeader("Access-Control-Allow-Origin", corsOrigin);
     for (const [key, value] of Object.entries(CORS_HEADERS))
         res.setHeader(key, value);
     if (req.method === "OPTIONS") {
         res.writeHead(204).end();
         return;
     }
-    const url = new URL(req.url ?? "/", "http://localhost");
-    const segments = url.pathname.split("/").filter(Boolean);
+    const allSegments = url.pathname.split("/").filter(Boolean);
+    // Anchor on the *last* "api" segment, not position 0 — a host may mount this control API
+    // (as middleware, or behind a proxy) underneath its own base path (e.g.
+    // `/api/v1/notebooks/api/activity`). Anchoring on position 0 breaks in that case; anchoring
+    // on the last "api" keeps the package route-independent of wherever the host puts it.
+    const apiIndex = allSegments.lastIndexOf("api");
     try {
-        if (segments[0] !== "api") {
+        if (apiIndex === -1) {
             notFound(res);
             return;
         }
+        const segments = allSegments.slice(apiIndex);
         if (segments[1] === "activity" && segments.length === 2 && req.method === "GET") {
             const limitParam = url.searchParams.get("limit");
             sendJson(res, 200, activityLog?.list(limitParam ? Number(limitParam) : undefined) ?? []);

package/dist/dashboard/server/index.d.ts

@@ -1,6 +1,8 @@
 import { type Server } from "node:http";
 export interface StartDashboardOptions {
     port?: number;
+    /** Bind address. Default `"127.0.0.1"` — set to `"0.0.0.0"` to expose it beyond localhost. */
+    host?: string;
 }
 /**
  * Serves the static dashboard-ui. This process does not hold any scenario state —

package/dist/dashboard/server/index.js

@@ -16,11 +16,12 @@ const MIME = {
  */
 export function startDashboard(options = {}) {
     const port = options.port ?? 4000;
+    const host = options.host ?? "127.0.0.1";
     const server = createServer((req, res) => {
         void serveStatic(req.url ?? "/", res);
     });
-    server.listen(port, () => {
-        console.log(`[chaos-api] dashboard running at http://localhost:${port}/dashboard`);
+    server.listen(port, host, () => {
+        console.log(`[chaos-api] dashboard running at http://${host}:${port}/dashboard`);
     });
     return server;
 }

package/dist/dashboard/ui/app.js

@@ -1,6 +1,8 @@
 const STORAGE_KEY = "chaos-api:control-url";
+const POLL_STORAGE_KEY = "chaos-api:poll-interval";
 
 const controlUrlInput = document.getElementById("control-url");
+const pollIntervalInput = document.getElementById("poll-interval");
 const connectButton = document.getElementById("connect");
 const listEl = document.getElementById("scenario-list");
 const bannerEl = document.getElementById("status-banner");
@@ -26,6 +28,7 @@ const PRESET_CATEGORIES = [
 let activePresetCategory = "";
 
 controlUrlInput.value = localStorage.getItem(STORAGE_KEY) || controlUrlInput.value;
+pollIntervalInput.value = localStorage.getItem(POLL_STORAGE_KEY) || pollIntervalInput.value;
 
 function controlUrl() {
   return controlUrlInput.value.replace(/\/$/, "");
@@ -192,13 +195,28 @@ async function refreshPresets() {
   if (presets) renderPresets(presets);
 }
 
+let pollTimer;
+
+function restartPolling() {
+  clearInterval(pollTimer);
+  const ms = Number(pollIntervalInput.value) || 3000;
+  pollTimer = setInterval(refreshActivity, ms);
+}
+
 connectButton.addEventListener("click", () => {
   localStorage.setItem(STORAGE_KEY, controlUrlInput.value);
+  localStorage.setItem(POLL_STORAGE_KEY, pollIntervalInput.value);
+  restartPolling();
   refresh();
   refreshActivity();
   refreshPresets();
 });
 
+pollIntervalInput.addEventListener("change", () => {
+  localStorage.setItem(POLL_STORAGE_KEY, pollIntervalInput.value);
+  restartPolling();
+});
+
 exportButton.addEventListener("click", async () => {
   const config = await withErrorHandling(() => api("/api/config"));
   if (!config) return;
@@ -299,7 +317,7 @@ function buildRunnerResult(ok, statusLine, headersText, bodyText) {
   return wrapper;
 }
 
-setInterval(refreshActivity, 3000);
+restartPolling();
 
 addForm.addEventListener("submit", async (e) => {
   e.preventDefault();

package/dist/dashboard/ui/index.html

@@ -157,6 +157,8 @@
     <div class="row">
       <span style="color: var(--text-muted)">control API:</span>
       <input id="control-url" type="text" value="http://localhost:51820" />
+      <span style="color: var(--text-muted)">polling (ms):</span>
+      <input id="poll-interval" type="number" min="500" step="500" value="3000" style="width: 80px" />
       <button id="connect">Conectar</button>
     </div>
   </header>

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { StateStore, globToRegex } from "./core/state-store.js";
 export type { RegisterScenarioInput, UpdateScenarioInput } from "./core/state-store.js";
 export { ActivityLog } from "./core/activity-log.js";
 export type { ActivityEvent, RecordActivityInput } from "./core/activity-log.js";
+export { isIgnoredPath } from "./core/ignore-paths.js";
+export type { IgnorePathPattern } from "./core/ignore-paths.js";
 export { ScenarioEngine } from "./core/scenario-engine.js";
 export type { ChaosRequestInfo, ChaosResponseController, LegacyScenarioType, ScenarioConfig, ScenarioDirection, ScenarioHandler, ScenarioResult, ScenarioScope, ScenarioType, } from "./core/types.js";
 export * from "./scenarios/index.js";
@@ -18,5 +20,7 @@ export type { ApplyPresetOverrides, PresetCategory, PresetDefinition } from "./p
 export { createChaosFetch } from "./outbound/index.js";
 export type { ChaosFetchOptions } from "./outbound/index.js";
 export { createControlApi } from "./dashboard/server/control-api.js";
+export type { ControlApiOptions } from "./dashboard/server/control-api.js";
 export { startDashboard } from "./dashboard/server/index.js";
+export type { StartDashboardOptions } from "./dashboard/server/index.js";
 export { isBlockedByGuardrail, resetGuardrailWarning } from "./guardrail.js";

package/dist/index.js

@@ -4,6 +4,7 @@ export { createChaosNestMiddleware } from "./adapters/nestjs.js";
 export { chaosKoaMiddleware } from "./adapters/koa.js";
 export { StateStore, globToRegex } from "./core/state-store.js";
 export { ActivityLog } from "./core/activity-log.js";
+export { isIgnoredPath } from "./core/ignore-paths.js";
 export { ScenarioEngine } from "./core/scenario-engine.js";
 export * from "./scenarios/index.js";
 export { PRESET_CATALOG, applyPreset, findPreset, listPresets } from "./presets/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henriquecosta/chaos-api",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "license": "MIT",
   "description": "Middleware pra simular falhas de producao (delay, erros, timeout, indisponibilidade, respostas malformadas/obsoletas) em APIs Express/Fastify/NestJS/Koa durante desenvolvimento.",
   "type": "module",