routing/http: add support for GetClosestPeers (IPIP-476) #1021

hsanjuan · 2025-09-01T11:50:24Z

Server side

Since FindPeers also returns PeerRecords, it is essentially a copy-paste, minus things like addrFilters which don't apply here, plus count and closerThan parsing from the query URL. The tests as well. We leave all logic regarding count/closerThan to the ContentRouter (the DHT, or the Kubo wrapper around it).

Client side

As the server part, this is heavily inspired in FindPeers.

Content router side:

Added GetClosestPeers support, depends on libp2p/go-libp2p-routing-helpers#93

routing/http/server/server.go

codecov · 2025-09-03T12:48:37Z

Codecov Report

❌ Patch coverage is 80.00000% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.19%. Comparing base (58ff268) to head (17f5746).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
routing/http/client/client.go	78.00%	8 Missing and 3 partials ⚠️
routing/http/server/server.go	83.92%	6 Missing and 3 partials ⚠️
routing/http/contentrouter/contentrouter.go	75.00%	5 Missing and 1 partial ⚠️

@@            Coverage Diff             @@
##             main    #1021      +/-   ##
==========================================
+ Coverage   61.09%   61.19%   +0.09%     
==========================================
  Files         268      268              
  Lines       26162    26284     +122     
==========================================
+ Hits        15984    16084     +100     
- Misses       8503     8519      +16     
- Partials     1675     1681       +6

Files with missing lines	Coverage Δ
routing/http/contentrouter/contentrouter.go	`53.71% <75.00%> (+3.38%)`	⬆️
routing/http/server/server.go	`76.15% <83.92%> (+1.50%)`	⬆️
routing/http/client/client.go	`75.53% <78.00%> (+0.38%)`	⬆️

... and 11 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

guillaumemichel

IIUC this PR isn't linked with the DHT yet, and there is no implementation of GetClosestPeers(ctx, pid, closerThanPid, count) (that doesn't depend on another GetClosestPeers(ctx, pid, closerThanPid, count)).

Is the bridge to the DHT going to be implemented in Kubo? I would like to see how everything fits together before merging this one.

hsanjuan · 2025-09-04T13:14:20Z

Is the bridge to the DHT going to be implemented in Kubo? I would like to see how everything fits together before merging this one.

Right. Yes, it is in Kubo where the bridge to an actual content routing thing happens. At which point we will need to call the DHT method with the DHT we have in Kubo. Perfectly fine to wait for that before merging.

This allows Kubo to respond to the GetClosestPeers() http routing v1 endpoint as spec'ed here: ipfs/specs#476 It is based on work from ipfs/boxo#1021 We let IpfsNode implmement the contentRouter.Client interface with the new method. We use our DHTs to get the closest peers. We try to respect the count/closerThan options here. We then trigger FindPeers lookups to fill-in information about the peers (addresses) and return the result. Tests are missing and will come up once discussions around the spec and the boxo pr have settled.

hsanjuan · 2025-09-16T14:36:01Z

Triage:

@hsanjuan will circle-back on this and related PRs.

I see no reason for it to be exported.

This adds the SERVER-side for GetClosestPeers. Since FindPeers also returns PeerRecords, it is essentially a copy-paste, minus things like addrFilters which don't apply here, plus `count` and `closerThan` parsing from the query URL. The tests as well. We leave all logic regarding count/closerThan to the ContentRouter (the DHT, or the Kubo wrapper around it). Spec: ipfs/specs#476

As the server part, this is heavily inspired in FindPeers.

Changes query parameter from 'closerThan' to 'closer-than' in routing/http client and server to match IPIP-0476 specification.

- clarified parameter behavior in godoc - documented amino dht limitation of 20 peers max - use amino.DefaultBucketSize constant for default count

- introduce DelegatedRouter interface for delegated routing operations - keep ContentRouter as deprecated alias for backward compatibility - update internal server struct to use DelegatedRouter - clarify interface focuses on querying with IPNS publishing support - note that additional publishing methods may be added via IPIP process this better aligns with the Delegated Routing V1 HTTP API spec and clarifies that this interface handles all routing operations (content, peers, values, DHT), not just content routing

This aligns it with latest version of the spec.

This allows Kubo to respond to the GetClosestPeers() http routing v1 endpoint as spec'ed here: ipfs/specs#476 It is based on work from ipfs/boxo#1021 We let IpfsNode implmement the contentRouter.Client interface with the new method. We use our DHTs to get the closest peers. We try to respect the count/closerThan options here. We then trigger FindPeers lookups to fill-in information about the peers (addresses) and return the result. Tests are missing and will come up once discussions around the spec and the boxo pr have settled.

routing/http/client/client.go

routing/http/contentrouter/contentrouter.go

routing/http/server/server.go

…-peers

