From 1467e48d8acb8cb7a86baac97fed83f26e84dca6 Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Mon, 29 May 2023 11:15:13 +0200 Subject: [PATCH 01/10] docs: start IPIP 0417 Co-authored-by: Marcin Rataj --- src/ipips/ipip-0417.md | 60 ++++++++++++++++++++++++++++++++++ src/routing/http-routing-v1.md | 41 +++++++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 src/ipips/ipip-0417.md diff --git a/src/ipips/ipip-0417.md b/src/ipips/ipip-0417.md new file mode 100644 index 000000000..d287375ad --- /dev/null +++ b/src/ipips/ipip-0417.md @@ -0,0 +1,60 @@ +--- +title: "IPIP-0417: Delegated Peer Routing HTTP API" +date: 2023-05-29 +ipip: proposal +editors: + - name: Henrique Dias + github: hacdias + url: https://hacdias.com/ + affiliation: + name: Protocol Labs + url: https://protocol.ai/ +relatedIssues: + - https://github.com/ipfs/specs/pull/410 + - https://github.com/ipfs/kubo/pull/9877 +order: 417 +tags: ['ipips'] +--- + +## Summary + +This IPIP specifies `/routing/v1/peers/{peer-id}` HTTP API to offload peer routing onto another server. + +## Motivation + +The motivation of this IPIP extends the one of :cite[ipip-0337] and :cite[ipip-0379], +which introduced delegated content routing and delegated naming, respectively. Now, +we expand upon those basis to introduce peer routing, reducing the barrier for interaction +across different systems. + +## Detailed design + +Add `/routing/v1/peers/{peer-id}` to the existing :cite[http-routing-v1] specification, +as well as the new Peer schema. + +## Design rationale + +In line with the remaining Routing V1 API, this IPIP introduces a new HTTP GET +endpoint that is used to retrieve peer records for a certain peer. + +### User benefit + +The user benefit brought by this PR is similar to the one in :cite[ipip-0379], +but instead of offloading the naming process, we offload the peer discovery and +routing. + +### Compatibility + +See the "Compatibility" section of :cite[ipip-0337]. + +### Security + +TODO + +### Alternatives + +TODO + +### Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index 480f930fc..655467184 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -102,6 +102,25 @@ Response limit: 100 providers Each object in the `Providers` list is a *read provider record*. +## Peers API + +### `GET /routing/v1/peers/{peer-id}` + +#### Path Parameters + +- `peer-id` is the [Peer ID](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md) to fetch peer records for, +represented as a CIDv1 encoded with `libp2p-key` codec. + +#### Response Status Codes + +- `200` (OK): the response body contains the peer record. +- `404` (Not Found): must be returned if no matching records are found. +- `422` (Unprocessable Entity): request does not conform to schema or semantic constraints. + +#### Response Body + +A [`peer` schema record](#peer). + ## IPNS API ### `GET /routing/v1/ipns/{name}` @@ -199,6 +218,28 @@ Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, OPTIONS ``` +## Known Schemas + +This section contains a non-exhaustive list of known schemas that MAY be supported by clients and servers. + +### Peer + +The `peer` schema represents an arbitrary peer. + +```json +{ + "Schema": "peer", + "ID": "12D3K...", + "Addrs": ["/ip4/..."], + "Protocols": ["transport-bitswap", ...] +} +``` + +- `ID`: the [Peer ID](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md). +- `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. + ## Known Transfer Protocols This section contains a non-exhaustive list of known transfer protocols (by name) that may be supported by clients and servers. From e1b335fcf306713398b89743edad2aff319d36cd Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Tue, 1 Aug 2023 12:41:40 +0200 Subject: [PATCH 02/10] add paragraph about additional fields --- src/routing/http-routing-v1.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index 655467184..9652cdc1c 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -240,6 +240,25 @@ The `peer` schema represents an arbitrary peer. - `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. +:::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. + +```json +{ + "Schema": "peer", + "ID": "12D3K...", + "Addrs": ["/ip4/..."], + "Protocols": ["transport-bitswap", "foobar", ...], + "foobar": "[base64-blob]", +} +``` + +::: + ## Known Transfer Protocols This section contains a non-exhaustive list of known transfer protocols (by name) that may be supported by clients and servers. From b77728b18c6b64b640c4f5c482f1b5c164916b82 Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Tue, 1 Aug 2023 12:44:26 +0200 Subject: [PATCH 03/10] remove known transfer protocols section --- src/routing/http-routing-v1.md | 57 ++-------------------------------- 1 file changed, 2 insertions(+), 55 deletions(-) diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index 9652cdc1c..e27903917 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -235,9 +235,9 @@ The `peer` schema represents an arbitrary peer. } ``` -- `ID`: the [Peer ID](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md). +- `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. +- `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. :::note @@ -259,59 +259,6 @@ use the information contained in the additional field. If that is not the case, ::: -## Known Transfer Protocols - -This section contains a non-exhaustive list of known transfer protocols (by name) that may be supported by clients and servers. - -### Bitswap - -- Multicodec name: `transport-bitswap` -- Schema: `bitswap` -- Specification: [ipfs/specs/BITSWAP.md](https://github.com/ipfs/specs/blob/main/BITSWAP.md) - -#### Bitswap Read Provider Records - -```json -{ - "Protocol": "transport-bitswap", - "Schema": "bitswap", - "ID": "12D3K...", - "Addrs": ["/ip4/..."] -} -``` - -- `ID`: the [Peer ID][peer-id] to contact -- `Addrs`: a list of known multiaddrs for the peer - - This list may be incomplete or incorrect and should only be treated as *hints* to improve performance by avoiding extra peer lookups - -The server should respect a passed `transport` query parameter by filtering against the `Addrs` list. - -### Filecoin Graphsync - -- Multicodec name: `transport-graphsync-filecoinv1` -- Schema: `graphsync-filecoinv1` -- Specification: [ipfs/go-graphsync/blob/main/docs/architecture.md](https://github.com/ipfs/go-graphsync/blob/main/docs/architecture.md) - -#### Filecoin Graphsync Read Provider Records - -```json -{ - "Protocol": "transport-graphsync-filecoinv1", - "Schema": "graphsync-filecoinv1", - "ID": "12D3K...", - "Addrs": ["/ip4/..."], - "PieceCID": "", - "VerifiedDeal": true, - "FastRetrieval": true -} -``` - -- `ID`: the [Peer ID][peer-id] of the provider -- `Addrs`: a list of known multiaddrs for the provider -- `PieceCID`: the CID of the [piece](https://spec.filecoin.io/systems/filecoin_files/piece/#section-systems.filecoin_files.piece) within which the data is stored -- `VerifiedDeal`: whether the deal corresponding to the data is verified -- `FastRetrieval`: whether the provider claims there is an unsealed copy of the data available for fast retrieval - [multibase]: https://github.com/multiformats/multibase [CIDv1]: https://github.com/multiformats/cid#cidv1 [multiaddr]: https://github.com/multiformats/multiaddr#specification From b1ed79e894385a07fa6dcf02fd32741e4b2285cd Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Tue, 1 Aug 2023 12:52:22 +0200 Subject: [PATCH 04/10] cleanup provider records story --- src/routing/http-routing-v1.md | 62 ++++++++++++++-------------------- 1 file changed, 26 insertions(+), 36 deletions(-) diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index e27903917..668858229 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -42,34 +42,6 @@ Until required for business logic, servers should treat these types as opaque st This API uses a standard version prefix in the path, such as `/v1/...`. If a backwards-incompatible change must be made, then the version number should be increased. -### Provider Records - -A provider record contains information about a content provider, including the transfer protocol and any protocol-specific information useful for fetching the content from the provider. - -The information required to write a record to a router (*"write" provider records*) may be different than the information contained when reading provider records (*"read" provider records*). - -For example, indexers may require a signature in `bitswap` write records for authentication of the peer contained in the record, but the read records may not include this authentication information. - -Both read and write provider records have a minimal required schema as follows: - -```json -{ - "Protocol": "", - "Schema": "", - ... -} -``` - -Where: - -- `Protocol` is the multicodec name of the transfer protocol or an opaque string (for experimenting with novel protocols without a multicodec) -- `Schema` denotes the schema to use for encoding/decoding the record - - This is separate from the `Protocol` to allow this HTTP API to evolve independently of the transfer protocol - - Implementations should switch on this when parsing records, not on `Protocol` -- `...` denotes opaque JSON, which may contain information specific to the transfer protocol - -Specifications for some transfer protocols are provided in the "Transfer Protocols" section. - ## Content Providers API ### `GET /routing/v1/providers/{cid}` @@ -90,17 +62,19 @@ Specifications for some transfer protocols are provided in the "Transfer Protoco { "Providers": [ { - "Protocol": "", - "Schema": "", - ... - } + "Schema": "peer", + "Protocols": ["", "", ...], + "ID": "12D3K...", + "Addrs": ["/ip4/..."], + }, + ... ] } ``` -Response limit: 100 providers +Response limit: 100 providers. -Each object in the `Providers` list is a *read provider record*. +Each object in the `Providers` list is a record confirming to the [Peer Schema](#peer). ## Peers API @@ -119,7 +93,23 @@ represented as a CIDv1 encoded with `libp2p-key` codec. #### Response Body -A [`peer` schema record](#peer). +```json +{ + "Peers": [ + { + "Schema": "", + "Protocols": ["", "", ...], + "ID": "12D3K...", + "Addrs": ["/ip4/..."], + }, + ... + ] +} +``` + +Response limit: 100 peer records. + +Each object in the `Peers` list is a record confirming to the [Peer Schema](#peer). ## IPNS API @@ -142,7 +132,7 @@ A [`peer` schema record](#peer). #### Response Body -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. +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}` From 828378d387191af470dc1293f547933ffa43e262 Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Tue, 1 Aug 2023 13:07:48 +0200 Subject: [PATCH 05/10] add notes to the compatibility section --- src/ipips/ipip-0417.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/ipips/ipip-0417.md b/src/ipips/ipip-0417.md index d287375ad..c246f70b8 100644 --- a/src/ipips/ipip-0417.md +++ b/src/ipips/ipip-0417.md @@ -30,7 +30,7 @@ across different systems. ## Detailed design Add `/routing/v1/peers/{peer-id}` to the existing :cite[http-routing-v1] specification, -as well as the new Peer schema. +as well as the new Peer schema, that replaces the existing "known transfer protocols". ## Design rationale @@ -45,7 +45,12 @@ routing. ### Compatibility -See the "Compatibility" section of :cite[ipip-0337]. +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. + +See more in the "Compatibility" section of :cite[ipip-0337]. ### Security From 2dbdb54d6fcf3ac07ae00523d8617d02f04dc469 Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Tue, 1 Aug 2023 13:13:21 +0200 Subject: [PATCH 06/10] editorial touches --- src/routing/http-routing-v1.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index 668858229..ed393937c 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -38,11 +38,11 @@ As such, human-readable encodings of types are preferred. This specification may Until required for business logic, servers should treat these types as opaque strings, and should preserve unknown JSON fields. -### Versioning +## Versioning This API uses a standard version prefix in the path, such as `/v1/...`. If a backwards-incompatible change must be made, then the version number should be increased. -## Content Providers API +## Content Routing API ### `GET /routing/v1/providers/{cid}` @@ -72,11 +72,11 @@ This API uses a standard version prefix in the path, such as `/v1/...`. If a bac } ``` -Response limit: 100 providers. +Responses SHOULD be limited to 100 providers. This endpoint MAY support [streaming](#streaming). -Each object in the `Providers` list is a record confirming to the [Peer Schema](#peer). +Each object in the `Providers` list is a record conforming to the [Peer Schema](#peer). -## Peers API +## Peer Routing API ### `GET /routing/v1/peers/{peer-id}` @@ -107,9 +107,9 @@ represented as a CIDv1 encoded with `libp2p-key` codec. } ``` -Response limit: 100 peer records. +Responses SHOULD be limited to 100 providers. This endpoint MAY support [streaming](#streaming). -Each object in the `Peers` list is a record confirming to the [Peer Schema](#peer). +Each object in the `Peers` list is a record conforming to the [Peer Schema](#peer). ## IPNS API @@ -172,7 +172,7 @@ with one result per line: :::note -Streaming is opt-in and backwards-compatibile with clients and servers that do +Streaming is opt-in and backwards-compatible with clients and servers that do not support streaming: - Requests without the `Accept: application/x-ndjson` header MUST default to From 4adf8b740b03e130258b295ab0f7a60c07cc129b Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Tue, 1 Aug 2023 13:14:20 +0200 Subject: [PATCH 07/10] finish sections in IPIP --- src/ipips/ipip-0417.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/ipips/ipip-0417.md b/src/ipips/ipip-0417.md index c246f70b8..aadb8287e 100644 --- a/src/ipips/ipip-0417.md +++ b/src/ipips/ipip-0417.md @@ -54,11 +54,11 @@ See more in the "Compatibility" section of :cite[ipip-0337]. ### Security -TODO +See the "Security" section of :cite[ipip-0337]. ### Alternatives -TODO +See the "Alternatives" section of :cite[ipip-0337]. ### Copyright From 86ecfa06fae4dc22d87d8573c81c9c3d5cfad9e2 Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Tue, 1 Aug 2023 16:02:35 +0200 Subject: [PATCH 08/10] editorial fixes Co-authored-by: Masih H. Derkani --- src/routing/http-routing-v1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index ed393937c..d4637ccd7 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -243,7 +243,7 @@ use the information contained in the additional field. If that is not the case, "ID": "12D3K...", "Addrs": ["/ip4/..."], "Protocols": ["transport-bitswap", "foobar", ...], - "foobar": "[base64-blob]", + "foobar": "[base64-blob]" } ``` From f3fe9d57a73a3b82ad39444c742cecf1588de008 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 31 Aug 2023 14:20:52 +0200 Subject: [PATCH 09/10] ipip-0417: final editorials, list legacy schemas we will have legacy schemas in the wild for a while, added a note that clients may parse them the same way as peer one (both have ID and Addrs) --- src/ipips/ipip-0417.md | 7 +- src/routing/http-routing-v1.md | 113 ++++++++++++++++++++++++++------- 2 files changed, 96 insertions(+), 24 deletions(-) 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 From 95999ef051941be60001137521347821d18b6bb6 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 31 Aug 2023 14:28:38 +0200 Subject: [PATCH 10/10] chore: bump date --- src/routing/http-routing-v1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index 67a743e2f..c7cc62e02 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -4,7 +4,7 @@ description: > Delegated routing is a mechanism for IPFS implementations to use for offloading content routing and naming to another process/server. This specification describes an HTTP API for delegated content routing. -date: 2023-03-22 +date: 2023-08-31 maturity: reliable editors: - name: Gus Eggert