Record HTTP interactions in versioned .eggr fixtures. Replay them without an
origin, or send the recorded requests to a live service and compare responses.
EggReplay owns the semantic layer: flows, matching, scenarios, redaction, comparison, and reporting. HTTP, TLS, framing, inbound serving, and route establishment are delegated to EggFetch, EggServe, and Eggress.
The CLI is not yet published on crates.io. Install it from source with Rust 1.89 or newer:
git clone https://github.com/eggstack/eggreplay.git
cd eggreplay
cargo install --path crates/eggreplay-cli
eggreplay --versionTo include the optional HTTP/1.1 proxy and HTTPS interception commands, add
--features intercept to cargo install.
This records a request, stops the origin, then serves the fixture offline. It
requires Python 3 and curl. Use two terminals. Keep the first terminal in the
same shell so its ORIGIN_PID variable remains available.
In terminal 1, start the temporary origin and recorder:
mkdir -p eggr-quickstart
cd eggr-quickstart
printf '%s\n' '{"greeting":"hello"}' > api.json
python3 -m http.server 9100 --bind 127.0.0.1 &
ORIGIN_PID=$!
eggreplay record --listen 127.0.0.1:8080 \
--upstream http://127.0.0.1:9100 --fixture demo.eggrWhile record is running, use terminal 2 to make a request through the
gateway:
curl http://127.0.0.1:8080/api.jsonPress Ctrl-C in terminal 1 to finalize the fixture. Then stop the origin and
start offline replay in terminal 1:
kill "$ORIGIN_PID"
wait "$ORIGIN_PID" 2>/dev/null || true
eggreplay serve --fixture demo.eggr --listen 127.0.0.1:9100In terminal 2, request the recorded origin again:
curl http://127.0.0.1:9100/api.jsonThe response comes from demo.eggr; no origin is running. Press Ctrl-C in
terminal 1 to stop the replay server. Replay matches the recorded upstream
authority, here 127.0.0.1:9100, and consumes each flow once.
For a full walkthrough, including validation, live regression, and redaction, see the Quickstart guide.
| Capability | Availability |
|---|---|
| HTTP/1.1 recording, offline replay, and live regression | CLI default |
| HAR 1.2 import and export | CLI default; lossy, with a loss report |
| WebSocket conversation recording and replay | Supported; recording requires --websockets |
| Eggress routing | Available in the CLI; direct is the default |
| Outbound and inbound HTTP/2 | Optional CLI features; experimental |
| gRPC-derived views | Optional eggreplay-http/grpc feature; experimental |
| HTTP/1.1 proxy, CONNECT policy, and HTTPS MITM | Optional intercept feature; policy-gated |
HTTP/2 is never enabled by default. See the protocol support matrix and unsupported capabilities for details and limitations.
| Guide | Covers |
|---|---|
| Quickstart | Record, inspect, replay, and regress a fixture |
| CLI and exit contracts | Commands, flags, exit codes, and output formats |
| Configuration | Matcher, timing, recording, and route settings |
| Matcher profiles | Matching behavior and flow consumption |
| Regression cookbook | replay, test, and diff |
.eggr schema |
Fixture layout, extensions, bounds, and integrity |
| HAR interchange | Import/export behavior and known data loss |
| HTTP/2 support | H2 and gRPC tiers and limitations |
| Interception threat model | Proxy, CONNECT policy, and MITM boundaries |
| CA and trust | CA lifecycle and manual trust setup |
| Non-goals | Deliberate exclusions and redaction limits |
| Python bindings | Python package and pytest integration |
| Testing | Local checks and CI qualification |
For the design and crate boundaries, see Architecture and
the architecture index. For repository contribution
rules, start with AGENTS.md.
Python bindings are distributed separately as an abi3 wheel. The default wheel excludes interception and multiprotocol serving. To develop locally:
cd crates/eggreplay-python
uv sync --extra dev
maturin developSee the Python package guide.
cargo fmt --all -- --check \
&& cargo check --workspace --all-targets --all-features \
&& cargo clippy --workspace --all-targets --all-features -- -D warnings \
&& cargo test --workspace --all-featuresCI also uses --locked and --no-fail-fast, plus architecture boundary lanes.
A passing test suite alone does not prove the dependency and protocol boundaries
are intact. See AGENTS.md and the
planning registry.
Contributing and security reports: CONTRIBUTING.md, SECURITY.md.
MIT. See LICENSE-MIT.