Skip to content

Latest commit

 

History

History
181 lines (158 loc) · 10.7 KB

cli.md

File metadata and controls

181 lines (158 loc) · 10.7 KB

CLI and exit contracts

Every result-producing command accepts --output human|json|junit (JUnit is meaningful for replay/test/diff; other commands project a single assertion). The flag is per-subcommand, not global. It must follow the command name (eggreplay validate --output json). JSON is a versioned envelope (command, schema_version, success, failure_class, warnings, payload); stdout carries JSON/JUnit, stderr carries {failure_class}: {message} diagnostics that agree with the envelope. Human rendering is terminal text (ok/failed (...)), never machine JSON, and is not a parsing contract. schema_version on the envelope is 1 and is a separate counter from the report schema and the session/flow schemas.

Commands: record, serve, replay, test, diff, inspect, validate, har import, har export, migrate, plus the --features intercept-gated proxy record, proxy validate, and ca init|import|inspect|export|rotate. validate checks a fixture without reading bodies; it is not the same as inspect --bodies.

Stable exit codes (compatibility contract):

  • 0 success (replay reports differences with 0; test/diff assert);
  • 1 regression/assertion mismatch (replay findings are reported, test enforces with regression, diff with diff);
  • 2 invalid CLI/config/policy (including malformed --route, no fallback-to-direct);
  • 3 invalid/corrupt fixture;
  • 4 network/runtime execution failure;
  • 5 internal/unexpected failure.

