faultmesh 1.0.0

package/dist/engine/ControlApi.d.ts

@@ -0,0 +1,24 @@
+import { ToxicPipeline } from './ToxicPipeline.js';
+import { TelemetryHub } from './TelemetryHub.js';
+import { ResilienceScorer } from '../scorer/ResilienceScorer.js';
+import { SecurityAuditor } from '../scorer/SecurityAuditor.js';
+import { TrafficStormAuditor } from '../scorer/TrafficStormAuditor.js';
+export declare class ControlApi {
+    private server;
+    private port;
+    private pipeline;
+    private telemetryHub;
+    private scorer;
+    private securityAuditor;
+    private trafficStormAuditor;
+    private dashboardDir;
+    private isRunning;
+    constructor(port: number, pipeline: ToxicPipeline, telemetryHub: TelemetryHub, scorer: ResilienceScorer, securityAuditor?: SecurityAuditor, trafficStormAuditor?: TrafficStormAuditor, dashboardDir?: string);
+    private handleRequest;
+    private serveStatic;
+    private readBody;
+    private json;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getPort(): number;
+}

package/dist/engine/ControlApi.js

@@ -0,0 +1,269 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SecurityAuditor } from '../scorer/SecurityAuditor.js';
+import { TrafficStormAuditor } from '../scorer/TrafficStormAuditor.js';
+export class ControlApi {
+    server;
+    port = 0;
+    pipeline;
+    telemetryHub;
+    scorer;
+    securityAuditor;
+    trafficStormAuditor;
+    dashboardDir;
+    isRunning = false;
+    constructor(port, pipeline, telemetryHub, scorer, securityAuditor, trafficStormAuditor, dashboardDir) {
+        this.port = port;
+        this.pipeline = pipeline;
+        this.telemetryHub = telemetryHub;
+        this.scorer = scorer;
+        this.securityAuditor = securityAuditor || new SecurityAuditor('http://127.0.0.1:3001');
+        this.trafficStormAuditor = trafficStormAuditor || new TrafficStormAuditor('http://127.0.0.1:3001');
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        let resolvedDir = dashboardDir || path.resolve(currentDir, '../dashboard');
+        if (!fs.existsSync(resolvedDir)) {
+            const fallbackDir = path.resolve(currentDir, '../../src/dashboard');
+            if (fs.existsSync(fallbackDir)) {
+                resolvedDir = fallbackDir;
+            }
+        }
+        this.dashboardDir = resolvedDir;
+        this.server = http.createServer((req, res) => this.handleRequest(req, res));
+    }
+    async handleRequest(req, res) {
+        const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+        const pathname = url.pathname;
+        // Enable CORS for local dashboards or external runners
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // 1. SSE Stream
+        if (pathname === '/_faultmesh/telemetry/stream' && req.method === 'GET') {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+            });
+            this.telemetryHub.registerSSEClient(res);
+            return;
+        }
+        // 2. Status & Metrics
+        if (pathname === '/_faultmesh/status' && req.method === 'GET') {
+            const rules = this.pipeline.getRules();
+            this.json(res, 200, {
+                status: 'online',
+                engine: 'FaultMesh v1.0.0',
+                metrics: this.telemetryHub.getMetrics(),
+                activeRules: rules,
+                activeToxics: rules, // backward compatibility
+            });
+            return;
+        }
+        // 3. Rules List
+        if ((pathname === '/_faultmesh/rules' || pathname === '/_faultmesh/toxics') && req.method === 'GET') {
+            this.json(res, 200, this.pipeline.getRules());
+            return;
+        }
+        // 4. Add / Update Rule
+        if ((pathname === '/_faultmesh/rules' || pathname === '/_faultmesh/toxics') && req.method === 'POST') {
+            const body = await this.readBody(req);
+            try {
+                const rule = JSON.parse(body);
+                if (!rule.id || !rule.type || !rule.config) {
+                    this.json(res, 400, { error: 'Invalid rule definition. Required: id, type, config' });
+                    return;
+                }
+                this.pipeline.addRule(rule);
+                this.json(res, 201, { success: true, rule });
+            }
+            catch (err) {
+                this.json(res, 400, { error: 'Malformed JSON payload', details: err.message });
+            }
+            return;
+        }
+        // 5. Delete Rule
+        const isDeleteSpecific = pathname.startsWith('/_faultmesh/rules/') || pathname.startsWith('/_faultmesh/toxics/');
+        if (isDeleteSpecific && req.method === 'DELETE') {
+            const prefix = pathname.startsWith('/_faultmesh/rules/') ? '/_faultmesh/rules/' : '/_faultmesh/toxics/';
+            const id = pathname.substring(prefix.length);
+            const removed = this.pipeline.removeRule(id);
+            this.json(res, removed ? 200 : 404, { success: removed, id });
+            return;
+        }
+        if ((pathname === '/_faultmesh/rules' || pathname === '/_faultmesh/toxics') && req.method === 'DELETE') {
+            this.pipeline.clearRules();
+            this.json(res, 200, { success: true, message: 'All simulation rules cleared' });
+            return;
+        }
+        // 6. Run Diagnostics / Health Check
+        const isRunTests = pathname === '/_faultmesh/diagnostics/run' || pathname === '/_faultmesh/tests/run' || pathname === '/_faultmesh/gauntlet/run';
+        if (isRunTests && req.method === 'POST') {
+            try {
+                let profile = 'resilient';
+                const queryProfile = url.searchParams.get('profile');
+                if (queryProfile === 'fragile' || queryProfile === 'resilient') {
+                    profile = queryProfile;
+                }
+                else {
+                    const body = await this.readBody(req);
+                    if (body) {
+                        try {
+                            const parsed = JSON.parse(body);
+                            if (parsed.profile === 'fragile' || parsed.profile === 'resilient') {
+                                profile = parsed.profile;
+                            }
+                        }
+                        catch { }
+                    }
+                }
+                const scorecard = await this.scorer.runGauntlet(profile);
+                this.json(res, 200, scorecard);
+            }
+            catch (err) {
+                this.json(res, 500, { error: 'Diagnostics execution error', details: err.message });
+            }
+            return;
+        }
+        // 7. Run Security & Protocol Audit
+        const isRunSecurity = pathname === '/_faultmesh/security/run' || pathname === '/_faultmesh/security/audit';
+        if (isRunSecurity && req.method === 'POST') {
+            try {
+                let profile = 'secure';
+                const queryProfile = url.searchParams.get('profile');
+                if (queryProfile === 'secure' || queryProfile === 'vulnerable') {
+                    profile = queryProfile;
+                }
+                else {
+                    const body = await this.readBody(req);
+                    if (body) {
+                        try {
+                            const parsed = JSON.parse(body);
+                            if (parsed.profile === 'secure' || parsed.profile === 'vulnerable') {
+                                profile = parsed.profile;
+                            }
+                        }
+                        catch { }
+                    }
+                }
+                const scorecard = await this.securityAuditor.runAudit(profile);
+                this.json(res, 200, scorecard);
+            }
+            catch (err) {
+                this.json(res, 500, { error: 'Security audit execution error', details: err.message });
+            }
+            return;
+        }
+        // 8. Run Traffic Storm & DoS Resilience Audit
+        const isRunStorm = pathname === '/_faultmesh/storm/run' || pathname === '/_faultmesh/storm/audit';
+        if (isRunStorm && req.method === 'POST') {
+            try {
+                let profile = 'resilient';
+                const queryProfile = url.searchParams.get('profile');
+                if (queryProfile === 'fragile' || queryProfile === 'resilient') {
+                    profile = queryProfile;
+                }
+                else {
+                    const body = await this.readBody(req);
+                    if (body) {
+                        try {
+                            const parsed = JSON.parse(body);
+                            if (parsed.profile === 'fragile' || parsed.profile === 'resilient') {
+                                profile = parsed.profile;
+                            }
+                        }
+                        catch { }
+                    }
+                }
+                const scorecard = await this.trafficStormAuditor.runStormSuite(profile);
+                this.json(res, 200, scorecard);
+            }
+            catch (err) {
+                this.json(res, 500, { error: 'Traffic storm execution error', details: err.message });
+            }
+            return;
+        }
+        // 9. Static Dashboard Serving
+        if (req.method === 'GET') {
+            this.serveStatic(pathname, res);
+            return;
+        }
+        this.json(res, 404, { error: 'Route not found' });
+    }
+    serveStatic(pathname, res) {
+        const safePath = pathname === '/' ? 'index.html' : pathname.replace(/^\//, '');
+        const filePath = path.join(this.dashboardDir, safePath);
+        // Prevent directory traversal
+        if (!filePath.startsWith(this.dashboardDir)) {
+            this.json(res, 403, { error: 'Forbidden' });
+            return;
+        }
+        if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+            const ext = path.extname(filePath);
+            const contentTypes = {
+                '.html': 'text/html',
+                '.css': 'text/css',
+                '.js': 'application/javascript',
+                '.json': 'application/json',
+                '.svg': 'image/svg+xml',
+            };
+            res.writeHead(200, { 'Content-Type': contentTypes[ext] || 'text/plain' });
+            fs.createReadStream(filePath).pipe(res);
+        }
+        else {
+            // Fallback to index.html for SPA if exists
+            const indexPath = path.join(this.dashboardDir, 'index.html');
+            if (fs.existsSync(indexPath)) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                fs.createReadStream(indexPath).pipe(res);
+            }
+            else {
+                this.json(res, 404, { error: 'File not found' });
+            }
+        }
+    }
+    readBody(req) {
+        return new Promise((resolve, reject) => {
+            let data = '';
+            req.on('data', chunk => data += chunk);
+            req.on('end', () => resolve(data));
+            req.on('error', reject);
+        });
+    }
+    json(res, status, data) {
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(data));
+    }
+    start() {
+        return new Promise((resolve, reject) => {
+            this.server.listen(this.port, () => {
+                const address = this.server.address();
+                if (address && typeof address === 'object') {
+                    this.port = address.port;
+                }
+                this.isRunning = true;
+                resolve();
+            });
+            this.server.once('error', reject);
+        });
+    }
+    stop() {
+        return new Promise((resolve) => {
+            if (!this.isRunning)
+                return resolve();
+            this.server.close(() => {
+                this.isRunning = false;
+                resolve();
+            });
+        });
+    }
+    getPort() {
+        return this.port;
+    }
+}

