@henriquecosta/chaos-api 1.0.0

package/dist/adapters/express.d.ts

@@ -0,0 +1,21 @@
+import type { NextFunction, Request, Response } from "express";
+import type { Server } from "node:http";
+import { ActivityLog } from "../core/activity-log.js";
+import { StateStore } from "../core/state-store.js";
+export interface ChaosOptions {
+    /** Bypass the NODE_ENV=production guardrail. Not recommended. */
+    allowInProduction?: boolean;
+    /** Reuse an existing StateStore (e.g. to share state across adapters in tests). */
+    store?: StateStore;
+    /** Reuse an existing ActivityLog (e.g. to share state across adapters in tests). */
+    activityLog?: ActivityLog;
+    /** If set, starts the local control API on this port for the dashboard UI to talk to. */
+    controlPort?: number;
+}
+export interface ChaosInstance {
+    (req: Request, res: Response, next: NextFunction): void;
+    store: StateStore;
+    activityLog: ActivityLog;
+    controlApi?: Server;
+}
+export declare function chaos(options?: ChaosOptions): ChaosInstance;

package/dist/adapters/express.js

@@ -0,0 +1,40 @@
+import { ActivityLog } from "../core/activity-log.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 engine = new ScenarioEngine(store, activityLog);
+    const middleware = ((req, res, next) => {
+        if (isBlockedByGuardrail(options)) {
+            next();
+            return;
+        }
+        const controller = {
+            status: (code) => {
+                res.status(code);
+            },
+            header: (name, value) => {
+                res.setHeader(name, value);
+            },
+            send: (body) => {
+                res.send(body);
+            },
+        };
+        engine
+            .resolve({ method: req.method, path: req.path }, controller)
+            .then((result) => {
+            if (result === "continue")
+                next();
+        })
+            .catch(next);
+    });
+    middleware.store = store;
+    middleware.activityLog = activityLog;
+    if (options.controlPort) {
+        middleware.controlApi = createControlApi(store, activityLog).listen(options.controlPort);
+    }
+    return middleware;
+}

package/dist/adapters/fastify.d.ts

@@ -0,0 +1,12 @@
+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 { ChaosOptions } from "./express.js";
+export interface ChaosFastifyPlugin {
+    (fastify: FastifyInstance): Promise<void>;
+    store: StateStore;
+    activityLog: ActivityLog;
+    controlApi?: Server;
+}
+export declare function chaosFastifyPlugin(options?: ChaosOptions): ChaosFastifyPlugin;

package/dist/adapters/fastify.js

@@ -0,0 +1,44 @@
+import { ActivityLog } from "../core/activity-log.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 engine = new ScenarioEngine(store, activityLog);
+    const plugin = (async (fastify) => {
+        fastify.addHook("onRequest", async (request, reply) => {
+            if (isBlockedByGuardrail(options))
+                return;
+            const controller = {
+                status: (code) => {
+                    reply.code(code);
+                },
+                header: (name, value) => {
+                    reply.header(name, value);
+                },
+                send: (body) => {
+                    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
+                // out of the request lifecycle so it doesn't send a default reply.
+                reply.hijack();
+            }
+        });
+    });
+    // Skip Fastify's plugin encapsulation so the onRequest hook applies to routes
+    // registered on the parent instance, not just inside this plugin's own context.
+    // This is the same mechanism the `fastify-plugin` package uses internally.
+    plugin[Symbol.for("skip-override")] = true;
+    plugin.store = store;
+    plugin.activityLog = activityLog;
+    if (options.controlPort) {
+        plugin.controlApi = createControlApi(store, activityLog).listen(options.controlPort);
+    }
+    return plugin;
+}

package/dist/adapters/koa.d.ts

