Failure Lab

Local chaos engineering tool for developers. Inject faults into HTTP traffic via a local proxy — without changing your application code.

Overview

Failure Lab sits between your application and the network as a transparent HTTP proxy. You define rules that match requests by host, path, method, or headers, and the proxy injects faults on matching traffic. A VS Code extension provides a sidebar UI for managing rules in real time.

Architecture

Your App  --->  Failure Lab Proxy (:7777)  --->  Target Server
                       |
                 Control API (:7778)
                       |
                VS Code Extension

• Core — Java 21 + Netty. HTTP proxy on port 7777, REST API on port 7778.
• VS Code Extension — TypeScript. Sidebar with rule management, live stats, latency chart, presets, and import/export.

Fault Types

Type	Description
Fixed Delay	Adds constant latency to responses
Jitter	Adds random latency within a configurable range
Fail Rate	Returns error status codes at a percentage rate
Timeout	Holds the connection open without responding
Status Override	Replaces the response with a custom status code and body
Drop Connection	Closes the socket abruptly

Quick Start

1. Build and run the core

cd core
./gradlew shadowJar
java -jar build/libs/failure-lab-core-1.0-SNAPSHOT-all.jar

2. Configure your application to use the proxy

export HTTP_PROXY=http://localhost:7777

3. Create a fault rule

curl -X POST http://localhost:7778/rules \
  -H "Content-Type: application/json" \
  -d '{"host":"api.example.com","fault":{"type":"FIXED_DELAY","delayMs":2000}}'

4. Enable chaos

curl -X POST http://localhost:7778/toggle

5. Test

curl -x http://localhost:7777 http://api.example.com/endpoint

VS Code Extension

Install from the VS Code Marketplace or build locally:

cd vscode-extension
npm install
npm run compile
npx vsce package

The extension provides:

• Auto-start of the Java core process
• Sidebar dashboard with real-time stats and latency chart
• Rule creation, editing, enable/disable, and deletion
• Quick presets for common fault scenarios
• Import/export of rule configurations

Rule Matching

Rules match requests based on the following fields (all optional except host):

Field	Example	Specificity Score
host	api.example.com	+1
pathPrefix	/v1/users	+2
method	GET	+4
headerKey/headerValue	X-Env: dev	+8

When multiple rules match a request, the most specific rule (highest score) is applied.

API Endpoints

Method	Path	Description
GET	/health	Health check
GET	/rules	List all rules
POST	/rules	Create a rule
PUT	/rules/{id}	Update a rule
DELETE	/rules/{id}	Delete a rule
POST	/toggle	Toggle chaos on/off
GET	/stats	Request and fault counters
GET	/events	Recent fault injection events

HTTPS Limitations

HTTP traffic gets full fault injection. HTTPS traffic passes through unmodified via CONNECT tunneling (the proxy cannot inspect encrypted traffic without MITM certificates).

Project Structure

core/               Java 21 proxy + API (Netty, Gradle)
vscode-extension/   VS Code sidebar extension (TypeScript)
samples/            Example configurations and test scripts

Requirements

• Java 21 or later
• Node.js 18+ (for building the extension)

License

MIT