Implement HTTP relay proxy with upstream load balancing (round-robin/best/priority), captive-style health checking, domain blacklist/whitelist routing with domain-expression matching, and hot reload

.github/copilot-instructions.md

@@ -0,0 +1,49 @@
+# Copilot Instructions
+
+## Project coding notes
+
+- Language: Rust (edition 2021)
+- Runtime: Tokio
+- Proxy protocol handling is in `src/proxy.rs`
+- Configuration is YAML via `yaml_serde`
+- Admin endpoints and shared metrics are in `src/admin.rs`
+- Integration coverage lives in `tests/integration_smoke.rs`
+- Container smoke coverage lives in `scripts/docker-smoke.sh`
+
+## Project status
+
+- This project is in a completed-v1 / release-ready state.
+- Default to preserving current runtime behavior unless a task explicitly asks for a change.
+- Regressions in proxy forwarding, response codes, admin APIs, metrics, graceful shutdown, request timeouts, connection limiting, and Docker deployment should be treated as important.
+
+## Development expectations
+
+1. Make surgical changes that directly address the request.
+2. Add/adjust tests for changed behavior.
+3. Keep docs aligned with user-facing configuration changes.
+4. Validate with:
+   - `cargo test`
+   - `cargo clippy -- -D warnings`
+   - `cargo fmt -- --check`
+   - `./scripts/docker-smoke.sh` when Docker-related or deployment behavior changes
+   - `./target/debug/http-proxy-lb --config config.yaml --check` when config behavior changes
+
+## Validation focus
+
+- Prefer integration coverage for:
+  - config validation
+  - real HTTP status propagation
+  - request timeout behavior
+  - connection limiting behavior
+  - admin metrics/status counters
+- Keep README, `AGENTS.md`, and this file aligned when the project’s validation workflow changes.
+
+## Domain policy expressions
+
+`domain_policy.domains` currently supports:
+
+- `domain:example.com` (exact match)
+- `suffix:example.com` (domain suffix match)
+- `*.example.com` (suffix shorthand)
+- `.example.com` (suffix shorthand)
+- `example.com` (backward-compatible exact-or-suffix behavior)

