Merge branch 'main' into ipip-car-order-signaling

.github/workflows/stale.yml

@@ -2,25 +2,12 @@ name: Close and mark stale issue
 
 on:
   schedule:
-  - cron: '0 0 * * *'
+    - cron: '0 0 * * *'
+
+permissions:
+  issues: write
+  pull-requests: write
 
 jobs:
   stale:
-
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      pull-requests: write
-
-    steps:
-    - uses: actions/stale@v3
-      with:
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-        stale-issue-message: 'Oops, seems like we needed more information for this issue, please comment with more details or this issue will be closed in 7 days.'
-        close-issue-message: 'This issue was closed because it is missing author input.'
-        stale-issue-label: 'kind/stale'
-        any-of-labels: 'need/author-input'
-        exempt-issue-labels: 'need/triage,need/community-input,need/maintainer-input,need/maintainers-input,need/analysis,status/blocked,status/in-progress,status/ready,status/deferred,status/inactive'
-        days-before-issue-stale: 6
-        days-before-issue-close: 7
-        enable-statistics: true
+    uses: pl-strflt/.github/.github/workflows/reusable-stale-issue.yml@v0.3

Makefile

@@ -1,4 +1,4 @@
-SPEC_GENERATOR_VER=v1.3.1
+SPEC_GENERATOR_VER=v1.3.2
 
 all: website
 

README.md

@@ -34,8 +34,8 @@ Nothing in this spec repository is `permanent` or even `stable` yet. Most of the
 The specs contained in this and related repositories are:
 
 - **IPFS Protocol:**
