Multiaddresses: a novel libp2p peeps idea worth embracing?

[goodboy]

Use upstream py-multiaddr for address handling

Motivation

The existing tractor.discovery._multiaddr mod was a hand-rolled
multiaddr parser that reimplemented (poorly, tho as a first
prototype) what the libp2p's multiformats
community already standardized.

The first WIP draft was always a prototype custom parse_maddr() fn,
and was never even called anywhere in the codebase — it was dead code
waiting for adoption that never came.

Meanwhile the .maddr properties on transport streams used
non-standard protocol names (ipv4 instead of ip4, uds instead
of unix) and the UDS variant had a bug where it only emitted the
directory path, dropping the socket filename.

By adopting py-multiaddr we get spec-compliant protocol names (per
the multiformats protocol registry), proper
Multiaddr objects with .protocols(), .values(), and
.encapsulate()/.decapsulate() for future use, and ipv4/ipv6
auto-detection via stdlib ipaddress (resolving an existing TODO).

---

Src of research

The following provide info on why/how this impl makes sense,

• https://github.com/multiformats/multiaddr#protocols

  • https://github.com/multiformats/multiaddr/blob/master/protocols.csv
  • https://github.com/multiformats/multiaddr/blob/master/protocols/unix.md
  • https://datatracker.ietf.org/doc/html/rfc3986#section-3.4

• https://github.com/multiformats/py-multiaddr/

  • https://github.com/multiformats/py-multiaddr/blob/44426b676745f1fd5e896d94f82ef4dfcf19cd72/tests/test_multiaddr.py#L131

---

Summary of changes

By chronological commit

• (f94b562b) Add uds protocol to ._multiaddr tables and
  tweak typing (cherry-pick from to_asyncio_crash_handler branch).

• (7b220c9f) Add usage snippet showing Multiaddr
  construction for IP4 and UDS paths.

• (536110fc) Add multiaddr>=0.2.0 dep to
  pyproject.toml.

• (2de1d03e) Drop the NIH custom parser (parse_maddr(),
  iter_prot_layers(), prots/ prot_params tables) and replace
  with a thin mk_maddr() factory wrapping the upstream
  multiaddr.Multiaddr type.

  • Standardize protocol names to match the multiformats spec (ipv4
    -> ip4, uds -> unix).
  • Fix UDS .maddr to include full sockpath (was dropping
    filename).

---

Scopes changed

• pyproject.toml

  • add multiaddr>=0.2.0 dep.

• tractor.discovery._multiaddr

  • full rewrite; drop bidict-based protocol tables, custom parser
    fns. Replace with mk_maddr() factory dispatching on
    Address.proto_key.
  • Re-export Multiaddr from upstream lib.
  • _tpt_proto_to_maddr mapping for internal proto_key ->
    standard protocol name translation.

• tractor.ipc._tcp

  • .maddr now returns Multiaddr via mk_maddr(self.raddr),
    auto-detects ip4/ip6.

• tractor.ipc._uds

  • .maddr returns Multiaddr|str.
  • fix sockpath to include filedir / filename.

• tractor.ipc._transport

  • MsgTransport.maddr type hint updated to Multiaddr|str.

• tractor.runtime._runtime

  • fix hardcoded /ipv4/ -> /ip4/ in log format string.

---

Future follow up

Ideally, tractor will eventually natively support "tunnelled multiaddrs"
where you can one-line-declare a composed protocol stack connection
such as,

from multiaddr import Multiaddr
actord = Multiaddr("/ip4/192.168.0.13/tcp/80")
wg_portal = Multiaddr("/ip4/10.20.30.40/udp/666")
actord_over_wg = wg_portal.encapsulate(actord)
print(actord_over_wg)
# /ip4/10.20.30.40/udp/666/ip4/192.168.0.13/tcp/80

(NOTE, that there is no current wg support in multiaddr yet,
so this will need to be proposed and patched.)

Our runtime should be able to re-construct the necessary layerd tpt
protos per sub-actor Address and bind all necessary endpoints, per proto (stack) layer,
from a single multiaddr input.

