Google is committed to advancing racial equity for Black communities. See how.

fuchsia.overnet.protocol

PROTOCOLS

Diagnostic

Defined in fuchsia.overnet.protocol/diagnostic.fidl

Diagnostic information exported by Overnet peers. This interface is additionally exported to the Overnet mesh.

Probe

Probe some basic statistics from this node

Request

NameType
selector ProbeSelector

Response

NameType
result ProbeResult

UdpReachable

Defined in fuchsia.overnet.protocol/relay.fidl

This capability is advertised via Overnet's peer discovery protocol when a given node is reachable via UDP. This allows discovery of UDP Overnet connectivity via Overnet, enabling for example:

  • Using a low bandwidth (serial? bluetooth?) link to discover and bootstrap a higher bandwidth UDP based link.
  • Using an intermediate UDP based node to discover and connect directly to other UDP based nodes.

GetPossibleAddressList

Hanging-get style returns the latest list of socket addresses that this node may be reachable from. This can change over time as extra sockets are added or removed, or NAT-ed addresses for existing sockets are learned, or indeed as connected networks change.

Request

<EMPTY>

Response

NameType
address vector<fuchsia.net/SocketAddress>

STRUCTS

BeginTransfer

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Body for fuchsia.overnet.protocol/StreamControl.begin_transfer.

FieldTypeDescriptionDefault
new_destination_node NodeId

The new owner of this stream endpoint.

No default
transfer_key TransferKey

A key to identify this transfer of ownership.

No default

ChannelHandle

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

A proxied channel.

FieldTypeDescriptionDefault
rights ChannelRights

The handle rights that are given to this handle.

No default
stream_ref StreamRef

The Overnet proxy stream that was created to carry this channel. The protocol over said stream will be a ZirconChannel.

No default

ConnectToService

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Create a new stream, labelled stream_id, to communicate with the advertised service service_name.

FieldTypeDescriptionDefault
service_name string[255]

Which service to connect to.

No default
stream_ref StreamRef

On which QUIC stream will this service connection be formed.

No default
rights ChannelRights

The channel rights for this connection.

No default
options ConnectToServiceOptions

Ancillary options for this connection.

No default

Empty

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

<EMPTY>

EventPairHandle

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

A proxied eventpair.

FieldTypeDescriptionDefault
rights EventPairRights

The handle rights that are given to this handle.

No default
stream_ref StreamRef

The Overnet proxy stream that was created to carry this eventpair. No payloads will be sent over this stream, however transport and signal control messages will be per the normal StreamControl/SignalUpdate protocols used for all handle types.

No default

LinkControlMessage

Defined in fuchsia.overnet.protocol/link_protocol.fidl

Control message sent over a link.

FieldTypeDescriptionDefault
seq uint64 No default
payload LinkControlPayload No default

NodeId

Defined in fuchsia.overnet.protocol/labels.fidl

Address of a node on the overlay network.

FieldTypeDescriptionDefault
id uint64 No default

OpenTransfer

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Create a new stream, labelled stream_id, to finalize the transfer labelled transfer_key.

FieldTypeDescriptionDefault
stream_id StreamId

On which QUIC stream will this service connection be formed.

No default
transfer_key TransferKey

Transfer key tracking the transfer.

No default

Route

Defined in fuchsia.overnet.protocol/link_protocol.fidl

Update route visibility via a node.

FieldTypeDescriptionDefault
destination NodeId

Target node id that can be routed to via this peer.

No default
route_metrics RouteMetrics

Metrics associated with this route.

No default

SetRoute

Defined in fuchsia.overnet.protocol/link_protocol.fidl

Partial send of new routes.

FieldTypeDescriptionDefault
is_end bool

Is this the last SetRoute frame in an update?

No default
routes vector<Route>

Routes to add to the route map being sent.

No default

SocketHandle

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

A proxied socket.

FieldTypeDescriptionDefault
rights SocketRights

The handle rights that are given to this handle.

No default
stream_ref StreamRef

The Overnet proxy stream that was created to carry this socket. The protocol over said stream will be a ZirconSocket.

No default
socket_type SocketType

Socket options, per zx_socket_create.

