Skip to content

Commit f8ed3e6

Browse files
masihhacdias
masih
authored and
hacdias
committed
IPIP-379 Delegated Naming HTTP API
Propose HTTP APIs for delegated naming system that enables offloading of naming system to other processes or servers. Relates to: - #377 Fixes #343
1 parent cd5f4e6 commit f8ed3e6

File tree

3 files changed

+274
-2
lines changed

3 files changed

+274
-2
lines changed

‎src/ipips/ipip-0337.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ To understand the design rationale, it is important to consider the concrete Ref
7070
So this API proposal makes the following changes:
7171

7272
- The Delegated Content Routing API is defined using HTTP semantics, and can be implemented without introducing Reframe concepts nor IPLD
73-
- There is a clear distinction between the RPC protocol (HTTP) and the API (Deleged Content Routing)
73+
- There is a clear distinction between the RPC protocol (HTTP) and the API (Delegated Content Routing)
7474
- "Method names" and cache-relevant parameters are pushed into the URL path
7575
- Streaming support is removed, and default response size limits are added.
7676
- 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:
8080
- 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`
8181
- Byte array values, such as signatures, are multibase-encoded strings (with an `m` prefix indicating Base64)
8282
- The "Identify" method and "message groups" are not included
83-
- The "GetIPNS" and "PutIPNS" methods are not included
83+
- 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]).
8484

8585
### User benefit
8686

‎src/ipips/ipip-0379.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: "IPIP-379: Delegated IPNS HTTP API"
3+
date: 2023-02-13
4+
ipip: proposal
5+
editors:
6+
- name: Masih H. Derkani
7+
github: masih
8+
- name: Marcin Rataj
9+
github: lidel
10+
url: https://lidel.org/
11+
relatedIssues:
12+
- https://github.com/ipfs/specs/issues/343
13+
- https://github.com/ipfs/specs/pull/337
14+
- https://github.com/ipfs/specs/pull/377
15+
order: 379
16+
tags: ['ipips']
17+
---
18+
19+
- Start Date: 2023-02-13
20+
- Related Issues:
21+
22+
## Summary
23+
24+
This IPIP specifies a set of HTTP APIs to offload naming system onto another process or server.
25+
26+
## Motivation
27+
28+
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.
29+
The performance of naming system over the IPFS DHT can suffer from long delays due to churn of records and quorum requirements.
30+
31+
## HTTP API Specification
32+
33+
See :cite[http-ipns-routing] specification.
34+
35+
## Design rationale
36+
37+
The rationale for delegated IPNS over HTTP APIs closely follows the reasoning listed in :cite[ipip-0337].
38+
39+
The document proposes the following:
40+
- Use of HTTP semantics for publication and resolution of naming records.
41+
- Preference for human-readable request and response encoding, such as JSON format
42+
- Optional backward compatibility support for the existing ProtocolBuffer format using `Content-Type: application/vnd.ipfs.ipns-record`
43+
- Use of extra headers in `OPTIONS` response to communicate the supported capabilities and limitations, namely:
44+
- `X-Ipns-Allow-Max-Size` -- to signal maximum supported IPNS record size
45+
- `X-Ipns-Allow-Protobuf` -- to signal whether the server supports ProtocolBuffer formatted records.
46+
- Streaming interaction is not supported.
47+
48+
### User benefit
49+
50+
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.
51+
52+
### Compatibility
53+
54+
#### Backwards Compatibility
55+
56+
##### Serialization Format
57+
58+
:cite[ipns-record] use ProtocolBuffer serialisation format.
59+
This format is widely in use in IPNS over PubSub and DHT routing systems.
60+
One of the motivations of this document is to introduce simple to use HTTP APIs and ultimately reduce barrier for interaction across alternative systems.
61+
Further, interoperability across the existing and HTTP APIs is also desirable in order to reduce the barrier for adoption of the delegated HTTP APIs.
62+
63+
The specification here maintains backwards compatibility in terms of record serialisation, with preference for human-readable formats such as JSON.
64+
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`.
65+
66+
##### Reframe
67+
68+
See "Backwards Compatibility" section of :cite[ipip-0337].
69+
70+
#### Forwards Compatibility
71+
72+
See "Forwards Compatibility" section of :cite[ipip-0337].
73+
74+
### Security
75+
76+
All interaction over the APIs should use TLS to protect against third-party observation and tampering.
77+
Additionally, the IPNS records are signed by the publisher's identity and contain sequence number to avoid replay attacks.
78+
79+
To avoid Denial of Service attack, maximum IPNS record size of `10 KiB` applies.
80+
Implements are permitted to set a lower limit. If lower than the default maximum, the limit should be discoverable via `OPTIONS` request with header key `X-Ipns-Allow-Max-Size` with value specified as the number of bytes.
81+
82+
Similarly, a client may check if a server supports ProtocolBuffer formatted records by checking the `X-Ipns-Allow-Protobuf` header key in response to `OPTIONS` request. If present the header value must be either `true` or `false` the absence of the header indicates that ProtocolBuffer formatted records are not supported.
83+
84+
Privacy in delegated IPNS is out of scope for this work.
85+
- The usual JSON parsing rules apply. To prevent potential Denial of Service (DoS) attack, clients should ignore responses larger than 100 providers and introduce a byte size limit that is applicable to their use case.
86+
87+
### Alternatives
88+
89+
See:
90+
- [Libp2p-based IPNS](https://github.com/ipfs/go-ipns).
91+
- Reframe; find out more on "Design Rationale" section of :cite[ipip-0337].
92+
93+
### Copyright
94+
95+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

‎src/routing/http-ipns-routing.md

+177
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
title: Delegated IPNS HTTP API
3+
description: >
4+
Delegated IPNS is a mechanism for IPFS implementations to offload naming system to another process
5+
or server. This includes naming resolution as well as publication of new naming records. This
6+
document describes an HTTP API through which such functionality is facilitated.
7+
date: 2023-03-22
8+
maturity: wip
9+
editors:
10+
- name: Masih H. Derkani
11+
github: masih
12+
order: 0
13+
tags: ['routing']
14+
---
15+
16+
Delegated IPNS is a mechanism for IPFS implementations to offload naming system to another process
17+
or server. This includes naming resolution as well as publication of new naming records. This
18+
document describes an HTTP API through which such functionality is facilitated.
19+
20+
## API Specification
21+
22+
The Delegated IPNS HTTP API uses the `application/json` content type by default.
23+
24+
As such, human-readable encodings of types are preferred. This spec may be updated in the future
25+
with a compact `application/cbor` encoding, in which case compact encodings of the various types
26+
would be used.
27+
28+
## Common Data Types
29+
30+
### IPNS Record
31+
32+
The following snippet outlines the JSON schema of IPNS records:
33+
34+
```json
35+
{
36+
"Signature": "<signature>",
37+
"Payload": {
38+
"Value": "<value>",
39+
"Sequence": 0,
40+
"Validity": {
41+
"EOL": {
42+
"Timestamp": 0,
43+
"AdvisoryTTL": 0
44+
}
45+
},
46+
"PublicKey": "<optional-public-key>",
47+
"ExtendedData": {}
48+
}
49+
}
50+
```
51+
52+
Where:
53+
54+
- `Signature` is the multibase-encoded signature of the sha256 hash of the `Payload` field, signed
55+
using the private key that corresponds to the `PublicKey` in the `Payload` if present. And
56+
Otherwise, the private key associcated to the IPNS record key. Signing details for specific key
57+
types should
58+
follow [libp2p/peerid specs](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#key-types),
59+
unless stated otherwise.
60+
- `Payload` is the content of the IPNS record as specified
61+
by :cite[ipns-record] specification:
62+
- `Value` is the string representation of the IPNS path,
63+
e.g. `ipns/{ipns-key}`, `/ipns/example.com`, `/ipfs/baf...`, etc.
64+
- `Sequence` represents the current version of the record starting from `0`.
65+
- `Validity` captures the mechanism by which the record is validated. Each validity type reserves a
66+
field key under this object.
67+
- `EOL` donates that the validity type is EOL, containing:
68+
- `Timestamp` represents the time in the future at which the record expires with nanoseconds
69+
precision represented as an ASCII string that follows notation
70+
from :cite[rfc3339].
71+
- `AdvisoryTTL` represents an optional field that hints at how long the record should be
72+
cached.
73+
- `PublicKey` represents the optional public key used to sign the record. This field is only
74+
required if it cannot be extracted from the IPNS name, e.g. in the case of legacy RSA keys.
75+
- `ExtendedData` represents the extensible data as arbitrary JSON object.
76+
77+
## Versioning
78+
79+
The path predix `/v1` donates the version number of the HTTP API. Backwards-incompatible change must
80+
increment the version number.
81+
82+
## API
83+
84+
### `GET /naming/v1/records/{ipns-name}`
85+
86+
**Path Parameters**
87+
88+
- `ipns-name` the IPNS name to resolve.
89+
90+
**Response Status Codes**
91+
92+
- `200` (OK): indicates that the response body containing the IPNS record that corresponds to the
93+
IPNS name.
94+
- `404` (Not Found): indicates that no matching records are found.
95+
- `400` (Bad Request): indicates that the given IPNS name is not valid.
96+
- `429` (Too Many Requests): indicates that the caller is issuing requests too many request and may
97+
retry after the time specified
98+
at [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) response
99+
header has elapsed.
100+
- `501` (Not Implemented): indicates that the server does not support resolution of IPNS records
101+
102+
**Response Body**
103+
104+
The response body contains the [IPNS record](#ipns-record).
105+
106+
```json
107+
{
108+
"Signature": "<signature>",
109+
"Payload": {
110+
"Value": "<value>",
111+
"Sequence": 0,
112+
"Validity": {
113+
"EOL": {
114+
"Timestamp": 0,
115+
"AdvisoryTTL": 0
116+
}
117+
},
118+
"PublicKey": "<optional-public-key>",
119+
"ExtendedData": {}
120+
}
121+
}
122+
```
123+
124+
### `PUT /naming/v1/records/{ipns-name}`
125+
126+
**Path Parameters**
127+
128+
- `ipns-name` the IPNS name to publish. The name must match `Value` in request body.
129+
130+
**Request Body**
131+
132+
```json
133+
{
134+
"Signature": "<signature>",
135+
"Payload": {
136+
"Value": "<value>",
137+
"Sequence": 0,
138+
"Validity": {
139+
"EOL": {
140+
"Timestamp": 0,
141+
"AdvisoryTTL": 0
142+
}
143+
},
144+
"PublicKey": "<optional-public-key>",
145+
"ExtendedData": {}
146+
}
147+
}
148+
```
149+
150+
**Response Status Codes**
151+
152+
- `200` (OK): indicates that the response body containing the IPNS record that corresponds to the
153+
IPNS name.
154+
- `404` (Not Found): indicates that no matching records are found.
155+
- `400` (Bad Request): indicates that the given IPNS record is not valid.
156+
- `429` (Too Many Requests): indicates that the caller is issuing requests too many request and may
157+
retry after the time specified
158+
at [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) response
159+
header has elapsed.
160+
- `501` (Not Implemented): indicates that the server does not support publication of IPNS records
161+
162+
## CORS and Web Browsers
163+
164+
Browser interoperability requires implementations to support
165+
[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
166+
167+
JavaScript client running on a third-party Origin must be able to send HTTP request to the endpoints
168+
defined in this specification, and read the received values. This means HTTP server implementing
169+
this API must:
170+
171+
1. support [CORS preflight requests](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) sent as HTTP OPTIONS, and
172+
2. always respond with headers that remove CORS limits, allowing every site to query the API for results:
173+
174+
```plaintext
175+
Access-Control-Allow-Origin: *
176+
Access-Control-Allow-Methods: GET, PUT, OPTIONS
177+
```

0 commit comments

Comments
 (0)