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:
|
||||
: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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
***********************
|
||||
|
|
|
|||
|
|
@ -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