rpcbench 0.1.0__tar.gz

rpcbench-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ehsan Hajian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rpcbench-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include endpoints.example.yaml
+include endpoints.ci.yaml
+graft tests
+graft docs
+global-exclude endpoints.yaml
+global-exclude endpoints.json
+global-exclude __pycache__
+global-exclude *.py[cod]

rpcbench-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: rpcbench
+Version: 0.1.0
+Summary: Compare EVM JSON-RPC endpoints: latency, percentiles, errors, ranked CLI and JSON.
+Author: Ehsan Hajian
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ehsanhajian/RPCBench
+Project-URL: Repository, https://github.com/ehsanhajian/RPCBench
+Project-URL: Issues, https://github.com/ehsanhajian/RPCBench/issues
+Keywords: rpc,ethereum,json-rpc,benchmark,latency
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Benchmark
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# RPCBench
+
+**Which RPC endpoint is fastest — for this call, from this machine?**
+
+RPCBench 0.1 is a small CLI that compares **EVM JSON-RPC over HTTP**: round-trip latency, P50/P95/P99, error rate, a ranked table, and JSON. Read-only by default. No accounts. No telemetry. Localhost and RFC1918 are allowed (that is how you bench your own node).
+
+It is **not** a security scanner ([Nodeprobe](https://github.com/ehsanhajian/nodeprobe)) and **not** validator monitoring ([ValidatorPulse](https://github.com/ehsanhajian/ValidatorPulse)). How the three tools split: [docs/BOUNDARY.md](https://github.com/ehsanhajian/RPCBench/blob/main/docs/BOUNDARY.md).
+
+The longer product (other families, workload mixes, HTML/TUI, production verdict) lives in the [issue tracker](https://github.com/ehsanhajian/RPCBench/issues). Parent epic: [#19](https://github.com/ehsanhajian/RPCBench/issues/19).
+
+## Install
+
+```bash
+pip install rpcbench
+```
+
+Requires Python 3.10+. `rpcbench --version` prints `0.1.0`.
+
+From a clone (contributors):
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Pull requests and pushes to `main` run `pytest`, then a live smoke: `rpcbench run` against PublicNode and dRPC (`--samples 1 --warmup 0`). There is no local node in CI. The smoke passes if either public endpoint is ok.
+
+## Quick start
+
+```bash
+rpcbench compare --endpoints https://ethereum.publicnode.com --samples 5 --warmup 1
+```
+
+Or a YAML/JSON file of named endpoints (keep API keys in a **local** file; do not commit it):
+
+```yaml
+endpoints:
+  - name: publicnode
+    url: https://ethereum.publicnode.com
+  - name: drpc
+    url: https://eth.drpc.org
+  - name: paid
+    url: https://eth.example/v3/YOUR_KEY
+    bearer: YOUR_TOKEN
+    headers:
+      X-Api-Key: YOUR_KEY
+```
+
+```bash
+rpcbench run --endpoints endpoints.yaml
+rpcbench compare --endpoints endpoints.yaml --json
+rpcbench run --endpoints endpoints.yaml -o report.json
+```
+
+`run` and `compare` are the same command. They print **summary**, **ranking**, **per-provider metrics**, and **method coverage**. Ranking is by **mean of successful samples** (warmup excluded); failed endpoints are last; ties keep config order. On a TTY, ok is green and fail is red (`NO_COLOR` or a pipe disables this). Reports print a redacted URL plus a short hash (`id=`), never API keys, bearer tokens, or header values.
+
+### Flags
+
+```bash
+rpcbench run --endpoints endpoints.yaml --samples 10 --warmup 1 --preset head --timeout 10 --budget 128
+rpcbench compare --endpoints http://127.0.0.1:8545
+rpcbench run --endpoints endpoints.yaml --verbose --json
+```
+
+`--samples` timed requests per endpoint after `--warmup` (defaults: 10 and 1). Warmup is excluded from min/mean/max, percentiles, and error rate. P50/P95/P99 are nearest-rank over successful samples. Error rate is failed/attempted with a class breakdown (timeout, connection, HTTP 4xx/5xx, JSON-RPC, malformed). `--verbose` prints each sample. `--preset` is `head` (`eth_blockNumber`), `chainId`, or `balance` (`eth_getBalance` of the zero address). Or pass `--method` and optional `--params` (JSON array). Write methods are rejected unless `--allow-writes`.
+
+`--json` prints a machine-readable report to stdout instead of the table. `-o FILE` writes that JSON to a file (the table still prints unless you also pass `--json`). Sequential `rps` is `1000 / mean_ms`. Reliability `score` is success rate.
+
+`--budget` is the max HTTP requests for the whole run, including warmup (default 128, hard cap `RPCBENCH_MAX_REQUESTS` default 10000). `--max-duration` stops remaining work after N seconds and still prints the report (default 600; `0` = no limit). `--concurrency` is 1.
+
+Kill switch: set `RPCBENCH_DISABLED=1`, or create `~/.config/rpcbench/DISABLED` (override path with `RPCBENCH_DISABLE_FILE`). RPCBench never prompts for a private key.
+
+## License
+
+[MIT](https://github.com/ehsanhajian/RPCBench/blob/main/LICENSE)

rpcbench-0.1.0/README.md

@@ -0,0 +1,76 @@
+# RPCBench
+
+**Which RPC endpoint is fastest — for this call, from this machine?**
+
+RPCBench 0.1 is a small CLI that compares **EVM JSON-RPC over HTTP**: round-trip latency, P50/P95/P99, error rate, a ranked table, and JSON. Read-only by default. No accounts. No telemetry. Localhost and RFC1918 are allowed (that is how you bench your own node).
+
+It is **not** a security scanner ([Nodeprobe](https://github.com/ehsanhajian/nodeprobe)) and **not** validator monitoring ([ValidatorPulse](https://github.com/ehsanhajian/ValidatorPulse)). How the three tools split: [docs/BOUNDARY.md](https://github.com/ehsanhajian/RPCBench/blob/main/docs/BOUNDARY.md).
+
+The longer product (other families, workload mixes, HTML/TUI, production verdict) lives in the [issue tracker](https://github.com/ehsanhajian/RPCBench/issues). Parent epic: [#19](https://github.com/ehsanhajian/RPCBench/issues/19).
+
+## Install
+
+```bash
+pip install rpcbench
+```
+
+Requires Python 3.10+. `rpcbench --version` prints `0.1.0`.
+
+From a clone (contributors):
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Pull requests and pushes to `main` run `pytest`, then a live smoke: `rpcbench run` against PublicNode and dRPC (`--samples 1 --warmup 0`). There is no local node in CI. The smoke passes if either public endpoint is ok.
+
+## Quick start
+
+```bash
+rpcbench compare --endpoints https://ethereum.publicnode.com --samples 5 --warmup 1
+```
+
+Or a YAML/JSON file of named endpoints (keep API keys in a **local** file; do not commit it):
+
+```yaml
+endpoints:
+  - name: publicnode
+    url: https://ethereum.publicnode.com
+  - name: drpc
+    url: https://eth.drpc.org
+  - name: paid
+    url: https://eth.example/v3/YOUR_KEY
+    bearer: YOUR_TOKEN
+    headers:
+      X-Api-Key: YOUR_KEY
+```
+
+```bash
+rpcbench run --endpoints endpoints.yaml
+rpcbench compare --endpoints endpoints.yaml --json
+rpcbench run --endpoints endpoints.yaml -o report.json
+```
+
+`run` and `compare` are the same command. They print **summary**, **ranking**, **per-provider metrics**, and **method coverage**. Ranking is by **mean of successful samples** (warmup excluded); failed endpoints are last; ties keep config order. On a TTY, ok is green and fail is red (`NO_COLOR` or a pipe disables this). Reports print a redacted URL plus a short hash (`id=`), never API keys, bearer tokens, or header values.
+
+### Flags
+
+```bash
+rpcbench run --endpoints endpoints.yaml --samples 10 --warmup 1 --preset head --timeout 10 --budget 128
+rpcbench compare --endpoints http://127.0.0.1:8545
+rpcbench run --endpoints endpoints.yaml --verbose --json
+```
+
+`--samples` timed requests per endpoint after `--warmup` (defaults: 10 and 1). Warmup is excluded from min/mean/max, percentiles, and error rate. P50/P95/P99 are nearest-rank over successful samples. Error rate is failed/attempted with a class breakdown (timeout, connection, HTTP 4xx/5xx, JSON-RPC, malformed). `--verbose` prints each sample. `--preset` is `head` (`eth_blockNumber`), `chainId`, or `balance` (`eth_getBalance` of the zero address). Or pass `--method` and optional `--params` (JSON array). Write methods are rejected unless `--allow-writes`.
+
+`--json` prints a machine-readable report to stdout instead of the table. `-o FILE` writes that JSON to a file (the table still prints unless you also pass `--json`). Sequential `rps` is `1000 / mean_ms`. Reliability `score` is success rate.
+
+`--budget` is the max HTTP requests for the whole run, including warmup (default 128, hard cap `RPCBENCH_MAX_REQUESTS` default 10000). `--max-duration` stops remaining work after N seconds and still prints the report (default 600; `0` = no limit). `--concurrency` is 1.
+
+Kill switch: set `RPCBENCH_DISABLED=1`, or create `~/.config/rpcbench/DISABLED` (override path with `RPCBENCH_DISABLE_FILE`). RPCBench never prompts for a private key.
+
+## License
+
+[MIT](https://github.com/ehsanhajian/RPCBench/blob/main/LICENSE)

rpcbench-0.1.0/docs/BOUNDARY.md

@@ -0,0 +1,44 @@
+# Boundary: RPCBench vs Nodeprobe vs ValidatorPulse
+
+Three tools, three questions. Do not copy checks across the line.
+
+| Tool | Question | Never does |
+| --- | --- | --- |
+| **[Nodeprobe](https://github.com/ehsanhajian/nodeprobe)** | Is this RPC **safe to expose**? | Latency percentiles, load, ranking providers |
+| **RPCBench** | Which RPC **performs best** for this workload? | Security findings, privileged-namespace probes, TLS/CORS, CVE/client disclosure |
+| **[ValidatorPulse](https://github.com/ehsanhajian/ValidatorPulse)** | Is **my validator** healthy? | Scanning other people’s RPCs; comparing providers |
+
+## Nodeprobe owns (RPCBench must not implement)
+
+- Privileged namespace **presence** as a finding: `admin_*`, `personal_*`, `miner_*`, `engine_*`, `txpool_*`, `clique_*`, `eth_accounts`, Solana `validatorExit` / `setLogFilter`, Cosmos unsafe, NEAR adversarial, Starknet devnet, Substrate key injection
+- TLS, CORS, `Server` header, `rpc_modules` disclosure, outdated-client / CVE recon
+- Security score (0–100), severity (Critical/High/…), escalation (`↳ Next:`)
+- Deep **method inventory as attack surface**
+- Blocking private/localhost targets (Nodeprobe anti-SSRF). RPCBench **must allow localhost** — you bench your own node
+- `--block-providers`, unauthorized-scan warnings as a product feature
+- Kill switch path or rule IDs copied from Nodeprobe
+
+## RPCBench owns (even if a method name appears in both)
+
+- Timed samples: P50/P95/P99, jitter, histograms, RPS, batch, load shapes
+- Fair paired compare, similar-band, body/hash **consistency** (correctness under load, not “exposed API”)
+- Head freshness / lag vs cohort; `latest` vs `safe` vs `finalized` **latency**
+- Archive / historical **read performance** (can this indexer finish, and how slow)
+- WebSocket **subscribe latency** and missed slots — Nodeprobe is HTTP-only
+- Rate limits as **reliability under a budgeted burst**, not “abuse posture”
+- Workload coverage: of the methods **this mix needs**, which ones succeeded and how fast
+- Optional **trace/debug timing** only when the user opts into a tracing/indexer mix — skip if missing, never a vulnerability
+- Client version as a **report label** (interpret Erigon vs Geth results), never a disclosure finding
+- HTML/JSON/Prometheus as **benchmark reports**, not finding cards with severity badges
+
+## Shared primitives (OK if the purpose differs)
+
+Identity calls (`eth_chainId`, `getHealth`, `system_health`) to pick a family and confirm the network. Same JSON-RPC, different question.
+
+## Profile names
+
+Nodeprobe: `--profile Quick|Standard|Deep` = **scan budget / escalation**.
+
+RPCBench: `--budget short|standard|long` = **sample count / duration**. Do not reuse Quick/Standard/Deep.
+
+Workload mixes (`general`, `wallet`, `indexer`, `trading`, `nft`, optional `tracing`) are RPCBench-only.

rpcbench-0.1.0/endpoints.ci.yaml

@@ -0,0 +1,7 @@
+# Public Ethereum RPCs for GitHub Actions smoke. No localhost. No API keys.
+
+endpoints:
+  - name: publicnode
+    url: https://ethereum.publicnode.com
+  - name: drpc
+    url: https://eth.drpc.org

rpcbench-0.1.0/endpoints.example.yaml

@@ -0,0 +1,15 @@
+# Named RPC endpoints. Localhost and RFC1918 are allowed.
+# Copy to endpoints.yaml and edit. JSON with the same shape also works.
+# Secrets in query strings, path tokens, userinfo, bearer, and headers
+# are stripped from reports; a short hash of the raw URL is kept instead.
+
+endpoints:
+  - name: local
+    url: http://127.0.0.1:8545
+  - name: publicnode
+    url: https://ethereum.publicnode.com
+  # - name: paid
+  #   url: https://eth.example/v3/YOUR_KEY
+  #   bearer: YOUR_TOKEN
+  #   headers:
+  #     X-Api-Key: YOUR_KEY

rpcbench-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rpcbench"
+version = "0.1.0"
+description = "Compare EVM JSON-RPC endpoints: latency, percentiles, errors, ranked CLI and JSON."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ehsan Hajian" }]
+keywords = ["rpc", "ethereum", "json-rpc", "benchmark", "latency"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Benchmark",
+]
+dependencies = [
+  "httpx>=0.27",
+  "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+]
+
+[project.scripts]
+rpcbench = "rpcbench.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ehsanhajian/RPCBench"
+Repository = "https://github.com/ehsanhajian/RPCBench"
+Issues = "https://github.com/ehsanhajian/RPCBench/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

rpcbench-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rpcbench-0.1.0/src/rpcbench/__init__.py

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

rpcbench-0.1.0/src/rpcbench/__main__.py

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

rpcbench-0.1.0/src/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-0.1.0/src/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)