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

STRUCTS

BeginTransfer

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Body for StreamControl.begin_transfer.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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

NameTypeDescriptionDefault

LinkStatus

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Status packet for a single link. A link is a unidirectional connection between two peers, and is owned by the first peer. The target node is identified by to.

NameTypeDescriptionDefault
to NodeId

Link target node.

No default
local_id LinkId

An identifier (chosen by the link owner) to label this link. The link owner must guarantee that the tuple (to, local_id) is unique for each of it's held links.

No default
metrics LinkMetrics

Metrics associated with this link.

No default

NodeId

Defined in fuchsia.overnet.protocol/labels.fidl

Address of a node on the overlay network.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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

SocketHandle

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

A proxied socket.

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
id uint64 No default

TransferInitiator

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Body for StreamRef.transfer_initiator.

NameTypeDescriptionDefault
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 StreamRef.transfer_waiter.

NameTypeDescriptionDefault
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

UpdateLinkStatus

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Update status of all links starting from a given node By bundling all link updates together, we guarantee:

  • a simple protocol that can deal with updates, additions, and deletions to the link set
  • no routing decisions based on partial information from any one node
NameTypeDescriptionDefault
link_status vector<LinkStatus>

Status of all active links originating at the sending node

No default

ZirconChannelMessage

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

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

NameTypeDescriptionDefault
bytes vector<uint8>[65536]

Bytes part of the payload.

No default
handles vector<ZirconHandle>[64]

Handles part of the payload.

No default

ENUMS

Implementation

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.

OperatingSystem

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

Type: uint32

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

The type of socket being communicated via SocketHandle.

NameValueDescription
DATAGRAM 0

A datagram oriented socket.

STREAM 1

A stream oriented socket.

TABLES

ConfigRequest

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Overall connection configuration request

OrdinalNameTypeDescription

ConfigResponse

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

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

OrdinalNameTypeDescription

ConnectToServiceOptions

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Options for service connection formation.

OrdinalNameTypeDescription

LinkDiagnosticInfo

Defined in fuchsia.overnet.protocol/diagnostic.fidl

Diagnostic data on a single link.

OrdinalNameTypeDescription
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.

LinkMetrics

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Metrics associated with a link. Note that a link is a uni-directional connection between two nodes.

OrdinalNameTypeDescription
1 round_trip_time uint64

Current round trip time for requests across this link in microseconds.

NodeDescription

Defined in fuchsia.overnet.protocol/diagnostic.fidl

Diagnostic data on a single node.

OrdinalNameTypeDescription
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

PeerConnectionDiagnosticInfo

Defined in fuchsia.overnet.protocol/diagnostic.fidl

Diagnostic data on a single peer connection.

OrdinalNameTypeDescription
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.

16 update_link_status_sends uint64

Number of link status updates.

17 update_link_status_send_bytes uint64

Number of bytes sent due to link status updates.

18 update_link_status_ack_sends uint64

Number of link status update acknowledgements sent.

19 update_link_status_ack_send_bytes uint64

Number of bytes sent due to link status update acknowledgements.

PeerDescription

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

Description of a single node.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription
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

3 links vector<LinkDiagnosticInfo>

Link list, obtained by probing ProbeSelector.LINKS

StreamSocketGreeting

Defined in fuchsia.overnet.protocol/stream_socket.fidl

Introduction packet sent on stream oriented links between Overnet nodes

OrdinalNameTypeDescription
1 magic_string string[32]

Protocol identification string; different kinds of streams might choose a different value here

2 node_id NodeId

Overnet NodeId of the sender

3 connection_label string[32]

Optional label for debugging

4 key uint64

Optional key (used on lossy connections to uniquely identify a handshake pair)

UNIONS

PeerMessage

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.

NameTypeDescription
connect_to_service ConnectToService

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

update_node_description PeerDescription

Update this peers description on the server.

update_link_status UpdateLinkStatus

Update information about a link that this peer knows about on the remote peer.

open_transfer OpenTransfer

Open a transfered stream.

ping uint64

Ping the peer and solicit a response. Used for verifying liveness. Value is echoed back in the PeerReply.pong message.

PeerReply

Defined in fuchsia.overnet.protocol/peer_protocol.fidl

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

NameTypeDescription
update_link_status_ack Empty

Acknowledge an UpdateLinkStatus message

pong uint64

Acknowledge a ping message.

StreamControl

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.

NameTypeDescription
begin_transfer BeginTransfer

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

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.

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.

shutdown zx/status

Shutdown the stream with some status.

StreamRef

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.

NameTypeDescription
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.

transfer_initiator TransferInitiator

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

transfer_waiter TransferWaiter

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

ZirconHandle

Defined in fuchsia.overnet.protocol/zircon_proxy.fidl

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

NameTypeDescription
channel ChannelHandle

A proxied channel.

socket SocketHandle

A proxied socket.

BITS

ChannelRights

Type: uint32

NameValueDescription
READ 1
WRITE 2

ProbeSelector

Type: uint64

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

LINKS 4

Request ProbeResult.links is present in the result

SocketRights

Type: uint32

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.