libp2p.discovery.rendezvous module

Rendezvous protocol implementation for py-libp2p.

This module provides both client and server implementations of the rendezvous protocol, allowing peers to advertise themselves and discover other peers through a centralized rendezvous point.

exception libp2p.discovery.rendezvous.InternalError(message: str = 'Internal server error')

Bases: RendezvousError

Raised when server encounters internal error.

exception libp2p.discovery.rendezvous.InvalidCookieError(message: str = 'Invalid cookie')

Bases: RendezvousError

Raised when discovery cookie is invalid.

exception libp2p.discovery.rendezvous.InvalidNamespaceError(message: str = 'Invalid namespace')

Bases: RendezvousError

Raised when namespace is invalid.

exception libp2p.discovery.rendezvous.InvalidPeerInfoError(message: str = 'Invalid peer info')

Bases: RendezvousError

Raised when peer information is invalid.

exception libp2p.discovery.rendezvous.InvalidTTLError(message: str = 'Invalid TTL')

Bases: RendezvousError

Raised when TTL is invalid.

exception libp2p.discovery.rendezvous.NotAuthorizedError(message: str = 'Not authorized')

Bases: RendezvousError

Raised when operation is not authorized.

class libp2p.discovery.rendezvous.RendezvousClient(host: IHost, rendezvous_peer: ID, enable_refresh: bool = False)

Bases: object

Rendezvous client for registering with and discovering peers through a rendezvous point.

async close() → None

Close the client and stop all refresh tasks.

async discover(namespace: str, limit: int = 100, cookie: bytes = b'') → tuple[list[PeerInfo], bytes]

Discover peers in a namespace.

Args:

namespace: Namespace to search limit: Maximum number of peers to return cookie: Pagination cookie from previous request

Returns:

Tuple of (peer list, new cookie for pagination)

Raises:

RendezvousError: If discovery fails

async register(namespace: str, ttl: int = 7200) → float

Register this peer under a namespace.

Args:

namespace: Namespace to register under ttl: Time-to-live in seconds (default 2 hours)

Returns:

Actual TTL granted by the server

Raises:

RendezvousError: If registration fails

set_nursery(nursery: Nursery) → None

Set the nursery for background tasks (called by RendezvousDiscovery).

async unregister(namespace: str) → None

Unregister this peer from a namespace.

Args:

namespace: Namespace to unregister from

class libp2p.discovery.rendezvous.RendezvousDiscovery(host: IHost, rendezvous_peer: ID, enable_refresh: bool = False)

Bases: object

Rendezvous-based peer discovery.

This class provides a high-level interface for peer discovery using the rendezvous protocol, including caching. Registration refresh is handled automatically by the underlying RendezvousClient.

async advertise(namespace: str, ttl: int = 7200) → float

Advertise this peer under a namespace.

Args:

namespace: Namespace to advertise under ttl: Time-to-live in seconds (default 2 hours)

Returns:

Actual TTL granted by the server

clear_cache(namespace: str | None = None) → None

Clear peer cache.

Args:

namespace: Specific namespace to clear, or None for all

async close() → None

Close the discovery service and clean up resources.

async find_all_peers(namespace: str) → list[PeerInfo]

Find all peers in a namespace using pagination.

Args:

namespace: Namespace to search

Returns:

List of all discovered peers

async find_peers(namespace: str, limit: int = 100, force_refresh: bool = False) → AsyncIterator[PeerInfo]

Find peers in a namespace.

Args:

namespace: Namespace to search limit: Maximum number of peers to return force_refresh: Force refresh from server instead of using cache

Yields:

PeerInfo objects for discovered peers

async run() → None

Run the rendezvous discovery service.

async unregister(namespace: str) → None

Stop advertising this peer under a namespace.

Args:

namespace: Namespace to stop advertising under

exception libp2p.discovery.rendezvous.RendezvousError(status: int, message: str = '')

Bases: Exception

Base exception for rendezvous protocol errors.

class libp2p.discovery.rendezvous.RendezvousService(host: IHost)

Bases: object

Rendezvous service for hosting a rendezvous point.

This service allows peers to register under namespaces and discover other peers that have registered under the same namespaces.

cleanup_all_expired() → None

Clean up expired registrations from all namespaces.

get_namespace_stats() → dict[str, int]

Get statistics about registrations per namespace.

exception libp2p.discovery.rendezvous.UnavailableError(message: str = 'Service unavailable')

Bases: RendezvousError

Raised when service is unavailable.

Submodules

libp2p.discovery.rendezvous.client module

Rendezvous client implementation.

class libp2p.discovery.rendezvous.client.RendezvousClient(host: IHost, rendezvous_peer: ID, enable_refresh: bool = False)

Bases: object

Rendezvous client for registering with and discovering peers through a rendezvous point.

async close() → None

Close the client and stop all refresh tasks.

