Web _redirects File Specification

2.1 From

The path to redirect from.

2.2 To

The URL or path to redirect to.

2.3 Status

An optional integer specifying the HTTP status code to return from the request. Supported values are:

• 200 - OK
  • Redirect will be treated as a rewrite, returning OK without changing the URL in the browser.
• 301 - Permanent Redirect (default)
• 302 - Found (commonly used for Temporary Redirect)
• 303 - See Other (replacing PUT and POST with GET)
• 307 - Temporary Redirect (explicitly preserving body and HTTP method of original request)
• 308 - Permanent Redirect (explicitly preserving body and HTTP method of original request)
• 404 - Not Found
  • Useful for redirecting invalid URLs to a pretty 404 page.
• 410 - Gone
• 451 - Unavailable For Legal Reasons

2.4 Placeholders

Placeholders are named variables that can be used to match path segments in the from path and inject them into the to path.

For example:

/posts/:month/:day/:year/:slug  /articles/:year/:month/:day/:slug

This rule will redirect a URL like /posts/06/15/2022/hello-world to /articles/2022/06/15/hello-world.

Implementation MUST error when the same placeholder name is used more than once in from.

Implementation MUST allow the same placeholder name to be used more than once in to.

/posts/* /articles/:splat

# Redirect home to index.html
/home /index.html 301

/home /index.html 301

3.1 Same-Origin Requirement

Rules MUST only be evaluated in contexts where Same-Origin isolation per root CID is possible.

This requirement is fulfilled on a Subdomain or DNSLink HTTP Gateway, and also applies to a web browser with native ipfs:// and ipns:// scheme handler.

3.2 Order

Rules MUST be evaluated in order, redirecting or rewriting using the first matching rule.

3.3 No Forced Redirects

All redirect logic MUST only be evaluated if the requested path is not present in the DAG. This means that any performance impact associated with checking for the existence of a _redirects file or evaluating redirect rules will only be incurred for non-existent paths.

6.1 Test fixtures

Sample files for various test cases can be found in QmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4. Implementations SHOULD use it for internal testing.

$ ipfs ls QmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4
QmcBcFnKKqgpCVMxxGsriw9ByTVF6uDdKDMuEBq3m6f1bm - bad-codes/
QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj - examples/
QmU7ysGXwAtiV7aBarZASJsxKoKyKmd9Xrz2FFamSCbg8S - forced/
QmWHn2TunA1g7gQ7q9rwAoWuot2hMpojZ6cZ9ERsNKm5gE - good-codes/
QmRgpzYQESidTtTojN8zRWjiNs9Cy6o7KHRxh7kDpJm3KH - invalid/
QmYzMrtPyBv7LKiEAGLLRPtvqm3SjQYLWxwWQ2vnpxQwRd - newlines/
QmQTfvjGmvTfxFpUcZNLdTLuKV227KJkGiN6xooHVeVZAS - too-large/

For example, the "examples" site can be found in QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj.

$ ipfs ls /ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj
Qmd9GD7Bauh6N2ZLfNnYS3b7QVAijbud83b8GE8LPMNBBP 7   404.html
QmSmR9NShZ89VEBrn9SBy7Xxvjw8Qe6XArD5GqtHvbtBM3 7   410.html
QmVQqj9oZig9tH3ENHo4bxV5pNgssUwFCXUjAJAVcZVbJG 7   451.html
QmZU3kboiyi9jV59D8Mw8wzuvsr3HmvskqhYRRhdFA8wRq 317 _redirects
QmaWDLb4gnJcJbT1Df5X3j91ysiwkkyxw6329NLiC1KMDR -   articles/
QmS6ZNKE9s8fsHoEnArsZXnzMWijKddhXXDsAev8LdTT5z 9   index.html
QmNwEgMrExwSsE8DCjZjahYfHUfkSWRhtqSkQUh4Fk3udD 7   one.html
QmVe2GcTbEPZkMbjVoQ9YieVGKCHmuHMcJ2kbSCzuBKh2s -   redirected-splat/
QmUGVnZaofnd5nEDvT2bxcFck7rHyJRbpXkh9znjrJNV92 7   two.html

The _redirects file is as follows.

$ ipfs cat /ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj/_redirects
/redirect-one /one.html
/301-redirect-one /one.html 301
/302-redirect-two /two.html 302
/200-index /index.html 200
/posts/:year/:month/:day/:title /articles/:year/:month/:day/:title 301
/splat/* /redirected-splat/:splat 301
/not-found/* /404.html 404
/gone/* /410.html 410
/unavail/* /451.html 451
/* /index.html 200

The non-existent paths that are being requested should be intercepted and redirected to the destination path and the specified HTTP status code returned. The rules are evaluated in the order they appear in the file.

Any request for an existing file should be returned as is, and not intercepted by the last catch all rule.