goodput-http 0.1.0

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

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

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

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

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

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.

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 and docs/legal.md.

Documentation

• ARCHITECTURE.md — full architecture & design decisions.
• docs/ — concepts, recipes, configuration reference.
• examples/ — runnable examples.

License

Apache-2.0. See LICENSE.