// Copyright 2019 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.posix.socket;

using fuchsia.io;
using fuchsia.net;
using fuchsia.posix;
using zx;

/// Chosen to be large enough to hold whatever we might want to cram in it. So long as we support
/// socket options, we don't have a good sense of what we might want to send as payload.
// TODO(https://fxbug.dev/44347): replace C structures on the wire with FIDL types.
alias sockopt = bytes:900;

/// The maximum length of an interface name.
// `sizeof((struct ifreq).ifr_name) == 16`; the last byte is reserved for the null terminator.
const uint8 INTERFACE_NAME_LENGTH = 15;

/// An interface name as a sequence of bytes.
alias interface_name = string:INTERFACE_NAME_LENGTH;

/// A network socket.
///
/// Once a socket has been retrieved from a `Provider`, this interface is then used to further
/// configure and use the socket. This interface is essentially POSIX. Its implementation must
/// support Linux-specific arguments to {Get,Set}SockOpt.
///
/// All methods on this type are nonblocking; their exact behaviors match their Linux counterparts.
///
/// *Warning:* This protocol is not yet ready for direct use by clients. Instead, clients should
/// use the BSD sockets API to interact with sockets. We plan to change this protocol substantially
/// and clients that couple directly to this protocol will make those changes more difficult.
protocol BaseSocket {
    compose fuchsia.io.Node;

    /// Sets the local address used for the socket.
    Bind(fuchsia.net.SocketAddress addr) -> () error fuchsia.posix.Errno;
    /// Initiates a connection to a remote address.
    Connect(fuchsia.net.SocketAddress addr) -> () error fuchsia.posix.Errno;
    /// Clears connection information from this socket.
    Disconnect() -> () error fuchsia.posix.Errno;
    /// Retrieves the local socket address.
    GetSockName() -> (fuchsia.net.SocketAddress addr) error fuchsia.posix.Errno;
    /// Retrieves the remote socket address.
    GetPeerName() -> (fuchsia.net.SocketAddress addr) error fuchsia.posix.Errno;

    /// Sets the value of a socket option.
    SetSockOpt(int16 level, int16 optname, sockopt optval) -> () error fuchsia.posix.Errno;
    /// Retrieves the value of a socket option.
    GetSockOpt(int16 level, int16 optname) -> (sockopt optval) error fuchsia.posix.Errno;
};

struct Empty {
};

/// Ancillary data for sending datagram sockets.
table SendControlData {
};

/// Ancillary data for received datagram sockets.
table RecvControlData {
};

/// Flags controlling RecvMsg behavior.
bits RecvMsgFlags : uint16 {
    /// Returns data from the receive queue without removing from it.
    ///
    /// Equivalent to `MSG_PEEK`.
    PEEK = 2;
};

// Flags controlling SendMsg behavior.
bits SendMsgFlags : uint16 {
    // NOTE We don't currently support any flags, but we need at least one definition.
    RESERVED = 0x8000;
};

/// Socket shutdown mode.
bits ShutdownMode : uint16 {
    /// Shutdown socket read endpoint.
    READ = 1;
    /// Shutdown socket write endpoint.
    WRITE = 2;
};

/// A datagram socket.
///
/// This type's [`fuchsia.io.Node/Describe`] method returns an eventpair which is used to signal
/// additional information about the state of the socket such as readiness or shutdown-ness.
///
/// All methods on this type are nonblocking; their exact behaviors match their Linux counterparts.
protocol DatagramSocket {
    compose BaseSocket;

    /// Shuts down part of the socket.
    Shutdown(ShutdownMode mode) -> () error fuchsia.posix.Errno;

    /// Receives a message from the socket.
    RecvMsg(bool want_addr, uint32 data_len, bool want_control, RecvMsgFlags flags) -> (fuchsia.net.SocketAddress? addr, bytes data, RecvControlData control, uint32 truncated) error fuchsia.posix.Errno;
    /// Sends a message on the socket.
    SendMsg(fuchsia.net.SocketAddress? addr, bytes:MAX data, SendControlData control, SendMsgFlags flags) -> (int64 len) error fuchsia.posix.Errno;
};

/// A stream socket.
///
/// This type's [`fuchsia.io.Node/Describe`] method returns a socket which is used to transfer data
/// to and from the caller. Signals are used to communicate additional information about the state
/// of the socket such as connectedness and the presence of incoming connections in the case of a
/// listening socket.
///
/// All methods on this type are nonblocking; their exact behaviors match their Linux counterparts.
protocol StreamSocket {
    compose BaseSocket;

    /// Begins listening for new incoming connections. At most `backlog` connections will be
    /// buffered.
    Listen(int16 backlog) -> () error fuchsia.posix.Errno;
    /// Accepts a buffered incoming connection.
    Accept(bool want_addr) -> (fuchsia.net.SocketAddress? addr, StreamSocket s) error fuchsia.posix.Errno;
};

