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
parent
8e428527ff
commit
bc132f0b4c
|
|
@ -14,10 +14,11 @@ transport may currently be enabled per actor.
|
||||||
:margin:
|
:margin:
|
||||||
:alt: layered runtime stack from app code down to transports
|
:alt: layered runtime stack from app code down to transports
|
||||||
|
|
||||||
Addresses are "unwrapped" tuples at the API edges:
|
Address declarations still accept the legacy ``(host, port)``
|
||||||
``('host', port)`` for TCP, filesystem-path pairs for UDS. For
|
TCP pair and ``(directory, filename)`` UDS pair. Wrapped addresses
|
||||||
the full layering story — transport protocols, the IPC server,
|
emit canonical, protocol-tagged tuples: ``('tcp', host, port)``
|
||||||
address types and the msg loop — see
|
and ``('unix', path)``. For the full layering story — transport
|
||||||
|
protocols, the IPC server, address types and the msg loop — see
|
||||||
:doc:`/explain/architecture`.
|
:doc:`/explain/architecture`.
|
||||||
|
|
||||||
.. currentmodule:: tractor
|
.. currentmodule:: tractor
|
||||||
|
|
|
||||||
|
|
@ -104,17 +104,24 @@ msg-spec *is* the protocol, which is exactly what lets payloads
|
||||||
be type-limited per-context (see ``pld_spec`` in
|
be type-limited per-context (see ``pld_spec`` in
|
||||||
:doc:`/guide/context`).
|
: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 —
|
- *legacy declarations*: the plain tuples accepted from existing
|
||||||
``('127.0.0.1', 1616)`` for tcp, or a
|
callers — ``('127.0.0.1', 1616)`` for tcp, or a
|
||||||
``(<filedir>, <filename>)`` path-pair for uds;
|
``(<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
|
- *wrapped*: the internal ``TCPAddress``/``UDSAddress`` struct
|
||||||
types (plus libp2p-style multiaddr helpers over in
|
types (plus libp2p-style multiaddr helpers over in
|
||||||
``tractor.discovery``).
|
``tractor.discovery``).
|
||||||
|
|
||||||
You only ever need the tuple form; the runtime wraps and
|
The runtime accepts either declaration spelling, wraps it at the
|
||||||
unwraps at the boundaries.
|
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
|
TCP: the boring default
|
||||||
***********************
|
***********************
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
Loading…
Reference in New Issue