// 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);
};