/// Holds information about an interface and its addresses.
table InterfaceAddresses {
    /// ID of the interface.
    1: uint64 id;
    /// Name of the interface.
    2: interface_name name;
    /// Contains the interface flags, as returned by the SIOCGIFFLAGS ioctl
    /// operation.
    ///
    /// TODO(fxbug.dev/64758): remove this once all clients are transitioned to
    /// use more strongly-typed `interface_flags`.
    3: uint32 flags;
    /// All addresses currently assigned to the interface.
    4: vector<fuchsia.net.Subnet>:MAX addresses;
    /// Contains the interface flags, as returned by the SIOCGIFFLAGS ioctl
    /// operation.
    5: InterfaceFlags interface_flags;
};

/// A socket's domain.
///
/// Determines the addressing domain for a socket.
enum Domain : int16 {
    /// An IPv4 socket. Equivalent to `AF_INET`.
    IPV4 = 0;
    /// An IPv6 socket. Equivalent to `AF_INET6`.
    IPV6 = 1;
};

/// Protocols supported by [`fuchsia.posix.socket/DatagramSocket`].
///
/// `DatagramSocketProtocol` enumerates the protocols supported by the network stack over datagram
/// sockets.
// NOTE: This list can be expanded to accommodate other protocols should the need arise. Most
// notably, there exists the question on whether to support raw IP sockets and what the access model
// for those should be.
enum DatagramSocketProtocol {
    /// UDP (User Datagram Protocol).
    ///
    /// A UDP socket is equivalent to the POSIX API of `SOCK_DGRAM` with a protocol of 0 or
    /// `IPPROTO_UDP`.
    UDP = 1;
    /// ICMP (Internet Control Message Protocol) echo.
    ///
    /// An ICMP echo socket is equivalent to the POSIX API of `SOCK_DGRAM` with a protocol of
    /// `IPPROTO_ICMP` `IPPROTO_ICMPV6` (depending on provided domain).
    ///
    /// Datagrams sent over an ICMP echo socket *must* have a valid ICMP or ICMPv6 echo header.
    ICMP_ECHO = 2;
};

/// Protocols supported by [`fuchsia.posix.socket/StreamSocket`].
///
/// `StreamSocketProtocol` enumerates the protocols supported by the network stack over stream
/// sockets.
enum StreamSocketProtocol {
    /// TCP (Transmission Control Protocol).
    ///
    /// A TCP socket is equivalent to the POSIX API of `SOCK_STREAM` with a protocol of 0 or
    /// `IPPROTO_TCP`.
    TCP = 0;
};

/// Bits representing the interface flags as returned by the SIOCGIFFLAGS ioctl
/// operation. These bitmasks are intended to track the C API definition. For
/// example, `InterfaceFlags.UP` corresponds to `IFF_UP`, etc.
bits InterfaceFlags : uint16 {
    UP = 0x1;
    BROADCAST = 0x2;
    DEBUG = 0x4;
    LOOPBACK = 0x8;
    POINTTOPOINT = 0x10;
    NOTRAILERS = 0x20;
    RUNNING = 0x40;
    NOARP = 0x80;
    PROMISC = 0x100;
    ALLMULTI = 0x200;
    LEADER = 0x400;
    FOLLOWER = 0x800;
    MULTICAST = 0x1000;
    PORTSEL = 0x2000;
    AUTOMEDIA = 0x4000;
    DYNAMIC = 0x8000;
};

/// Provider implements the POSIX sockets API.
[Discoverable]
protocol Provider {
    /// Requests a stream socket with the specified parameters.
    StreamSocket(Domain domain, StreamSocketProtocol proto) -> (StreamSocket s) error fuchsia.posix.Errno;
    /// Requests a datagram socket with the specified parameters.
    DatagramSocket(Domain domain, DatagramSocketProtocol proto) -> (DatagramSocket s) error fuchsia.posix.Errno;

    /// Looks up an interface by its index and returns its name. Returns `ZX_ERR_NOT_FOUND` if the
    /// specified index doesn't exist.
    InterfaceIndexToName(uint64 index) -> (interface_name name) error zx.status;
    /// Looks up an interface by its name and returns its index. Returns `ZX_ERR_NOT_FOUND` if the
    /// specified name doesn't exist.
    InterfaceNameToIndex(interface_name name) -> (uint64 index) error zx.status;
    /// Looks up an interface by its name and returns its flags. Returns `ZX_ERR_NOT_FOUND` if the
    /// specified name doesn't exist.
    InterfaceNameToFlags(interface_name name) -> (InterfaceFlags flags) error zx.status;

    /// Requests a list of [`fuchsia.posix.socket.InterfaceAddresses`]
    /// describing the network interfaces on the system.
    GetInterfaceAddresses() -> (vector<InterfaceAddresses>:MAX interfaces);
};