diff --git a/src/ipips/ipip-0417.md b/src/ipips/ipip-0417.md index aadb8287e..cd53bdde8 100644 --- a/src/ipips/ipip-0417.md +++ b/src/ipips/ipip-0417.md @@ -47,8 +47,11 @@ routing. The section "Known Transfer Protocols" has been removed and replaced by a "Known Schemas" section. Before, we used to have protocol specific schemas, such as `bitswap` and `graphsync-filecoinv1`. -The usage of the removed schemas is no longer encouraged. Instead, clients and servers -SHOULD be updated to use the new, more generic, `peer` schema. + +The usage of these schemas is no longer encouraged. Instead, clients and +servers SHOULD be updated to use the new, more generic, `peer` schema, which +avoids returning the same peer multiple times, making results more efficient +when a peer supports more than one protocol. See more in the "Compatibility" section of :cite[ipip-0337]. diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index d4637ccd7..67a743e2f 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -9,11 +9,26 @@ maturity: reliable editors: - name: Gus Eggert github: guseggert + affiliation: + name: Protocol Labs + url: https://protocol.ai/ - name: Masih H. Derkani github: masih + affiliation: + name: Protocol Labs + url: https://protocol.ai/ - name: Henrique Dias url: https://hacdias.com/ github: hacdias + affiliation: + name: Protocol Labs + url: https://protocol.ai/ + - name: Marcin Rataj + github: lidel + url: https://lidel.org/ + affiliation: + name: Protocol Labs + url: https://protocol.ai/ xref: - ipns-record order: 0 @@ -32,7 +47,7 @@ As such, human-readable encodings of types are preferred. This specification may - CIDs are always string-encoded using a [multibase]-encoded [CIDv1]. - Multiaddrs are string-encoded according to the [human-readable multiaddr specification][multiaddr]. -- Peer IDs are string-encoded according [PeerID string representation specification][peer-id-representation]. +- Peer IDs are string-encoded according [PeerID string representation specification][peer-id-representation]: either a Multihash in Base58btc, or a CIDv1 with libp2p-key (`0x72`) codec. - Multibase bytes are string-encoded according to [the Multibase spec][multibase], and SHOULD use base64. - Timestamps are Unix millisecond epoch timestamps. @@ -62,19 +77,21 @@ This API uses a standard version prefix in the path, such as `/v1/...`. If a bac { "Providers": [ { - "Schema": "peer", - "Protocols": ["", "", ...], - "ID": "12D3K...", + "Schema": "", + "ID": "bafz...", "Addrs": ["/ip4/..."], + ... }, ... ] } ``` -Responses SHOULD be limited to 100 providers. This endpoint MAY support [streaming](#streaming). +The `application/json` responses SHOULD be limited to 100 providers. + +The client SHOULD be able to make a request with `Accept: application/x-ndjson` and get a [stream](#streaming) with more results. -Each object in the `Providers` list is a record conforming to the [Peer Schema](#peer). +Each object in the `Providers` list is a record conforming to a schema, usually the [Peer Schema](#peer-schema). ## Peer Routing API @@ -99,17 +116,20 @@ represented as a CIDv1 encoded with `libp2p-key` codec. { "Schema": "", "Protocols": ["", "", ...], - "ID": "12D3K...", + "ID": "bafz...", "Addrs": ["/ip4/..."], + ... }, ... ] } ``` -Responses SHOULD be limited to 100 providers. This endpoint MAY support [streaming](#streaming). +The `application/json` responses SHOULD be limited to 100 peers. -Each object in the `Peers` list is a record conforming to the [Peer Schema](#peer). +The client SHOULD be able to make a request with `Accept: application/x-ndjson` and get a [stream](#streaming) with more results. + +Each object in the `Peers` list is a record conforming to the [Peer Schema](#peer-schema). ## IPNS API @@ -212,43 +232,92 @@ Access-Control-Allow-Methods: GET, OPTIONS This section contains a non-exhaustive list of known schemas that MAY be supported by clients and servers. -### Peer +### Peer Schema The `peer` schema represents an arbitrary peer. ```json { "Schema": "peer", - "ID": "12D3K...", + "ID": "bafz...", "Addrs": ["/ip4/..."], "Protocols": ["transport-bitswap", ...] + ... } ``` -- `ID`: the [Peer ID][peer-id]. -- `Addrs`: a list of known [multiaddrs][multiaddr] for this peer. This list MAY be incomplete. -- `Protocols`: a list of protocols known to be supported by this peer. - - If empty, it means the server is missing protocol information, and the client should use `ID` and `Addrs` to connect to the peer and use the [libp2p identify protocol](/~https://github.com/libp2p/specs/tree/master/identify) to learn about supported ones. +- `ID`: the [Peer ID][peer-id] as Multihash in Base58btc or CIDv1 with libp2p-key codec. +- `Addrs`: an optional list of known [multiaddrs][multiaddr] for this peer. + - If missing or empty, it means the router server is missing that information, and the client should use `ID` to lookup updated peer information. +- `Protocols`: an optional list of protocols known to be supported by this peer. + - If missing or empty, it means the router server is missing that information, and the client should use `ID` and `Addrs` to lookup connect to the peer and use the [libp2p identify protocol](/~https://github.com/libp2p/specs/tree/master/identify) to learn about supported ones. :::note -To allow for protocol-specific fields and future-proofing, the parser MUST allow for unknown fields, -and the clients MUST ignore unknown ones. Below is an example on how one could create a `foobar` protocol -that includes an additional field `foobar`. If the client knows the `foobar` protocol, they are free to -use the information contained in the additional field. If that is not the case, the field MUST be ignored. +To allow for protocol-specific fields and future-proofing, the parser MUST +allow for unknown fields, and the clients MUST ignore unknown ones. + +Below is an example on how one could include `protocol-a` and `protocol-b` +protocols that includes an additional fields `protocol-a` and `protocol-b`. + +If the client knows the protocol, they are free to use the extra binary +(base64) or JSON information contained in the additional field. If that is not +the case, the field MUST be ignored. ```json { "Schema": "peer", - "ID": "12D3K...", + "ID": "bafz...", "Addrs": ["/ip4/..."], - "Protocols": ["transport-bitswap", "foobar", ...], - "foobar": "[base64-blob]" + "Protocols": ["transport-bitswap", "protocol-a", "protocol-b", ...], + "protocol-a": "[base64-blob]", + "protocol-b": { "foo": "bar" } } ``` ::: +### Legacy Schemas + +Legacy schemas include `ID` and optional `Addrs` list just like +the [`peer` schema](#peer-schema) does. + +These schemas are deprecated and SHOULD be replaced with `peer` over time, but +MAY be returned by some legacy endpoints. In such case, a client MAY parse +them the same way as the `peer` schema. + +#### Bitswap Schema + +A legacy schema used by some routers to indicate a peer supports retrieval over +the `/ipfs/bitswap[/*]` libp2p protocol. + +```json +{ + "Protocol": "transport-bitswap", + "Schema": "bitswap", + "ID": "bafz...", + "Addrs": ["/ip4/..."] +} +``` + +#### Graphsync Schema + +A legacy schema used by some routers to indicate a peer supports retrieval over +the [graphsync](/~https://github.com/ipfs/go-graphsync/blob/main/docs/architecture.md) +libp2p protocol. + +```json +{ + "Protocol": "transport-graphsync-filecoinv1", + "Schema": "graphsync-filecoinv1", + "ID": "bafz...", + "Addrs": ["/ip4/..."], + "PieceCID": "", + "VerifiedDeal": true, + "FastRetrieval": true +} +``` + [multibase]: /~https://github.com/multiformats/multibase [CIDv1]: /~https://github.com/multiformats/cid#cidv1 [multiaddr]: /~https://github.com/multiformats/multiaddr#specification