rpcbench 0.1.0__py3-none-any.whl

rpcbench/__init__.py

@@ -0,0 +1,3 @@
+"""RPCBench: vendor-neutral RPC quality comparison CLI."""
+
+__version__ = "0.1.0"

rpcbench/__main__.py

@@ -0,0 +1,4 @@
+from rpcbench.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rpcbench/cli.py

@@ -0,0 +1,196 @@
+"""rpcbench CLI."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from rpcbench import __version__
+from rpcbench.config import ConfigError, load_targets
+from rpcbench.methods import MethodError, resolve_method
+from rpcbench.report import format_json, format_run
+from rpcbench.run import run_endpoints
+from rpcbench.safety import SafetyError, check_budget, kill_switch_reason
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="rpcbench",
+        description="Measure RPC quality and compare providers.",
+    )
+    parser.add_argument("--version", action="version", version=f"rpcbench {__version__}")
+    sub = parser.add_subparsers(dest="command")
+    _add_run_parser(
+        sub,
+        "run",
+        "Measure JSON-RPC round-trip latency and print a comparison report",
+    )
+    _add_run_parser(
+        sub,
+        "compare",
+        "Same as run: print a ranked CLI report for configured endpoints",
+    )
+    return parser
+
+
+def _add_run_parser(sub, name: str, help_text: str) -> None:
+    run = sub.add_parser(name, help=help_text)
+    run.add_argument(
+        "--endpoints",
+        required=True,
+        metavar="FILE|URL",
+        help="YAML/JSON file, or a single http(s) URL (localhost is allowed)",
+    )
+    run.add_argument(
+        "--method",
+        default=None,
+        help="JSON-RPC method (default: eth_blockNumber). Do not combine with --preset.",
+    )
+    run.add_argument(
+        "--preset",
+        default=None,
+        metavar="NAME",
+        help="Read-only method pack: head, chainId, or balance",
+    )
+    run.add_argument(
+        "--params",
+        default=None,
+        metavar="JSON",
+        help='JSON array of params, e.g. \'["0x0","latest"]\'',
+    )
+    run.add_argument(
+        "--allow-writes",
+        action="store_true",
+        help="Allow write methods (eth_send*, personal_*, …). Default is read-only.",
+    )
+    run.add_argument(
+        "--samples",
+        type=int,
+        default=10,
+        help="Timed samples per endpoint after warmup (default: 10)",
+    )
+    run.add_argument(
+        "--warmup",
+        type=int,
+        default=1,
+        help="Warmup requests excluded from stats (default: 1)",
+    )
+    run.add_argument(
+        "--timeout",
+        type=float,
+        default=10.0,
+        help="Per-request timeout in seconds (default: 10)",
+    )
+    run.add_argument(
+        "--budget",
+        type=int,
+        default=128,
+        help="Max HTTP requests for the whole run, including warmup (default: 128)",
+    )
+    run.add_argument(
+        "--max-duration",
+        type=float,
+        default=600.0,
+        metavar="SEC",
+        help="Stop the run after this many seconds and still print a report (default: 600; 0 = no limit)",
+    )
+    run.add_argument(
+        "--concurrency",
+        type=int,
+        default=1,
+        help="Max in-flight requests (only 1 is supported)",
+    )
+    run.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Print per-sample latency and error-class detail",
+    )
+    run.add_argument(
+        "--json",
+        action="store_true",
+        help="Print a JSON report to stdout instead of the CLI table",
+    )
+    run.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="Write the JSON report to FILE (CLI table still prints unless --json)",
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 2
+    if args.command in {"run", "compare"}:
+        return _cmd_run(args)
+    parser.print_help()
+    return 2
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    stopped = kill_switch_reason()
+    if stopped:
+        print(f"rpcbench: disabled ({stopped})", file=sys.stderr)
+        return 2
+    try:
+        check_budget(args.budget)
+        config = load_targets(args.endpoints)
+        method, params = resolve_method(
+            method=args.method,
+            preset=args.preset,
+            params_json=args.params,
+            allow_writes=args.allow_writes,
+        )
+    except (ConfigError, MethodError, SafetyError) as exc:
+        print(f"rpcbench: {exc}", file=sys.stderr)
+        return 2
+    if (
+        args.timeout <= 0
+        or args.budget < 1
+        or args.samples < 1
+        or args.warmup < 0
+        or args.max_duration < 0
+    ):
+        print(
+            "rpcbench: --timeout must be > 0, --samples >= 1, "
+            "--warmup >= 0, --budget >= 1, --max-duration >= 0",
+            file=sys.stderr,
+        )
+        return 2
+    if args.concurrency != 1:
+        print("rpcbench: only --concurrency 1 is supported", file=sys.stderr)
+        return 2
+    result = run_endpoints(
+        config,
+        method=method,
+        params=params,
+        samples=args.samples,
+        warmup=args.warmup,
+        timeout=args.timeout,
+        budget=args.budget,
+        max_duration=args.max_duration,
+    )
+    payload = format_json(result) if (args.json or args.output) else None
+    if args.output:
+        path = Path(args.output)
+        try:
+            path.write_text(payload or "", encoding="utf-8")
+        except OSError as exc:
+            print(f"rpcbench: cannot write {path}: {exc}", file=sys.stderr)
+            return 2
+    if args.json:
+        sys.stdout.write(payload or "")
+    else:
+        sys.stdout.write(format_run(result, verbose=args.verbose))
+    if any(outcome.stats.n_ok for outcome in result.outcomes):
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rpcbench/config.py

@@ -0,0 +1,122 @@
+"""Load named RPC endpoints from YAML or JSON. Localhost is allowed."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import yaml
+
+from rpcbench.urls import display_url, url_fingerprint
+
+
+class ConfigError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    name: str
+    url: str
+    headers: tuple[tuple[str, str], ...] = ()
+
+    @property
+    def display_url(self) -> str:
+        return display_url(self.url)
+
+    @property
+    def url_id(self) -> str:
+        return url_fingerprint(self.url)
+
+
+@dataclass(frozen=True)
+class BenchConfig:
+    endpoints: tuple[Endpoint, ...]
+
+
+def load_targets(spec: str | Path) -> BenchConfig:
+    text = str(spec).strip()
+    if text.startswith("http://") or text.startswith("https://"):
+        host = urlsplit(text).hostname or "cli"
+        return parse_endpoints(
+            {"endpoints": [{"name": host, "url": text}]},
+            source="cli",
+        )
+    return load_endpoints(text)
+
+
+def load_endpoints(path: str | Path) -> BenchConfig:
+    raw_path = Path(path)
+    if not raw_path.is_file():
+        raise ConfigError(f"endpoints file not found: {raw_path}")
+    text = raw_path.read_text(encoding="utf-8")
+    suffix = raw_path.suffix.lower()
+    try:
+        if suffix == ".json":
+            data = json.loads(text)
+        else:
+            data = yaml.safe_load(text)
+    except (json.JSONDecodeError, yaml.YAMLError) as exc:
+        raise ConfigError(f"invalid endpoints file {raw_path}: {exc}") from exc
+    return parse_endpoints(data, source=str(raw_path))
+
+
+def parse_endpoints(data: object, *, source: str = "config") -> BenchConfig:
+    if not isinstance(data, dict):
+        raise ConfigError(f"{source}: expected a mapping with an 'endpoints' list")
+    items = data.get("endpoints")
+    if not isinstance(items, list) or not items:
+        raise ConfigError(f"{source}: 'endpoints' must be a non-empty list")
+    seen: set[str] = set()
+    endpoints: list[Endpoint] = []
+    for i, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise ConfigError(f"{source}: endpoints[{i}] must be a mapping")
+        name = item.get("name")
+        url = item.get("url")
+        if not isinstance(name, str) or not name.strip():
+            raise ConfigError(f"{source}: endpoints[{i}].name is required")
+        if not isinstance(url, str) or not url.strip():
+            raise ConfigError(f"{source}: endpoints[{i}].url is required")
+        name = name.strip()
+        url = url.strip()
+        if name in seen:
+            raise ConfigError(f"{source}: duplicate endpoint name {name!r}")
+        scheme = url.split(":", 1)[0].lower()
+        if scheme not in {"http", "https"}:
+            raise ConfigError(
+                f"{source}: endpoints[{i}] ({name}) URL must be http or https"
+            )
+        headers = _parse_headers(item, source=source, index=i, name=name)
+        seen.add(name)
+        endpoints.append(Endpoint(name=name, url=url, headers=headers))
+    return BenchConfig(endpoints=tuple(endpoints))
+
+
+def _parse_headers(
+    item: dict, *, source: str, index: int, name: str
+) -> tuple[tuple[str, str], ...]:
+    headers: list[tuple[str, str]] = []
+    raw = item.get("headers")
+    if raw is not None:
+        if not isinstance(raw, dict):
+            raise ConfigError(
+                f"{source}: endpoints[{index}] ({name}) headers must be a mapping"
+            )
+        for key, value in raw.items():
+            if not isinstance(key, str) or not isinstance(value, str):
+                raise ConfigError(
+                    f"{source}: endpoints[{index}] ({name}) header names and values "
+                    "must be strings"
+                )
+            headers.append((key.strip(), value))
+    bearer = item.get("bearer")
+    if bearer is not None:
+        if not isinstance(bearer, str) or not bearer.strip():
+            raise ConfigError(
+                f"{source}: endpoints[{index}] ({name}) bearer must be a string"
+            )
+        headers.append(("Authorization", f"Bearer {bearer.strip()}"))
+    return tuple(headers)

