goodboy
/
tractor
1
0
Fork 2
Code Issues 5 Pull Requests 6 Packages Projects Releases Wiki Activity
tractor/ai/tpt-backends
History
Gud Boi 41d08d04a6 Fix the `wg` maddr grammar, `/wg/` is *infix* 
The prior revision (and gh #482's examples) had it as a suffix,
`/ip4/10.0.11.1/tcp/1616/wg/u<key>`. Wrong: verified against
`baudco/py-multiaddr@wg_support` (py-multiaddr#108) installed in
a throwaway venv, the canonical form is

  /ip4/192.168.1.50/udp/51820/wg/u<A_pub>/ip4/10.0.11.1/tcp/1616

where segs *before* `/wg/` are the **bearer** — the underlay
`(ip, udp-port)` `wg(8)` itself listens on (`ListenPort`), per
the codec docstring's own example — and segs *after* are the
**overlay** ep, the only part we ever bind. The suffix form does
parse, which is why it slipped through, but it's semantically
inverted: overlay addr where the bearer belongs, `tcp` where
wg's `udp` goes, and no overlay ep declared at all.

Records the observed `[p.name for p in m.protocols()]` lists so
the `match` can be written against fact, and replaces the
"composed vs not" framing w/ what's actually the design axis:
three parts, three **owners** — bearer bound by the kernel via
`wg-quick`/`pyroute2`, `/wg/u<key>` bound by nothing (it's an
identity, verified out-of-band), overlay bound by our
`IPCServer` as `.inner`. `_peel_tunnel_segs()` correspondingly
grows a 3rd return, splitting *at* the tunnel seg so nested
tunnels fall out for free.

Also hoists the netns conclusion to the top of §5.3 where it
can't be missed: netns is a **runtime-level config API, not an
actor-app-code one**. It's a spawn/boot-time input alongside
`enable_transports`/`tpt_bind_addrs`, deliberately w/ no
`await actor.enter_netns(...)`, because `setns(2)` neither moves
already-created sockets nor applies beyond the calling thread —
so a mid-life API would silently leave the IPC server bound in
the old ns.

(this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`))
 		2026-08-12 20:08:15 -04:00
..
00_shared_backend_contract.md Proto-key the unwrapped-addr form in the plans 2026-08-12 20:08:15 -04:00
01_tipc_backend.md Proto-key the unwrapped-addr form in the plans 2026-08-12 20:08:15 -04:00
02_quic_iroh_backend.md Add `QUIC`-via-`iroh` tpt-backend plan 2026-08-12 20:08:15 -04:00
03_wg_tunnel_bindspace.md Fix the `wg` maddr grammar, `/wg/` is *infix* 2026-08-12 20:08:15 -04:00
README.md Index the tpt-backend plans w/ a README 2026-08-12 20:08:15 -04:00

README.md

next-gen tractor.ipc transport backend plans

Implementation specs for three prospective .ipc transport backends, written so each can be worked independently (by a different model/provider) without design or lib-selection drift.

Read 00_shared_backend_contract.md first — it is the normative description of what a tractor transport backend is as of main@83b34884 (the backend duck-type, the 10-item registration checklist, the test-harness plumbing, the code-style rules). The three plans assume it and document only their own deltas.

plan issue dep size lands
01 — TIPC #378 none (stdlib) small first
02 — QUIC/iroh #353 iroh (uniffi FFI) large needs a prep PR
03 — wg bindspace #482, #443 pyroute2 medium, 3 layers layer A now

Headline conclusions:

  • TIPC is the cheap win. Verified: trio.SocketStream and trio.SocketListener are address-family agnostic (only SOCK_STREAM + a trio socket), and CPython ships AF_TIPC + 23 TIPC_* constants. So the backend is ~one module of contract boilerplate, zero new deps, and it buys kernel-native service discovery: bind() publishes, connect()-by-name resolves — no registrar in the loop. (modprobe tipc is required; hard-gate everything.)
  • QUIC’s cost is entirely in two adapters, not in QUIC. The iroh python bindings are uniffi-generated asyncio, but the asyncio dependency is confined to one future-poll callback — a ~40-line trio bridge (TrioToken.run_sync_soon) replaces it. The second cost is that an iroh listener isn’t a socket, which needs a small, independently-reviewable prep PR to _server.py/_types.py.
  • WireGuard is not a transport. It’s an iface-layer tunnel, so it belongs as a nested bindspace (TunnelledAddress + open_bindspace() @acms) wrapping whatever L4 tpt is in use — which is also what finally implements the long-spec’d Address.namespace, and what generalizes to veth/vxlan/gre.

Ordering rationale: plan 01 first as the cheap proof the table-registration story generalizes to a genuinely new proto; plan 03 layer A is already deployable-today doc/example work; plan 02 last (and gated on its prep PR). Plans 01 and 02 both want the same Address.rebind_from_sockname gate — whichever lands first ships it.