package/dist/engine/FaultMeshProxy.d.ts

@@ -0,0 +1,16 @@
+import { ProxyConfig } from '../types.js';
+import { ToxicPipeline } from './ToxicPipeline.js';
+import { TelemetryHub } from './TelemetryHub.js';
+export declare class FaultMeshProxy {
+    private server;
+    private port;
+    private config;
+    private toxicPipeline;
+    private telemetryHub;
+    private isRunning;
+    constructor(config: ProxyConfig, toxicPipeline: ToxicPipeline, telemetryHub: TelemetryHub);
+    private handleRequest;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getPort(): number;
+}

package/dist/engine/FaultMeshProxy.js

@@ -0,0 +1,167 @@
+import http from 'node:http';
+export class FaultMeshProxy {
+    server;
+    port = 0;
+    config;
+    toxicPipeline;
+    telemetryHub;
+    isRunning = false;
+    constructor(config, toxicPipeline, telemetryHub) {
+        this.config = config;
+        this.toxicPipeline = toxicPipeline;
+        this.telemetryHub = telemetryHub;
+        this.server = http.createServer((req, res) => this.handleRequest(req, res));
+    }
+    async handleRequest(req, res) {
+        const startTime = Date.now();
+        const requestId = `req_${Math.random().toString(36).substring(2, 9)}`;
+        this.telemetryHub.recordRequestStart();
+        const appliedToxics = [];
+        let bytesReceived = 0;
+        let bytesSent = 0;
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204, {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
+                'Access-Control-Allow-Headers': '*',
+            });
+            res.end();
+            return;
+        }
+        // 1. Check for immediate downstream Status override toxic
+        const statusToxic = this.toxicPipeline.getActiveStatusToxic('downstream');
+        if (statusToxic) {
+            appliedToxics.push(`Status (${statusToxic.statusCode})`);
+            const body = statusToxic.responseBody || JSON.stringify({
+                error: statusToxic.statusMessage,
+                code: statusToxic.statusCode,
+                faultMesh: true,
+            });
+            res.writeHead(statusToxic.statusCode, {
+                'Content-Type': 'application/json',
+                'X-FaultMesh-Injected': 'status',
+                'Access-Control-Allow-Origin': '*',
+            });
+            res.end(body);
+            this.telemetryHub.recordRequestComplete({
+                id: requestId,
+                timestamp: startTime,
+                method: req.method || 'GET',
+                path: req.url || '/',
+                statusCode: statusToxic.statusCode,
+                durationMs: Date.now() - startTime,
+                bytesReceived: 0,
+                bytesSent: Buffer.byteLength(body),
+                appliedToxics,
+            });
+            return;
+        }
+        // 2. Prepare Upstream forwarding
+        const targetUrl = new URL(req.url || '/', this.config.targetUrl);
+        const options = {
+            protocol: targetUrl.protocol,
+            hostname: targetUrl.hostname,
+            port: targetUrl.port,
+            path: targetUrl.pathname + targetUrl.search,
+            method: req.method,
+            headers: { ...req.headers, host: targetUrl.host },
+        };
+        const upstreamReq = http.request(options, async (upstreamRes) => {
+            // 3. Prepare Downstream transformers
+            const { transformers: downstreamTransformers, appliedNames } = this.toxicPipeline.createStreamTransformers('downstream');
+            appliedToxics.push(...appliedNames);
+            const headers = { ...upstreamRes.headers };
+            delete headers['content-length']; // Length changes if chunks are compressed, cut, or padded
+            headers['x-faultmesh-proxy'] = 'active';
+            headers['access-control-allow-origin'] = '*';
+            res.writeHead(upstreamRes.statusCode || 200, headers);
+            try {
+                if (downstreamTransformers.length > 0) {
+                    // Chain transformers between upstreamRes and client res
+                    let currentStream = upstreamRes;
+                    for (const t of downstreamTransformers) {
+                        currentStream = currentStream.pipe(t);
+                    }
+                    currentStream.on('data', (chunk) => {
+                        bytesSent += chunk.length;
+                        res.write(chunk);
+                    });
+                    currentStream.on('end', () => {
+                        res.end();
+                        finishTelemetry(upstreamRes.statusCode || 200);
+                    });
+                    currentStream.on('error', (err) => {
+                        res.destroy(err);
+                        finishTelemetry(upstreamRes.statusCode || 200, err.message);
+                    });
+                }
+                else {
+                    upstreamRes.on('data', (chunk) => {
+                        bytesSent += chunk.length;
+                        res.write(chunk);
+                    });
+                    upstreamRes.on('end', () => {
+                        res.end();
+                        finishTelemetry(upstreamRes.statusCode || 200);
+                    });
+                }
+            }
+            catch (err) {
+                res.destroy(err);
+                finishTelemetry(502, err.message);
+            }
+        });
+        const finishTelemetry = (statusCode, error) => {
+            this.telemetryHub.recordRequestComplete({
+                id: requestId,
+                timestamp: startTime,
+                method: req.method || 'GET',
+                path: req.url || '/',
+                statusCode,
+                durationMs: Date.now() - startTime,
+                bytesReceived,
+                bytesSent,
+                appliedToxics,
+                error,
+            });
+        };
+        upstreamReq.on('error', (err) => {
+            if (!res.headersSent) {
+                res.writeHead(502, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Upstream connection failed', details: err.message }));
+            }
+            finishTelemetry(502, err.message);
+        });
+        req.on('data', (chunk) => {
+            bytesReceived += chunk.length;
+        });
+        // Forward request body to upstream
+        req.pipe(upstreamReq);
+    }
+    start() {
+        return new Promise((resolve, reject) => {
+            this.server.listen(this.config.port, () => {
+                const address = this.server.address();
+                if (address && typeof address === 'object') {
+                    this.port = address.port;
+                }
+                this.isRunning = true;
+                resolve();
+            });
+            this.server.once('error', reject);
+        });
+    }
+    stop() {
+        return new Promise((resolve) => {
+            if (!this.isRunning)
+                return resolve();
+            this.server.close(() => {
+                this.isRunning = false;
+                resolve();
+            });
+        });
+    }
+    getPort() {
+        return this.port;
+    }
+}

