blob: cd2dd9f921bfd6032d37951eb4c937350417c601 [file] [log] [blame]
// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.overnet.protocol;
using zx;
// TODO(ctiller): make this fuchsia.io.MAX_FILENAME
const MAX_SERVICE_NAME_LENGTH uint64 = 255;
/// Peer-to-peer protocol between two Overnet nodes.
/// Client QUIC connections send this xunion to servers over QUIC stream 0.
type PeerMessage = strict union {
/// Request to create a channel to a service exported by this peer.
1: connect_to_service ConnectToService;
/// Update this peers description on the server.
2: update_node_description PeerDescription;
3: reserved;
/// Open a transfered stream.
4: open_transfer OpenTransfer;
5: reserved;
};
/// Overall connection configuration request
type ConfigRequest = table {};
/// Overall connection configuration response - sent as the first response
/// message on the connection stream.
type ConfigResponse = table {};
/// Reply messages for PeerMessage, where appropriate.
/// The ConfigResponse message must have been sent already.
type PeerReply = strict union {
/// Acknowledge an UpdateLinkStatus message
1: update_link_status_ack Empty;
2: reserved;
};
type Empty = struct {};
/// Create a new stream, labelled `stream_id`, to communicate with the
/// advertised service `service_name`.
type ConnectToService = struct {
/// Which service to connect to.
service_name string:MAX_SERVICE_NAME_LENGTH;
/// On which QUIC stream will this service connection be formed.
stream_ref StreamRef;
/// The channel rights for this connection.
rights ChannelRights;
/// Ancillary options for this connection.
options ConnectToServiceOptions;
};
/// Options for service connection formation.
type ConnectToServiceOptions = table {};
/// Create a new stream, labelled `stream_id`, to finalize the transfer
/// labelled `transfer_key`.
type OpenTransfer = struct {
/// On which QUIC stream will this service connection be formed.
stream_id StreamId;
/// Transfer key tracking the transfer.
transfer_key TransferKey;
};
/// Description of a single node.
type PeerDescription = table {
/// The set of services published by this node.
1: services vector<string:MAX_SERVICE_NAME_LENGTH>:MAX;
};
/// 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.
type StreamControl = strict union {
/// A transfer is beginning: the sending node would like to transfer
/// control.
1: begin_transfer BeginTransfer;
/// 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.
2: ack_transfer Empty;
/// End a transfer - signal that a drain stream has finished draining.
/// This should be the last message sent on a drain stream.
3: end_transfer Empty;
/// Shutdown the stream with some status.
4: shutdown zx.status;
};
/// Body for [`fuchsia.overnet.protocol/StreamControl.begin_transfer`].
type BeginTransfer = struct {
/// The new owner of this stream endpoint.
new_destination_node NodeId;
/// A key to identify this transfer of ownership.
transfer_key TransferKey;
};
/// A StreamRef identifies a new proxied stream, and details how that stream
/// will come to be on the receiving node.
type StreamRef = strict union {
/// 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.
1: creating StreamId;
/// An existing proxy is being transferred to this node. This node should
/// initiate communication with the peer.
2: transfer_initiator TransferInitiator;
/// An existing proxy is being transferred to this node. This node should
/// await contact from the peer.
3: transfer_waiter TransferWaiter;
};
/// Body for [`fuchsia.overnet.protocol/StreamRef.transfer_initiator`].
type TransferInitiator = struct {
/// 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.
stream_id StreamId;
/// 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.
new_destination_node NodeId;
/// A key to identify this transfer of ownership.
transfer_key TransferKey;
};
/// Body for [`fuchsia.overnet.protocol/StreamRef.transfer_waiter`].
type TransferWaiter = struct {
/// 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.
stream_id StreamId;
/// A key to identify this transfer of ownership.
transfer_key TransferKey;
};