bridge-checker 1.0.0__tar.gz

bridge_checker-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

bridge_checker-1.0.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: bridge-checker
+Version: 1.0.0
+Summary: Fast, concurrent OBFS4 Tor bridge reachability checker with a terminal UI
+License: MIT
+Keywords: tor,obfs4,bridges,censorship-circumvention,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=0.60
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# bridge-checker
+
+A fast, concurrent reachability checker for [Tor](https://www.torproject.org/) **OBFS4
+bridges**, with an interactive terminal UI.
+
+Bridges are unlisted Tor relays that help people get online in places where Tor
+is blocked or throttled. Public bridge lists rot quickly — many entries go
+offline — so this tool re-tests a list and tells you which bridges are
+actually up right now.
+
+![status](https://img.shields.io/badge/status-beta-yellow)
+![license](https://img.shields.io/badge/license-MIT-blue)
+
+## What it does
+
+- Parses a plain-text list of `obfs4 ...` bridge lines (from a file or a URL).
+- Opens a raw TCP connection to each `host:port` concurrently (default: 150 at
+  once) and records whether it's reachable and how long it took.
+- Streams results into a live terminal UI, or runs headlessly for scripts/CI.
+- Writes the working (and, optionally, failed) bridges back out to plain
+  bridge-list files you can drop straight into `torrc`.
+
+**Note on what "reachable" means:** this only proves the host is accepting TCP
+connections on that port — it does **not** perform the actual obfs4
+handshake, which requires the real Tor/obfs4proxy stack. A bridge that passes
+this check is very likely a live relay, but a full Tor connection is the only
+true test.
+
+## Install
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+Requires Python 3.10+. Only dependencies are [`textual`](https://github.com/Textualize/textual)
+(the TUI) and [`rich`](https://github.com/Textualize/rich) (headless progress output).
+
+## Usage
+
+### Interactive TUI (default)
+
+```bash
+bridge-checker
+```
+
+With no arguments it fetches a default public bridge list and drops you into
+the TUI. Point it at your own list instead:
+
+```bash
+bridge-checker path/to/bridges.txt
+bridge-checker https://example.com/my-bridges.txt
+```
+
+Keys: `s` start/refresh, `w` save working bridges to disk, `q` quit. You can
+also change the source in the input field and click **Start**.
+
+### Headless / scripting mode
+
+```bash
+bridge-checker bridges.txt --no-tui --output working.txt --failed failed.txt
+```
+
+```
+Loading bridges from bridges.txt …
+Found 214 bridge(s). Checking with concurrency=150, timeout=4.0s …
+
+  ✔ 203.0.113.4:443              212 ms
+  ✘ 203.0.113.9:8443
+  ...
+checking ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 214/214  up 137  down 77   0:00:06
+
+Results
+  Total checked : 214
+  Working       : 137
+  Failed        : 77
+  Time elapsed  : 6.1s (35.1 bridges/s)
+```
+
+### All options
+
+```
+usage: bridge-checker [-h] [--workers CONCURRENCY] [--timeout TIMEOUT]
+                       [--output OUTPUT] [--failed FAILED] [--no-tui] [--quiet]
+                       [--version]
+                       [source]
+
+positional arguments:
+  source                Path to a local bridge list, or a URL to fetch one
+                        from
+
+options:
+  --workers, -w         Number of concurrent connection attempts (default: 150)
+  --timeout, -t         Per-connection timeout in seconds (default: 4.0)
+  --output, -o          Where to write working bridges
+  --failed, -f          Also write failed bridges to this file
+  --no-tui              Run headlessly instead of the interactive TUI
+  --quiet, -q           Headless mode only: summary output only
+```
+
+## Project layout
+
+```
+bridge_checker/
+  models.py     # Bridge / BridgeResult / RunStats dataclasses
+  parser.py     # obfs4 line parsing
+  fetch.py      # load a bridge list from a file or URL
+  checker.py    # async concurrent TCP reachability checks
+  tui.py        # Textual-based interactive UI
+  headless.py   # rich-based non-interactive mode
+  cli.py        # argument parsing / entry point
+tests/
+  test_parser.py
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Releasing
+
+`.github/workflows/publish.yml` builds and publishes the package to PyPI
+whenever a tag matching `v*.*.*` is pushed (e.g. `v1.0.1`), or when run
+manually from the Actions tab. It uses
+[PyPI's trusted publishing](https://docs.pypi.org/trusted-publishers/) via
+OIDC, so no API token/secret is needed — just:
+
+1. Create a `pypi` environment on the PyPI project page and add this
+   repository as a trusted publisher, pointing at the `publish.yml` workflow.
+2. Bump the `version` in `pyproject.toml`.
+3. Push a matching tag: `git tag v1.0.1 && git push origin v1.0.1`.
+
+A separate `.github/workflows/ci.yml` runs the test suite on every push and
+pull request.
+
+## Contributing
+
+Issues and pull requests are welcome. Please keep changes small and covered
+by a test where practical.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bridge_checker-1.0.0/README.md

@@ -0,0 +1,146 @@
+# bridge-checker
+
+A fast, concurrent reachability checker for [Tor](https://www.torproject.org/) **OBFS4
+bridges**, with an interactive terminal UI.
+
+Bridges are unlisted Tor relays that help people get online in places where Tor
+is blocked or throttled. Public bridge lists rot quickly — many entries go
+offline — so this tool re-tests a list and tells you which bridges are
+actually up right now.
+
+![status](https://img.shields.io/badge/status-beta-yellow)
+![license](https://img.shields.io/badge/license-MIT-blue)
+
+## What it does
+
+- Parses a plain-text list of `obfs4 ...` bridge lines (from a file or a URL).
+- Opens a raw TCP connection to each `host:port` concurrently (default: 150 at
+  once) and records whether it's reachable and how long it took.
+- Streams results into a live terminal UI, or runs headlessly for scripts/CI.
+- Writes the working (and, optionally, failed) bridges back out to plain
+  bridge-list files you can drop straight into `torrc`.
+
+**Note on what "reachable" means:** this only proves the host is accepting TCP
+connections on that port — it does **not** perform the actual obfs4
+handshake, which requires the real Tor/obfs4proxy stack. A bridge that passes
+this check is very likely a live relay, but a full Tor connection is the only
+true test.
+
+## Install
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+Requires Python 3.10+. Only dependencies are [`textual`](https://github.com/Textualize/textual)
+(the TUI) and [`rich`](https://github.com/Textualize/rich) (headless progress output).
+
+## Usage
+
+### Interactive TUI (default)
+
+```bash
+bridge-checker
+```
+
+With no arguments it fetches a default public bridge list and drops you into
+the TUI. Point it at your own list instead:
+
+```bash
+bridge-checker path/to/bridges.txt
+bridge-checker https://example.com/my-bridges.txt
+```
+
+Keys: `s` start/refresh, `w` save working bridges to disk, `q` quit. You can
+also change the source in the input field and click **Start**.
+
+### Headless / scripting mode
+
+```bash
+bridge-checker bridges.txt --no-tui --output working.txt --failed failed.txt
+```
+
+```
+Loading bridges from bridges.txt …
+Found 214 bridge(s). Checking with concurrency=150, timeout=4.0s …
+
+  ✔ 203.0.113.4:443              212 ms
+  ✘ 203.0.113.9:8443
+  ...
+checking ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 214/214  up 137  down 77   0:00:06
+
+Results
+  Total checked : 214
+  Working       : 137
+  Failed        : 77
+  Time elapsed  : 6.1s (35.1 bridges/s)
+```
+
+### All options
+
+```
+usage: bridge-checker [-h] [--workers CONCURRENCY] [--timeout TIMEOUT]
+                       [--output OUTPUT] [--failed FAILED] [--no-tui] [--quiet]
+                       [--version]
+                       [source]
+
+positional arguments:
+  source                Path to a local bridge list, or a URL to fetch one
+                        from
+
+options:
+  --workers, -w         Number of concurrent connection attempts (default: 150)
+  --timeout, -t         Per-connection timeout in seconds (default: 4.0)
+  --output, -o          Where to write working bridges
+  --failed, -f          Also write failed bridges to this file
+  --no-tui              Run headlessly instead of the interactive TUI
+  --quiet, -q           Headless mode only: summary output only
+```
+
+## Project layout
+
+```
+bridge_checker/
+  models.py     # Bridge / BridgeResult / RunStats dataclasses
+  parser.py     # obfs4 line parsing
+  fetch.py      # load a bridge list from a file or URL
+  checker.py    # async concurrent TCP reachability checks
+  tui.py        # Textual-based interactive UI
+  headless.py   # rich-based non-interactive mode
+  cli.py        # argument parsing / entry point
+tests/
+  test_parser.py
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Releasing
+
+`.github/workflows/publish.yml` builds and publishes the package to PyPI
+whenever a tag matching `v*.*.*` is pushed (e.g. `v1.0.1`), or when run
+manually from the Actions tab. It uses
+[PyPI's trusted publishing](https://docs.pypi.org/trusted-publishers/) via
+OIDC, so no API token/secret is needed — just:
+
+1. Create a `pypi` environment on the PyPI project page and add this
+   repository as a trusted publisher, pointing at the `publish.yml` workflow.
+2. Bump the `version` in `pyproject.toml`.
+3. Push a matching tag: `git tag v1.0.1 && git push origin v1.0.1`.
+
+A separate `.github/workflows/ci.yml` runs the test suite on every push and
+pull request.
+
+## Contributing
+
+Issues and pull requests are welcome. Please keep changes small and covered
+by a test where practical.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bridge_checker-1.0.0/bridge_checker/__init__.py

@@ -0,0 +1,3 @@
+"""bridge-checker: a fast, concurrent OBFS4 Tor bridge reachability checker."""
+
+__version__ = "1.0.0"

bridge_checker-1.0.0/bridge_checker/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

bridge_checker-1.0.0/bridge_checker/checker.py

@@ -0,0 +1,49 @@
+"""Concurrent reachability checks for bridges.
+
+We only perform a bare TCP handshake to each host:port. That proves the
+relay is online and accepting connections, which is the practical
+definition of "reachable" without pulling in a full obfs4proxy/Tor
+client stack. It does not verify the obfs4 handshake itself.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Sequence
+
+from .models import Bridge, BridgeResult
+
+
+async def check_bridge(bridge: Bridge, timeout: float) -> BridgeResult:
+    start = time.monotonic()
+    try:
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(bridge.host, bridge.port), timeout=timeout
+        )
+        writer.close()
+        try:
+            await writer.wait_closed()
+        except OSError:
+            pass
+        return BridgeResult(bridge=bridge, ok=True, latency=time.monotonic() - start)
+    except (OSError, asyncio.TimeoutError) as exc:
+        return BridgeResult(bridge=bridge, ok=False, latency=time.monotonic() - start, error=str(exc))
+
+
+async def check_all(
+    bridges: Sequence[Bridge],
+    *,
+    timeout: float = 4.0,
+    concurrency: int = 150,
+) -> AsyncIterator[BridgeResult]:
+    """Check every bridge concurrently, yielding results as they complete."""
+    semaphore = asyncio.Semaphore(concurrency)
+
+    async def _bounded(bridge: Bridge) -> BridgeResult:
+        async with semaphore:
+            return await check_bridge(bridge, timeout)
+
+    tasks = [asyncio.create_task(_bounded(b)) for b in bridges]
+    for coro in asyncio.as_completed(tasks):
+        yield await coro

bridge_checker-1.0.0/bridge_checker/cli.py

@@ -0,0 +1,79 @@
+"""Command-line entry point for bridge-checker."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .fetch import DEFAULT_BRIDGES_URL, is_url
+from .headless import run_headless
+from .tui import run_tui
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bridge-checker",
+        description="Fast, concurrent OBFS4 Tor bridge reachability checker.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "source",
+        nargs="?",
+        default=DEFAULT_BRIDGES_URL,
+        help="Path to a local bridge list, or a URL to fetch one from",
+    )
+    parser.add_argument(
+        "--workers", "-w", type=int, default=150, dest="concurrency",
+        help="Number of concurrent connection attempts",
+    )
+    parser.add_argument(
+        "--timeout", "-t", type=float, default=4.0,
+        help="Per-connection timeout in seconds",
+    )
+    parser.add_argument(
+        "--output", "-o", default=None,
+        help="Where to write working bridges (default: <source>_working.txt)",
+    )
+    parser.add_argument(
+        "--failed", "-f", default=None,
+        help="Also write failed bridges to this file",
+    )
+    parser.add_argument(
+        "--no-tui", action="store_true",
+        help="Run headlessly (plain progress output) instead of the interactive TUI",
+    )
+    parser.add_argument(
+        "--quiet", "-q", action="store_true",
+        help="Headless mode only: suppress per-bridge lines, show summary only",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.no_tui:
+        stem = "bridges" if is_url(args.source) else Path(args.source).stem
+        output = Path(args.output) if args.output else Path(f"{stem}_working.txt")
+        failed = Path(args.failed) if args.failed else None
+        return run_headless(
+            args.source,
+            timeout=args.timeout,
+            concurrency=args.concurrency,
+            output=output,
+            failed_output=failed,
+            quiet=args.quiet,
+        )
+
+    output = Path(args.output) if args.output else None
+    run_tui(args.source, timeout=args.timeout, concurrency=args.concurrency, output=output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bridge_checker-1.0.0/bridge_checker/fetch.py

@@ -0,0 +1,37 @@
+"""Loading bridge lists from a local file or a remote URL."""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+#: The community-maintained list this project was originally built around.
+#: Anyone can point the checker at their own list instead.
+DEFAULT_BRIDGES_URL = (
+    "https://raw.githubusercontent.com/scriptzteam/Tor-Bridges-Collector/"
+    "refs/heads/main/bridges-obfs4"
+)
+
+_USER_AGENT = "bridge-checker/1.0 (+https://github.com/)"
+
+
+def is_url(source: str) -> bool:
+    return source.startswith("http://") or source.startswith("https://")
+
+
+def load_text(source: str, timeout: float = 15.0) -> str:
+    """Return the raw text of a bridge list, from a file path or a URL.
+
+    Raises FileNotFoundError / urllib.error.URLError on failure so callers
+    can present a clean error message.
+    """
+    if is_url(source):
+        req = urllib.request.Request(source, headers={"User-Agent": _USER_AGENT})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            return resp.read().decode("utf-8", errors="replace")
+
+    path = Path(source)
+    if not path.exists():
+        raise FileNotFoundError(f"No such file: {path}")
+    return path.read_text(encoding="utf-8", errors="replace")

bridge_checker-1.0.0/bridge_checker/headless.py

@@ -0,0 +1,114 @@
+"""Non-interactive ("headless") checking mode, for scripts and CI.
+
+Prints a live progress bar with `rich` and writes results to disk as
+they come in, instead of dropping into the full Textual TUI.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from pathlib import Path
+
+from rich.console import Console
+from rich.progress import BarColumn, MofNCompleteColumn, Progress, TextColumn, TimeElapsedColumn
+
+from .checker import check_all
+from .fetch import load_text
+from .models import BridgeResult
+from .parser import parse_text
+
+console = Console()
+
+
+def run_headless(
+    source: str,
+    *,
+    timeout: float = 4.0,
+    concurrency: int = 150,
+    output: Path,
+    failed_output: Path | None = None,
+    quiet: bool = False,
+) -> int:
+    """Run a full check synchronously (wraps the async pipeline). Returns exit code."""
+    console.print(f"[bold]Loading bridges from[/bold] {source} …")
+    try:
+        text = load_text(source)
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Error loading bridge list:[/red] {exc}")
+        return 1
+
+    bridges, skipped = parse_text(text)
+    if skipped:
+        console.print(f"[yellow]Skipped {skipped} unrecognised line(s).[/yellow]")
+    if not bridges:
+        console.print("[red]No valid obfs4 bridges found.[/red]")
+        return 1
+
+    total = len(bridges)
+    console.print(
+        f"Found [bold]{total}[/bold] bridge(s). "
+        f"Checking with concurrency={concurrency}, timeout={timeout}s …\n"
+    )
+
+    working: list[BridgeResult] = []
+    failed: list[BridgeResult] = []
+
+    out_fh = output.open("w", encoding="utf-8")
+    fail_fh = failed_output.open("w", encoding="utf-8") if failed_output else None
+
+    progress = Progress(
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TextColumn("[green]up {task.fields[ok]}[/]  [red]down {task.fields[failed]}[/]"),
+        TimeElapsedColumn(),
+        console=console,
+    )
+
+    async def _drive() -> None:
+        task_id = progress.add_task("checking", total=total, ok=0, failed=0)
+        async for result in check_all(bridges, timeout=timeout, concurrency=concurrency):
+            if result.ok:
+                working.append(result)
+                out_fh.write(result.bridge.raw + "\n")
+                out_fh.flush()
+            else:
+                failed.append(result)
+                if fail_fh:
+                    fail_fh.write(result.bridge.raw + "\n")
+                    fail_fh.flush()
+
+            progress.update(task_id, advance=1, ok=len(working), failed=len(failed))
+            if not quiet:
+                if result.ok:
+                    console.print(f"  [green]✔[/] {result.bridge.address:<25} {result.latency_ms:6.0f} ms")
+                else:
+                    console.print(f"  [red]✘[/] {result.bridge.address}")
+
+    t0 = time.monotonic()
+    try:
+        with progress:
+            asyncio.run(_drive())
+    finally:
+        out_fh.close()
+        if fail_fh:
+            fail_fh.close()
+    elapsed = time.monotonic() - t0
+
+    console.print("\n[bold]Results[/bold]")
+    console.print(f"  Total checked : {total}")
+    console.print(f"  [green]Working[/green]       : {len(working)}")
+    console.print(f"  [red]Failed[/red]        : {len(failed)}")
+    rate = total / elapsed if elapsed > 0 else 0.0
+    console.print(f"  Time elapsed  : {elapsed:.1f}s ({rate:.1f} bridges/s)")
+    console.print(f"\n  Working bridges -> [bold]{output}[/bold]")
+    if failed_output:
+        console.print(f"  Failed  bridges -> [bold]{failed_output}[/bold]")
+
+    if working:
+        console.print("\n[bold]Top 10 fastest:[/bold]")
+        for i, result in enumerate(sorted(working, key=lambda r: r.latency)[:10], 1):
+            console.print(f"    {i:>2}. {result.bridge.address:<25} {result.latency_ms:6.0f} ms")
+
+    return 0

bridge_checker-1.0.0/bridge_checker/models.py

@@ -0,0 +1,52 @@
+"""Data models for OBFS4 bridge lines."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class Bridge:
+    """A single parsed `obfs4 ...` bridge line."""
+
+    raw: str
+    host: str
+    port: int
+    fingerprint: str
+    extra: str = ""
+
+    @property
+    def address(self) -> str:
+        return f"{self.host}:{self.port}"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.address
+
+
+@dataclass(slots=True)
+class BridgeResult:
+    """Outcome of testing a single bridge."""
+
+    bridge: Bridge
+    ok: bool
+    latency: float = 0.0
+    error: str = ""
+
+    @property
+    def latency_ms(self) -> float:
+        return self.latency * 1000
+
+
+@dataclass(slots=True)
+class RunStats:
+    """Aggregate stats for a whole checking run."""
+
+    total: int = 0
+    done: int = 0
+    ok: int = 0
+    failed: int = 0
+    started_at: float = field(default=0.0)
+
+    @property
+    def pct(self) -> float:
+        return (self.done / self.total * 100) if self.total else 0.0

bridge_checker-1.0.0/bridge_checker/parser.py

@@ -0,0 +1,58 @@
+"""Parsing of obfs4 bridge lines.
+
+A typical line looks like:
+
+    obfs4 192.0.2.1:443 0123456789ABCDEF0123456789ABCDEF01234567 cert=... iat-mode=0
+
+IPv6 hosts are also supported, e.g. ``obfs4 [2001:db8::1]:443 ...``.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .models import Bridge
+
+_BRIDGE_RE = re.compile(
+    r"^obfs4\s+"
+    r"(\[?[\w:.]+\]?):(\d+)"  # host : port
+    r"\s+([0-9A-Fa-f]{40})"  # 40-hex fingerprint
+    r"(.*)",  # cert= iat-mode= ...
+    re.IGNORECASE,
+)
+
+
+def parse_line(line: str) -> Bridge | None:
+    """Parse a single line, returning ``None`` if it isn't a valid bridge."""
+    line = line.strip()
+    if not line or line.startswith("#"):
+        return None
+
+    match = _BRIDGE_RE.match(line)
+    if not match:
+        return None
+
+    host, port_str, fingerprint, extra = match.groups()
+    host = host.strip("[]")
+
+    try:
+        port = int(port_str)
+    except ValueError:
+        return None
+    if not (1 <= port <= 65535):
+        return None
+
+    return Bridge(raw=line, host=host, port=port, fingerprint=fingerprint, extra=extra.strip())
+
+
+def parse_text(text: str) -> tuple[list[Bridge], int]:
+    """Parse a whole bridge list. Returns ``(bridges, skipped_line_count)``."""
+    bridges: list[Bridge] = []
+    skipped = 0
+    for line in text.splitlines():
+        bridge = parse_line(line)
+        if bridge is not None:
+            bridges.append(bridge)
+        elif line.strip() and not line.strip().startswith("#"):
+            skipped += 1
+    return bridges, skipped

bridge_checker-1.0.0/bridge_checker/tui.py

@@ -0,0 +1,246 @@
+"""Interactive terminal UI for the bridge checker, built with Textual."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.reactive import reactive
+from textual.widgets import (
+    Button,
+    DataTable,
+    Footer,
+    Header,
+    Input,
+    Label,
+    ProgressBar,
+    Static,
+)
+from textual.worker import Worker, WorkerState
+
+from .checker import check_all
+from .fetch import DEFAULT_BRIDGES_URL, load_text
+from .models import Bridge, BridgeResult
+from .parser import parse_text
+
+STATUS_PENDING = "…"
+STATUS_OK = "[green]✔ up[/]"
+STATUS_FAIL = "[red]✘ down[/]"
+
+
+class StatsBar(Static):
+    """One-line summary of the current run."""
+
+    total: reactive[int] = reactive(0)
+    done: reactive[int] = reactive(0)
+    ok: reactive[int] = reactive(0)
+    failed: reactive[int] = reactive(0)
+    elapsed: reactive[float] = reactive(0.0)
+
+    def render(self) -> str:
+        rate = self.done / self.elapsed if self.elapsed > 0 else 0.0
+        return (
+            f"checked [b]{self.done}[/]/{self.total}   "
+            f"[green]up {self.ok}[/]   [red]down {self.failed}[/]   "
+            f"{self.elapsed:.1f}s   {rate:.1f} bridges/s"
+        )
+
+
+class BridgeCheckerApp(App):
+    """A small TUI for testing OBFS4 bridge reachability."""
+
+    CSS = """
+    #controls {
+        height: auto;
+        padding: 1 1 0 1;
+    }
+    #source {
+        width: 1fr;
+        margin-right: 1;
+    }
+    #controls Button {
+        margin-right: 1;
+    }
+    #progress {
+        padding: 0 1;
+        height: auto;
+    }
+    StatsBar {
+        padding: 0 1 1 1;
+        color: $text-muted;
+    }
+    DataTable {
+        height: 1fr;
+    }
+    """
+
+    BINDINGS = [
+        Binding("s", "start", "Start / Refresh"),
+        Binding("w", "save", "Save working list"),
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(
+        self,
+        source: str = DEFAULT_BRIDGES_URL,
+        *,
+        timeout: float = 4.0,
+        concurrency: int = 150,
+        output: Path | None = None,
+    ) -> None:
+        super().__init__()
+        self._source = source
+        self._timeout = timeout
+        self._concurrency = concurrency
+        self._output = output
+        self._bridges: list[Bridge] = []
+        self._results: dict[str, BridgeResult] = {}
+        self._row_keys: dict[str, object] = {}
+        self._worker: Worker | None = None
+        self._status_col = None
+        self._latency_col = None
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        with Vertical():
+            with Horizontal(id="controls"):
+                yield Input(value=self._source, placeholder="Bridge file path or URL", id="source")
+                yield Button("Start", id="start", variant="primary")
+                yield Button("Save working", id="save")
+            with Horizontal(id="progress"):
+                yield ProgressBar(id="bar", show_eta=False)
+            yield StatsBar()
+            yield DataTable(id="table", zebra_stripes=True)
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.title = "OBFS4 Bridge Checker"
+        self.sub_title = "press s to start"
+        table = self.query_one("#table", DataTable)
+        cols = table.add_columns("Address", "Fingerprint", "Status", "Latency")
+        self._status_col, self._latency_col = cols[2], cols[3]
+
+    # -- actions ---------------------------------------------------------
+
+    def action_start(self) -> None:
+        self._run_check()
+
+    def action_save(self) -> None:
+        self._save_working()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "start":
+            self._run_check()
+        elif event.button.id == "save":
+            self._save_working()
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        self._run_check()
+
+    # -- core logic --------------------------------------------------------
+
+    def _run_check(self) -> None:
+        if self._worker is not None and self._worker.state == WorkerState.RUNNING:
+            self.notify("A check is already running.", severity="warning")
+            return
+
+        source = self.query_one("#source", Input).value.strip() or self._source
+        self._source = source
+        self._worker = self._load_and_check(source)
+
+    @work(exclusive=True, thread=False)
+    async def _load_and_check(self, source: str) -> None:
+        table = self.query_one("#table", DataTable)
+        stats = self.query_one(StatsBar)
+        bar = self.query_one("#bar", ProgressBar)
+
+        table.clear()
+        self._results.clear()
+        self._row_keys.clear()
+        self.sub_title = f"loading {source} …"
+
+        try:
+            text = await self.run_worker_io(source)
+        except Exception as exc:  # noqa: BLE001
+            self.notify(f"Failed to load bridge list: {exc}", severity="error", timeout=8)
+            self.sub_title = "load failed"
+            return
+
+        bridges, skipped = parse_text(text)
+        self._bridges = bridges
+        if not bridges:
+            self.notify("No valid obfs4 bridges found in that source.", severity="error")
+            self.sub_title = "no bridges found"
+            return
+        if skipped:
+            self.notify(f"Skipped {skipped} unrecognised line(s).", severity="warning")
+
+        for bridge in bridges:
+            key = table.add_row(bridge.address, bridge.fingerprint[:12] + "…", STATUS_PENDING, "")
+            self._row_keys[bridge.fingerprint] = key
+
+        total = len(bridges)
+        bar.total = total
+        bar.progress = 0
+        stats.total = total
+        stats.done = 0
+        stats.ok = 0
+        stats.failed = 0
+        stats.elapsed = 0.0
+        self.sub_title = f"checking {total} bridge(s) …"
+
+        start = time.monotonic()
+        async for result in check_all(bridges, timeout=self._timeout, concurrency=self._concurrency):
+            self._results[result.bridge.fingerprint] = result
+            row_key = self._row_keys[result.bridge.fingerprint]
+            status = STATUS_OK if result.ok else STATUS_FAIL
+            latency = f"{result.latency_ms:.0f} ms" if result.ok else "-"
+            table.update_cell(row_key, self._status_col, status)
+            table.update_cell(row_key, self._latency_col, latency)
+
+            stats.done += 1
+            stats.ok += 1 if result.ok else 0
+            stats.failed += 0 if result.ok else 1
+            stats.elapsed = time.monotonic() - start
+            bar.progress = stats.done
+
+        self.sub_title = (
+            f"done — {stats.ok} up / {stats.failed} down "
+            f"({stats.elapsed:.1f}s). press w to save, s to re-run."
+        )
+
+    async def run_worker_io(self, source: str) -> str:
+        """Load bridge-list text off the event loop's thread pool."""
+        import asyncio
+
+        return await asyncio.get_running_loop().run_in_executor(None, load_text, source)
+
+    def _save_working(self) -> None:
+        working = [r.bridge.raw for r in self._results.values() if r.ok]
+        if not working:
+            self.notify("No working bridges to save yet.", severity="warning")
+            return
+
+        if self._output is not None:
+            out_path = self._output
+        else:
+            base = Path(self._source).stem if not self._source.startswith("http") else "bridges"
+            out_path = Path(f"{base}_working.txt")
+
+        out_path.write_text("\n".join(working) + "\n", encoding="utf-8")
+        self.notify(f"Saved {len(working)} working bridge(s) to {out_path}")
+
+
+def run_tui(
+    source: str = DEFAULT_BRIDGES_URL,
+    *,
+    timeout: float = 4.0,
+    concurrency: int = 150,
+    output: Path | None = None,
+) -> None:
+    app = BridgeCheckerApp(source, timeout=timeout, concurrency=concurrency, output=output)
+    app.run()

bridge_checker-1.0.0/bridge_checker.egg-info/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: bridge-checker
+Version: 1.0.0
+Summary: Fast, concurrent OBFS4 Tor bridge reachability checker with a terminal UI
+License: MIT
+Keywords: tor,obfs4,bridges,censorship-circumvention,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=0.60
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# bridge-checker
+
+A fast, concurrent reachability checker for [Tor](https://www.torproject.org/) **OBFS4
+bridges**, with an interactive terminal UI.
+
+Bridges are unlisted Tor relays that help people get online in places where Tor
+is blocked or throttled. Public bridge lists rot quickly — many entries go
+offline — so this tool re-tests a list and tells you which bridges are
+actually up right now.
+
+![status](https://img.shields.io/badge/status-beta-yellow)
+![license](https://img.shields.io/badge/license-MIT-blue)
+
+## What it does
+
+- Parses a plain-text list of `obfs4 ...` bridge lines (from a file or a URL).
+- Opens a raw TCP connection to each `host:port` concurrently (default: 150 at
+  once) and records whether it's reachable and how long it took.
+- Streams results into a live terminal UI, or runs headlessly for scripts/CI.
+- Writes the working (and, optionally, failed) bridges back out to plain
+  bridge-list files you can drop straight into `torrc`.
+
+**Note on what "reachable" means:** this only proves the host is accepting TCP
+connections on that port — it does **not** perform the actual obfs4
+handshake, which requires the real Tor/obfs4proxy stack. A bridge that passes
+this check is very likely a live relay, but a full Tor connection is the only
+true test.
+
+## Install
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+Requires Python 3.10+. Only dependencies are [`textual`](https://github.com/Textualize/textual)
+(the TUI) and [`rich`](https://github.com/Textualize/rich) (headless progress output).
+
+## Usage
+
+### Interactive TUI (default)
+
+```bash
+bridge-checker
+```
+
+With no arguments it fetches a default public bridge list and drops you into
+the TUI. Point it at your own list instead:
+
+```bash
+bridge-checker path/to/bridges.txt
+bridge-checker https://example.com/my-bridges.txt
+```
+
+Keys: `s` start/refresh, `w` save working bridges to disk, `q` quit. You can
+also change the source in the input field and click **Start**.
+
+### Headless / scripting mode
+
+```bash
+bridge-checker bridges.txt --no-tui --output working.txt --failed failed.txt
+```
+
+```
+Loading bridges from bridges.txt …
+Found 214 bridge(s). Checking with concurrency=150, timeout=4.0s …
+
+  ✔ 203.0.113.4:443              212 ms
+  ✘ 203.0.113.9:8443
+  ...
+checking ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 214/214  up 137  down 77   0:00:06
+
+Results
+  Total checked : 214
+  Working       : 137
+  Failed        : 77
+  Time elapsed  : 6.1s (35.1 bridges/s)
+```
+
+### All options
+
+```
+usage: bridge-checker [-h] [--workers CONCURRENCY] [--timeout TIMEOUT]
+                       [--output OUTPUT] [--failed FAILED] [--no-tui] [--quiet]
+                       [--version]
+                       [source]
+
+positional arguments:
+  source                Path to a local bridge list, or a URL to fetch one
+                        from
+
+options:
+  --workers, -w         Number of concurrent connection attempts (default: 150)
+  --timeout, -t         Per-connection timeout in seconds (default: 4.0)
+  --output, -o          Where to write working bridges
+  --failed, -f          Also write failed bridges to this file
+  --no-tui              Run headlessly instead of the interactive TUI
+  --quiet, -q           Headless mode only: summary output only
+```
+
+## Project layout
+
+```
+bridge_checker/
+  models.py     # Bridge / BridgeResult / RunStats dataclasses
+  parser.py     # obfs4 line parsing
+  fetch.py      # load a bridge list from a file or URL
+  checker.py    # async concurrent TCP reachability checks
+  tui.py        # Textual-based interactive UI
+  headless.py   # rich-based non-interactive mode
+  cli.py        # argument parsing / entry point
+tests/
+  test_parser.py
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Releasing
+
+`.github/workflows/publish.yml` builds and publishes the package to PyPI
+whenever a tag matching `v*.*.*` is pushed (e.g. `v1.0.1`), or when run
+manually from the Actions tab. It uses
+[PyPI's trusted publishing](https://docs.pypi.org/trusted-publishers/) via
+OIDC, so no API token/secret is needed — just:
+
+1. Create a `pypi` environment on the PyPI project page and add this
+   repository as a trusted publisher, pointing at the `publish.yml` workflow.
+2. Bump the `version` in `pyproject.toml`.
+3. Push a matching tag: `git tag v1.0.1 && git push origin v1.0.1`.
+
+A separate `.github/workflows/ci.yml` runs the test suite on every push and
+pull request.
+
+## Contributing
+
+Issues and pull requests are welcome. Please keep changes small and covered
+by a test where practical.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bridge_checker-1.0.0/bridge_checker.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+bridge_checker/__init__.py
+bridge_checker/__main__.py
+bridge_checker/checker.py
+bridge_checker/cli.py
+bridge_checker/fetch.py
+bridge_checker/headless.py
+bridge_checker/models.py
+bridge_checker/parser.py
+bridge_checker/tui.py
+bridge_checker.egg-info/PKG-INFO
+bridge_checker.egg-info/SOURCES.txt
+bridge_checker.egg-info/dependency_links.txt
+bridge_checker.egg-info/entry_points.txt
+bridge_checker.egg-info/requires.txt
+bridge_checker.egg-info/top_level.txt
+tests/test_parser.py

bridge_checker-1.0.0/bridge_checker.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bridge_checker-1.0.0/bridge_checker.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bridge-checker = bridge_checker.cli:main

bridge_checker-1.0.0/bridge_checker.egg-info/requires.txt

@@ -0,0 +1,6 @@
+textual>=0.60
+rich>=13.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.23

bridge_checker-1.0.0/bridge_checker.egg-info/top_level.txt

@@ -0,0 +1 @@
+bridge_checker

bridge_checker-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bridge-checker"
+version = "1.0.0"
+description = "Fast, concurrent OBFS4 Tor bridge reachability checker with a terminal UI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["tor", "obfs4", "bridges", "censorship-circumvention", "tui"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet",
+    "Topic :: Security",
+]
+dependencies = [
+    "textual>=0.60",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+bridge-checker = "bridge_checker.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["bridge_checker*"]

bridge_checker-1.0.0/setup.cfg

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

bridge_checker-1.0.0/tests/test_parser.py

@@ -0,0 +1,52 @@
+from bridge_checker.parser import parse_line, parse_text
+
+FP = "0123456789ABCDEF0123456789ABCDEF01234567"
+
+
+def test_parse_valid_ipv4_line():
+    line = f"obfs4 192.0.2.1:443 {FP} cert=abc123 iat-mode=0"
+    bridge = parse_line(line)
+    assert bridge is not None
+    assert bridge.host == "192.0.2.1"
+    assert bridge.port == 443
+    assert bridge.fingerprint == FP
+    assert bridge.address == "192.0.2.1:443"
+
+
+def test_parse_valid_ipv6_line():
+    line = f"obfs4 [2001:db8::1]:443 {FP} cert=abc123"
+    bridge = parse_line(line)
+    assert bridge is not None
+    assert bridge.host == "2001:db8::1"
+    assert bridge.port == 443
+
+
+def test_parse_rejects_comments_and_blank_lines():
+    assert parse_line("") is None
+    assert parse_line("   ") is None
+    assert parse_line("# a comment") is None
+
+
+def test_parse_rejects_bad_port():
+    line = f"obfs4 192.0.2.1:999999 {FP} cert=abc123"
+    assert parse_line(line) is None
+
+
+def test_parse_rejects_short_fingerprint():
+    line = "obfs4 192.0.2.1:443 deadbeef cert=abc123"
+    assert parse_line(line) is None
+
+
+def test_parse_text_counts_skipped_lines():
+    text = "\n".join(
+        [
+            f"obfs4 192.0.2.1:443 {FP} cert=abc123",
+            "not a bridge line",
+            "# comment",
+            "",
+            f"obfs4 192.0.2.2:8443 {FP} cert=def456",
+        ]
+    )
+    bridges, skipped = parse_text(text)
+    assert len(bridges) == 2
+    assert skipped == 1