package/dist/engine/TelemetryHub.d.ts

@@ -0,0 +1,16 @@
+import { ServerResponse } from 'node:http';
+import { ProxyMetrics, TelemetryEvent } from '../types.js';
+export declare class TelemetryHub {
+    private metrics;
+    private recentEvents;
+    private readonly maxRecentEvents;
+    private sseClients;
+    private latencySum;
+    recordRequestStart(): void;
+    recordRequestComplete(event: TelemetryEvent): void;
+    getMetrics(): ProxyMetrics;
+    getRecentEvents(): TelemetryEvent[];
+    registerSSEClient(res: ServerResponse): void;
+    private broadcastSSE;
+    clear(): void;
+}

package/dist/engine/TelemetryHub.js

@@ -0,0 +1,67 @@
+export class TelemetryHub {
+    metrics = {
+        totalRequests: 0,
+        activeConnections: 0,
+        bytesProxied: 0,
+        faultsInjected: 0,
+        avgLatencyMs: 0,
+    };
+    recentEvents = [];
+    maxRecentEvents = 50;
+    sseClients = new Set();
+    latencySum = 0;
+    recordRequestStart() {
+        this.metrics.totalRequests++;
+        this.metrics.activeConnections++;
+    }
+    recordRequestComplete(event) {
+        this.metrics.activeConnections = Math.max(0, this.metrics.activeConnections - 1);
+        this.metrics.bytesProxied += event.bytesReceived + event.bytesSent;
+        this.metrics.faultsInjected += event.appliedToxics.length;
+        this.latencySum += event.durationMs;
+        this.metrics.avgLatencyMs = Math.round(this.latencySum / this.metrics.totalRequests);
+        // Keep ring buffer
+        this.recentEvents.unshift(event);
+        if (this.recentEvents.length > this.maxRecentEvents) {
+            this.recentEvents.pop();
+        }
+        // Broadcast to live SSE subscribers
+        this.broadcastSSE('telemetry', event);
+    }
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    getRecentEvents() {
+        return [...this.recentEvents];
+    }
+    registerSSEClient(res) {
+        this.sseClients.add(res);
+        // Send initial snapshot
+        res.write(`event: snapshot\ndata: ${JSON.stringify({ metrics: this.metrics, events: this.recentEvents })}\n\n`);
+        res.on('close', () => {
+            this.sseClients.delete(res);
+        });
+    }
+    broadcastSSE(eventType, data) {
+        const payload = `event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`;
+        for (const client of this.sseClients) {
+            try {
+                client.write(payload);
+            }
+            catch {
+                this.sseClients.delete(client);
+            }
+        }
+    }
+    clear() {
+        this.metrics = {
+            totalRequests: 0,
+            activeConnections: 0,
+            bytesProxied: 0,
+            faultsInjected: 0,
+            avgLatencyMs: 0,
+        };
+        this.latencySum = 0;
+        this.recentEvents = [];
+    }
+}

