Skip to content

Commit f0434a2

Browse files
suicidesuicide
committed
IPIP propose gateway interop redirects compatible with _redirects
1 parent 80db667 commit f0434a2

File tree

2 files changed

+171
-1
lines changed

2 files changed

+171
-1
lines changed

‎IPIP/0386-gateway-interop-redirects.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# IPIP-386: Subdomain Gateway interop with _redirects
2+
3+
<!-- IPIP number should match its pull request number. After you open a PR,
4+
please update title and include anqabbreviated title in the filename too:
5+
`0000-draft-title-abbrev.md`. -->
6+
7+
- Start Date: 2023-03-18
8+
- Related Issues:
9+
- IPIP-2 _redirects file
10+
11+
## Summary
12+
13+
<!--One paragraph explanation of the IPIP.-->
14+
This IPIP suggests a tweak in the Path and Subdomain Gateway interop to
15+
leverage the `_redirects` file.
16+
17+
## Motivation
18+
19+
When hosting a modern Single Page Application on IPFS, one wants to use native
20+
URLs to share the app with other users, e.g. `ipns://example.org/cool/feature`.
21+
On traditional hosting, deep links are redirected or rewritten to a single
22+
entry point, e.g. `/index.html`, and the router on the client side evaluates
23+
the path segments to render the correct content.
24+
25+
The `_redirects` file, defined in [`REDIRECTS_FILE.md`](../REDIRECTS_FILE.md),
26+
supports such applications when a Subdomain Gateway is used directly. However,
27+
the current resolution of native URLs uses a Path Gateway link scheme and
28+
subsequently fails to resolve the URL correctly.
29+
30+
For example:
31+
32+
- `ipns://example.org/some/path` is resolved as
33+
- `http://{gateway}/ipns/example.org/some/path`
34+
- this request fails with 404 as the resource `/some/path` does not exist.
35+
36+
NOTE: The `kubo` gateway returns a 404 including a new `Location` header
37+
already pointing to the correct subdomain URL. But browsers do not follow the
38+
header as the status is 404, and the response contains a `text/plain` body
39+
string.
40+
41+
When using a Subdomain Gateway on the proper host, the path can be resolved
42+
using the `_redirects` file:
43+
44+
- `http://example-org.ipns.{gateway}/some/path` is redirected (301) to
45+
- `http://example-org.ipns.{gateway}/correct/path` as defined in
46+
`_redirects`file
47+
48+
49+
## Detailed design
50+
51+
This IPIP suggests the following resolution steps for DNSLink names, CIDs
52+
should be resolved similarly:
53+
54+
- `ipns://example.org/some/path` is resolved as
55+
- `http://{gateway}/ipns/example.org/some/path` is redirected (301) to the
56+
Subdomain Gateway
57+
- `http://example-org.ipns.{gateway}/some/path` is redirected (301) to
58+
- `http://example-org.ipns.{gateway}/correct/path` as defined in `_redirects`.
59+
60+
A Subdomain Gateway that provides interoperability with Path-Gateway-style URLs
61+
should redirect to a Subdomain-Gateway-style URL first and then try to resolve
62+
a given path. This allows the usage of a potential `_redirects` file in the
63+
root.
64+
65+
This change subsequently fixes the resolution of native URLs in browsers using
66+
the companion extension and browsers like Brave.
67+
68+
A paragraph is added to the [`SUBDOMAIN_GATEWAY.md`](../SUBDOMAIN_GATEWAY.md)
69+
spec that describes the preservation of path segments and query parameters
70+
during the interop redirect. Furthermore, it specifies that gateway
71+
implementations should redirect to subdomain URLs if a resource is initially
72+
not found in the directory identified by the CID or DNSLink name.
73+
74+
## Test fixtures
75+
76+
The example from the [REDIRECTS_FILE.md](../REDIRECTS_FILE.md) can be re-used,
77+
`QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj`.
78+
79+
```
80+
$ ipfs ls /ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj
81+
Qmd9GD7Bauh6N2ZLfNnYS3b7QVAijbud83b8GE8LPMNBBP 7 404.html
82+
QmSmR9NShZ89VEBrn9SBy7Xxvjw8Qe6XArD5GqtHvbtBM3 7 410.html
83+
QmVQqj9oZig9tH3ENHo4bxV5pNgssUwFCXUjAJAVcZVbJG 7 451.html
84+
QmZU3kboiyi9jV59D8Mw8wzuvsr3HmvskqhYRRhdFA8wRq 317 _redirects
85+
QmaWDLb4gnJcJbT1Df5X3j91ysiwkkyxw6329NLiC1KMDR - articles/
86+
QmS6ZNKE9s8fsHoEnArsZXnzMWijKddhXXDsAev8LdTT5z 9 index.html
87+
QmNwEgMrExwSsE8DCjZjahYfHUfkSWRhtqSkQUh4Fk3udD 7 one.html
88+
QmVe2GcTbEPZkMbjVoQ9YieVGKCHmuHMcJ2kbSCzuBKh2s - redirected-splat/
89+
QmUGVnZaofnd5nEDvT2bxcFck7rHyJRbpXkh9znjrJNV92 7 two.html
90+
```
91+
92+
The `_redirects` file is as follows.
93+
94+
```
95+
$ ipfs cat /ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj/_redirects
96+
/redirect-one /one.html
97+
/301-redirect-one /one.html 301
98+
/302-redirect-two /two.html 302
99+
/200-index /index.html 200
100+
/posts/:year/:month/:day/:title /articles/:year/:month/:day/:title 301
101+
/splat/* /redirected-splat/:splat 301
102+
/not-found/* /404.html 404
103+
/gone/* /410.html 410
104+
/unavail/* /451.html 451
105+
/* /index.html 200
106+
```
107+
108+
Following redirects should occur:
109+
110+
```
111+
$ curl -v http://{gateway}/ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj/redirect-one
112+
...
113+
< HTTP/1.1 301 Moved Permanently
114+
< Location: http://bafybeiesjgoros75o5meijhfvnxmy7kzkynhqijlzmypw3nry6nvsjqkzy.ipfs.{gateway}/redirect-one
115+
...
116+
```
117+
118+
Subsequent requests should comply with IPIP-2.
119+
120+
## Design rationale
121+
122+
Gateways like `kubo` already support the suggested redirect but block the
123+
redirect chain by returning a 404 when a resource is not found on the Path
124+
Gateway. By removing the 404, users get another chance to find the resources
125+
they are looking for.
126+
127+
### User benefit
128+
129+
Currently, users are presented with an error message when they request a
130+
resource on a Path Gateway intended for a Subdomain Gateway. Since a given
131+
gateway would redirect on a valid resource anyway, redirecting to the subdomain
132+
URL on a potentially invalid resource would improve usability and
133+
compatibility.
134+
135+
### Compatibility
136+
137+
This proposal improves the reach of `_redirects` files.
138+
139+
The current behavior is defined in [PATH_GATEWAY.md](../PATH_GATEWAY.md). The
140+
404 return code indicates that a resource does not exist. Changing this to a
141+
301 redirect that is subsequently answered with a 404 from the subdomain URL
142+
might break clients.
143+
144+
However, requesting an existing resource on the Path Gateway URL in `kubo`
145+
already returns a 301 redirect while also providing the content in the body.
146+
147+
### Security
148+
149+
Security should not be compromised as the resource is not delivered from the
150+
Path Gateway URL but from the subsequent subdomain URL that offers improved
151+
security due to host separation.
152+
153+
### Alternatives
154+
155+
Gateways could continue to return a 404 response for the non-existing resource,
156+
but also include an HTML body containing a redirect link. This would help users
157+
to find the requested site.
158+
159+
### Copyright
160+
161+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

