RFC: Incremental interception + optional MITM roadmap (follow-up to #43)

[gkoos]

Describe the feature

Summary

Following up on #43, I'd like to propose an incremental roadmap to add programmable interception and eventually optional MITM capabilities to httpxy, in small phases rather than one huge PR.

Motivation

The original request asks for behavior similar to Charles/Burp-style interception:

• Rewrite request/response headers
• Rewrite request/response bodies
• Apply programmatic rules by host/path/etc.
• Potentially support HTTPS interception (MITM)

This is valuable, but broad. A phased approach should reduce risk and make review/maintenance manageable.

Proposed Scope

Phase 1 (PR1): HTTP interception API (no MITM)

• Add first-class interceptor hooks for request/response mutation on HTTP traffic.
• Keep streaming-safe defaults.
• Allow body rewrite only when explicitly enabled (buffering mode).
• Add tests for header/body rewrite, passthrough, and error behavior.

Phase 2 (PR2): Rule engine

• Declarative matching by hostname/path/method/header predicates.
• Deterministic ordering/priority.
• Rule-level enable/disable and clear conflict behavior.
• Add tests for ordering and matching edge-cases.

Phase 3 (PR3): Response/body handling hardening

• Content-length/chunked correctness after rewrite.
• Compression handling strategy (gzip/br/deflate) with explicit opt-in behavior.
• SSE/streaming compatibility and backpressure tests.

Phase 4+ (later RFC/PRs): Optional CONNECT + TLS MITM mode

• Explicit opt-in mode only.
• CONNECT handling and TLS termination.
• CA + dynamic cert generation strategy.
• Security model and operational warnings.
• This phase is intentionally separated due to complexity and security implications.

Non-goals for initial phases

• Native HTTP/3 interception.
• Full browser-like certificate trust automation.
• Transparent proxy mode across all protocols.

Why this approach?

• Smaller, reviewable PRs.
• Earlier user value (header/body interception without TLS MITM).
• Less risk to core proxy behavior and performance.
• Clear boundary before security-sensitive TLS interception work.

Questions for maintainers

1. Is this phased breakdown acceptable?
2. Is HTTP-only interception a good first deliverable for PR1?
3. Any constraints on API shape or backward compatibility expectations?
4. Any preference on where rule matching should live (core middleware vs dedicated module)?

If aligned, I can start with Phase 1 and submit a small PR focused on interception hooks + tests.

Additional information

• Would you be willing to help implement this feature?