lkrequest 0.1.0__tar.gz

lkrequest-0.1.0/.editorconfig

@@ -0,0 +1,23 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.rs]
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{toml,yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[Justfile]
+indent_style = space
+indent_size = 4

lkrequest-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,195 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  # Keep PEP 517 source installs aligned with the all-feature release wheels.
+  MATURIN_PEP517_ARGS: "--all-features"
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - name: cargo fmt --check
+        run: cargo fmt --check
+      - name: cargo clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
+
+  test:
+    name: Test (source)
+    needs: [lint]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build & install (source, all features) + test deps
+        run: pip install ".[test]"
+      - name: Verify all feature APIs
+        run: python -c "import lkrequest; required = ('QuicProfile', 'Layers', 'NegotiabilityFloor'); missing = [name for name in required if not hasattr(lkrequest, name)]; assert not missing, f'missing all-feature APIs:{missing}'"
+      - name: Run tests
+        run: pytest tests/ -v
+
+  build-wheels:
+    name: Wheel · ${{ matrix.target }}
+    needs: [test]
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            runner: ubuntu-latest
+            manylinux: "2_28"
+          - target: x86_64-pc-windows-msvc
+            runner: windows-latest
+            manylinux: "auto"
+          - target: aarch64-apple-darwin
+            runner: macos-15
+            manylinux: "auto"
+          - target: x86_64-apple-darwin
+            runner: macos-15-intel
+            manylinux: "auto"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up NASM (Windows)
+        if: runner.os == 'Windows'
+        uses: ilammy/setup-nasm@v1
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.manylinux }}
+          args: --release --strip --all-features --out dist
+          sccache: "true"
+          before-script-linux: |
+            dnf install -y cmake perl clang || yum install -y cmake perl clang
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.target }}
+          path: dist/*.whl
+          if-no-files-found: error
+
+  build-sdist:
+    name: sdist
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  test-wheel:
+    name: Test wheel · ${{ matrix.os }} · py${{ matrix.python }}
+    needs: [build-wheels]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            wheel: wheel-x86_64-unknown-linux-gnu
+            python: "3.9"
+          - os: ubuntu-latest
+            wheel: wheel-x86_64-unknown-linux-gnu
+            python: "3.12"
+          - os: windows-latest
+            wheel: wheel-x86_64-pc-windows-msvc
+            python: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/download-artifact@v4
+        with:
+          name: ${{ matrix.wheel }}
+          path: dist
+      - name: Install wheel + test deps
+        shell: bash
+        run: pip install "$(ls dist/*.whl)[test]"
+      - name: Verify all feature APIs
+        run: python -c "import lkrequest; required = ('QuicProfile', 'Layers', 'NegotiabilityFloor'); missing = [name for name in required if not hasattr(lkrequest, name)]; assert not missing, f'missing all-feature APIs:{missing}'"
+      - name: Run tests
+        run: pytest tests/ -v
+
+  release-assets:
+    name: Upload to GitHub Release
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [test-wheel, build-sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Attach artifacts to release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          fail_on_unmatched_files: true
+
+  check-pypi-token:
+    name: Check PyPI token
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    outputs:
+      configured: ${{ steps.check.outputs.configured }}
+    steps:
+      - id: check
+        env:
+          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if [ -n "$PYPI_API_TOKEN" ]; then
+            echo "configured=true" >> "$GITHUB_OUTPUT"
+            echo "PYPI_API_TOKEN is set; publish-pypi will run."
+          else
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::PYPI_API_TOKEN is not set; skipping publish-pypi (GitHub Release assets are unaffected)."
+          fi
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v') && needs.check-pypi-token.outputs.configured == 'true'
+    needs: [test-wheel, build-sdist, check-pypi-token]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          password: ${{ secrets.PYPI_API_TOKEN }}

lkrequest-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+/target
+__pycache__
+*.pyc
+*.pyo
+*.egg-info
+dist/
+build/
+.venv/
+*.so
+*.pyd
+*.dll
+.pytest_cache/
+.cargo/
+.claude/
+EVOLUTION_PLAN.md
+.idea
+.DS_Store
+CLAUDE.md
+Makefile
+AGENTS.md

lkrequest-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All important changes to this project will be documented in this file.
+
+## lkrequest-py 0.2.0
+
+### 🚀 Features
+- **Synthetic Fingerprint Negotiability (`synthetic-fp`)** — Added `NegotiabilityFloor.UNIVERSAL`, `NegotiabilityFloor.PRESET_FAMILY`, `NegotiabilityFloor.custom(...)`, and `Randomize.negotiability(...)` so synthesized ClientHello profiles retain a configurable signature-algorithm compatibility floor.
+- **Multi-hop Proxy Chains** — Added `ProxyConfig.parse_chain(...)` and `.through(...)`, with chain metadata via `hop_count()` and `identity()`. Client sessions, proxy pools, and session pools now accept either proxy URLs or `ProxyConfig` objects.
+- **Mixed Proxy Transports** — HTTP/1.1 and HTTP/2 can traverse ordered combinations of HTTP CONNECT, SOCKS5, and SOCKS5H hops. QUIC/HTTP3 supports all-SOCKS5 chains when the optional `quic-h3` feature is enabled.
+- **Chrome 150 QUIC/H3 (`quic-h3`)** — `Client.chrome_150()` now uses dedicated Chrome 150 QUIC TLS and HTTP/3 profiles instead of reusing Chrome 146. The preset covers captured signature algorithms, QUIC transport parameters, QPACK limits, navigation `PRIORITY_UPDATE`, connection-ID lengths, and Initial datagram sizing. Added `QuicProfile.chrome_150()` and the `"chrome_150"` QUIC profile name.
+
+### 🐞 Fixes
+- **TLS Handshake Reassembly** — TLS 1.2 and TLS 1.3 handshake messages fragmented across multiple records are now buffered and reassembled correctly, preventing failures such as `truncated handshake message in record` without changing ClientHello or fingerprint output.
+- **SOCKS5 UDP Relay Compatibility** — QUIC-over-SOCKS5 accepts relay replies from the advertised source IP even when the relay uses a different egress port, preventing affected HTTP/3 requests from hanging.
+- **Package Version Reporting** — `lkrequest.__version__` is now read from installed distribution metadata instead of being maintained as a separate hard-coded value.
+- **TLS 1.3 ECH + HelloRetryRequest** — Real ECH CH2 now reuses the ECH configuration, HPKE sender context, Inner random, GREASE values, extension permutation, and fake ECH bytes. HRR confirmation, selected groups, cookie-only retries, invalid extensions, dummy CCS, and local fatal alerts now follow the browser/RFC flow.
+- **ECH + PSK + HRR Binders** — `pre_shared_key` remains exclusively in `ClientHelloInner`; CH1 and CH2 binders now use the correct truncated Inner transcripts, including `message_hash(ClientHelloInner1) + HRR` for CH2.
+- **QUIC/H3 HRR State Transitions** — QUIC revokes 0-RTT stream and packet state after HRR and maps local TLS alerts to QUIC `CRYPTO_ERROR` codes.
+
+## lkrequest-py 0.1.0
+
+### 🚀 Features
+- **TLS Fingerprint Control** — Byte-level ClientHello generation that matches real browsers (Chrome, Firefox, Safari)
+- **HTTP/2 Fingerprint Control** — SETTINGS frame order, pseudo-header order, WINDOW_UPDATE, PRIORITY frames, and per-request priority weights
+- **HTTP/3 + QUIC** — Optional `quic-h3` feature for full HTTP/3 over QUIC with fingerprint-aware Transport Parameters, Alt-Svc auto-discovery, and H2→H3 seamless upgrade
+- **Built-in Browser Presets** — Chrome 131/144/145/146/147/148/149/150, Firefox 133/147, Safari 18/26 (TLS + H2, plus QUIC when `quic-h3` is enabled)
+- **Session Management** — Cookie jars, connection pooling, HTTP/2 multiplexing, and optional QUIC 0-RTT session resumption
+- **Connection Prewarming** — `session.preconnect()` pre-establishes DNS + TCP + TLS + H2 (or, with `quic-h3`, QUIC + H3) connections
+- **Custom DNS Resolver** — Pluggable DNS with DoH support, auto ECH config and H3 hints via HTTPS/SVCB records
+- **Alt-Svc Discovery** — Automatic HTTP/2 → HTTP/3 protocol upgrade via Alt-Svc headers with broken-QUIC fallback
+- **SessionPool** — High-concurrency pool with proxy rotation (round-robin / random)
+- **Proxy Support** — SOCKS5 and HTTP CONNECT with authentication
+- **WebSocket** — HTTP/1.1 Upgrade (RFC 6455) and H2 Extended CONNECT (RFC 8441)
+- **Middleware** — Interceptor chain for request/response modification
+- **Retry Policies** — Exponential backoff, fixed interval, custom strategies; idempotency-aware (non-idempotent methods are not silently replayed after a possibly-already-sent failure unless marked `Idempotency::Idempotent`)
+- **Redirect Control** — `RedirectPolicy::Follow(n)` or `RedirectPolicy::None` for manual handling
+- **Auto-Decompression** — Brotli, gzip, deflate, zstd
+- **Blocking API** — Synchronous wrapper for non-async contexts
+- **Multipart/Form-Data** — File uploads with streaming support
+- **TCP Fingerprint** — JA4T-style TCP SYN fingerprinting

lkrequest-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to lkrequest
+
+Thanks for your interest in contributing! This package is a [PyO3](https://pyo3.rs)
+binding over the `lkrequest` Rust workspace, built with
+[maturin](https://www.maturin.rs).
+
+## Development setup
+
+```bash
+git clone https://github.com/ez-opensource/lkrequest-py
+cd lkrequest-py
+python3 -m venv .venv                 # Linux/macOS
+# py -m venv .venv                    # Windows
+# Windows:        .venv\Scripts\Activate.ps1
+# Linux / macOS:  source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install maturin
+python -m pip install -e ".[test,lint]"
+```
+
+Alternatively, use uv to create and manage the environment:
+
+```bash
+uv sync --extra test --extra lint
+```
+
+Optional build features:
+
+```bash
+maturin develop --features telemetry  # enable metrics_snapshot() counters
+maturin develop --features quic-h3     # enable QUIC / HTTP3
+```
+
+## Running the test suite
+
+```bash
+python -m pip install -e ".[test]"   # pytest + local server dependencies
+just test
+
+# With uv:
+just test
+# Or:
+uv run pytest tests/ -v
+
+# Skip the network/server tests and run only unit-level checks:
+python -m pytest tests/ -v -k "not httpbin and not echo"
+```
+
+## Before opening a pull request
+
+The CI lint gate is strict — please run these locally and make sure they pass:
+
+```bash
+cargo fmt --all          # format (CI runs `cargo fmt --check`)
+cargo clippy -- -D warnings
+python -m pytest tests/ -v
+```
+
+A few project conventions:
+
+- **Type stubs are the source of truth for the public API.** Any new public
+  class, method, or module function in Rust must also be declared in
+  `python/lkrequest/_lkrequest.pyi`. `tests/test_stub_parity.py` enforces this.
+- **Avoid `unwrap()` / `expect()`** in non-test code (clippy is configured to
+  warn). Propagate errors with `?` and the project's error types, or add an
+  `#[allow(...)]` with a justifying comment where a panic is genuinely
+  unreachable (e.g. a `LazyLock` initializer).
+- Keep new code formatted to match the surrounding style; `cargo fmt` handles
+  this for Rust.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+[Apache License 2.0](LICENSE), consistent with the rest of the project.