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] 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.