@@ -0,0 +1,12 @@
+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 { ChaosOptions } from "./express.js";
+export interface ChaosKoaMiddleware extends Middleware {
+    store: StateStore;
+    activityLog: ActivityLog;
+    controlApi?: Server;
+}
+/** 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;

package/dist/adapters/koa.js

@@ -0,0 +1,47 @@
+import { ActivityLog } from "../core/activity-log.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";
+/** 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 engine = new ScenarioEngine(store, activityLog);
+    const middleware = (async (ctx, next) => {
+        if (isBlockedByGuardrail(options)) {
+            await next();
+            return;
+        }
+        let responded = false;
+        const controller = {
+            status: (code) => {
+                ctx.status = code;
+                responded = true;
+            },
+            header: (name, value) => {
+                ctx.set(name, value);
+            },
+            send: (body) => {
+                ctx.body = body;
+                responded = true;
+            },
+        };
+        const result = await engine.resolve({ method: ctx.method, path: ctx.path }, controller);
+        if (result === "terminated") {
+            if (!responded) {
+                // connection-reset: no response was written on purpose — take Koa out of the
+                // request lifecycle so it doesn't send a default reply / close the socket.
+                ctx.respond = false;
+            }
+            return;
+        }
+        await next();
+    });
+    middleware.store = store;
+    middleware.activityLog = activityLog;
+    if (options.controlPort) {
+        middleware.controlApi = createControlApi(store, activityLog).listen(options.controlPort);
+    }
+    return middleware;
+}

package/dist/adapters/nestjs.d.ts

@@ -0,0 +1,34 @@
+import type { Server } from "node:http";
+import { ActivityLog } from "../core/activity-log.js";
+import { StateStore } from "../core/state-store.js";
+import type { ChaosOptions } from "./express.js";
+/**
+ * Minimal structural shapes for Nest's req/res — deliberately not `@nestjs/common` types, so
+ * this package doesn't need Nest (or Express/Fastify) as a dependency just to type this file.
+ * Works under both platform-express (req/res are Express-decorated) and platform-fastify
+ * (functional middleware gets the raw `http.IncomingMessage`/`ServerResponse`).
+ */
+export interface NestLikeRequest {
+    method: string;
+    url: string;
+    originalUrl?: string;
+}
+export interface NestLikeResponse {
+    statusCode?: number;
+    status?(code: number): unknown;
+    send?(body?: unknown): unknown;
+    setHeader(name: string, value: string): unknown;
+    end(chunk?: unknown): unknown;
+}
+export type NestMiddlewareFn = (req: NestLikeRequest, res: NestLikeResponse, next: (err?: unknown) => void) => void;
+export interface ChaosNestMiddleware extends NestMiddlewareFn {
+    store: StateStore;
+    activityLog: ActivityLog;
+    controlApi?: Server;
+}
+/**
+ * docs/PRD.md 6.6 — thin adapter over the shared core, same pattern as adapters/express.ts and
+ * adapters/fastify.ts. Register as functional middleware: `consumer.apply(createChaosNestMiddleware()).forRoutes("*")`
+ * in a NestModule's `configure()`, or just `app.use(createChaosNestMiddleware())` in main.ts.
+ */
+export declare function createChaosNestMiddleware(options?: ChaosOptions): ChaosNestMiddleware;

package/dist/adapters/nestjs.js

@@ -0,0 +1,52 @@
+import { ActivityLog } from "../core/activity-log.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";
+/**
+ * docs/PRD.md 6.6 — thin adapter over the shared core, same pattern as adapters/express.ts and
+ * adapters/fastify.ts. Register as functional middleware: `consumer.apply(createChaosNestMiddleware()).forRoutes("*")`
+ * in a NestModule's `configure()`, or just `app.use(createChaosNestMiddleware())` in main.ts.
+ */
+export function createChaosNestMiddleware(options = {}) {
+    const store = options.store ?? new StateStore();
+    const activityLog = options.activityLog ?? new ActivityLog();
+    const engine = new ScenarioEngine(store, activityLog);
+    const middleware = ((req, res, next) => {
+        if (isBlockedByGuardrail(options)) {
+            next();
+            return;
+        }
+        const controller = {
+            status: (code) => {
+                if (typeof res.status === "function")
+                    res.status(code);
+                else
+                    res.statusCode = code;
+            },
+            header: (name, value) => {
+                res.setHeader(name, value);
+            },
+            send: (body) => {
+                if (typeof res.send === "function")
+                    res.send(body);
+                else
+                    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) => {
+            if (result === "continue")
+                next();
+        })
+            .catch(next);
+    });
+    middleware.store = store;
+    middleware.activityLog = activityLog;
+    if (options.controlPort) {
+        middleware.controlApi = createControlApi(store, activityLog).listen(options.controlPort);
+    }
+    return middleware;
+}

