From 11b53bc055fb0c89d4d17972f439e89b1b0ab83b Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Wed, 7 Sep 2022 11:48:02 -0400 Subject: [PATCH] Very rough draft --- .../websites-on-ipfs/gateway-redirects.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/how-to/websites-on-ipfs/gateway-redirects.md diff --git a/docs/how-to/websites-on-ipfs/gateway-redirects.md b/docs/how-to/websites-on-ipfs/gateway-redirects.md new file mode 100644 index 000000000..3423e2098 --- /dev/null +++ b/docs/how-to/websites-on-ipfs/gateway-redirects.md @@ -0,0 +1,91 @@ +--- +title: Gateway redirects +description: What gateway redirects are and how to use them with a website on IPFS. +--- + +# THIS IS A DRAFT. DO NOT MERGE. + +# To do: +1. How to redirect old URL to a new place (301 and 302 redirects) +1. How to use it for PWA/SPA hosting (catch-all 200) +1. How to use it to provide custom `404 not found` pages (superceding what `ipfs-404.html` does - ideally not mention old way) + +# Gateway Redirects + +Gateway Redirects provide support for URL redirects and rewrites for websites hosted on Subdomain or DNSLink gateways. This feature enables support for single-page applications, and avoids link rot when moving to IPFS-backed hosting. + +Using Gateway Redirects, you can change the appearance of a URL, change where content is located without breaking existing links, redirect invalid URLs to a custom 404 page, and enable URL rewriting. + +# Supported HTTP status codes + +* `200` - OK (redirect will be treated as a rewrite, returning OK without changing the URL shown in the browser). +* `301` - Permanent redirect (the default status). +* `302` - Found (commonly used for temporary redirects). +* `303` - See other (replaces PUT and POST with GET). +* `307` - Temporary redirect (preserves the body and HTTP method of the original request). +* `308` - Permanent redirect (preserves the body and HTTP method of the original request). +* `404` - Not found (can be used redirect to custom 404 pages). +* `410` - Gone (the requested content has been permanently removed). +* `451` - Unavailable for legal reasons. + +# How to set up gateway redirects + +To use Gateway Redirects, there must be a file named `_redirects` stored underneath the root CID of the website. This `_redirects` file must be a text file containing one or more lines that follow the format explained below. + +## Format of the `_redirects` file + +Each line contained within the `_redirects` file has 3 basic components: + +1. The `from` path, this specifies the path to be redirected from. +1. The `to` path, this specifies the path to be redirected to. +1. The `status` component, this part is optional and specifies the HTTP status code that will be returned. (301, 404, etc.) + +For example, if I want to redirect a page to a custom `404` page, the `_redirects` file will contain a line that looks something like this: +``` +/ /custom404.html 404 +``` + +The same format is used for all redirects. + +## 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, if I wanted to search for an article titled "hello world" that was written on June 15, 2022, I could search for it like this: `/posts/06/15/2022/hello-world` and be redirected to `/articles/2022/06/15/hello-world` + +## Splat + +If the `from` path ends with an asterisk (`*`), the rest of the `from` path will be slurped up into the special `:splat` placeholder, which can then be injected into the `to` path. +``` +/posts/* /articles/:splat +``` +:::note +Splat logic must only apply to a single trailing asterisk, as it is a greedy match that consumes the remainder of the path. ::: + +## Comments + +Any line in the `_redirects` file that begins with `#` will be ignored and treated as a comment. + +## Line termination + +Each line in the `_redirects` file must be terminated with either `\n` or `\r\n`. + +``` +/ /custom404.html 404 \n +/home /index.html \n +``` +# Evaluation + +Rules must only be evaluated when hosted on a subdomain or DNSLink gateway, this is to maintain same-origin isolation. + +## Order + +Rules must be evaluated in order, redirecting or rewriting using the first matching pair. + +## No forced redirects + +Redirect logic will only be evaluated if the requested path is not in the DAG. 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. + +# Error handling + +If there are any errors reading or parsing the `_redirects` file, the error codes will be returned with an HTTP 500 status code. \ No newline at end of file