Merge pull request #442 from ipfs/chore/impoved-descriptions

chore: missing affinity and improved descriptions
ipfs · Oct 12, 2023 · 578ee8a · 578ee8a
2 parents 24861cd + 15e30d3
commit 578ee8a
Show file tree

Hide file tree

Showing 6 changed files with 70 additions and 21 deletions.
diff --git a/src/http-gateways/dnslink-gateway.md b/src/http-gateways/dnslink-gateway.md
@@ -1,16 +1,22 @@
 ---
 title: DNSLink Gateway Specification
 description: >
-  DNSLink Gateways are an extension of Path Gateways that enable hosting a
-  specific content path under a specific DNS name.
+  Defines how to utilize the HTTP Host header to serve a content path from a
+  DNSLink record as a website under a particular DNS name.
 date: 2022-11-09
 maturity: reliable
 editors:
   - name: Marcin Rataj
     github: lidel
     url: https://lidel.org/
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
   - name: Thibault Meunier
     github: thibmeu
+    affiliation:
+      name: Cloudflare
+      url: https://cloudflare.com/
 tags: ['httpGateways', 'webHttpGateways']
 order: 4
 ---

diff --git a/src/http-gateways/libp2p-gateway.md b/src/http-gateways/libp2p-gateway.md
@@ -1,7 +1,7 @@
 ---
 title: libp2p+HTTP Transport Gateway Specification
 description: >
-  The libp2p Transport Gateway specification describes how HTTP Gateway semantics can be used over libp2p transports.
+  Describes how HTTP Gateway semantics can be used over libp2p transports.
 date: 2023-10-04
 maturity: draft
 editors:

diff --git a/src/http-gateways/path-gateway.md b/src/http-gateways/path-gateway.md
@@ -1,24 +1,39 @@
 ---
 title: Path Gateway Specification
 description: >
-  The most versatile form of IPFS Gateway is a Path Gateway. It exposes namespaces, such
-  as /ipfs/ and /ipns/ under an HTTP server root and provides basic primitives for integrating
-  IPFS resources within the existing HTTP stack.
+  The comprehensive low-level HTTP Gateway enables the integration of IPFS
+  resources into the HTTP stack through /ipfs and /ipns namespaces, supporting
+  both deserialized and verifiable response types.
 date: 2023-03-30
 maturity: reliable
 editors:
   - name: Marcin Rataj
     github: lidel
     url: https://lidel.org/
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
   - name: Adrian Lanzafame
     github: lanzafame
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
   - name: Vasco Santos
     github: vasco-santos
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
   - name: Oli Evans
     github: olizilla
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
   - name: Henrique Dias
     github: hacdias
     url: https://hacdias.com/
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
 xref:
   - url
   - trustless-gateway

diff --git a/src/http-gateways/subdomain-gateway.md b/src/http-gateways/subdomain-gateway.md
@@ -1,36 +1,59 @@
 ---
 title: Subdomain Gateway Specification
 description: >
-  Subdomain Gateways are an extension of Path Gateways that enable website hosting
-  isolated per CID/name, while remaining compatible with web browsers relative pathing and
-  the security model of the web.
+  Defines how HTTP Gateway can implement support for HTTP Host headers to
+  enable isolated website hosting based on root CID-derived Origins. This
+  ensures compatibility with native ipfs:// and ipns:// URIs, and aligns with
+  the existing Same-origin security model in web browsers, including
+  relative URL pathing and permission scopes of Web APIs.
 date: 2023-01-28
 maturity: reliable
 editors:
   - name: Marcin Rataj
     github: lidel
     url: https://lidel.org/
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
   - name: Adrian Lanzafame
     github: lanzafame
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
   - name: Vasco Santos
     github: vasco-santos
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
   - name: Oli Evans
     github: olizilla
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
   - name: Thibault Meunier
     github: thibmeu
+    affiliation:
+      name: Cloudflare
+      url: https://cloudflare.com/
   - name: Steve Loeppky
     github: BigLep
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
 xref:
   - url
   - html
 tags: ['httpGateways', 'webHttpGateways']
 order: 3
 ---
 
-Subdomain Gateway is an extension of :cite[path-gateway] that
-enables website hosting isolated per CID/name, while remaining compatible with
-web browsers relative pathing and security model of the web.
-Below should be read as a delta on top of that spec.
+Subdomain Gateways extend :cite[path-gateway] with HTTP [Host](#host-request-header)
+header support. Below should be read as a delta on top of that spec.
+
+This specification enables isolated website hosting based on root CID-derived
+Origins, ensures compatibility with native ipfs:// and ipns:// URIs, and aligns
+with the existing Same-origin security model in web browsers,
+including relative URL pathing and permission scopes of Web APIs.
 
 Summary:
 

diff --git a/src/http-gateways/trustless-gateway.md b/src/http-gateways/trustless-gateway.md
@@ -1,9 +1,9 @@
 ---
 title: Trustless Gateway Specification
 description: >
-  Trustless Gateways are a minimal subset of Path Gateways that allow light IPFS
-  clients to retrieve data behind a CID and verify its integrity without delegating any
-  trust to the gateway itself.
+  The minimal subset of HTTP Gateway response types facilitates data retrieval
+  via CID and ensures integrity verification, all while eliminating the need to
+  trust the gateway itself.
 date: 2023-06-20
 maturity: reliable
 editors:

diff --git a/src/http-gateways/web-redirects-file.md b/src/http-gateways/web-redirects-file.md
@@ -1,30 +1,35 @@
 ---
 title: Web _redirects File Specification
 description: >
-  The Redirects File specification is an extension of the Subdomain Gateway and DNSLink Gateway specifications that
-  enables URL redirects or rewrites by adding redirect rules to a0 file stored underneath the root CID of a web
-  site.
+  Defines how URL redirects and rewrites can be implemented by adding rules to
+  a plain text file stored underneath the root CID of a website.
 date: 2023-01-28
 maturity: reliable
 editors:
   - name: Justin Johnson
     github: justincjohnson
+    affiliation:
+      name: Fission
+      url: https://fission.codes/
   - name: Marcin Rataj
     github: lidel
     url: https://lidel.org/
+    affiliation:
+      name: Protocol Labs
+      url: https://protocol.ai/
 tags: ['httpGateways', 'webHttpGateways']
 order: 5
 ---
 
 The Web Redirects File specification is an extension of the Subdomain Gateway and DNSLink Gateway specifications.
 
-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.
+Developers can enable URL redirects or rewrites by adding redirect rules to a file named `_redirects` stored underneath the root CID of their website.
 
 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.
 
 # File Name and Location
 
-The Redirects File MUST be named `_redirects` and stored underneath the root CID of the web site.
+The Redirects File MUST be named `_redirects` and stored underneath the root CID of the website.
 
 # File Format