Dialing and Connecting to Other Nodes

Once your node is bootstrapped and listening on an address, the next step in setting up a distributed actor system is dialing and connecting to other nodes. Kameo’s ActorSwarm allows nodes to discover and connect with peers using libp2p’s peer-to-peer communication capabilities. This section covers how to dial peers using multiaddresses, how to manage peer connections, and how libp2p’s mDNS feature can simplify peer discovery.

Dialing a Peer

To establish a connection with another node, you need to dial its multiaddress. A multiaddress specifies the protocol, IP address, and port required to reach the node.

actor_swarm.dial("/ip4/192.0.2.0/udp/8020/quic-v1".parse()?).await?;

In this example, the node is dialing another node located at IP address 192.0.2.0 on UDP port 8020, using the QUIC protocol. Once the connection is established, the node can interact with remote actors on the peer.

Dialing with Options

For more advanced use cases, Kameo provides the DialOpts structure, which allows you to customize how you dial peers. This is useful when you need to include additional details or preferences when establishing connections, such as specifying peer IDs.

let dial_opts = DialOpts::unknown_peer_id()
    .address("/ip4/192.0.2.0/udp/8020/quic-v1".parse()?)
    .build();

actor_swarm.dial(dial_opts).await?;

In this example, DialOpts is used to dial a peer at a known address without specifying the peer’s ID. This option can be customized depending on the situation, such as when connecting to peers with specific identities or conditions.

Auto-discovery with mDNS

In most cases, libp2p’s mDNS (Multicast DNS) feature allows nodes to automatically discover each other on the same local network, without needing to manually dial peers. This greatly simplifies setting up a distributed system, as peers will be able to find and connect to each other without explicit configuration.

If your network environment supports mDNS, it can be enabled by default in Kameo’s ActorSwarm. With mDNS, nodes announce themselves to the network and discover other peers in the same multicast domain.

// Example of using mDNS auto-discovery
let actor_swarm = ActorSwarm::bootstrap()?;
actor_swarm.listen_on("/ip4/0.0.0.0/udp/8020/quic-v1".parse()?).await?;
// Peers on the same local network can now discover each other automatically

This makes peer discovery effortless in environments where mDNS is available, such as local networks or development environments.

Adding Peer Addresses Manually

In some cases, you may want to manually add a known peer’s address to the swarm without dialing immediately. This can be useful for preloading peers or when you want to manage connections programmatically.

let peer_id: PeerId = ...; // Obtained from the peer's identity
let addr: Multiaddr = "/ip4/192.0.2.0/tcp/1234".parse()?;

actor_swarm.add_peer_address(peer_id, addr);

This example shows how to associate a peer’s identity with a known address. Once the peer address is added, the swarm will use it to attempt future connections or for message routing.

Disconnecting from Peers

If you need to disconnect from a peer, you can do so using the peer’s PeerId. This is helpful when you want to manage peer connections and ensure that a node is no longer part of the active network.

actor_swarm.disconnect_peer_id(peer_id);

This cleanly terminates the connection with the specified peer, removing it from the swarm’s list of active peers.

Example: Dialing and Connecting to Peers

Here’s a full example of how to dial a peer and establish a connection:

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Bootstrap the swarm
    let actor_swarm = ActorSwarm::bootstrap()?;

    // Start listening on a multiaddress
    actor_swarm.listen_on("/ip4/0.0.0.0/udp/8020/quic-v1".parse()?).await?;

    // Dial a peer on a specific address
    actor_swarm.dial("/ip4/192.0.2.0/udp/8020/quic-v1".parse()?).await?;

    // The node is now connected to the peer and can send/receive messages
    Ok(())
}

This example shows how to bootstrap the swarm, set up a listener, and connect to another node using a multiaddress.

What’s Next?

Now that you can connect to other nodes, the next step is registering actors and looking them up across the network. This allows nodes to discover and interact with actors on remote peers.

Explore the next section on Registering and Looking up Actors to learn more about actor registration and discovery.