🚦 Traffic Mirror (http-log-replay)

Regressions No More. Record production traffic and replay it against your changes to verify correctness with zero effort.

Traffic Mirror is a powerful regression testing tool designed for modern engineering teams. It allows you to record HTTP traffic from a live environment (like Production) and replay it against two different target environments (e.g., Stable vs. Canary) to instantly detect regressions, bugs, or side-effects.

📋 Table of Contents

• 🌟 Features
• 🚀 Quick Start (Zero Setup)
• 💻 Usage Guide: Web UI
• 🖥️ Usage Guide: CLI
• 🐳 Usage Guide: Docker
• 🛠️ Development & Contribution
• 📦 Maintenance

🌟 Features

• 🛡️ Zero-Config Recording: Acts as a transparent HTTP proxy to capture real requests.
• ⚡ High-Performance Replay: Replay thousands of requests in parallel with customizable concurrency.
• 🔍 Intelligent Diffing: compares JSON responses and ignores dynamic fields (like timestamps, UUIDs) that cause false positives.
• 📊 Rich Reporting: Generates detailed HTML reports showing exactly what broke.
• 🔌 Swagger Integration: Auto-generate test traffic from your OpenAPI definitions if you don't have live traffic.
• 🏗️ Two Modes: Full interactive Web UI for debugging and a lightweight CLI for CI/CD pipelines.

🚀 Quick Start (Zero Setup)

You don't need to install anything if you have Node.js (v18+) installed. Just run:

npx http-log-replay ui --port 4200

This will launch the Traffic Mirror Dashboard at http://localhost:4200.

💻 Usage Guide: Web UI

The Web UI is the best way to get started. It guides you through the entire workflow in three simple tabs.

1. 🔴 Record / Generate

• Manual Mode: Start the proxy, point your application/client to it, and select desired HTTP methods (e.g., GET, POST).
• Auto-Generate: Upload an OpenAPI/Swagger JSON file to automatically generate realistic traffic patterns.
• YAML Config Mode: Load a config.yaml file to pre-configure Traffic Generation (target, source, exclusions, timeouts, methods).

2. ▶️ Replay

• Configure your Primary (Stable) and Secondary (Test) environments.
• Set Concurrency to speed up large suites.
• Add Ignore Fields (e.g., createdAt, traceId) to filter out noise in the comparison.
• Click Replay & Compare.

3. 📄 Report

• Instantly view the results.
• Green: Exact match.
• Red: Mismatch (click to expand the JSON diff).

🖥️ Usage Guide: CLI

Perfect for CI/CD pipelines or headless environments.

1. Record Traffic

Start a recording proxy on port 3000 forwarding to your real API at localhost:8080.

# Run from source
node index.js record --target http://localhost:8080 --port 3000 --out traffic.jsonl

2. Auto-Generate from Swagger

Generate traffic without manual clicking. You can use command line flags or a YAML configuration file.

Using Configuration File (Recommended):

node index.js generate --config config.example.yaml

Using Flags:

node index.js generate --file ./openapi.json --target http://localhost:3000

3. Replay & Verify

Replay recorded traffic against two environments and generate an HTML report.

node index.js replay \
  --log traffic.jsonl \
  --primary http://prod-api.com \
  --secondary http://staging-api.com \
  --report report.html \
  --ignore "timestamp,id"

🐳 Usage Guide: Docker

We provide optimized Docker images for both the UI and CLI.

Prerequisites

• Docker & Docker Compose installed.

Option A: Complete Environment (Recommended)

Use the included docker-compose.yml to run everything.

Start the GUI:

docker-compose up gui

Access at http://localhost:4200. Data is persisted to your host folder.

Run CLI Commands:

docker-compose run cli record --target http://host.docker.internal:8080 ...

Option B: Manual Docker Run

UI Image:

docker run -p 4200:4200 -v $(pwd):/app traffic-mirror-gui

CLI Image:

docker run -v $(pwd):/app traffic-mirror-cli --help

🛠️ Development & Contribution

We welcome contributions! Here is how to run the project locally for development.

1. Setup

git clone https://github.com/your-username/http-log-replay.git
cd http-log-replay
npm install

2. Build the UI

The UI is built with Angular. You must build it before running the app.

cd ui
npm install
npm run build
cd ..

3. Run Locally (Dev Mode)

# Start the full app (Frontend + Backend)
node index.js ui --port 4200

4. Testing & Code Quality

We use Jest for testing and ESLint for code quality.

# Run Unit Tests
npm test

# Lint Code
npm run lint

# Format Code
npm run format

# Production Start (PM2)
npm run start:pm2

5. Contribution Guidelines

We use Semantic Release to automate version management and package publishing. To ensure this works correctly, please follow the Conventional Commits specification for your commit messages.

Commit Message Format:

<type>(<scope>): <subject>

Common Types:

• feat: A new feature (triggers a MINOR release).
• fix: A bug fix (triggers a PATCH release).
• docs: Documentation only changes (triggers a PATCH release).
• refactor: A code change that neither fixes a bug nor adds a feature (triggers a PATCH release).
• perf, test, ci, chore: Changes that do not trigger a release (unless configured otherwise).

📦 Maintenance

Publishing to NPM

1. Bump Version: Update version in package.json.
2. Build UI: The prepublishOnly script will automatically build the Angular UI.
3. Publish:

   npm publish

File Structure

• index.js: CLI entry point.
• recorder.js: Proxy logic.
• replayer.js: Replay & Diff logic.
• server.js: Express server for the UI.
• ui/: Angular frontend source code.
• tests/: Jest unit tests.

Built with ❤️ by the Traffic Mirror Team.