IPIP-0386: Subdomain Gateway Interop with _redirects

1. Summary

This IPIP provides a detailed clarification on the interoperability between the Path and Subdomain Gateway. Specifically, it ensures that features such as [web-redirects-file] are executed only AFTER a redirect to a subdomain has taken place.

2. Motivation

When hosting a modern Single Page Application on IPFS, one wants to use native URLs to share the app with other users, e.g. ipns://example.org/cool/feature. On traditional hosting, deep links are redirected or rewritten to a single entry point, e.g. /index.html, and the router on the client side evaluates the path segments to render the correct content.

The _redirects file, defined in [web-redirects-file], supports such applications when a Subdomain Gateway is used directly. However, the current resolution of native URLs uses a Path Gateway link scheme and subsequently fails to resolve the URL correctly.

For example:

• ipns://example.org/some/path is resolved as
• http://{gateway}/ipns/example.org/some/path
• this request fails with 404 as the resource /some/path does not exist.

NOTE: The kubo (<0.20) gateway returns a 404 including a new Location header already pointing to the correct subdomain URL. But browsers do not follow the header as the status is 404, and the response contains a text/plain body string.

When using a Subdomain Gateway on the proper host, the path can be resolved using the _redirects file:

• http://example-org.ipns.{gateway}/some/path is redirected (301) to
• http://example-org.ipns.{gateway}/correct/path as defined in _redirectsfile

3. Detailed design

This IPIP suggests the following resolution steps for DNSLink names, CIDs should be resolved similarly:

• ipns://example.org/some/path is resolved as
• http://{gateway}/ipns/example.org/some/path is redirected (301) to the Subdomain Gateway
• http://example-org.ipns.{gateway}/some/path is redirected (301) to
• http://example-org.ipns.{gateway}/correct/path as defined in _redirects.

A Subdomain Gateway that provides interoperability with Path-Gateway-style URLs should redirect to a Subdomain-Gateway-style URL first and then try to resolve a given path. This allows the usage of a potential _redirects file in the root.

This change subsequently fixes the resolution of native URLs in browsers using the companion extension and browsers like Brave.

A paragraph is added to the [subdomain-gateway] spec that describes the preservation of path segments and query parameters during the interop redirect. Furthermore, it specifies that gateway implementations should redirect to subdomain URLs if a resource is initially not found in the directory identified by the CID or DNSLink name.

4. Test fixtures

The example from the [web-redirects-file] can be re-used, 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

Following redirects should occur:

$ curl -v http://{gateway}/ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj/redirect-one
...
< HTTP/1.1 301 Moved Permanently
< Location: http://bafybeiesjgoros75o5meijhfvnxmy7kzkynhqijlzmypw3nry6nvsjqkzy.ipfs.{gateway}/redirect-one
...

Subsequent requests should comply with [ipip-0002].

5. Design rationale

Gateways like kubo (before v0.20) already support the _redirect and subdomain redirect, but block the redirect chain by returning a 404 when a resource is not found on the Path Gateway. By moving the 404 to occur at the subdomain, users get another chance to find the resources they are looking for.