From 6d49dfbf9874d0d47b11b308c893a9505bf3d3b4 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 31 May 2023 19:53:43 +0200 Subject: [PATCH] chore(ipip-379): final editorials --- src/ipips/ipip-0379.md | 37 ++++++++++++++++++++++------------ src/routing/http-routing-v1.md | 23 ++++++++++++--------- 2 files changed, 38 insertions(+), 22 deletions(-) diff --git a/src/ipips/ipip-0379.md b/src/ipips/ipip-0379.md index 7cd83d59f..6cc550f31 100644 --- a/src/ipips/ipip-0379.md +++ b/src/ipips/ipip-0379.md @@ -20,39 +20,49 @@ tags: ['ipips'] ## Summary -This IPIP specifies a set of HTTP APIs to offload naming system onto another process or server. +This IPIP specifies `/routing/v1/ipns` HTTP API to offload naming system onto another process or server. ## Motivation -Expanding on the motivations of :cite[ipip-0337], the work here concentrates on delegation of _naming system_ over HTTP APIs. Naming is part of the core IPFS DHT functionality. +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 -See :cite[http-routing-v1] specification. +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: -- Use of HTTP semantics for publication and resolution of naming records. -- Use of existing :ref[IPNS Record] serialization format through `Content-Type: application/vnd.ipfs.ipns-record`. -- Streaming interaction is not supported. +- 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 of offload naming onto another process or server via an idiomatic and simple HTTP API opens up an opportunity to not only reduce the burden of naming system management, but also introduce alternative naming systems across other routing systems, namely IPNI. +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 "Compatibility" section of :cite[ipip-0337]. +See the "Compatibility" section of :cite[ipip-0337]. #### Serialization Format -:cite[ipns-record] uses `application/vnd.ipfs.ipns-record` protobuf 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. -One of the motivations of this document is to introduce simple to use HTTP APIs and ultimately reduce barrier for interaction across alternative 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`. @@ -64,14 +74,15 @@ Additionally, the IPNS records must be validated according to the rules stated i 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 work. +Privacy in delegated IPNS is out of scope for this IPIP. ### Alternatives See: - -- [Libp2p-based IPNS](https://github.com/ipfs/go-ipns). +- 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 diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index 747711225..5e6e9e412 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -67,11 +67,7 @@ Where: Specifications for some transfer protocols are provided in the "Transfer Protocols" section. -### IPNS Records - -:ref[IPNS Records] are serialized using the verifiable [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) format. For more details, read the specification :cite[ipns-record]. - -## API +## Content Providers API ### `GET /routing/v1/providers/{cid}` @@ -103,35 +99,44 @@ Response limit: 100 providers Each object in the `Providers` list is a *read provider record*. +## IPNS API + ### `GET /routing/v1/ipns/{name}` #### Path Parameters -- `name` is the :ref[IPNS Name] to resolve. +- `name` is the :ref[IPNS Name] to resolve, encoded as CIDv1. #### Response Status Codes - `200` (OK): the response body contains the :ref[IPNS Record] for the given :ref[IPNS Name]. - `404` (Not Found): must be returned if no matching records are found. +- `406` (Not Acceptable): requested content type is missing or not supported. Error message returned in body should inform the user to retry with `Accept: application/vnd.ipfs.ipns-record`. + +#### Response Headers + +- `Etag`: a globally unique opaque string used for HTTP caching. MUST be derived from the protobuf record returned in the body. +- `Cache-Control: max-age={TTL}`: cache TTL returned with :ref[IPNS Record] that has `IpnsEntry.data[TTL] > 0`. When present, SHOULD match the TTL value from the record. When record was not found (HTTP 404) or has no TTL (value is `0`), implementation SHOULD default to `max-age=60`. #### Response Body -The response body contains a [`application/vnd.ipfs.ipns-record`][application/vnd.ipfs.ipns-record] serialized :ref[IPNS Record]. +The response body contains a :ref[IPNS Record] serialized using the verifiable [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) protobuf format. ### `PUT /routing/v1/ipns/{name}` #### Path Parameters -- `name` is the :ref[IPNS Name] to publish. +- `name` is the :ref[IPNS Name] to publish, encoded as CIDv1. #### Request Body -The content body must be a [`application/vnd.ipfs.ipns-record`][application/vnd.ipfs.ipns-record] serialized :ref[IPNS Record], which matches the `name` path parameter. +The content body must be a [`application/vnd.ipfs.ipns-record`][application/vnd.ipfs.ipns-record] serialized :ref[IPNS Record], with a valid signature matching the `name` path parameter. #### Response Status Codes - `200` (OK): the provided :ref[IPNS Record] was published. - `400` (Bad Request): the provided :ref[IPNS Record] or :ref[IPNS Name] are not valid. +- `406` (Not Acceptable): submitted content type is not supported. Error message returned in body should inform the user to retry with `Content-Type: application/vnd.ipfs.ipns-record`. ## Pagination