Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .skills/rust-proxy-dev/skill.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,18 @@ For Python embedding, use the `eggress-python` crate and `python/eggress` packag
- `FeatureInfo` — dataclass with feature_id, tier, supported
- `.pyi` type stubs for all public modules

### pproxy drop-in binary

- `pproxy` binary target in `eggress-cli` — direct drop-in replacement for the original pproxy command
- Source: `crates/eggress-cli/src/pproxy_main.rs` — raw arg parsing (not clap), delegates to `PproxyArgs::parse()` → `translate_pproxy_args()`
- Flags: `-l`, `-r`, `-ul`, `-ur`, `-b`, `-a`, `-s`, `-v/-vv/-vvv`, `--ssl`, `--pac`, `--test`, `--sys`, `--daemon/-d`, `--reuse`, `--get`, `--log`, `--rulefile`, `--version`, `-h/--help`
- `--help` prints comprehensive flag reference; `--version` prints `eggress-pproxy-compat {VERSION}`
- `--test` spawns `eggress upstream test -c <config>` and exits with its status
- `--sys` calls `inspect_system_proxy()` and prints results before starting
- `-v/-vv/-vvv` maps to RUST_LOG levels: 0→info, 1-2→debug, 3+→trace
- Startup banner prints version, listeners, remotes, UDP, TLS, PAC to stderr
- Tests: `cargo test -p eggress-cli --test pproxy_binary`

### Building

```bash
Expand Down
9 changes: 7 additions & 2 deletions .skills/testing/skill.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,10 @@ Protocol-specific tests live alongside the implementation:
- `crates/eggress-cli/tests/interoperability_pproxy.rs` — pproxy-based

### Differential tests
- `crates/eggress-cli/tests/differential_pproxy.rs` — gated differential tests against pproxy (27 scenarios, `EGRESS_REQUIRE_EXTERNAL_INTEROP=1`)
- `crates/eggress-cli/tests/pproxy_differential.rs` — Phase 41 reusable differential parity harness (11 scenarios, `EGRESS_RUN_PPROXY_DIFFERENTIAL=1`)
- `crates/eggress-cli/tests/differential_pproxy.rs` — gated differential tests against pproxy (28 scenarios, `EGRESS_REQUIRE_EXTERNAL_INTEROP=1`)
- `crates/eggress-cli/tests/pproxy_differential.rs` — Phase 41 reusable differential parity harness (18 scenarios, `EGRESS_RUN_PPROXY_DIFFERENTIAL=1`)
- `crates/eggress-cli/tests/interoperability_shadowsocks.rs` — gated Shadowsocks interop tests (TCP tests fail due to non-standard framing)
- `crates/eggress-cli/tests/oracle.rs` — scenario-driven oracle harness (31 scenarios, `EGRESS_ORACLE=1`)

Gated tests require environment variables and external tools. See `docs/DIFFERENTIAL_TESTING.md` for prerequisites, environment variables, and running instructions.

Expand Down Expand Up @@ -139,6 +140,7 @@ Black-box probe tests document pproxy behavior for ambiguous scenarios (refused
- Fixture servers (`fixtures` module) — TCP/UDP echo, HTTP origin, HTTP CONNECT upstream, SOCKS4/5 upstream, TLS echo
- Differential case model (`case_model` module) — `PproxyCase`, `CaseOutcome`, comparison helpers
- Parity report generator (`report` module) — JSON and markdown reports from manifest + test results
- Oracle harness (`oracle` module) — scenario registry, JSON report generation, gate functions (`EGRESS_ORACLE`)

## Running tests
```bash
Expand Down Expand Up @@ -171,6 +173,9 @@ EGRESS_REQUIRE_EXTERNAL_INTEROP=1 cargo test -p eggress-cli --test differential_
EGRESS_REQUIRE_SHADOWSOCKS_INTEROP=1 cargo test -p eggress-cli --test interoperability_shadowsocks -- --ignored
EGRESS_RUN_PPROXY_DIFFERENTIAL=1 cargo test -p eggress-cli --test pproxy_differential -- --ignored