record, replay, and test accept a common --route (direct default, or a pproxy URI such as socks5://127.0.0.1:1080 and two-hop socks5://...__http://...). Non-direct routes use EggressDialer via EggFetch's custom Dialer seam; redaction-safe physical_route metadata is recorded in flows. inspect --bodies performs an explicit bounded body read (--max-body-bytes, default 64 KiB, truncates with counts): UTF-8 text when valid, otherwise length + digest (bounded base64 only with --bodies-base64). Stored bodies are already redacted, so inspection never bypasses markers.

WebSocket recording is disabled by default. Use record --websockets or serve --record-mode once|re-record --websockets to admit HTTP/1.1 WebSocket upgrades. --redact-websocket-text and --redact-websocket-binary replace whole message payloads before publication; configured JSON Pointer redaction also applies to valid JSON text messages. serve --record-mode append-new rejects --websockets. Offline replay/sealed serve and candidate test automatically use recorded WebSocket transcripts. The optional --websocket-cadence-tolerance-ms adds message cadence findings. It is a comparison flag, so it exists on replay, test, and diff, not on record or serve.

inspect --websockets reports conversation IDs, flow links, message kind, direction, timing, payload digest/length, close metadata, and redaction markers; it never prints message bytes.

Transport protocol flags

serve and record take --inbound, which selects the serving protocol. Accepted values are http1 (aliases: h1, the default) and http2 (aliases: h2, h2c, http2-cleartext; all select cleartext HTTP/2 prior knowledge).

--inbound h2-tls / http2-tls is a recognised name that is deliberately rejected: TLS serving requires operator certificate and key material, so the policy is built from --inbound-tls-cert and --inbound-tls-key rather than by naming the protocol. Passing it exits 2 with a diagnostic. ALPN negotiation therefore happens when the identity is supplied, not when the name is chosen.

http2 requires a build with the h2-inbound (or h2-inbound-tls) cargo feature; without it the flag fails closed with exit code 2 rather than silently serving HTTP/1.1. For TLS, pass both --inbound-tls-cert and --inbound-tls-key to supply the operator's identity. These are not a minted CA. --h2-max-concurrent-streams bounds concurrent streams per connection. The JSON result of both commands reports the effective serving policy.

serve, replay, record, and test take --outbound-version, which selects the outbound client policy. Accepted values are auto (the default), http1, and http2. Use the spellings http1 and http2, not h1 or h2, which are rejected at parse time. Selecting http2 requires the CLI's h2 feature. auto means HTTP/1.1, not EggFetch's Auto: an upstream release must not be able to change the protocol of an existing invocation.

record, replay, test, and serve take --timeout-secs <N>, a wall-clock ceiling for one outbound request. It bounds every phase including total, which is the part that matters most: the per-phase read budget is "time between response body chunks", so an origin that accepts a connection and then says nothing is bounded only by total. The flag is unset by default, preserving existing invocation behavior, just as --outbound-version auto does. A timed-out transaction is recorded in the flow as ErrorCategory::Timeout; the command still exits 0. The effective timeout is reported as outbound_timeout in the JSON result ({"bounded": false, "total_secs": null} when unset). diff reports outbound_timeout: null because it never opens a socket.

A fixture recorded over https replays only over TLS. A scheme mismatch is a bounded refusal (not a relaxed match), and a gateway flow records the upstream authority it reached rather than the inbound :authority.

See docs/http2-support.md for tiers, invariants, and known limitations.

serve --scenario <ID> explicitly enables one authored scenario from the fixture's rules extension. Without the flag, a required scenario extension fails closed instead of being silently ignored. Scenario state is isolated to that server process.

serve --record-mode sealed is the default and never opens an upstream. once records only when the destination fixture is new; if it already exists, the policy resolves to sealed replay. append-new and re-record require an explicit --upstream; append-new uses EggFetch on exact misses and transactionally publishes the merged fixture when the server stops, while re-record stages a replacement and preserves the old fixture until the new recording validates. --route is only accepted with a network-capable mode. --matcher-profile selects strict or practical, and serve's JSON result reports the effective record, matcher, upstream, and timing policies, plus the redaction profile and outbound timeout in the network-capable modes (once, append-new, re-record). The sealed mode reports record, matcher, upstream, and timing but omits redaction_profile and outbound_timeout even though it accepts both flags; a sealed server opens no socket, so nothing is timed. serve --timing-mode accepts immediate (default), recorded, or scaled:<factor> with factors from 0.01 to 100. Timed replay needs a validated stream-events extension; recorded data delays are capped at 60 seconds each and five minutes per flow. Dropping a response cancels its pending sleep.

inspect --sse adds a derived view for text/event-stream response bodies. The view is bounded by --max-body-bytes and the 16 MiB parser cap; raw body bytes remain authoritative. replay, test, and fixture diff compare ordered response stream events only with --compare-stream-events, cadence only with --cadence-tolerance-ms <N> (which implies stream comparison), and derived SSE semantics only with --compare-sse or repeatable --sse-ignore <field> (data,event,id,retry,comments, which implies SSE comparison). Raw body comparison remains authoritative; SSE findings never suppress raw-body findings. Requested stream comparison requires valid metadata on both sides; missing metadata is an explicit fixture/configuration error.

Stream comparison covers the response direction only, and that is a structural decision rather than a gap. Recorded request events are inbound transport-frame boundaries, and a candidate's request is synthesized by the replay client, so a request-direction comparison would measure the original client's framing against EggReplay's own. The volatile Date header is suppressed when present on both sides and listed in the report's suppressed array. If it appears on only one side, the presence mismatch remains a finding. Other headers are compared normally.

--max-elapsed-ms <N> asserts that each candidate flow finishes within N milliseconds of starting, emitting a timing.elapsed_ms finding when it does not. It is a comparison bound on a finished run, not playback configuration: it is independent of --timing-mode, which controls how a fixture is paced during replay. diff compares two fixtures and applies the same bound to the candidate side.

replay and test keep sequential candidate execution by default. Add --scheduler timeline to start candidate requests at their recorded monotonic offsets; equal offsets follow fixture order, and --max-concurrency (default 8, maximum 1,024) bounds active requests. Timeline mode requires one validated start offset for every flow and reports findings in fixture order.

HAR import and export are offline and lossy. Import a HAR 1.2 file with eggreplay har import --har input.har --fixture out.eggr; the selected redaction policy is applied before publication. Import writes a non-required interop-provenance extension and can emit a loss report with --loss-report. Export with eggreplay har export --fixture in.eggr --har out.har; the output includes _eggreplay loss/provenance metadata and can emit a separate loss report with --loss-report. Neither direction is lossless. Upgrade a schema-1 fixture transactionally with eggreplay migrate --fixture old.eggr --to new.eggr or eggreplay migrate --fixture old.eggr --in-place to replace it. Migration checks registered extensions and rejects unknown required extensions and future schemas. See har-interchange.md for the loss matrices and redaction rules.

Interception builds add eggreplay proxy record, eggreplay proxy validate --policy-file ..., and eggreplay ca init|import|inspect|export|rotate. Proxy recording uses an explicit-proxy listener and a CONNECT policy (deny, tunnel, or intercept); intercept rules require a CA directory. Validation prints the normalized policy. CA commands manage operator-owned certificates and keys, expose public metadata only, and do not install trust. These commands require an explicit --features intercept build; default builds do not enable interception. JSON reports the bind address, capability, public CA fingerprint, policy counts, traffic counters, and bounded failures. It never includes key contents, key paths, credentials, or decrypted payloads. See interception-ca-trust.md for manual trust setup.