+  - [IPFS Guide](https://docs.ipfs.tech/) - to start your IPFS journey
   - [Protocol Architecture Overview](./ARCHITECTURE.md) - the top-level spec and the stack
-  - [Other IPFS Overviews](/overviews) - quick overviews of the various parts of IPFS
 - **User Interface (aka Public APIs):**
   - [HTTP Gateways](./http-gateways/) - implementation agnostic interfaces for accessing content-addressed data over HTTP
   - IPFS implementations may provide additional interfaces, for example:

src/http-gateways/dnslink-gateway.md

@@ -92,5 +92,5 @@ Same as "HTTP Response" of :cite[path-gateway].
 
 ## Redirects, single-page applications, and custom 404s
 
-DNSLink Gateway implementations are free to include `_redirects` file support
+DNSLink Gateway implementations SHOULD include `_redirects` file support
 defined in :cite[web-redirects-file].

src/http-gateways/path-gateway.md

@@ -53,7 +53,7 @@ Downloads data at specified **immutable** content path.
 
 Same as GET, but does not return any payload.
 
-Implementations are free to limit the scope of IPFS data transfer triggered by
+Implementations SHOULD limit the scope of IPFS data transfer triggered by
 `HEAD` requests to a minimal DAG subset required for producing response headers
 such as
 [`X-Ipfs-Roots`](#x-ipfs-roots-response-header),
@@ -120,7 +120,7 @@ fetch, a [`412 Precondition Failed`](#412-precondition-failed) HTTP status code
 should be returned by the gateway without any payload or specific HTTP headers.
 
 NOTE: when processing a request for a DAG, traversing it and checking every CID
-might be too expensive. Implementations are free to implement own heuristics to
+might be too expensive. Implementations SHOULD implement own heuristics to
 maximize cache hits while minimizing performance cost of checking if the entire
 DAG is locally cached. A good rule of thumb is to at the minimum test if the root
 block is in the local cache.
@@ -138,7 +138,7 @@ For example:
 - [application/vnd.ipld.dag-cbor](https://www.iana.org/assignments/media-types/application/vnd.ipld.dag-cbor) – requests [IPLD Data Model](https://ipld.io/docs/data-model/) representation serialized into [DAG-CBOR format](https://ipld.io/docs/codecs/known/dag-cbor/). If the requested CID already has `dag-cbor` (0x71) codec,  data is validated as DAG-CBOR before being returned as-is. Invalid DAG-CBON produces HTTP Error 500.
 - [application/json](https://www.iana.org/assignments/media-types/application/json) – same as `application/vnd.ipld.dag-json`, unless the CID's codec already is `json` (0x0200). Then, the raw JSON block can be returned as-is without any conversion.
 - [application/cbor](https://www.iana.org/assignments/media-types/application/cbor) – same as `application/vnd.ipld.dag-cbor`, unless the CID's codec already is `cbor` (0x51). Then, the raw CBOR block can be returned as-is without any conversion.
-- [application/vnd.ipfs.ipns-record](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) – requests a verifiable [IPNS Record](../ipns/IPNS.md#ipns-record) to be returned. Produces 400 Bad Request if the content is not under the IPNS namespace, or contains a path.
+- [application/vnd.ipfs.ipns-record](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) – requests a verifiable :cite[ipns-record] to be returned. Produces 400 Bad Request if the content is not under the IPNS namespace, or contains a path.
 
 ### `Range` (request header)
 
@@ -354,10 +354,10 @@ Returned directive depends on requested content path and format:
   resources under `/ipns/{id-with-ttl}/` namespace; `max-age=<ttl>` should
   indicate remaining TTL of the mutable pointer such as IPNS record or DNSLink
   TXT record.
-  - Implementations are free to place an upper bound on any TTL received, as
-    noted in Section 8 of :cite[rfc2131].
-  - If TTL value is unknown, implementations are free to set it to a static
-    value, but it should not be lower than 60 seconds.
+  - Implementations MAY place an upper bound on any TTL received, as
+    noted in Section 8 of :cite[rfc2181].
+  - If TTL value is unknown, implementations SHOULD set it to a static
+    value, but it SHOULD not be lower than 60 seconds.
 
 ### `Last-Modified` (response header)
 
@@ -389,9 +389,10 @@ Returned with custom response formats such as `application/vnd.ipld.car` or
 `application/vnd.ipld.raw`. CAR must be returned with explicit version.
 Example: `Content-Type: application/vnd.ipld.car; version=1`
 
-When no explicit response format is provided with the request, and the
+When deserialized responses are enabled,
+and no explicit response format is provided with the request, and the
 requested data itself has no built-in content type metadata, implementations
-are free to perform content type sniffing based on file name
+SHOULD perform content type sniffing based on file name
 (from :ref[url] path, or optional [`filename`](#filename-request-query-parameter) parameter)
 and magic bytes to improve the utility of produced responses.
 
@@ -538,12 +539,27 @@ Optional, present in certain response types:
   non-executable binary response types are not used in `<script>` and `<style>`
   HTML tags.
 
-### `X-Trace-Id` (response header)
+### `Server-Timing` (response header)
 
-Optional. Implementations are free to use this header to return a globally
+Optional. Implementations MAY use this header to communicate one or more
+metrics and descriptions for the given request-response cycle.
+
+See `Server-Timing` at [W3C: Server Timing](https://www.w3.org/TR/server-timing/#the-server-timing-header-field).
+
+### `Traceparent` (response header)
+
+Optional. Implementations MAY use this header to return a globally
 unique identifier to help in debugging errors and performance issues.
 
-A good practice is to always return it with HTTP error [status codes](#response-status-codes) >=`400`.
+See `Traceparent` at [W3C: Trace Context](https://www.w3.org/TR/trace-context-1/#traceparent-header).
+
+### `Tracestate` (response header)
+
+Optional. Implementations MAY use this header to return a additional
+vendor-specific trace identification information across different distributed
+tracing systems and is a companion header for the `Traceparent` header.
+
+See `Tracestate` at [W3C: Trace Context](https://www.w3.org/TR/trace-context-1/#tracestate-header).
 
 ## Response Payload
 
@@ -669,7 +685,7 @@ Gateway MUST respond with HTTP error when requested CID is on any of active deny
 - [410 Gone](#410-gone) returned when CID is denied for non-legal reasons, or when the exact reason is unknown
 - [451 Unavailable For Legal Reasons](#451-unavailable-for-legal-reasons) returned when denylist indicates that content was blocked on legal basis
 
-Implementation is free to apply some denylists by default as long the gateway
+Gateway implementation MAY apply some denylists by default as long the gateway
 operator is able to inspect and modify the list of denylists that are applied.
 
 **Examples of public deny lists**
@@ -681,7 +697,7 @@ operator is able to inspect and modify the list of denylists that are applied.
 
 ## Generated HTML with directory index
 
-While implementations are free to decide on the way HTML directory listing is
+While implementations decide on the way HTML directory listing is
 generated and presented to the user, following below suggestions is advised.
 
 Linking to alternative response types such as CAR and dag-json allows clients

src/http-gateways/subdomain-gateway.md

@@ -257,5 +257,5 @@ From there, regular subdomain gateway logic applies.
 
 ## Redirects, single-page applications, and custom 404s
 
-Subdomain Gateway implementations are free to include `_redirects` file
-support defined in :cite[web-redirects-file].
+Subdomain Gateway implementations SHOULD include `_redirects` file
+support defined in :cite[web-redirects-file].

src/http-gateways/trustless-gateway.md

@@ -57,15 +57,16 @@ Same as in :cite[path-gateway], but with limited number of supported response ty
 
 This HTTP header is required when running in a strict, trustless mode.
 
-Gateway is free to return HTTP 400 Bad Request when running in strict trustless
-mode and  `Accept` header is missing
-
 Below response types MUST to be supported:
-
 - [application/vnd.ipld.raw](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw) – requests a single, verifiable raw block to be returned
+
+Below response types SHOULD to be supported:
 - [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) – disables IPLD/IPFS deserialization, requests a verifiable CAR stream to be returned, implementations MAY support optional parameters (:cite[ipip-0412])
 - [application/vnd.ipfs.ipns-record](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) – requests a verifiable :cite[ipns-record] (multicodec `0x0300`).
 
+Gateway SHOULD return HTTP 400 Bad Request when running in strict trustless
+mode (no deserialized responses) and  `Accept` header is missing.
+
 # HTTP Response
 
 Below MUST be implemented **in addition** to "HTTP Response" of :cite[path-gateway].

src/http-gateways/web-redirects-file.md

@@ -140,7 +140,7 @@ The [max file size](#max-file-size) helps to prevent an additional [denial of se
 ## Test fixtures
 
 Sample files for various test cases can be found in `QmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4`.
-Implementations are free to use it for internal testing.
+Implementations SHOULD use it for internal testing.
 
 ```
 $ ipfs ls QmQyqMY5vUBSbSxyitJqthgwZunCQjDVtNd8ggVCxzuPQ4

src/ipips/ipip-0337.md

@@ -70,7 +70,7 @@ To understand the design rationale, it is important to consider the concrete Ref
 So this API proposal makes the following changes:
 
 - The Delegated Content Routing API is defined using HTTP semantics, and can be implemented without introducing Reframe concepts nor IPLD
-- There is a clear distinction between the RPC protocol (HTTP) and the API (Deleged Content Routing)
+- There is a clear distinction between the [Kubo RPC](https://docs.ipfs.tech/reference/kubo/rpc/)  and the vendor-agnostic Routing V1 HTTP API.
 - "Method names" and cache-relevant parameters are pushed into the URL path
 - Streaming support is removed, and default response size limits are added.
   - We will add streaming support in a subsequent IPIP, but we are trying to minimize the scope of this IPIP to what is immediately useful
@@ -80,7 +80,7 @@ So this API proposal makes the following changes:
   - Multiaddrs use the [human-readable format](https://github.com/multiformats/multiaddr#specification) that is used in existing tools and Kubo CLI commands such as `ipfs id` or `ipfs swarm peers`
   - Byte array values, such as signatures, are multibase-encoded strings (with an `m` prefix indicating Base64)
 - The "Identify" method and "message groups" are not included
-- The "GetIPNS" and "PutIPNS" methods are not included
+- The "GetIPNS" and "PutIPNS" methods are not included. Instead, a separate Delegated IPNS HTTP API aims to firstly facilitate naming system delegation, and secondly, pave the way for future iterations of IPNS with less interdependency with content routing. For more information, see Delegated IPNS HTTP API (:cite[ipip-0379]).
 
 ### User benefit
 

src/ipips/ipip-0379.md

@@ -0,0 +1,89 @@
+---
+title: "IPIP-0379: Delegated IPNS HTTP API"
+date: 2023-02-13
+ipip: ratified
+editors:
+  - name: Masih H. Derkani
+    github: masih
+  - name: Marcin Rataj
+    github: lidel
+    url: https://lidel.org/
+relatedIssues:
+  - https://github.com/ipfs/specs/issues/343
+  - https://github.com/ipfs/specs/pull/337
+  - https://github.com/ipfs/specs/pull/377
+xref:
+  - ipns-record
+order: 379
+tags: ['ipips']
+---
+
+## Summary
+
+This IPIP specifies `/routing/v1/ipns` HTTP API to offload naming system onto another process or server.
+
+## Motivation
+
+One of the motivations of this document is to introduce simple to use HTTP APIs and ultimately reduce barrier for interaction across alternative systems.
+
+Expanding on the motivations of :cite[ipip-0337], the work here concentrates on delegation of IPNS over HTTP API. Naming is part of the core IPFS DHT functionality.
+The performance of naming system over the IPFS DHT can suffer from long delays due to churn of records and quorum requirements.
+
+## Detailed design
+
+Add `/routing/v1/ipns` to the existing :cite[http-routing-v1] specification.
+
+## Design rationale
+
+The rationale for delegated IPNS over HTTP APIs closely follows the reasoning listed in :cite[ipip-0337].
+
+The document proposes the following:
+- HTTP `GET` and `PUT` semantics for publication and resolution of IPNS records.
+- Use of existing :ref[IPNS Record] serialization format as HTTP `Content-Type` [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record).
+
+### User benefit
+
+The ability to offload naming to another process or server using a simple HTTP
+API brings several benefits:
+
+- It reduces the resource drain on light clients such as JavaScript running on
+  a web page, mobile devices, IoT devices, and gateway HTTP services.
+- It enables scaling of IPNS resolution separately from retrieval and
+  deserialization/verification services.
+- Expands the utility of IPNS beyond IPFS nodes, contributes to its broader
+  adoption and impact by reducing integration costs.
+
+### Compatibility
+
+See the "Compatibility" section of :cite[ipip-0337].
+
+#### Serialization Format
+
+Standard IPNS record serialization format is used, making it fully compatible with the existing IPNS ecosystem.
+
+:cite[ipns-record] uses [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) protobuf serialization format.
+This format is widely in use in IPNS over PubSub and DHT routing systems.
+Further, interoperability across the existing and HTTP APIs is also desirable in order to reduce the barrier for adoption of the delegated HTTP APIs.
+
+To maximize interoperability with existing ecosystem, the canonical IPNS record serialization format :cite[ipns-record] (`0x0300`) can be requested with content type `application/vnd.ipfs.ipns-record`.
+
+### Security
+
+All interaction over the APIs should use TLS to protect against third-party observation and tampering.
+Additionally, the IPNS records must be validated according to the rules stated in :cite[ipns-record] before further processing.
+
+To avoid Denial of Service attack, maximum IPNS record size defined in :cite[ipns-record] applies.
+
+Privacy in delegated IPNS is out of scope for this IPIP.
+
+### Alternatives
+
+See:
+- IPNS over (libp2p over HTTP). While it may be possible in the future, it has more narrow utility and way bigger implementation complexity than libp2p-agnostic HTTP API  with protobuf GET/PUT.
+- Reframe; it was deprecated and now removed. Historical reasons can be found in :cite[ipip-0337].
+- JSON IPNS Record representation was descoped due to open question how signing should work and unclear use case ([discussion](https://github.com/ipfs/specs/pull/379#discussion_r1107898543)).
+- API-specific max record size was descoped, as it would introduce interop problems harmful to the IPNS ecosystem.
+
+### Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).