#!/usr/bin/env python3 import argparse import concurrent.futures import datetime import ipaddress import json import math import pathlib import socket import statistics import time import urllib.error import urllib.parse import urllib.request class NoRedirectHandler(urllib.request.HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, headers, newurl): return None def parse_args(): parser = argparse.ArgumentParser(description="Run a bounded HTTP benchmark against a local service.") parser.add_argument("--url", required=True) parser.add_argument("--method", default="GET", choices=("GET", "HEAD", "POST")) parser.add_argument("--requests", type=int, default=100) parser.add_argument("--concurrency", type=int, default=1) parser.add_argument("--timeout", type=float, default=10.0) parser.add_argument("--warmup", type=int, default=0) parser.add_argument("--expected-status", type=int, action="append") parser.add_argument("--body-file") parser.add_argument("--headers-file") parser.add_argument("--output") return parser.parse_args() def validate_target(raw_url): parsed = urllib.parse.urlsplit(raw_url) if parsed.scheme not in {"http", "https"} or not parsed.hostname: raise ValueError("URL must use http or https and include a host.") if parsed.username or parsed.password or parsed.query or parsed.fragment: raise ValueError("Credentials, query strings, and fragments are not allowed in benchmark URLs.") if parsed.hostname == "localhost": return try: addresses = {item[4][0] for item in socket.getaddrinfo(parsed.hostname, parsed.port)} except socket.gaierror as exc: raise ValueError(f"Unable to resolve benchmark host: {parsed.hostname}") from exc for address in addresses: candidate = ipaddress.ip_address(address) if not (candidate.is_loopback or candidate.is_private or candidate.is_link_local): raise ValueError(f"Refusing to benchmark non-local address: {address}") def percentile(values, percentage): if not values: return None ordered = sorted(values) rank = max(1, math.ceil((percentage / 100) * len(ordered))) return round(ordered[rank - 1], 3) def main(): args = parse_args() if not 1 <= args.requests <= 1_000_000: raise SystemExit("--requests must be between 1 and 1000000") if not 1 <= args.concurrency <= 256: raise SystemExit("--concurrency must be between 1 and 256") if args.warmup < 0 or args.timeout <= 0: raise SystemExit("--warmup must be non-negative and --timeout must be positive") validate_target(args.url) body = pathlib.Path(args.body_file).read_bytes() if args.body_file else None headers = {} if args.headers_file: headers = json.loads(pathlib.Path(args.headers_file).read_text(encoding="utf-8")) if not isinstance(headers, dict) or not all(isinstance(key, str) and isinstance(value, str) for key, value in headers.items()): raise SystemExit("--headers-file must contain a JSON object of string values") expected_statuses = set(args.expected_status or range(200, 400)) opener = urllib.request.build_opener( urllib.request.ProxyHandler({}), NoRedirectHandler(), ) def request_once(): request = urllib.request.Request(args.url, data=body, headers=headers, method=args.method) started = time.perf_counter() try: with opener.open(request, timeout=args.timeout) as response: response_body = response.read() retry_after = response.headers.get("Retry-After") return response.status, (time.perf_counter() - started) * 1000, None, response_body, retry_after except urllib.error.HTTPError as exc: response_body = exc.read() retry_after = exc.headers.get("Retry-After") return exc.code, (time.perf_counter() - started) * 1000, None, response_body, retry_after except Exception as exc: return None, (time.perf_counter() - started) * 1000, type(exc).__name__, b"", None for _ in range(args.warmup): request_once() started_at = datetime.datetime.now(datetime.timezone.utc) started = time.perf_counter() with concurrent.futures.ThreadPoolExecutor(max_workers=args.concurrency) as executor: results = list(executor.map(lambda _: request_once(), range(args.requests))) duration_seconds = time.perf_counter() - started latencies = [latency for _, latency, _, _, _ in results] statuses = {} errors = {} response_codes = {} retry_after_values = {} successful = 0 for status, _, error, response_body, retry_after in results: if status is not None: statuses[str(status)] = statuses.get(str(status), 0) + 1 if status in expected_statuses: successful += 1 if error: errors[error] = errors.get(error, 0) + 1 if retry_after: retry_after_values[retry_after] = retry_after_values.get(retry_after, 0) + 1 if response_body: try: parsed_body = json.loads(response_body) except (UnicodeDecodeError, json.JSONDecodeError): parsed_body = None if isinstance(parsed_body, dict) and parsed_body.get("code") is not None: code = str(parsed_body["code"]) response_codes[code] = response_codes.get(code, 0) + 1 report = { "schema_version": 1, "started_at_utc": started_at.isoformat(), "target": args.url, "method": args.method, "requests": args.requests, "concurrency": args.concurrency, "timeout_seconds": args.timeout, "warmup_requests": args.warmup, "body_bytes": len(body or b""), "custom_headers_supplied": bool(headers), "duration_seconds": round(duration_seconds, 6), "requests_per_second": round(args.requests / duration_seconds, 3), "successful_requests": successful, "failed_requests": args.requests - successful, "status_counts": statuses, "transport_error_counts": errors, "application_code_counts": response_codes, "retry_after_counts": retry_after_values, "latency_ms": { "min": round(min(latencies), 3), "mean": round(statistics.fmean(latencies), 3), "p50": percentile(latencies, 50), "p95": percentile(latencies, 95), "p99": percentile(latencies, 99), "max": round(max(latencies), 3), }, } rendered = json.dumps(report, ensure_ascii=False, indent=2) print(rendered) if args.output: output_path = pathlib.Path(args.output) output_path.parent.mkdir(parents=True, exist_ok=True) output_path.write_text(rendered + "\n", encoding="utf-8") if successful != args.requests: raise SystemExit(2) if __name__ == "__main__": main()