---

(this pr content was generated in some part by claude-code)

[Copilot]

Pull request overview

This PR refactors tractor’s internal module layout (introducing runtime/, spawn/, discovery/ subpackages), renames the “arbiter” concept to “registrar” while preserving backward compatibility, and adopts upstream py-multiaddr for multiaddress formatting.

Changes:

• Add multiaddr>=0.2.0 and replace the custom multiaddr parser with py-multiaddr + a new mk_maddr() helper used by TCP/UDS transports.
• Move/rename registry implementation (Arbiter → Registrar) into tractor.discovery._registry and update imports throughout the codebase/tests.
• Introduce a RuntimeVars(msgspec.Struct) and a get_runtime_vars() accessor; update test tooling (tractor_test) and spawning helpers.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pyproject.toml	Adds multiaddr dependency required for new multiaddress support.
uv.lock	Locks new dependency set (incl. multiaddr and its transitive deps).
tractor/discovery/_multiaddr.py	New helper converting internal Address → Multiaddr.
tractor/ipc/_tcp.py, tractor/ipc/_uds.py, tractor/ipc/_transport.py	Transport .maddr now produced via mk_maddr() (multiaddr-formatted).
tractor/discovery/_registry.py, tractor/runtime/_runtime.py, tractor/_root.py	Moves registry actor to discovery package; provides compatibility aliases.
tractor/runtime/_state.py	Introduces RuntimeVars + get_runtime_vars() accessor.
tractor/_testing/pytest.py	Reworks tractor_test decorator to support optional args via wrapt.
tractor/spawn/_mp_fixup_main.py	New spawning helper module based on multiprocessing.spawn utilities.
Tests/examples/misc imports	Updates imports and terminology (arbiter → registrar).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Windows start_method validation is currently inverted: when start_method is missing (None), the code still checks start_method != 'trio' and will always raise on Windows. If the intent is to force start_method='trio' on Windows, set the default to 'trio' when missing and only raise when an explicit non-'trio' value is provided.

[goodboy]

🤖 response authored by claude-code

Valid observation, but _testing/pytest.py is not touched by this PR — pre-existing logic outside the scope of the multiaddr changes.

[Copilot]

_tpt_proto_to_maddr is defined but never used in this module. With Ruff's F (unused) rules enabled, this will fail linting; either remove it or use it in mk_maddr() (e.g. to map proto_key to multiaddr protocol strings).

[goodboy]

🤖 response authored by claude-code

Good catch — _tpt_proto_to_maddr was defined as a lookup table but mk_maddr() hardcoded the protocol names in each match arm. Now the mapping is used to resolve proto_key -> multiaddr protocol name, and unknown keys are rejected upfront.

📎 fixed in d09ecde7

[Copilot]

The tractor_test wrapper asserts kwargs[kw] for any fixture name present in the wrapped test signature. This will (a) raise KeyError if pytest didn't pass that kwarg and (b) fail for legitimate falsy values like debug_mode=False or reg_addr=('', 0). Prefer checking key presence (kw in kwargs) or defaulting via kwargs.get(kw, ...) instead of asserting truthiness.

[goodboy]

🤖 response authored by claude-code

Same — tractor_test wrapper is pre-existing code not modified by this PR. The assertion pattern is a separate concern.

[Copilot]

Path is used but not imported, so this snippet won't run as-is. Add from pathlib import Path (and consider normalizing spacing) to keep the example executable.

[goodboy]

🤖 response authored by claude-code

Added from pathlib import Path import to the snippet.

📎 fixed in d09ecde7

[Copilot]

Typo in docstring: recevier should be receiver.

Suggested change

	remotely; enables them being re-raised on the receiver side of

[goodboy]

🤖 response authored by claude-code

Valid typo, but _exceptions.py is not touched by this PR — out of scope for the multiaddr changes.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

tractor/discovery/_addr.py:214