No default

StreamId

Defined in fuchsia.overnet.protocol/labels.fidl

Identifies a single overnet stream between two processes on the Overnet mesh.

FieldTypeDescriptionDefault
id uint64 No default

TransferInitiator

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Body for fuchsia.overnet.protocol/StreamRef.transfer_initiator.

FieldTypeDescriptionDefault
stream_id StreamId

The drain stream for this transfer. Buffered messages from the old proxy end will be sent via this unidirectional QUIC stream and should be processed prior to processing any messages from the new endpoint.

No default
new_destination_node NodeId

The peer node id for this proxy that we should reach out to. Note that this may be the same node that receives this message.

No default
transfer_key TransferKey

A key to identify this transfer of ownership.

No default

TransferWaiter

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Body for fuchsia.overnet.protocol/StreamRef.transfer_waiter.

FieldTypeDescriptionDefault
stream_id StreamId

The drain stream for this transfer. Buffered messages from the old proxy end will be sent via this unidirectional QUIC stream and should be processed prior to processing any messages from the new endpoint.

No default
transfer_key TransferKey

A key to identify this transfer of ownership.

No default

ZirconChannelMessage

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

A single message proxied from a Zircon channel over an Overnet stream.

FieldTypeDescriptionDefault
bytes vector<uint8>[65536]

Bytes part of the payload.

No default
handles vector<ZirconHandle>[64]

Handles part of the payload.

No default

ENUMS

Implementation strict

Type: uint32

Defined in fuchsia.overnet.protocol/diagnostic.fidl

The implementation of a node that's running.

NameValueDescription
UNIT_TEST 0

Some unit test... shouldn't be seen in the wild.

OVERNET_STACK 1

The overnetstack daemon on Fuchsia.

ASCENDD 2

The non-Fuchsia routing daemon Ascendd.

HOIST_RUST_CRATE 3

The hoist Rust crate embedding Overnet.

UNKNOWN 4

The unknown value reported when otherwise unconfigured.

OperatingSystem strict

Type: uint32

Defined in fuchsia.overnet.protocol/diagnostic.fidl

The operating system running a node.

NameValueDescription
FUCHSIA 0

Fuchsia

LINUX 1

Linux

MAC 2

MacOS

SocketType strict

Type: uint32

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

The type of socket being communicated via fuchsia.overnet.protocol/SocketHandle.

NameValueDescription
DATAGRAM 0

A datagram oriented socket.

STREAM 1

A stream oriented socket.

TABLES

AscenddLinkConfig

Defined in fuchsia.overnet.protocol/diagnostic.fidl

An ascendd link configuration.

OrdinalFieldTypeDescription
1 path string[1024]

Path to the ascendd socket.

2 connection_label string[32]

Connection label for this link.

ConfigRequest

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Overall connection configuration request

OrdinalFieldTypeDescription

ConfigResponse

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Overall connection configuration response - sent as the first response message on the connection stream.

OrdinalFieldTypeDescription

ConnectToServiceOptions

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Options for service connection formation.

OrdinalFieldTypeDescription

LinkDiagnosticInfo

Defined in fuchsia.overnet.protocol/diagnostic.fidl

Diagnostic data on a single link.

OrdinalFieldTypeDescription
1 source NodeId

Source address.

2 destination NodeId

Destination address.

3 source_local_id uint64

Source identifier for this link.

4 received_packets uint64

Number of packets received.

5 sent_packets uint64

Number of packets sent.

6 received_bytes uint64

Number of bytes received.

7 sent_bytes uint64

Number of bytes sent.

8 round_trip_time_microseconds uint64

Round trip time for the connection in microseconds.

9 pings_sent uint64

Number of ping requests sent.

10 packets_forwarded uint64

Number of packets forwarded.

11 config LinkConfig

Type of link & configuration data.

LinkIntroduction

Defined in fuchsia.overnet.protocol/link_protocol.fidl

Introduction data for a link - basic configuration stuff will go here.

OrdinalFieldTypeDescription
1 you_are fuchsia.net/SocketAddress

For IP based link protocols: the address of the receiver of this introduction, as observed by the sender.

NodeDescription