‎http-gateways/SUBDOMAIN_GATEWAY.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,11 +160,20 @@ Below MUST be implemented **in addition** to
160160

161161
Returned with [`301` Moved Permanently](./PATH_GATEWAY.md#301-moved-permanently) when `Host` header does
162162
not follow the subdomain naming convention, but the requested URL path happens
163-
to be a valid `/ipfs/{cid}` or `/ipfs/{name}` content path.
163+
to be a valid `/ipfs/{cid}(/{path})` or `/ipns/{name}(/{path})` content path.
164164

165165
This redirect allows subdomain gateway to be used as a drop-in
166166
replacement compatible with regular path gateways.
167167

168+
Redirects MUST preserve the path segments (`path`) following the CID or DNSLink
169+
name and all query parameters. Implementations may choose to look up the CID or
170+
DNSLink name before redirecting, but they MUST still redirect if the requested
171+
`path` in the directory is not found and a `_redirects` file is present in the
172+
root. Alternatively, the implementation may blindly redirect solely based on
173+
the information in the requested URL. Eventually, the Subdomain Gateway may use
174+
the `_redirects` file from [`REDIRECTS_FILE.md`](./REDIRECTS_FILE.md) to
175+
resolve the requested resource.
176+
168177
NOTE: the content root identifier must be converted to case-insensitive/inlined
169178
form if necessary. For example:
170179

0 commit comments

Comments
 (0)