# Scenario-driven oracle harness (gated, requires pproxy==2.7.9)
EGRESS_ORACLE=1 cargo test -p eggress-cli --test oracle -- --ignored

# Python tests
python -m pytest python/tests/test_pproxy_dropin.py -v
python -m pytest python/tests/test_pproxy_differential.py -v
Expand Down
25 changes: 20 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,9 @@ EGRESS_REQUIRE_EXTERNAL_INTEROP=1 cargo test -p eggress-cli --test differential_
# Run pproxy standalone UDP differential tests only
./scripts/compat_udp_pproxy.sh

# Run pproxy binary drop-in tests
cargo test -p eggress-cli --test pproxy_binary

# Run Phase 41 pproxy differential parity harness tests (gated, requires pproxy==2.7.9)
EGRESS_RUN_PPROXY_DIFFERENTIAL=1 cargo test -p eggress-cli --test pproxy_differential -- --ignored

Expand Down Expand Up @@ -175,6 +178,9 @@ cargo test -p eggress-pproxy-compat
# Run pproxy oracle tests (Phase 18, requires pproxy==2.7.9)
cargo test -p eggress-testkit pproxy_oracle -- --ignored

# Run scenario-driven oracle harness (gated, requires pproxy==2.7.9)
EGRESS_ORACLE=1 cargo test -p eggress-cli --test oracle -- --ignored

# Run pproxy differential tests (gated, requires pproxy==2.7.9)
EGRESS_REQUIRE_EXTERNAL_INTEROP=1 cargo test -p eggress-cli --test differential_pproxy -- --ignored

Expand All @@ -187,6 +193,15 @@ cargo test -p eggress-testkit manifest_test_names_exist
# Run all manifest validation tests (Phase 36)
cargo test -p eggress-testkit --lib manifest

# Validate canonical parity manifest via Rust (Phase 53)
cargo test -p eggress-testkit validate_real_canonical_manifest

# Run all canonical manifest validation tests (Phase 53)
cargo test -p eggress-testkit canonical_manifest

# Cross-check parity report against canonical manifest (Phase 53)
cargo test -p eggress-testkit parity_manifest_consistency

# Validate pproxy parity capability manifest (Phase 37)
python3 scripts/validate_pproxy_parity_manifest.py docs/parity/pproxy_capability_manifest.toml

Expand Down Expand Up @@ -350,7 +365,7 @@ eggress/
├── .skills/ # Agent skill files for this codebase
├── crates/
│ ├── eggress-core/ # Core types, traits, relay, listener, connector, chain
│ ├── eggress-cli/ # CLI binary
│ ├── eggress-cli/ # CLI binary (eggress + pproxy drop-in binary)
│ ├── eggress-server/ # Server orchestration: accept, execute, reply, error
│ ├── eggress-runtime/ # Service supervisor, composition layer, signal handling
│ ├── eggress-uri/ # URI parser and AST
Expand Down Expand Up @@ -491,7 +506,7 @@ See `docs/DIFFERENTIAL_TESTING.md` for gated differential and interoperability t

## Key Architecture Facts

