// 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 HOST_CID uint32 = 2;
const DEFAULT_GUEST_CID uint32 = 3;

/// 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(resource struct {
        src_cid uint32;
        src_port uint32;
        port uint32;
        socket zx.handle:SOCKET;
    }) -> (struct {}) error zx.status;
};

/// Exposed by a host capable of listening via vsocks. A variant of a
/// `GuestVsockAcceptor` that is responsible for creating the `socket` with which
/// to communicate.
protocol HostVsockAcceptor {
    Accept(struct {
        src_cid uint32;
        src_port uint32;
        port uint32;
    }) -> (resource struct {
        socket zx.handle:SOCKET;
    }) error zx.status;
};

/// 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 socket with which
/// to communicate.
protocol HostVsockConnector {
    Connect(struct {
        src_cid uint32;
        src_port uint32;
        cid uint32;
        port uint32;
    }) -> (resource struct {
        socket zx.handle:SOCKET;
    }) error zx.status;
};

/// 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(resource struct {
        cid uint32;
        connector client_end:HostVsockConnector;
        acceptor server_end:GuestVsockAcceptor;
    });
    -> OnShutdown(struct {
        src_cid uint32;
        src_port uint32;
        dst_cid uint32;
        dst_port uint32;
    });
};

// A host port and acceptor pair. When a guest attempts to initiate a connection on the given port,
// the matching acceptor is used.
type Listener = resource struct {
    port uint32;
    acceptor client_end:HostVsockAcceptor;
};

/// Exposed by a host to provide the ability for listeners to be multiplexed by
/// port and to manage dynamic port allocation for outbound connections.
@discoverable
protocol HostVsockEndpoint {
    /// Instructs the device to listen for guest initiated connections to a given port by
    /// using `acceptor` when the guest creates a connection.
    ///
    /// Possible errors:
    ///     - ZX_ERR_ALREADY_BOUND: A client is already listening on this port.
    Listen(Listener) -> (struct {}) error zx.status;

    /// Attempts to create a vsock connection to a guest on 'guest_port'. Uses a dynamically chosen
    /// ephemeral host port.
    ///
    /// Possible errors:
    ///     - ZX_ERR_NO_RESOURCES: The device couldn't allocate an unused host port.
    ///     - ZX_ERR_CONNECTION_REFUSED: The guest refused this connection.
    ///
    /// Other errors are related to socket creation, see
    /// [zx_socket_create](https://fuchsia.dev/fuchsia-src/reference/syscalls/socket_create.md)
    Connect2(struct {
        guest_port uint32;
    }) -> (resource struct {
        socket zx.handle:SOCKET;
    }) error zx.status;
};