// 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.virtualization;

using zx;

// |HOST_CID| is the reserved context ID (CID) of the host.
//
// CIDs for guests are assigned by the Manager and can be found in the
// corresponding |InstanceInfo| structure.
const uint32 HOST_CID = 2;

// Exposed by guests capable of listening via vsocks. On a request to establish
// a connection, the |Accept| method will be called. If the port is open and
// accepting connections, the implementation should return |ZX_OK|.
//
// Also see |GuestVsockEndpoint|.
protocol GuestVsockAcceptor {
    Accept(uint32 src_cid, uint32 src_port, uint32 port, handle? handle)
        -> (zx.status status);
};

// Exposed by a host capable of listening via vsocks. A variant of a
// |GuestVsockAcceptor| that is responsible for creating the |handle| with which
// to communicate. The |handle| will be either a socket or a channel, depending
// on the current configuration.
protocol HostVsockAcceptor {
    Accept(uint32 src_cid, uint32 src_port, uint32 port)
        -> (zx.status status, handle? handle);
};

// Exposed by a host capable of connecting via vsocks. This allows a guest to
// identify itself via {src_cid, src_port}, and request to connect to
// {cid, port}. The host should return |ZX_OK|, and create a handle with which
// to communicate. The |handle| will be either a socket or a channel, depending
// on the current configuration.
protocol HostVsockConnector {
    Connect(uint32 src_cid, uint32 src_port, uint32 cid, uint32 port)
        -> (zx.status status, handle? handle);
};

// Exposed by guests capable of handling vsock traffic. During
// initialization the Manager will assign a unique CID to this endpoint and
// provide a |HostVsockConnector| that can be used to establish outbound
// connections. The implementation should provide a |GuestVsockAcceptor|
// implementation that can handle any inbound connection requests.
[Discoverable]
protocol GuestVsockEndpoint {
    SetContextId(uint32 cid, HostVsockConnector connector,
                 request<GuestVsockAcceptor> acceptor);
    -> OnShutdown(uint32 src_cid, uint32 src_port, uint32 dst_cid, uint32 dst_port);
};

// Exposed by a host to provide the ability for listeners to be multiplexed by
// port and to manage dynamic port allocation for outbound connections.
protocol HostVsockEndpoint {
    // Register |acceptor| to be invoked for any connection requests to |port|.
    Listen(uint32 port, HostVsockAcceptor acceptor)
        -> (zx.status status);

    // Similar to |HostVsockConnector.Connect| except the |src_cid| is
    // |HOST_CID| and |src_port| is generated automatically.
    Connect(uint32 cid, uint32 port, handle? handle)
        -> (zx.status status);
};