Add an AF_TIPC transport backend

[goodboy]

Add an AF_TIPC transport backend

Motivation

Finally attempting to implement #378, per #492 🏄🏼

Every other tractor transport hands us a pipe and leaves discovery
to us: the registrar actor, the find_actor() round-trip, the whole
tractor.discovery apparatus. TIPC is different in a way that
actually matters — its service names live in a cluster-wide name
table the kernel itself maintains. So a .bind() is service
registration and a .connect()-by-name is the lookup, resolved and
load-balanced in-kernel.

That makes it the cheapest new backend we can add (stdlib-only, zero
new deps, and trio.SocketStream/SocketListener turn out to be
fully address-family agnostic) while simultaneously being the only
one that gives us cluster-wide discovery for free. It's also the
right first backend to land of the three planned in #492: unlike the
iroh/QUIC work it needs no generalization of _server.py or
transport_from_stream(), so it's a cheap proof that the
table-registration story works for a genuinely new proto.

A lovely side-effect of leaning into this proto is that it already
contains a built-in discovery system, which would let
us avoid R&D-ing something more involved of our own medium-term
(#184, #216). There's also a lot to leverage from the sophisticated
msging system including load-balancing in ideal cases and
fail-over connectivity for worst.

Src of research

The tipc.io docs are stale in places, so the kernel sources are
treated as the only normative reference throughout,

• include/uapi/linux/tipc.h — address flavours, sockopts, the
  topology structs
• net/tipc/socket.c, net/tipc/topsrv.c
• man 8 tipc
• http://tipc.io/
  • http://tipc.io/tracking.html
  • http://tipc.io/addressing.html
  • http://tipc.io/messaging.html

Every behavioural claim below was settled by probing a live kernel
(modprobe tipc, py3.13) rather than reasoning from docs — several
turned out to contradict the plan.

Summary of changes

• an actor's TIPC address is a service name (stype, instance),
  wrapped as TIPCAddress. Binding the singleton TIPC_ADDR_NAMESEQ
  range publishes it — it shows up in tipc nametable show — and
  MsgpackTIPCStream.connect_to() dials it by name. .unwrap() is
  proto-keyed as ('tipc', stype, inst, scope) using the multiaddr
  proto spelling so wrap_address() can't confuse it with the
  tcp/uds 2-tuples.
• .bindspace is the TIPC scope, which is about as literal a
  reading of that property's "set of hosts this bind is reachable
  from" docstring as exists. TIPC_ZONE_SCOPE is deprecated/aliased
  in modern kernels so it's folded to cluster on input.
• a new Address.rebind_from_sockname: ClassVar[bool] gates
  Endpoint.start_listener()'s post-bind getsockname()
  reconciliation (cca3a70d). That reconciliation exists
  only to learn a kernel-assigned port from a port=0 tcp bind;
  TIPC has no such late-binding and its getsockname() answers a
  TIPC_ADDR_ID port-id, so rebinding from it would swap a dialable
  service name for an un-dialable one. True on tcp/uds keeps
  today's behaviour bit-for-bit.
• layer B: open_topology_events() subscribes to TIPC_TOP_SRV and
  yields a trio receive-chan of TIPCNameEvent — push-based
  discovery, where the kernel tells us the instant any actor anywhere
  in the cluster publishes or withdraws a name. This is the
  groundwork for a registrar that never polls find_actor(). Event
  delivery now aborts explicitly on user-space overflow so a consumer
  must resubscribe instead of silently trusting stale topology state.
• full registration across every table in the shared-contract
  checklist (_state.TransportProtocolKey,
  _addr._address_types/._default_lo_addrs/wrap_address(),
  _types' four tables + transport_from_stream()), plus
  test-harness plumbing so --tpt-proto tipc is a first-class suite
  mode.
• an interim str-only /tipc/<stype>/<instance>/<scope> maddr
  grammar; parse_maddr() special-cases the prefix before
  Multiaddr(), which would otherwise reject the unregistered proto
  name outright.
• a blocking --tpt-proto=tipc CI leg with a gated sudo modprobe tipc step. The experimental continue-on-error was removed after
  repeated green runs (partially addresses Run (various) test suite(s) under different tpt protocols in CI #420).
• docs: a docs/guide/tipc.rst page and an
  examples/multihost/tipc_cluster/ set. Both single-host examples
  were run against a live kernel and their real output is what's
  pasted in the README. The two-physical-host example is now an
  operator runbook covering cluster identity, bearer setup,
  failure/rejoin and diagnostic capture; it introduces “Cluster
  Domain Sockets” as the newcomer-facing explanation while retaining
  tipc as the interoperable key. Plus
  ai/tpt-backends/01_tipc_HANDOFF.md, a provider-neutral cold-start
  handoff carrying the verified-behaviour table and closed decisions.
• an upstream /tipc multiaddr issue draft with a fixed-width
  (type, instance, scope) value, canonical structured text form,
  WireGuard composition and separation from future pyroute2
  generic-netlink deployment management (#498).

Two fixes fell out that are not TIPC-specific,

• pformat_caller_frame() was passing an indent='' kwarg
  pformat_boxed_tb() has never accepted, so EVERY send-side
  MsgTypeError died with a TypeError while formatting itself,
  masking the real msg-spec violation (f9f98eeb). Dates
  to 888af602; present on main and every wkt/* branch. It is now
  isolated in PR #503 for landing before this stack.
• SpawnSpec.reg_addrs/.bind_addrs pinned the wire shape to a
  2-tuple, so every TIPC subactor died at Expected array of length 2, got 4 (22049794). Widened to UnwrappedAddress —
  which SpawnSpec's own # TODO already asked for — and note the
  alias had to become variadic (tuple[str|int, ...]) bc
  msgspec refuses a union holding more than one array-like type.
  First real bite of the proto-key migration in Add impl plans for TIPC/QUIC/wg tpt backends #492's shared
  contract.

Verified kernel behaviour

Several of these contradict what the plan assumed, and two were
hazards it never anticipated,

• duplicate name binds both succeed and connects round-robin
  between them (six dials alternated strictly). So a get_random()
  instance collision is silent crosstalk, never EADDRINUSE —
  which is why the instance is a blake2b digest of the actor
  identity.
• dialing an unpublished name answers EHOSTUNREACH instantly,
  no SYN-timeout wait — better discovery-ping behaviour than TCP. But
  python maps it to a bare OSError, NOT a ConnectionError
  subtype the way ECONNREFUSED maps to ConnectionRefusedError, so
  the _reraise_as_connerr() normalization is required by the shared
  contract's handshake rules rather than being polish.
• a connect-then-drop peer used to kill the whole actor. TIPC
  answers ENOTCONN from getpeername() once the peer's gone
  (tcp/uds keep answering until we close), and
  MsgpackTransport.__init__() calls .get_stream_addrs() before
  the handshake — so the OSError escaped
  handle_stream_from_peer()'s handshake tolerance. A port scan was
  a remote actor-kill. Found by our own daemon fixture's readiness
  probe.
• SO_ACCEPTCONN works on AF_TIPC (answers 1); trio's
  except OSError carve-out isn't load-bearing here after all.
• the topology struct tipc_event is 48 bytes, not 40, and
  native '=' byte-order is accepted — so the plan's proposed
  _detect_topsrv_endianness() '>'-retry probe was deleted as
  unnecessary. TIPC_WAIT_FOREVER is -1 in python and must be
  masked before packing as an unsigned field.
• graceful peer close surfaces as BrokenResourceError/ECONNRESET
  rather than a clean 0-byte EOF. Benign — _iter_packets() already
  classifies it as a normal disconnect — but it looks alarming in
  transport logs.

The plan doc was reconciled against all of the above in
7e20585f, per the shared contract's "if the doc disagrees
with the code, the code wins" rule.

Testing

The acceptance bar for any backend is that the entire existing
suite passes under it unmodified. The refreshed blocking matrix passes
on Linux with TCP, UDS and TIPC and on macOS with TCP, alongside sdist
and docs. Local verification collected 479 tests, passed all
43 IPC tests, and passed all 35 TIPC-specific tests.

TODOs before landing

• land the isolated pformat red-test/fix pair in #503 before
  Add an AF_TIPC transport backend #493 — it is unrelated to TIPC and every branch has the bug
• confirm the refreshed matrix remains green with TIPC now a
  blocking CI leg
• rebase Add an AF_TIPC transport backend #493 onto Add impl plans for TIPC/QUIC/wg tpt backends #492's current head, then onto main once
  Add impl plans for TIPC/QUIC/wg tpt backends #492 merges
• extensive real-world and simulated (via net-overlay lib?)
  testing over real clusters, ideally distilled into the pytest
  harness with as many (0mq and/or erlang inspired) examples as
  possible Bo
  • at least partially completing some work around Chaos and resliliency testing #124
• submit the drafted /tipc multiaddr protocol upstream (#498),
  similar to our recent one for wg, after local review
  of its fixed-width schema and canonical text form

Future follow up

All filed as follow-up-labelled issues,

• #495 — TIPC_IMPORTANCE supervision QoS on the parent<->child
  chan. Genuinely novel: no other backend can rank a conn's traffic
  under congestion.
• #496 — TIPC_TOP_SRV-driven push registry in
  discovery._registry. The consumer side of
  open_topology_events(), and what would move the needle on Discovery and concensus: research and discussion. #184 /
  Multi-root discovery: pragmatic, simple consensus. #216.
• #497 — dual-link resiliency as two TIPC udp bearers over
  two distinct wg paths, rather than assuming two physical NICs.
• #498 — /tipc multiaddr spec submission, with the composed
  /ip4/…/udp/…/wg/u<key>/tipc/<stype>/<inst>/<scope> form as the
  real target. Goes up alongside wg multiaddr protocol: upstream spec submission plan #483 and unblocks the "return
  Multiaddr everywhere" item in Follow-up: multiaddr_support (PR #429) #443.
• #499 — registrar-less discovery via name derivation, since a
  bind already is a registration.
• #500 — TIPC multicast / group msging as a broadcast tpt for
  tractor.trionics fan-out (explicitly NOT a MsgTransport).
• #501 — post-bind verification for instance collisions, the
  escalation if the blake2b digest ever proves too narrow.
• #502 — TIPC over a wg mesh, the intended reference
  multihost deployment. NB the motivation is not confidentiality
  (TIPC ships its own AES-GCM crypto); it's public-key identity, NAT
  traversal and one overlay every tpt can share.

---

(this pr content was generated in some part by claude-code using
claude-opus-5 (anthropic))

(this update was generated in some part by opencode using
gpt-5.6-sol (openai))

Links

• Investigating TIPC, the "end game" cluster proto maybe? #378
• Add impl plans for TIPC/QUIC/wg tpt backends #492
• Run (various) test suite(s) under different tpt protocols in CI #420
• Follow-up: multiaddr_support (PR #429) #443
• wg multiaddr protocol: upstream spec submission plan #483
• Discovery and concensus: research and discussion. #184
• Multi-root discovery: pragmatic, simple consensus. #216
• Chaos and resliliency testing #124
• Fix pformat_caller_frame() render failure #503
• Add wireguard support (with key 'wg'?) multiformats/py-multiaddr#107

[Copilot]

Pull request overview

This PR introduces an initial AF_TIPC transport backend and the supporting wiring needed to register it as a first-class IPC transport alongside existing tcp and uds backends. It also widens the on-wire “unwrapped address” representation to accommodate proto-keyed transport shapes and adds targeted tests (including kernel-gated tests) to validate behavior.

Changes:

• Add a new TIPC transport backend (tractor.ipc._tipc) and register it in transport/address dispatch tables.
• Widen UnwrappedAddress in the wire types (SpawnSpec) and discovery layer to support proto-keyed/variadic address shapes.
• Improve listener-address reconciliation via Address.rebind_from_sockname, add /tipc/... multiaddr parsing/formatting, and expand tests (TIPC + server reconciliation + devx pformat).

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tractor/runtime/_state.py	Adds 'tipc' to the supported transport protocol key literal.
tractor/msg/types.py	Introduces a variadic UnwrappedAddress wire alias and updates SpawnSpec address fields.
tractor/ipc/_uds.py	Adds rebind_from_sockname opt-in for UDS listener reconciliation.
tractor/ipc/_types.py	Registers TIPC address/transport types and adds AF_TIPC detection in transport_from_stream().
tractor/ipc/_tipc.py	New TIPC backend implementing TIPCAddress, listener publish, and msgpack stream support.
tractor/ipc/_tcp.py	Adds rebind_from_sockname=True to preserve port-0 bind reconciliation behavior.
tractor/ipc/_server.py	Gates post-bind address reconciliation on Address.rebind_from_sockname.
tractor/discovery/_multiaddr.py	Adds TIPC mapping and interim /tipc/... string parsing/formatting.
tractor/discovery/_addr.py	Registers TIPCAddress and adds proto-keyed dispatch support in wrap_address().
tractor/devx/pformat.py	Removes an invalid kwarg passed to pformat_boxed_tb().
tractor/_testing/pytest.py	Adds tipc marker and a generic backend capability gate via Address.is_available().
tractor/_testing/addr.py	Adds random TIPC address generation for test isolation.
tests/ipc/test_tipc.py	Adds address-algebra + kernel-gated integration tests for the TIPC backend.
tests/ipc/test_server.py	Adds regression test for listener .addr reconciliation for tcp and uds.
tests/discovery/test_multiaddr.py	Extends proto↔multiaddr mapping expectations to include tipc.
tests/discovery/conftest.py	Adds TIPC readiness probing via connect-by-name for daemon startup polling.
tests/devx/test_pformat.py	Adds coverage to ensure pformat_caller_frame() and boxed TB rendering don’t raise.

Suppressed comments (1)

tractor/discovery/_multiaddr.py:71

• mk_maddr() can now return str for TIPC while the docstring still claims it constructs a Multiaddr. Update the docstring to reflect the Multiaddr|str return and that str is used when the upstream proto isn’t registered yet.

    Construct a `Multiaddr` from a tractor `Address` instance,
    dispatching on the `.proto_key` to build the correct
    multiaddr-spec-compliant protocol path.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[goodboy]

Addressed in a19a639d. wrap_address() now structurally matches only the exact 3- and 4-element proto-keyed TIPC forms, so a normal two-element address such as ("tipc", 80) continues through TCP dispatch. The regression test covers that collision explicitly.

[goodboy]

Addressed in a19a639d. /tipc parsing now routes the decoded tuple through TIPCAddress.from_addr(), preserving scope normalization and validation, and malformed forms are re-raised as an actionable Invalid TIPC multiaddr error. Regression coverage pins both behaviors.

[goodboy]

Addressed in 145782d3 with a stricter platform gate rather than a post-creation sockopt probe. is_tipc_available() now returns False before socket creation on every non-Linux platform, so fallback UAPI integers cannot alias another OS socket family. The Darwin regression test verifies the socket constructor is never called.

[goodboy]

[P1] Keep Linux-only constants out of macOS collection

tests/ipc/test_tipc.py:12-17 | confidence: high | category: portability

The module imports SOL_TIPC directly from socket. On macOS that symbol does not exist, and pytest collects this module even during a TCP run. Consequently, the entire macOS suite aborts during collection.

Evidence: the current #493 CI job fails with:

ImportError: cannot import name 'SOL_TIPC' from 'socket'

Recommendation: import SOL_TIPC from tractor.ipc._tipc, which already provides the cross-platform UAPI fallback, or otherwise guard the Linux-only import.

[P1] Include actor UUID in generated service names

tractor/ipc/_tipc.py:382-403 | confidence: high | category: correctness

With a live runtime, TIPCAddress.get_random() hashes only actor.aid.name and the process-local PID. Actors with the same name and PID on different hosts therefore publish the same cluster-wide TIPC name.

Because duplicate binds succeed and connections round-robin, this produces silent cross-tree routing rather than EADDRINUSE. PID overlap across hosts is normal, so this is materially more likely than the documented random 32-bit collision.

The collision test at tests/ipc/test_tipc.py:179-204 exercises only the no-runtime branch, which includes a per-call UUID and therefore misses the production branch.

Recommendation: derive the instance from actor.aid.uuid, optionally retaining the actor name for domain separation. Add a regression test where two actors have equal names/PIDs but different UUIDs.

Related follow-ups: #499 owns stable (name, uuid) derivation;
#501 owns post-bind collision verification.

[P2] Make the two-host walkthrough executable

examples/multihost/tipc_cluster/host_a_srv.py:50-55
examples/multihost/tipc_cluster/host_b_client.py:29-47
confidence: high | category: correctness

The advertised two-host example has two deterministic blockers:

• host_a is the registrar itself and is never registered in its own Registrar._registry, so find_actor('host_a') returns None.
• If a portal is obtained another way, Portal.open_context() receives the string 'host_a_srv:echo', but NamespacePath.from_ref() requires a callable and accesses ref.__module__.

The documented multihost demonstration therefore cannot reach echo().

Recommendation: spawn and register a named service actor on host A, and import/pass the enabled echo callable on host B, following the existing working RPC examples.

Related follow-up: #502 owns the reference multihost deployment.

[P2] Handle peer withdrawal during post-connect setup

tractor/ipc/_tipc.py:685-700 | confidence: high | category: reliability

MsgpackTIPCStream.__init__() tolerates getpeername() failing after a peer disconnects, but connect_to() immediately calls sock.getpeername() again without that protection.

A service that accepts and closes promptly can make this second call raise ENOTCONN. The successful dial then fails with a raw OSError, and the now-wrapped socket is not deterministically closed.

Recommendation: reuse the tolerant address already obtained during construction, retain destaddr without a port ID when unavailable, and keep socket/stream ownership under cleanup protection until initialization completes.

[P2] Do not fabricate topology-event scope

tractor/ipc/_tipc.py:941-949
tractor/ipc/_tipc.py:1003-1062
confidence: high | category: correctness

The scope argument is not encoded in struct tipc_subscr, the topology event contains no scope, and this implementation does not include it in the topology-server connection. Calls differing only by scope therefore send identical kernel requests.

Nevertheless, every received event is labeled with the caller-supplied scope. Consumers can consequently treat a publication as cluster-visible even though that scope was never observed or filtered.

Recommendation: represent event scope as unknown or explicitly as caller context. Remove the claim that subscriptions are per-scope unless an actual filtering mechanism is added.

Related follow-up: this is prerequisite feed correctness for #496.

[P2] Surface topology-stream overflow

tractor/ipc/_tipc.py:979-989 | confidence: high | category: reliability

When the memory channel fills, publication and withdrawal events are dropped with only a warning. A push registry can then permanently retain a withdrawn actor or miss a newly published actor while continuing to treat its state as authoritative.

Recommendation: terminate the stream with an explicit overflow/resync signal, or use backpressure if kernel-queue behavior permits it. Consumers must not continue without knowing their view is incomplete.

Related follow-up: #496 is the consumer that needs an authoritative
feed or an explicit resync signal.

[P3] Close finite subscriptions after timeout

tractor/ipc/_tipc.py:929-999 | confidence: high | category: reliability

A TIPC_SUBSCR_TIMEOUT event is forwarded and then the reader resumes waiting. The socket has no remaining subscription, so a caller that receives the timeout and asks for another event waits indefinitely.

Recommendation: return from _stream_name_events() after forwarding the timeout event so the send channel closes.

Related follow-up: #496 will consume this channel lifecycle.

Stack Context
The current submitted PR and contextual branches are not at one common tip:

• #493 head: 1298ba945f9d0a2dfcde014be39c10d8e9169878
• Forge-reported #493 base snapshot: ee17ed9f6e13d955029b2f30c296d036aacc1434
• Current #492 / ng_tpts_planning: d9a6e2e9b4213bb0900b99deda851cb2eaaa2b1b
• Local merge base: ee17ed9f
• Current-upstream divergence: 2 commits on ng_tpts_planning, 19 on #493

The staged wkt/addr_unpacking work is prospective context, not part of #493. Before combining them:

• Preserve #493’s variadic UnwrappedAddress and TIPC registration; the WIP starts from the older two-element alias.
• Peel TunnelledAddress before transport_from_addr() and Endpoint; both currently dispatch by exact wrapper type/module.
• Generalize the WIP’s string-only bindspace annotation because TIPCAddress.bindspace is an integer scope.
• Either peel before endpoint reconciliation or delegate rebind_from_sockname; TIPC must retain False.
• The WIP’s intentionally lossy .unwrap() remains compatible with TIPC’s four-element overlay descriptor.

The composed-address specification is tracked by #498, while #502
owns the resulting WireGuard/TIPC deployment.

The WIP’s unstaged .claude/settings.local.json was excluded.

Checks Run

• Submitted range whitespace check passed:
  git diff --check ee17ed9f...1298ba94
• Prospective current-upstream range check passed:
  git diff --check d9a6e2e9...1298ba94
• WIP staged diff check passed for its four staged source/test files.
• Current CI inspected at head 1298ba94.
• Ubuntu TCP, UDS, TIPC, sdist, and Sphinx checks passed.
• macOS TCP failed during collection as described above.

Checks Not Run
No local tests or analyzers were executed because this was a read-only review. Existing CI results were used as runtime evidence.

Scope
Reviewed GitHub PR #493 at exact range ee17ed9f...1298ba94, covering all 30 changed paths. Provider diff-base OID was unavailable. Current #492 and the staged wkt/addr_unpacking changes were inspected as prospective integration context, not folded into the submitted PR diff.

(this review was generated in some part by opencode using gpt-5.6-sol
(openai))

[goodboy]

Review follow-up

All findings from the full review are addressed at current head 53516b09:

• macOS-safe SOL_TIPC import and strict address dispatch: a19a639d
• UUID-derived actor service names: d52c78c1
• post-connect peer-withdrawal handling: 145782d3
• unknown topology scope and finite-timeout closure: be6f9e86
• executable two-host service example: c1501a36
• explicit topology overflow/resync failure: 53516b09

Regression coverage was added with each fix. Local IPC verification passed (43 passed), full collection passed (479 tests collected), and the refreshed CI run is in progress. The four Copilot inline threads also have commit-linked responses.