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

using zx;
using fuchsia.hardware.vsock;

/// Collection of objects that represent an open connection.
type ConnectionTransport = resource struct {
    /// `data` socket that is ultimately given to the underlying vsock driver and
    /// is where all incoming data can be received from.
    data zx.Handle:SOCKET;
    /// `Connection` interface that is retained by a vsock service that can be
    /// used to manipulate the state of a connection or perform more complex
    /// operations than just sending and receiving on a socket.
    con server_end:Connection;
};

/// Interface for manipulating the state of an active connection.
closed protocol Connection {
    /// Trigger asynchronous shutdown. The underlying channel will be closed
    /// once shutdown is complete. Shutdown has an implicit barrier as any already
    /// queued sends will complete, but any additional sends will generate errors
    strict Shutdown();
    /// Send a VMO. The reply indicates that the VMO send has finished and that
    /// data may be queued on the socket again without causing races.
    strict SendVmo(resource struct {
        vmo zx.Handle:VMO;
        off uint64;
        len uint64;
    }) -> (struct {
        status zx.Status;
    });
};

/// Interface presented by a listener to accept or reject connections
closed protocol Acceptor {
    /// The response is either a `ConnectionTransport` to indicate that the connection
    /// is accepted, or none to indicate that it should be rejected.
    strict Accept(struct {
        addr fuchsia.hardware.vsock.Addr;
    }) -> (resource struct {
        con box<ConnectionTransport>;
    });
};

/// Exposed by a service that can act as a bridge to the underlying vsock driver and
/// provides the ability for listeners to be multiplexed by port and manages dynamic
/// port allocation for outbound connections.
@discoverable
closed protocol Connector {
    /// Attempt to establish a connection to the specified remote cid/port pair.
    /// No local port is specified as an ephemeral one will automatically be allocated.
    strict Connect(resource struct {
        remote_cid uint32;
        remote_port uint32;
        con ConnectionTransport;
    }) -> (struct {
        status zx.Status;
        local_port uint32;
    });
    /// Registers a listener for a local port. There can only be one listener for
    /// a single port at a time.
    strict Listen(resource struct {
        local_port uint32;
        acceptor client_end:Acceptor;
    }) -> (struct {
        status zx.Status;
    });
};