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 ✅

• 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(our_name, peer_name, cookie) lazy-connects: EPMD lookup + TCP connect + v6 handshake on construction
• Node.call(target_name, request, timeout=5.0) implements the $gen_call protocol:

  caller -> {'$gen_call', {FromPid, Ref}, Request}    (REG_SEND)
  server -> {Ref, Reply}                              (SEND)
  

• Unique Ref per call, matched on receive — protocol violations surface as CallProtocolError, timeouts as CallTimeout
• Tests: {ping, X} -> {pong, X}, {add, A, B} -> {ok, A+B}, sequential calls without crosstalk, timeout against a slow responder, drop-on-the-floor against an unknown registered name, Ref uniqueness across the Node lifetime

Phase 6 — TLS dist ✅

• make_dist_tls_context(cert=, key=, ca=) helper builds an ssl.SSLContext tuned for OTP defaults (verify_peer, TLSv1.2 min)
• Node(..., tls_context=ctx) wraps the post-EPMD socket in TLS before the dist handshake
• Auto-selects frame_size=4 for the handshake when TLS is in use (the non-obvious quirk: inet_tls_dist uses {packet, 4} on the SSL socket, where plain inet_tcp_dist uses {packet, 2} during handshake)
• Live tests: generate CA + SAN-bearing certs with openssl, spawn erl -proto_dist inet_tls, drive a full Node.call() through the tunnel. Negative tests confirm: plaintext connection fails, wrong-CA client cert fails.

Phase 7 — unfeed integration ✅

• ErlangDistTransport lives in unfeed/wallet.py (not erldistpy itself — keeps erldistpy app-agnostic)
• Implements WalletTransport Protocol via erldistpy.Node.call
• Wraps each HTTP-shape (method, path, json, params) into a single {:unfeed_rpc, Method, Path, JsonBody, Params} gen_server request
• Reply translation: atoms/binaries → str, nested maps/lists recurse
• Error mapping: {:error, code, msg, retryable} → WalletBridgeError; CallTimeout → bridge_timeout; NodeError → bridge_unreachable
• Selected per-deploy via unfeed.wallet_transport = http | erldist
• Optional TLS dist by setting wallet_node_tls_* config keys
• 11 tests in unfeed/tests/test_wallet_erldist.py mock Node.call and verify the full request/reply contract

The Elixir-side gen_server (wallet_rpc) doesn't exist yet — it's the next ticket on the Elixir wallet bridge side. Once it lands and a staging deploy stays healthy, flip the production switch.