package/dist/bin/chaos-api.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/chaos-api.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { ActivityLog } from "../core/activity-log.js";
+import { StateStore } from "../core/state-store.js";
+import { createControlApi } from "../dashboard/server/control-api.js";
+import { startDashboard } from "../dashboard/server/index.js";
+const [, , command, ...rest] = process.argv;
+const DEFAULT_CONTROL_PORT = 51820;
+function flagValue(flag) {
+    const index = rest.indexOf(flag);
+    return index >= 0 ? rest[index + 1] : undefined;
+}
+function hasFlag(flag) {
+    return rest.includes(flag);
+}
+if (command === "dashboard") {
+    const portFlag = flagValue("--port");
+    startDashboard({ port: portFlag ? Number(portFlag) : undefined });
+    if (!hasFlag("--no-control-api")) {
+        const controlPortFlag = flagValue("--control-port");
+        const controlPort = controlPortFlag ? Number(controlPortFlag) : DEFAULT_CONTROL_PORT;
+        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} ` +
+                "(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]`);
+    process.exit(1);
+}

package/dist/core/activity-log.d.ts

@@ -0,0 +1,24 @@
+import type { ScenarioDirection, ScenarioType } from "./types.js";
+export interface ActivityEvent {
+    id: string;
+    timestamp: number;
+    scenarioId: string;
+    scenarioType: ScenarioType;
+    direction: ScenarioDirection;
+    method: string;
+    path: string;
+}
+export type RecordActivityInput = Omit<ActivityEvent, "id" | "timestamp">;
+/**
+ * In-memory ring buffer of fired scenarios (docs/PRD.md 6.5 "feed de atividade") — no external
+ * dependency, capped so it can't grow unbounded in a long-running process.
+ */
+export declare class ActivityLog {
+    private readonly capacity;
+    private readonly events;
+    constructor(capacity?: number);
+    record(input: RecordActivityInput): ActivityEvent;
+    /** Newest first. */
+    list(limit?: number): ActivityEvent[];
+    clear(): void;
+}

package/dist/core/activity-log.js

@@ -0,0 +1,26 @@
+import { randomUUID } from "node:crypto";
+/**
+ * In-memory ring buffer of fired scenarios (docs/PRD.md 6.5 "feed de atividade") — no external
+ * dependency, capped so it can't grow unbounded in a long-running process.
+ */
+export class ActivityLog {
+    capacity;
+    events = [];
+    constructor(capacity = 200) {
+        this.capacity = capacity;
+    }
+    record(input) {
+        const event = { id: randomUUID(), timestamp: Date.now(), ...input };
+        this.events.unshift(event);
+        if (this.events.length > this.capacity)
+            this.events.length = this.capacity;
+        return event;
+    }
+    /** Newest first. */
+    list(limit) {
+        return limit !== undefined ? this.events.slice(0, limit) : [...this.events];
+    }
+    clear() {
+        this.events.length = 0;
+    }
+}

package/dist/core/scenario-engine.d.ts

@@ -0,0 +1,12 @@
+import type { ActivityLog } from "./activity-log.js";
+import type { StateStore } from "./state-store.js";
+import type { ChaosRequestInfo, ChaosResponseController, ScenarioResult } from "./types.js";
+export declare class ScenarioEngine {
+    private readonly store;
+    private readonly activityLog?;
+    constructor(store: StateStore, activityLog?: ActivityLog | undefined);
+    resolve(req: ChaosRequestInfo, res: ChaosResponseController): Promise<ScenarioResult>;
+    /** docs/PRD.md 6.4 — `req.path` carries the outbound call's destination host, not a route. */
+    resolveOutbound(req: ChaosRequestInfo, res: ChaosResponseController): Promise<ScenarioResult>;
+    private apply;
+}

