Document canonical tagged `Address` forms

Separate legacy declaration inputs from canonical serialized outputs
in IPC and architecture docs, and state the same-version registrar
tree contract while no wire-format negotiation exists.

Add PR #505's feature news fragment for `TunnelledAddress` and tagged
TCP/Unix output.

Review: PR #505 (goodboy)
https://github.com/goodboy/tractor/pull/505#pullrequestreview-5094473850

(this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))
wkt/addr_unpacking
Gud Boi 2026-09-02 17:07:38 -04:00
parent 8e428527ff
commit bc132f0b4c
3 changed files with 20 additions and 9 deletions

View File

@ -14,10 +14,11 @@ transport may currently be enabled per actor.
:margin:
:alt: layered runtime stack from app code down to transports
Addresses are "unwrapped" tuples at the API edges:
``('host', port)`` for TCP, filesystem-path pairs for UDS. For
the full layering story — transport protocols, the IPC server,
address types and the msg loop — see
Address declarations still accept the legacy ``(host, port)``
TCP pair and ``(directory, filename)`` UDS pair. Wrapped addresses
emit canonical, protocol-tagged tuples: ``('tcp', host, port)``
and ``('unix', path)``. For the full layering story — transport
protocols, the IPC server, address types and the msg loop — see
:doc:`/explain/architecture`.
.. currentmodule:: tractor

View File

@ -104,17 +104,24 @@ msg-spec *is* the protocol, which is exactly what lets payloads
be type-limited per-context (see ``pld_spec`` in
:doc:`/guide/context`).
Addresses come in two spellings:
Address declarations and serialized values have distinct spellings:
- *unwrapped*: the plain-tuple form you pass to user APIs —
``('127.0.0.1', 1616)`` for tcp, or a
- *legacy declarations*: the plain tuples accepted from existing
callers — ``('127.0.0.1', 1616)`` for tcp, or a
``(<filedir>, <filename>)`` path-pair for uds;
- *canonical serialized values*: protocol-tagged tuples emitted by
address objects — ``('tcp', '127.0.0.1', 1616)`` and
``('unix', <path>)``;
- *wrapped*: the internal ``TCPAddress``/``UDSAddress`` struct
types (plus libp2p-style multiaddr helpers over in
``tractor.discovery``).
You only ever need the tuple form; the runtime wraps and
unwraps at the boundaries.
The runtime accepts either declaration spelling, wraps it at the
boundary and emits the canonical tagged form.
Actors sharing a registrar are expected to run the same Tractor
version; the runtime does not negotiate address formats between
versions.
TCP: the boring default
***********************

View File

@ -0,0 +1,3 @@
Add transparent ``TunnelledAddress`` declarations for WireGuard
multiaddrs and emit canonical protocol-tagged TCP and Unix transport
addresses. Legacy untagged address pairs remain accepted as inputs.