goodboy
/
tractor
1
0
Fork 2
Code Issues 5 Pull Requests 6 Packages Projects Releases Wiki Activity
tractor/ai/tpt-backends/04_tipc_multiaddr_upstream.md

6.7 KiB
Raw Blame History

/tipc multiaddr protocol: upstream issue draft

Candidate issue for multiformats/multiaddr, to be submitted after the encoding questions below have been reviewed locally.

Context

Linux TIPC (Transparent Inter-Process Communication) addresses a service by a location-independent (service type, instance) name. A server publishes that name into the kernel-maintained cluster name table and a client connects by the same name; no host or transport port forms part of the service identity.

TIPC is also known as Cluster Domain Sockets, a useful description of its relationship to Unix-domain sockets. The registered protocol name should nevertheless remain tipc: it matches Linux’s AF_TIPC, socket constants, kernel module and iproute2 frontend. Registering cds would create an ecosystem-specific alias that is harder to map back to the normative kernel API.

We would like to register a tipc multiaddr component so these service endpoints can be represented directly and composed with a bearer or tunnel description:

/tipc/1953628160:1616:2

/ip4/192.168.1.50/udp/51820/wg/u<key>/tipc/1953628160:1616:2
\____________ WireGuard bearer ____________/\____ TIPC service ____/

In the composed form, the components through /wg/<key> identify the routed bearer and tunnel peer. The /tipc/... component is pure service identity, resolved to a current publisher by the TIPC kernel name table. Unlike a TCP endpoint, it deliberately has no inner IP address or port.

This proposal does not imply that parsing the multiaddr configures a TIPC bearer. In particular, TIPC over a WireGuard interface requires a separately configured TIPC UDP bearer; WireGuard interfaces are L3 devices and cannot carry TIPC Ethernet media directly.

Today that bearer is configured through iproute2’s tipc frontend, which speaks the kernel’s TIPCv2 generic-netlink family. pyroute2 already provides WireGuard support and generic-netlink primitives but has no TIPC codec/module; adding one is a complementary deployment automation track, not part of this address-format proposal.

Proposed protocol

  • Name: tipc
  • Code: TBD, allocated in multiformats/multicodec under the multiaddr tag before implementations stabilize one
  • Size: 72 bits
  • Value: service type, service instance and publication scope

Binary form

Exactly nine bytes with no value-length prefix:

Offset Size Field Encoding
0 4 bytes service type unsigned 32-bit big-endian
4 4 bytes service instance unsigned 32-bit big-endian
8 1 byte publication scope unsigned enum byte 
tipc-value = uint32be(type) || uint32be(instance) || uint8(scope)

For type 1953628160 (0x74720000), instance 1616 and cluster scope 2, the payload is:

74 72 00 00 00 00 06 50 02

String form

Use one multiaddr value segment containing three canonical decimal integers:

/tipc/<type>:<instance>:<scope>

Canonical values have no sign, whitespace, alternate radix or leading zeroes, except that zero itself is 0. type and instance must fit unsigned 32-bit fields. Scope is one of:

  • 2: TIPC_CLUSTER_SCOPE
  • 3: TIPC_NODE_SCOPE

The existing experimental spelling /tipc/<type>/<instance>/<scope> cannot be registered as one normal multiaddr protocol: generic parsing treats each slash-delimited name as another protocol component. A single structured value preserves TIPC’s atomic service-address semantics without registering three artificial protocols.

Why scope is included

TIPC scope controls where a bound service publication is visible. The same address representation is used for listener configuration and dialing, so retaining scope lets a multiaddr round-trip the full socket address rather than silently turning a node-local bind into a cluster publication.

Modern Linux UAPI defines cluster and node scopes. The deprecated zone spelling should not receive a new wire value; implementations may normalize legacy input to cluster scope before encoding.

Composition

Standalone service:

/tipc/1953628160:1616:2

TIPC service reached through a WireGuard bearer:

/ip4/192.168.1.50/udp/51820/wg/u<key>/tipc/1953628160:1616:2

This differs intentionally from TCP over WireGuard:

/ip4/192.168.1.50/udp/51820/wg/u<key>/ip4/10.0.11.1/tcp/1616

TCP repeats an inner locative address. TIPC does not: its service name is resolved and load-balanced in-kernel across current publishers.

Semantics and security

  • A TIPC service name identifies a service, not a unique process. Multiple publishers may bind the same name and connections can be distributed among them.
  • Publication scope is reachability metadata, not authentication.
  • A composed /wg key authenticates the tunnel peer, not the TIPC service publisher.
  • TIPC’s optional native AES-GCM link encryption is independent of this address codec and of WireGuard.
  • Codec implementations should validate field widths and canonical text only; cluster membership and publisher authorization remain deployment concerns.

Implementation plan

  1. Reserve a multiaddr-tagged code in multiformats/multicodec.
  2. Add the fixed-size protocol row and normative encoding text to multiformats/multiaddr.
  3. Add codecs and cross-language test vectors, beginning with multiformats/py-multiaddr.
  4. Verify standalone and composed wg + tipc string/binary round-trips.

Open questions

  1. Is a fixed 72-bit value preferred over a self-describing or variable-width tuple for this kernel-defined address?
  2. Should node scope be representable in a generally shareable multiaddr, or should the registered form be cluster-only?
  3. Does multiaddr have an existing convention for structured numeric values that should replace the colon-separated text form?
  4. Should the specification describe TIPC service ranges, or keep this protocol limited to singleton service names used for connection endpoints?

References