lidel · 2025-09-30T14:58:25Z

Triage notes:

before merging, open a PR for someguy to see how this behaves end-to-end

routing/http/server/server.go

routing/http/contentrouter/contentrouter.go

…-peers

This allows Kubo to respond to the GetClosestPeers() http routing v1 endpoint as spec'ed here: ipfs/specs#476 It is based on work from ipfs/boxo#1021 We let IpfsNode implmement the contentRouter.Client interface with the new method. We use our DHTs to get the closest peers. We try to respect the count/closerThan options here. We then trigger FindPeers lookups to fill-in information about the peers (addresses) and return the result. Tests are missing and will come up once discussions around the spec and the boxo pr have settled.

- parseKey() utility tries peer.Decode() first, then cid.Decode() - tests use hardcoded examples from libp2p specs - tests verify digest matching (not exact CID) via hex-encoded values - only the multihash digest matters for DHT operations, not CID codec - error messages include both parse failures for better debugging

- routing/http/server accepts CID or PeerID for GetClosestPeers - references IPIP-476

fixes copy-paste error where GetClosestPeers endpoint was logging errors as "FindPeers" instead of "GetClosestPeers"

hsanjuan · 2025-10-20T10:10:34Z

Thank you @lidel . Latest changes LGTM. Would you be so kind to call the shot regarding the DHTRouter interface in libp2p-routing-helpers (commit above from @guillaumemichel)? We can move it here or leave it there. Probably it is the last thing to resolve.

routing/http/server/server.go

