Permanent redirects for the addresses a hub used to answer: old routes, renamed files and superseded identifiers
  • Python 91.4%
  • HTML 7.6%
  • Mako 1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-16 17:09:49 +00:00
docs feat: the addresses a hub used to answer keep answering, 301, 308 or 410 (CO-2) 2026-10-25 02:47:50 +01:00
src tests: in a product with a /doi/<pid>/ route the router adds the slash first 2026-11-01 13:43:09 +01:00
.gitignore feat: scaffold splent_feature_legacy_urls with splent feature:create 2026-10-25 02:38:37 +01:00
COPYING feat: scaffold splent_feature_legacy_urls with splent feature:create 2026-10-25 02:38:37 +01:00
COPYING.LESSER feat: scaffold splent_feature_legacy_urls with splent feature:create 2026-10-25 02:38:37 +01:00
MANIFEST.in feat: scaffold splent_feature_legacy_urls with splent feature:create 2026-10-25 02:38:37 +01:00
pyproject.toml chore: release splent_io/splent_feature_legacy_urls to v0.2.1 2026-11-16 17:09:49 +00:00
README.md docs: legacy_urls => auth in the line, and why 2026-10-25 16:26:36 +01:00

splent_feature_legacy_urls

The addresses a hub used to answer, kept answering (CO-2). A hub that moves, renames a route or takes a page down leaves its old addresses in citations, bookmarks, mails and other sites. This feature keeps one row per address with what it answers now: a permanent redirect, 301 or 308, to where it went, or 410, gone. Rows come in through an import, from a file or a migration, and administrators read them on /admin/legacy-urls.

What an old address answers

A row answers only an address nothing else answers. The lookup runs on a response that is a 404, whoever made it: a route that matched nothing, a route that found nothing (dataset's /doi/<doi>/ for a DOI no dataset has), or a product's own handler. Any other response goes out as it was, without a query, so a route of the hub always wins over a row, and an address the hub answers is never looked up.

  • 301 and 308 redirect to the row's target, a path of the hub or an http(s) address elsewhere. 308 keeps the method and the body, so a client that posted to the old address posts to the new one; 301 lets a client follow it with a GET. The request's query string goes along when the target has none.
  • 410 answers the product's 410.html, else an errors/410.html a theme ships, else this feature's page in the public shell (legacy_urls/gone.html), and JSON ({"error": "Gone", "code": "gone"}) to a client that asks for JSON.
  • The path is what a route reads: percent-decoded, without the query string, compared byte for byte (utf8mb4_bin). An address finds its own row, else the row of the same path with or without its last /. A row whose target is the very address asked for answers nothing, so no redirect sends a client back where it was.

Why after the request: the framework has no hook that runs before a 404. Its error handler for 404 is the one theme replaces from its own init_feature, so a handler of this feature would win or lose by the order the features load in. A catch-all route registered last does not help either: Werkzeug ranks routes by their fixed parts, not by when they were registered, so /<path:path> loses to every route with a fixed start, an old DOI under /doi/<path:doi>/ among them, and it would turn the 405 of a known address into a 404. answer_moved (redirects.py), an after_request of the app, sees every 404 instead, and costs one indexed query on a 404 and nothing on any other response. Without the table (a database the migration has not reached yet) the 404 stays, and the log says so.

Importing

splent feature:legacy_urls import addresses.csv
splent feature:legacy_urls import addresses.json --dry-run
cat addresses.csv | splent feature:legacy_urls import -

A CSV starts with the header path,target,status,ref; a JSON file is a list of objects with those keys. ref says what the row stands for where it came from (doi_mapping:12, hubfiles:7), and the screen shows it. Every row is checked before any is written, and one refused row means nothing changes: the command lists each refused row with its reason and exits 1. A row of a path already there replaces it; the command says how many it adds, updates and leaves as they were. A row is refused when:

  • its path does not start with one /, holds a query string, a fragment or a control character, or is longer than 512;
  • its status is not 301, 308 or 410;
  • a redirect has no target, or one that is neither a path of the hub nor an http or https address, or its own path; a 410 has a target;
  • the file names its path twice;
  • its target leads, through the other redirects, back to it, or into a loop of others.

In code, LegacyUrlService().import_rows(rows, dry_run=False) does the same with a list of dicts and returns what it did (ImportResult), and answering(path) is the lookup.

For administrators

/admin/legacy-urls, in the Administration section of the menu (legacy_urls, order 96), lists the rows by path, with what each answers, its target and its ref, narrowed by a text in the path or the target and by the answer. It changes nothing: rows come in through the import.

The table

legacy_url (legacy_urls0001_urls): path (unique, utf8mb4_bin), target (NULL for a 410), status, ref, created_at and updated_at. The downgrade drops it, and the addresses answer 404 again.

Use it in a product

splent feature:add splent_feature_legacy_urls

It requires no other feature; the screen needs a signed-in administrator, so it reads the account from auth. In the OpenHubs line it is an optional feature of the repository layer (repositorio, added by docs/openhubs_spl.uvl.patch), with legacy_urls => auth: the screen of the old addresses is for administrators.

Develop

splent feature:test splent_feature_legacy_urls
splent feature:contract splent_feature_legacy_urls

Release

splent feature:release splent_feature_legacy_urls --dry-run --bump minor
splent feature:release splent_feature_legacy_urls

The first command rehearses the release and changes nothing. The second publishes it to the git forge and to PyPI, and a PyPI version is permanent.

License

LGPL-3.0-or-later, as the rest of the SPLENT catalog: COPYING.LESSER and COPYING.