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

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

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

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

/// 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(resource struct {
        port uint32;
        acceptor client_end:HostVsockAcceptor;
    }) -> (struct {
        status zx.status;
    });

    /// Similar to `HostVsockConnector.Connect` except the `src_cid` is
    /// `HOST_CID` and `src_port` is generated automatically.
    Connect(resource struct {
        cid uint32;
        port uint32;
        handle zx.handle:optional;
    }) -> (struct {
        status zx.status;
    });
};