diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 34da2aeb..5b54d387 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,94 +6,30 @@ on: pull_request: branches: [main] +concurrency: + group: ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + env: CARGO_TERM_COLOR: always - RUSTFLAGS: -D warnings jobs: - check: - name: Check (${{ matrix.os }}) - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: Swatinem/rust-cache@v2 - - run: cargo check --workspace --all-targets - - test: - name: Test (${{ matrix.os }}) - runs-on: ${{ matrix.os }} - timeout-minutes: 15 - strategy: - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: Swatinem/rust-cache@v2 - - run: cargo test --workspace - - fmt: - name: Format - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - with: - components: rustfmt - - run: cargo fmt --all -- --check - - clippy: - name: Clippy + rust: + name: Rust smoke runs-on: ubuntu-latest + timeout-minutes: 20 steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable with: - components: clippy + components: rustfmt, clippy - uses: Swatinem/rust-cache@v2 - - run: cargo clippy --workspace --all-targets -- -D warnings - - deny: - name: Deny - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: EmbarkStudios/cargo-deny-action@v2 - - audit: - name: Audit - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - run: cargo install cargo-audit - # RUSTSEC-2025-0134: rustls-pemfile is unmaintained. The crate is the - # only published version on crates.io and is needed by eggress-transport-tls - # for PEM cert chain loading. Tracked for removal once a maintained - # successor (or upstream rustls integration) is available. - - run: cargo audit --ignore RUSTSEC-2025-0134 - - interoperability: - name: Interoperability (Ubuntu) - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: Swatinem/rust-cache@v2 - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - run: pip install "pproxy==2.7.9" - - run: cargo test -p eggress-cli --test interoperability_pproxy -- --ignored --skip test_pproxy_http_server_eggress_client --skip test_pproxy_socks5_server_eggress_client - env: - EGRESS_REQUIRE_EXTERNAL_INTEROP: "1" - # curl interop tests require curl binary — skip in CI until - # a dedicated runner with curl is provisioned - # - run: cargo test -p eggress-cli --test interoperability_curl -- --ignored - # env: - # EGRESS_REQUIRE_CURL_INTEROP: "1" - + - name: Format + run: cargo fmt --all -- --check + - name: Clippy + run: cargo clippy --workspace --all-targets -- -D warnings + - name: Test + run: cargo test --workspace --locked diff --git a/.github/workflows/pproxy-compat.yml b/.github/workflows/pproxy-compat.yml deleted file mode 100644 index ef5beb00..00000000 --- a/.github/workflows/pproxy-compat.yml +++ /dev/null @@ -1,58 +0,0 @@ -name: pproxy-compatibility - -on: - push: - branches: [main] - pull_request: - branches: [main] - workflow_dispatch: - -env: - CARGO_TERM_COLOR: always - RUSTFLAGS: -D warnings - -jobs: - pproxy-compat: - name: pproxy Compat (Ubuntu) - runs-on: ubuntu-latest - timeout-minutes: 20 - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: Swatinem/rust-cache@v2 - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - name: Install pproxy - run: pip install "pproxy==2.7.9" - - name: Verify pproxy - run: python -m pproxy --help - - name: Build - run: cargo build --workspace - - name: Validate manifest invariants - run: cargo test -p eggress-testkit validate_real_manifest - - name: Validate parity capability manifest - run: python3 scripts/validate_pproxy_parity_manifest.py docs/parity/pproxy_capability_manifest.toml - - name: Verify parity report is consistent with manifest - run: python3 scripts/validate_pproxy_parity_manifest.py --check-report docs/parity/PPROXY_PARITY_REPORT.md docs/parity/pproxy_capability_manifest.toml - - name: Run testkit pproxy_oracle tests - run: cargo test -p eggress-testkit pproxy_oracle -- --ignored - - name: Run differential pproxy tests - env: - EGRESS_REQUIRE_EXTERNAL_INTEROP: "1" - run: cargo test -p eggress-cli --test differential_pproxy -- --ignored - - name: Run interoperability pproxy tests - env: - EGRESS_REQUIRE_EXTERNAL_INTEROP: "1" - run: cargo test -p eggress-cli --test interoperability_pproxy -- --ignored - - name: Generate parity report - run: cargo test -p eggress-testkit report -- --ignored - - name: Upload parity report - if: always() - uses: actions/upload-artifact@v4 - with: - name: pproxy-parity-report - path: | - target/compat/pproxy-parity-report.json - target/compat/pproxy-parity-report.md - if-no-files-found: ignore diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml deleted file mode 100644 index 70abd686..00000000 --- a/.github/workflows/publish-pypi.yml +++ /dev/null @@ -1,39 +0,0 @@ -name: Publish to PyPI - -on: - workflow_dispatch: - inputs: - repository: - description: "Target repository (testpypi or pypi)" - required: true - default: "testpypi" - type: choice - options: - - testpypi - - pypi - -jobs: - publish: - runs-on: ubuntu-latest - timeout-minutes: 15 - environment: ${{ inputs.repository == 'pypi' && 'pypi' || 'testpypi' }} - permissions: - id-token: write - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - name: Install maturin - run: pip install maturin - - name: Build wheel and sdist - run: | - maturin build --release --out dist - maturin sdist --out dist - working-directory: crates/eggress-python - - name: Publish to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 - with: - packages-dir: crates/eggress-python/dist/ - repository-url: ${{ inputs.repository == 'testpypi' && 'https://test.pypi.org/legacy/' || '' }} diff --git a/.github/workflows/python-compat.yml b/.github/workflows/python-compat.yml deleted file mode 100644 index 1b631806..00000000 --- a/.github/workflows/python-compat.yml +++ /dev/null @@ -1,56 +0,0 @@ -name: Python Compatibility Distribution - -on: - pull_request: - paths: - - 'crates/eggress-embed/**' - - 'crates/eggress-python/**' - - 'python/**' - - 'python-pproxy-compat/**' - - 'python/tests/test_proxy_connection.py' - - '.github/workflows/python-compat.yml' - push: - branches: [main] - paths: - - 'crates/eggress-embed/**' - - 'crates/eggress-python/**' - - 'python/**' - - 'python-pproxy-compat/**' - - 'python/tests/test_proxy_connection.py' - - '.github/workflows/python-compat.yml' - workflow_dispatch: - -jobs: - clean-wheel-smoke: - runs-on: ${{ matrix.os }} - timeout-minutes: 20 - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: actions/setup-python@v5 - with: - python-version: '3.12' - - name: Install build and cipher dependencies - run: python -m pip install "maturin>=1.0,<2.0" "cryptography>=42,<47" pytest "pytest-asyncio>=0.23,<1" - - name: Build canonical wheel - run: maturin build --release --out dist - working-directory: crates/eggress-python - - name: Build compatibility wheel - run: python -m pip wheel --no-deps --wheel-dir compat-dist ./python-pproxy-compat - - name: Install both wheels in a clean environment - shell: bash - run: | - python -m venv .compat-venv - if [[ "$RUNNER_OS" == "Windows" ]]; then VENV_PY=.compat-venv/Scripts/python.exe; else VENV_PY=.compat-venv/bin/python; fi - "$VENV_PY" -m pip install --upgrade pip - "$VENV_PY" -m pip install crates/eggress-python/dist/eggress-*.whl compat-dist/eggress_pproxy_compat-*.whl "cryptography>=42,<47" pytest "pytest-asyncio>=0.23,<1" - "$VENV_PY" -c "import eggress, pproxy; from pproxy import Connection, Server; assert eggress.__version__ == '0.1.0'; print('clean compatibility import passed')" - - name: Test native outbound and wheel imports - shell: bash - run: | - if [[ "$RUNNER_OS" == "Windows" ]]; then VENV_PY=.compat-venv/Scripts/python.exe; else VENV_PY=.compat-venv/bin/python; fi - "$VENV_PY" -m pytest --import-mode=importlib python/tests/test_proxy_connection.py python/tests/test_wheel_import_smoke.py -q diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml index 4da5008e..26d4fa7f 100644 --- a/.github/workflows/python-test.yml +++ b/.github/workflows/python-test.yml @@ -1,65 +1,58 @@ -name: Python Tests +name: Python smoke on: pull_request: paths: + - 'crates/eggress-embed/**' - 'crates/eggress-python/**' - 'python/**' - 'python-pproxy-compat/**' - 'tests/compat/**' + - 'Cargo.toml' + - 'Cargo.lock' - '.github/workflows/python-test.yml' push: branches: [main] paths: + - 'crates/eggress-embed/**' - 'crates/eggress-python/**' - 'python/**' - 'python-pproxy-compat/**' - 'tests/compat/**' + - 'Cargo.toml' + - 'Cargo.lock' - '.github/workflows/python-test.yml' - workflow_dispatch: + +concurrency: + group: python-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read jobs: - test: - runs-on: ${{ matrix.os }} + smoke: + name: Python 3.12 smoke + runs-on: ubuntu-latest timeout-minutes: 20 - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, macos-latest] - python-version: ["3.9", "3.12", "3.13"] steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 - uses: actions/setup-python@v5 with: - python-version: ${{ matrix.python-version }} - - name: Install maturin + python-version: '3.12' + - name: Create test environment run: | python -m venv .venv - source .venv/bin/activate - pip install "maturin>=1.0,<2.0" - echo "VIRTUAL_ENV=${{ github.workspace }}/.venv" >> "$GITHUB_ENV" - echo "${{ github.workspace }}/.venv/bin" >> "$GITHUB_PATH" - - name: Clean stale native extension - # Maturin leaves a per-build `_eggress.cpython-*.so` under python/eggress/ - # which is .gitignored. If a stale build from a different architecture - # or Python interpreter is present, pytest collection will fail with - # import errors. Remove any such stale artifacts before building. - run: git clean -fX python/eggress - - name: Build and install - run: maturin develop + .venv/bin/python -m pip install --upgrade pip + .venv/bin/python -m pip install "maturin>=1.0,<2.0" pytest "pytest-asyncio>=0.23,<1" "cryptography>=42,<47" + - name: Build native wheel + run: ../../.venv/bin/maturin build --release --out ../../target/wheels working-directory: crates/eggress-python - - name: Build and install pproxy compat wheel - run: pip wheel --no-deps --wheel-dir /tmp/compat-wheels ./python-pproxy-compat && pip install /tmp/compat-wheels/eggress_pproxy_compat-*.whl - - name: Verify py.typed - run: python -c "import importlib.resources; p = importlib.resources.files('eggress').joinpath('py.typed'); assert p.is_file(), 'py.typed not found'; print('py.typed found')" - - name: Syntax check - run: python -m compileall python/eggress - - name: Install test dependencies - run: pip install pytest "pytest-asyncio>=0.23,<1" "tomli; python_version < '3.11'" "cryptography>=42,<47" - - name: Run tests - run: python -m pytest python/tests -v - - name: Wheel import smoke tests - run: python -m pytest python/tests/test_wheel_import_smoke.py -v - - name: API contract validator tests - run: python -m pytest tests/compat/test_pproxy_api_contract.py -v + - name: Install packages + run: | + .venv/bin/python -m pip install target/wheels/eggress-*.whl + .venv/bin/python -m pip install --no-deps ./python-pproxy-compat + - name: Run Python smoke suite + run: .venv/bin/python -m pytest python/tests tests/compat -q diff --git a/.github/workflows/python-wheels.yml b/.github/workflows/python-wheels.yml deleted file mode 100644 index 2ebbf5a7..00000000 --- a/.github/workflows/python-wheels.yml +++ /dev/null @@ -1,81 +0,0 @@ -name: Build Python Wheels - -on: - push: - tags: - - "v*" - workflow_dispatch: - -jobs: - build_wheels: - runs-on: ${{ matrix.os }} - timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - include: - - os: ubuntu-latest - target: x86_64 - rust_target: x86_64-unknown-linux-gnu - wheel_smoke: true - - os: macos-13 - target: x86_64 - rust_target: x86_64-apple-darwin - wheel_smoke: false - - os: macos-latest - target: aarch64 - rust_target: aarch64-apple-darwin - wheel_smoke: true - - os: windows-latest - target: x86_64 - rust_target: x86_64-pc-windows-msvc - wheel_smoke: false - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - with: - targets: ${{ matrix.rust_target }} - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - name: Install maturin - run: pip install "maturin>=1.0,<2.0" - - name: Build wheel - shell: bash - run: maturin build --release --target ${{ matrix.rust_target }} -i python --out dist - working-directory: crates/eggress-python - - name: Smoke test wheel - if: ${{ matrix.wheel_smoke }} - shell: bash - run: | - python -m venv .venv-smoke - if [[ "${{ runner.os }}" == "Windows" ]]; then - . .venv-smoke/Scripts/activate - else - . .venv-smoke/bin/activate - fi - pip install crates/eggress-python/dist/eggress-*.whl - python -c "import eggress; print(eggress.__version__)" - python -c "from eggress.pproxy import check_pproxy_uri; print(check_pproxy_uri('socks5://127.0.0.1:1080'))" - - uses: actions/upload-artifact@v4 - with: - name: wheel-${{ matrix.os }}-${{ matrix.target }} - path: crates/eggress-python/dist/*.whl - - build_sdist: - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - name: Install maturin - run: pip install "maturin>=1.0,<2.0" - - name: Build sdist - run: maturin sdist --out dist - working-directory: crates/eggress-python - - uses: actions/upload-artifact@v4 - with: - name: sdist - path: crates/eggress-python/dist/*.tar.gz diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index c5e45a06..00000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,428 +0,0 @@ -name: Release - -on: - push: - tags: - - "v*" - workflow_dispatch: - inputs: - version: - description: "Release version (e.g., v0.1.0)" - required: false - -env: - CARGO_TERM_COLOR: always - RUSTFLAGS: -D warnings - -jobs: - # ── CI gates (must pass before any artifacts are built) ────────────── - ci-gates: - name: CI Gates - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - with: - components: rustfmt, clippy - - uses: Swatinem/rust-cache@v2 - - name: Format check - run: cargo fmt --all -- --check - - name: Check - run: cargo check --workspace --all-targets - # Tests are covered by the CI workflow (test matrix: Ubuntu + macOS + Windows). - # The prior Ubuntu test hang (supervised_process_kill_group using external - # kill command) was fixed by switching to child.kill(). Ubuntu is now - # included in the CI test matrix. - - name: Clippy - run: cargo clippy --workspace --all-targets -- -D warnings - - uses: EmbarkStudios/cargo-deny-action@v2 - - name: Audit - run: | - cargo install cargo-audit - # RUSTSEC-2025-0134: rustls-pemfile is unmaintained. The crate is the - # only published version on crates.io and is needed by - # eggress-transport-tls for PEM cert chain loading. Tracked for - # removal once a maintained successor (or upstream rustls - # integration) is available. - cargo audit --ignore RUSTSEC-2025-0134 - - # ── CLI binary builds ─────────────────────────────────────────────── - build-binaries: - name: Binary (${{ matrix.target }}) - needs: ci-gates - runs-on: ${{ matrix.os }} - timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - include: - - target: x86_64-unknown-linux-gnu - os: ubuntu-latest - archive: tar.gz - - target: aarch64-unknown-linux-gnu - os: ubuntu-latest - archive: tar.gz - - target: x86_64-apple-darwin - os: macos-13 - archive: tar.gz - - target: aarch64-apple-darwin - os: macos-latest - archive: tar.gz - - target: x86_64-pc-windows-msvc - os: windows-latest - archive: zip - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - with: - targets: ${{ matrix.target }} - - uses: Swatinem/rust-cache@v2 - with: - key: ${{ matrix.target }} - - - name: Install cross-compilation tools (Linux aarch64) - if: matrix.target == 'aarch64-unknown-linux-gnu' - run: | - sudo apt-get update - sudo apt-get install -y gcc-aarch64-linux-gnu - echo "CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc" >> "$GITHUB_ENV" - - - name: Build release binary - run: cargo build --release --locked --target ${{ matrix.target }} -p eggress-cli - - - name: Rename binary (Unix) - if: runner.os != 'Windows' - run: | - cd target/${{ matrix.target }}/release - mv eggress eggress-${{ github.ref_name }}-${{ matrix.target }} - cp ${{ github.workspace }}/LICENSE . - tar czf ../../../eggress-${{ github.ref_name }}-${{ matrix.target }}.tar.gz \ - eggress-${{ github.ref_name }}-${{ matrix.target }} \ - LICENSE - cd ../../.. - - - name: Rename binary (Windows) - if: runner.os == 'Windows' - shell: pwsh - run: | - cd target/${{ matrix.target }}/release - Copy-Item eggress.exe "eggress-${{ github.ref_name }}-${{ matrix.target }}.exe" - Compress-Archive -Path "eggress-${{ github.ref_name }}-${{ matrix.target }}.exe" ` - -DestinationPath "../../../eggress-${{ github.ref_name }}-${{ matrix.target }}.zip" - cd ../../.. - - - uses: actions/upload-artifact@v4 - with: - name: binary-${{ matrix.target }} - path: eggress-${{ github.ref_name }}-${{ matrix.target }}.${{ matrix.archive }} - - # ── Python wheels ─────────────────────────────────────────────────── - build-wheels: - name: Wheel (${{ matrix.os }}-${{ matrix.target }}) - needs: ci-gates - runs-on: ${{ matrix.os }} - timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - include: - - os: ubuntu-latest - target: x86_64 - rust_target: x86_64-unknown-linux-gnu - wheel_smoke: false - - os: macos-13 - target: x86_64 - rust_target: x86_64-apple-darwin - wheel_smoke: true - - os: macos-latest - target: aarch64 - rust_target: aarch64-apple-darwin - wheel_smoke: true - - os: windows-latest - target: x86_64 - rust_target: x86_64-pc-windows-msvc - wheel_smoke: false - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - with: - targets: ${{ matrix.rust_target }} - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - name: Install maturin - run: pip install "maturin>=1.0,<2.0" - - - name: Build wheel - shell: bash - run: maturin build --release --target ${{ matrix.rust_target }} -i python --out dist - working-directory: crates/eggress-python - - - name: Smoke test wheel - shell: bash - if: ${{ matrix.wheel_smoke }} - run: | - python -m venv .venv-smoke - if [[ "${{ runner.os }}" == "Windows" ]]; then - . .venv-smoke/Scripts/activate - else - . .venv-smoke/bin/activate - fi - pip install crates/eggress-python/dist/eggress-*.whl - python -c "import eggress; print(eggress.__version__)" - python -c "from eggress.pproxy import check_pproxy_uri; print(check_pproxy_uri('socks5://127.0.0.1:1080'))" - - - uses: actions/upload-artifact@v4 - with: - name: wheel-${{ matrix.os }}-${{ matrix.target }} - path: crates/eggress-python/dist/*.whl - - build-sdist: - name: Source Distribution - needs: ci-gates - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - name: Install maturin - run: pip install "maturin>=1.0,<2.0" - - name: Build sdist - run: maturin sdist --out dist - working-directory: crates/eggress-python - - uses: actions/upload-artifact@v4 - with: - name: sdist - path: crates/eggress-python/dist/*.tar.gz - - build-pproxy-compat: - name: Top-level pproxy compatibility wheel - needs: ci-gates - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - name: Build compatibility wheel - run: python -m pip wheel --no-deps --wheel-dir dist ./python-pproxy-compat - - name: Upload compatibility wheel - uses: actions/upload-artifact@v4 - with: - name: pproxy-compat-wheel - path: dist/eggress_pproxy_compat-*.whl - - # ── Checksums and SBOM ───────────────────────────────────────────── - checksums: - name: Checksums & SBOM - needs: [build-binaries, build-wheels, build-sdist, build-pproxy-compat] - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - uses: actions/checkout@v4 - - - name: Download binaries - uses: actions/download-artifact@v4 - with: - path: artifacts - pattern: "binary-*" - merge-multiple: true - - name: Download wheels - uses: actions/download-artifact@v4 - with: - path: artifacts - pattern: "wheel-*" - merge-multiple: true - - name: Download sdist - uses: actions/download-artifact@v4 - with: - path: artifacts - name: sdist - merge-multiple: true - - name: Download compatibility wheel - uses: actions/download-artifact@v4 - with: - path: artifacts - name: pproxy-compat-wheel - merge-multiple: true - - - name: Generate SHA256SUMS - run: | - cd artifacts - find . -type f \( -name "*.tar.gz" -o -name "*.zip" -o -name "*.whl" \) \ - -not -name "SHA256SUMS" -exec sha256sum {} \; > ../SHA256SUMS - cd .. - cat SHA256SUMS - - - name: Generate SBOM (best-effort) - run: | - cargo install cargo-auditable || true - cargo auditable build --release -p eggress-cli || echo "::warning::SBOM generation skipped (cargo-auditable not available)" - pip install cyclonedx-bom || true - cyclonedx-py environment --format json --output-file sbom.json || echo "::warning::CycloneDX SBOM generation skipped" - - - name: SBOM placeholder - if: always() && !hashFiles('sbom.json') - run: | - echo '{"note": "SBOM generation failed or was skipped"}' > sbom.json - - - name: Install cosign - if: startsWith(github.ref, 'refs/tags/v') - uses: sigstore/cosign-installer@v3 - - - name: Sign checksums - if: startsWith(github.ref, 'refs/tags/v') - run: | - cosign sign-blob --yes --output-signature SHA256SUMS.sig \ - --output-certificate SHA256SUMS.cert SHA256SUMS - env: - COSIGN_EXPERIMENTAL: "1" - - - uses: actions/upload-artifact@v4 - with: - name: checksums-sbom - path: | - SHA256SUMS - SHA256SUMS.sig - SHA256SUMS.cert - sbom.json - - # ── Container image ──────────────────────────────────────────────── - build-container: - name: Container Image - needs: [build-binaries] - runs-on: ubuntu-latest - timeout-minutes: 20 - permissions: - contents: read - packages: write - steps: - - uses: actions/checkout@v4 - - - name: Download Linux binaries - uses: actions/download-artifact@v4 - with: - name: binary-x86_64-unknown-linux-gnu - path: binaries/x86_64 - - - name: Download Linux aarch64 binary - uses: actions/download-artifact@v4 - with: - name: binary-aarch64-unknown-linux-gnu - path: binaries/aarch64 - - - name: Prepare binaries for multi-arch build - run: | - mkdir -p build/x86_64 build/aarch64 - cd binaries/x86_64 - tar xzf *.tar.gz - mv eggress-* ../../build/x86_64/eggress - cd ../aarch64 - tar xzf *.tar.gz - mv eggress-* ../../build/aarch64/eggress - chmod +x ../../build/x86_64/eggress ../../build/aarch64/eggress - - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Login to GHCR - uses: docker/login-action@v3 - with: - registry: ghcr.io - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} - - - name: Build and push - uses: docker/build-push-action@v5 - with: - context: . - platforms: linux/amd64,linux/arm64 - push: ${{ startsWith(github.ref, 'refs/tags/v') }} - tags: | - ghcr.io/${{ github.repository_owner }}/eggress:${{ github.ref_name }} - ghcr.io/${{ github.repository_owner }}/eggress:latest - build-args: | - VERSION=${{ github.ref_name }} - - # ── GitHub Release ───────────────────────────────────────────────── - create-release: - name: GitHub Release - needs: [build-binaries, build-wheels, build-sdist, build-pproxy-compat, checksums] - runs-on: ubuntu-latest - timeout-minutes: 10 - permissions: - contents: write - packages: write - steps: - - uses: actions/checkout@v4 - - - name: Download binaries - uses: actions/download-artifact@v4 - with: - path: release-artifacts - pattern: "binary-*" - merge-multiple: true - - name: Download wheels - uses: actions/download-artifact@v4 - with: - path: release-artifacts - pattern: "wheel-*" - merge-multiple: true - - name: Download sdist - uses: actions/download-artifact@v4 - with: - path: release-artifacts - name: sdist - merge-multiple: true - - name: Download compatibility wheel - uses: actions/download-artifact@v4 - with: - path: release-artifacts - name: pproxy-compat-wheel - merge-multiple: true - - name: Download checksums and SBOM - uses: actions/download-artifact@v4 - with: - path: release-artifacts - name: checksums-sbom - merge-multiple: true - - - name: Create GitHub Release - uses: softprops/action-gh-release@v2 - with: - draft: true - generate_release_notes: false - files: | - release-artifacts/**/*.tar.gz - release-artifacts/**/*.zip - release-artifacts/**/*.whl - release-artifacts/SHA256SUMS - release-artifacts/SHA256SUMS.sig - release-artifacts/SHA256SUMS.cert - release-artifacts/sbom.json - body: | - ## eggress ${{ github.ref_name }} - - ### Installation - - **Binary:** See [BINARY_INSTALL.md](docs/release/BINARY_INSTALL.md) - **Python:** `pip install eggress==${{ github.ref_name }}` - **pproxy subset:** `pip install eggress-pproxy-compat==${{ github.ref_name }}` in a clean environment - **Container:** `docker pull ghcr.io/${{ github.repository_owner }}/eggress:${{ github.ref_name }}` - - ### Verification - - ```bash - sha256sum -c SHA256SUMS - ``` - - See [RELEASE_NOTES_PHASE_51.md](docs/release/RELEASE_NOTES_PHASE_51.md) for full release notes. - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/shadowsocks-interop.yml b/.github/workflows/shadowsocks-interop.yml deleted file mode 100644 index 4ae0ea71..00000000 --- a/.github/workflows/shadowsocks-interop.yml +++ /dev/null @@ -1,41 +0,0 @@ -name: Shadowsocks Interop - -on: - push: - branches: [main] - pull_request: - branches: [main] - workflow_dispatch: - -env: - CARGO_TERM_COLOR: always - RUSTFLAGS: -D warnings - -jobs: - shadowsocks-interop: - name: Shadowsocks Interop (Ubuntu) - runs-on: ubuntu-latest - timeout-minutes: 20 - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - with: - components: cargo - - uses: Swatinem/rust-cache@v2 - - name: Install shadowsocks-rust - run: cargo install shadowsocks-rust --features "local,server" - - name: Verify ssserver - run: ssserver --help - - name: Verify sslocal - run: sslocal --help - - name: Run Shadowsocks interop tests - env: - EGRESS_REQUIRE_SHADOWSOCKS_INTEROP: "1" - run: cargo test -p eggress-cli --test interoperability_shadowsocks -- --ignored --test-threads=1 - - name: Upload logs on failure - if: failure() - uses: actions/upload-artifact@v4 - with: - name: shadowsocks-interop-logs - path: target/tmp/ - if-no-files-found: ignore diff --git a/.github/workflows/strict-differential.yml b/.github/workflows/strict-differential.yml deleted file mode 100644 index a1cf5522..00000000 --- a/.github/workflows/strict-differential.yml +++ /dev/null @@ -1,134 +0,0 @@ -name: strict-differential - -on: - push: - branches: [main] - pull_request: - branches: [main] - workflow_dispatch: - -env: - CARGO_TERM_COLOR: always - -jobs: - strict-integrity: - name: Strict Manifest Integrity - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: Swatinem/rust-cache@v2 - - name: Validate strict manifest - run: cargo test -p eggress-testkit strict_manifest - - name: Validate strict report freshness - run: cargo run -p eggress-testkit --bin strict-report -- --check - - uses: actions/setup-python@v5 - with: - python-version: "3.11" - - name: Check release docs consistency - run: python3 scripts/check_release_docs.py - - strict-paired-api: - name: Strict Paired API (Python 3.11) - runs-on: ubuntu-latest - timeout-minutes: 20 - needs: strict-integrity - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: Swatinem/rust-cache@v2 - - uses: actions/setup-python@v5 - with: - python-version: "3.11" - - name: Set up oracle venv - run: | - python3 -m venv .venv-oracle - .venv-oracle/bin/pip install --upgrade pip - .venv-oracle/bin/pip install "pproxy==2.7.9" - .venv-oracle/bin/pip install pysocks cryptography - - name: Verify pproxy oracle - run: .venv-oracle/bin/python -c "from importlib.metadata import version; print(f'pproxy {version(\"pproxy\")}')" - - name: Set up candidate venv - run: | - python3 -m venv .venv-candidate - .venv-candidate/bin/pip install --upgrade pip - .venv-candidate/bin/pip install maturin pytest pytest-asyncio pytest-timeout cryptography - - name: Build eggress wheel - run: .venv-candidate/bin/maturin build --release --out target/wheels -m crates/eggress-python/Cargo.toml - - name: Install eggress wheel - run: | - WHEEL=$(ls target/wheels/eggress-*.whl) - .venv-candidate/bin/pip install "$WHEEL" - - name: Build and install compat wheel - run: | - .venv-candidate/bin/pip wheel --no-deps --wheel-dir target/wheels ./python-pproxy-compat - COMPAT_WHEEL=$(ls target/wheels/eggress_pproxy_compat-*.whl) - .venv-candidate/bin/pip install "$COMPAT_WHEEL" - - name: Verify candidate imports - run: | - .venv-candidate/bin/python -c "import pproxy; print(f'candidate pproxy OK')" - .venv-candidate/bin/python -c "import eggress; print(f'candidate eggress OK')" - - name: Run paired API probes (closure-required) - env: - ORACLE_VENV: ${{ github.workspace }}/.venv-oracle - CANDIDATE_VENV: ${{ github.workspace }}/.venv-candidate - run: | - python3 scripts/run_strict_pproxy_api.py \ - --oracle-venv "$ORACLE_VENV" \ - --candidate-venv "$CANDIDATE_VENV" \ - --closure-required - - name: Run strict differential tests - env: - EGRESS_REQUIRE_PPROXY_DIFFERENTIAL: "1" - run: | - .venv-candidate/bin/python -m pytest python/tests/strict/ -v --timeout=60 - - name: Upload paired observations - if: always() - uses: actions/upload-artifact@v4 - with: - name: strict-paired-observations-${{ github.sha }} - path: target/strict/paired_observations/ - if-no-files-found: error - retention-days: 30 - - strict-closure-audit: - name: Strict Closure Audit - runs-on: ubuntu-latest - timeout-minutes: 90 - needs: [strict-integrity, strict-paired-api] - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: Swatinem/rust-cache@v2 - - uses: actions/setup-python@v5 - with: - python-version: "3.11" - - name: Install cargo tools - run: | - cargo install cargo-deny - cargo install cargo-audit - - name: Install maturin system-wide - run: pip3 install "maturin>=1.0,<2.0" - - name: Install pproxy for interop tests - run: pip3 install "pproxy==2.7.9" - - name: Set up isolated oracle venv - run: | - python3 -m venv .venv-oracle-api - .venv-oracle-api/bin/pip install --upgrade pip - .venv-oracle-api/bin/pip install "pproxy==2.7.9" pysocks cryptography - - name: Set up isolated candidate venv - run: | - python3 -m venv .venv-candidate-api - .venv-candidate-api/bin/pip install --upgrade pip - .venv-candidate-api/bin/pip install maturin pytest pytest-asyncio pytest-timeout cryptography - - name: Run authoritative closure audit - run: ./scripts/run_strict_pproxy_closure_audit.sh - - name: Upload closure audit evidence - if: always() - uses: actions/upload-artifact@v4 - with: - name: strict-closure-audit-${{ github.sha }} - path: target/closure-audit/ - if-no-files-found: error - retention-days: 90 diff --git a/docs/CI_STATUS.md b/docs/CI_STATUS.md index e20c38ff..8a1404c7 100644 --- a/docs/CI_STATUS.md +++ b/docs/CI_STATUS.md @@ -1,150 +1,88 @@ -# CI Status +# CI and Verification Policy -## Hosted CI State +This document is the source of truth for repository verification. It supersedes older phase-completion documents and workflow descriptions that treated every available check as a mandatory gate. -As of 2026-06-26, hosted GitHub Actions CI is **non-functional** due to a -billing/payment issue on the repository account. All workflow runs fail -immediately (within 1–2 seconds) with: +## Policy -> The job was not started because recent account payments have failed or your -> spending limit needs to be increased. Please check the 'Billing & plans' -> section in your settings +Egress uses deliberately small hosted CI. GitHub Actions is a smoke signal for ordinary development, not a release engine, compatibility evidence archive, or substitute for focused local testing. -This affects both `ci.yml` and `security.yml` workflows on every push to -`main` and every pull request. No jobs actually execute — the failures are -not code-related. +The repository has two automatic workflows: -## Required Local Verification +- `.github/workflows/ci.yml`: one Ubuntu Rust job running format, Clippy, and the workspace test suite. +- `.github/workflows/python-test.yml`: one path-scoped Ubuntu/Python 3.12 smoke job for the Python binding and compatibility packages. -Before merging or marking a phase complete, run **all** of the following: +There are no tag-triggered release workflows, artifact assembly workflows, publishing workflows, cross-platform release matrices, or mandatory compatibility-evidence uploads. -```bash -cargo fmt --all -- --check -cargo check --workspace --all-targets -cargo test --workspace -cargo clippy --workspace --all-targets -- -D warnings -cargo deny check -cargo audit -``` - -These correspond to the six CI jobs: Format, Check, Test, Clippy, Deny, -and Audit. If all pass locally, the changes are correct regardless of -hosted CI status. - -## Workflows - -### ci.yml (primary) - -Triggers on pushes to `main` and pull requests to `main`. Contains these -separate visible jobs: - -| Job | Runner | What it checks | -|-----|--------|----------------| -| Format | ubuntu-latest | `cargo fmt --all -- --check` | -| Check | ubuntu/macos/windows | `cargo check --workspace --all-targets` | -| Test | ubuntu/macos/windows | `cargo test --workspace` | -| Clippy | ubuntu-latest | `cargo clippy --workspace --all-targets -- -D warnings` | -| Deny | ubuntu-latest | `cargo deny check` (license + advisory) | -| Audit | ubuntu-latest | `cargo audit` (security advisories) | -| Interoperability | ubuntu-latest | Cross-implementation tests (pproxy, curl) | - -### pproxy-compatibility.yml - -Triggers on pushes to `main`, pull requests to `main`, and manual dispatch. -Runs the full pproxy compatibility suite: - -| Job | Runner | What it checks | -|-----|--------|----------------| -| pproxy Compat | ubuntu-latest | Manifest validation, pproxy oracle tests, differential tests, interoperability tests, parity report | - -Requires `pproxy==2.7.9` (Python). Manifest validation runs before differential -tests. Parity report artifacts are uploaded on every run. +## Routine development -### shadowsocks-interop.yml +Use the narrowest local command that exercises the code being changed. Examples: -Triggers on pushes to `main`, pull requests to `main`, and manual dispatch. -Runs Shadowsocks standard interop tests: - -| Job | Runner | What it checks | -|-----|--------|----------------| -| Shadowsocks Interop | ubuntu-latest | TCP/UDP interop with `ssserver`/`sslocal` from `shadowsocks-rust` | - -Requires `shadowsocks-rust` (installed via `cargo install`). Logs uploaded -on failure. This is a manually-gated workflow — Shadowsocks interop claims -cite this workflow but it is not required for merge. - -### security.yml (legacy — removed) +```bash +cargo test -p eggress-routing +cargo test -p eggress-runtime retry_fallback +cargo test -p eggress-cli --test cli_exit_codes +``` -Previously ran duplicate `cargo-deny` and `cargo-audit` jobs using older -action versions. Superseded by the Deny and Audit jobs in `ci.yml`. Removed -to avoid confusion and wasted billing minutes. +Formatting should normally be applied locally before commit: -### python-test.yml +```bash +cargo fmt --all +``` -Runs Python tests on push to `main` and pull requests affecting Python code. +A routine change does not require security audits, cross-platform matrices, ignored interoperability suites, benchmark runs, parity-report regeneration, or completion-evidence documents unless the change directly affects those areas. -| Job | Runner | What it checks | -|-----|--------|----------------| -| Test (matrix) | ubuntu-latest, macos-latest × Python 3.9/3.12/3.13 | `maturin develop` + `pytest python/tests` | +## Before merge -### python-compat.yml +For a normal Rust change, the expected broad local check is: -Runs clean canonical/compatibility wheel smoke tests on Linux, macOS, and -Windows. It verifies that the canonical wheel stays namespace-clean and that -the separate `eggress-pproxy-compat` wheel supplies the top-level `pproxy` -imports and native outbound stream tests. +```bash +cargo fmt --all -- --check +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace --locked +``` -### python-wheels.yml +For a Python-facing change, also build the extension and run the relevant Python tests: -Builds platform wheels on version tags (`v*`). +```bash +python3 -m venv .venv +.venv/bin/python -m pip install "maturin>=1.0,<2.0" pytest "pytest-asyncio>=0.23,<1" "cryptography>=42,<47" +(cd crates/eggress-python && ../../.venv/bin/maturin develop) +.venv/bin/python -m pip install --no-deps ./python-pproxy-compat +.venv/bin/python -m pytest python/tests tests/compat -q +``` -| Job | Runner | What it builds | -|-----|--------|----------------| -| build_wheels (matrix) | ubuntu/macos/windows × x86_64/aarch64 | Platform-specific wheel | -| build_sdist | ubuntu-latest | Source distribution | +A focused test may be sufficient during iteration. The broad workspace check is expected before merging a substantial change, not after every edit. -### publish-pypi.yml +## Specialized checks -Publishes to PyPI or TestPyPI via manual dispatch. Uses trusted publishing (OIDC). +Run these only when their trigger condition applies: -| Input | Options | Default | -|-------|---------|---------| -| repository | `testpypi`, `pypi` | `testpypi` | +| Check | Trigger | +|---|---| +| `cargo deny check` | Dependency, feature, or license-policy changes; release preparation | +| `cargo audit --ignore RUSTSEC-2025-0134` | Dependency changes; release preparation | +| pproxy differential/oracle suites | Compatibility behavior, manifests, URI translation, or pproxy namespace changes | +| Shadowsocks external interoperability | Shadowsocks wire-format, cipher, or relay changes | +| strict closure audit | Explicit compatibility-certification work | +| benchmarks, load, soak, or fuzzing | Performance, concurrency, parser, or hardening work | +| cross-platform local/hosted checks | Platform-specific code or release preparation | -**Note:** All Python workflows are subject to the same billing limitations as `ci.yml`. Local verification remains the source of truth. +The commands remain documented in `docs/TESTING.md`, `docs/DIFFERENTIAL_TESTING.md`, and `AGENTS.md`. Their existence does not make them routine merge gates. -## Performance Testing +## Evidence and completion records -Performance tests are gated and not run in CI by default. See `docs/performance/` for the full guide. +Ordinary implementation work requires a clear commit message and passing relevant tests. It does not require generated parity reports, uploaded workflow artifacts, large completion documents, screenshots, or copied command transcripts. -| Test | Command | Gating | -|------|---------|--------| -| Tier 0 benchmarks | `cargo bench --workspace` | Informational (manual) | -| Tier 1 smoke | `cargo test -p eggress-runtime --test performance_smoke` | Automated | -| Tier 2 soak | `EGRESS_REQUIRE_SOAK=1 cargo test -p eggress-runtime --test reverse_soak -- --ignored` | Gated | -| Tier 3 pproxy | `EGRESS_REQUIRE_PPROXY_PERF=1 scripts/perf/run_pproxy_comparison.sh` | Gated | -| Python perf | `python -m pytest python/tests/test_performance_smoke.py` | Automated | +Compatibility claims must still be backed by the applicable oracle or interoperability suite. Evidence should be generated when a claim changes or a release is being evaluated, not on every push. -## How to Interpret Completion Docs +## Release boundary -When hosted CI is unavailable, completion documents (e.g. -`PHASE_*_COMPLETION.md`) should record: +Release cadence is entirely manual. GitHub Actions must not publish crates, create GitHub Releases, push container images, build release bundles, or react to version tags. -1. **Local verification commands run** — which of the six commands were - executed and their pass/fail status. -2. **Local test output** — relevant test names and counts, not full trace. -3. **Absence of hosted CI** — explicitly note that hosted CI was not - observable, and that local verification is the source of truth. +The release operator performs release checks and `cargo publish` locally. See `docs/release/RELEASE_PROCESS.md`. -Do not claim "CI passed" when only local verification was performed. Say -"Local verification passed" instead. +## Design rationale -## Known Blockers +The previous apparatus duplicated compilation and linting across multiple workflows, ran operating-system and Python-version matrices for routine changes, installed external implementations on every push, generated evidence artifacts continuously, and repeated the same gates inside release automation. That increased latency and maintenance without proportionate correctness benefit. -- **Billing**: GitHub Actions minutes are unavailable until the repository - owner resolves the payment issue in Settings → Billing & plans. -- **No secrets required**: None of the CI jobs depend on custom repository - secrets. The only secret used is `GITHUB_TOKEN` (automatic). -- **No paid-only actions**: All actions used (`actions/checkout`, - `dtolnay/rust-toolchain`, `Swatinem/rust-cache`, - `EmbarkStudios/cargo-deny-action`) are free for public repositories. +The lean policy preserves the highest-value invariant checks while moving expensive or environment-sensitive verification to the point where it is technically relevant. diff --git a/docs/TESTING.md b/docs/TESTING.md index e2651b33..867fab49 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -1,265 +1,143 @@ # Testing -## Normal Local Checks +Egress uses targeted local testing during development, a small workspace gate before merge, and specialized suites only when the affected subsystem requires them. The canonical policy is `docs/CI_STATUS.md`. -Run these before any commit. See `AGENTS.md` for the canonical list. +## Routine local testing -```bash -# Format -cargo fmt --all - -# Check formatting -cargo fmt --all -- --check - -# Compile check -cargo check --workspace - -# Run all tests -cargo test --workspace +Run the narrowest test that covers the change: -# Lint -cargo clippy --workspace --all-targets -- -D warnings - -# Security audit -cargo deny check -cargo audit +```bash +cargo test -p eggress-uri +cargo test -p eggress-routing scheduler +cargo test -p eggress-runtime retry_fallback +cargo test -p eggress-cli --test cli_exit_codes ``` -## Focused Test Commands - -Per-crate test suites from `AGENTS.md`: +Apply formatting as part of normal development: ```bash -# UDP-focused tests -cargo test -p eggress-udp -cargo test -p eggress-runtime udp -cargo test -p eggress-config udp - -# UDP upstream tests -cargo test -p eggress-udp socks5_upstream -cargo test -p eggress-runtime udp_upstream - -# Protocol-specific tests -cargo test -p eggress-protocol-trojan -cargo test -p eggress-transport-tls - -# Shadowsocks protocol tests -cargo test -p eggress-protocol-shadowsocks -cargo test -p eggress-runtime shadowsocks_tcp -cargo test -p eggress-runtime shadowsocks_udp - -# Reverse proxy tests -cargo test -p eggress-protocol-reverse -cargo test -p eggress-runtime reverse -cargo test -p eggress-runtime --test reverse_soak -EGRESS_REQUIRE_REVERSE_INTEROP=1 cargo test -p eggress-runtime --test reverse_interop -- --ignored - -# Upstream protocol tests (HTTP, SOCKS4, SOCKS5, WS, Raw) -cargo test -p eggress-runtime upstream_protocols - -# CLI -cargo run --bin eggress -- --help -cargo run --bin eggress -- -l http://:8080 -cargo run --bin eggress -- --config path/to/config.toml +cargo fmt --all ``` -## Integration Tests - -Integration tests live in `crates/eggress-runtime/tests/` and exercise the supervisor end-to-end: +Do not run every compatibility, security, performance, and platform suite after each edit. That produces long feedback cycles without improving the signal for a focused change. -| Test File | Coverage | -|-----------|----------| -| `startup.rs` | Basic supervisor startup and listener binding | -| `routing.rs` | Rule evaluation and route selection | -| `health.rs` | Health probe lifecycle | -| `admin.rs` | Admin endpoint responses | -| `reload.rs` | Config reload success, rejection, failure | -| `shutdown.rs` | Graceful shutdown and drain | -| `pac_static.rs` | PAC file and static content serving | -| `udp.rs` | UDP association lifecycle, TCP control close, echo relay, bind conflict, topology rejection, config reload | -| `udp_upstream.rs` | SOCKS5 upstream relay through full stack | -| `upstream_protocols.rs` | HTTP, SOCKS4, SOCKS5, WS/Raw upstream relay, and unsupported-combo rejection | -| `shadowsocks_tcp.rs` | Shadowsocks TCP relay through full stack | -| `shadowsocks_udp.rs` | Shadowsocks UDP relay through full stack | -| `reverse_interop.rs` | Reverse/backward proxy self-interop and credential redaction (3 un-gated tests) | -| `reverse_runtime.rs` | Runtime reverse server/client lifecycle, supervisor spawning, metrics (13 tests) | -| `reverse_soak.rs` | Soak tests: performance, reconnect churn, auth failure churn (3 gated tests, requires `EGRESS_REQUIRE_SOAK=1`) | +## Broad pre-merge check -Negative-path tests cover: bind conflict, invalid source, oversized identity, reload-time failure. +Before merging a substantial Rust change, run: -## Property Tests +```bash +cargo fmt --all -- --check +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace --locked +``` -Property-based testing with `proptest` is enabled for codec and parser crates: +`cargo check` is not a separate required gate because Clippy and the test build already compile the workspace. It remains useful interactively when a faster compile-only pass is desired. -| Crate | What is tested | -|-------|----------------| -| `eggress-uri` | URI parsing roundtrips | -| `eggress-protocol-socks` | SOCKS4/4a and SOCKS5 codec encode/decode | -| `eggress-protocol-http` | HTTP CONNECT message parsing | -| `eggress-protocol-trojan` | Trojan password/header parsing | -| `eggress-routing` | Rule matching, CIDR parsing, regex compilation | +## Python binding and compatibility package -Run property tests with: +For Python-facing changes: ```bash -cargo test -p eggress-uri proptest -cargo test -p eggress-protocol-socks proptest -cargo test -p eggress-protocol-http proptest -cargo test -p eggress-protocol-trojan proptest -cargo test -p eggress-routing proptest +python3 -m venv .venv +.venv/bin/python -m pip install --upgrade pip +.venv/bin/python -m pip install "maturin>=1.0,<2.0" pytest "pytest-asyncio>=0.23,<1" "cryptography>=42,<47" +(cd crates/eggress-python && ../../.venv/bin/maturin develop) +.venv/bin/python -m pip install --no-deps ./python-pproxy-compat +.venv/bin/python -m pytest python/tests tests/compat -q ``` -## Gated Interoperability Tests - -Differential interoperability tests compare eggress behavior against Python `pproxy`. All tests are `#[ignore]` and require: - -1. Environment variable: `EGRESS_REQUIRE_EXTERNAL_INTEROP=1` -2. Python 3 with `pproxy` installed (`pip install pproxy`) +Use a focused Python module while iterating, for example: ```bash -EGRESS_REQUIRE_EXTERNAL_INTEROP=1 cargo test -p eggress-cli --test differential_pproxy -- --ignored +.venv/bin/python -m pytest python/tests/test_proxy_connection.py -q +.venv/bin/python -m pytest tests/compat/test_pproxy_api_contract.py -q ``` -Tests cover: HTTP CONNECT, SOCKS4, SOCKS5, multi-hop chains, authentication, and binary payload transfer. +Routine hosted Python CI uses one Ubuntu/Python 3.12 smoke environment. Additional Python versions and operating systems are release or compatibility checks, not per-change gates. -Gated reverse interop tests (`EGRESS_REQUIRE_REVERSE_INTEROP=1`) test eggress↔pproxy wire compatibility for the reverse/backward proxy protocol. +## Dependency and security checks -### pproxy Compatibility Harness (Phase 18) +Run dependency-policy checks when dependencies, features, licenses, or release inputs change: -The compatibility harness launches real pproxy processes and compares behavior -with eggress. It requires `pproxy==2.7.9` to be installed. - -Run with: ```bash -cargo test -p eggress-testkit pproxy_oracle -- --ignored +cargo deny check +cargo audit --ignore RUSTSEC-2025-0134 ``` -The harness uses: -- `tests/compat/pproxy_target.toml` — pinned pproxy version and timeouts -- `tests/compat/pproxy_manifest.toml` — feature evidence index -- `eggress-testkit` — oracle runner, fixtures, case model, report generator - -Parity reports are generated at: -- `target/compat/pproxy-parity-report.json` - -### Scenario-Driven Oracle Harness (Track A.01) +These are intentionally not installed and executed by routine CI. Installing auditing tools on every push is slow and duplicates checks whose inputs usually did not change. -The oracle harness provides scenario-driven comparison of eggress vs pproxy -under equivalent conditions. 31 scenarios across 5 categories: CLI/defaults, -HTTP/SOCKS TCP, Chains, Rules, UDP. +## pproxy compatibility -Gate: `EGRESS_ORACLE=1` +The ordinary workspace suite includes non-ignored compatibility tests. External oracle and differential suites are opt-in because they install and launch Python `pproxy==2.7.9`: ```bash -# Run all oracle scenarios -EGRESS_ORACLE=1 cargo test -p eggress-cli --test oracle -- --ignored +python3 -m pip install "pproxy==2.7.9" +EGRESS_REQUIRE_EXTERNAL_INTEROP=1 \ + cargo test -p eggress-cli --test differential_pproxy -- --ignored --test-threads=1 -# Run a specific scenario -EGRESS_ORACLE=1 cargo test -p eggress-cli --test oracle oracle_tcp_socks5_connect -- --ignored --nocapture - -# Generate a JSON comparison report -EGRESS_ORACLE=1 cargo test -p eggress-cli --test oracle oracle_generate_report -- --ignored +cargo test -p eggress-testkit pproxy_oracle -- --ignored ``` -Always-run unit tests (no gate needed): +Run these when changing pproxy behavior, URI translation, compatibility manifests, process behavior, or the top-level `pproxy` namespace. See `docs/DIFFERENTIAL_TESTING.md` for the full harness. + +The strict certification audit is reserved for explicit closure or release evaluation: + ```bash -cargo test -p eggress-cli --test oracle -cargo test -p eggress-testkit oracle +./scripts/run_strict_pproxy_closure_audit.sh ``` -Scenario registry and report types live in `eggress_testkit::oracle`. - -### pproxy Chain Tests (Phase 39) +Its generated reports are evidence for compatibility claims. They are not routine merge artifacts. -Chain-related tests cover URI parsing and translation of `__`-separated multi-hop chains: +## Protocol interoperability -- `crates/eggress-pproxy-compat/src/uri.rs` — URI chain parsing: `__` separator, semicolon/comma rejection, per-hop protocol validation (14 tests) -- `crates/eggress-pproxy-compat/src/translate.rs` — Chain translation: multi-hop TOML generation, unsupported protocol diagnostics per hop (8 tests) +External interoperability checks are subsystem-specific: -Run with: ```bash -cargo test -p eggress-pproxy-compat -``` -- `target/compat/pproxy-parity-report.md` +# Shadowsocks wire compatibility; requires ssserver and sslocal +EGRESS_REQUIRE_SHADOWSOCKS_INTEROP=1 \ + cargo test -p eggress-cli --test interoperability_shadowsocks -- --ignored --test-threads=1 -## Fuzz Smoke Testing +# Reverse protocol compatibility; requires pproxy +EGRESS_REQUIRE_REVERSE_INTEROP=1 \ + cargo test -p eggress-runtime --test reverse_interop -- --ignored --test-threads=1 +``` -Fuzz targets live in `fuzz/` (standalone workspace, `libfuzzer-sys` based): +Run them after changes to the relevant wire format, cipher, handshake, relay path, or compatibility claim. -| Target | What it fuzzes | -|--------|----------------| -| `fuzz_targets/uri_parse.rs` | URI parser with arbitrary input | -| `fuzz_targets/socks5_udp_datagram.rs` | SOCKS5 UDP datagram codec with arbitrary input | -| `fuzz_targets/socks5_handshake.rs` | SOCKS5 method negotiation + CONNECT/UDP_ASSOCIATE request parsers | -| `fuzz_targets/http_connect_response.rs` | HTTP CONNECT status line, authority, header, basic-auth parsers | -| `fuzz_targets/trojan_request.rs` | Trojan password hash + request encoder across IP / domain targets | -| `fuzz_targets/route_match.rs` | Route matcher evaluation with constructed routers and requests | +## Performance, soak, and load tests -Run fuzz smoke testing (requires `cargo-fuzz`): +Performance and endurance tests are manual: ```bash -cargo fuzz run uri_parse -- -runs=1000 -cargo fuzz run socks5_udp_datagram -- -runs=1000 -cargo fuzz run socks5_handshake -- -runs=1000 -cargo fuzz run http_connect_response -- -runs=1000 -cargo fuzz run trojan_request -- -runs=1000 -cargo fuzz run route_match -- -runs=1000 +cargo test -p eggress-runtime --test performance_smoke +cargo bench --workspace +EGRESS_REQUIRE_SOAK=1 \ + cargo test -p eggress-runtime --test reverse_soak -- --ignored --test-threads=1 +EGRESS_REQUIRE_PPROXY_PERF=1 ./scripts/perf/run_pproxy_comparison.sh ``` -Fuzz targets can also be smoke-compiled without `cargo-fuzz`: +Use them for performance-sensitive or concurrency-heavy work and before a release when the changed path warrants it. + +## Fuzzing and parser hardening + +Fuzz targets are in the standalone `fuzz/` workspace. Compile-smoke or run only the targets relevant to the parser being changed: ```bash cargo check --manifest-path fuzz/Cargo.toml --bins -cargo test --manifest-path fuzz/Cargo.toml --no-run +cargo fuzz run uri_parse -- -runs=1000 +cargo fuzz run socks5_udp_datagram -- -runs=1000 ``` -## Ignored Load Tests +## Cross-platform verification -Some tests are marked `#[ignore]` for load or long-running scenarios. Run with: +Routine CI runs on Ubuntu. Validate macOS or Windows when modifying platform-specific code, process supervision, filesystem behavior, system proxy integration, packaging, or release artifacts. Cross-platform matrices are not required for unrelated changes. -```bash -cargo test -- --ignored -``` - -## Benchmark Commands +## Test selection rule -Benchmarks use `criterion` with HTML reports: +A change is adequately verified when: -```bash -cargo bench -``` +1. The directly affected unit or integration tests pass. +2. The broad workspace gate passes before merge for substantial changes. +3. Any specialized claim changed by the patch is exercised by its corresponding opt-in suite. -| Benchmark | What it measures | -|-----------|------------------| -| `tcp_relay` | TCP bidirectional relay throughput | -| `udp_relay` | UDP datagram relay throughput | -| `route_match` | Routing rule matching latency | -| `http_connect_upstream` | HTTP CONNECT upstream open latency (no auth, basic auth, 407 rejection) | - -## Security Invariant Tests - -The following tests verify security invariants: - -| Test | Crate | What it verifies | -|------|-------|------------------| -| `metric_names_are_stable` | `eggress-metrics` | All metric names appear in output (no accidental removal) | -| `labels_no_secrets` | `eggress-metrics` | No password/secret/token in metric output | -| `bridge_no_privacy_leak` | `eggress-metrics` | No IP addresses in metrics output | -| `prometheus_output_is_parseable` | `eggress-metrics` | Every non-comment line has valid numeric value | -| `test_redacted_display` | `eggress-uri` | `RedactedUri` replaces credentials with `****:****@` | -| `validate_credentials` | `eggress-protocol-http` | Control characters rejected in HTTP auth | - -## Observability Tests - -| Test | Crate | What it verifies | -|------|-------|------------------| -| `counter_increments` | `eggress-metrics` | Route decision counter increments correctly | -| `gauge_returns_to_zero` | `eggress-metrics` | Upstream health gauge returns to 0 | -| `session_recording_updates_all_metrics` | `eggress-metrics` | Session lifecycle updates all relevant metrics | -| `udp_association_metrics` | `eggress-metrics` | UDP association creation/closure tracked | -| `udp_packet_metrics` | `eggress-metrics` | UDP packet/byte counters update | -| `bridge_*` | `eggress-metrics` | Bridged UdpMetrics appear in Prometheus output | -| `health_returns_200` | `eggress-admin` | `/-/health` returns 200 | -| `ready_returns_200` / `ready_returns_503_when_not_ready` | `eggress-admin` | `/-/ready` reflects readiness state | -| `metrics_returns_prometheus_format` | `eggress-admin` | `/metrics` returns valid Prometheus text | -| `pac_endpoint_returns_pac_when_configured` | `eggress-admin` | PAC file served at configured path | +More commands are not inherently stronger evidence. Verification should be proportional to the code and claim being changed. diff --git a/docs/release/RELEASE_PROCESS.md b/docs/release/RELEASE_PROCESS.md index 9bd02ce0..8539ae73 100644 --- a/docs/release/RELEASE_PROCESS.md +++ b/docs/release/RELEASE_PROCESS.md @@ -1,184 +1,135 @@ -# Release Process (Phase 49) +# Manual Release Process -This document defines the end-to-end release process for eggress, covering -Rust binaries, Python wheels, container images, and all associated artifacts. +Egress releases are operator-driven. GitHub Actions does not publish crates, build release bundles, create GitHub Releases, push container images, publish Python packages, or react to version tags. + +No release cadence is encoded in the repository. A maintainer releases when the code and version are ready. + +## Release target + +The primary release channel is crates.io using local `cargo publish` commands. Git tags and GitHub Releases are optional bookkeeping performed manually after crates.io publication; they are not release prerequisites or automation triggers. + +Python/PyPI distribution is a separate manual operation and must not be coupled to the Rust release workflow. ## Prerequisites -- Rust stable toolchain (MSRV 1.75) -- Python >= 3.9 with `maturin` installed -- `gh` CLI authenticated (for GitHub Release creation) -- `cargo-deny` and `cargo-audit` installed -- Write access to the repository +- A clean local checkout of the intended commit. +- Rust stable and the repository MSRV available. +- crates.io credentials configured with `cargo login` or `CARGO_REGISTRY_TOKEN`. +- The intended version committed in all affected manifests and user-visible version constants. +- Release notes or changelog text prepared when the change warrants it. -## Pre-release checklist +Crates.io versions are immutable. A published version cannot be overwritten. If publication partially succeeds or a package is incorrect, fix the repository, increment the version, and publish a new version. -### 1. Code quality gates +## 1. Verify the release candidate -All of these must pass on `main` before tagging: +Run the broad local gate once on the exact release commit: ```bash cargo fmt --all -- --check -cargo check --workspace --all-targets -cargo test --workspace cargo clippy --workspace --all-targets -- -D warnings -cargo deny check -cargo audit +cargo test --workspace --locked ``` -### 2. Python package verification +Run dependency and advisory checks because release inputs are changing: ```bash -cd crates/eggress-python -maturin build --release --out ../../dist -cd ../.. -./scripts/test_wheel.sh -python3 scripts/validate_pproxy_parity_manifest.py --strict docs/parity/pproxy_capability_manifest.toml -``` - -### 3. Manifest validation - -```bash -cargo test -p eggress-testkit --lib manifest -cargo test -p eggress-testkit --lib corpus +cargo deny check +cargo audit --ignore RUSTSEC-2025-0134 ``` -### 4. Version alignment +Run specialized interoperability, Python, performance, or cross-platform checks only when the release contains relevant changes or makes claims that depend on them. The selection policy is in `docs/TESTING.md`. -Verify version is consistent across: +## 2. Check package metadata -- `Cargo.toml` workspace version -- `crates/eggress-python/pyproject.toml` -- `crates/eggress-python/Cargo.toml` -- `python/eggress/__init__.py` (`__version__`) +For every crate intended for publication, verify: -### 5. Documentation review +- the package version is correct; +- published internal dependencies specify a crates.io version as well as any local path used for workspace development; +- required `description`, `license`, `repository`, `readme`, and include/exclude metadata are present; +- generated package contents do not contain secrets, fixtures, large evidence directories, or development-only artifacts. -- [ ] Release notes updated (`docs/release/RELEASE_NOTES_PARITY_RC.md`) -- [ ] Platform support matrix current (`docs/release/PLATFORM_SUPPORT_MATRIX.md`) -- [ ] Migration guide current (`docs/release/MIGRATION_FROM_PPROXY_FINAL.md`) -- [ ] README install section accurate - -## Release steps - -### Step 1: Create release branch (optional) +Use a dry run for each public crate: ```bash -git checkout -b release/v0.1.0 +cargo publish --dry-run -p ``` -### Step 2: Tag the release +A dry-run failure is a packaging defect. Fix it before publishing rather than adding CI automation around it. -```bash -git tag -a v0.1.0 -m "Release v0.1.0" -git push origin v0.1.0 -``` +## 3. Publish dependency-first -### Step 3: Wait for CI +Publish crates in dependency order. Leaf libraries must be available in the crates.io index before crates that depend on them can be published. The CLI or other top-level facade should be published last. -The `v*` tag triggers: +For each crate: -- **`python-wheels.yml`**: Builds wheels for 5 platforms, uploads as artifacts -- **`release.yml`**: Builds CLI binaries, generates checksums/SBOM, creates GitHub Release +```bash +cargo publish -p +``` -### Step 4: Create GitHub Release +Wait for crates.io index propagation before publishing the next dependent crate. Re-run that dependent crate's dry run if resolution is uncertain. -If not auto-created by CI: +Do not use `--allow-dirty` for a normal release. Do not publish from an unreviewed working tree. -```bash -gh release create v0.1.0 \ - --title "eggress v0.1.0" \ - --notes-file docs/release/RELEASE_NOTES_PARITY_RC.md \ - --draft -``` +## 4. Verify crates.io installation -### Step 5: Upload artifacts to GitHub Release +Install the published top-level package into a clean temporary location: ```bash -gh release upload v0.1.0 \ - dist/eggress-*.tar.gz \ - dist/eggress-*.zip \ - dist/SHA256SUMS \ - dist/sbom.json +cargo install eggress-cli --version --locked --root /tmp/eggress-release-check +/tmp/eggress-release-check/bin/eggress --version +/tmp/eggress-release-check/bin/pproxy --help ``` -### Step 6: Publish Python package to PyPI +Use an equivalent temporary directory on platforms where `/tmp` is unavailable. -Trigger the `publish-pypi.yml` workflow manually, or: +If the release includes public libraries, create a minimal temporary consumer project and confirm that Cargo resolves the published versions without workspace paths. -```bash -cd crates/eggress-python -maturin upload --repository pypi ../../dist/* -``` +## 5. Optional manual repository bookkeeping -### Step 7: Build and push container image +After crates.io verification, a maintainer may create and push a tag: ```bash -docker buildx build --platform linux/amd64,linux/arm64 \ - -t ghcr.io/{owner}/eggress:v0.1.0 \ - -t ghcr.io/{owner}/eggress:latest \ - --push . +git tag -a v -m "Release v" +git push origin v ``` -### Step 8: Finalize GitHub Release +A GitHub Release may also be created manually for notes or separately built binaries: ```bash -gh release edit v0.1.0 --draft=false +gh release create v \ + --title "eggress v" \ + --notes-file ``` -## Post-release +These commands are optional and must remain manual. Pushing a tag must not start publishing, artifact construction, signing, container pushes, or release creation in GitHub Actions. -### Verify installation methods +## Python distribution -```bash -# Binary -./eggress --version - -# Python -pip install eggress==0.1.0 -python -c "import eggress; print(eggress.__version__)" - -# Container -docker pull ghcr.io/{owner}/eggress:v0.1.0 -docker run --rm ghcr.io/{owner}/eggress:v0.1.0 --version -``` +When the Python packages are ready for a separate release, build and publish them locally with maturin and the chosen Python package repository credentials. Verify canonical `eggress` and `eggress-pproxy-compat` packages together in a clean environment before upload. -### Update documentation +Python publishing is intentionally outside the crates.io release procedure. Removing GitHub publishing workflows does not imply that Python packaging is abandoned; it means packaging cadence and credentials remain under explicit operator control. -- [ ] Tag the release in README badge/links -- [ ] Update ROADMAP.md with completed phase -- [ ] Create `docs/release/RELEASE_v0.1.0.md` if needed +## Roll-forward policy -## Rollback +Crates.io publication is irreversible except for yanking. For a defective release: -If a critical regression is found: +1. Yank the affected version when appropriate. +2. Correct the defect. +3. Increment the package version. +4. Repeat dry runs and relevant verification. +5. Publish the corrected version. -1. **Yank Python wheels**: `twine yank eggress==0.1.0` -2. **Delete GitHub Release** (binaries are not yankable) -3. **Push patch**: `v0.1.1` with the fix -4. **Rebuild and republish** all artifacts +Do not delete or retag an existing version to simulate replacement. -## Versioning +## Prohibited automation -- Use semantic versioning: `MAJOR.MINOR.PATCH` -- Tags use the format `vX.Y.Z` -- Python package version must match the git tag version -- Workspace `Cargo.toml` version is the single source of truth +The following must not be added back without an explicit project-level decision: -## CI/CD flow +- publishing on a tag or branch push; +- crates.io tokens or trusted-publishing configuration in GitHub Actions; +- automated GitHub Release creation; +- mandatory release artifact, checksum, SBOM, signature, or container jobs; +- a release workflow that repeats the ordinary CI suite; +- release gates that require generated evidence unrelated to the changed release surface. -``` -git tag v0.1.0 - │ - ├─→ python-wheels.yml (v* trigger) - │ ├─ Build wheels (5 platforms) - │ ├─ Build sdist - │ └─ Upload artifacts - │ - └─→ release.yml (v* trigger) - ├─ Build CLI binaries (5 targets) - ├─ Generate SHA256SUMS - ├─ Generate SBOM - ├─ Build container image - └─ Create GitHub Release with all artifacts -``` +Release correctness comes from a clean release commit, proportionate local verification, package dry runs, explicit operator publication, and post-publication installation checks.