@henriquecosta/chaos-api 1.0.3 → 1.0.4

package/dist/adapters/express.d.ts

@@ -12,11 +12,11 @@ export interface ChaosOptions {
     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. */
+    /** If set (or `CHAOS_CONTROL_PORT` is 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. */
+    /** Bind address for the control API. Default `CHAOS_CONTROL_HOST` env var, else `"127.0.0.1"`. */
     controlHost?: string;
-    /** `Access-Control-Allow-Origin` for the control API. Default `"*"`. */
+    /** `Access-Control-Allow-Origin` for the control API. Default `CHAOS_CORS_ORIGIN` env var, else `"*"`. */
     corsOrigin?: string;
     /** Paths that always bypass chaos scenarios (glob strings like `"/health*"` or RegExp), e.g. health checks. */
     ignorePaths?: IgnorePathPattern[];

package/dist/adapters/express.js

@@ -1,5 +1,7 @@
 import { ActivityLog } from "../core/activity-log.js";
+import { resolveControlApiConfig } from "../core/control-api-env.js";
 import { isIgnoredPath } from "../core/ignore-paths.js";
+import { warnOnPortCollision } from "../core/safe-listen.js";
 import { ScenarioEngine } from "../core/scenario-engine.js";
 import { StateStore } from "../core/state-store.js";
 import { createControlApi } from "../dashboard/server/control-api.js";
@@ -34,8 +36,10 @@ export function chaos(options = {}) {
     });
     middleware.store = store;
     middleware.activityLog = activityLog;
-    if (options.controlPort) {
-        middleware.controlApi = createControlApi(store, activityLog, { corsOrigin: options.corsOrigin }).listen(options.controlPort, options.controlHost ?? "127.0.0.1");
+    const controlApiConfig = resolveControlApiConfig(options);
+    if (controlApiConfig.port) {
+        const server = createControlApi(store, activityLog, { corsOrigin: controlApiConfig.corsOrigin }).listen(controlApiConfig.port, controlApiConfig.host);
+        middleware.controlApi = warnOnPortCollision(server, "control API", controlApiConfig.port, controlApiConfig.host);
     }
     return middleware;
 }

package/dist/adapters/fastify.d.ts

@@ -2,6 +2,7 @@ import type { FastifyInstance } from "fastify";
 import type { Server } from "node:http";
 import { ActivityLog } from "../core/activity-log.js";
 import { StateStore } from "../core/state-store.js";
