goodput-http 0.1.0__py3-none-any.whl

goodput/classify.py

@@ -0,0 +1,191 @@
+"""Classification of attempts into success / throttle / error (brief §14).
+
+Classification is fully pluggable. The engine runs, in order:
+
+1. a :class:`ThrottleClassifier` (does this attempt evidence throttling?),
+2. a :class:`SuccessClassifier` (is this a logical success?),
+3. an :class:`ErrorClassifier` (if not success, what kind of error, retryable?).
+
+Default implementations cover the common cases (2xx success, 429/Retry-After
+throttle, 5xx retryable). Users supply their own by implementing the protocols
+or passing predicate callbacks to :class:`Classifiers.build`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from .models import Classification, ErrorClass, Outcome, ThrottleSignal
+from .retry_after import parse_rate_limit_headers, parse_retry_after
+
+
+@dataclass
+class ResponseView:
+    """The minimal, transport-agnostic view classifiers operate on.
+
+    Keeping this separate from httpx's ``Response`` lets simulations and tests
+    classify without a real HTTP layer, and keeps body access bounded.
+    """
+
+    status_code: int | None
+    headers: Mapping[str, str]
+    elapsed: float
+    body_preview: bytes = b""
+    error_class: ErrorClass = ErrorClass.NONE
+    error_message: str | None = None
+    now_epoch: float | None = None
+
+
+# A user predicate may be sync or async and returns a bool or a Classification.
+SyncPredicate = Callable[[ResponseView], bool]
+ThrottlePredicate = Callable[[ResponseView], ThrottleSignal | None]
+
+
+class SuccessClassifier(Protocol):
+    def __call__(self, view: ResponseView) -> bool: ...
+
+
+class ThrottleClassifier(Protocol):
+    def __call__(self, view: ResponseView) -> ThrottleSignal | None: ...
+
+
+class ErrorClassifier(Protocol):
+    def __call__(self, view: ResponseView) -> tuple[ErrorClass, bool]:
+        """Return ``(error_class, retryable)``."""
+        ...
+
+
+# -- defaults ------------------------------------------------------------------
+
+
+def default_success(view: ResponseView, *, ok_statuses: range = range(200, 300)) -> bool:
+    return view.status_code is not None and view.status_code in ok_statuses
+
+
+def default_throttle(
+    view: ResponseView,
+    *,
+    throttle_statuses: frozenset[int] = frozenset({429}),
+) -> ThrottleSignal | None:
+    """Detect throttling from status + Retry-After + rate-limit headers."""
+    evidence: list[str] = []
+    throttled = False
+    retry_after: float | None = None
+    reset_at: float | None = None
+
+    if view.status_code in throttle_statuses:
+        throttled = True
+        evidence.append(f"status={view.status_code}")
+
+    ra = parse_retry_after(_get(view.headers, "retry-after"), now_epoch=view.now_epoch)
+    if ra is not None:
+        retry_after = ra
+        evidence.append(f"retry-after={ra:g}s")
+        # Retry-After on a 503 is a strong throttle/overload signal too.
+        if view.status_code == 503:
+            throttled = True
+
+    rl = parse_rate_limit_headers(view.headers, now_epoch=view.now_epoch)
+    if rl is not None and rl.exhausted:
+        throttled = True
+        reset_at = rl.reset_seconds
+        evidence.append(f"ratelimit-remaining=0 ({rl.source})")
+
+    if not throttled:
+        return None
+    return ThrottleSignal(
+        throttled=True,
+        confidence=1.0 if view.status_code in throttle_statuses else 0.7,
+        retry_after=retry_after,
+        reset_at=reset_at,
+        evidence=tuple(evidence),
+    )
+
+
+def default_error(view: ResponseView) -> tuple[ErrorClass, bool]:
+    """Classify a non-success, non-throttle attempt and whether it is retryable."""
+    if view.error_class is not ErrorClass.NONE:
+        # Transport-level error already classified upstream.
+        retryable = view.error_class in {
+            ErrorClass.DNS,
+            ErrorClass.CONNECT,
+            ErrorClass.TLS,
+            ErrorClass.PROXY,
+            ErrorClass.TIMEOUT,
+            ErrorClass.READ,
+        }
+        return view.error_class, retryable
+    sc = view.status_code
+    if sc is None:
+        return ErrorClass.UNKNOWN, True
+    if sc in (401, 403):
+        return ErrorClass.AUTH, False
+    if 500 <= sc < 600:
+        return ErrorClass.HTTP_STATUS, True  # transient server error → retryable
+    if 400 <= sc < 500:
+        return ErrorClass.HTTP_STATUS, False  # client error → not retryable
+    return ErrorClass.HTTP_STATUS, False
+
+
+def _get(headers: Mapping[str, str], key: str) -> str | None:
+    key = key.lower()
+    for k, v in headers.items():
+        if k.lower() == key:
+            return v
+    return None
+
+
+@dataclass
+class Classifiers:
+    """Bundle of the three classifier stages used by the engine."""
+
+    success: SuccessClassifier
+    throttle: ThrottleClassifier
+    error: ErrorClassifier
+
+    @classmethod
+    def default(cls) -> Classifiers:
+        return cls(success=default_success, throttle=default_throttle, error=default_error)
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        ok_statuses: Sequence[int] | None = None,
+        success: SuccessClassifier | None = None,
+        throttle: ThrottleClassifier | None = None,
+        error: ErrorClassifier | None = None,
+    ) -> Classifiers:
+        """Build classifiers from common overrides without writing classes."""
+        succ = success
+        if succ is None and ok_statuses is not None:
+            ok = frozenset(ok_statuses)
+            succ = lambda v: v.status_code is not None and v.status_code in ok  # noqa: E731
+        return cls(
+            success=succ or default_success,
+            throttle=throttle or default_throttle,
+            error=error or default_error,
+        )
+
+    def classify(self, view: ResponseView) -> Classification:
+        """Run all stages and produce a single :class:`Classification`."""
+        throttle = self.throttle(view)
+        if throttle is not None and throttle.throttled:
+            return Classification(
+                outcome=Outcome.THROTTLED,
+                error_class=ErrorClass.THROTTLE,
+                retryable=True,
+                throttle=throttle,
+                reason="throttle classifier matched",
+            )
+        if self.success(view):
+            return Classification(outcome=Outcome.SUCCESS, reason="success classifier matched")
+        error_class, retryable = self.error(view)
+        return Classification(
+            outcome=Outcome.FAILURE,
+            error_class=error_class,
+            retryable=retryable,
+            reason=f"error classifier: {error_class.value} (retryable={retryable})",
+        )

goodput/cli.py

@@ -0,0 +1,178 @@
+"""Command-line interface (brief §33).
+
+Implemented with the standard library ``argparse`` so the CLI works without any
+optional dependency. Commands:
+
+* ``validate`` — validate a config file / inline options and print the dry-run plan.
+* ``run`` — execute a repeated-endpoint or JSONL workload.
+* ``plugins`` — list discovered plugins.
+* ``version`` — print the version.
+
+Secrets are never echoed; the CLI discourages putting secrets on the command
+line (brief §33) and supports machine-readable JSON output and no-color mode.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .api import run as _run
+from .config import EngineConfig, Mode, load_config
+from .control_mode import bounded_adaptive, fixed
+from .models import Request
+from .plugins import PluginRegistry
+from .sources import from_jsonl, repeat
+
+
+def _build_config(args: argparse.Namespace) -> EngineConfig:
+    overrides: dict[str, object] = {}
+    if args.mode:
+        overrides["mode"] = Mode(args.mode)
+    if args.timeout:
+        overrides["default_timeout"] = args.timeout
+    cfg = (
+        load_config(Path(args.config), overrides=overrides)
+        if args.config
+        else EngineConfig(**overrides)
+    )
+    # Concurrency from CLI (explicit override beats file/defaults — brief §34).
+    if args.concurrency is not None:
+        if args.adaptive:
+            cfg.global_concurrency = bounded_adaptive(
+                minimum=1, maximum=args.max_concurrency or args.concurrency * 10,
+                initial=args.concurrency, name="global_concurrency",
+            )
+        else:
+            cfg.global_concurrency = fixed(args.concurrency, name="global_concurrency")
+    if args.rate is not None:
+        cfg.request_rate = fixed(float(args.rate), name="request_rate")
+    return cfg
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    cfg = _build_config(args)
+    plan = cfg.validate_constraints()
+    if args.json:
+        print(json.dumps({
+            "ok": plan.ok,
+            "conflicts": plan.conflicts,
+            "warnings": plan.warnings,
+        }, indent=2))
+    else:
+        print(plan.render())
+    return 0 if plan.ok else 1
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    import anyio
+
+    cfg = _build_config(args)
+    plan = cfg.validate_constraints()
+    if not plan.ok:
+        print("configuration is invalid:", file=sys.stderr)
+        print(plan.render(), file=sys.stderr)
+        return 1
+
+    if args.jsonl:
+        source = from_jsonl(args.jsonl)
+    elif args.url:
+        source = repeat(Request(args.method, args.url), times=args.count)
+    else:
+        print("error: provide --url or --jsonl", file=sys.stderr)
+        return 2
+
+    sinks = None
+    if args.output:
+        from .sinks.jsonl import JSONLSink
+
+        sinks = [JSONLSink(args.output)]
+
+    async def _go():  # type: ignore[no-untyped-def]
+        return await _run(source, config=cfg, sinks=sinks)
+
+    result = anyio.run(_go)
+    if args.json:
+        print(json.dumps(result.report.to_dict(), indent=2))
+    else:
+        print(result.report.summary())
+    return 0
+
+
+def _cmd_plugins(args: argparse.Namespace) -> int:
+    registry = PluginRegistry()
+    found = registry.discover_all()
+    if args.json:
+        print(json.dumps(found, indent=2))
+    else:
+        for group, names in found.items():
+            print(f"{group}:")
+            for name in names:
+                print(f"  - {name}")
+            if not names:
+                print("  (none)")
+    return 0
+
+
+def _cmd_version(args: argparse.Namespace) -> int:
+    print(f"goodput {__version__}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="goodput",
+        description="Adaptive HTTP execution engine that maximizes successful goodput.",
+    )
+    parser.add_argument("--no-color", action="store_true", help="disable ANSI colors")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def add_common(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--config", help="path to a TOML/JSON config file")
+        p.add_argument("--concurrency", type=int, help="global concurrency")
+        p.add_argument("--max-concurrency", type=int, help="upper bound for adaptive concurrency")
+        p.add_argument("--adaptive", action="store_true", help="make concurrency bounded-adaptive")
+        p.add_argument("--rate", type=float, help="fixed request-start rate (req/s)")
+        p.add_argument("--mode", choices=[m.value for m in Mode], help="operating mode")
+        p.add_argument("--timeout", type=float, help="default per-request timeout (s)")
+        p.add_argument("--json", action="store_true", help="machine-readable JSON output")
+
+    p_val = sub.add_parser("validate", help="validate config and print the plan")
+    add_common(p_val)
+    p_val.set_defaults(func=_cmd_validate)
+
+    p_run = sub.add_parser("run", help="execute a workload")
+    add_common(p_run)
+    p_run.add_argument("--url", help="endpoint to call repeatedly")
+    p_run.add_argument("--method", default="GET", help="HTTP method for --url")
+    p_run.add_argument("--count", type=int, default=100, help="number of requests for --url")
+    p_run.add_argument("--jsonl", help="JSONL workload file")
+    p_run.add_argument("--output", help="write per-result JSONL to this path")
+    p_run.set_defaults(func=_cmd_run)
+
+    p_plug = sub.add_parser("plugins", help="list discovered plugins")
+    p_plug.add_argument("--json", action="store_true")
+    p_plug.set_defaults(func=_cmd_plugins)
+
+    p_ver = sub.add_parser("version", help="print version")
+    p_ver.set_defaults(func=_cmd_version)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except KeyboardInterrupt:  # graceful Ctrl+C (brief §33)
+        print("\ninterrupted", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

goodput/clock.py

@@ -0,0 +1,61 @@
+"""Clock abstraction (brief §4: monotonic clocks; §36: deterministic fake clocks).
+
+Durations are always measured with a *monotonic* clock. Tests and controller
+simulations inject a :class:`ManualClock` for determinism — no test ever sleeps
+in wall-clock time.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Protocol
+
+import anyio
+
+
+class Clock(Protocol):
+    """A source of monotonic time and async sleeping."""
+
+    def now(self) -> float:
+        """Monotonic seconds. Only differences are meaningful."""
+        ...
+
+    async def sleep(self, seconds: float) -> None:
+        """Sleep for ``seconds`` (cancellation-safe)."""
+        ...
+
+
+class MonotonicClock:
+    """The production clock: :func:`time.monotonic` + :func:`anyio.sleep`."""
+
+    def now(self) -> float:
+        return time.monotonic()
+
+    async def sleep(self, seconds: float) -> None:
+        if seconds > 0:
+            await anyio.sleep(seconds)
+
+
+class ManualClock:
+    """A deterministic clock for tests and simulations.
+
+    Time advances only when :meth:`advance` is called. ``sleep`` does not block
+    on wall time; it registers a wakeup and yields control so other tasks run.
+    For most unit tests, advancing time explicitly between assertions is enough.
+    """
+
+    def __init__(self, start: float = 0.0) -> None:
+        self._t = start
+
+    def now(self) -> float:
+        return self._t
+
+    def advance(self, seconds: float) -> None:
+        if seconds < 0:
+            raise ValueError("cannot move ManualClock backwards")
+        self._t += seconds
+
+    async def sleep(self, seconds: float) -> None:
+        # Advance virtual time and yield so cooperating tasks make progress.
+        self.advance(max(0.0, seconds))
+        await anyio.lowlevel.checkpoint()