async discover(namespace: str, limit: int = 100, cookie: bytes = b'') → tuple[list[PeerInfo], bytes]

Discover peers in a namespace.

Args:

namespace: Namespace to search limit: Maximum number of peers to return cookie: Pagination cookie from previous request

Returns:

Tuple of (peer list, new cookie for pagination)

Raises:

RendezvousError: If discovery fails

async register(namespace: str, ttl: int = 7200) → float

Register this peer under a namespace.

Args:

namespace: Namespace to register under ttl: Time-to-live in seconds (default 2 hours)

Returns:

Actual TTL granted by the server

Raises:

RendezvousError: If registration fails

set_nursery(nursery: Nursery) → None

Set the nursery for background tasks (called by RendezvousDiscovery).

async unregister(namespace: str) → None

Unregister this peer from a namespace.

Args:

namespace: Namespace to unregister from

libp2p.discovery.rendezvous.service module

Rendezvous service implementation for hosting a rendezvous point.

class libp2p.discovery.rendezvous.service.RegistrationRecord(peer_id: ID, addrs: list[bytes], namespace: str, ttl: int)

Bases: object

Represents a peer registration record.

is_expired() → bool

Check if this registration has expired.

to_protobuf_register() → Register

Convert to protobuf Register message.

class libp2p.discovery.rendezvous.service.RendezvousService(host: IHost)

Bases: object

Rendezvous service for hosting a rendezvous point.

This service allows peers to register under namespaces and discover other peers that have registered under the same namespaces.

cleanup_all_expired() → None

Clean up expired registrations from all namespaces.

get_namespace_stats() → dict[str, int]

Get statistics about registrations per namespace.

libp2p.discovery.rendezvous.discovery module

Rendezvous discovery implementation that conforms to py-libp2p’s discovery interface.

class libp2p.discovery.rendezvous.discovery.PeerCache

Bases: object

Cache for discovered peers with TTL management.

add_peer(peer: PeerInfo, ttl: int) → None

Add a peer to the cache with TTL.

clear() → None

Clear the cache.

get_valid_peers(limit: int = 0) → list[PeerInfo]

Get valid (non-expired) peers from cache.

class libp2p.discovery.rendezvous.discovery.RendezvousDiscovery(host: IHost, rendezvous_peer: ID, enable_refresh: bool = False)

Bases: object

Rendezvous-based peer discovery.

This class provides a high-level interface for peer discovery using the rendezvous protocol, including caching. Registration refresh is handled automatically by the underlying RendezvousClient.

async advertise(namespace: str, ttl: int = 7200) → float

Advertise this peer under a namespace.

Args:

namespace: Namespace to advertise under ttl: Time-to-live in seconds (default 2 hours)

Returns:

Actual TTL granted by the server

clear_cache(namespace: str | None = None) → None

Clear peer cache.

Args:

namespace: Specific namespace to clear, or None for all

async close() → None

Close the discovery service and clean up resources.

async find_all_peers(namespace: str) → list[PeerInfo]

Find all peers in a namespace using pagination.

Args:

namespace: Namespace to search

Returns:

List of all discovered peers

async find_peers(namespace: str, limit: int = 100, force_refresh: bool = False) → AsyncIterator[PeerInfo]

Find peers in a namespace.

Args:

namespace: Namespace to search limit: Maximum number of peers to return force_refresh: Force refresh from server instead of using cache

Yields:

PeerInfo objects for discovered peers

async run() → None

Run the rendezvous discovery service.

async unregister(namespace: str) → None

Stop advertising this peer under a namespace.

Args:

namespace: Namespace to stop advertising under

libp2p.discovery.rendezvous.config module

Configuration constants for the rendezvous protocol implementation.

This module contains all protocol constants, limits, and configuration values used throughout the rendezvous implementation.

libp2p.discovery.rendezvous.messages module

Message construction helpers for rendezvous protocol.

libp2p.discovery.rendezvous.messages.create_discover_message(namespace: str, limit: int = 0, cookie: bytes = b'') → Message

Create a DISCOVER message.

libp2p.discovery.rendezvous.messages.create_discover_response_message(registrations: list[Register], cookie: bytes = b'', status: int = 0, status_text: str = '') → Message

Create a DISCOVER_RESPONSE message.

libp2p.discovery.rendezvous.messages.create_register_message(namespace: str, peer_id: ID, addrs: list[Multiaddr], ttl: int) → Message

Create a REGISTER message.

libp2p.discovery.rendezvous.messages.create_register_response_message(status: int, status_text: str = '', ttl: int = 0) → Message

Create a REGISTER_RESPONSE message.

libp2p.discovery.rendezvous.messages.create_unregister_message(namespace: str, peer_id: ID) → Message

Create an UNREGISTER message.

libp2p.discovery.rendezvous.messages.parse_peer_info(peer_info: PeerInfo) → tuple[ID, list[Multiaddr]]

Parse PeerInfo from protobuf message.

Subpackages