Docs | synapsereality.io | Synapse open source | PyPI
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. Run it in CI has jobs for GitHub Actions, GitLab CI, Bitbucket Pipelines and a plain shell step.
Docs: https://synapsereality.io/open-source/one-hop/
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.
Before the move: snapshot the old URLs
A redirect map is only as good as its list of old URLs. one-hop snapshot
records them while the old site is still up, so the map starts from what the
site serves, not from memory.
one-hop snapshot https://example.com/sitemap.xml --out snapshot.csv
It reads the sitemap, following redirects, sitemap indexes and .gz files.
--urls FILE adds URLs the sitemap leaves out, one per line. Then it fetches
each URL, follows its redirects and writes a row for it. Against a local test
server:
$ one-hop snapshot https://example.com/sitemap.xml --urls extra-urls.txt --out snapshot.csv
fetching 5 URLs, 2 a second per host, 2 at a time
5/5
wrote 5 rows to snapshot.csv (200: 2, 301: 1, 404: 1, disallowed by robots.txt: 1)
old,new,status,final_status,final_url,canonical,note
/,,200,200,https://example.com/,https://example.com/,
/about-us,,301,200,https://example.com/about/,https://example.com/about/,
/blog/old-post/,,200,200,https://example.com/blog/old-post/,https://example.com/blog/new-post/,
/private/report,,,,,,disallowed by robots.txt
/pricing,,404,404,https://example.com/pricing,,
| column | what it holds |
|---|---|
old |
the URL as a path. URLs on another host keep the full URL, as does a path starting with //. --absolute keeps it for all of them |
new |
empty. Fill it in for each URL that moves |
status |
what the old URL answered |
final_status, final_url |
where its redirects end, and what that URL answered |
canonical |
the canonical URL of the final page, from a Link header or the HTML <head> |
note |
what stopped the fetch, if anything: robots.txt, a redirect loop, too many redirects, a redirect to a non-http URL or a failed request |
Fill in new and the file is the redirect map this tool checks:
one-hop snapshot.csv --base https://staging.example.com
A row with new left empty says the URL must still answer 200 with no
redirect, so a page nobody mapped fails the check as not_found.
It records the URL inventory, not the site. No page content is kept, so it doesn't replace a backup.
How it fetches
- It reads each host's robots.txt first, as
RFC 9309 describes. It follows the
group for
one-hop, or*when no group names it. A URL that robots.txt disallows is listed with a note and never fetched. - If robots.txt answers 5xx or 429, or doesn't answer, nothing on that host is fetched. A 404 robots.txt allows everything.
- It sends at most
--raterequests a second to any one host (default 2), with at most--concurrencyin flight (default 2). A slowerCrawl-delayin robots.txt wins, up to 60 seconds. - The user agent is
one-hop/VERSION (+https://github.com/synapsereality/one-hop). - It only sends GET requests, and reads at most 1 MiB of each page to find the canonical.
Snapshot options
| flag | default | |
|---|---|---|
--urls FILE |
none | also fetch the URLs in FILE, one per line. Repeatable, - reads stdin |
--out FILE |
stdout | where to write the CSV |
--rate N |
2 | requests a second to any one host |
--concurrency N |
2 | requests in flight at once |
--timeout S |
20 | seconds per request |
--max-hops N |
10 | stop following a redirect chain after N hops |
--max-urls N |
50000 | stop after N URLs |
--absolute |
off | write full URLs in the old column |
--insecure |
off | skip TLS certificate checks |
The exit code is 0 when no sitemap failed. That includes a run that
--max-urls cut short. It's 1 when a sitemap couldn't be read, or when the
run stopped after 1,000 sitemap files. The CSV still has every URL it found.
It's 2 when the command line was wrong, --out can't be written or there
were no URLs to fetch. A failed run leaves an earlier --out file as it was.
Sitemaps have to be UTF-8, as the sitemap protocol says. One with a
DOCTYPE or entities isn't read.
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.
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:
$ 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.
Run it in CI
Each job below fails when any rule fails. They check redirects.csv against a
staging host. After the move, point --base at the live site and run the same
job again.
For a staging host behind a password, store user:password as a secret named
ONE_HOP_AUTH. one-hop reads it from the environment, so it never appears in
the command or the log.
GitHub Actions
- uses: actions/checkout@v4
- uses: synapsereality/one-hop@v0.2.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.
GitLab CI
In .gitlab-ci.yml:
redirects:
image: python:3.13-slim
script:
- pip install one-hop==0.2.0
- one-hop redirects.csv --base https://staging.example.com --json redirects.json
artifacts:
when: always
paths:
- redirects.json
Add ONE_HOP_AUTH under Settings, CI/CD, Variables, with its visibility set
to Masked and "Expand variable reference" unticked. GitLab passes it to the
job as an environment variable. A masked value has to be at least 8
characters with no spaces. With expansion on, GitLab also refuses most
symbols in it. when: always keeps the
JSON report when the job fails, which is when you need it.
Bitbucket Pipelines
In bitbucket-pipelines.yml:
image: python:3.13-slim
pipelines:
default:
- step:
name: Check the redirect map
script:
- pip install one-hop==0.2.0
- one-hop redirects.csv --base https://staging.example.com
Add ONE_HOP_AUTH under Repository settings, Pipelines, Repository variables,
with Secured ticked. Bitbucket passes it to the step as an environment
variable and hides its value in the log.
Any other CI: a shell step
Jenkins, CircleCI, Drone, a Makefile or a deploy script: anything that runs a shell command and reads its exit code. You need Python 3.10 or later. A virtual environment keeps the install away from the system Python:
python3 -m venv .one-hop
.one-hop/bin/pip install one-hop==0.2.0
.one-hop/bin/one-hop redirects.csv --base https://staging.example.com
To tell a broken redirect apart from a check that couldn't run:
status=0
.one-hop/bin/one-hop redirects.csv --base https://staging.example.com || status=$?
case $status in
0) echo "every old URL reaches its new URL in one hop" ;;
1) echo "at least one rule failed. See the FAIL lines above."; exit 1 ;;
*) echo "one-hop did not run: check the CSV and the command line"; exit 2 ;;
esac
Exit codes
| code | meaning |
|---|---|
| 0 | Every rule passed. |
| 1 | At least one rule failed: any kind in the table above, error included. A host that refuses the connection or times out is a failure too. A crash also gives 1, for example a --json path that can't be written. |
| 2 | Nothing was checked: the CSV couldn't be read or had no rules, --base wasn't an absolute URL, or a flag was wrong. |
Pin the version, as above, so a new release can't change a passing build.
Install from source
git clone https://github.com/synapsereality/one-hop
cd one-hop
pip install .
Python 3.11 or later, no dependencies. python -m one_hop works without
installing if src is on PYTHONPATH.
Tests
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.
Metadata
Release files for one-hop 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| one_hop-0.2.0.tar.gz | 32.5 kB | With provenance | Details for one_hop-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| one_hop-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for one_hop-0.2.0-py3-none-any.whl |
Total release size: 56.3 kB
Release files / one_hop-0.2.0.tar.gz
| Download URL | one_hop-0.2.0.tar.gz |
|---|---|
| Size | 32.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
51358738b8608ddf55696adee76387e6e122edfaab0847af555e122dbf64d3a9
|
|
BLAKE2b-256 checksum How to use checksums |
fe272c6626757c6be48bf2497da2084056db8e0aad7a0c34effbe52322980a36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / one_hop-0.2.0-py3-none-any.whl
| Download URL | one_hop-0.2.0-py3-none-any.whl |
|---|---|
| Size | 23.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2536e8d53a0e0198dbaadb8a3ac34423dca80ed93bed707f1c19fef566d4792e
|
|
BLAKE2b-256 checksum How to use checksums |
b221932e170d334a619fd75d2fa2b142eeeaff2eefe2b3a998058937081f8aa4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for one-hop 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for one_hop-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.