erldistpy/docs/ROADMAP.md

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

• TCP connect to the resolved port
• send_name / recv_status / recv_challenge / send_challenge_reply / recv_challenge_ack
• Cookie digest via erlang:phash2-equivalent (md5-based per spec)
• Version 6 ("v6") handshake, the modern one Elixir 1.15+ uses
• Tests: handshake against a live Erlang node started in conftest

Phase 4 — Distribution channel

• After handshake, the socket carries control + payload messages framed by a 4-byte length prefix
• Send SEND_TT / REG_SEND for outgoing messages
• Receive replies, route by ref
• Tick loop for keepalive (60s default per OTP)

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