one-hop 0.1.0__tar.gz

one_hop-0.1.0/LICENSE

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

one_hop-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: one-hop
+Version: 0.1.0
+Summary: Check a redirect map: every old URL must reach its new URL in exactly one hop, and the new URL must answer 200.
+Author: Synapse Research Ltd
+License-Expression: MIT
+Project-URL: Homepage, https://synapsereality.io/open-source/one-hop/
+Project-URL: Documentation, https://synapsereality.io/open-source/one-hop/
+Project-URL: Repository, https://github.com/synapsereality/one-hop
+Project-URL: Issues, https://github.com/synapsereality/one-hop/issues
+Keywords: redirects,301,seo,site-migration,ci
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management :: Link Checking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# one-hop
+
+Checks a redirect map. Every old URL has to answer with one permanent redirect
+(301 or 308) straight to its new URL. The new URL has to answer 200. Anything else
+fails: a chain, a loop, a 404, a redirect to the wrong page. The exit code is then
+1, so CI can stop the release.
+
+Docs: https://synapsereality.io/open-source/one-hop/
+
+```bash
+pip install one-hop
+one-hop redirects.csv --base https://example.com
+```
+
+## Why one hop
+
+A chain such as `/about-us` to `/about` to `/about/` still loads in a browser, so
+nobody spots it. Crawlers do. Google follows up to 10 hops and then gives up, and
+every extra hop is one more request per URL. After a migration the map is often
+right on paper and wrong on the server. One trailing-slash rule or a leftover
+redirect plugin adds a second hop to hundreds of rules at once.
+
+We wrote the first version for our own site move in September 2026, 2,030 rules
+from a WordPress site to a static build. This is that script, made general.
+
+## The CSV
+
+Two columns, old URL then new URL. A header row is optional. With one, the columns
+can be named `old`/`new`, `source`/`destination` or `from`/`to`, and extra columns
+are ignored.
+
+```csv
+old,new
+/blog/old-post,/blog/new-post/
+/about-us,/about/
+/services,https://example.com/services/seo/
+/pricing,
+```
+
+Leave the new URL empty (as for `/pricing` above) when the page should answer 200
+with no redirect at all. Relative URLs are resolved against `--base`. Lines that
+start with `#` are skipped.
+
+## Output
+
+Against a local test server with five rules:
+
+```text
+$ one-hop redirects.csv --base https://example.com
+checking 5 rules against https://example.com
+1/5 OK
+  loop: 1
+  not_found: 2
+  chain: 1
+FAIL [loop] line 5: /team  redirect loop: 301 https://example.com/team -> 301 https://example.com/people/ -> /team
+FAIL [not_found] line 4: /services  new URL returned 404
+FAIL [not_found] line 6: /pricing  old URL returned 404, no redirect
+FAIL [chain] line 3: /about-us  reaches the new URL after 2 redirects: 301 https://example.com/about-us -> 301 https://example.com/about -> 200 https://example.com/about/
+```
+
+| kind | what happened |
+|---|---|
+| `chain` | more than one redirect before a final answer |
+| `loop` | a redirect came back to a URL already visited |
+| `not_found` | the old or the new URL answered 404 or 410 |
+| `wrong_target` | the redirect points somewhere other than the new URL in the map |
+| `no_redirect` | the old URL answered 200 when a redirect was expected |
+| `temporary` | a 302, 303 or 307 where a permanent redirect was expected |
+| `redirected` | a row with no new URL redirected instead of answering 200 |
+| `bad_status` | anything else: a 5xx, a redirect with no `Location` header |
+| `error` | the request failed (DNS, TLS, timeout, refused) |
+
+`--json report.json` writes every result with each hop's URL, status and
+`Location`. `--json -` prints it to stdout instead.
+
+## Options
+
+| flag | default | |
+|---|---|---|
+| `--base URL` | required | the site to test |
+| `--workers N` | 8 | parallel requests |
+| `--timeout S` | 20 | seconds per request |
+| `--max-hops N` | 10 | stop following a chain after N hops |
+| `--limit N` | all | check only the first N rules |
+| `--auth user:pass` | none | basic auth for a staging host. `ONE_HOP_AUTH` works too |
+| `--header 'Name: value'` | none | extra header, repeatable |
+| `--method GET` | HEAD | HEAD falls back to GET on a 405 or 501 anyway |
+| `--allow-temporary` | off | accept 302, 303 and 307 as the one hop |
+| `--path-only` | off | compare path and query only, ignore scheme and host |
+| `--insecure` | off | skip TLS certificate checks (self-signed staging) |
+
+Credentials from `--auth` and `--header` go to the `--base` host only. If a
+redirect points at another host, that request is sent without them.
+
+Trailing slashes count. `/about` and `/about/` are two URLs, and a map that says
+`/about/` when the server redirects to `/about` fails as `wrong_target`.
+
+## GitHub Actions
+
+```yaml
+- uses: actions/checkout@v4
+- uses: synapsereality/one-hop@v0.1.0
+  with:
+    csv: redirects.csv
+    base: https://staging.example.com
+    auth: ${{ secrets.STAGING_AUTH }}
+    args: --workers 4
+```
+
+The action needs `python3` on the runner, which GitHub's hosted runners have. It
+installs nothing.
+
+## Install from source
+
+```bash
+git clone https://github.com/synapsereality/one-hop
+cd one-hop
+pip install .
+```
+
+Python 3.10 or later, no dependencies. `python -m one_hop` works without
+installing if `src` is on `PYTHONPATH`.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The tests start a local HTTP server and cover every result kind, the HEAD to GET
+fallback, and credentials staying on the base host.
+
+## Licence
+
+MIT. Made by [Synapse](https://synapsereality.io/open-source/one-hop/).

one_hop-0.1.0/README.md

@@ -0,0 +1,136 @@
+# one-hop
+
+Checks a redirect map. Every old URL has to answer with one permanent redirect
+(301 or 308) straight to its new URL. The new URL has to answer 200. Anything else
+fails: a chain, a loop, a 404, a redirect to the wrong page. The exit code is then
+1, so CI can stop the release.
+
+Docs: https://synapsereality.io/open-source/one-hop/
+
+```bash
+pip install one-hop
+one-hop redirects.csv --base https://example.com
+```
+
+## Why one hop
+
+A chain such as `/about-us` to `/about` to `/about/` still loads in a browser, so
+nobody spots it. Crawlers do. Google follows up to 10 hops and then gives up, and
+every extra hop is one more request per URL. After a migration the map is often
+right on paper and wrong on the server. One trailing-slash rule or a leftover
+redirect plugin adds a second hop to hundreds of rules at once.
+
+We wrote the first version for our own site move in September 2026, 2,030 rules
+from a WordPress site to a static build. This is that script, made general.
+
+## The CSV
+
+Two columns, old URL then new URL. A header row is optional. With one, the columns
+can be named `old`/`new`, `source`/`destination` or `from`/`to`, and extra columns
+are ignored.
+
+```csv
+old,new
+/blog/old-post,/blog/new-post/
+/about-us,/about/
+/services,https://example.com/services/seo/
+/pricing,
+```
+
+Leave the new URL empty (as for `/pricing` above) when the page should answer 200
+with no redirect at all. Relative URLs are resolved against `--base`. Lines that
+start with `#` are skipped.
+
+## Output
+
+Against a local test server with five rules:
+
+```text
+$ one-hop redirects.csv --base https://example.com
+checking 5 rules against https://example.com
+1/5 OK
+  loop: 1
+  not_found: 2
+  chain: 1
+FAIL [loop] line 5: /team  redirect loop: 301 https://example.com/team -> 301 https://example.com/people/ -> /team
+FAIL [not_found] line 4: /services  new URL returned 404
+FAIL [not_found] line 6: /pricing  old URL returned 404, no redirect
+FAIL [chain] line 3: /about-us  reaches the new URL after 2 redirects: 301 https://example.com/about-us -> 301 https://example.com/about -> 200 https://example.com/about/
+```
+
+| kind | what happened |
+|---|---|
+| `chain` | more than one redirect before a final answer |
+| `loop` | a redirect came back to a URL already visited |
+| `not_found` | the old or the new URL answered 404 or 410 |
+| `wrong_target` | the redirect points somewhere other than the new URL in the map |
+| `no_redirect` | the old URL answered 200 when a redirect was expected |
+| `temporary` | a 302, 303 or 307 where a permanent redirect was expected |
+| `redirected` | a row with no new URL redirected instead of answering 200 |
+| `bad_status` | anything else: a 5xx, a redirect with no `Location` header |
+| `error` | the request failed (DNS, TLS, timeout, refused) |
+
+`--json report.json` writes every result with each hop's URL, status and
+`Location`. `--json -` prints it to stdout instead.
+
+## Options
+
+| flag | default | |
+|---|---|---|
+| `--base URL` | required | the site to test |
+| `--workers N` | 8 | parallel requests |
+| `--timeout S` | 20 | seconds per request |
+| `--max-hops N` | 10 | stop following a chain after N hops |
+| `--limit N` | all | check only the first N rules |
+| `--auth user:pass` | none | basic auth for a staging host. `ONE_HOP_AUTH` works too |
+| `--header 'Name: value'` | none | extra header, repeatable |
+| `--method GET` | HEAD | HEAD falls back to GET on a 405 or 501 anyway |
+| `--allow-temporary` | off | accept 302, 303 and 307 as the one hop |
+| `--path-only` | off | compare path and query only, ignore scheme and host |
+| `--insecure` | off | skip TLS certificate checks (self-signed staging) |
+
+Credentials from `--auth` and `--header` go to the `--base` host only. If a
+redirect points at another host, that request is sent without them.
+
+Trailing slashes count. `/about` and `/about/` are two URLs, and a map that says
+`/about/` when the server redirects to `/about` fails as `wrong_target`.
+
+## GitHub Actions
+
+```yaml
+- uses: actions/checkout@v4
+- uses: synapsereality/one-hop@v0.1.0
+  with:
+    csv: redirects.csv
+    base: https://staging.example.com
+    auth: ${{ secrets.STAGING_AUTH }}
+    args: --workers 4
+```
+
+The action needs `python3` on the runner, which GitHub's hosted runners have. It
+installs nothing.
+
+## Install from source
+
+```bash
+git clone https://github.com/synapsereality/one-hop
+cd one-hop
+pip install .
+```
+
+Python 3.10 or later, no dependencies. `python -m one_hop` works without
+installing if `src` is on `PYTHONPATH`.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The tests start a local HTTP server and cover every result kind, the HEAD to GET
+fallback, and credentials staying on the base host.
+
+## Licence
+
+MIT. Made by [Synapse](https://synapsereality.io/open-source/one-hop/).

one_hop-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "one-hop"
+version = "0.1.0"
+description = "Check a redirect map: every old URL must reach its new URL in exactly one hop, and the new URL must answer 200."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Synapse Research Ltd" }]
+keywords = ["redirects", "301", "seo", "site-migration", "ci"]
+classifiers = [
+  "Environment :: Console",
+  "Programming Language :: Python :: 3",
+  "Topic :: Internet :: WWW/HTTP :: Site Management :: Link Checking",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://synapsereality.io/open-source/one-hop/"
+Documentation = "https://synapsereality.io/open-source/one-hop/"
+Repository = "https://github.com/synapsereality/one-hop"
+Issues = "https://github.com/synapsereality/one-hop/issues"
+
+[project.scripts]
+one-hop = "one_hop.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"

one_hop-0.1.0/setup.cfg

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

one_hop-0.1.0/src/one_hop/__init__.py

@@ -0,0 +1,6 @@
+"""one-hop: check that every old URL redirects to its new URL in exactly one hop."""
+
+from .core import Checker, Hop, Result, Rule, normalise, read_rules
+
+__version__ = "0.1.0"
+__all__ = ["Checker", "Hop", "Result", "Rule", "__version__", "normalise", "read_rules"]

one_hop-0.1.0/src/one_hop/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

one_hop-0.1.0/src/one_hop/cli.py

@@ -0,0 +1,117 @@
+"""Command line entry point. Exit 0 when every rule passes, 1 when any fails, 2 on bad input."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import sys
+from collections import Counter
+from pathlib import Path
+
+from . import __version__
+from .core import KINDS, Checker, read_rules
+
+EPILOG = """\
+examples:
+  one-hop redirects.csv --base https://example.com
+  one-hop redirects.csv --base https://staging.example.com --auth user:pass
+  one-hop redirects.csv --base https://example.com --json report.json
+
+The CSV has two columns, old URL then new URL. Leave the new URL empty for a
+page that must answer 200 with no redirect. Docs:
+https://synapsereality.io/open-source/one-hop/
+"""
+
+
+def _parse_header(raw: str) -> tuple[str, str]:
+    name, sep, value = raw.partition(":")
+    if not sep or not name.strip():
+        raise argparse.ArgumentTypeError(f"expected 'Name: value', got {raw!r}")
+    return name.strip(), value.strip()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="one-hop",
+        description="Check that every old URL redirects to its new URL in one hop, and the new URL answers 200.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    ap.add_argument("csv", nargs="+", help="redirect map(s): old,new per line; '-' reads stdin")
+    ap.add_argument("--base", required=True, help="site to test, e.g. https://example.com")
+    ap.add_argument("--workers", type=int, default=8, help="parallel requests (default 8)")
+    ap.add_argument("--timeout", type=float, default=20.0, help="seconds per request (default 20)")
+    ap.add_argument("--max-hops", type=int, default=10, help="stop following a chain after this many hops")
+    ap.add_argument("--limit", type=int, default=0, help="check only the first N rules")
+    ap.add_argument("--auth", help="user:password for HTTP basic auth, sent to the base host only "
+                    "(or set ONE_HOP_AUTH, which keeps it out of the process list)")
+    ap.add_argument("--header", action="append", type=_parse_header, default=[],
+                    help="extra request header 'Name: value' (base host only; repeatable)")
+    ap.add_argument("--method", choices=("HEAD", "GET"), default="HEAD",
+                    help="HEAD by default; falls back to GET on a 405 or 501")
+    ap.add_argument("--allow-temporary", action="store_true", help="accept 302, 303 and 307 as the one hop")
+    ap.add_argument("--path-only", action="store_true",
+                    help="compare only path and query of the target, not scheme and host")
+    ap.add_argument("--insecure", action="store_true", help="do not verify TLS certificates")
+    ap.add_argument("--json", metavar="FILE", help="write every result as JSON ('-' for stdout)")
+    ap.add_argument("--show", type=int, default=50, help="print at most N failures (default 50)")
+    ap.add_argument("--version", action="version", version=f"one-hop {__version__}")
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    rules = []
+    try:
+        for src in args.csv:
+            text = sys.stdin.read() if src == "-" else Path(src).read_text(encoding="utf-8-sig")
+            rules += read_rules(text)
+    except (OSError, ValueError) as e:
+        print(f"one-hop: {e}", file=sys.stderr)
+        return 2
+    if args.limit:
+        rules = rules[: args.limit]
+    if not rules:
+        print("one-hop: no rules found in the input", file=sys.stderr)
+        return 2
+
+    headers = dict(args.header)
+    auth = args.auth or os.environ.get("ONE_HOP_AUTH")
+    if auth:
+        headers["Authorization"] = "Basic " + base64.b64encode(auth.encode()).decode()
+    try:
+        checker = Checker(args.base, headers=headers, timeout=args.timeout, max_hops=args.max_hops,
+                          allow_temporary=args.allow_temporary, path_only=args.path_only,
+                          method=args.method, insecure=args.insecure)
+    except ValueError as e:
+        print(f"one-hop: {e}", file=sys.stderr)
+        return 2
+
+    quiet = args.json == "-"
+    log = sys.stderr if quiet else sys.stdout
+    print(f"checking {len(rules)} rules against {args.base}", file=log)
+    results = checker.check_all(rules, workers=args.workers)
+    bad = [r for r in results if not r.ok]
+    bad.sort(key=lambda r: (KINDS.index(r.kind), r.rule.line))
+
+    counts = Counter(r.kind for r in results)
+    print(f"{len(results) - len(bad)}/{len(results)} OK", file=log)
+    for kind in KINDS:
+        if kind != "ok" and counts[kind]:
+            print(f"  {kind}: {counts[kind]}", file=log)
+    for r in bad[: args.show]:
+        where = f"line {r.rule.line}: " if r.rule.line else ""
+        print(f"FAIL [{r.kind}] {where}{r.rule.old}  {r.detail}", file=log)
+    if len(bad) > args.show:
+        print(f"... and {len(bad) - args.show} more (use --json for all)", file=log)
+
+    if args.json:
+        payload = json.dumps({"base": args.base, "total": len(results), "failed": len(bad),
+                              "results": [r.as_dict() for r in results]}, indent=2)
+        if quiet:
+            print(payload)
+        else:
+            Path(args.json).write_text(payload + "\n", encoding="utf-8")
+    return 1 if bad else 0

one_hop-0.1.0/src/one_hop/core.py

@@ -0,0 +1,261 @@
+"""Check that every old URL reaches its new URL in exactly one redirect.
+
+A migration map is only right when each old URL answers with one permanent
+redirect straight to its new URL, and that new URL answers 200 itself. A chain
+(old -> /tmp -> new) still "works" in a browser, so nobody notices it, but each
+extra hop costs crawl budget and can drop signals. This module follows every
+hop by hand and says exactly which rule broke and how.
+"""
+
+from __future__ import annotations
+
+import csv
+import http.client
+import io
+import ssl
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from urllib.parse import urljoin, urlsplit, urlunsplit
+
+__all__ = ["Checker", "Hop", "Result", "Rule", "normalise", "read_rules"]
+
+USER_AGENT = "one-hop/0.1 (+https://synapsereality.io/open-source/one-hop/)"
+PERMANENT = (301, 308)
+TEMPORARY = (302, 303, 307)
+GONE = (404, 410)
+
+# Result kinds, in the order a report lists them.
+OK = "ok"
+KINDS = ("error", "loop", "not_found", "no_redirect", "temporary", "wrong_target",
+         "chain", "bad_status", "redirected", OK)
+
+
+@dataclass(frozen=True)
+class Rule:
+    old: str
+    new: str  # "" means "this URL must answer 200 itself, with no redirect"
+    line: int = 0
+
+
+@dataclass(frozen=True)
+class Hop:
+    url: str
+    status: int
+    location: str | None = None
+
+
+@dataclass
+class Result:
+    rule: Rule
+    kind: str
+    detail: str
+    hops: list[Hop] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return self.kind == OK
+
+    def as_dict(self) -> dict:
+        return {
+            "old": self.rule.old,
+            "new": self.rule.new,
+            "line": self.rule.line,
+            "ok": self.ok,
+            "kind": self.kind,
+            "detail": self.detail,
+            "hops": [{"url": h.url, "status": h.status, "location": h.location} for h in self.hops],
+        }
+
+
+_OLD_NAMES = ("old", "source", "from", "old_url", "source_url")
+_NEW_NAMES = ("new", "destination", "to", "target", "new_url", "destination_url")
+
+
+def read_rules(text: str) -> list[Rule]:
+    """Parse a redirect map. Two columns, old then new.
+
+    A header row is optional. When there is one, the columns can be called
+    old/new, source/destination or from/to, in any order, and other columns are
+    ignored. Blank lines and lines starting with `#` are skipped.
+    """
+    rows = [
+        (i, r) for i, r in enumerate(csv.reader(io.StringIO(text)), start=1)
+        if r and any(c.strip() for c in r) and not r[0].lstrip().startswith("#")
+    ]
+    if not rows:
+        return []
+    old_i, new_i = 0, 1
+    head = [c.strip().lower() for c in rows[0][1]]
+    if any(h in _OLD_NAMES for h in head):
+        old_i = next(i for i, h in enumerate(head) if h in _OLD_NAMES)
+        new_i = next((i for i, h in enumerate(head) if h in _NEW_NAMES), None)
+        if new_i is None:
+            raise ValueError("the header names an old-URL column but no new-URL column")
+        rows = rows[1:]
+    rules = []
+    for line, r in rows:
+        old = r[old_i].strip() if len(r) > old_i else ""
+        new = r[new_i].strip() if len(r) > new_i else ""
+        if not old:
+            raise ValueError(f"line {line}: no old URL")
+        rules.append(Rule(old=old, new=new, line=line))
+    return rules
+
+
+def normalise(url: str) -> str:
+    """One spelling per URL: lower-case scheme and host, no default port, `/` for an empty path.
+
+    The path, query and trailing slash are kept as they are, because the server
+    treats `/a` and `/a/` as two URLs and a redirect between them is a real hop.
+    """
+    p = urlsplit(url)
+    scheme = p.scheme.lower()
+    host = (p.hostname or "").lower()
+    port = p.port
+    if port and not ((scheme == "http" and port == 80) or (scheme == "https" and port == 443)):
+        host = f"{host}:{port}"
+    return urlunsplit((scheme, host, p.path or "/", p.query, ""))
+
+
+def _origin(url: str) -> str:
+    p = urlsplit(normalise(url))
+    return f"{p.scheme}://{p.netloc}"
+
+
+class Checker:
+    """Checks rules against one site. Thread-safe: every request opens its own connection."""
+
+    def __init__(
+        self,
+        base: str,
+        *,
+        headers: dict[str, str] | None = None,
+        timeout: float = 20.0,
+        max_hops: int = 10,
+        allow_temporary: bool = False,
+        path_only: bool = False,
+        method: str = "HEAD",
+        insecure: bool = False,
+    ) -> None:
+        if not urlsplit(base).scheme or not urlsplit(base).netloc:
+            raise ValueError(f"base must be an absolute URL such as https://example.com, got {base!r}")
+        self.base = base
+        self.origin = _origin(base)
+        self.headers = dict(headers or {})
+        self.timeout = timeout
+        self.max_hops = max_hops
+        self.allow_temporary = allow_temporary
+        self.path_only = path_only
+        self.method = method.upper()
+        self._ssl = ssl._create_unverified_context() if insecure else ssl.create_default_context()
+
+    # ------------------------------------------------------------------ http ---
+    def request(self, url: str, method: str | None = None) -> Hop:
+        """One request. Redirects are never followed here: every hop has to be seen."""
+        method = (method or self.method).upper()
+        p = urlsplit(url)
+        if p.scheme == "https":
+            conn = http.client.HTTPSConnection(p.hostname, p.port, timeout=self.timeout, context=self._ssl)
+        elif p.scheme == "http":
+            conn = http.client.HTTPConnection(p.hostname, p.port, timeout=self.timeout)
+        else:
+            raise ValueError(f"unsupported URL scheme in {url!r}")
+        path = (p.path or "/") + (f"?{p.query}" if p.query else "")
+        headers = {"User-Agent": USER_AGENT, "Accept": "*/*"}
+        # Extra headers usually carry credentials for a staging host. They go to
+        # that host only, never to a host a redirect points at.
+        if _origin(url) == self.origin:
+            headers.update(self.headers)
+        try:
+            conn.request(method, path, headers=headers)
+            r = conn.getresponse()
+            status, location = r.status, r.getheader("Location")
+        finally:
+            conn.close()
+        # Some servers refuse HEAD. Ask again with GET rather than report their 405.
+        if method == "HEAD" and status in (405, 501):
+            return self.request(url, "GET")
+        return Hop(url=url, status=status, location=location)
+
+    def follow(self, start: str) -> tuple[list[Hop], str]:
+        """Follow redirects by hand from `start`. Returns the hops and an end state:
+        "final" (a non-redirect answer), "loop", "too_many" or "no_location"."""
+        hops: list[Hop] = []
+        seen: set[str] = set()
+        url = start
+        while True:
+            key = normalise(url)
+            if key in seen:
+                return hops, "loop"
+            seen.add(key)
+            if len(hops) > self.max_hops:
+                return hops, "too_many"
+            hop = self.request(url)
+            hops.append(hop)
+            if not (300 <= hop.status < 400):
+                return hops, "final"
+            if not hop.location:
+                return hops, "no_location"
+            url = urljoin(url, hop.location)
+
+    # ----------------------------------------------------------------- check ---
+    def _same_target(self, got: str, want: str) -> bool:
+        if self.path_only:
+            g, w = urlsplit(normalise(got)), urlsplit(normalise(want))
+            return (g.path, g.query) == (w.path, w.query)
+        return normalise(got) == normalise(want)
+
+    def check(self, rule: Rule) -> Result:
+        src = urljoin(self.base, rule.old)
+        want = urljoin(self.base, rule.new) if rule.new else ""
+        if want and normalise(want) == normalise(src):
+            want = ""
+        try:
+            hops, end = self.follow(src)
+        except Exception as e:  # noqa: BLE001 - any network failure is a result, not a crash
+            return Result(rule, "error", f"request failed: {type(e).__name__}: {e}")
+        first, last = hops[0], hops[-1]
+        chain = " -> ".join(f"{h.status} {h.url}" for h in hops)
+
+        if end == "loop":
+            return Result(rule, "loop", f"redirect loop: {chain} -> {hops[-1].location}", hops)
+        if end == "too_many":
+            return Result(rule, "chain", f"more than {self.max_hops} redirects: {chain}", hops)
+        if end == "no_location":
+            return Result(rule, "bad_status", f"{last.status} with no Location header at {last.url}", hops)
+
+        if not want:
+            if first.status == 200:
+                return Result(rule, OK, "200", hops)
+            if first.status in GONE:
+                return Result(rule, "not_found", f"expected 200, got {first.status}", hops)
+            if 300 <= first.status < 400:
+                return Result(rule, "redirected", f"expected 200 with no redirect: {chain}", hops)
+            return Result(rule, "bad_status", f"expected 200, got {first.status}", hops)
+
+        if first.status in GONE:
+            return Result(rule, "not_found", f"old URL returned {first.status}, no redirect", hops)
+        if first.status == 200:
+            return Result(rule, "no_redirect", "old URL returned 200, no redirect", hops)
+        if first.status in TEMPORARY and not self.allow_temporary:
+            return Result(rule, "temporary", f"{first.status} is a temporary redirect, want 301 or 308", hops)
+        if first.status not in PERMANENT + TEMPORARY:
+            return Result(rule, "bad_status", f"expected 301 or 308, got {first.status}", hops)
+
+        target = urljoin(first.url, first.location or "")
+        if not self._same_target(target, want):
+            if len(hops) > 2 and self._same_target(last.url, want):
+                return Result(rule, "chain", f"reaches the new URL after {len(hops) - 1} redirects: {chain}",
+                              hops)
+            return Result(rule, "wrong_target", f"redirects to {target}, want {want} ({chain})", hops)
+        if len(hops) > 2:
+            return Result(rule, "chain", f"{len(hops) - 1} redirects before a final answer: {chain}", hops)
+        if last.status in GONE:
+            return Result(rule, "not_found", f"new URL returned {last.status}", hops)
+        if last.status != 200:
+            return Result(rule, "bad_status", f"new URL returned {last.status}", hops)
+        return Result(rule, OK, f"{first.status} -> 200", hops)
+
+    def check_all(self, rules: list[Rule], workers: int = 8) -> list[Result]:
+        with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+            return list(pool.map(self.check, rules))

one_hop-0.1.0/src/one_hop.egg-info/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: one-hop
+Version: 0.1.0
+Summary: Check a redirect map: every old URL must reach its new URL in exactly one hop, and the new URL must answer 200.
+Author: Synapse Research Ltd
+License-Expression: MIT
+Project-URL: Homepage, https://synapsereality.io/open-source/one-hop/
+Project-URL: Documentation, https://synapsereality.io/open-source/one-hop/
+Project-URL: Repository, https://github.com/synapsereality/one-hop
+Project-URL: Issues, https://github.com/synapsereality/one-hop/issues
+Keywords: redirects,301,seo,site-migration,ci
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management :: Link Checking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# one-hop
+
+Checks a redirect map. Every old URL has to answer with one permanent redirect
+(301 or 308) straight to its new URL. The new URL has to answer 200. Anything else
+fails: a chain, a loop, a 404, a redirect to the wrong page. The exit code is then
+1, so CI can stop the release.
+
+Docs: https://synapsereality.io/open-source/one-hop/
+
+```bash
+pip install one-hop
+one-hop redirects.csv --base https://example.com
+```
+
+## Why one hop
+
+A chain such as `/about-us` to `/about` to `/about/` still loads in a browser, so
+nobody spots it. Crawlers do. Google follows up to 10 hops and then gives up, and
+every extra hop is one more request per URL. After a migration the map is often
+right on paper and wrong on the server. One trailing-slash rule or a leftover
+redirect plugin adds a second hop to hundreds of rules at once.
+
+We wrote the first version for our own site move in September 2026, 2,030 rules
+from a WordPress site to a static build. This is that script, made general.
+
+## The CSV
+
+Two columns, old URL then new URL. A header row is optional. With one, the columns
+can be named `old`/`new`, `source`/`destination` or `from`/`to`, and extra columns
+are ignored.
+
+```csv
+old,new
+/blog/old-post,/blog/new-post/
+/about-us,/about/
+/services,https://example.com/services/seo/
+/pricing,
+```
+
+Leave the new URL empty (as for `/pricing` above) when the page should answer 200
+with no redirect at all. Relative URLs are resolved against `--base`. Lines that
+start with `#` are skipped.
+
+## Output
+
+Against a local test server with five rules:
+
+```text
+$ one-hop redirects.csv --base https://example.com
+checking 5 rules against https://example.com
+1/5 OK
+  loop: 1
+  not_found: 2
+  chain: 1
+FAIL [loop] line 5: /team  redirect loop: 301 https://example.com/team -> 301 https://example.com/people/ -> /team
+FAIL [not_found] line 4: /services  new URL returned 404
+FAIL [not_found] line 6: /pricing  old URL returned 404, no redirect
+FAIL [chain] line 3: /about-us  reaches the new URL after 2 redirects: 301 https://example.com/about-us -> 301 https://example.com/about -> 200 https://example.com/about/
+```
+
+| kind | what happened |
+|---|---|
+| `chain` | more than one redirect before a final answer |
+| `loop` | a redirect came back to a URL already visited |
+| `not_found` | the old or the new URL answered 404 or 410 |
+| `wrong_target` | the redirect points somewhere other than the new URL in the map |
+| `no_redirect` | the old URL answered 200 when a redirect was expected |
+| `temporary` | a 302, 303 or 307 where a permanent redirect was expected |
+| `redirected` | a row with no new URL redirected instead of answering 200 |
+| `bad_status` | anything else: a 5xx, a redirect with no `Location` header |
+| `error` | the request failed (DNS, TLS, timeout, refused) |
+
+`--json report.json` writes every result with each hop's URL, status and
+`Location`. `--json -` prints it to stdout instead.
+
+## Options
+
+| flag | default | |
+|---|---|---|
+| `--base URL` | required | the site to test |
+| `--workers N` | 8 | parallel requests |
+| `--timeout S` | 20 | seconds per request |
+| `--max-hops N` | 10 | stop following a chain after N hops |
+| `--limit N` | all | check only the first N rules |
+| `--auth user:pass` | none | basic auth for a staging host. `ONE_HOP_AUTH` works too |
+| `--header 'Name: value'` | none | extra header, repeatable |
+| `--method GET` | HEAD | HEAD falls back to GET on a 405 or 501 anyway |
+| `--allow-temporary` | off | accept 302, 303 and 307 as the one hop |
+| `--path-only` | off | compare path and query only, ignore scheme and host |
+| `--insecure` | off | skip TLS certificate checks (self-signed staging) |
+
+Credentials from `--auth` and `--header` go to the `--base` host only. If a
+redirect points at another host, that request is sent without them.
+
+Trailing slashes count. `/about` and `/about/` are two URLs, and a map that says
+`/about/` when the server redirects to `/about` fails as `wrong_target`.
+
+## GitHub Actions
+
+```yaml
+- uses: actions/checkout@v4
+- uses: synapsereality/one-hop@v0.1.0
+  with:
+    csv: redirects.csv
+    base: https://staging.example.com
+    auth: ${{ secrets.STAGING_AUTH }}
+    args: --workers 4
+```
+
+The action needs `python3` on the runner, which GitHub's hosted runners have. It
+installs nothing.
+
+## Install from source
+
+```bash
+git clone https://github.com/synapsereality/one-hop
+cd one-hop
+pip install .
+```
+
+Python 3.10 or later, no dependencies. `python -m one_hop` works without
+installing if `src` is on `PYTHONPATH`.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The tests start a local HTTP server and cover every result kind, the HEAD to GET
+fallback, and credentials staying on the base host.
+
+## Licence
+
+MIT. Made by [Synapse](https://synapsereality.io/open-source/one-hop/).

one_hop-0.1.0/src/one_hop.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/one_hop/__init__.py
+src/one_hop/__main__.py
+src/one_hop/cli.py
+src/one_hop/core.py
+src/one_hop.egg-info/PKG-INFO
+src/one_hop.egg-info/SOURCES.txt
+src/one_hop.egg-info/dependency_links.txt
+src/one_hop.egg-info/entry_points.txt
+src/one_hop.egg-info/requires.txt
+src/one_hop.egg-info/top_level.txt
+tests/test_core.py

one_hop-0.1.0/src/one_hop.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

one_hop-0.1.0/src/one_hop.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+one-hop = one_hop.cli:main

one_hop-0.1.0/src/one_hop.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=8

one_hop-0.1.0/src/one_hop.egg-info/top_level.txt

@@ -0,0 +1 @@
+one_hop

one_hop-0.1.0/tests/test_core.py

@@ -0,0 +1,172 @@
+import json
+
+import pytest
+
+from one_hop import Checker, Rule, normalise, read_rules
+from one_hop.cli import main
+
+
+def kind(site, old, new, **kw):
+    return Checker(site.url, **kw).check(Rule(old, new))
+
+
+def test_one_hop_to_a_200_passes(site):
+    site.routes = {"/old": (301, "/new"), "/new": (200, None)}
+    r = kind(site, "/old", "/new")
+    assert r.ok and r.detail == "301 -> 200"
+
+
+def test_308_and_absolute_location_pass(site):
+    site.routes = {"/old": (308, f"{site.url}/new"), "/new": (200, None)}
+    assert kind(site, "/old", "/new").ok
+
+
+def test_chain_is_reported_with_every_hop(site):
+    site.routes = {"/old": (301, "/new"), "/new": (301, "/new/"), "/new/": (200, None)}
+    r = kind(site, "/old", "/new")
+    assert r.kind == "chain"
+    assert [h.status for h in r.hops] == [301, 301, 200]
+
+
+def test_loop_is_detected(site):
+    site.routes = {"/a": (301, "/b"), "/b": (301, "/a")}
+    r = kind(site, "/a", "/b")
+    assert r.kind == "loop"
+
+
+def test_self_redirect_is_a_loop(site):
+    site.routes = {"/a": (301, "/a")}
+    assert kind(site, "/a", "/b").kind == "loop"
+
+
+def test_missing_old_url_is_not_found(site):
+    assert kind(site, "/gone", "/new").kind == "not_found"
+
+
+def test_destination_404_is_not_found(site):
+    site.routes = {"/old": (301, "/new")}
+    r = kind(site, "/old", "/new")
+    assert r.kind == "not_found" and "new URL" in r.detail
+
+
+def test_wrong_target(site):
+    site.routes = {"/old": (301, "/elsewhere"), "/elsewhere": (200, None)}
+    assert kind(site, "/old", "/new").kind == "wrong_target"
+
+
+def test_trailing_slash_matters(site):
+    site.routes = {"/old": (301, "/new/"), "/new/": (200, None)}
+    assert kind(site, "/old", "/new").kind == "wrong_target"
+
+
+def test_temporary_redirect_fails_unless_allowed(site):
+    site.routes = {"/old": (302, "/new"), "/new": (200, None)}
+    assert kind(site, "/old", "/new").kind == "temporary"
+    assert kind(site, "/old", "/new", allow_temporary=True).ok
+
+
+def test_old_url_answering_200_is_no_redirect(site):
+    site.routes = {"/old": (200, None)}
+    assert kind(site, "/old", "/new").kind == "no_redirect"
+
+
+def test_keep_rule_wants_a_plain_200(site):
+    site.routes = {"/keep": (200, None), "/moved": (301, "/x"), "/x": (200, None)}
+    assert kind(site, "/keep", "").ok
+    assert kind(site, "/moved", "").kind == "redirected"
+    assert kind(site, "/keep", "/keep").ok  # new == old means keep
+
+
+def test_redirect_without_location(site):
+    site.routes = {"/old": (301, None)}
+    assert kind(site, "/old", "/new").kind == "bad_status"
+
+
+def test_server_error(site):
+    site.routes = {"/old": (500, None)}
+    assert kind(site, "/old", "/new").kind == "bad_status"
+
+
+def test_too_many_hops_is_a_chain(site):
+    site.routes = {f"/{i}": (301, f"/{i + 1}") for i in range(20)}
+    r = kind(site, "/0", "/1", max_hops=5)
+    assert r.kind == "chain" and "more than 5" in r.detail
+
+
+def test_connection_refused_is_an_error():
+    r = Checker("http://127.0.0.1:9").check(Rule("/old", "/new"))
+    assert r.kind == "error"
+
+
+def test_head_refused_falls_back_to_get(site):
+    site.refuse_head = True
+    site.routes = {"/old": (301, "/new"), "/new": (200, None)}
+    assert kind(site, "/old", "/new").ok
+    assert {m for m, _, _ in site.seen} == {"HEAD", "GET"}
+
+
+def test_query_is_part_of_the_url(site):
+    site.routes = {"/old?id=1": (301, "/new?id=1"), "/new?id=1": (200, None)}
+    assert kind(site, "/old?id=1", "/new?id=1").ok
+    assert kind(site, "/old?id=1", "/new?id=2").kind == "wrong_target"
+
+
+def test_cross_host_redirect_and_credentials_stay_home(site, other_site):
+    site.routes = {"/old": (301, f"{other_site.url}/new")}
+    other_site.routes = {"/new": (200, None)}
+    r = Checker(site.url, headers={"Authorization": "Basic c2VjcmV0"}).check(
+        Rule("/old", f"{other_site.url}/new"))
+    assert r.ok
+    assert site.seen[0][2].get("Authorization") == "Basic c2VjcmV0"
+    assert "Authorization" not in other_site.seen[0][2]
+
+
+def test_path_only_ignores_host(site, other_site):
+    site.routes = {"/old": (301, f"{other_site.url}/new")}
+    other_site.routes = {"/new": (200, None)}
+    assert kind(site, "/old", "/new").kind == "wrong_target"
+    assert kind(site, "/old", "/new", path_only=True).ok
+
+
+def test_normalise():
+    assert normalise("HTTPS://Example.com:443") == "https://example.com/"
+    assert normalise("http://a.b:8080/x?y=1#frag") == "http://a.b:8080/x?y=1"
+
+
+def test_read_rules_headers_and_comments():
+    rules = read_rules("# map\nsource,destination,note\n/a,/b,x\n\n/c,,keep\n")
+    assert [(r.old, r.new, r.line) for r in rules] == [("/a", "/b", 3), ("/c", "", 5)]
+    rules = read_rules("to,from\n/new,/old\n")
+    assert (rules[0].old, rules[0].new) == ("/old", "/new")
+    assert [r.old for r in read_rules("/a,/b\n/c,/d\n")] == ["/a", "/c"]
+
+
+def test_read_rules_rejects_missing_column():
+    with pytest.raises(ValueError):
+        read_rules("old,notes\n/a,x\n")
+
+
+def test_base_must_be_absolute():
+    with pytest.raises(ValueError):
+        Checker("example.com")
+
+
+def test_cli_exit_codes_and_json(site, tmp_path, capsys):
+    site.routes = {"/a": (301, "/b"), "/b": (200, None), "/c": (301, "/d"), "/d": (301, "/e"), "/e": (200, None)}
+    good = tmp_path / "good.csv"
+    good.write_text("old,new\n/a,/b\n")
+    assert main([str(good), "--base", site.url]) == 0
+    mixed = tmp_path / "mixed.csv"
+    mixed.write_text("old,new\n/a,/b\n/c,/e\n")
+    out = tmp_path / "r.json"
+    assert main([str(mixed), "--base", site.url, "--json", str(out)]) == 1
+    data = json.loads(out.read_text())
+    assert data["failed"] == 1 and data["results"][1]["kind"] == "chain"
+    assert "FAIL [chain] line 3: /c" in capsys.readouterr().out
+
+
+def test_cli_bad_input(tmp_path):
+    empty = tmp_path / "e.csv"
+    empty.write_text("")
+    assert main([str(empty), "--base", "https://example.com"]) == 2
+    assert main([str(tmp_path / "missing.csv"), "--base", "https://example.com"]) == 2