Channel wraps the post-handshake socket and carries 4-byte length-
prefixed distribution messages: pass-through byte ('p') + ETF control
tuple + optional payload term.

API surface:
  send_raw / recv_raw     -- raw 4-byte framed bytes, empty == net_tick
  send_tick               -- send keepalive frame
  send_control / recv_message  -- structured control + payload
  send_reg_send           -- helper for the REG_SEND case (FromPid,
                             registered name, payload)

recv_message() transparently skips inbound ticks; callers wanting tick
awareness use recv_raw().

etf.decode_term(data, offset) exposed as a streaming decoder so the
channel can read control + payload back-to-back from one frame body.

Tests:
  - pure encode/decode round-trips
  - socketpair tests for framing, ticks, helper signatures
  - live end-to-end against an erl node with a registered echo process:
    EPMD -> handshake -> REG_SEND -> recv reply, payload matches
  - boot script writes a /tmp ready-flag after registering `echo`;
    fixture waits for both EPMD registration AND the flag to dodge
    the race where EPMD registers the node before -eval runs

101 tests green, lint clean.

2026-06-16 11:23:16 -04:00

3.3 KiB

Raw Blame History

erldistpy roadmap

Phases below are sized to land as discrete commits. Each phase ends with make all green and a real-VM interop test where applicable.

Phase 0 — Repo bones ✅

LICENSE, README, .gitignore, Makefile, pyproject.toml
Package skeleton, ruff config matches unfeed
make bootstrap test lint works on a fresh checkout

Phase 1 — ETF codec ✅

Subset of External Term Format we need for gen_call to Elixir: small_int, int, big_int, atom_utf8 (legacy atom_ext on decode), binary, nil, list, tuple (small + large), pid (new_pid), ref (newer_reference)
Booleans and None ride as atoms true / false / nil
Golden vectors decoded from real term_to_binary/1 output
Round-trip tests for the encoder
Generator script committed at docs/etf_vectors.erl

Phase 2 — EPMD client ✅

EPMD (Erlang Port Mapper Daemon) maps node names to TCP ports.

Synchronous TCP client
PORT_PLEASE2_REQ (122) → EpmdInfo(name, port, node_type, protocol, hi_ver, lo_ver, extra)
Returns None cleanly on unregistered node, raises EpmdError on socket failures
Tests: recorded byte streams from real EPMD + live integration that spawns its own erl -sname and tears it down

Phase 3 — Distribution handshake ✅

handshake(sock, our_name=..., cookie=...) drives the v6 dance: send_name(N) / recv_status(s) / recv_challenge(N) / send_challenge_reply(r) / recv_challenge_ack(a)
MD5 cookie digest, cross-checked against erlang:md5/1 output
Flag set in erldistpy/flags.py advertises OTP 23+ compatibility
Tests:
- Frame builders/parsers as pure functions
- Cookie digest against an Erlang-computed reference
- Live handshake against erl -sname ... -setcookie ...
- Wrong-cookie test confirms peer rejection surfaces correctly

Newer SHA-256 digest (DFLAG_MANDATORY_25_DIGEST) deferred — landed only if we hit a peer that requires it.

Phase 4 — Distribution channel ✅

Channel wraps the post-handshake socket: 4-byte length frames, pass-through byte ('p'), control tuple + optional payload term
send_reg_send(from_pid, to_name, payload) helper for the common case
recv_message() skips ticks transparently; recv_raw() exposes them for callers that need tick awareness
Tick keepalive via send_tick() — caller drives the timer for now (background ticker lands in Phase 7 alongside unfeed integration)
Tests:
- Pure encode/decode round-trips
- Socket-pair tests for send/recv framing, tick handling
- Live end-to-end against an erl node with a registered echo process: EPMD → handshake → REG_SEND → recv reply, payload matches
- Survives an outbound tick before the reply

Phase 5 — gen_call convenience layer

Node.call(name_or_pid, request, timeout=5.0) → reply term
Wraps the $gen_call protocol used by :gen_server
Idempotency-key handling lives in the caller; we just pass the term

Phase 6 — TLS dist

Wrap the post-EPMD socket in TLS
Match inet_tls_dist config on the Erlang side (cert + key + ca paths)
Same handshake, just runs inside the TLS tunnel

Phase 7 — unfeed integration

ErlangDistTransport implementing unfeed's WalletTransport Protocol
Maps /v1/health, /v1/address, ... to gen_call requests
unfeed deploys with a config switch: wallet_transport = http | erldist
Cutover after a soak period on staging

3.3 KiB Raw Blame History