Skip to content

Commit 16cc443

Browse files
lidellidel
authored
Merge pull request #290 from justincjohnson/feat/gateway-redirects
IPIP: Gateway _redirects File
2 parents 7e9612d + 33f4f44 commit 16cc443

5 files changed

+291
-0
lines changed

‎IPIP/0002-gateway-redirects-file.md

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# IPIP 0002: _redirects File Support on Web Gateways
2+
3+
- Start Date: (format: 2022-06-15)
4+
- Related Issues:
5+
- [ipfs/specs/issues/257](https://github.com/ipfs/specs/issues/257)
6+
- [ipfs/kubo/pull/8890](https://github.com/ipfs/kubo/pull/8890)
7+
- [ipfs-docs/pull/1275](https://github.com/ipfs/ipfs-docs/pull/1275)
8+
9+
## Summary
10+
11+
Provide support for URL redirects and rewrites for web sites hosted on Subdomain or DNSLink Gateways, thus enabling support for [single-page applications (SPAs)](https://en.wikipedia.org/wiki/Single-page_application), and avoiding [link rot](https://en.wikipedia.org/wiki/Link_rot) when moving to IPFS-backed hosting.
12+
13+
## Motivation
14+
15+
Web sites often need to redirect from one URL to another, for example, to change the appearance of a URL, to change where content is located without breaking existing links (see [Cool URIs don't change](https://www.w3.org/Provider/Style/URI), [link rot](https://en.wikipedia.org/wiki/Link_rot)), to redirect invalid URLs to a pretty 404 page, or to enable URL rewriting.
16+
URL rewriting in particular is a critical feature for hosting SPAs, allowing routing logic to be handled by front end code. SPA support is the primary impetus for this RFC.
17+
18+
Currently the only way to handle URL redirects or rewrites is with additional software such as NGINX sitting in front of the Gateway. This software introduces operational complexity and decreases the uniformity of experience when navigating to content hosted on a Gateway, thus decreasing the value proposition of hosting web sites in IPFS.
19+
20+
This IPIP proposes the introduction of redirect support for content hosted on Subdomain or DNSLink Gateways, configured via a `_redirects` file residing underneath the root CID of the web site.
21+
22+
## Detailed design
23+
24+
Allow developers to configure redirect support by adding redirect rules to a file named `_redirects` stored underneath the root CID of their web site.
25+
The format for this file is similar to those of [Netlify](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) and [Cloudflare Pages](https://developers.cloudflare.com/pages/platform/redirects) but only supporting a subset of their functionality.
26+
27+
The format for the file is `from to [status]`.
28+
29+
- `from` - specifies the path to intercept (can include placeholders and a trailing splat)
30+
- `to` - specifies the path or URL to redirect to (can include placeholders or splat matched in `from`)
31+
- `status` - optional [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) (301 if not specified)
32+
33+
Rules in the file are evaluated top to bottom.
34+
35+
For performance reasons this proposal does not include forced redirect support (i.e. redirect rules that are evaluated even if the `from` path exists). In other word, redirect logic will be evaluated if and only if the requested path does not exist. If the requested path exists, we won't even check for the existence of the `_redirects` file.
36+
37+
If a `_redirects` file exists but is unable to be processed, perhaps not even parsing correctly, errors will be returned to the user viewing the site via the Gateway.
38+
39+
The detailed specification is added in [`http-gateways/REDIRECTS_FILE.md`](../http-gateways/REDIRECTS_FILE.md).
40+
41+
### Test fixtures
42+
QmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4
43+
44+
See spec for testing details.
45+
46+
## Design rationale
47+
48+
Popular services today such as [Netlify](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) and [Cloudflare Pages](https://developers.cloudflare.com/pages/platform/redirects) allow developers to configure redirect support
49+
using a `_redirects` file hosted at the top level of the web site. While we do not intend to provide all of the same functionality, it seems desirable to use a similar approach to provide a meaningful subset of the functionality offered by these services.
50+
51+
- The format is simple and low on syntax
52+
- Many developers are already familiar with this file name and format
53+
- Using a text file for configuration enables developers to make changes without using other IPFS tools
54+
- The configuration can be easily versioned in both version control systems and IPFS by virtue of the resulting change to the root CID for the content
55+
56+
### User benefit
57+
58+
Provides general URL redirect and rewrite support, which enables three important features:
59+
1. Developers will be able to host single-page applications in IPFS.
60+
2. Same configuration file used for setting up pretty 404 pages.
61+
3. The cost of switching hosting of an existing website to IPFS is lowered by making it possible to keep all legacy URLs working.
62+
63+
### Compatibility
64+
65+
If by some chance developers are already hosting sites that contain a `_redirects` file that does something else, they may need to update the contents of the file to match the new functionality. Errors returned to the user due to parsing errors will guide them regarding the required updates.
66+
67+
### Alternatives
68+
69+
- There was some discussion early on about a [manifest file](https://github.com/ipfs/specs/issues/257) that could be used to configure redirect support in addition to many other things. While the idea of a manifest file has merit, manifest files are much larger in scope and it became challenging to reach agreement on functionality to include.
70+
There is already a large need for redirect support for SPAs, and this proposal allows us to provide that critical functionality without being hampered by further design discussion around manifest files.
71+
In addition, similar to how Netlify allows redirect support to be configured in either a `_redirects` file or a more general [configuration file](https://docs.netlify.com/configure-builds/file-based-configuration/#redirects), there is nothing precluding IPFS from allowing developers to configure redirect support in an app manifest later on.
72+
- There was some discussion with the [n0](https://github.com/n0-computer/) team about potential ways to improve the performance of retrieving metadata such as redirect rules, possibly including it as metadata with the root CID such that it would be included with the request for the CID to begin with.
73+
I believe the performance concerns are alleviated by not providing forced redirect support, and looking for `_redirects` only if the DAG is missing a requested path. Never the less, if a more generic metadata facility were to be introduced in the future, it may make sense to reconsider how redirect rules are specified.
74+
75+
### Copyright
76+
77+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

‎http-gateways/DNSLINK_GATEWAY.md

+5
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ In short:
3636
- [HTTP Response](#http-response)
3737
- [Appendix: notes for implementers](#appendix-notes-for-implementers)
3838
- [Leveraging DNS for content routing](#leveraging-dns-for-content-routing)
39+
- [Redirects, single-page applications, and custom 404s](#redirects-single-page-applications-and-custom-404s)
3940

4041
# HTTP API
4142

@@ -98,3 +99,7 @@ Same as [HTTP Response section in `PATH_GATEWAY.md`](./PATH_GATEWAY.md#http-resp
9899
TXT records with known content providers for the data behind a DNSLink. IPFS
99100
clients will be able to detect DNSAddr and preconnect to known content
100101
providers, removing the need for expensive DHT lookup.
102+
103+
## Redirects, single-page applications, and custom 404s
104+
105+
DNSLink Gateway implementations are free to include `_redirects` file support defined in [`REDIRECTS_FILE.md`](./REDIRECTS_FILE.md).

‎http-gateways/README.md

+1
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,4 @@ model](https://en.wikipedia.org/wiki/Same-origin_policy).
4040

4141
* [SUBDOMAIN_GATEWAY.md](./SUBDOMAIN_GATEWAY.md)
4242
* [DNSLINK_GATEWAY.md](./DNSLINK_GATEWAY.md)
43+
* [REDIRECTS_FILE.md](./REDIRECTS_FILE.md)

‎http-gateways/REDIRECTS_FILE.md

+204
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# `_redirects` File Specification
2+
3+
![draft](https://img.shields.io/badge/status-draft-yellow.svg?style=flat-square)
4+
5+
**Authors**:
6+
7+
- Justin Johnson ([@justincjohnson](https://github.com/justincjohnson))
8+
9+
----
10+
11+
**Abstract**
12+
13+
The Redirects File specification is an extension of the Subdomain Gateway and DNSLink Gateway specifications.
14+
15+
Developers can enable URL redirects or rewrites by adding redirect rules to a file named `_redirects` stored underneath the root CID of their web site.
16+
17+
This can be used, for example, to enable URL rewriting for hosting a single-page application, to redirect invalid URLs to a pretty 404 page, or to avoid [link rot](https://en.wikipedia.org/wiki/Link_rot) when moving to IPFS-based website hosting.
18+
19+
# Table of Contents
20+
21+
- [File Name and Location](#file-name-and-location)
22+
- [File Format](#file-format)
23+
- [From](#from)
24+
- [To](#to)
25+
- [Status](#status)
26+
- [Placeholders](#placeholders)
27+
- [Splat](#splat)
28+
- [Comments](#comments)
29+
- [Line Termination](#line-termination)
30+
- [Max File Size](#max-file-size)
31+
- [Evaluation](#evaluation)
32+
- [Subdomain or DNSLink Gateways](#subdomain-or-dnslink-gateways)
33+
- [Order](#order)
34+
- [No Forced Redirects](#no-forced-redirects)
35+
- [Error Handling](#error-handling)
36+
- [Security](#security)
37+
- [Appendix: notes for implementors](#appendix-notes-for-implementors)
38+
- [Test fixtures](#test-fixtures)
39+
40+
# File Name and Location
41+
42+
The Redirects File MUST be named `_redirects` and stored underneath the root CID of the web site.
43+
44+
# File Format
45+
46+
The Redirects File MUST be a text file containing one or more lines with the following format (brackets indication optionality).
47+
48+
```
49+
from to [status]
50+
```
51+
52+
## From
53+
54+
The path to redirect from.
55+
56+
## To
57+
58+
The URL or path to redirect to.
59+
60+
## Status
61+
62+
An optional integer specifying the HTTP status code to return from the request. Supported values are:
63+
64+
- `200` - OK
65+
- Redirect will be treated as a rewrite, returning OK without changing the URL in the browser.
66+
- `301` - Permanent Redirect (default)
67+
- `302` - Found (commonly used for Temporary Redirect)
68+
- `303` - See Other (replacing PUT and POST with GET)
69+
- `307` - Temporary Redirect (explicitly preserving body and HTTP method of original request)
70+
- `308` - Permanent Redirect (explicitly preserving body and HTTP method of original request)
71+
- `404` - Not Found
72+
- Useful for redirecting invalid URLs to a pretty 404 page.
73+
- `410` - Gone
74+
- `451` - Unavailable For Legal Reasons
75+
76+
## Placeholders
77+
78+
Placeholders are named variables that can be used to match path segments in the `from` path and inject them into the `to` path.
79+
80+
For example:
81+
82+
```
83+
/posts/:month/:day/:year/:slug /articles/:year/:month/:day/:slug
84+
```
85+
86+
This rule will redirect a URL like `/posts/06/15/2022/hello-world` to `/articles/2022/06/15/hello-world`.
87+
88+
### Splat
89+
90+
If a `from` path ends with an asterisk (i.e. `*`), the remainder of the `from` path is slurped up into the special `:splat` placeholder, which can then be injected into the `to` path.
91+
92+
For example:
93+
94+
```
95+
/posts/* /articles/:splat
96+
```
97+
98+
This rule will redirect a URL like `/posts/2022/06/15/hello-world` to `/articles/2022/06/15/hello-world`.
99+
100+
Splat logic MUST only apply to a single trailing asterisk, as this is a greedy match, consuming the remainder of the path.
101+
102+
### Comments
103+
104+
Any line beginning with `#` will be treated as a comment and ignored at evaluation time.
105+
106+
For example:
107+
108+
```
109+
# Redirect home to index.html
110+
/home /index.html 301
111+
```
112+
113+
is functionally equivalent to
114+
115+
```
116+
/home /index.html 301
117+
```
118+
119+
### Line Termination
120+
121+
Lines MUST be terminated by either `\n` or `\r\n`.
122+
123+
### Max File Size
124+
125+
The file size MUST NOT exceed 64 KiB.
126+
127+
# Evaluation
128+
129+
## Subdomain or DNSLink Gateways
130+
131+
Rules MUST only be evaluated when hosted on a Subdomain or DNSLink Gateway, so that we have [Same-Origin](https://en.wikipedia.org/wiki/Same-origin_policy) isolation.
132+
133+
## Order
134+
135+
Rules MUST be evaluated in order, redirecting or rewriting using the first matching rule.
136+
137+
## No Forced Redirects
138+
139+
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.
140+
141+
# Error Handling
142+
143+
If the Redirects File exists but there is an error reading or parsing it, the errors MUST be returned to the user with a 500 HTTP status code.
144+
145+
# Security
146+
147+
This functionality will only be evaluated for Subdomain or DNSLink Gateways, to ensure that redirect paths are relative to the root CID hosted at the specified domain name.
148+
149+
Parsing of the `_redirects` file should be done safely to prevent any sort of injection vector or daemon crash.
150+
151+
The [max file size](#max-file-size) helps to prevent an additional [denial of service attack](https://en.wikipedia.org/wiki/Denial-of-service_attack) vector.
152+
153+
# Appendix: notes for implementors
154+
155+
## Test fixtures
156+
157+
Sample files for various test cases can be found in `QmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4`.
158+
Implementations are free to use it for internal testing.
159+
160+
```
161+
$ ipfs ls QmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4
162+
QmcBcFnKKqgpCVMxxGsriw9ByTVF6uDdKDMuEBq3m6f1bm - bad-codes/
163+
QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj - examples/
164+
QmU7ysGXwAtiV7aBarZASJsxKoKyKmd9Xrz2FFamSCbg8S - forced/
165+
QmWHn2TunA1g7gQ7q9rwAoWuot2hMpojZ6cZ9ERsNKm5gE - good-codes/
166+
QmRgpzYQESidTtTojN8zRWjiNs9Cy6o7KHRxh7kDpJm3KH - invalid/
167+
QmYzMrtPyBv7LKiEAGLLRPtvqm3SjQYLWxwWQ2vnpxQwRd - newlines/
168+
QmQTfvjGmvTfxFpUcZNLdTLuKV227KJkGiN6xooHVeVZAS - too-large/
169+
```
170+
171+
For example, the "examples" site can be found in `QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj`.
172+
173+
```
174+
$ ipfs ls /ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj
175+
Qmd9GD7Bauh6N2ZLfNnYS3b7QVAijbud83b8GE8LPMNBBP 7 404.html
176+
QmSmR9NShZ89VEBrn9SBy7Xxvjw8Qe6XArD5GqtHvbtBM3 7 410.html
177+
QmVQqj9oZig9tH3ENHo4bxV5pNgssUwFCXUjAJAVcZVbJG 7 451.html
178+
QmZU3kboiyi9jV59D8Mw8wzuvsr3HmvskqhYRRhdFA8wRq 317 _redirects
179+
QmaWDLb4gnJcJbT1Df5X3j91ysiwkkyxw6329NLiC1KMDR - articles/
180+
QmS6ZNKE9s8fsHoEnArsZXnzMWijKddhXXDsAev8LdTT5z 9 index.html
181+
QmNwEgMrExwSsE8DCjZjahYfHUfkSWRhtqSkQUh4Fk3udD 7 one.html
182+
QmVe2GcTbEPZkMbjVoQ9YieVGKCHmuHMcJ2kbSCzuBKh2s - redirected-splat/
183+
QmUGVnZaofnd5nEDvT2bxcFck7rHyJRbpXkh9znjrJNV92 7 two.html
184+
```
185+
186+
The `_redirects` file is as follows.
187+
188+
```
189+
$ ipfs cat /ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj/_redirects
190+
/redirect-one /one.html
191+
/301-redirect-one /one.html 301
192+
/302-redirect-two /two.html 302
193+
/200-index /index.html 200
194+
/posts/:year/:month/:day/:title /articles/:year/:month/:day/:title 301
195+
/splat/* /redirected-splat/:splat 301
196+
/not-found/* /404.html 404
197+
/gone/* /410.html 410
198+
/unavail/* /451.html 451
199+
/* /index.html 200
200+
```
201+
202+
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.
203+
204+
Any request for an existing file should be returned as is, and not intercepted by the last catch all rule.

‎http-gateways/SUBDOMAIN_GATEWAY.md

+4
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ Summary:
5050
- [DNS label limits](#dns-label-limits)
5151
- [Security considerations](#security-considerations)
5252
- [URI router](#uri-router)
53+
- [Redirects, single-page applications, and custom 404s](#redirects-single-page-applications-and-custom-404s)
5354

5455
# HTTP API
5556

@@ -269,3 +270,6 @@ which in turn should redirect to
269270

270271
From there, regular subdomain gateway logic applies.
271272

273+
## Redirects, single-page applications, and custom 404s
274+
275+
Subdomain Gateway implementations are free to include `_redirects` file support defined in [`REDIRECTS_FILE.md`](./REDIRECTS_FILE.md).

0 commit comments

Comments
 (0)