Gud Boi
7e20585f59
Per contract §0 ("if this doc disagrees with the code, the code
wins; fix it in the same PR"), fold the step-0 probe results and
the as-landed impl back into `01_tipc_backend.md`.
Settled the two claims §9 flagged as unverified,
- `SO_ACCEPTCONN` on `AF_TIPC` **works** (answers `1`); we never
needed trio's `except OSError` carve-out.
- dup-name bind → **silent crosstalk is real**: both binds
succeed and dials alternate strictly, so a `.get_random()`
clash is never `EADDRINUSE`.
Corrections where the plan was wrong,
- §5.2's `tipc_event` is **48B not 40B** (`4+4+4+8+28`), and
python exposes `TIPC_WAIT_FOREVER` as `-1` so it needs masking
before packing as `'I'`.
- §7.2's pytest mark goes in `_testing/pytest.py::
pytest_configure()`, NOT `pyproject.toml` — the repo has no
`markers` ini table.
- §7.4's "10k → 10k distinct" is a ~1.2% flaky assert by
birthday bound on a 32b instance space; use `>= n-2` w/ the
arithmetic documented.
- §2.2's `unwrapped_type` and §3.2's `from_addr()` sketch still
showed the 2-tuple + the `'tipc:<stype>:<scope>'` prefix hack
that §2.2 itself had already withdrawn.
Two hazards the plan never anticipated, now recorded in §9,
- an unpublished-name dial answers `EHOSTUNREACH` which python
maps to a **bare `OSError`**, NOT a `ConnectionError` subtype,
so the `_reraise_as_connerr()` wrap is contract-§4 mandatory.
- a connect-then-drop peer answers `ENOTCONN` from
`getpeername()`, which — since `.get_stream_addrs()` runs
BEFORE the handshake — used to kill the whole actor.
Also withdraw §9's "fold a 6-byte digest into `(stype_low,
instance)`" escalation: varying `_stype` per-actor would need
65536 topology subscriptions and kills layer B outright.
(this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`))
|
||
|---|---|---|
| .. | ||
| 00_shared_backend_contract.md | ||
| 01_tipc_backend.md | ||
| 02_quic_iroh_backend.md | ||
| 03_wg_tunnel_bindspace.md | ||
| README.md | ||
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.SocketStreamandtrio.SocketListenerare address-family agnostic (onlySOCK_STREAM+ a trio socket), and CPython shipsAF_TIPC+ 23TIPC_*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 tipcis required; hard-gate everything.) - QUIC’s cost is entirely in two adapters, not in QUIC. The
irohpython bindings areuniffi-generated asyncio, but the asyncio dependency is confined to one future-poll callback — a ~40-linetriobridge (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’dAddress.namespace, and what generalizes toveth/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.