russell@unturf.com
c870bdb2ac
ErlangDistTransport itself lives in unfeed/unfeed/wallet.py to keep erldistpy app-agnostic. Tests + docs there. Pending the Elixir-side wallet_rpc gen_server, then staging soak, then prod switch.
114 lines
5 KiB
Markdown
114 lines
5 KiB
Markdown
# 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.
|