…lt (#10954) This allows Kubo to respond to the GetClosestPeers() http routing v1 endpoint as spec'ed here: ipfs/specs#476 It is based on work from ipfs/boxo#1021 We let IpfsNode implmement the contentRouter.Client interface with the new method. We use our WAN-DHT to get the closest peers. Additionally, Routing V1 HTTP API is exposed by default which enables light clients in browsers to use Kubo Gateway as delegated routing backend Co-authored-by: Marcin Rataj <[email protected]>

Final ratification cleanup aligning specs with actual shipped implementation. Changes to IPIP-0476: - change path parameter from {peer-id} to {key} - remove unimplemented query parameters (count, closer-than) - document query parameters in Alternatives section with rationale - add peer sorting requirement (XOR distance for Kademlia DHTs) - update test fixtures to reflect actual API surface - note about raw codec for arbitrary multihash lookups - update date to 2025-11-20 Changes to http-routing-v1.md: - add raw codec documentation for arbitrary multihash lookups - clarify peer sorting requirement (SHOULD, XOR distance) - fix streaming description (remove "more results" language) - add note about streaming being blocked until DHT lookup completes - reorganize frontmatter: move inactive editors to former_editors - add contributors to thanks section - update date to 2025-11-20 Both specs now accurately reflect the API shipped in: - boxo v0.35.2 (ipfs/boxo#1021) - someguy v0.11.0 (https://github.com/ipfs/someguy/releases/tag/v0.11.0)

hsanjuan self-assigned this Sep 1, 2025

guillaumemichel reviewed Sep 2, 2025

View reviewed changes

routing/http/server/server.go Outdated Show resolved Hide resolved

hsanjuan force-pushed the feat/1004-get-closest-peers branch from bd45b83 to c70f108 Compare September 3, 2025 12:44

hsanjuan force-pushed the feat/1004-get-closest-peers branch 2 times, most recently from 6ddfda9 to 3bb649c Compare September 4, 2025 11:39

hsanjuan marked this pull request as ready for review September 4, 2025 11:41

hsanjuan requested a review from a team as a code owner September 4, 2025 11:41

guillaumemichel self-requested a review September 4, 2025 11:57

guillaumemichel reviewed Sep 4, 2025

View reviewed changes

hsanjuan mentioned this pull request Sep 5, 2025

feat: support GetClosesPeers (IPIP-476) and ExposeRoutingAPI by default ipfs/kubo#10954

Merged

3 tasks

hsanjuan and others added 9 commits September 26, 2025 14:09

Unexport private constant

220a690

I see no reason for it to be exported.

routing/http/client: add support for GetClosestPeers

5d4e99e

As the server part, this is heavily inspired in FindPeers.

routing/http/contentrouter: add support for GetClosestPeers

d52bcb1

fix: use 'closer-than' query parameter for spec compliance

0264929

Changes query parameter from 'closerThan' to 'closer-than' in routing/http client and server to match IPIP-0476 specification.

fix: use correct variable in error message for closer-than parameter

39432b9

docs: improve GetClosestPeers godoc and use amino constant

384effb

- clarified parameter behavior in godoc - documented amino dht limitation of 20 peers max - use amino.DefaultBucketSize constant for default count

GetClosestPeers(): remove closer-than and timeout parameters.

0a8bc14

This aligns it with latest version of the spec.

hsanjuan force-pushed the feat/1004-get-closest-peers branch from dbed850 to 0a8bc14 Compare September 26, 2025 12:14

examples: go mod tidy

ce702e0

gammazero requested changes Sep 26, 2025

View reviewed changes

routing/http/client/client.go Outdated Show resolved Hide resolved

routing/http/client/client.go Outdated Show resolved Hide resolved

routing/http/contentrouter/contentrouter.go Outdated Show resolved Hide resolved

routing/http/server/server.go Outdated Show resolved Hide resolved

guillaumemichel self-requested a review September 26, 2025 22:42

Address review

bdb5505

Merge remote-tracking branch 'origin/main' into feat/1004-get-closest…

cd7be90

…-peers

gammazero approved these changes Sep 29, 2025

View reviewed changes

lidel added the status/blocked Unable to be worked further until needs are met label Sep 30, 2025

lidel self-requested a review September 30, 2025 14:58

guillaumemichel reviewed Oct 1, 2025

View reviewed changes

routing/http/server/server.go Show resolved Hide resolved

routing/http/server/server.go Outdated Show resolved Hide resolved

guillaumemichel reviewed Oct 1, 2025

View reviewed changes

routing/http/contentrouter/contentrouter.go Outdated Show resolved Hide resolved

hsanjuan added 2 commits October 16, 2025 10:56

Routing: GetClosestPeers: replace peer.ID argument with CID

07e74fb

Merge remote-tracking branch 'origin/main' into feat/1004-get-closest…

5162f7c

…-peers

lidel added 3 commits October 17, 2025 17:42

docs: add GetClosestPeers changes to CHANGELOG

ce6837e

- routing/http/server accepts CID or PeerID for GetClosestPeers - references IPIP-476

fix(routing/http): correct method name in getClosestPeersJSON logging

3256401

fixes copy-paste error where GetClosestPeers endpoint was logging errors as "FindPeers" instead of "GetClosestPeers"

lidel mentioned this pull request Oct 17, 2025

feat: add "getclosestpeers" support (IPIP-476) ipfs/someguy#124

Merged

1 task

lidel changed the title ~~routing/http: add support for GetClosestPeers()~~ feat: support IPIP-476 and Gateway.ExposeRoutingAPI=true by default Oct 17, 2025

lidel changed the title ~~feat: support IPIP-476 and Gateway.ExposeRoutingAPI=true by default~~ feat: support IPIP-476 and ExposeRoutingAPI by default Oct 17, 2025

lidel changed the title ~~feat: support IPIP-476 and ExposeRoutingAPI by default~~ routing/http: add support for GetClosestPeers (IPIP-476) Oct 17, 2025

hsanjuan removed the status/blocked Unable to be worked further until needs are met label Oct 20, 2025

gammazero reviewed Oct 24, 2025

View reviewed changes

routing/http/server/server.go Show resolved Hide resolved

gammazero and others added 3 commits November 11, 2025 19:48

Merge branch 'main' into feat/1004-get-closest-peers

918fee9

move DHTRouter interface to contentrouter from routing-helpers

86f6bf2

go mod tidy

17f5746

hsanjuan merged commit e71f50e into main Nov 18, 2025
16 checks passed

hsanjuan deleted the feat/1004-get-closest-peers branch November 18, 2025 17:02

lidel mentioned this pull request Nov 20, 2025

IPIP-0476: Delegated Routing DHT Closest Peers API ipfs/specs#476

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

routing/http: add support for GetClosestPeers (IPIP-476) #1021

routing/http: add support for GetClosestPeers (IPIP-476) #1021

Uh oh!

hsanjuan commented Sep 1, 2025 •

edited by lidel

Loading

Uh oh!

Uh oh!

codecov bot commented Sep 3, 2025 •

edited

Loading

Uh oh!

guillaumemichel left a comment

Uh oh!

hsanjuan commented Sep 4, 2025

Uh oh!

hsanjuan commented Sep 16, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lidel commented Sep 30, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hsanjuan commented Oct 20, 2025

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

routing/http: add support for GetClosestPeers (IPIP-476) #1021

routing/http: add support for GetClosestPeers (IPIP-476) #1021

Uh oh!

Conversation

hsanjuan commented Sep 1, 2025 • edited by lidel Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Server side

Client side

Content router side:

Uh oh!

Uh oh!

codecov bot commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

guillaumemichel left a comment

Choose a reason for hiding this comment

Uh oh!

hsanjuan commented Sep 4, 2025

Uh oh!

hsanjuan commented Sep 16, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lidel commented Sep 30, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hsanjuan commented Oct 20, 2025

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

hsanjuan commented Sep 1, 2025 •

edited by lidel

Loading

codecov bot commented Sep 3, 2025 •

edited

Loading