mroki

README

Safe shadow traffic testing for production systems.

mroki mirrors live HTTP traffic to a shadow service, diffs the JSON responses, and surfaces the differences — so you can validate changes against real production behavior before rolling out.

See the full screenshot gallery for more views.

Quick Start

# Start the dev stack (PostgreSQL + API + Proxy)
docker compose -f build/dev/compose.yaml up -d

# Create a gate (live/shadow service pair)
curl -s -X POST http://localhost:8090/gates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mroki-dev-api-key-16" \
  -d '{"live_url": "https://httpbin.org/anything?env=live", "shadow_url": "https://httpbin.org/anything?env=shadow"}'

# Send traffic through the proxy
curl http://localhost:8080/get

Responses from both services are compared automatically. Open mroki-hub to browse gates, requests, and diffs.

See the Quick Start Guide for the full walkthrough.

How It Works

A gate is a pair of services: a live (production) URL and a shadow (experimental) URL.

A proxy forwards each request to both services and sends the raw responses to the API — without affecting the live response. The API computes the JSON diff server-side.

The hub is a web UI for managing gates, browsing captured requests, and visualizing response diffs side-by-side.

Architecture

graph TD
    Client([Client]) -->|HTTP Request| Proxy[mroki-proxy]
    Proxy -->|Forward| Live[Live Service]
    Proxy -->|Forward| Shadow[Shadow Service]
    Live -->|Live Response| Proxy
    Shadow -->|Shadow Response| Proxy
    Proxy -->|Return live response| Client
    Proxy -.->|Send raw responses| API[mroki-api<br><i>REST API + Diff</i>]
    API -->|Store| DB[(PostgreSQL)]
    Hub[mroki-hub<br><i>Web UI</i>] -->|Query| API

Components

Component	Description	Docs
mroki-proxy	HTTP proxy — forwards traffic to live and shadow, sends responses to API	docs
mroki-api	REST API — gate management, request/diff storage, server-side diff computation	docs
mroki-hub	Web UI — gate dashboard, request browser, diff viewer	docs
caddy-mroki	Caddy module — standalone shadow diffing embedded in Caddy server	docs

Use Cases

API refactoring — Test refactored endpoints against real production traffic to catch behavioral regressions before they ship.

Database migrations — Run your new schema in shadow mode and verify it returns identical results to the current one.

Framework upgrades — Upgrade your framework on the shadow service and validate with real request patterns, not synthetic tests.

Documentation

• Quick Start — Get running in 5 minutes
• Development — Local setup, testing, code style
• Deployment — Production deployment with Docker Compose and Kubernetes
• System Overview — Architecture and data flow
• API Contracts — Endpoint specifications
• Roadmap

Development

# Start dev stack
make dev-up

# Run all tests
make test

# Build all binaries
make build

# Lint
make lint

See the Development Guide for the full workflow.

Contributing

Contributions welcome. Please read the Contributing Guide before submitting PRs.

This project follows the Contributor Covenant Code of Conduct.

License

MIT