Defined in fuchsia.overnet.protocol/diagnostic.fidl

Diagnostic data on a single node.

OrdinalFieldTypeDescription
1 operating_system OperatingSystem

A string saying something about what operating system this node is running on Currently used: 'fuchsia', 'linux', 'mac'

2 implementation Implementation

A string saying something about the runtime environment of a node

3 binary string[32]

The name of the binary containing Overnet

4 hostname string[32]

The hostname of the device running Overnet

PeerConnectionDiagnosticInfo

Defined in fuchsia.overnet.protocol/diagnostic.fidl

Diagnostic data on a single peer connection.

OrdinalFieldTypeDescription
1 source NodeId

Source address.

2 destination NodeId

Destination address.

3 is_client bool

Whether this connection is a client.

4 is_established bool

True if the connection established and ready to send traffic.

5 received_packets uint64

Number of packets received.

6 sent_packets uint64

Number of packets sent.

7 lost_packets uint64

Number of packets lost.

8 round_trip_time_microseconds uint64

Round trip time for the connection in microseconds.

9 congestion_window_bytes uint64

Current congestion window in bytes.

10 messages_sent uint64

Number of overnet messages sent.

11 bytes_sent uint64

Number of bytes sent due to overnet messages.

12 connect_to_service_sends uint64

Number of connect to service requests.

13 connect_to_service_send_bytes uint64

Number of bytes sent due to connect to service requests.

14 update_node_description_sends uint64

Number of node description updates.

15 update_node_description_send_bytes uint64

Number of bytes sent due to node description updates.

PeerDescription

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Description of a single node.

OrdinalFieldTypeDescription
1 services vector<string>

The set of services published by this node.

ProbeResult

Defined in fuchsia.overnet.protocol/diagnostic.fidl

Composition of results from Diagnostic/Probe.

OrdinalFieldTypeDescription
1 node_description NodeDescription

Node description, obtained by probing ProbeSelector.NODE_DESCRIPTION

2 peer_connections vector<PeerConnectionDiagnosticInfo>

Peer connections list, obtained by probing ProbeSelector.PEER_CONNECTIONS

RouteMetrics

Defined in fuchsia.overnet.protocol/link_protocol.fidl

Metrics that may be used to determine the optimimum route for a packet.

OrdinalFieldTypeDescription
1 intermediate_hops vector<NodeId>

Intermediate proposed path to the destination (used for loop prevention).

2 round_trip_time_us uint64

Round trip time to the destination and back (in microseconds).

SignalUpdate

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

Signal state updates. Transported as a side channel for each handle type, these propagate some signal bits.

OrdinalFieldTypeDescription
1 assert_signals Signals

Update some signals

UNIONS

LinkConfig strict

Defined in fuchsia.overnet.protocol/diagnostic.fidl

A description of the configuration of a given link.

Ordinal
VariantTypeDescription
7 socket Empty

A link configured via fuchsia.overnet.MeshController/AttachSocket - these are links that are implemented externally to Overnet.

1
2 udp fuchsia.net/Ipv6SocketAddress

A link using overnetstack's UDP protocol. The content of this config is the address of the peer.

3 serial_server string[256]

A link using Overnet's serial protocol acting as a server. The text is the canonicalized unparsed serial descriptor for this serial port.

4 serial_client string[256]

A link using Overnet's serial protocol acting as a client. The text is the canonicalized unparsed serial descriptor for this serial port.

5 ascendd_server AscenddLinkConfig

Ascendd server link. The text is the path to the ascendd socket.

6 ascendd_client AscenddLinkConfig

A host binary connecting to ascendd. Text is the path to the ascendd socket.

LinkControlFrame strict

Defined in fuchsia.overnet.protocol/link_protocol.fidl

Control frame sent over a link.

Ordinal
VariantTypeDescription
1 ack uint64
2 message LinkControlMessage

LinkControlPayload strict

Defined in fuchsia.overnet.protocol/link_protocol.fidl

Control message payload.

Ordinal
VariantTypeDescription
1 introduction LinkIntroduction

Initial message.

2 set_route SetRoute

