From f9a6e7618f82f7ea5fb7c87a6d5ffd08bb205763 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 6 Sep 2024 12:44:20 +0200 Subject: [PATCH 01/23] feat: delegated routing filtering for transports chore: update ipip number --- src/ipips/ipip-0484.md | 105 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 src/ipips/ipip-0484.md diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md new file mode 100644 index 00000000..d2dd09c8 --- /dev/null +++ b/src/ipips/ipip-0484.md @@ -0,0 +1,105 @@ +--- +title: 'IPIP-0484: Delegated Routing V1 Support for Querying Specific Network Transport and Transfer Protocols' +date: 2024-09-03 +ipip: proposal +editors: + - name: Daniel Norman + github: 2color + affiliation: + name: Shipyard + url: https://www.ipshipyard.com/ +relatedIssues: + - https://github.com/ipfs-shipyard/someguy/issues/13 +order: 483 +tags: ['ipips'] +--- + +## Summary + +Add opt-in support for filtering specific network transports and/or transfer protocols to the Delegated Routing v1 HTTP endpoint via HTTP GET parameters. + +## Motivation + +IPFS aims to allow ubiquitous data exchange across different runtimes and platforms. One of the most challenging aspects of this goal is the diversity of network conditions and capabilities across different environments. Web browsers have a very limited network stack, and most web browsers do not support the full range of network transport protocols that are commonly used in other IPFS implementations. + +The Delegated Routing v1 API empowers resource constrained clients like web browsers by significantly reducing the number of network connections necessary to fetch content addressed data directly from provider peers. + +However, there are many cases where most of the results from the Delegated Routing v1 API are not actionable by clients, because the client does not support either the **network transport protocol** or the **transfer protocol** of the provider. + +For instance, web browsers are limited to a specific set of network transport protocols, namely HTTPS, Secure WebSockets, WebTransport (emerging), and WebRTC. Consequently, providing information about providers that exclusively support TCP and/or UDP is not beneficial for browser-based clients, as they are unable to utilize such connections. + +Moreover, [Helia](https://github.com/ipfs/helia/), the most actively maintained browser IPFS implementation, supports block retrieval by CID with Bitswap and Trustless Gateways, but does not support GraphSync. + +This means that returning providers that only support GraphSync from the Delegated Routing API is not useful for browser clients, and results in unnecessary network traffic for browser clients. + +## Note on terminology + +The term **"transport"** is overloaded in the IPFS ecosystem. + +In the context of this IPIP, we refer to the network layer transport protocol, e.g. TCP, QUIC, WebTransport, as **"network transport protocol"** to avoid ambiguity. + +**"Transfer protocol"** refers to data exchange protocols, i.e. content-addressed block retrieval format, e.g. Bitswap, GraphSync, HTTP. + +## Detailed design + +### Network Transport Protocol Filtering + +The proposed change is to add a `?network-transports` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: + +- Add a `?network-transports=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema](peer-schema). +- The value of the `network-transports` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?network-transports=webtransport`. +- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs. +- Only multiaddrs that pass the filter are included in the response. +- If there are no multiaddrs that match the passed transports, the provider is omitted from the response. +- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?network-transports=!webtransport`. +- The filtering is case-insensitive. +- If the parameter is not passed, the default behavior is to not apply filtering by network transports. + +:::note +Filtering out providers without any matching transport, will cause providers without any multiaddrs to be filtered out, even if they _might_ support the requested transports. This is due to the fact that provider records are independent of peer records, and it's pretty common to have provider records without up-to-date multiaddrs for that peer. +::: + +### Transfer Protocol Filtering + +The proposed change is to add a `?transfer-protocols` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: + +- Add a `?transfer-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which transfer protocols to return by filtering the `Protocol` field of the [Peer schema](peer-schema). +- The value of the `transfer-protocols` parameter is a comma-separated list of known transfer protocol names: + - `transport-bitswap` + - `transport-graphsync-filecoinv1` + - `transport-ipfs-gateway-http` +- Providers are filtered by checking if the transfer protocol name appears at least once in the `Protocols` array. +- If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. +- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?transport=!transport-graphsync-filecoinv1`. +- The filtering is case-insensitive. +- If the parameter is not passed, the default behavior is to not filter by transfer protocol. +- Providers returned from the DHT, currently do not contain a `Protocol` field. In such cases, Bitswap can be implied. + +:::note +For legacy reasons, the transfer protocols are referred to and prefixed with `transport` in their names, e.g. `transport-bitswap`, `transport-graphsync-filecoinv1`, and `transport-ipfs-gateway-http`. This is not to be confused with the network transport protocols, which are filtered using the `network-transports` parameter. +::: + +## Design rationale + +- Using these query parameters improves cache efficiency, as the response will be smaller and more specific to the client's needs. +- Backward compatibility by not changing the default behavior of the API. +- Use of protocol name rather than code makes it easier for human debugging. +- DHT providers currently do not contain any transfer protocol, even though Bitswap can be implied in all cases. + +### User benefit + +By filtering out providers that do not support the desired network transport protocol and/or transfer protocol, the client can reduce the traffic necessary in order to fetch the data. + +Moreover, it makes it much easier to determine whether there are any browser-usable providers for a given CID, which is a common use case for clients. + +### Compatibility + +This should not effect existing clients or servers. + +The default behavior when `?network-transports` and `?transfer-protocols` is not passed is left unspecified, this IPIP is limited to opt-in behavior. + +### Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +[peer-schema]: https://specs.ipfs.tech/routing/http-routing-v1/#peer-schema From e2b9fdb7fc04174697cd5dceff6ae7c4ebc71ed2 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 6 Sep 2024 12:51:16 +0200 Subject: [PATCH 02/23] fix: lint error --- src/ipips/ipip-0484.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index d2dd09c8..d7f5985b 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -46,7 +46,7 @@ In the context of this IPIP, we refer to the network layer transport protocol, e The proposed change is to add a `?network-transports` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: -- Add a `?network-transports=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema](peer-schema). +- Add a `?network-transports=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. - The value of the `network-transports` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?network-transports=webtransport`. - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs. - Only multiaddrs that pass the filter are included in the response. @@ -63,7 +63,7 @@ Filtering out providers without any matching transport, will cause providers wit The proposed change is to add a `?transfer-protocols` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: -- Add a `?transfer-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which transfer protocols to return by filtering the `Protocol` field of the [Peer schema](peer-schema). +- Add a `?transfer-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which transfer protocols to return by filtering the `Protocol` field of the [Peer schema]. - The value of the `transfer-protocols` parameter is a comma-separated list of known transfer protocol names: - `transport-bitswap` - `transport-graphsync-filecoinv1` @@ -102,4 +102,4 @@ The default behavior when `?network-transports` and `?transfer-protocols` is not Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). -[peer-schema]: https://specs.ipfs.tech/routing/http-routing-v1/#peer-schema +[Peer schema]: https://specs.ipfs.tech/routing/http-routing-v1/#peer-schema From cc3816385f87f96b4efc63540bfc98f078d209ea Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 6 Sep 2024 15:47:49 +0200 Subject: [PATCH 03/23] fix: introduce unkown filtering --- src/ipips/ipip-0484.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index d7f5985b..08c0a579 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -38,7 +38,7 @@ The term **"transport"** is overloaded in the IPFS ecosystem. In the context of this IPIP, we refer to the network layer transport protocol, e.g. TCP, QUIC, WebTransport, as **"network transport protocol"** to avoid ambiguity. -**"Transfer protocol"** refers to data exchange protocols, i.e. content-addressed block retrieval format, e.g. Bitswap, GraphSync, HTTP. +**"Transfer protocol"** refers to data transfer protocols, i.e. content-addressed block retrieval protocols, e.g. Bitswap, GraphSync, HTTP. ## Detailed design @@ -51,9 +51,9 @@ The proposed change is to add a `?network-transports` parameter to the `GET /rou - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs. - Only multiaddrs that pass the filter are included in the response. - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. -- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?network-transports=!webtransport`. -- The filtering is case-insensitive. -- If the parameter is not passed, the default behavior is to not apply filtering by network transports. +- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?network-transports=!quic-v1,!tcp`. +- Filtering is case-insensitive. +- If no parameter is passed, the default behavior is to not apply filtering by network transports. :::note Filtering out providers without any matching transport, will cause providers without any multiaddrs to be filtered out, even if they _might_ support the requested transports. This is due to the fact that provider records are independent of peer records, and it's pretty common to have provider records without up-to-date multiaddrs for that peer. @@ -64,19 +64,18 @@ Filtering out providers without any matching transport, will cause providers wit The proposed change is to add a `?transfer-protocols` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: - Add a `?transfer-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which transfer protocols to return by filtering the `Protocol` field of the [Peer schema]. -- The value of the `transfer-protocols` parameter is a comma-separated list of known transfer protocol names: - - `transport-bitswap` - - `transport-graphsync-filecoinv1` - - `transport-ipfs-gateway-http` -- Providers are filtered by checking if the transfer protocol name appears at least once in the `Protocols` array. +- The `transfer-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?transfer-protocols=transport-bitswap`. +- Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). Implementations should not break when encountering unknown transfer protocol names. +- `unknown` can be be passed to include providers whose transfer protocol is unknown, e.g. `?transfer-protocols=unknown`. This allows filtering providers returned from the DHT that do not contain explicit transfer protocol information. +- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array. - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. - Negative filtering is done by prefixing the protocol name with `!`, e.g. `?transport=!transport-graphsync-filecoinv1`. -- The filtering is case-insensitive. -- If the parameter is not passed, the default behavior is to not filter by transfer protocol. -- Providers returned from the DHT, currently do not contain a `Protocol` field. In such cases, Bitswap can be implied. +- Filtering is case-insensitive. +- If no parameter is passed, the default behavior is to not filter by transfer protocol. + :::note -For legacy reasons, the transfer protocols are referred to and prefixed with `transport` in their names, e.g. `transport-bitswap`, `transport-graphsync-filecoinv1`, and `transport-ipfs-gateway-http`. This is not to be confused with the network transport protocols, which are filtered using the `network-transports` parameter. +Even though existing transfer protocol names start with `transport`, e.g. `transport-bitswap`, `transport-graphsync-filecoinv1`, and `transport-ipfs-gateway-http`. This is not to be confused with the network transport protocols, which are filtered using the `network-transports` parameter. ::: ## Design rationale @@ -84,7 +83,7 @@ For legacy reasons, the transfer protocols are referred to and prefixed with `tr - Using these query parameters improves cache efficiency, as the response will be smaller and more specific to the client's needs. - Backward compatibility by not changing the default behavior of the API. - Use of protocol name rather than code makes it easier for human debugging. -- DHT providers currently do not contain any transfer protocol, even though Bitswap can be implied in all cases. +- DHT providers currently do not contain any transfer protocol information. `unknown` can be used to filter such providers. ### User benefit From 1eb4b65473866a7eaed9c2109d01ec5c235773b8 Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Fri, 6 Sep 2024 16:36:35 +0200 Subject: [PATCH 04/23] Apply suggestions from code review Co-authored-by: Marcin Rataj --- src/ipips/ipip-0484.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 08c0a579..092e5edb 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -7,10 +7,10 @@ editors: github: 2color affiliation: name: Shipyard - url: https://www.ipshipyard.com/ + url: https://ipshipyard.com relatedIssues: - https://github.com/ipfs-shipyard/someguy/issues/13 -order: 483 +order: 484 tags: ['ipips'] --- @@ -30,7 +30,7 @@ For instance, web browsers are limited to a specific set of network transport pr Moreover, [Helia](https://github.com/ipfs/helia/), the most actively maintained browser IPFS implementation, supports block retrieval by CID with Bitswap and Trustless Gateways, but does not support GraphSync. -This means that returning providers that only support GraphSync from the Delegated Routing API is not useful for browser clients, and results in unnecessary network traffic for browser clients. +This means that returning providers that only support raw TCP, raw UDP/QUIC, or GraphSync from the Delegated Routing API is not useful for browser clients, and results in unnecessary network traffic for browser clients. ## Note on terminology @@ -48,7 +48,7 @@ The proposed change is to add a `?network-transports` parameter to the `GET /rou - Add a `?network-transports=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. - The value of the `network-transports` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?network-transports=webtransport`. -- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs. +- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). - Only multiaddrs that pass the filter are included in the response. - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. - Negative filtering is done by prefixing the protocol name with `!`, e.g. `?network-transports=!quic-v1,!tcp`. @@ -63,7 +63,7 @@ Filtering out providers without any matching transport, will cause providers wit The proposed change is to add a `?transfer-protocols` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: -- Add a `?transfer-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which transfer protocols to return by filtering the `Protocol` field of the [Peer schema]. +- Add a `?transfer-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which transfer protocols to return by filtering the `Protocol` field of the [Peer schema] (logical OR). - The `transfer-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?transfer-protocols=transport-bitswap`. - Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). Implementations should not break when encountering unknown transfer protocol names. - `unknown` can be be passed to include providers whose transfer protocol is unknown, e.g. `?transfer-protocols=unknown`. This allows filtering providers returned from the DHT that do not contain explicit transfer protocol information. From eab124c17db896a97f26903793b3172fe1f5f885 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Tue, 10 Sep 2024 15:05:51 +0200 Subject: [PATCH 05/23] fix: linting error --- src/ipips/ipip-0484.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 092e5edb..71a29ae8 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -73,7 +73,6 @@ The proposed change is to add a `?transfer-protocols` parameter to the `GET /rou - Filtering is case-insensitive. - If no parameter is passed, the default behavior is to not filter by transfer protocol. - :::note Even though existing transfer protocol names start with `transport`, e.g. `transport-bitswap`, `transport-graphsync-filecoinv1`, and `transport-ipfs-gateway-http`. This is not to be confused with the network transport protocols, which are filtered using the `network-transports` parameter. ::: From 040732053f872fc9ef937e5d01a6f842a6e4ef82 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Tue, 10 Sep 2024 18:10:32 +0200 Subject: [PATCH 06/23] feat: rename query params --- src/ipips/ipip-0484.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 71a29ae8..b6fc8b72 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -44,14 +44,14 @@ In the context of this IPIP, we refer to the network layer transport protocol, e ### Network Transport Protocol Filtering -The proposed change is to add a `?network-transports` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: +The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: -- Add a `?network-transports=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. -- The value of the `network-transports` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?network-transports=webtransport`. +- Add a `?filter-addrs=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. +- The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`. - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). - Only multiaddrs that pass the filter are included in the response. - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. -- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?network-transports=!quic-v1,!tcp`. +- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?filter-addrs=!quic-v1,!tcp`. - Filtering is case-insensitive. - If no parameter is passed, the default behavior is to not apply filtering by network transports. @@ -61,12 +61,12 @@ Filtering out providers without any matching transport, will cause providers wit ### Transfer Protocol Filtering -The proposed change is to add a `?transfer-protocols` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: +The proposed change is to add a `?filter-protocols` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: -- Add a `?transfer-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which transfer protocols to return by filtering the `Protocol` field of the [Peer schema] (logical OR). -- The `transfer-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?transfer-protocols=transport-bitswap`. +- Add a `?filter-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which transfer protocols to return by filtering the `Protocol` field of the [Peer schema] (logical OR). +- The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. - Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). Implementations should not break when encountering unknown transfer protocol names. -- `unknown` can be be passed to include providers whose transfer protocol is unknown, e.g. `?transfer-protocols=unknown`. This allows filtering providers returned from the DHT that do not contain explicit transfer protocol information. +- `unknown` can be be passed to include providers whose transfer protocol is unknown, e.g. `?filter-protocols=unknown`. This allows filtering providers returned from the DHT that do not contain explicit transfer protocol information. - Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array. - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. - Negative filtering is done by prefixing the protocol name with `!`, e.g. `?transport=!transport-graphsync-filecoinv1`. @@ -74,7 +74,7 @@ The proposed change is to add a `?transfer-protocols` parameter to the `GET /rou - If no parameter is passed, the default behavior is to not filter by transfer protocol. :::note -Even though existing transfer protocol names start with `transport`, e.g. `transport-bitswap`, `transport-graphsync-filecoinv1`, and `transport-ipfs-gateway-http`. This is not to be confused with the network transport protocols, which are filtered using the `network-transports` parameter. +Even though existing transfer protocol names start with `transport`, e.g. `transport-bitswap`, `transport-graphsync-filecoinv1`, and `transport-ipfs-gateway-http`. This is not to be confused with the network transport protocols, which are filtered using the `filter-addrs` parameter. ::: ## Design rationale @@ -94,7 +94,7 @@ Moreover, it makes it much easier to determine whether there are any browser-usa This should not effect existing clients or servers. -The default behavior when `?network-transports` and `?transfer-protocols` is not passed is left unspecified, this IPIP is limited to opt-in behavior. +The default behavior when `?filter-addrs` and `?filter-protocols` is not passed is left unspecified, this IPIP is limited to opt-in behavior. ### Copyright From 024539272df44ba7a1a39b2e153a6ec02ddf757b Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Wed, 11 Sep 2024 12:17:54 +0200 Subject: [PATCH 07/23] feat: add unknown to filter addrs --- src/ipips/ipip-0484.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index b6fc8b72..9812942e 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -48,6 +48,7 @@ The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v - Add a `?filter-addrs=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. - The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`. +- `unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering. - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). - Only multiaddrs that pass the filter are included in the response. - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. @@ -55,10 +56,6 @@ The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v - Filtering is case-insensitive. - If no parameter is passed, the default behavior is to not apply filtering by network transports. -:::note -Filtering out providers without any matching transport, will cause providers without any multiaddrs to be filtered out, even if they _might_ support the requested transports. This is due to the fact that provider records are independent of peer records, and it's pretty common to have provider records without up-to-date multiaddrs for that peer. -::: - ### Transfer Protocol Filtering The proposed change is to add a `?filter-protocols` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: @@ -82,7 +79,8 @@ Even though existing transfer protocol names start with `transport`, e.g. `trans - Using these query parameters improves cache efficiency, as the response will be smaller and more specific to the client's needs. - Backward compatibility by not changing the default behavior of the API. - Use of protocol name rather than code makes it easier for human debugging. -- DHT providers currently do not contain any transfer protocol information. `unknown` can be used to filter such providers. +- DHT providers currently do not contain any transfer protocol information. `unknown` can be passed to `filter-protocols` to include such providers. +- Since provider records are independent of peer records, and it's pretty common to have provider records without up-to-date multiaddrs for that peer, `unknown` can be passed to `filter-addrs` to include such providers. ### User benefit From f6aceee65afa3d6c217627eca2de8cc76dd71347 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Wed, 11 Sep 2024 15:01:22 +0200 Subject: [PATCH 08/23] fix: clarify that filter-protocols will not modify record --- src/ipips/ipip-0484.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 9812942e..bd368b34 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -60,12 +60,13 @@ The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v The proposed change is to add a `?filter-protocols` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: -- Add a `?filter-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which transfer protocols to return by filtering the `Protocol` field of the [Peer schema] (logical OR). +- Add a `?filter-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` to filter providers based on the `Protocol` field of the [Peer schema] . - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. - Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). Implementations should not break when encountering unknown transfer protocol names. - `unknown` can be be passed to include providers whose transfer protocol is unknown, e.g. `?filter-protocols=unknown`. This allows filtering providers returned from the DHT that do not contain explicit transfer protocol information. -- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array. +- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. +- If a provider passes the filter, it is returned unchanged, i.e. the full set of protocols is returned including protocols that not included in the filter. (note that this is different from `filter-addrs` where only the multiaddrs that pass the filter are returned) - Negative filtering is done by prefixing the protocol name with `!`, e.g. `?transport=!transport-graphsync-filecoinv1`. - Filtering is case-insensitive. - If no parameter is passed, the default behavior is to not filter by transfer protocol. From b078e126f7a505e3062e59d4f84ec945cd50f15d Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Thu, 12 Sep 2024 11:40:35 +0200 Subject: [PATCH 09/23] Update src/ipips/ipip-0484.md --- src/ipips/ipip-0484.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index bd368b34..c4cc8f5b 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -67,7 +67,6 @@ The proposed change is to add a `?filter-protocols` parameter to the `GET /routi - Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. - If a provider passes the filter, it is returned unchanged, i.e. the full set of protocols is returned including protocols that not included in the filter. (note that this is different from `filter-addrs` where only the multiaddrs that pass the filter are returned) -- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?transport=!transport-graphsync-filecoinv1`. - Filtering is case-insensitive. - If no parameter is passed, the default behavior is to not filter by transfer protocol. From 3da9d871299d5ae05565f969c94150185879e68f Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 13 Sep 2024 12:55:02 +0200 Subject: [PATCH 10/23] correct nuances around negative addr filtering --- src/ipips/ipip-0484.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index c4cc8f5b..4c5364cc 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -50,9 +50,10 @@ The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v - The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`. - `unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering. - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). +- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?filter-addrs=!quic-v1,!tcp`. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND). +- For an address to pass the filter, it must pass all negative filters AND match at least one positive filter. - Only multiaddrs that pass the filter are included in the response. - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. -- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?filter-addrs=!quic-v1,!tcp`. - Filtering is case-insensitive. - If no parameter is passed, the default behavior is to not apply filtering by network transports. From 1d58c199847fd509f39978d9a605c249230e11a7 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 13 Sep 2024 15:19:22 +0200 Subject: [PATCH 11/23] add additional clarifications --- src/ipips/ipip-0484.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 4c5364cc..5ee0f6a7 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -78,10 +78,11 @@ Even though existing transfer protocol names start with `transport`, e.g. `trans ## Design rationale - Using these query parameters improves cache efficiency, as the response will be smaller and more specific to the client's needs. -- Backward compatibility by not changing the default behavior of the API. -- Use of protocol name rather than code makes it easier for human debugging. +- Backward compatibility is maintained by not changing the default behavior of the API. +- Use of protocol name rather than codes makes it easier for human debugging. - DHT providers currently do not contain any transfer protocol information. `unknown` can be passed to `filter-protocols` to include such providers. - Since provider records are independent of peer records, and it's pretty common to have provider records without up-to-date multiaddrs for that peer, `unknown` can be passed to `filter-addrs` to include such providers. +- Combining transfer protocol and transport protocol filters is done by ANDing the results of the filters, e.g. `?filter-addrs=webtransport&filter-protocols=transport-bitswap` will return providers that support bitswap and have a webtransport multiaddr. ### User benefit From 7e7071a5f6e24b5b7b2c22cbfc5b7f670fe92dd8 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Tue, 24 Sep 2024 15:58:49 +0200 Subject: [PATCH 12/23] feat: include peer routing endpoint --- src/ipips/ipip-0484.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 5ee0f6a7..a424a6e7 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -16,7 +16,7 @@ tags: ['ipips'] ## Summary -Add opt-in support for filtering specific network transports and/or transfer protocols to the Delegated Routing v1 HTTP endpoint via HTTP GET parameters. +Add opt-in support for filtering specific network transports and/or transfer protocols to the Delegated Routing v1 HTTP endpoints via HTTP GET parameters. ## Motivation @@ -44,7 +44,7 @@ In the context of this IPIP, we refer to the network layer transport protocol, e ### Network Transport Protocol Filtering -The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: +The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v1/providers/{cid}` and `GET /routing/v1/peers/{peer-id}` endpoints of :cite[http-routing-v1]: - Add a `?filter-addrs=` optional parameter to `GET /routing/v1/providers/{CID}` that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. - The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`. @@ -59,7 +59,7 @@ The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v ### Transfer Protocol Filtering -The proposed change is to add a `?filter-protocols` parameter to the `GET /routing/v1/providers/{cid}` endpoint of :cite[http-routing-v1]: +The proposed change is to add a `?filter-protocols` parameter to the `GET /routing/v1/providers/{cid}` and `GET /routing/v1/peers/{peer-id}` endpoints of :cite[http-routing-v1]: - Add a `?filter-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` to filter providers based on the `Protocol` field of the [Peer schema] . - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. From ce765612c4e7c67e6cbcb459738619f1a4f2c5e3 Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Wed, 25 Sep 2024 13:07:18 +0200 Subject: [PATCH 13/23] Update src/ipips/ipip-0484.md --- src/ipips/ipip-0484.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index a424a6e7..54db81f9 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -28,7 +28,7 @@ However, there are many cases where most of the results from the Delegated Routi For instance, web browsers are limited to a specific set of network transport protocols, namely HTTPS, Secure WebSockets, WebTransport (emerging), and WebRTC. Consequently, providing information about providers that exclusively support TCP and/or UDP is not beneficial for browser-based clients, as they are unable to utilize such connections. -Moreover, [Helia](https://github.com/ipfs/helia/), the most actively maintained browser IPFS implementation, supports block retrieval by CID with Bitswap and Trustless Gateways, but does not support GraphSync. +Moreover, [Helia](https://github.com/ipfs/helia/), the most actively maintained browser IPFS implementation, supports block retrieval by CID with Bitswap and Trustless Gateways, but does not support Graphsync. This means that returning providers that only support raw TCP, raw UDP/QUIC, or GraphSync from the Delegated Routing API is not useful for browser clients, and results in unnecessary network traffic for browser clients. From f5852101f510cc6f8a2d8d94378651e27de53c6e Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Wed, 25 Sep 2024 13:08:03 +0200 Subject: [PATCH 14/23] fix: name Graphsync consisently --- src/ipips/ipip-0484.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 54db81f9..87d737c2 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -30,7 +30,7 @@ For instance, web browsers are limited to a specific set of network transport pr Moreover, [Helia](https://github.com/ipfs/helia/), the most actively maintained browser IPFS implementation, supports block retrieval by CID with Bitswap and Trustless Gateways, but does not support Graphsync. -This means that returning providers that only support raw TCP, raw UDP/QUIC, or GraphSync from the Delegated Routing API is not useful for browser clients, and results in unnecessary network traffic for browser clients. +This means that returning providers that only support raw TCP, raw UDP/QUIC, or Graphsync from the Delegated Routing API is not useful for browser clients, and results in unnecessary network traffic for browser clients. ## Note on terminology @@ -38,7 +38,7 @@ The term **"transport"** is overloaded in the IPFS ecosystem. In the context of this IPIP, we refer to the network layer transport protocol, e.g. TCP, QUIC, WebTransport, as **"network transport protocol"** to avoid ambiguity. -**"Transfer protocol"** refers to data transfer protocols, i.e. content-addressed block retrieval protocols, e.g. Bitswap, GraphSync, HTTP. +**"Transfer protocol"** refers to data transfer protocols, i.e. content-addressed block retrieval protocols, e.g. Bitswap, Graphsync, HTTP. ## Detailed design From eb7add8016805c4dae5f377bc6c3dce107710769 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Wed, 25 Sep 2024 15:37:30 +0200 Subject: [PATCH 15/23] fix: refine only negative address filter behaviour --- src/ipips/ipip-0484.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 87d737c2..7ade57b0 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -51,11 +51,12 @@ The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v - `unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering. - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). - Negative filtering is done by prefixing the protocol name with `!`, e.g. `?filter-addrs=!quic-v1,!tcp`. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND). -- For an address to pass the filter, it must pass all negative filters AND match at least one positive filter. -- Only multiaddrs that pass the filter are included in the response. +- If no parameter is passed, the default behavior is to return the original list of addresses unchanged. +- If only negative filters are provided, addresses not passing any of the negative filters are included. +- If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included. +- If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included. - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. - Filtering is case-insensitive. -- If no parameter is passed, the default behavior is to not apply filtering by network transports. ### Transfer Protocol Filtering From afdda724516da70907954593692f8e0f4f0e100e Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Wed, 25 Sep 2024 16:11:43 +0200 Subject: [PATCH 16/23] Update ipip-0484.md Co-authored-by: Marcin Rataj --- src/ipips/ipip-0484.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 7ade57b0..eac2cc98 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -64,7 +64,8 @@ The proposed change is to add a `?filter-protocols` parameter to the `GET /routi - Add a `?filter-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` to filter providers based on the `Protocol` field of the [Peer schema] . - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. -- Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). Implementations should not break when encountering unknown transfer protocol names. +- Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). +- Implementations MUST ignore unknown transfer protocol names. - `unknown` can be be passed to include providers whose transfer protocol is unknown, e.g. `?filter-protocols=unknown`. This allows filtering providers returned from the DHT that do not contain explicit transfer protocol information. - Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. From 37cd8eb34fa0a1203073fd886244eac001d5642c Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Wed, 25 Sep 2024 16:12:44 +0200 Subject: [PATCH 17/23] Update ipip-0484.md Co-authored-by: Marcin Rataj --- src/ipips/ipip-0484.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index eac2cc98..f36251f3 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -50,7 +50,7 @@ The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v - The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`. - `unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering. - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). -- Negative filtering is done by prefixing the protocol name with `!`, e.g. `?filter-addrs=!quic-v1,!tcp`. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND). +- Negative filtering is done by prefixing the protocol name with `!`, e.g. to skip IPv6 and QUIC addrs: `?filter-addrs=!ip6,!quic-v1`. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND). - If no parameter is passed, the default behavior is to return the original list of addresses unchanged. - If only negative filters are provided, addresses not passing any of the negative filters are included. - If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included. From 601a4971bfa2bbbccb82afb7325e8830d45c7482 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 27 Sep 2024 11:27:05 +0200 Subject: [PATCH 18/23] fix: linting --- src/ipips/ipip-0484.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index f36251f3..1f326db5 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -62,7 +62,7 @@ The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v The proposed change is to add a `?filter-protocols` parameter to the `GET /routing/v1/providers/{cid}` and `GET /routing/v1/peers/{peer-id}` endpoints of :cite[http-routing-v1]: -- Add a `?filter-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` to filter providers based on the `Protocol` field of the [Peer schema] . +- Add a `?filter-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` to filter providers based on the `Protocol` field of the [Peer schema]. - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. - Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). - Implementations MUST ignore unknown transfer protocol names. From ee9b62ee24ca12f7797535d3f9bc71e5eb542ceb Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 27 Sep 2024 11:28:44 +0200 Subject: [PATCH 19/23] fix: linting --- src/ipips/ipip-0484.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 1f326db5..eb9a7086 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -64,7 +64,7 @@ The proposed change is to add a `?filter-protocols` parameter to the `GET /routi - Add a `?filter-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` to filter providers based on the `Protocol` field of the [Peer schema]. - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. -- Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). +- Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). - Implementations MUST ignore unknown transfer protocol names. - `unknown` can be be passed to include providers whose transfer protocol is unknown, e.g. `?filter-protocols=unknown`. This allows filtering providers returned from the DHT that do not contain explicit transfer protocol information. - Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). From 4a1f33b4196dc457d3042e08611d92ee6591ee0a Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Fri, 27 Sep 2024 14:45:02 +0200 Subject: [PATCH 20/23] Apply suggestions from code review Co-authored-by: Marcin Rataj --- src/ipips/ipip-0484.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index eb9a7086..1d45d28b 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -1,5 +1,5 @@ --- -title: 'IPIP-0484: Delegated Routing V1 Support for Querying Specific Network Transport and Transfer Protocols' +title: 'IPIP-0484: Opt-in Provider and Peer Filtering in Routing V1 HTTP API' date: 2024-09-03 ipip: proposal editors: @@ -58,15 +58,15 @@ The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. - Filtering is case-insensitive. -### Transfer Protocol Filtering +### IPFS Protocol Filtering The proposed change is to add a `?filter-protocols` parameter to the `GET /routing/v1/providers/{cid}` and `GET /routing/v1/peers/{peer-id}` endpoints of :cite[http-routing-v1]: - Add a `?filter-protocols=` optional parameter to `GET /routing/v1/providers/{CID}` to filter providers based on the `Protocol` field of the [Peer schema]. - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. - Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). -- Implementations MUST ignore unknown transfer protocol names. -- `unknown` can be be passed to include providers whose transfer protocol is unknown, e.g. `?filter-protocols=unknown`. This allows filtering providers returned from the DHT that do not contain explicit transfer protocol information. +- Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them. +- A special `unknown` name can be be passed to include providers whose transfer protocol list is empty (unknown), e.g. `?filter-protocols=unknown`. This allows for including providers returned from the DHT that do not contain explicit transfer protocol information. - Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. - If a provider passes the filter, it is returned unchanged, i.e. the full set of protocols is returned including protocols that not included in the filter. (note that this is different from `filter-addrs` where only the multiaddrs that pass the filter are returned) @@ -74,7 +74,7 @@ The proposed change is to add a `?filter-protocols` parameter to the `GET /routi - If no parameter is passed, the default behavior is to not filter by transfer protocol. :::note -Even though existing transfer protocol names start with `transport`, e.g. `transport-bitswap`, `transport-graphsync-filecoinv1`, and `transport-ipfs-gateway-http`. This is not to be confused with the network transport protocols, which are filtered using the `filter-addrs` parameter. +Even though some of existing IPFS transfer protocol names start with `transport`, e.g. `transport-bitswap`, `transport-graphsync-filecoinv1`, and `transport-ipfs-gateway-http`, they should not to be confused with the network transport protocols used in peer addresses, which are filtered using the `filter-addrs` parameter. ::: ## Design rationale From 89d5d453ca3068fd2d52610cae85fd1bf33fb7ef Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Fri, 27 Sep 2024 14:45:20 +0200 Subject: [PATCH 21/23] Update src/ipips/ipip-0484.md Co-authored-by: Marcin Rataj --- src/ipips/ipip-0484.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 1d45d28b..77dde69d 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -42,7 +42,7 @@ In the context of this IPIP, we refer to the network layer transport protocol, e ## Detailed design -### Network Transport Protocol Filtering +### Network Address Filtering The proposed change is to add a `?filter-addrs` parameter to the `GET /routing/v1/providers/{cid}` and `GET /routing/v1/peers/{peer-id}` endpoints of :cite[http-routing-v1]: From 2171e9c37861e69f7649e81566ac3ae61d8fb78e Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 27 Sep 2024 15:01:13 +0200 Subject: [PATCH 22/23] docs: add filtering to the http routing spec --- src/routing/http-routing-v1.md | 52 ++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index edd30cea..7b9a78e1 100644 --- a/src/routing/http-routing-v1.md +++ b/src/routing/http-routing-v1.md @@ -65,6 +65,32 @@ This API uses a standard version prefix in the path, such as `/v1/...`. If a bac - `cid` is the [CID](https://github.com/multiformats/cid) to fetch provider records for. +#### Request Query Parameters + +- `?filter-addrs`: Network Address Filtering + - `?filter-addrs=` optional parameter that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. + - The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`. + - `unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering. + - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). + - Negative filtering is done by prefixing the protocol name with `!`, e.g. to skip IPv6 and QUIC addrs: `?filter-addrs=!ip6,!quic-v1`. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND). + - If no parameter is passed, the default behavior is to return the original list of addresses unchanged. + - If only negative filters are provided, addresses not passing any of the negative filters are included. + - If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included. + - If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included. + - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. + - Filtering is case-insensitive. +- `?filter-protocols`: IPFS Protocol Filtering + - `?filter-protocols=` optional parameter to filter providers based on the `Protocol` field of the [Peer schema]. + - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. + - Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). + - Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them. + - A special `unknown` name can be be passed to include providers whose transfer protocol list is empty (unknown), e.g. `?filter-protocols=unknown`. This allows for including providers returned from the DHT that do not contain explicit transfer protocol information. + - Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). + - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. + - If a provider passes the filter, it is returned unchanged, i.e. the full set of protocols is returned including protocols that not included in the filter. (note that this is different from `filter-addrs` where only the multiaddrs that pass the filter are returned) + - Filtering is case-insensitive. + - If no parameter is passed, the default behavior is to not filter by transfer protocol. + #### Response Status Codes - `200` (OK): the response body contains 0 or more records. @@ -113,6 +139,32 @@ Each object in the `Providers` list is a record conforming to a schema, usually - `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. +#### Request Query Parameters + +- `?filter-addrs`: Network Address Filtering + - `?filter-addrs=` optional parameter that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. + - The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`. + - `unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering. + - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). + - Negative filtering is done by prefixing the protocol name with `!`, e.g. to skip IPv6 and QUIC addrs: `?filter-addrs=!ip6,!quic-v1`. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND). + - If no parameter is passed, the default behavior is to return the original list of addresses unchanged. + - If only negative filters are provided, addresses not passing any of the negative filters are included. + - If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included. + - If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included. + - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. + - Filtering is case-insensitive. +- `?filter-protocols`: IPFS Protocol Filtering + - `?filter-protocols=` optional parameter to filter providers based on the `Protocol` field of the [Peer schema]. + - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. + - Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). + - Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them. + - A special `unknown` name can be be passed to include providers whose transfer protocol list is empty (unknown), e.g. `?filter-protocols=unknown`. This allows for including providers returned from the DHT that do not contain explicit transfer protocol information. + - Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). + - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. + - If a provider passes the filter, it is returned unchanged, i.e. the full set of protocols is returned including protocols that not included in the filter. (note that this is different from `filter-addrs` where only the multiaddrs that pass the filter are returned) + - Filtering is case-insensitive. + - If no parameter is passed, the default behavior is to not filter by transfer protocol. + #### Response Status Codes - `200` (OK): the response body contains the peer record. From 3f4a4304ca7435222a3b93a4e7ac28f86f661df9 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 30 Oct 2024 00:00:23 +0100 Subject: [PATCH 23/23] chore: ratification and final editorials removed duplicated content, adjusted examples to follow closer real world examples of what we do today --- src/ipips/ipip-0484.md | 9 ++-- src/routing/http-routing-v1.md | 97 ++++++++++++++++------------------ 2 files changed, 51 insertions(+), 55 deletions(-) diff --git a/src/ipips/ipip-0484.md b/src/ipips/ipip-0484.md index 77dde69d..bbf3b79c 100644 --- a/src/ipips/ipip-0484.md +++ b/src/ipips/ipip-0484.md @@ -1,7 +1,7 @@ --- -title: 'IPIP-0484: Opt-in Provider and Peer Filtering in Routing V1 HTTP API' -date: 2024-09-03 -ipip: proposal +title: 'IPIP-0484: Opt-in Filtering in Routing V1 HTTP API' +date: 2024-10-29 +ipip: ratified editors: - name: Daniel Norman github: 2color @@ -9,7 +9,8 @@ editors: name: Shipyard url: https://ipshipyard.com relatedIssues: - - https://github.com/ipfs-shipyard/someguy/issues/13 + - https://github.com/ipfs/ipfs-check/issues/70 + - https://github.com/ipfs/boxo/pull/678 order: 484 tags: ['ipips'] --- diff --git a/src/routing/http-routing-v1.md b/src/routing/http-routing-v1.md index 7b9a78e1..8108a247 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, peer routing and naming to another process/server. This specification describes an HTTP API for delegated routing of content, peers, and IPNS. -date: 2024-03-22 +date: 2024-10-29 maturity: reliable editors: - name: Gus Eggert @@ -21,14 +21,19 @@ editors: url: https://hacdias.com/ github: hacdias affiliation: - name: Protocol Labs - url: https://protocol.ai/ + name: Shipyard + url: https://ipshipyard.com - name: Marcin Rataj github: lidel url: https://lidel.org/ affiliation: - name: Protocol Labs - url: https://protocol.ai/ + name: Shipyard + url: https://ipshipyard.com + - name: Daniel Norman + github: 2color + affiliation: + name: Shipyard + url: https://ipshipyard.com xref: - ipns-record order: 0 @@ -67,29 +72,35 @@ This API uses a standard version prefix in the path, such as `/v1/...`. If a bac #### Request Query Parameters -- `?filter-addrs`: Network Address Filtering - - `?filter-addrs=` optional parameter that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. - - The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`. - - `unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering. - - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). - - Negative filtering is done by prefixing the protocol name with `!`, e.g. to skip IPv6 and QUIC addrs: `?filter-addrs=!ip6,!quic-v1`. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND). - - If no parameter is passed, the default behavior is to return the original list of addresses unchanged. - - If only negative filters are provided, addresses not passing any of the negative filters are included. - - If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included. - - If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included. - - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. - - Filtering is case-insensitive. -- `?filter-protocols`: IPFS Protocol Filtering - - `?filter-protocols=` optional parameter to filter providers based on the `Protocol` field of the [Peer schema]. - - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. - - Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). - - Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them. - - A special `unknown` name can be be passed to include providers whose transfer protocol list is empty (unknown), e.g. `?filter-protocols=unknown`. This allows for including providers returned from the DHT that do not contain explicit transfer protocol information. - - Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). - - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. - - If a provider passes the filter, it is returned unchanged, i.e. the full set of protocols is returned including protocols that not included in the filter. (note that this is different from `filter-addrs` where only the multiaddrs that pass the filter are returned) - - Filtering is case-insensitive. - - If no parameter is passed, the default behavior is to not filter by transfer protocol. +##### `filter-addrs` (providers request query parameter) + +Optional `?filter-addrs` to apply Network Address Filtering from [IPIP-484](https://specs.ipfs.tech/ipips/ipip-0484/). + +- `?filter-addrs=` optional parameter that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema](#peer-schema). +- The value of the `filter-addrs` parameter is a comma-separated (`,` or `%2C`) list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=tls,webrtc-direct,webtransport`. +- `unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows for not removing providers whose multiaddrs are unknown at the time of filtering (e.g. keeping DHT results that require additional peer lookup). +- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). +- Negative filtering is done by prefixing the protocol name with `!`, e.g. to skip IPv6 and QUIC addrs: `?filter-addrs=!ip6,!quic-v1`. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND). +- If no parameter is passed, the default behavior is to return the original list of addresses unchanged. +- If only negative filters are provided, addresses not passing any of the negative filters are included. +- If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included. +- If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included. +- If there are no multiaddrs that match the passed transports, the provider is omitted from the response. +- Filtering is case-insensitive. + +##### `filter-protocols` (providers request query parameter) + +Optional `?filter-protocols` to apply IPFS Protocol Filtering from [IPIP-484](https://specs.ipfs.tech/ipips/ipip-0484/). + +- The `filter-protocols` parameter is a comma-separated (`,` or `%2C`) list of transfer protocol names, e.g. `?filter-protocols=unknown,transport-bitswap,transport-ipfs-gateway-http`. +- Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). +- Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them. +- A special `unknown` name can be be passed to include providers whose transfer protocol list is empty (unknown), e.g. `?filter-protocols=unknown`. This allows for including providers returned from the DHT that do not contain explicit transfer protocol information. +- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). +- If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. +- If a provider passes the filter, it is returned unchanged, i.e. the full set of protocols is returned including protocols that not included in the filter. (note that this is different from `filter-addrs` where only the multiaddrs that pass the filter are returned) +- Filtering is case-insensitive. +- If no parameter is passed, the default behavior is to not filter by transfer protocol. #### Response Status Codes @@ -141,29 +152,13 @@ represented as a CIDv1 encoded with `libp2p-key` codec. #### Request Query Parameters -- `?filter-addrs`: Network Address Filtering - - `?filter-addrs=` optional parameter that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema]. - - The value of the `filter-addrs` parameter is a comma-separated list of network transport protocol _name strings_ as defined in the [multiaddr protocol registry](https://github.com/multiformats/multiaddr/blob/master/protocols.csv), e.g. `?filter-addrs=webtransport`. - - `unknown` can be be passed to include providers whose multiaddrs are unknown, e.g. `?filter-addrs=unknown`. This allows filtering providers whose multiaddrs are unknown at the time of filtering. - - Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR). - - Negative filtering is done by prefixing the protocol name with `!`, e.g. to skip IPv6 and QUIC addrs: `?filter-addrs=!ip6,!quic-v1`. Note that negative filtering is done by checking if the protocol name does not appear in any of the multiaddrs (logical AND). - - If no parameter is passed, the default behavior is to return the original list of addresses unchanged. - - If only negative filters are provided, addresses not passing any of the negative filters are included. - - If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included. - - If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included. - - If there are no multiaddrs that match the passed transports, the provider is omitted from the response. - - Filtering is case-insensitive. -- `?filter-protocols`: IPFS Protocol Filtering - - `?filter-protocols=` optional parameter to filter providers based on the `Protocol` field of the [Peer schema]. - - The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`. - - Transfer protocols names should be treated as opaque strings and have a max length of 63 characters. A non-exhaustive list of transfer protocols are defined per convention in the [multicodec registry](https://github.com/multiformats/multicodec/blob/3b7b52deb31481790bc4bae984d8675bda4e0c82/table.csv#L149-L151). - - Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them. - - A special `unknown` name can be be passed to include providers whose transfer protocol list is empty (unknown), e.g. `?filter-protocols=unknown`. This allows for including providers returned from the DHT that do not contain explicit transfer protocol information. - - Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR). - - If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response. - - If a provider passes the filter, it is returned unchanged, i.e. the full set of protocols is returned including protocols that not included in the filter. (note that this is different from `filter-addrs` where only the multiaddrs that pass the filter are returned) - - Filtering is case-insensitive. - - If no parameter is passed, the default behavior is to not filter by transfer protocol. +##### `filter-addrs` (peers request query parameter) + +Optional, same rules as [`filter-addrs` providers request query parameter](#filter-addrs-providers-request-query-parameter). + +##### `filter-protocols` (peers request query parameter) + +Optional, same rules as [`filter-protocols` providers request query parameter](#filter-protocols-providers-request-query-parameter). #### Response Status Codes