2.1From

The path to redirect from.

2.2To

The URL or path to redirect to.

2.3Status

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.4Placeholders

Placeholders are named variables that can be used to match path segments in thefrom path and inject them into theto 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.

ImplementationMUST error when the same placeholder name is used more than once infrom.

ImplementationMUST allow the same placeholder name to be used more than once into.

/posts/* /articles/:splat

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

/home /index.html 301

3.1Same-Origin Requirement

RulesMUST only be evaluated in contexts whereSame-Origin isolation perroot CID is possible.

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

3.2Order

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

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.

3.3No Forced Redirects

All redirect logicMUST 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.

3.4Error Handling

If the_redirects file exists but there is an error reading or parsing it, the errorsMUST be returned to the user with a 500 HTTP status code.

3.5Query Parameters

ImplementationsSHOULD retain any dynamic query parameters supplied by the user and pass them along in theLocation header of the HTTP redirect response.

When merging these user-provided parameters with any static ones defined in theTo field, the user’s dynamic values take precedence, overriding static ones in case of a conflict.

5.1Test fixtures

Sample files for various test cases can be found inQmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4.ImplementationsSHOULD use it for internal testing.

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

For example, the "examples" site can be found inQmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj.

$ ipfs ls /ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZjQmd9GD7Bauh6N2ZLfNnYS3b7QVAijbud83b8GE8LPMNBBP 7   404.htmlQmSmR9NShZ89VEBrn9SBy7Xxvjw8Qe6XArD5GqtHvbtBM3 7   410.htmlQmVQqj9oZig9tH3ENHo4bxV5pNgssUwFCXUjAJAVcZVbJG 7   451.htmlQmZU3kboiyi9jV59D8Mw8wzuvsr3HmvskqhYRRhdFA8wRq 317 _redirectsQmaWDLb4gnJcJbT1Df5X3j91ysiwkkyxw6329NLiC1KMDR -   articles/QmS6ZNKE9s8fsHoEnArsZXnzMWijKddhXXDsAev8LdTT5z 9   index.htmlQmNwEgMrExwSsE8DCjZjahYfHUfkSWRhtqSkQUh4Fk3udD 7   one.htmlQmVe2GcTbEPZkMbjVoQ9YieVGKCHmuHMcJ2kbSCzuBKh2s -   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

A dedicated test vector with URL query parameter behavior can be found inbafybeiee3ltldvmfgsxiqazbatrkbvkl34eanbourajwnavhupb64nnbxa.ImplementationsSHOULD use it for internal testing whenquery parameter support is desired.

$ ipfs cat bafybeiee3ltldvmfgsxiqazbatrkbvkl34eanbourajwnavhupb64nnbxa/_redirects# redirect to URL with some static query parameters/source1/* /target-file?static-query1=static-val1&static-query2=static-val2 301# redirect to URL where path segments are converted to query parameters/source2/:code/:name /target-file?code=:code&name=:name 301# catch-all redirect (test should make request with query parameters, and confirm response preserved them in returned Location header)/source3/* https://example.net/target3/:splat 301