Skip to content

Commit 3f4a430

Browse files
committed
chore: ratification and final editorials
removed duplicated content, adjusted examples to follow closer real world examples of what we do today
1 parent 2171e9c commit 3f4a430

File tree

2 files changed

+51
-55
lines changed

2 files changed

+51
-55
lines changed

src/ipips/ipip-0484.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
---
2-
title: 'IPIP-0484: Opt-in Provider and Peer Filtering in Routing V1 HTTP API'
3-
date: 2024-09-03
4-
ipip: proposal
2+
title: 'IPIP-0484: Opt-in Filtering in Routing V1 HTTP API'
3+
date: 2024-10-29
4+
ipip: ratified
55
editors:
66
- name: Daniel Norman
77
github: 2color
88
affiliation:
99
name: Shipyard
1010
url: https://ipshipyard.com
1111
relatedIssues:
12-
- https://github.com/ipfs-shipyard/someguy/issues/13
12+
- https://github.com/ipfs/ipfs-check/issues/70
13+
- https://github.com/ipfs/boxo/pull/678
1314
order: 484
1415
tags: ['ipips']
1516
---

src/routing/http-routing-v1.md

+46-51
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: >
44
Delegated routing is a mechanism for IPFS implementations to use for offloading
55
content routing, peer routing and naming to another process/server. This specification describes
66
an HTTP API for delegated routing of content, peers, and IPNS.
7-
date: 2024-03-22
7+
date: 2024-10-29
88
maturity: reliable
99
editors:
1010
- name: Gus Eggert
@@ -21,14 +21,19 @@ editors:
2121
url: https://hacdias.com/
2222
github: hacdias
2323
affiliation:
24-
name: Protocol Labs
25-
url: https://protocol.ai/
24+
name: Shipyard
25+
url: https://ipshipyard.com
2626
- name: Marcin Rataj
2727
github: lidel
2828
url: https://lidel.org/
2929
affiliation:
30-
name: Protocol Labs
31-
url: https://protocol.ai/
30+
name: Shipyard
31+
url: https://ipshipyard.com
32+
- name: Daniel Norman
33+
github: 2color
34+
affiliation:
35+
name: Shipyard
36+
url: https://ipshipyard.com
3237
xref:
3338
- ipns-record
3439
order: 0
@@ -67,29 +72,35 @@ This API uses a standard version prefix in the path, such as `/v1/...`. If a bac
6772

6873
#### Request Query Parameters
6974

70-
- `?filter-addrs`: Network Address Filtering
71-
- `?filter-addrs=<comma-separated-list>` optional parameter that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema].
72-
- 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`.
73-
- `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.
74-
- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR).
75-
- 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).
76-
- If no parameter is passed, the default behavior is to return the original list of addresses unchanged.
77-
- If only negative filters are provided, addresses not passing any of the negative filters are included.
78-
- If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included.
79-
- If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included.
80-
- If there are no multiaddrs that match the passed transports, the provider is omitted from the response.
81-
- Filtering is case-insensitive.
82-
- `?filter-protocols`: IPFS Protocol Filtering
83-
- `?filter-protocols=<comma-separated-list>` optional parameter to filter providers based on the `Protocol` field of the [Peer schema].
84-
- The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`.
85-
- 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).
86-
- Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them.
87-
- 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.
88-
- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR).
89-
- If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response.
90-
- 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)
91-
- Filtering is case-insensitive.
92-
- If no parameter is passed, the default behavior is to not filter by transfer protocol.
75+
##### `filter-addrs` (providers request query parameter)
76+
77+
Optional `?filter-addrs` to apply Network Address Filtering from [IPIP-484](https://specs.ipfs.tech/ipips/ipip-0484/).
78+
79+
- `?filter-addrs=<comma-separated-list>` optional parameter that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema](#peer-schema).
80+
- 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`.
81+
- `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).
82+
- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR).
83+
- 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).
84+
- If no parameter is passed, the default behavior is to return the original list of addresses unchanged.
85+
- If only negative filters are provided, addresses not passing any of the negative filters are included.
86+
- If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included.
87+
- If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included.
88+
- If there are no multiaddrs that match the passed transports, the provider is omitted from the response.
89+
- Filtering is case-insensitive.
90+
91+
##### `filter-protocols` (providers request query parameter)
92+
93+
Optional `?filter-protocols` to apply IPFS Protocol Filtering from [IPIP-484](https://specs.ipfs.tech/ipips/ipip-0484/).
94+
95+
- 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`.
96+
- 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).
97+
- Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them.
98+
- 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.
99+
- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR).
100+
- If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response.
101+
- 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)
102+
- Filtering is case-insensitive.
103+
- If no parameter is passed, the default behavior is to not filter by transfer protocol.
93104

94105
#### Response Status Codes
95106

@@ -141,29 +152,13 @@ represented as a CIDv1 encoded with `libp2p-key` codec.
141152

142153
#### Request Query Parameters
143154

144-
- `?filter-addrs`: Network Address Filtering
145-
- `?filter-addrs=<comma-separated-list>` optional parameter that indicates which network transports to return by filtering the multiaddrs in the `Addrs` field of the [Peer schema].
146-
- 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`.
147-
- `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.
148-
- Multiaddrs are filtered by checking if the protocol name appears in any of the multiaddrs (logical OR).
149-
- 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).
150-
- If no parameter is passed, the default behavior is to return the original list of addresses unchanged.
151-
- If only negative filters are provided, addresses not passing any of the negative filters are included.
152-
- If positive filters are provided, only addresses passing at least one positive filter (and no negative filters) are included.
153-
- If both positive and negative filters are provided, the address must pass all negative filters and at least one positive filter to be included.
154-
- If there are no multiaddrs that match the passed transports, the provider is omitted from the response.
155-
- Filtering is case-insensitive.
156-
- `?filter-protocols`: IPFS Protocol Filtering
157-
- `?filter-protocols=<comma-separated-list>` optional parameter to filter providers based on the `Protocol` field of the [Peer schema].
158-
- The `filter-protocols` parameter is a comma-separated list of transfer protocol names, e.g. `?filter-protocols=transport-bitswap`.
159-
- 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).
160-
- Implementations MUST preserve all transfer protocol names when returning a positive result that matches one or more of them.
161-
- 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.
162-
- Providers are filtered by checking if the transfer protocol name appears in the `Protocols` array (logical OR).
163-
- If the provider doesn't match any of the passed transfer protocols, the provider is omitted from the response.
164-
- 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)
165-
- Filtering is case-insensitive.
166-
- If no parameter is passed, the default behavior is to not filter by transfer protocol.
155+
##### `filter-addrs` (peers request query parameter)
156+
157+
Optional, same rules as [`filter-addrs` providers request query parameter](#filter-addrs-providers-request-query-parameter).
158+
159+
##### `filter-protocols` (peers request query parameter)
160+
161+
Optional, same rules as [`filter-protocols` providers request query parameter](#filter-protocols-providers-request-query-parameter).
167162

168163
#### Response Status Codes
169164

0 commit comments

Comments
 (0)