rpcbench/methods.py

@@ -0,0 +1,76 @@
+"""Read-only JSON-RPC methods used for latency probes."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
+
+# Presets: chain head, identity, and a cheap account read.
+PRESETS: dict[str, tuple[str, list[Any]]] = {
+    "head": ("eth_blockNumber", []),
+    "chainId": ("eth_chainId", []),
+    "balance": ("eth_getBalance", [ZERO_ADDRESS, "latest"]),
+}
+
+_WRITE_PREFIXES = (
+    "eth_send",
+    "eth_sign",
+    "personal_",
+    "miner_",
+    "admin_",
+    "wallet_",
+)
+
+
+class MethodError(ValueError):
+    pass
+
+
+def resolve_method(
+    *,
+    method: str | None,
+    preset: str | None,
+    params_json: str | None,
+    allow_writes: bool = False,
+) -> tuple[str, list[Any]]:
+    if preset and method:
+        raise MethodError("use either --preset or --method, not both")
+    if preset:
+        key = preset.strip().lower()
+        matched = next((name for name in PRESETS if name.lower() == key), None)
+        if matched is None:
+            known = ", ".join(sorted(PRESETS))
+            raise MethodError(f"unknown preset {preset!r} (try {known})")
+        name, params = PRESETS[matched]
+        if params_json:
+            params = parse_params(params_json)
+        if not allow_writes:
+            _reject_writes(name)
+        return name, params
+    name = (method or "eth_blockNumber").strip()
+    if not name:
+        raise MethodError("method is required")
+    if not allow_writes:
+        _reject_writes(name)
+    params = parse_params(params_json) if params_json else []
+    return name, params
+
+
+def parse_params(raw: str) -> list[Any]:
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise MethodError(f"invalid --params JSON: {exc}") from exc
+    if not isinstance(data, list):
+        raise MethodError("--params must be a JSON array")
+    return data
+
+
+def _reject_writes(method: str) -> None:
+    lower = method.lower()
+    if any(lower.startswith(p) for p in _WRITE_PREFIXES):
+        raise MethodError(
+            f"{method} is a write method; pass --allow-writes to run it anyway"
+        )