- **Entry point**: `eggress-cli` binary → `eggress-runtime` `ServiceSupervisor::run()` → `eggress-server` `serve_connection()`
- **Entry point**: `eggress-cli` binary → `eggress-runtime` `ServiceSupervisor::run()` → `eggress-server` `serve_connection()`. The `pproxy` binary is a drop-in compatibility wrapper that translates pproxy-style args to TOML and delegates to the same runtime.
- **Streams are boxed** at protocol/transport boundaries (`BoxStream`) — don't propagate generic stream types
- **Protocol detection** uses ordered `ProtocolDetector` implementations; mixed-protocol listeners are the norm
- **Chain executor** folds over hop list with protocol-specific handlers — validate chain capabilities before executing
Expand Down Expand Up @@ -521,10 +536,10 @@ See `docs/DIFFERENTIAL_TESTING.md` for gated differential and interoperability t
- **PyPI packaging**: Wheels built with maturin for Linux x86_64/aarch64, macOS x86_64/arm64, Windows x86_64. See `docs/PYPI_RELEASE.md`.
- **Python packaging**: Canonical package `eggress` on PyPI. `eggress.pproxy` provides compatibility helpers. No top-level `pproxy` shim (deferred). Wheels built for 5 platforms via maturin. `py.typed` PEP 561 marker included. Version/capability metadata exposed via `eggress.__version__`, `eggress.version()`, `eggress.capabilities()`, `eggress.pproxy.compatibility_version()`. See `docs/adr/ADR_python_import_and_distribution_strategy.md`.
- **Release candidate audit (Phase 17)**: Final parity matrix audit, Rust/Python release audits, security/redaction audit including Python binding surface, documentation consistency pass. Release candidate document at `docs/TRUE_PPROXY_PARITY_RELEASE_CANDIDATE.md`. All verification commands pass; go recommendation issued. See `docs/PHASE_17_TRUE_PPROXY_PARITY_RELEASE_CANDIDATE_COMPLETION.md`.
- **Manifest validation**: `tests/compat/pproxy_manifest.toml` is the canonical evidence index. `egress_status = "compatible"` requires `evidence_level = "compatible"` backed by real pproxy differential tests. `implemented_synthetic` evidence cannot support compatibility claims. Validation enforced by `eggress-testkit::manifest::validate_manifest()`. `last_updated` field removed in Phase 24; stale warnings no longer emitted.
- **pproxy parity manifest (Phase 37)**: `docs/parity/pproxy_capability_manifest.toml` is the authoritative compatibility contract — 109 capabilities across 5 categories (CLI, URI, Protocol, Routing, Python) with tier classification, evidence requirements, and config/runtime/test layers. Frozen as of Phase 51 final parity certification. Validated by `scripts/validate_pproxy_parity_manifest.py` (13 rules, strict mode). The report `docs/parity/PPROXY_PARITY_REPORT.md` is generated from the manifest (Phase 42: `--write-report`/`--check-report`). See `docs/parity/README.md` for design.
- **Manifest validation**: Two manifests coexist with different schemas. The **canonical parity contract** is `docs/parity/pproxy_capability_manifest.toml` (Phase 37+, 139 capabilities, `[[capability]]` arrays, 5-tier vocabulary). Validated by Rust (`eggress-testkit::canonical_manifest::validate_canonical_manifest()`, 13 rules) and Python (`scripts/validate_pproxy_parity_manifest.py`, 14 rules). The **legacy evidence index** is `tests/compat/pproxy_manifest.toml` (Phase 18, `[[features]]` arrays, different taxonomy) — retained for Rust cross-check tests but superseded for parity claims.
- **pproxy parity manifest (Phase 37)**: `docs/parity/pproxy_capability_manifest.toml` is the authoritative compatibility contract — 139 capabilities across 5 categories (CLI, URI, Protocol, Routing, Python) with tier classification, evidence requirements, and config/runtime/test layers. Frozen as of Phase 51 final parity certification. Validated by Rust (`eggress-testkit::canonical_manifest::validate_canonical_manifest()`, 13 rules) and Python (`scripts/validate_pproxy_parity_manifest.py`, 14 rules, strict mode). The report `docs/parity/PPROXY_PARITY_REPORT.md` is generated from the manifest (Phase 42: `--write-report`/`--check-report`). See `docs/parity/README.md` for design.
- **Phase 42 corrective consistency pass**: `CompatibilityReport.tier` now uses the five-tier manifest vocabulary (`drop_in`, `compatible_with_warning`, `native_equivalent`, `intentional_non_parity`, `unsupported`); `PPProxyService.from_args` preserves the full pproxy argument vector through `translate_pproxy_args`; `--ssl` applies TLS to all compatible listeners (matches pproxy, which loads the cert chain into every ssl context). See `docs/PHASE_42_PPROXY_PARITY_CORRECTIVE_CONSISTENCY_PASS_COMPLETION.md`.
- **pproxy CLI native-equivalent closure (Phase 38)**: `--ssl`, `-b`, `--rulefile` generate TOML config (TLS listener, reject rules, rulefile-parsed rules). `-a N` generates `[health] interval = "Ns"` TOML. `--pac` generates `[admin.pac] enabled = true` TOML. `--test` translates config and runs `eggress upstream test -c <config>`, then exits. `--sys` auto-invokes `eggress system-proxy inspect` before starting the service. `--log`, `--get`, `--reuse` emit structured diagnostics. `--daemon` remains unsupported. See `plans/phase_38_pproxy_cli_native_equivalent_closure.md`, `docs/PHASE_38_PPROXY_CLI_NATIVE_EQUIVALENT_CLOSURE_COMPLETION.md`, and `docs/cli/PPROXY_CLI_INVENTORY.md`.
- **pproxy CLI native-equivalent closure (Phase 38)**: `--ssl`, `-b`, `--rulefile` generate TOML config (TLS listener, reject rules, rulefile-parsed rules). `-a N` generates `[health] interval = "Ns"` TOML. `--pac` generates `[admin.pac] enabled = true` TOML. `--test` translates config and runs `eggress upstream test -c <config>`, then exits. `--sys` auto-invokes `eggress system-proxy inspect` before starting the service. `--log`, `--get`, `--reuse` emit structured diagnostics. `--daemon` remains unsupported. See `plans/phase_38_pproxy_cli_native_equivalent_closure.md`, `docs/PHASE_38_PPROXY_CLI_NATIVE_EQUIVALENT_CLOSURE_COMPLETION.md`, and `docs/cli/PPROXY_CLI_INVENTORY.md`.\n- **pproxy regex and rulefile compatibility (Phase A.03)**: Dual regex backend (`fast regex` + `fancy_regex` for lookahead/lookbehind/backreferences). `--rulefile` loader validates patterns and enforces `MAX_RULE_ENTRIES = 10_000`. `-b` flag patterns validated at parse time. URI `?rules_file=` query parameter preserved through translation. New diagnostic codes: `RulefileError`, `InvalidRegexPattern`, `FancyRegexBackend`, `UriPreservedUnsupportedComponent`. See `crates/eggress-pproxy-compat/src/regex_compat.rs`.
- **Manifest external dependency checks (Phase 24)**: Compatible entries with differential tests require `external_dependency`; implemented_interop requires dependency or divergence note explaining interop.
- **Exit codes**: Structured exit codes defined in `eggress-pproxy-compat::exit_codes`. CLI uses constants, not ad-hoc returns.
- **Diagnostics**: `DiagnosticCode` enum with stable codes for all pproxy compat errors/warnings. `StructuredDiagnostic` for JSON output.
Expand Down
14 changes: 14 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ insta = "1"
trait-variant = "0.1"
ipnet = "2"
fastrand = "2"
fancy-regex = "0.14"
rand = "0.8"
arc-swap = "1"
tokio-tungstenite = "0.26"
Expand Down
15 changes: 12 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

