Skip to content

Commit 847dc6d

Browse files
seetadevseetadev
authored
Merge pull request #916 from sumanjeet0012/feature/rendezvous
feat: Implement Rendezvous module in py-libp2p
2 parents 14fc7fd + bc18110 commit 847dc6d

29 files changed

+4302
-2
lines changed

‎Makefile‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,8 @@ PB = libp2p/crypto/pb/crypto.proto \
6161
libp2p/host/autonat/pb/autonat.proto \
6262
libp2p/relay/circuit_v2/pb/circuit.proto \
6363
libp2p/relay/circuit_v2/pb/dcutr.proto \
64-
libp2p/kad_dht/pb/kademlia.proto
64+
libp2p/kad_dht/pb/kademlia.proto \
65+
libp2p/discovery/rendezvous/pb/rendezvous.proto
6566

6667
PY = $(PB:.proto=_pb2.py)
6768
PYI = $(PB:.proto=_pb2.pyi)

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ ______________________________________________________________________
6666
| **`bootstrap`** | ✅ | [source](https://github.com/libp2p/py-libp2p/tree/main/libp2p/discovery/bootstrap) |
6767
| **`random-walk`** | ✅ | [source](https://github.com/libp2p/py-libp2p/tree/main/libp2p/discovery/random_walk) |
6868
| **`mdns-discovery`** | ✅ | [source](https://github.com/libp2p/py-libp2p/tree/main/libp2p/discovery/mdns) |
69-
| **`rendezvous`** | 🌱 | |
69+
| **`rendezvous`** | ✅ | [source](https://github.com/libp2p/py-libp2p/tree/main/libp2p/discovery/rendezvous) |
7070

7171
______________________________________________________________________
7272

‎docs/examples.rendezvous.rst‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
Rendezvous Protocol Demo
2+
========================
3+
4+
This example demonstrates the **rendezvous protocol** for peer discovery in libp2p networks. The rendezvous protocol allows peers to register under namespaces and discover other peers within the same namespace, facilitating peer-to-peer communication without requiring direct connections.
5+
6+
Overview
7+
--------
8+
9+
The rendezvous protocol consists of two main components:
10+
11+
1. **Rendezvous Server**: Acts as a registry where peers can register and discover each other
12+
2. **Rendezvous Client**: Registers with the server and discovers other peers in the same namespace
13+
14+
Key Features
15+
------------
16+
17+
- **Namespace-based Discovery**: Peers register under specific namespaces for organized discovery
18+
- **Automatic Refresh**: Optional background refresh to maintain registrations and discovery cache
19+
- **TTL Management**: Time-based expiration of registrations to prevent stale entries
20+
- **Peer Advertisement**: Peers can advertise their presence and availability
21+
- **Scalable Discovery**: Efficient peer discovery without flooding the network
22+
23+
Quick Start
24+
-----------
25+
26+
1. **Install py-libp2p:**
27+
28+
.. code-block:: console
29+
30+
$ python -m pip install libp2p
31+
32+
2. **Start a Rendezvous Server:**
33+
34+
.. code-block:: console
35+
36+
$ python rendezvous.py --mode server
37+
2025-09-21 14:05:47,378 [INFO] [libp2p.discovery.rendezvous.service] Rendezvous service started
38+
2025-09-21 14:05:47,378 [INFO] [rendezvous_example] Rendezvous server started with peer ID: Qmey5ZN9WjvtjzYrDfv3NYUY61tusn1qyHAWpuT5vaWUUR
39+
2025-09-21 14:05:47,378 [INFO] [rendezvous_example] Listening on: /ip4/0.0.0.0/tcp/51302/p2p/Qmey5ZN9WjvtjzYrDfv3NYUY61tusn1qyHAWpuT5vaWUUR
40+
2025-09-21 14:05:47,378 [INFO] [rendezvous_example] To connect a client, use:
41+
2025-09-21 14:05:47,378 [INFO] [rendezvous_example] python rendezvous.py --mode client --address /ip4/0.0.0.0/tcp/51302/p2p/Qmey5ZN9WjvtjzYrDfv3NYUY61tusn1qyHAWpuT5vaWUUR
42+
2025-09-21 14:05:47,378 [INFO] [rendezvous_example] Press Ctrl+C to stop...
43+
44+
3. **Connect Clients (in separate terminals):**
45+
46+
.. code-block:: console
47+
48+
$ python rendezvous.py --mode client --address /ip4/0.0.0.0/tcp/51302/p2p/Qmey5ZN9WjvtjzYrDfv3NYUY61tusn1qyHAWpuT5vaWUUR
49+
2025-09-21 14:07:07,641 [INFO] [rendezvous_example] Connected to rendezvous server: Qmey5ZN9WjvtjzYrDfv3NYUY61tusn1qyHAWpuT5vaWUUR
50+
2025-09-21 14:07:07,641 [INFO] [rendezvous_example] Enable refresh: True
51+
2025-09-21 14:07:07,641 [INFO] [rendezvous_example] 🔄 Refresh mode enabled - discovery service running in background
52+
2025-09-21 14:07:07,642 [INFO] [rendezvous_example] Client started with peer ID: QmWyrP7nwTaDDaM4CayBybs6aATNM4CYmbmXDU6oPADN7Y
53+
2025-09-21 14:07:07,644 [INFO] [rendezvous_example] Registering in namespace 'rendezvous'...
54+
2025-09-21 14:07:07,645 [INFO] [rendezvous_example] ✓ Registered with TTL 7200s
55+
2025-09-21 14:07:08,652 [INFO] [rendezvous_example] Discovering peers in namespace 'rendezvous'...
56+
2025-09-21 14:07:08,653 [INFO] [rendezvous_example] Found self: QmWyrP7nwTaDDaM4CayBybs6aATNM4CYmbmXDU6oPADN7Y
57+
2025-09-21 14:07:08,653 [INFO] [rendezvous_example] Total peers found: 1
58+
2025-09-21 14:07:08,653 [INFO] [rendezvous_example] No other peers found (only self)
59+
60+
Usage Examples
61+
--------------
62+
63+
Basic Server
64+
~~~~~~~~~~~~
65+
66+
Start a rendezvous server on a specific port:
67+
68+
.. code-block:: console
69+
70+
$ python rendezvous.py --mode server --port 8080
71+
72+
Client with Custom Namespace
73+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
74+
75+
Register and discover peers in a custom namespace:
76+
77+
.. code-block:: console
78+
79+
$ python rendezvous.py --mode client --address <server_multiaddr> --namespace "my-app"
80+
81+
Client without Refresh
82+
~~~~~~~~~~~~~~~~~~~~~~
83+
84+
Run a client without automatic refresh (single-shot mode):
85+
86+
.. code-block:: console
87+
88+
$ python rendezvous.py --mode client --address <server_multiaddr> --refresh False
89+
90+
Verbose Logging
91+
~~~~~~~~~~~~~~~
92+
93+
Enable debug logging for detailed information:
94+
95+
.. code-block:: console
96+
97+
$ python rendezvous.py --mode server --verbose
98+
99+
Command Line Options
100+
--------------------
101+
102+
.. code-block:: text
103+
104+
usage: rendezvous.py [-h] [--mode {server,client}] [--address [ADDRESS]]
105+
[-p PORT] [-n NAMESPACE] [-v] [-r]
106+
107+
optional arguments:
108+
-h, --help show this help message and exit
109+
--mode {server,client}
110+
Run as server or client
111+
--address [ADDRESS] Server multiaddr (required for client mode)
112+
-p PORT, --port PORT Port for server to listen on (default: random)
113+
-n NAMESPACE, --namespace NAMESPACE
114+
Namespace to register/discover in (default: rendezvous)
115+
-v, --verbose Enable verbose logging
116+
-r, --refresh Enable automatic refresh for registration and discovery cache
117+
118+
Protocol Flow
119+
-------------
120+
121+
1. **Server Setup**: The rendezvous server starts and listens for incoming connections
122+
2. **Client Connection**: Clients connect to the server using its multiaddr
123+
3. **Registration**: Clients register themselves under a namespace with a TTL
124+
4. **Discovery**: Clients query the server for other peers in the same namespace
125+
5. **Refresh**: (Optional) Clients automatically refresh their registration before TTL expires
126+
6. **Unregistration**: Clients cleanly unregister when shutting down
127+
128+
Key Components
129+
--------------
130+
131+
RendezvousService
132+
~~~~~~~~~~~~~~~~~
133+
134+
The server-side component that:
135+
136+
- Manages peer registrations by namespace
137+
- Handles registration, unregistration, and discovery requests
138+
- Automatically cleans up expired registrations
139+
- Provides namespace statistics
140+
141+
RendezvousDiscovery
142+
~~~~~~~~~~~~~~~~~~~
143+
144+
The client-side component that:
145+
146+
- Registers the local peer under namespaces
147+
- Discovers other peers in namespaces
148+
- Optionally runs background refresh tasks
149+
- Manages registration TTL and cache refresh
150+
151+
Configuration
152+
-------------
153+
154+
Default values can be customized:
155+
156+
.. code-block:: python
157+
158+
from libp2p.discovery.rendezvous import config
159+
160+
# Default namespace for registrations
161+
config.DEFAULT_NAMESPACE = "rendezvous"
162+
163+
# Default TTL for registrations (2 hours)
164+
config.DEFAULT_TTL = 2 * 3600
165+
166+
# Maximum number of registrations per namespace
167+
config.MAX_REGISTRATIONS = 1000
168+
169+
# Maximum TTL allowed
170+
config.MAX_TTL = 24 * 3600 # 24 hours
171+
172+
Refresh Mode
173+
------------
174+
175+
When refresh mode is enabled (default), the client:
176+
177+
- Automatically re-registers before the TTL expires (at 80% of TTL)
178+
- Refreshes the discovery cache periodically
179+
- Runs a background service using trio's structured concurrency
180+
- Maintains long-term presence in the network
181+
182+
This is ideal for long-running applications that need continuous peer discovery.
183+
184+
Use Cases
185+
---------
186+
187+
- **Distributed Applications**: Services that need to find each other dynamically
188+
- **Gaming**: Players discovering game sessions or lobbies
189+
- **Content Sharing**: Nodes advertising available content or services
190+
- **Mesh Networks**: Peers discovering neighbors in decentralized networks
191+
- **Service Discovery**: Microservices finding each other in P2P architectures
192+
193+
Error Handling
194+
--------------
195+
196+
The implementation includes robust error handling:
197+
198+
- Connection failures to rendezvous servers
199+
- Registration timeouts and failures
200+
- Discovery query errors
201+
- Background refresh task failures
202+
- Network connectivity issues
203+
204+
Best Practices
205+
--------------
206+
207+
1. **Use descriptive namespaces** to organize different types of peers
208+
2. **Enable refresh mode** for long-running applications
209+
3. **Set appropriate TTL values** based on your application's needs
210+
4. **Handle connection failures** gracefully in production code
211+
5. **Monitor namespace statistics** on the server for debugging
212+
6. **Use verbose logging** during development and testing
213+
214+
Source Code
215+
-----------
216+
217+
.. literalinclude:: ../examples/rendezvous/rendezvous.py
218+
:language: python
219+
:linenos:
220+
221+
API Reference
222+
-------------
223+
224+
For detailed API documentation, see:
225+
226+
- :doc:`libp2p.discovery` - Discovery protocol interfaces
227+
- :doc:`libp2p.discovery.rendezvous` - Rendezvous implementation details

‎docs/examples.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,5 +15,6 @@ Examples
1515
examples.circuit_relay
1616
examples.kademlia
1717
examples.mDNS
18+
examples.rendezvous
1819
examples.random_walk
1920
examples.multiple_connections

‎docs/libp2p.discovery.rendezvous.pb.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
libp2p.discovery.rendezvous.pb package
2+
======================================
3+
4+
Submodules
5+
----------
6+
7+
libp2p.discovery.rendezvous.pb.rendezvous\_pb2 module
8+
-----------------------------------------------------
9+
10+
.. automodule:: libp2p.discovery.rendezvous.pb.rendezvous_pb2
11+
:members:
12+
:show-inheritance:
13+
:undoc-members:
14+
15+
Module contents
16+
---------------
17+
18+
.. automodule:: libp2p.discovery.rendezvous.pb
19+
:members:
20+
:show-inheritance:
21+
:undoc-members:

‎docs/libp2p.discovery.rendezvous.rst‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
libp2p.discovery.rendezvous module
2+
===================================
3+
4+
.. automodule:: libp2p.discovery.rendezvous
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
9+
Submodules
10+
----------
11+
12+
libp2p.discovery.rendezvous.client module
13+
------------------------------------------
14+
15+
.. automodule:: libp2p.discovery.rendezvous.client
16+
:members:
17+
:undoc-members:
18+
:show-inheritance:
19+
20+
libp2p.discovery.rendezvous.service module
21+
-------------------------------------------
22+
23+
.. automodule:: libp2p.discovery.rendezvous.service
24+
:members:
25+
:undoc-members:
26+
:show-inheritance:
27+
28+
libp2p.discovery.rendezvous.discovery module
29+
---------------------------------------------
30+
31+
.. automodule:: libp2p.discovery.rendezvous.discovery
32+
:members:
33+
:undoc-members:
34+
:show-inheritance:
35+
36+
libp2p.discovery.rendezvous.config module
37+
------------------------------------------
38+
39+
.. automodule:: libp2p.discovery.rendezvous.config
40+
:members:
41+
:undoc-members:
42+
:show-inheritance:
43+
44+
libp2p.discovery.rendezvous.messages module
45+
--------------------------------------------
46+
47+
.. automodule:: libp2p.discovery.rendezvous.messages
48+
:members:
49+
:undoc-members:
50+
:show-inheritance:
51+
52+
Subpackages
53+
-----------
54+
55+
.. toctree::
56+
:maxdepth: 4
57+
58+
libp2p.discovery.rendezvous.pb

‎docs/libp2p.discovery.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Subpackages
1111
libp2p.discovery.events
1212
libp2p.discovery.mdns
1313
libp2p.discovery.random_walk
14+
libp2p.discovery.rendezvous
1415

1516
Submodules
1617
----------

0 commit comments

Comments
 (0)