package/dist/engine/ToxicPipeline.d.ts

@@ -0,0 +1,22 @@
+import { Transform } from 'node:stream';
+import { ToxicRule, ToxicStreamDirection } from '../types.js';
+import { StatusToxic } from '../toxics/StatusToxic.js';
+export declare class ToxicPipeline {
+    private rules;
+    addRule(rule: ToxicRule): void;
+    removeRule(id: string): boolean;
+    getRules(): ToxicRule[];
+    getRule(id: string): ToxicRule | undefined;
+    clearRules(): void;
+    /**
+     * Check if any active StatusToxic exists for the specified direction
+     */
+    getActiveStatusToxic(direction: ToxicStreamDirection): StatusToxic | null;
+    /**
+     * Create an array of streaming transformers for the specified stream direction
+     */
+    createStreamTransformers(direction: ToxicStreamDirection): {
+        transformers: Transform[];
+        appliedNames: string[];
+    };
+}

package/dist/engine/ToxicPipeline.js

@@ -0,0 +1,67 @@
+import { LatencyToxic } from '../toxics/LatencyToxic.js';
+import { BandwidthToxic } from '../toxics/BandwidthToxic.js';
+import { CutToxic } from '../toxics/CutToxic.js';
+import { CorruptToxic } from '../toxics/CorruptToxic.js';
+import { StatusToxic } from '../toxics/StatusToxic.js';
+export class ToxicPipeline {
+    rules = new Map();
+    addRule(rule) {
+        this.rules.set(rule.id, rule);
+    }
+    removeRule(id) {
+        return this.rules.delete(id);
+    }
+    getRules() {
+        return Array.from(this.rules.values());
+    }
+    getRule(id) {
+        return this.rules.get(id);
+    }
+    clearRules() {
+        this.rules.clear();
+    }
+    /**
+     * Check if any active StatusToxic exists for the specified direction
+     */
+    getActiveStatusToxic(direction) {
+        for (const rule of this.rules.values()) {
+            if (rule.enabled && rule.type === 'status' && rule.direction === direction) {
+                return new StatusToxic(rule.config);
+            }
+        }
+        return null;
+    }
+    /**
+     * Create an array of streaming transformers for the specified stream direction
+     */
+    createStreamTransformers(direction) {
+        const transformers = [];
+        const appliedNames = [];
+        for (const rule of this.rules.values()) {
+            if (!rule.enabled || rule.direction !== direction)
+                continue;
+            switch (rule.type) {
+                case 'latency':
+                    transformers.push(new LatencyToxic(rule.config));
+                    appliedNames.push(`Latency (${rule.name})`);
+                    break;
+                case 'bandwidth':
+                    transformers.push(new BandwidthToxic(rule.config));
+                    appliedNames.push(`Bandwidth (${rule.name})`);
+                    break;
+                case 'cut':
+                    transformers.push(new CutToxic(rule.config));
+                    appliedNames.push(`Cut (${rule.name})`);
+                    break;
+                case 'corrupt':
+                    transformers.push(new CorruptToxic(rule.config));
+                    appliedNames.push(`Corrupt (${rule.name})`);
+                    break;
+                case 'status':
+                    // Status toxics are handled at the HTTP response header layer, not stream byte level
+                    break;
+            }
+        }
+        return { transformers, appliedNames };
+    }
+}

package/dist/scorer/ResilienceScorer.d.ts

@@ -0,0 +1,13 @@
+import { ResilienceScorecard } from '../types.js';
+import { ToxicPipeline } from '../engine/ToxicPipeline.js';
+export declare class ResilienceScorer {
+    private proxyUrl;
+    private pipeline;
+    constructor(proxyUrl: string, pipeline: ToxicPipeline);
+    runGauntlet(profile?: 'resilient' | 'fragile'): Promise<ResilienceScorecard>;
+    private testLatencySpike;
+    private testBandwidthConstraint;
+    private testConnectionCut;
+    private testPayloadCorruption;
+    private testServiceOutage;
+}