p2p
stablePeer-to-peer networking primitives including peer identity, Kademlia-style XOR routing, message encoding, and pub/sub topic management via PeerTable and TopicRegistry classes.
use plugin p2p::{generate_peer_id, hash_content, encode_handshake, …} Functions (21)
- generate_peer_id Generate a random 20-byte hex peer ID
- hash_content SHA-256 hash a string, return hex digest
- encode_handshake Encode peer ID + protocol into handshake bytes
- decode_handshake Decode handshake bytes into peer_id + protocol
- distance_xor Compute XOR distance between two hex peer IDs
- encode_message Encode typed message with sender into bytes
- decode_message Decode message bytes into type/sender/payload
- peer_info Build a peer descriptor table with routing bucket
- PeerTable.new Create an in-memory peer routing table
- PeerTable.add Add a peer (id, address) to the table
- PeerTable.remove Remove a peer by ID
- PeerTable.get Look up a peer address by ID
- PeerTable.list List all peers as an id→addr table
- PeerTable.count Count the number of tracked peers
- PeerTable.closest Find N closest peers by XOR distance
- TopicRegistry.new Create a pub/sub topic registry
- TopicRegistry.subscribe Subscribe a peer to a topic
- TopicRegistry.unsubscribe Unsubscribe a peer from a topic
- TopicRegistry.subscribers List subscribers of a topic
- TopicRegistry.list_topics List all active topics
- TopicRegistry.subscriber_count Count subscribers for a topic
Generate a random 20-byte hex peer ID
Generates a cryptographically random 20-byte peer identity and returns it as a 40-character lowercase hex string. Use this to assign a stable ID to each node in your network.
use plugin p2p::{generate_peer_id}
let my_id = generate_peer_id()
print("My peer ID: {my_id}")
SHA-256 hash a string, return hex digest
Computes the SHA-256 digest of data_str and returns a 64-character hex string. Useful for content-addressed storage and verifying data integrity across peers.
use plugin p2p::{hash_content}
let cid = hash_content("hello world")
print("Content ID: {cid}")
Encode peer ID + protocol into handshake bytes
Encodes a peer ID and protocol name into a compact binary handshake packet. The format is [proto_len(1)][proto_bytes][peer_id_bytes(20)]. Returns raw bytes suitable for transmission.
use plugin p2p::{generate_peer_id, encode_handshake}
let id = generate_peer_id()
let pkt = encode_handshake(id, "zolo/1.0")
print("Handshake bytes length: {pkt.len}")
Decode handshake bytes into peer_id + protocol
Parses a handshake packet produced by encode_handshake and returns a table with peer_id (hex string) and protocol (string) fields.
use plugin p2p::{generate_peer_id, encode_handshake, decode_handshake}
let id = generate_peer_id()
let pkt = encode_handshake(id, "zolo/1.0")
let parsed = decode_handshake(pkt)
print("Protocol: {parsed["protocol"]}, Peer: {parsed["peer_id"]}")
Compute XOR distance between two hex peer IDs
Computes the XOR distance between two hex-encoded node IDs, returning the result as a hex string. This is the core metric for Kademlia-style DHT routing.
use plugin p2p::{generate_peer_id, distance_xor}
let a = generate_peer_id()
let b = generate_peer_id()
let dist = distance_xor(a, b)
print("Distance: {dist}")
Encode typed message with sender into bytes
Encodes a typed message from a sender with an arbitrary string payload into a binary frame. The format is [type_len][type][sender_len][sender][payload].
use plugin p2p::{generate_peer_id, encode_message}
let id = generate_peer_id()
let msg = encode_message("PING", id, "hello")
print("Message bytes ready to send")
Decode message bytes into type/sender/payload
Decodes a binary message frame back into a table with type, sender_id, and payload string fields.
use plugin p2p::{generate_peer_id, encode_message, decode_message}
let id = generate_peer_id()
let msg = encode_message("PING", id, "hello")
let parsed = decode_message(msg)
print("From: {parsed["sender_id"]}, Payload: {parsed["payload"]}")
Build a peer descriptor table with routing bucket
Builds a descriptor table for a peer including peer_id, addr, protocol (defaults to "zolo/1.0"), and bucket (leading-zero bits of SHA-256(peer_id), used for Kademlia bucket assignment).
use plugin p2p::{generate_peer_id, peer_info}
let id = generate_peer_id()
let info = peer_info(id, "192.168.1.5:4001")
print("Bucket: {info["bucket"]}")
Create an in-memory peer routing table
Creates a new thread-safe routing table that maps peer IDs to addresses. Use one per node to track known peers.
use plugin p2p::{PeerTable, generate_peer_id}
let table = PeerTable.new()
let id = generate_peer_id()
table.add(id, "10.0.0.1:4001")
print("Peers: {table.count()}")
Add a peer (id, address) to the table
Inserts or updates the address for a peer ID. Silently overwrites existing entries.
use plugin p2p::{PeerTable, generate_peer_id}
let table = PeerTable.new()
table.add(generate_peer_id(), "node-a:4001")
table.add(generate_peer_id(), "node-b:4001")
print("Tracking {table.count()} peers")
Remove a peer by ID
Removes the peer with the given ID. Returns true if the peer existed and was removed, false otherwise.
use plugin p2p::{PeerTable, generate_peer_id}
let table = PeerTable.new()
let id = generate_peer_id()
table.add(id, "10.0.0.2:4001")
let removed = table.remove(id)
print("Removed: {removed}")
Look up a peer address by ID
Returns the address string for the given peer ID, or nil if not found.
use plugin p2p::{PeerTable, generate_peer_id}
let table = PeerTable.new()
let id = generate_peer_id()
table.add(id, "10.0.0.3:4001")
let addr = table.get(id)
print("Address: {addr}")
List all peers as an id→addr table
Returns a table mapping each peer ID to its address string. Useful for serializing the routing table or debugging.
use plugin p2p::{PeerTable, generate_peer_id}
let table = PeerTable.new()
table.add(generate_peer_id(), "node-a:4001")
table.add(generate_peer_id(), "node-b:4001")
let all = table.list()
print("All peers: {all}")
Count the number of tracked peers
Returns the number of peers currently in the table.
use plugin p2p::{PeerTable}
let table = PeerTable.new()
print("Peers: {table.count()}")
Find N closest peers by XOR distance
Finds the n peers with the smallest XOR distance to target_id, sorted from closest to furthest. Each entry is a table with id and addr fields.
use plugin p2p::{PeerTable, generate_peer_id}
let table = PeerTable.new()
table.add(generate_peer_id(), "node-a:4001")
table.add(generate_peer_id(), "node-b:4001")
table.add(generate_peer_id(), "node-c:4001")
let target = generate_peer_id()
let nearest = table.closest(target, 2)
print("Nearest peers: {nearest}")
Create a pub/sub topic registry
Creates a thread-safe pub/sub topic registry. Tracks which peer IDs are subscribed to which topics.
use plugin p2p::{TopicRegistry, generate_peer_id}
let registry = TopicRegistry.new()
let peer = generate_peer_id()
registry.subscribe("news", peer)
print("Subscribers: {registry.subscriber_count("news")}")
Subscribe a peer to a topic
Subscribes a peer to the given topic. Duplicate subscriptions are silently ignored.
use plugin p2p::{TopicRegistry, generate_peer_id}
let reg = TopicRegistry.new()
reg.subscribe("chat", generate_peer_id())
reg.subscribe("chat", generate_peer_id())
print("Chat subscribers: {reg.subscriber_count("chat")}")
Unsubscribe a peer from a topic
Removes a peer from a topic. Returns true if the peer was subscribed, false otherwise. Removes the topic entry entirely when no subscribers remain.
use plugin p2p::{TopicRegistry, generate_peer_id}
let reg = TopicRegistry.new()
let peer = generate_peer_id()
reg.subscribe("events", peer)
let ok = reg.unsubscribe("events", peer)
print("Unsubscribed: {ok}")
List subscribers of a topic
Returns a list of peer IDs subscribed to the given topic, indexed from 1.
use plugin p2p::{TopicRegistry, generate_peer_id}
let reg = TopicRegistry.new()
reg.subscribe("alerts", generate_peer_id())
reg.subscribe("alerts", generate_peer_id())
let subs = reg.subscribers("alerts")
print("Subscriber list: {subs}")
List all active topics
Returns a list of all topic names that currently have at least one subscriber.
use plugin p2p::{TopicRegistry, generate_peer_id}
let reg = TopicRegistry.new()
reg.subscribe("chat", generate_peer_id())
reg.subscribe("news", generate_peer_id())
let topics = reg.list_topics()
print("Active topics: {topics}")
Count subscribers for a topic
Returns the number of peers subscribed to the given topic. Returns 0 if the topic does not exist.
use plugin p2p::{TopicRegistry, generate_peer_id}
let reg = TopicRegistry.new()
reg.subscribe("metrics", generate_peer_id())
print("Metrics subscribers: {reg.subscriber_count("metrics")}")