.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  validate:
+    name: Validate
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+
+      - name: Cache Rust artifacts
+        uses: Swatinem/rust-cache@v2
+
+      - name: Format check
+        run: cargo fmt -- --check
+
+      - name: Clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Test
+        run: cargo test --locked
+
+  binary-build:
+    name: Binary Build (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust artifacts
+        uses: Swatinem/rust-cache@v2
+
+      - name: Build release binary
+        run: cargo build --release --locked
+
+      - name: Upload binary artifact (Unix)
+        if: runner.os != 'Windows'
+        uses: actions/upload-artifact@v6
+        with:
+          name: http-proxy-lb-${{ runner.os }}
+          path: target/release/http-proxy-lb
+
+      - name: Upload binary artifact (Windows)
+        if: runner.os == 'Windows'
+        uses: actions/upload-artifact@v6
+        with:
+          name: http-proxy-lb-${{ runner.os }}
+          path: target/release/http-proxy-lb.exe
+
+  docker-build:
+    name: Docker Build
+    runs-on: ubuntu-latest
+    needs: validate
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Run Docker smoke test
+        run: ./scripts/docker-smoke.sh

.github/workflows/release.yml

@@ -0,0 +1,137 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  packages: write
+
+env:
+  CARGO_TERM_COLOR: always
+  BINARY_NAME: http-proxy-lb
+
+jobs:
+  release-binaries:
+    name: Release Binary (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-x86_64
+            os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            archive_ext: tar.gz
+          - name: macos-aarch64
+            os: macos-14
+            target: aarch64-apple-darwin
+            archive_ext: tar.gz
+          - name: windows-x86_64
+            os: windows-latest
+            target: x86_64-pc-windows-msvc
+            archive_ext: zip
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Cache Rust artifacts
+        uses: Swatinem/rust-cache@v2
+
+      - name: Build release binary
+        run: cargo build --release --locked --target ${{ matrix.target }}
+
+      - name: Package archive (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          set -euo pipefail
+          pkg_dir="${BINARY_NAME}-${{ github.ref_name }}-${{ matrix.target }}"
+          mkdir -p "${pkg_dir}"
+          cp "target/${{ matrix.target }}/release/${BINARY_NAME}" "${pkg_dir}/"
+          cp README.md LICENSE "${pkg_dir}/"
+          tar -czf "${pkg_dir}.tar.gz" "${pkg_dir}"
+
+      - name: Package archive (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $pkgDir = "${env:BINARY_NAME}-${{ github.ref_name }}-${{ matrix.target }}"
+          New-Item -ItemType Directory -Path $pkgDir | Out-Null
+          Copy-Item "target/${{ matrix.target }}/release/${env:BINARY_NAME}.exe" "$pkgDir/"
+          Copy-Item "README.md","LICENSE" "$pkgDir/"
+          Compress-Archive -Path "$pkgDir/*" -DestinationPath "$pkgDir.zip"
+
+      - name: Upload packaged artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: release-${{ matrix.target }}
+          path: |
+            http-proxy-lb-${{ github.ref_name }}-${{ matrix.target }}.tar.gz
+            http-proxy-lb-${{ github.ref_name }}-${{ matrix.target }}.zip
+          if-no-files-found: ignore
+
+  github-release:
+    name: GitHub Release
+    runs-on: ubuntu-latest
+    needs: release-binaries
+
+    steps:
+      - name: Download packaged artifacts
+        uses: actions/download-artifact@v5
+        with:
+          path: dist
+          pattern: release-*
+          merge-multiple: true
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.tar.gz
+            dist/*.zip
+          generate_release_notes: true
+
+  docker-release:
+    name: Docker Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=ref,event=tag
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+## Purpose
+
+This repository contains `http-proxy-lb`, a Rust HTTP relay proxy with upstream load balancing, health checks, hot reload, domain policy routing, admin endpoints, Prometheus metrics, graceful shutdown, request limits, and container deployment assets.
+
+## Status
+
+- The repository is in a near-release / completed-v1 state.
+- Prefer preserving the current behavior and validation baseline unless the task explicitly requires a change.
+- Treat regressions in proxy behavior, admin endpoints, metrics, timeout handling, connection limiting, or Docker deployment as high priority.
+
+## Scope
+
+- Keep code changes minimal and focused.
+- Prefer targeted tests first, then full validation.
+- Preserve existing behavior unless the task explicitly requires a change.
+
+## Local validation
+
+- Run tests: `cargo test`
+- Run lint checks: `cargo clippy -- -D warnings`
+- Format code: `cargo fmt -- --check`
+- Run container smoke test: `./scripts/docker-smoke.sh`
+- Validate config file: `./target/debug/http-proxy-lb --config config.yaml --check`
+
+## Code structure
+
+- `src/config.rs`: configuration model and YAML loading
+- `src/admin.rs`: admin server, `/metrics`, `/status`, `/health`, and shared metrics
+- `src/upstream.rs`: upstream entry state + pool selection/reload
+- `src/health.rs`: active health checking logic
+- `src/proxy.rs`: CONNECT and HTTP forwarding logic
+- `src/main.rs`: startup, accept loop, background tasks
+- `tests/integration_smoke.rs`: end-to-end integration tests for config validation, timeouts, metrics, and connection limits
+- `scripts/docker-smoke.sh`: local Docker smoke test helper
+
+## Expectations
+
+- Keep changes minimal and targeted.
+- Update tests and docs for any user-visible behavior change.
+- Prefer keeping `cargo test`, `cargo clippy -- -D warnings`, `cargo fmt -- --check`, and `./scripts/docker-smoke.sh` green before considering work complete.