pyrlang.dist_proto

The Erlang distribution protocol: EPMD client, handshake, and the messages of connected nodes.

class pyrlang.dist_proto.ErlangDistribution(node_name, hidden=False, use_epmd=True, dist_port=0, dynamic_host=None)

Bases: object

Implements network part of the EPMD registration and Erlang dist_proto protocol.

node_name_

Node name, a string.

dynamic_

The node got, or will get, its name from another node.

name_pending_

The node has no name yet.

host_

The host part of the node name.

naming_lock_

One connection setup at a time while the node has no name.

creation_

Creation of this incarnation of the node, part of every pid and reference it makes and of its handshake messages. Chosen here, before the first process exists, and never 0; the creation EPMD hands out later is not used (as for erl_interface nodes).

serve_task_: Task[None] | None

Runs run_dist_server; cancelled when the node stops.

connecting_: dict[str, Task[bool]]

Connection setups this node started, by peer name; everyone who wants that peer awaits the same task.

pending_out_: dict[str, DistClientProtocol]

Outgoing connections whose handshake is not finished, by peer.

superseded_: set[str]

Peers whose own connection to us was preferred over our setup (simultaneous connect).

async start_server()

Start listening for incoming connections.

async start_distribution()

Start listening for other nodes and, unless the node does not use EPMD, register in the local EPMD.

Raises:
async run_dist_server()

Start listening for connections from other nodes.

disconnect_epmd()

Finish EPMD connection, this will remove the node from the list of available nodes on EPMD

destroy()

Stop listening and leave EPMD. Safe to call twice.

async connect_to_node(local_node, remote_node, address=None)

Query EPMD where is the node, connect and run the handshake. Concurrent calls for one node share one connection setup.

Parameters:
  • local_node (str) – name of the local Erlang Node object

  • remote_node (str) – String with node ‘name@ip’

  • address (tuple[str, int] | None) – host and port of the node, if known; EPMD is not asked then

Returns:

True once the connection is established; False if EPMD does not know the node

Raises:
Return type:

bool

accept_pending(peer_name)

Decide what an incoming connection from peer_name is told while this node may be connecting to that peer itself, as net_kernel does for accept_pending.

Returns:

the status to send: ok, ok_simultaneous (our own attempt is dropped) or nok (our attempt goes on, the incoming connection must be closed)

Return type:

str

class pyrlang.dist_proto.DistServerProtocol(node_name)

Bases: BaseDistProtocol

Protocol handles incoming connections from other nodes.

alive_peer_

Name of the peer that was told ‘alive’ and has not answered.

connection_lost(exc)

The connection ended; its peer, if the handshake was over, is down.

on_packet(data)

Handle incoming dist_proto packet

Parameters:

data (bytes) – The packet after the header had been removed

on_packet_recvname(data)

Handle RECV_NAME command, the first packet in a new connection: check the peer’s flags and answer with a status, as dist_util:handshake_other_started does.

on_packet_alive_reply(data)

The initiator’s answer to status alive (dist_util:recv_status_reply).

on_packet_challengereply(data)

The initiator’s answer to our challenge and its own challenge: check one, answer the other.

class pyrlang.dist_proto.DistClientProtocol(node_name, peer_name)

Bases: BaseDistProtocol

Handles outgoing connections from our to other nodes.

asked_name_

The name message asked the peer for a node name (DFLAG_NAME_ME).

given_name_: Named | None

The name and creation the peer gave; adopted by the node once the cookie has checked out.

handshake_done_: Future[None]

Done when the connection is established; carries the DistributionError if the handshake fails.

connection_made(transport)

The TCP connection is up: send our name.

connection_lost(exc)

The connection ended; a handshake still under way has failed.

is_pending()

True while the handshake runs: our name was sent and the connection is not established yet.

abandon()

Give up this handshake: the peer’s own connection to us is used instead (simultaneous connect).

on_packet(data)

Handle incoming dist_proto packet

Parameters:

data (bytes) – The packet after the header had been removed

on_packet_recvstatus(data)

The acceptor’s verdict on our name (dist_util:recv_status).

on_packet_recvchallenge(data)

The peer’s challenge: answer it and challenge the peer.

on_packet_recvchallenge_ack(data)

The peer’s answer to our challenge: the connection is set up if it is right.

class pyrlang.dist_proto.DistributionFlags(cookie, dflags=468282470332, net_ticktime=60, max_fragmented_size=268435456, dist_buf_busy_limit=1048576, recv_backlog_messages=10000, recv_backlog_bytes=33554432)

Bases: object

A class holding an integer with features that are supported by this node, and the network cookie.

max_fragmented_size_

Most bytes of unfinished fragmented messages held per connection; a peer that exceeds it is disconnected.

dist_buf_busy_limit_

Bytes waiting to be sent on one connection above which senders that await wait; OTP’s +zdbbl (dist_buf_busy_limit), whose default is the same.

recv_backlog_bytes_

Messages, and their bytes, that one connection may have in process inboxes before reading from it pauses.

network_tick_time_

Seconds; OTP’s kernel parameter net_ticktime. A tick is sent every quarter of it on an idle connection, and a peer silent for this long (plus up to a quarter) is considered down. Connected nodes should use the same value.

set_node_published()

Announce the node as visible (not hidden).

Modules

base_dist_protocol

Base abstract Distribution connection class

client

The module implements outgoing TCP dist_proto connection (i.e. initiated by our node to another node with the help of EPMD).

control

Messages of an established connection, as pure functions over bytes: splitting a packet's content into control message and payload, and checking the control message's shape ("Protocol between Connected Nodes" in erl_dist_protocol).

dist_header

Framing of the packets of an established connection, over bytes: pass-through packets, the distribution header with its atom cache, and fragmented messages ("Distribution Header" in erl_ext_dist; the checks follow erts_prepare_dist_ext in OTP 29's external.c).

distribution

Distribution class is a separate running Task which owns its TCP connection.

epmd_client

The module represents EPMD connection and implements the protocol.

flags

Distribution flags, named and valued as in OTP's lib/kernel/include/dist.hrl (the header wins where the docs differ).

handshake

The messages of the distribution handshake, version 6 (OTP 23 and newer), as pure functions over bytes: no sockets, no state.

server

The module implements incoming TCP dist_proto protocol (i.e. initiated by another node with the help of EPMD).

version

Implement shared pieces of Erlang node negotiation and dist_proto protocol