Configure some routes. Since the complete routing table might be longer than can fit in one frame, it may take multiple set_route messages to update a routing table. is_end will be set on the last frame of a given update round to signify that the update is done.

PeerMessage strict

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Peer-to-peer protocol between two Overnet nodes. Client QUIC connections send this xunion to servers over QUIC stream 0.

Ordinal
VariantTypeDescription
1 connect_to_service ConnectToService

Request to create a channel to a service exported by this peer.

2 update_node_description PeerDescription

Update this peers description on the server.

3
4 open_transfer OpenTransfer

Open a transfered stream.

5

PeerReply strict

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Reply messages for PeerMessage, where appropriate. The ConfigResponse message must have been sent already.

Ordinal
VariantTypeDescription
2

StreamControl strict

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Stream control message: sent instead of usual stream frames if the frame type is 1 (StreamControl). TODO: consider defining the stream framing format in FIDL also.

Ordinal
VariantTypeDescription
1 begin_transfer BeginTransfer

A transfer is beginning: the sending node would like to transfer control.

2 ack_transfer Empty

Acknowledge a begin_transfer - the sender has seen a previously sent begin_transfer, and responded to it. This should be the last message sent on a regular stream.

3 end_transfer Empty

End a transfer - signal that a drain stream has finished draining. This should be the last message sent on a drain stream.

4 shutdown zx/status

Shutdown the stream with some status.

StreamRef strict

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

A StreamRef identifies a new proxied stream, and details how that stream will come to be on the receiving node.

Ordinal
VariantTypeDescription
1 creating StreamId

A new proxy is being created, and the other end of the proxy is on the sending node. This is the simple case, and we just communicate the QUIC stream ID that will be used to carry traffic.

2 transfer_initiator TransferInitiator

An existing proxy is being transferred to this node. This node should initiate communication with the peer.

3 transfer_waiter TransferWaiter

An existing proxy is being transferred to this node. This node should await contact from the peer.

ZirconHandle strict

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

A single handle to be proxied. Not all Zircon types are supported.

Ordinal
VariantTypeDescription
1 channel ChannelHandle

A proxied channel.

2 socket SocketHandle

A proxied socket.

3 event_pair EventPairHandle

A proxied eventpair.

BITS

ChannelRights strict

Type: uint32

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

Channel rights. Overnet treats rights as per-object type, to reduce the space of things that can be communicated over its wire format. Transfer rights are always assumed present.

NameValueDescription
READ 1
WRITE 2

EventPairRights strict

Type: uint32

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

EventPair rights. Overnet treats rights as per-object type, to reduce the space of things that can be communicated over its wire format. Transfer rights are always assumed present.

NameValueDescription
DO_NOT_USE 2147483648

ProbeSelector strict

Type: uint64

Defined in fuchsia.overnet.protocol/diagnostic.fidl

Selector bits for what to probe during Diagnostic/Probe.

NameValueDescription
NODE_DESCRIPTION 1

Request ProbeResult.node_description is present in the result

PEER_CONNECTIONS 2

Request ProbeResult.peer_connections is present in the result

Signals strict

Type: uint32

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

Signals that can be propagated. These are deliberately chosen to be different bits than defined in Zircon, to force mapping code to exist, and minimize the chance that Zircon ABI accidentally becomes Overnet protocol.

NameValueDescription
USER_0 1
USER_1 2
USER_2 4
USER_3 8
USER_4 16
USER_5 32
USER_6 64
USER_7 128

SocketRights strict

Type: uint32

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

Socket rights. Overnet treats rights as per-object type, to reduce the space of things that can be communicated over its wire format. Transfer rights are always assumed present.

NameValueDescription
READ 1
WRITE 2

CONSTANTS

NameValueTypeDescription
MAX_SERVICE_NAME_LENGTH 255 uint64
TRANSFER_KEY_LENGTH 16 uint32

Length of a transfer key.

TYPE ALIASES

NameValueDescription
LinkId uint64

Node-local link label.

TransferKey array[TRANSFER_KEY_LENGTH]

A transfer key is used when moving a stream endpoint from one node to another. It identifies a single transfer, should be unique (so, made from random bytes), and should be discarded at the end of the transfer.