A Rust-native, embeddable, multi-protocol proxy framework and CLI targeting practical and behavioral parity with Python `pproxy`.

> Status: Phase 51 final parity certification complete. The parity capability manifest (109 capabilities, machine-validated) is frozen; the parity report is regenerated and consistency-checked; all workspace unit/lib tests pass; CLI binary builds and runs; release artifacts verified. Release candidate: `docs/release/`.
> Status: Phase 51 final parity certification complete. The parity capability manifest (139 capabilities, machine-validated) is frozen; the parity report is regenerated and consistency-checked; all workspace unit/lib tests pass; CLI binary builds and runs; release artifacts verified. Release candidate: `docs/release/`.

eggress will preserve the compact URI-driven workflow of `pproxy` while using explicit Rust abstractions for listeners, application proxy protocols, transport wrappers, routing, proxy chains, UDP associations, and platform integration.

Expand Down Expand Up @@ -32,7 +32,7 @@ The `eggress-pproxy-compat` crate provides:
- Python pproxy drop-in API (`PPProxyService`, `CompatibilityReport`, `start_pproxy` multi-mode) — Phase 40
- `.pyi` type stubs for all public modules
- Python API parity specification with tier classification (Phase 29) — 424-line inventory covering 114 pproxy API entries across exports, protocols, ciphers, scheduling, lifecycle, and error surfaces
- Authoritative parity capability manifest (`docs/parity/pproxy_capability_manifest.toml`) — 109 capabilities across 5 categories with tier classification and machine-readable validation
- Authoritative parity capability manifest (`docs/parity/pproxy_capability_manifest.toml`) — 139 capabilities across 5 categories with tier classification and machine-readable validation
- Reusable differential parity harness (`eggress-testkit::differential`) — 27 scenarios against pproxy 2.7.9 — Phase 41
- Phase 42 corrective consistency pass: `CompatibilityReport` uses the five-tier manifest vocabulary; `PPProxyService.from_args` preserves the full pproxy argument vector through `translate_pproxy_args`; `--ssl` applies to all listeners (matches pproxy); parity report can be regenerated (`--write-report`) and consistency-checked (`--check-report`) from the manifest

