goodput-http 0.1.0__tar.gz

goodput_http-0.1.0/.claude/settings.local.json

@@ -0,0 +1,48 @@
+{
+  "permissions": {
+    "allow": [
+      "PowerShell(pip *)",
+      "PowerShell(py *)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pip install -q \"httpx[http2]\" anyio pydantic pydantic-settings 2>&1 | Select-Object -Last 5)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pip install -q pytest pytest-anyio hypothesis trio respx 2>&1 | Select-Object -Last 5; echo \"DONE\")",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -c \"import httpx, anyio, pydantic, pydantic_settings, trio, respx, hypothesis; print\\('httpx', httpx.__version__\\); print\\('anyio', anyio.__version__\\); print\\('pydantic', pydantic.VERSION\\)\")",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -c \"import importlib.metadata as m; [print\\(p, m.version\\(p\\)\\) for p in ['httpx','anyio','pydantic','pydantic-settings','trio','respx','hypothesis','pytest']]\")",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pip install -q -e . 2>&1 | Select-Object -Last 10; echo \"EXIT=$LASTEXITCODE\")",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pip install -q -e . 2>&1 | Select-Object -Last 6; echo \"EXIT=$LASTEXITCODE\")",
+      "Bash(.venv/Scripts/python.exe /tmp/smoke.py)",
+      "Bash(echo \"EXIT=$?\")",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/test_control_mode.py tests/test_models.py tests/test_retry_after.py tests/test_classify.py tests/test_retry.py -q 2>&1 | Select-Object -Last 30)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/ -q -p anyio 2>&1 | Select-Object -Last 35)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/test_controllers.py tests/test_engine.py 2>&1 | Select-Object -Last 40)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/test_controllers.py tests/test_engine.py 2>&1 | Select-Object -Last 25)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/test_config.py tests/test_simulation.py 2>&1 | Select-Object -Last 30)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/ 2>&1 | Select-Object -Last 8)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/test_transport_respx.py tests/test_checkpoint_cli.py 2>&1 | Select-Object -Last 40)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/ 2>&1 | Select-Object -Last 6)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m goodput.cli version; echo \"---\"; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m goodput.cli validate --concurrency 20 --adaptive --max-concurrency 200)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\goodput.exe version 2>&1)",
+      "Bash(cat)",
+      "Bash(.venv/Scripts/python.exe /tmp/server.py)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\goodput.exe run --url http://127.0.0.1:8731/ --count 500 --concurrency 20 --adaptive --max-concurrency 100 2>&1 | Select-Object -First 40)",
+      "Bash(curl -s \"http://127.0.0.1:8731/__shutdown\")",
+      "Bash(powershell.exe -Command 'Get-Process python -ErrorAction SilentlyContinue | Where-Object {$_.Path -like '\\\\''*goodput*'\\\\''} | Stop-Process -Force -ErrorAction SilentlyContinue')",
+      "Bash(powershell.exe *)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -c \"import ast; [ast.parse\\(open\\(f\\).read\\(\\)\\) for f in ['examples/01_repeat_endpoint.py','examples/02_fixed_concurrency_per_ip.py','examples/03_isolated_throttle_scope.py']]; print\\('examples parse OK'\\)\")",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pip install -q build 2>&1 | Select-Object -Last 2; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m build 2>&1 | Select-Object -Last 8)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pip install -q ruff 2>&1 | Select-Object -Last 1; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m ruff check src tests 2>&1 | Select-Object -Last 40)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m ruff check --fix src tests 2>&1 | Select-Object -Last 5; echo \"=== REMAINING ===\"; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m ruff check src tests 2>&1 | Select-Object -Last 60)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m ruff check src tests --output-format concise 2>&1)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m ruff check src tests 2>&1; echo \"=== TESTS ===\"; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/ 2>&1 | Select-Object -Last 5)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m ruff check src tests 2>&1)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pip install -q mypy 2>&1 | Select-Object -Last 1; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m mypy src 2>&1 | Select-Object -Last 40)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m mypy src 2>&1 | Select-Object -Last 30)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m mypy src 2>&1 | Select-Object -Last 20)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m ruff check src tests 2>&1; echo \"=== PYTEST ===\"; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/ 2>&1 | Select-Object -Last 6)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m ruff check --fix src tests 2>&1 | Select-Object -Last 3; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m ruff check src tests 2>&1; echo \"=== mypy ===\"; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m mypy src 2>&1 | Select-Object -Last 3)",
+      "PowerShell(& C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m pytest tests/ -q 2>&1 | Select-Object -Last 4; echo \"=== build ===\"; & C:\\\\Users\\\\amoradi\\\\projects\\\\misc\\\\goodput\\\\.venv\\\\Scripts\\\\python.exe -m build 2>&1 | Select-Object -Last 2)",
+      "Bash(.venv/Scripts/python.exe -m pytest tests/ --co -q)",
+      "Bash(.venv/Scripts/python.exe -m pytest tests/ -q)",
+      "Bash(.venv/Scripts/python.exe -m pytest tests/)"
+    ]
+  }
+}

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

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,http2]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Type check
+        run: mypy src
+      - name: Test
+        run: pytest -q
+
+  build:
+    name: build & install from artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel + sdist
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Install from wheel
+        run: |
+          pip install dist/*.whl
+          python -c "import goodput; print(goodput.__version__)"
+          goodput version

goodput_http-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish Python package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Store distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/goodput-http/
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+

goodput_http-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+htmlcov/
+.coverage
+.coverage.*
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# goodput run artifacts
+*.jsonl
+checkpoints/
+reports/

goodput_http-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,192 @@
+# goodput — Architecture
+
+> An adaptive HTTP execution engine that maximizes **sustainable successful
+> logical-request goodput** while treating every user-declared fixed value as an
+> invariant.
+
+This document is the architecture deliverable required by the project brief
+(section 41). It is intentionally concise; deeper rationale lives in the
+`docs/adr/` Architecture Decision Records.
+
+---
+
+## 1. Problem analysis
+
+The task is to execute very large volumes of HTTP requests while *automatically
+maximizing the rate of terminally-successful logical requests* — **goodput** —
+subject to a user-controlled authority model. The hard parts are not "send many
+requests" (a `asyncio.gather` loop does that). The hard parts are:
+
+1. **Goodput vs. offered load.** A logical request may take several attempts. We
+   must count one logical success/failure regardless of attempts, and optimize
+   the *successful* rate, not the attempt rate. Naive load generators happily
+   melt a server and report "1M requests sent" while goodput collapses.
+2. **Authority.** Users must be able to pin any dimension (concurrency,
+   per-IP concurrency, route count, rate, retries…) as an invariant the
+   optimizer may never touch, while still letting the optimizer tune everything
+   else *around* those invariants.
+3. **Bounded everything.** Memory, queues, task creation, and response retention
+   must stay bounded under infinite/lazy workloads.
+4. **Attribution.** A proxy-auth failure must not penalize the origin; a
+   target-wide outage must not quarantine one healthy route.
+5. **Explainability.** Every adaptive decision must be recordable and auditable.
+
+## 2. Competitor evaluation (summary)
+
+| Tool | Role for us |
+|------|-------------|
+| **HTTPX / HTTPCore** | Chosen transport. Async, HTTP/2, proxies, custom transports, source-address binding via `httpcore`. MIT/BSD. Active. |
+| **aiohttp** | Capable but client model is heavier to abstract; HTTPX's `AsyncBaseTransport` seam is cleaner for pluggable routes. Kept as a possible alt-transport plugin. |
+| **AnyIO** | Chosen concurrency foundation: structured concurrency, task groups, capacity limiters, cancellation that works on both asyncio and Trio. |
+| **Tenacity** | Good retry primitive but we need retry tied to *logical-request* accounting, idempotency, and route selection — so retries live behind our own `RetryPolicy` abstraction (Tenacity may back it as a plugin). |
+| **aiometer / aiolimiter / PyrateLimiter** | Algorithmic references. We implement our own token-bucket/GCRA so limiter state can be scoped per route/credential and shared/isolated for throttle-scope testing. |
+| **Locust / k6** | Comparison & interop targets, not the core engine. Their VU model is closed-loop only; we support both open- and closed-loop. |
+| **Netflix concurrency-limits / Envoy adaptive concurrency** | Controller references: AIMD, Gradient/Gradient2, Vegas-style minimum-RTT tracking. We implement AIMD + a gradient controller. |
+| **OpenTelemetry / Prometheus / structlog** | Optional observability integrations behind extras; never required, never configured at import time. |
+| **Redis** | Optional distributed limiter/coordination backend. |
+| **PyArrow / HDR / t-digest** | Optional Parquet sink; streaming stats use an in-house log-bucketed histogram (no required dep). |
+
+## 3. Dependency evaluation
+
+**Required (minimal):** `httpx`, `anyio`, `pydantic`, `pydantic-settings`.
+Everything substantial (HTTP/2, SOCKS, Redis, OTel, Prometheus, Parquet, CLI,
+structlog) is an **optional extra**. No required dependency does networking or
+logging configuration at import time.
+
+## 4. Recommended architecture
+
+A **closed control loop** wrapped around a **bounded execution pipeline**:
+
+```
+ RequestSource (lazy, async)            Observability (events → sinks/metrics/logs)
+        │                                        ▲
+        ▼                                        │
+   Ingress queue ──► Admission ──► Worker pool ──► Classifier ──► Result accounting
+   (bounded)         (limiters,     (bounded,       (success/      (logical vs attempt)
+                      circuits,      AnyIO          throttle/         │
+                      route pick)    CapacityLimiter)  error)         ▼
+        ▲                                                        Result sinks
+        │                                                             │
+   Controllers ◄──────────── metrics window ◄───────────────────────┘
+   (authority-gated: only touch ADAPTIVE / BOUNDED_ADAPTIVE knobs)
+```
+
+## 5. Major subsystem boundaries
+
+- **models** — `LogicalRequest`, `Attempt`, `LogicalResult`, classifications.
+- **control_mode** — `Controlled[T]` value with `FIXED/ADAPTIVE/BOUNDED_ADAPTIVE/DISABLED/INHERIT`.
+- **config** — pydantic-validated `EngineConfig`; constraint validation & dry-run plan.
+- **classify** — pluggable success/throttle/error classifiers.
+- **ratelimit / retry_after / retry / circuit** — pacing & resilience primitives.
+- **routing** — `Route`, selectors, health, quarantine, throttle-scope.
+- **control** — controller protocol + AIMD/Gradient implementations + decision records.
+- **scheduler/engine** — bounded pipeline, permit accounting, cancellation, lifecycle.
+- **stats / report / events / sinks** — observability & output.
+- **sim** — deterministic in-memory server transports for controller tests.
+
+## 6. Public API proposal
+
+```python
+import goodput as gp
+
+result = await gp.run(
+    gp.repeat(gp.Request("GET", "https://api.example/health"), times=10_000),
+    config=gp.EngineConfig(
+        objective=gp.Objective.MAX_GOODPUT,
+        global_concurrency=gp.adaptive(initial=20, minimum=1, maximum=500),
+        request_rate=gp.fixed(None),            # unpaced
+    ),
+)
+print(result.report.summary())
+```
+
+The engine is also usable as an explicit context-managed object
+(`async with gp.Engine(config) as e: report = await e.run(source)`), and a
+synchronous convenience wrapper `gp.run_sync(...)`.
+
+## 7. Configuration-authority model
+
+Every tunable is a `Controlled[T]`. Modes: **FIXED** (invariant — optimizer must
+never change), **ADAPTIVE** (optimizer owns it), **BOUNDED_ADAPTIVE** (optimizer
+owns it within `[minimum, maximum]`, respecting `max_step` and `min_interval`),
+**DISABLED** (capability off), **INHERIT** (take broader scope's value). The
+optimizer is *structurally* unable to write a FIXED value — controllers receive
+only the set of `BOUNDED_ADAPTIVE`/`ADAPTIVE` handles.
+
+## 8. Constraint-resolution model
+
+Constraints form a hierarchy (global → target → route-group → route → IP →
+credential → request). Resolution rule: **the most specific value wins, but may
+never exceed a hard higher-level ceiling.** The validator detects contradictions
+(e.g. per-route fixed concurrency × route count > global ceiling) *before*
+execution. Runtime conflicts emit explicit `ConstraintEvent`s and are reported,
+never silently resolved by mutating a FIXED value.
+
+## 9. Adaptive-controller strategy
+
+Multiple timescales: concurrency changes fast (AIMD/Gradient on latency + error
+signal), rate changes at moderate cadence, route weights periodically.
+Controllers consume a `Sample` (goodput, error ratio, throttle ratio, latency
+percentiles, queue/limiter wait) and emit a `Decision` (variable, old, new,
+mode, bounds, reason, confidence, expected effect) which is recorded and later
+correlated with observed effect. Guards against oscillation, retry storms, and
+sample bias are built into the controllers.
+
+## 10. Route-optimization strategy
+
+Routes (direct / local-IP-bound / proxy) are first-class. Selectors: weighted,
+round-robin, least-in-flight, latency-aware, goodput-aware. Health tracking with
+quarantine + recovery probes. The optimizer may redistribute traffic among
+fixed routes (route_weights ADAPTIVE) without changing a FIXED route set or
+per-route concurrency.
+
+## 11. Throttle-scope model
+
+`DECLARED / SHARED / ISOLATED_FOR_TEST / INFERRED / CUSTOM`. Limiter and
+controller state is keyed by a scope resolver. The library never merges isolated
+scopes when the user has asked for isolation (authorized scope testing), and
+reports inference with confidence, evidence, and limitations — never as proof.
+
+## 12–13. Observability & reporting strategy
+
+Events are emitted to an in-process bus; subscribers include sinks, the live CLI
+display, and optional Prometheus/OTel exporters. Reports strictly separate
+planned/generated/admitted/completed/successful/failed/throttled logical
+requests from attempts/retries, and provide per-route/IP/credential breakdowns,
+timelines, and (for authorized tests) throttle-scope findings.
+
+## 14. Testing strategy
+
+pytest + AnyIO + RESPX/mock transports + Hypothesis + a deterministic fake clock
+and an in-memory simulated server. Property invariants enforce the safety rules
+in brief §36 (fixed never changes, bounded stays in bounds, one terminal state
+per logical request, no permit leaks, secrets never serialized…).
+
+## 15. Security & misuse-risk analysis
+
+Secure defaults (TLS verify on, bounded bodies, redirect limits, secret
+redaction everywhere), authorization scaffolding (host/CIDR allowlists, run
+ceilings, emergency stop, immutable run metadata with authorization reference).
+**Excluded by design:** credential theft, exploit delivery, CAPTCHA bypass,
+stealth/evasion, target discovery. The library does not grant permission to test
+any system; the operator is responsible for authorization.
+
+## 16. Phased implementation plan
+
+Mirrors brief §42. The repository is kept runnable + tested after every phase.
+Implemented here: Phase 1 (core), Phase 2 (resilience), Phase 3 (controllers +
+sim), Phase 4 (routing/scope), Phase 5 (report/CLI/sinks). Phase 6 (distributed)
+is scaffolded with documented interfaces.
+
+## 17. ADRs
+
+See `docs/adr/`. Key decisions: HTTPX transport, AnyIO concurrency, in-house
+limiter & histogram (zero required deps), `Controlled[T]` authority primitive,
+logical-vs-attempt accounting as the central invariant.
+
+### Environment note
+
+The brief requests Python ≥ 3.11. This implementation targets **≥ 3.10** so it
+runs and is tested on the development machine (3.10). All code is 3.10-compatible
+and forward-compatible with 3.11/3.12. Bump `requires-python` to `>=3.11` if you
+do not need 3.10 support.

goodput_http-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+- GitHub Actions trusted-publishing workflow for releasing `goodput-http` to
+  PyPI from GitHub Releases.
+
+### Changed
+
+- Renamed the published distribution from `goodput` to `goodput-http` while
+  keeping the import package as `goodput`.
+- Corrected project metadata URLs to point at
+  `https://github.com/alimoradics/goodput`.
+
+## [0.1.0] - 2026-06-17
+
+### Added
+
+- Core domain model with strict logical-request vs. attempt accounting.
+- `Controlled[T]` configuration-authority primitive
+  (FIXED / ADAPTIVE / BOUNDED_ADAPTIVE / DISABLED / INHERIT).
+- Validated `EngineConfig` with pre-execution contradiction detection and a
+  dry-run plan renderer.
+- Bounded, cancellation-safe execution engine with a closed adaptive control loop.
+- AIMD and latency-gradient concurrency controllers with fully auditable decisions.
+- Pluggable success / throttle / error classifiers; Retry-After and RateLimit
+  header parsing.
+- Idempotency-aware retries with retry budgets; circuit breakers.
+- First-class routes (direct / source-IP-bound / proxy), route selectors, health
+  tracking with quarantine + recovery, and failure attribution.
+- Throttle-scope modes (DECLARED / SHARED / ISOLATED_FOR_TEST / INFERRED / CUSTOM).
+- Bounded-memory streaming statistics (log-bucketed histogram, EWMA, rolling window).
+- Secret redaction across logs, events, reports, and sinks.
+- Result sinks (bounded memory, JSONL) with explicit failure policies.
+- Checkpoint + resume; entry-point plugin registry.
+- `argparse`-based CLI (`validate` / `run` / `plugins` / `version`).
+- Deterministic simulation transport and controller simulations.
+- 120+ unit, property, integration, and simulation tests.
+
+[Unreleased]: https://github.com/alimoradics/goodput/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/alimoradics/goodput/releases/tag/v0.1.0

goodput_http-0.1.0/CLAUDE.md

@@ -0,0 +1,122 @@
+# CLAUDE.md — goodput
+
+Guidance for Claude Code (and humans) working in this repository. Read this
+first. Subdirectory `CLAUDE.md` files add detail for `src/goodput/` and `tests/`.
+
+## What this project is
+
+`goodput` is a production-grade, async-first Python library that executes very
+high volumes of HTTP requests while **automatically maximizing sustainable
+successful logical-request goodput** — terminally-successful logical requests per
+unit time, *not* attempt volume. It is a library first, with an optional CLI,
+pluggable policies, route/egress optimization, an adaptive control system, and
+support for **authorized** throttling-validation testing.
+
+The full design rationale is in `ARCHITECTURE.md`; conceptual docs in `docs/`.
+This file is operational guidance, not a duplicate of those.
+
+## The one-paragraph mental model
+
+A lazy `RequestSource` feeds a **bounded** pipeline: ingress queue → bounded
+worker pool (concurrency capped by an `anyio.CapacityLimiter`) → transport →
+classifier → result accounting → sinks. A periodic **controller loop** samples
+metrics and adjusts *only* the knobs the user marked adaptive. Every tunable is a
+`Controlled[T]` that declares whether the optimizer may touch it; FIXED values
+are structurally immutable. A logical request may make several attempts but
+terminates in exactly one outcome.
+
+## Environment & toolchain
+
+- **Python target is `>=3.10`** (not 3.11). The dev machine only has 3.10, so the
+  code is written and tested against 3.10 and is forward-compatible with
+  3.11/3.12. `tomllib` is imported with a `tomli` fallback for 3.10. Do not use
+  3.11+-only syntax/stdlib without a fallback.
+- A virtualenv lives at `.venv/`. Always use it:
+  - Tests: `.venv/Scripts/python.exe -m pytest tests/`
+  - Lint: `.venv/Scripts/python.exe -m ruff check src tests`
+  - Types: `.venv/Scripts/python.exe -m mypy src`
+  - Build: `.venv/Scripts/python.exe -m build`
+- Shell is PowerShell (or the Bash tool). On Windows the venv binaries are under
+  `.venv/Scripts/` (`python.exe`, `goodput.exe`, `ruff`, `mypy`).
+
+## Definition of "done" for any change
+
+A change is not complete until **all three** pass:
+
+```
+.venv/Scripts/python.exe -m pytest tests/      # 123 tests, must stay green
+.venv/Scripts/python.exe -m ruff check src tests
+.venv/Scripts/python.exe -m mypy src           # strict; must report no issues
+```
+
+`mypy` runs in **strict** mode and `src` must stay clean. Keep the repo runnable
+after every change.
+
+## Invariants that must never regress
+
+These are enforced by tests (`tests/test_control_mode.py`, `test_engine.py`,
+`test_retry.py`, `test_routing.py`, …) and encode the project's reason for
+existing (brief §36/§43). Do not weaken them:
+
+1. **FIXED values never change.** The optimizer cannot mutate a FIXED knob.
+2. **BOUNDED_ADAPTIVE values never exceed their `[minimum, maximum]`.**
+3. **DISABLED capabilities stay off.**
+4. **One logical request → exactly one terminal outcome.** Attempts and retries
+   are counted separately (1 success after 4 failures = 1 success, 5 attempts,
+   4 retries).
+5. **Non-idempotent requests are not retried** unless explicitly permitted
+   (`RetryPolicy.retry_non_idempotent` or `Request.idempotent=True`).
+6. **Queues, task creation, and memory stay bounded.** Never create a task per
+   request; never retain whole runs or full response bodies by default.
+7. **Secrets never appear in any serialized output** (logs, events, reports,
+   sinks). All such paths go through `redaction.Redactor`.
+8. **Isolated throttle scopes never silently merge**; shared scopes stay shared.
+9. **No import-time networking or logging configuration.**
+10. **Route failures are attributed correctly** — transport/proxy/TLS errors are
+    route-attributable (can quarantine); HTTP-status/application errors are not.
+
+If a task seems to require violating one of these, stop and surface the conflict
+rather than working around it.
+
+## Authorized-use posture
+
+The library supports **authorized** security testing (throttle-scope validation,
+multi-route/IP/credential testing). It must **not** gain offensive capabilities
+unrelated to throughput/throttle testing: no credential theft, exploit delivery,
+CAPTCHA bypass, stealth/evasion, target discovery, or payload generation. Reject
+contributions that add these. See `SECURITY.md` and `docs/legal.md`.
+
+## Known gotchas
+
+- **`ManualClock` inflates reported durations.** In tests using `ManualClock`,
+  concurrent virtual `sleep`s accumulate on the shared clock, so `report.elapsed`
+  and goodput-per-second are artifacts. Assert on *counts* (completed, attempts,
+  outcomes), not wall-clock-derived rates, in clock-driven tests. Engine
+  integration tests use a real `MonotonicClock` with tiny sim latencies instead.
+- **The `CapacityLimiter` is created inside `run()`**, not `__init__`, because it
+  must bind to the running event loop and needs integer `total_tokens`.
+- **anyio's pytest plugin** is enabled via `-p anyio` in `addopts`; async tests
+  need `pytestmark = pytest.mark.anyio` or the `@pytest.mark.anyio` marker plus
+  the `anyio_backend` fixture (defaults to asyncio in `conftest.py`).
+- **Controllers receive a float view** of integer knobs via `Controlled.as_float()`;
+  the engine rounds back when applying. Don't hand a controller a raw int knob.
+
+## Layout
+
+```
+src/goodput/          # the library (see src/goodput/CLAUDE.md)
+  control/            # adaptive controllers (AIMD, gradient) + protocol
+  routing/            # routes, selectors, health, quarantine
+  sinks/              # result sinks (memory, jsonl)
+tests/                # pytest suite (see tests/CLAUDE.md)
+examples/             # runnable usage examples
+docs/                 # concepts, legal, ADRs
+ARCHITECTURE.md       # full design + §41 deliverables
+```
+
+## Commit / PR conventions
+
+- Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`).
+- Update `CHANGELOG.md` under *Unreleased* for user-visible changes.
+- Add/extend tests for behavior changes; keep the three checks green.
+- Only commit or push when explicitly asked. Branch first if on the default branch.

goodput_http-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include showing
+empathy and kindness, respecting differing opinions, giving and gracefully
+accepting constructive feedback, and focusing on what is best for the community.
+
+Unacceptable behavior includes harassment, trolling, insulting or derogatory
+comments, public or private harassment, and publishing others' private
+information without explicit permission.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated promptly and fairly.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1.
+
+[homepage]: https://www.contributor-covenant.org

goodput_http-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to goodput
+
+Thanks for your interest! This project values correctness, bounded operation,
+explainability, and strong typing.
+
+## Development setup
+
+```bash
+python -m venv .venv
+. .venv/Scripts/activate   # Windows;  source .venv/bin/activate on Unix
+pip install -e ".[dev,http2]"
+pytest
+```
+
+## Standards
+
+- **Python ≥ 3.10**, `src/` layout, full type hints, `py.typed`.
+- **Ruff** for lint/format: `ruff check src tests`.
+- **mypy --strict** (or strict Pyright) for typing.
+- **pytest** + **Hypothesis** for tests; use the deterministic `ManualClock` and
+  the `SimTransport` for engine/controller tests — no real network in unit tests.
+- Conventional Commits for messages (`feat:`, `fix:`, `docs:`, `test:`, …).
+
+## Invariants we will not regress
+
+These are enforced by tests and must stay true (see brief §36):
+
+- fixed values never change; bounded values never exceed bounds;
+- disabled capabilities stay disabled;
+- one logical request → one terminal state; attempts counted separately;
+- non-idempotent operations are not retried without explicit permission;
+- queues stay bounded; no permit leaks; secrets never appear in serialized output.
+
+## Out of scope
+
+We do not accept contributions adding offensive capabilities unrelated to
+throughput/throttle validation (see [`SECURITY.md`](SECURITY.md)).
+
+## Pull requests
+
+1. Add/extend tests for your change.
+2. Run `ruff check`, `mypy`, and `pytest` locally.
+3. Update `CHANGELOG.md` under *Unreleased*.
+4. Keep the repository runnable.

goodput_http-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 goodput contributors
+
+   Full text: https://www.apache.org/licenses/LICENSE-2.0.txt