+import { type ControlApiOptions } from "../dashboard/server/control-api.js";
 import type { ChaosOptions } from "./express.js";
 export interface ChaosFastifyPlugin {
     (fastify: FastifyInstance): Promise<void>;
@@ -10,3 +11,12 @@ export interface ChaosFastifyPlugin {
     controlApi?: Server;
 }
 export declare function chaosFastifyPlugin(options?: ChaosOptions): ChaosFastifyPlugin;
+export interface ChaosControlApiFastifyPlugin {
+    (fastify: FastifyInstance): Promise<void>;
+}
+/**
+ * Fastify-compatible plugin serving the same routes as `createControlApi`, mounted directly onto
+ * the host app's own Fastify instance — no extra port, no port-collision risk. Requests that
+ * aren't ours fall through to Fastify's normal routing untouched.
+ */
+export declare function createControlApiFastifyPlugin(store: StateStore, activityLog?: ActivityLog, options?: ControlApiOptions): ChaosControlApiFastifyPlugin;

package/dist/adapters/fastify.js

@@ -1,8 +1,10 @@
 import { ActivityLog } from "../core/activity-log.js";
+import { resolveControlApiConfig } from "../core/control-api-env.js";
 import { isIgnoredPath } from "../core/ignore-paths.js";
+import { warnOnPortCollision } from "../core/safe-listen.js";
 import { ScenarioEngine } from "../core/scenario-engine.js";
 import { StateStore } from "../core/state-store.js";
-import { createControlApi } from "../dashboard/server/control-api.js";
+import { createControlApi, handleControlApiRequest, isControlApiRoute, } from "../dashboard/server/control-api.js";
 import { isBlockedByGuardrail } from "../guardrail.js";
 export function chaosFastifyPlugin(options = {}) {
     const store = options.store ?? new StateStore();
@@ -38,8 +40,28 @@ export function chaosFastifyPlugin(options = {}) {
     plugin[Symbol.for("skip-override")] = true;
     plugin.store = store;
     plugin.activityLog = activityLog;
-    if (options.controlPort) {
-        plugin.controlApi = createControlApi(store, activityLog, { corsOrigin: options.corsOrigin }).listen(options.controlPort, options.controlHost ?? "127.0.0.1");
+    const controlApiConfig = resolveControlApiConfig(options);
+    if (controlApiConfig.port) {
+        const server = createControlApi(store, activityLog, { corsOrigin: controlApiConfig.corsOrigin }).listen(controlApiConfig.port, controlApiConfig.host);
+        plugin.controlApi = warnOnPortCollision(server, "control API", controlApiConfig.port, controlApiConfig.host);
     }
     return plugin;
 }
+/**
+ * Fastify-compatible plugin serving the same routes as `createControlApi`, mounted directly onto
+ * the host app's own Fastify instance — no extra port, no port-collision risk. Requests that
+ * aren't ours fall through to Fastify's normal routing untouched.
+ */
+export function createControlApiFastifyPlugin(store, activityLog, options = {}) {
+    const corsOrigin = options.corsOrigin ?? "*";
+    const plugin = (async (fastify) => {
+        fastify.addHook("onRequest", async (request, reply) => {
+            if (!isControlApiRoute(request.url.split("?")[0]))
+                return;
+            reply.hijack();
+            await handleControlApiRequest(request.raw, reply.raw, store, activityLog, corsOrigin);
+        });
+    });
+    plugin[Symbol.for("skip-override")] = true;
+    return plugin;
+}

package/dist/adapters/koa.d.ts

@@ -2,6 +2,7 @@ import type { Middleware } from "koa";
 import type { Server } from "node:http";
 import { ActivityLog } from "../core/activity-log.js";
 import { StateStore } from "../core/state-store.js";
+import { type ControlApiOptions } from "../dashboard/server/control-api.js";
 import type { ChaosOptions } from "./express.js";
 export interface ChaosKoaMiddleware extends Middleware {
     store: StateStore;
@@ -10,3 +11,9 @@ export interface ChaosKoaMiddleware extends Middleware {
 }
 /** docs/PRD.md 6.6 — thin adapter over the shared core, same pattern as adapters/express.ts and adapters/fastify.ts. */
 export declare function chaosKoaMiddleware(options?: ChaosOptions): ChaosKoaMiddleware;
+/**
+ * Koa-compatible middleware serving the same routes as `createControlApi`, mounted directly onto
+ * the host app's own Koa instance — no extra port, no port-collision risk. Requests that aren't
+ * ours fall through to Koa's normal middleware chain untouched.
+ */
+export declare function createControlApiKoaMiddleware(store: StateStore, activityLog?: ActivityLog, options?: ControlApiOptions): Middleware;

package/dist/adapters/koa.js

@@ -1,8 +1,10 @@
 import { ActivityLog } from "../core/activity-log.js";
+import { resolveControlApiConfig } from "../core/control-api-env.js";
 import { isIgnoredPath } from "../core/ignore-paths.js";
+import { warnOnPortCollision } from "../core/safe-listen.js";
 import { ScenarioEngine } from "../core/scenario-engine.js";
 import { StateStore } from "../core/state-store.js";
-import { createControlApi } from "../dashboard/server/control-api.js";
+import { createControlApi, handleControlApiRequest, isControlApiRoute, } from "../dashboard/server/control-api.js";
 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 = {}) {
@@ -41,8 +43,28 @@ export function chaosKoaMiddleware(options = {}) {
     });
     middleware.store = store;
     middleware.activityLog = activityLog;
-    if (options.controlPort) {
-        middleware.controlApi = createControlApi(store, activityLog, { corsOrigin: options.corsOrigin }).listen(options.controlPort, options.controlHost ?? "127.0.0.1");
+    const controlApiConfig = resolveControlApiConfig(options);
+    if (controlApiConfig.port) {
+        const server = createControlApi(store, activityLog, { corsOrigin: controlApiConfig.corsOrigin }).listen(controlApiConfig.port, controlApiConfig.host);
+        middleware.controlApi = warnOnPortCollision(server, "control API", controlApiConfig.port, controlApiConfig.host);
     }
     return middleware;
 }
+/**
+ * Koa-compatible middleware serving the same routes as `createControlApi`, mounted directly onto
+ * the host app's own Koa instance — no extra port, no port-collision risk. Requests that aren't
+ * ours fall through to Koa's normal middleware chain untouched.
+ */
+export function createControlApiKoaMiddleware(store, activityLog, options = {}) {
+    const corsOrigin = options.corsOrigin ?? "*";
+    return async (ctx, next) => {
+        if (!isControlApiRoute(ctx.path)) {
+            await next();
+            return;
+        }
+        // We answer with the raw req/res directly (same as the standalone control API server) —
+        // take Koa out of the response-committing flow so it doesn't also try to write a reply.
+        ctx.respond = false;
+        await handleControlApiRequest(ctx.req, ctx.res, store, activityLog, corsOrigin);
+    };
+}

package/dist/adapters/nestjs.js

@@ -1,5 +1,7 @@
 import { ActivityLog } from "../core/activity-log.js";
+import { resolveControlApiConfig } from "../core/control-api-env.js";
 import { isIgnoredPath } from "../core/ignore-paths.js";
+import { warnOnPortCollision } from "../core/safe-listen.js";
 import { ScenarioEngine } from "../core/scenario-engine.js";
 import { StateStore } from "../core/state-store.js";
 import { createControlApi } from "../dashboard/server/control-api.js";
@@ -46,8 +48,10 @@ export function createChaosNestMiddleware(options = {}) {
     });
     middleware.store = store;
     middleware.activityLog = activityLog;
-    if (options.controlPort) {
-        middleware.controlApi = createControlApi(store, activityLog, { corsOrigin: options.corsOrigin }).listen(options.controlPort, options.controlHost ?? "127.0.0.1");
+    const controlApiConfig = resolveControlApiConfig(options);
+    if (controlApiConfig.port) {
+        const server = createControlApi(store, activityLog, { corsOrigin: controlApiConfig.corsOrigin }).listen(controlApiConfig.port, controlApiConfig.host);
+        middleware.controlApi = warnOnPortCollision(server, "control API", controlApiConfig.port, controlApiConfig.host);
     }
     return middleware;
 }

package/dist/bin/chaos-api.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { ActivityLog } from "../core/activity-log.js";
+import { resolveControlApiConfig } from "../core/control-api-env.js";
+import { warnOnPortCollision } from "../core/safe-listen.js";
 import { StateStore } from "../core/state-store.js";
 import { createControlApi } from "../dashboard/server/control-api.js";
 import { startDashboard } from "../dashboard/server/index.js";
@@ -20,15 +22,20 @@ if (command === "dashboard") {
         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 config = resolveControlApiConfig({
+            controlPort: controlPortFlag ? Number(controlPortFlag) : undefined,
+            controlHost: controlHostFlag,
+            corsOrigin: corsOriginFlag,
+        });
+        const controlPort = config.port ?? DEFAULT_CONTROL_PORT;
         const store = new StateStore();
         const activityLog = new ActivityLog();
-        createControlApi(store, activityLog, { corsOrigin: corsOriginFlag }).listen(controlPort, controlHost, () => {
-            console.log(`[chaos-api] standalone control API running at http://${controlHost}:${controlPort} ` +
+        const server = createControlApi(store, activityLog, { corsOrigin: config.corsOrigin }).listen(controlPort, config.host, () => {
+            console.log(`[chaos-api] standalone control API running at http://${config.host}:${controlPort} ` +
                 "(demo StateStore, not wired to a real app — pass --no-control-api if your app " +
                 "already runs chaos({ controlPort }) itself)");
         });
+        warnOnPortCollision(server, "standalone control API", controlPort, config.host);
     }
 }
 else {

package/dist/core/control-api-env.d.ts

@@ -0,0 +1,17 @@
+export interface ControlApiEnvOptions {
+    controlPort?: number;
+    controlHost?: string;
+    corsOrigin?: string;
+}
+export interface ResolvedControlApiConfig {
+    port?: number;
+    host: string;
+    corsOrigin: string;
+}
+/**
+ * Resolves control-API bind config: explicit `chaos()` options win, then `CHAOS_CONTROL_PORT` /
+ * `CHAOS_CONTROL_HOST` / `CHAOS_CORS_ORIGIN` env vars, then hardcoded defaults. Lets ops move the
+ * control API to a different port per environment (e.g. to dodge the `chaos-api dashboard`
+ * CLI's demo control API, which defaults to the same 51820) without touching code.
+ */
+export declare function resolveControlApiConfig(options: ControlApiEnvOptions): ResolvedControlApiConfig;

package/dist/core/control-api-env.js

@@ -0,0 +1,14 @@
+/**
+ * Resolves control-API bind config: explicit `chaos()` options win, then `CHAOS_CONTROL_PORT` /
+ * `CHAOS_CONTROL_HOST` / `CHAOS_CORS_ORIGIN` env vars, then hardcoded defaults. Lets ops move the
+ * control API to a different port per environment (e.g. to dodge the `chaos-api dashboard`
+ * CLI's demo control API, which defaults to the same 51820) without touching code.
+ */
+export function resolveControlApiConfig(options) {
+    const envPort = process.env.CHAOS_CONTROL_PORT;
+    return {
+        port: options.controlPort ?? (envPort ? Number(envPort) : undefined),
+        host: options.controlHost ?? process.env.CHAOS_CONTROL_HOST ?? "127.0.0.1",
+        corsOrigin: options.corsOrigin ?? process.env.CHAOS_CORS_ORIGIN ?? "*",
+    };
+}

package/dist/core/safe-listen.d.ts

@@ -0,0 +1,10 @@
+import type { Server } from "node:http";
+/**
+ * Attaches an `error` handler that turns EADDRINUSE into a clear, actionable log line instead of
+ * an unhandled-exception crash of the whole process. Two chaos-api control APIs easily end up on
+ * the same port (e.g. `chaos-api dashboard`'s demo control API defaults to 51820, same as the
+ * README's `chaos({ controlPort: 51820 })` example) — without this, whichever `.listen()` call
+ * loses the race silently kills its entire process, and the dashboard ends up talking to
+ * whichever StateStore *did* win the bind, with no indication anything went wrong.
+ */
+export declare function warnOnPortCollision(server: Server, label: string, port: number, host: string): Server;

package/dist/core/safe-listen.js

@@ -0,0 +1,19 @@
+/**
+ * Attaches an `error` handler that turns EADDRINUSE into a clear, actionable log line instead of
+ * an unhandled-exception crash of the whole process. Two chaos-api control APIs easily end up on
+ * the same port (e.g. `chaos-api dashboard`'s demo control API defaults to 51820, same as the
+ * README's `chaos({ controlPort: 51820 })` example) — without this, whichever `.listen()` call
+ * loses the race silently kills its entire process, and the dashboard ends up talking to
+ * whichever StateStore *did* win the bind, with no indication anything went wrong.
+ */
+export function warnOnPortCollision(server, label, port, host) {
+    server.on("error", (err) => {
+        if (err.code !== "EADDRINUSE")
+            throw err;
+        console.error(`[chaos-api] ${label} could not bind ${host}:${port} — address already in use. ` +
+            "Another chaos-api process is likely already bound there (e.g. `chaos-api dashboard` " +
+            "without --no-control-api running next to an app that already runs chaos({ controlPort }))." +
+            " Pick a different port (CHAOS_CONTROL_PORT env var or the controlPort/--control-port option).");
+    });
+    return server;
+}

package/dist/dashboard/server/index.js

@@ -2,6 +2,7 @@ import { createServer } from "node:http";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { warnOnPortCollision } from "../../core/safe-listen.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const UI_DIR = path.join(__dirname, "..", "ui");
 const MIME = {
@@ -23,7 +24,7 @@ export function startDashboard(options = {}) {
     server.listen(port, host, () => {
         console.log(`[chaos-api] dashboard running at http://${host}:${port}/dashboard`);
     });
-    return server;
+    return warnOnPortCollision(server, "dashboard server", port, host);
 }
 async function serveStatic(url, res) {
     let pathname = url.split("?")[0];

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { chaos } from "./adapters/express.js";
 export type { ChaosOptions, ChaosInstance } from "./adapters/express.js";
-export { chaosFastifyPlugin } from "./adapters/fastify.js";
-export type { ChaosFastifyPlugin } from "./adapters/fastify.js";
+export { chaosFastifyPlugin, createControlApiFastifyPlugin } from "./adapters/fastify.js";
+export type { ChaosFastifyPlugin, ChaosControlApiFastifyPlugin } from "./adapters/fastify.js";
 export { createChaosNestMiddleware } from "./adapters/nestjs.js";
 export type { ChaosNestMiddleware, NestLikeRequest, NestLikeResponse, NestMiddlewareFn } from "./adapters/nestjs.js";
-export { chaosKoaMiddleware } from "./adapters/koa.js";
+export { chaosKoaMiddleware, createControlApiKoaMiddleware } from "./adapters/koa.js";
 export type { ChaosKoaMiddleware } from "./adapters/koa.js";
 export { StateStore, globToRegex } from "./core/state-store.js";
 export type { RegisterScenarioInput, UpdateScenarioInput } from "./core/state-store.js";
@@ -19,8 +19,10 @@ export { PRESET_CATALOG, applyPreset, findPreset, listPresets } from "./presets/
 export type { ApplyPresetOverrides, PresetCategory, PresetDefinition } from "./presets/index.js";
 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 { createControlApi, createControlApiMiddleware, handleControlApiRequest, isControlApiRoute, } from "./dashboard/server/control-api.js";
+export type { ControlApiOptions, ControlApiMiddleware, ControlApiNext } 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";
+export { resolveControlApiConfig } from "./core/control-api-env.js";
+export type { ControlApiEnvOptions, ResolvedControlApiConfig } from "./core/control-api-env.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { chaos } from "./adapters/express.js";
-export { chaosFastifyPlugin } from "./adapters/fastify.js";
+export { chaosFastifyPlugin, createControlApiFastifyPlugin } from "./adapters/fastify.js";
 export { createChaosNestMiddleware } from "./adapters/nestjs.js";
-export { chaosKoaMiddleware } from "./adapters/koa.js";
+export { chaosKoaMiddleware, createControlApiKoaMiddleware } 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";
@@ -9,6 +9,7 @@ export { ScenarioEngine } from "./core/scenario-engine.js";
 export * from "./scenarios/index.js";
 export { PRESET_CATALOG, applyPreset, findPreset, listPresets } from "./presets/index.js";
 export { createChaosFetch } from "./outbound/index.js";
-export { createControlApi } from "./dashboard/server/control-api.js";
+export { createControlApi, createControlApiMiddleware, handleControlApiRequest, isControlApiRoute, } from "./dashboard/server/control-api.js";
 export { startDashboard } from "./dashboard/server/index.js";
 export { isBlockedByGuardrail, resetGuardrailWarning } from "./guardrail.js";
+export { resolveControlApiConfig } from "./core/control-api-env.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henriquecosta/chaos-api",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "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",
@@ -26,7 +26,8 @@
     "dev": "tsx watch src/bin/chaos-api.ts dashboard",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "check": "npx qlscanner scan"
   },
   "peerDependencies": {
     "express": ">=4",