chore: ratification and final editorials

removed duplicated content, adjusted examples to follow closer real
world examples of what we do today

Author: lidel

src/ipips/ipip-0484.md

@@ -1,15 +1,16 @@
 ---
-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
     affiliation:
       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']
 ---

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=<comma-separated-list>` 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=<comma-separated-list>` 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=<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).
+- 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=<comma-separated-list>` 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=<comma-separated-list>` 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