Metadata-Version: 2.4
Name: goodput-http
Version: 0.1.1
Summary: An adaptive HTTP execution engine that maximizes sustainable successful logical-request goodput.
Project-URL: Homepage, https://github.com/alimoradics/goodput
Project-URL: Documentation, https://github.com/alimoradics/goodput#readme
Project-URL: Source, https://github.com/alimoradics/goodput
Project-URL: Issues, https://github.com/alimoradics/goodput/issues
Project-URL: PyPI, https://pypi.org/project/goodput-http/
Author-email: Ali Moradi <alimoradics@gmail.com>
License:                                  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
License-File: LICENSE
Keywords: adaptive-concurrency,async,goodput,http,load-testing,rate-limiting,throughput
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Testing :: Traffic Generation
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anyio>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.5
Provides-Extra: all
Requires-Dist: httpx[http2,socks]>=0.27; extra == 'all'
Requires-Dist: opentelemetry-api>=1.20; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all'
Requires-Dist: prometheus-client>=0.19; extra == 'all'
Requires-Dist: pyarrow>=14.0; extra == 'all'
Requires-Dist: redis>=5.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: structlog>=24.1; extra == 'all'
Requires-Dist: typer>=0.12; extra == 'all'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.12; extra == 'cli'
Provides-Extra: dev
Requires-Dist: anyio>=4.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: trio>=0.25; extra == 'dev'
Provides-Extra: http2
Requires-Dist: httpx[http2]>=0.27; extra == 'http2'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Provides-Extra: parquet
Requires-Dist: pyarrow>=14.0; extra == 'parquet'
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.19; extra == 'prometheus'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Provides-Extra: socks
Requires-Dist: httpx[socks]>=0.27; extra == 'socks'
Provides-Extra: structlog
Requires-Dist: structlog>=24.1; extra == 'structlog'
Description-Content-Type: text/markdown

# goodput

**An adaptive HTTP execution engine that maximizes sustainable successful
logical-request goodput.**

`goodput` is a production-grade, async-first Python library for executing very
large volumes of HTTP requests while *automatically maximizing the rate of
terminally-successful logical requests* — not raw attempt volume. It is a
reusable library first, with an optional CLI, pluggable policies, route/egress
optimization, and a deterministic adaptive control system.

It is **not** a thin wrapper around `asyncio.gather()`. The core abstractions —
optimizer authority, logical-request-vs-attempt accounting, bounded scheduling,
route intelligence, and explainable adaptive control — are designed for
high-volume API clients, bulk ingestion, sync/migration, webhook delivery,
load/stress/soak testing, capacity discovery, and **authorized** throttling
validation.

> **goodput** = terminally successful *logical* requests completed per unit time.
> One logical request may take several attempts but counts as exactly one
> success or failure.

---

## Install

Published on PyPI as [`goodput-http`](https://pypi.org/project/goodput-http/).
The import package remains `goodput`.

```bash
pip install goodput-http                 # core
pip install "goodput-http[http2]"       # + HTTP/2
pip install "goodput-http[cli]"         # + CLI
pip install "goodput-http[all]"         # everything
```

```python
import goodput
```

Requires Python ≥ 3.10. Core dependencies are minimal: `httpx`, `anyio`,
`pydantic`, `pydantic-settings`. Everything substantial (HTTP/2, SOCKS, Redis,
OpenTelemetry, Prometheus, Parquet, CLI) is an optional extra.

## Quick start

```python
import goodput as gp

result = gp.run_sync(
    gp.repeat(gp.Request("GET", "https://example.com/health"), times=1000),
    config=gp.EngineConfig(
        # The optimizer may tune concurrency within these bounds, and nowhere else.
        global_concurrency=gp.bounded_adaptive(minimum=1, maximum=200, initial=10),
    ),
)
print(result.report.summary())
```

### Async

```python
import goodput as gp

async def main():
    async with gp.Engine(config=gp.EngineConfig()) as engine:
        run = await engine.run(
            gp.repeat(gp.Request("GET", "https://example.com/"), times=10_000)
        )
        print(run.report.summary())
```

## The big idea: optimizer authority

Every tunable knob declares **whether the optimizer may change it** — and the
rule is structural, not advisory. A `FIXED` value can never be mutated.

```python
import goodput as gp

config = gp.EngineConfig(
    # Optimizer owns this, within bounds:
    global_concurrency=gp.bounded_adaptive(minimum=1, maximum=500, initial=20),
    # Optimizer must NEVER change this:
    request_rate=gp.fixed(100.0),
)
```

Control modes (brief §5):

| Mode | Meaning |
|------|---------|
| `fixed(v)` | Exact value; the optimizer must never change it. |
| `adaptive()` | Optimizer fully owns it (within engine safety ceilings). |
| `bounded_adaptive(min, max)` | Optimizer owns it only within `[min, max]`. |
| `disabled()` | Capability must not be used. |
| `inherit()` | Value comes from a broader configuration scope. |

When a fixed value causes throttling or poor performance, the engine **preserves
the fixed value**, adjusts only what it is authorized to change, emits a
constraint event, and reports the issue — it never silently overrides you.

## What it does

- **Goodput-first accounting** — logical requests vs. attempts vs. retries are
  always distinct (brief §1, §18).
- **Adaptive control** — AIMD and latency-gradient concurrency controllers, with
  every decision recorded and explainable (brief §10).
- **Route & egress optimization** — direct routes, source-IP binding, HTTP/SOCKS
  proxies as first-class dimensions; weighted/least-in-flight/goodput-aware
  selection; health tracking, quarantine, and recovery (brief §11, §12, §20).
- **Throttle-scope testing** — `DECLARED / SHARED / ISOLATED_FOR_TEST / INFERRED
  / CUSTOM` scope models for **authorized** validation of whether throttling is
  correctly scoped (brief §13).
- **Bounded everything** — bounded queues, bounded task creation, bounded memory,
  streaming percentile statistics, safe cancellation and cleanup (brief §4, §27).
- **Resilience** — idempotency-aware retries with budgets (no retry storms),
  circuit breakers, Retry-After / RateLimit header parsing (brief §18, §19, §21).
- **Observability** — structured events, secret redaction everywhere, sinks
  (memory / JSONL), and reports that separate every count that matters (brief §23–26).

## Authorized use only

This library supports **authorized** security testing, including testing whether
throttling can be bypassed or is incorrectly scoped. It does **not** grant
permission to test any system.

- You must obtain authorization from the target owner.
- You are responsible for legal, contractual, ethical, and regulatory compliance.
- Unauthorized use may be illegal.
- Use explicit scope, ceilings, monitoring, and emergency-stop procedures.

The library deliberately **excludes** offensive capabilities unrelated to
throughput/throttle testing: credential theft, exploit delivery, CAPTCHA bypass,
stealth/evasion, target discovery, and payload generation. See
[`SECURITY.md`](SECURITY.md) and [`docs/legal.md`](docs/legal.md).

## Documentation

- [`ARCHITECTURE.md`](ARCHITECTURE.md) — full architecture & design decisions.
- [`docs/`](docs/) — concepts, recipes, configuration reference.
- [`examples/`](examples/) — runnable examples.

## License

Apache-2.0. See [`LICENSE`](LICENSE).