Expand Down Expand Up @@ -64,6 +64,14 @@ sudo mv eggress /usr/local/bin/

See [BINARY_INSTALL.md](docs/release/BINARY_INSTALL.md) for all platforms and checksum verification.

The release archive includes a `pproxy` compatibility binary alongside `eggress`. Users can run `pproxy` directly as a drop-in replacement for the original `pproxy` command:

```bash
pproxy -l http://:8080 -r socks5://127.0.0.1:1080
pproxy --help
pproxy --version
```

### Python package

```bash
Expand Down Expand Up @@ -479,12 +487,13 @@ differential testing possible, user demand, CONNECT-UDP/MASQUE standardization.
- [x] `--json` flag for machine-readable pproxy check output (Phase 28)
- [x] CLI flag inventory: full parity documentation of translate/check/run subcommands (Phase 28)
- [x] Compatibility manifest tracking all parity features with evidence levels (`tests/compat/pproxy_manifest.toml`)
- [x] Authoritative parity capability manifest — 109 capabilities, 5 categories, machine-validated (Phase 37, updated Phase 51)
- [x] Authoritative parity capability manifest — 139 capabilities, 5 categories, machine-validated (Phase 37, updated Phase 51)
- [x] pproxy CLI native-equivalent closure — `--ssl`, `-b`, `--rulefile`, `-a`, `--pac`, `--test`, `--sys` generate TOML (Phase 38)
- [x] URI grammar chain semantics — `__` separator, modifiers, default port inference (Phase 39)
- [x] Python pproxy drop-in API — `PPProxyService`, `CompatibilityReport`, `.pyi` stubs (Phase 40)
- [x] Reusable differential parity harness — 27 scenarios against pproxy 2.7.9 (Phase 41)
- [x] Corrective consistency pass — `CompatibilityReport` five-tier manifest vocabulary, `PPProxyService.from_args` full argument vector, `--ssl` applies to all listeners, parity report `--write-report`/`--check-report` (Phase 42)
- [x] `pproxy` drop-in binary — run `pproxy -l http://:8080 -r socks5://127.0.0.1:1080` directly, with `--help`, `--version`, `-v/-vv/-vvv` verbosity, startup banner, `--test`, `--sys`
- Oracle process runner for real pproxy differential testing (`eggress-testkit`)
- Machine-readable parity reports generated after differential test runs

Expand Down
4 changes: 4 additions & 0 deletions crates/eggress-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ license.workspace = true
name = "eggress"
path = "src/main.rs"

[[bin]]
name = "pproxy"
path = "src/pproxy_main.rs"

[dependencies]
eggress-core.workspace = true
eggress-server.workspace = true
Expand Down
Loading
Loading