ipip-386: editorial fixes

Author: lidel

IPIP/0386-gateway-interop-redirects.md renamed to src/ipips/ipip-0386.md

@@ -1,18 +1,21 @@
-# IPIP-386: Subdomain Gateway interop with _redirects
-
-<!-- IPIP number should  match its pull request number. After you open a PR,
-please update title and include anqabbreviated title in the filename too:
-`0000-draft-title-abbrev.md`. -->
-
-- Start Date: 2023-03-18
-- Related Issues:
-  - IPIP-2 _redirects file
+---
+title: "IPIP-0386: Subdomain Gateway Interop with _redirects"
+date: 2023-03-18
+ipip: proposal
+editors:
+  - name: suicide
+    github: suicide
+relatedIssues:
+  - https://github.com/ipfs/boxo/pull/326
+  - https://github.com/ipfs/boxo/pull/412
+order: 386
+tags: ['ipips']
+---
 
 ## Summary
 
-<!--One paragraph explanation of the IPIP.-->
-This IPIP suggests a tweak in the Path and Subdomain Gateway interop to
-leverage the `_redirects` file.
+This IPIP clarifies the Path and Subdomain Gateway interop to
+ensure features like `_redirects` file work correctly.
 
 ## Motivation
 
@@ -22,7 +25,7 @@ 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 [`REDIRECTS_FILE.md`](../REDIRECTS_FILE.md),
+The `_redirects` file, defined in :cite[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.
@@ -33,7 +36,7 @@ For example:
 - `http://{gateway}/ipns/example.org/some/path`
 - this request fails with 404 as the resource `/some/path` does not exist.
 
-NOTE: The `kubo` gateway returns a 404 including a new `Location` header
+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.
@@ -73,7 +76,7 @@ not found in the directory identified by the CID or DNSLink name.
 
 ## Test fixtures
 
-The example from the [REDIRECTS_FILE.md](../REDIRECTS_FILE.md) can be re-used,
+The example from the :cite[web-redirects-file] can be re-used,
 `QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj`.
 
 ```
@@ -115,14 +118,14 @@ $ curl -v http://{gateway}/ipfs/QmYBhLYDwVFvxos9h8CGU2ibaY66QNgv8hpfewxaQrPiZj/r
 ...
 ```
 
-Subsequent requests should comply with IPIP-2.
+Subsequent requests should comply with :cite[ipip-0002].
 
 ## Design rationale
 
-Gateways like `kubo` already support the suggested redirect but block the
-redirect chain by returning a 404 when a resource is not found on the Path
-Gateway. By removing the 404, users get another chance to find the resources
-they are looking for.
+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.
 
 ### User benefit
 
@@ -134,15 +137,17 @@ compatibility.
 
 ### Compatibility
 
-This proposal improves the reach of `_redirects` files.
+This proposal fixes a bug in handling of `_redirects` files.
 
-The current behavior is defined in [PATH_GATEWAY.md](../PATH_GATEWAY.md). The
+The current behavior is defined in :cite[path-gateway]. The
 404 return code indicates that a resource does not exist. Changing this to a
 301 redirect that is subsequently answered with a 404 from the subdomain URL
-might break clients.
+is a breaking change, but the old behavior should be considered as a bug.
+
+Requesting an existing resource on the Path Gateway URL in `kubo` already
+returns a 301 redirect: client expectation is for the behavior to be the same
+for invalid paths.
 
-However, requesting an existing resource on the Path Gateway URL in `kubo`
-already returns a 301 redirect while also providing the content in the body.
 
 ### Security
 
@@ -154,7 +159,8 @@ security due to host separation.
 
 Gateways could continue to return a 404 response for the non-existing resource,
 but also include an HTML body containing a redirect link. This would help users
-to find the requested site.
+to find the requested site, but comes with worse UX than the fix proposed in
+this IPIP.
 
 ### Copyright