From 632a4a79b0b4ddf5204064ebdb13f6c3f8e68401 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 21 Apr 2023 18:08:41 +0200 Subject: [PATCH 1/3] routing api: clarify string in the protocol field This clarifies what values can be put in the field to improve robustness, and that protocols without multicodec registered should ensure global uniqueness. --- routing/ROUTING_V1_HTTP.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/routing/ROUTING_V1_HTTP.md b/routing/ROUTING_V1_HTTP.md index 4d2891785..879cde99c 100644 --- a/routing/ROUTING_V1_HTTP.md +++ b/routing/ROUTING_V1_HTTP.md @@ -54,7 +54,9 @@ Both read and write provider records have a minimal required schema as follows: Where: -- `Protocol` is the multicodec name of the transfer protocol or an opaque string (for experimenting with novel protocols without a multicodec) +- `Protocol` is a globlly unique opaque string that represents the transfer protocol used by a content provider. + - If a multicodec has been registered for the protocol, it can be referred to by either its `name` or `code` in `0xHEX` notation. Using the `code` is preferred since it is what is sent on the wire and won't break if the plain text `name` label is ever changed. + - For protocols without a dedicated multicodec, it is recommended to use a globally unique enough identifier to prevent collisions. - `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` @@ -127,7 +129,7 @@ This section contains a non-exhaustive list of known transfer protocols (by name ### Bitswap -Multicodec name: `transport-bitswap` +Protocol: `transport-bitswap` multicodec name or code in hex `0x0900` Schema: `bitswap` Specification: [ipfs/specs/BITSWAP.md](https://github.com/ipfs/specs/blob/main/BITSWAP.md) @@ -150,7 +152,7 @@ The server should respect a passed `transport` query parameter by filtering agai ### Filecoin Graphsync -Multicodec name: `transport-graphsync-filecoinv1` +Protocol: `transport-graphsync-filecoinv1` multicodec name or code in hex `0x0910` Schema: `graphsync-filecoinv1` Specification: [ipfs/go-graphsync/blob/main/docs/architecture.md](https://github.com/ipfs/go-graphsync/blob/main/docs/architecture.md) From c097fd44a214b1574e93021c1fbc7791edc151fc Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 21 Apr 2023 18:16:18 +0200 Subject: [PATCH 2/3] routing api: suggest behavior for default schemas --- routing/ROUTING_V1_HTTP.md | 1 + 1 file changed, 1 insertion(+) diff --git a/routing/ROUTING_V1_HTTP.md b/routing/ROUTING_V1_HTTP.md index 879cde99c..8bf282af5 100644 --- a/routing/ROUTING_V1_HTTP.md +++ b/routing/ROUTING_V1_HTTP.md @@ -60,6 +60,7 @@ Where: - `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` + - Protocols without an explicit schema or multiple versions, can use the same opaque string as in `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. From 19b31ccabbf68769c88a360df8d66ef0a3b7c91f Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Tue, 2 May 2023 13:21:37 +0200 Subject: [PATCH 3/3] Update routing/ROUTING_V1_HTTP.md Co-authored-by: Alex Potsides --- routing/ROUTING_V1_HTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/routing/ROUTING_V1_HTTP.md b/routing/ROUTING_V1_HTTP.md index 8bf282af5..7e185de5e 100644 --- a/routing/ROUTING_V1_HTTP.md +++ b/routing/ROUTING_V1_HTTP.md @@ -54,7 +54,7 @@ Both read and write provider records have a minimal required schema as follows: Where: -- `Protocol` is a globlly unique opaque string that represents the transfer protocol used by a content provider. +- `Protocol` is a globally unique opaque string that represents the transfer protocol used by a content provider. - If a multicodec has been registered for the protocol, it can be referred to by either its `name` or `code` in `0xHEX` notation. Using the `code` is preferred since it is what is sent on the wire and won't break if the plain text `name` label is ever changed. - For protocols without a dedicated multicodec, it is recommended to use a globally unique enough identifier to prevent collisions. - `Schema` denotes the schema to use for encoding/decoding the record