• wrap_address() now accepts multiaddr strings, but the docstring still describes only wrapping an UnwrappedAddress tuple/list. Update the docstring (and any referenced type aliases) to reflect that a leading-/ multiaddr str is a supported input and what formats are accepted.

    addr: UnwrappedAddress|str,
) -> Address:
    '''
    Wrap an `UnwrappedAddress` as an `Address`-type based
    on matching builtin python data-structures which we adhoc
    use for each.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

parse_maddr() builds UDSAddress using str(sockpath.parent)/str(sockpath.name) and also strips the leading / from the unix value. This produces a UDSAddress whose filedir/filename are plain strings and can turn absolute paths into relative ones, which then breaks UDS runtime code that expects Path-like behavior (e.g. .bindspace.is_dir() / .sockpath). Construct the UDSAddress via UDSAddress.from_addr(...) (or pass Path objects) and preserve the absolute path semantics from the parsed multiaddr.

Suggested change

	# unix protocol value; strip it to recover the
	# original relative path.
	raw: str = maddr.value_for_protocol('unix')
	sockpath = Path(raw.lstrip('/'))
	return UDSAddress(
	filedir=str(sockpath.parent),
	filename=str(sockpath.name),
	# unix protocol value. Preserve the path semantics
	# and pass `Path` components through to `UDSAddress`.
	raw: str = maddr.value_for_protocol('unix')
	sockpath = Path(raw)
	return UDSAddress(
	filedir=sockpath.parent,
	filename=sockpath.name,

[goodboy]

🤖 response authored by claude-code

Valid — parse_maddr() was stripping the leading / from the unix protocol value which turned absolute runtime paths into relative ones. Removed the .lstrip('/') so the lib-prepended / now correctly restores absolute path semantics. Updated UDS test cases to use absolute paths matching real runtime behavior.

📎 fixed in 1e0bca22

[Copilot]

The UDS tests construct UDSAddress instances with filedir/filename as plain strings and assume absolute paths cause /unix//... double-slash issues. In the runtime, UDSAddress typically carries Path components and mk_maddr() already strips the leading / to avoid double slashes. Consider updating these tests to use Path inputs (and add a case covering an absolute sockpath) so they exercise the same types/round-trip behavior used by the UDS transport.

[goodboy]

🤖 response authored by claude-code

Updated all UDS test params to use absolute paths (/tmp/tractor_rt/..., /tmp/tractor_test/...) so they exercise the same path semantics as the runtime. The test_parse_maddr_uds assertion now checks for the exact absolute filedir string.

📎 fixed in 1e0bca22

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

tractor/discovery/_addr.py:214

• wrap_address() now accepts multiaddr-format strings (see the new case str() if addr.startswith('/')), but the docstring still describes only wrapping an UnwrappedAddress. Please update the docstring to mention the accepted string form (and, if relevant, what multiaddr protocol combos are supported).

    '''
    Wrap an `UnwrappedAddress` as an `Address`-type based
    on matching builtin python data-structures which we adhoc
    use for each.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

MsgTransport.maddr is now typed as Multiaddr|str, but downstream APIs still assume str (e.g. Channel.maddr and Context.dst_maddr are annotated as str and return the transport value directly). This creates an inconsistent public surface and can break type-checking (and potentially callers that rely on str methods). Consider either (a) standardizing on returning Multiaddr everywhere and updating the dependent annotations/APIs, or (b) keeping MsgTransport.maddr as str by returning str(Multiaddr) at the transport boundary (and providing a separate .multiaddr/.maddr_obj accessor for the object form).

Suggested change

	def maddr(self) -> Multiaddr|str:
	def maddr(self) -> str:

[Copilot]

The inline comments here still document Channel.maddr() / Context.maddr() as returning str, but transports now return Multiaddr (or Multiaddr|str). Update these comments to reflect the current API so log/debug output guidance stays accurate.

Suggested change

	# - `Channel.maddr() -> str:` obvi!
	# - `Context.maddr() -> str:`
	# - `Channel.maddr() -> Multiaddr | str:` obvi!
	# - `Context.maddr() -> Multiaddr | str:`