chaos-injector/README.markdown

Chaos engineering middleware for testing API resilience

# Chaos Injector

Inject chaos into your Express.js APIs to test resilience and fault tolerance.

## Overview

**Chaos Injector** is a lightweight Node.js library designed to simulate real-world failure scenarios in your Express applications. By injecting delays, errors, timeouts, and empty responses, it helps you **test the resilience** and **reliability** of your APIs under unpredictable conditions.

## Features

- 🧪 Inject HTTP errors dynamically
- 🐢 Simulate random response delays
- ⏳ Simulate timeouts
- 🛑 Inject empty or missing responses
- ⚙️ Highly configurable (or use ready-made chaos profiles)
- 🛠️ Minimal setup — simple middleware integration

## Installation

```bash
npm install chaos-injector
```

## Usage

```javascript
const express = require('express');
const { withChaos } = require('chaos-injector');

const app = express();

// Apply chaos injection to a route
app.get('/', withChaos('flakyNetwork'), (req, res) => {
  res.send('Hello, Chaos!');
});

app.listen(3000, () => console.log('Server running on port 3000'));
```

## API

### `withChaos(profileName?, userConfig?)`

| Parameter     | Type   | Description                                      |
|---------------|--------|--------------------------------------------------|
| `profileName` | `string` | (Optional) Name of a predefined chaos profile   |
| `userConfig`  | `object` | (Optional) Custom configuration that overrides the profile |

Returns an Express middleware function that injects chaos according to the configuration.

## Configuration Options

| Option            | Type                | Description                                                  |
|-------------------|---------------------|--------------------------------------------------------------|
| `failureRate`     | `number (0-1)`      | Probability of injecting a failure (default: `0.0`)           |
| `delayRange`      | `[min, max]` array  | Delay response randomly between min and max (ms)              |
| `errorTypes`      | `string[]`          | Array of HTTP error status codes to simulate                  |
| `emptyType`       | `string`            | Type of empty response: `'empty'`, `'empty_object'`, `'empty_array'`, or `'no_data'` |
| `simulateTimeout` | `boolean`           | If `true`, simulates a timeout without sending a response    |

## Chaos Profiles

Predefined profiles for quick setup:

| Profile              | Behavior                                                  |
|----------------------|-----------------------------------------------------------|
| **flakyNetwork**     | Random delays (300-1500ms) + occasional `503`, `504` errors |
| **overloadedServer** | Heavy delays (1200-4000ms) + frequent server errors        |
| **gremlinAttack**    | High error rate across various HTTP error codes           |
| **intermittentEmpty**| Frequent empty successful responses                       |
| **timeoutScenario**  | Very high chance of timeout without a response            |
| **latencySpike**     | Extreme delays (2000-8000ms) without errors                |
| **errorStorm**       | Frequent server-side errors                               |
| **emptyTrap**        | Intermittent empty object responses                       |

### Example: Using a Predefined Profile

```javascript
app.get('/chaos', withChaos('gremlinAttack'), (req, res) => {
  res.send('Chaos injected!');
});
```

### Example: Using Custom Configuration

```javascript
app.get('/test', withChaos({
  delayRange: [100, 300],
  failureRate: 0.2,
  errorTypes: ['500', '400']
}), (req, res) => {
  res.send('This might be slow or fail sometimes.');
});
```

## Error Handling

- If a configured chaos event triggers, the middleware automatically sends a corresponding HTTP error or empty response.
- If invalid config options are provided, the middleware calls `next()` with an `Error`.

## Limitations

- No dynamic adjustment of failure rate over time (planned for future releases).
- No input validation on user config (planned for future enhancement).

## Contributing

Contributions are welcome! 🚀 Please feel free to:

- Submit bug reports
- Suggest new chaos profiles
- Improve documentation
- Add test coverage

To contribute, fork the repository, make your changes, and submit a pull request.

## License

This project is licensed under the [MIT License](LICENSE).

## ✨ Why Chaos Injector?

> **"Everything fails, all the time."** — Werner Vogels, CTO, Amazon.

Test your services like they live in the real, messy, unpredictable internet. 🌎

## Author

Created with ❤️ by [Gopal Vallu](https://www.linkedin.com/in/gopal-vallu-a4822b262/).