package/dist/core/scenario-engine.js

@@ -0,0 +1,38 @@
+import { SCENARIO_REGISTRY } from "../scenarios/registry.js";
+/** Fixed apply order for combined scenarios — matches docs/architecture-and-walkthrough.md. */
+const PRIORITY = SCENARIO_REGISTRY.map((def) => def.type);
+const HANDLERS = Object.fromEntries(SCENARIO_REGISTRY.map((def) => [def.type, def.handler]));
+export class ScenarioEngine {
+    store;
+    activityLog;
+    constructor(store, activityLog) {
+        this.store = store;
+        this.activityLog = activityLog;
+    }
+    async resolve(req, res) {
+        return this.apply(this.store.getActiveForPath(req.path), req, res);
+    }
+    /** docs/PRD.md 6.4 — `req.path` carries the outbound call's destination host, not a route. */
+    async resolveOutbound(req, res) {
+        return this.apply(this.store.getActiveOutbound(req.path), req, res);
+    }
+    async apply(active, req, res) {
+        const ordered = PRIORITY.flatMap((type) => active.filter((s) => s.type === type));
+        for (const scenario of ordered) {
+            if (Math.random() > scenario.rate)
+                continue;
+            this.activityLog?.record({
+                scenarioId: scenario.id,
+                scenarioType: scenario.type,
+                direction: scenario.direction,
+                method: req.method,
+                path: req.path,
+            });
+            const handler = HANDLERS[scenario.type];
+            const result = await handler({ req, res }, scenario.options);
+            if (result === "terminated")
+                return "terminated";
+        }
+        return "continue";
+    }
+}

package/dist/core/state-store.d.ts

@@ -0,0 +1,26 @@
+import type { LegacyScenarioType, ScenarioConfig, ScenarioDirection, ScenarioScope, ScenarioType } from "./types.js";
+export interface RegisterScenarioInput {
+    type: ScenarioType | LegacyScenarioType;
+    scope?: ScenarioScope;
+    /** "inbound" (default) matches request path; "outbound" matches destination host (docs/PRD.md 6.4). */
+    direction?: ScenarioDirection;
+    rate?: number;
+    enabled?: boolean;
+    options?: Record<string, unknown>;
+}
+export type UpdateScenarioInput = Partial<Omit<ScenarioConfig, "id" | "type">>;
+/** Converts a route glob (`/orders/*`) into a matching RegExp. Only `*` is a wildcard. */
+export declare function globToRegex(pattern: string): RegExp;
+/** In-memory registry of active chaos scenarios. One instance lives per middleware. */
+export declare class StateStore {
+    private readonly scenarios;
+    register(input: RegisterScenarioInput): ScenarioConfig;
+    update(id: string, patch: UpdateScenarioInput): ScenarioConfig | undefined;
+    remove(id: string): boolean;
+    get(id: string): ScenarioConfig | undefined;
+    list(): ScenarioConfig[];
+    getActiveForPath(path: string): ScenarioConfig[];
+    /** docs/PRD.md 6.4 — scenarios scoped to an outbound call's destination host instead of a route. */
+    getActiveOutbound(host: string): ScenarioConfig[];
+    clear(): void;
+}

package/dist/core/state-store.js

@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+/** v1 -> v2 primitive mapping (docs/PRD.md 6.2). Keeps pre-refactor configs working unchanged. */
+const LEGACY_TYPE_ALIASES = {
+    "random-error": "error-response",
+    "random-timeout": "connection-reset",
+    "unavailable-503": "unavailable",
+};
+function normalizeType(type) {
+    return type in LEGACY_TYPE_ALIASES ? LEGACY_TYPE_ALIASES[type] : type;
+}
+/** Converts a route glob (`/orders/*`) into a matching RegExp. Only `*` is a wildcard. */
+export function globToRegex(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`);
+}
+function matchesScope(scope, path) {
+    if (scope === "global")
+        return true;
+    return globToRegex(scope.pattern).test(path);
+}
+/** In-memory registry of active chaos scenarios. One instance lives per middleware. */
+export class StateStore {
+    scenarios = new Map();
+    register(input) {
+        if (input.rate !== undefined && (input.rate < 0 || input.rate > 1)) {
+            throw new Error(`rate must be between 0 and 1, got ${input.rate}`);
+        }
+        const scenario = {
+            id: randomUUID(),
+            type: normalizeType(input.type),
+            scope: input.scope ?? "global",
+            direction: input.direction ?? "inbound",
+            rate: input.rate ?? 1,
+            enabled: input.enabled ?? true,
+            options: input.options ?? {},
+        };
+        this.scenarios.set(scenario.id, scenario);
+        return scenario;
+    }
+    update(id, patch) {
+        const existing = this.scenarios.get(id);
+        if (!existing)
+            return undefined;
+        const updated = { ...existing, ...patch, id: existing.id, type: existing.type };
+        this.scenarios.set(id, updated);
+        return updated;
+    }
+    remove(id) {
+        return this.scenarios.delete(id);
+    }
+    get(id) {
+        return this.scenarios.get(id);
+    }
+    list() {
+        return [...this.scenarios.values()];
+    }
+    getActiveForPath(path) {
+        return this.list().filter((s) => s.enabled && s.direction === "inbound" && matchesScope(s.scope, path));
+    }
+    /** docs/PRD.md 6.4 — scenarios scoped to an outbound call's destination host instead of a route. */
+    getActiveOutbound(host) {
+        return this.list().filter((s) => s.enabled && s.direction === "outbound" && matchesScope(s.scope, host));
+    }
+    clear() {
+        this.scenarios.clear();
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,41 @@
+/** v2 primitives (PRD docs/PRD.md 6.2) — the ~85-item preset catalog (6.3) all resolve to one of these. */
+export type ScenarioType = "delay" | "error-response" | "connection-reset" | "unavailable" | "malformed-response" | "stale-response";
+/**
+ * v1 type names, kept accepted at registration time so existing configs don't break.
+ * `StateStore.register` normalizes these to their v2 primitive equivalent (see
+ * `LEGACY_TYPE_ALIASES` in state-store.ts) — a stored `ScenarioConfig.type` is always
+ * a `ScenarioType`, never one of these.
+ */
+export type LegacyScenarioType = "random-error" | "random-timeout" | "unavailable-503";
+export type ScenarioScope = "global" | {
+    pattern: string;
+};
+/**
+ * inbound (default) — scope pattern matches request path, e.g. "/orders/*".
+ * outbound (docs/PRD.md 6.4) — scope pattern matches destination host, e.g. "api.stripe.com".
+ */
+export type ScenarioDirection = "inbound" | "outbound";
+export interface ScenarioConfig {
+    id: string;
+    type: ScenarioType;
+    scope: ScenarioScope;
+    direction: ScenarioDirection;
+    /** 0..1 — fraction of matching requests this scenario applies to. */
+    rate: number;
+    enabled: boolean;
+    options: Record<string, unknown>;
+}
+export interface ChaosRequestInfo {
+    method: string;
+    path: string;
+}
+export interface ChaosResponseController {
+    status(code: number): void;
+    header(name: string, value: string): void;
+    send(body?: unknown): void;
+}
+export type ScenarioResult = "continue" | "terminated";
+export type ScenarioHandler = (ctx: {
+    req: ChaosRequestInfo;
+    res: ChaosResponseController;
+}, options: Record<string, unknown>) => Promise<ScenarioResult> | ScenarioResult;

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,9 @@
+import { type Server } from "node:http";
+import type { ActivityLog } from "../../core/activity-log.js";
+import type { StateStore } from "../../core/state-store.js";
+/**
+ * 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.
+ */
+export declare function createControlApi(store: StateStore, activityLog?: ActivityLog): Server;