sdk/fidl/fuchsia.posix.socket/socket.fidl

// 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.net.interfaces;
using fuchsia.posix;
using zx;

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

/// Packet timestamp reporting precision options.
type TimestampOption = strict enum {
    /// Do not report timestamp.
    DISABLED = 0;
    /// Report timestamp with nanosecond precision.
    NANOSECOND = 1;
    /// Report timestamp with microsecond precision.
    MICROSECOND = 2;
};

/// A socket.
protocol BaseSocket {
    compose fuchsia.io.Node;

    /// Set `SOL_SOCKET` -> `SO_REUSEADDR`.
    SetReuseAddress(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_REUSEADDR`.
    GetReuseAddress() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    // NOTE: get `SOL_SOCKET` -> `SO_TYPE` is implemented in the client
    // (libfdio).

    /// Get `SOL_SOCKET` -> `SO_ERROR`.
    /// Returns the last error if there is an error set on the socket.
    GetError() -> (struct {}) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_BROADCAST`.
    SetBroadcast(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_BROADCAST`.
    GetBroadcast() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_SNDBUF`.
    SetSendBuffer(struct {
        value_bytes uint64;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_SNDBUF`.
    GetSendBuffer() -> (struct {
        value_bytes uint64;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_RCVBUF`.
    SetReceiveBuffer(struct {
        value_bytes uint64;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_RCVBUF`.
    GetReceiveBuffer() -> (struct {
        value_bytes uint64;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_KEEPALIVE`.
    SetKeepAlive(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_KEEPALIVE`.
    GetKeepAlive() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_OOBINLINE`.
    SetOutOfBandInline(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_OOBINLINE`.
    GetOutOfBandInline() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_NO_CHECK`.
    SetNoCheck(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_NO_CHECK`.
    GetNoCheck() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_LINGER`.
    SetLinger(struct {
        linger bool;
        length_secs uint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_LINGER`.
    GetLinger() -> (struct {
        linger bool;
        length_secs uint32;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_REUSEPORT`.
    SetReusePort(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_REUSEPORT`.
    GetReusePort() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    // NOTE: get `SOL_SOCKET` -> `SO_PEERCRED` not supported in netstack.

    // NOTE: get/set `SOL_SOCKET` -> `SO_SNDTIMEO` is implemented in the client
    // (libfdio).
    // NOTE: get/set `SOL_SOCKET` -> `SO_RCVTIMEO` is implemented in the client
    // (libfdio).

    /// Get `SOL_SOCKET` -> `SO_ACCEPTCONN`.
    GetAcceptConn() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_BINDTODEVICE`.
    SetBindToDevice(struct {
        value fuchsia.net.interfaces.name;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_BINDTODEVICE`.
    GetBindToDevice() -> (struct {
        value fuchsia.net.interfaces.name;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_TIMESTAMP`.
    // TODO(https://fxbug.dev/87656): Remove after ABI transition.
    @deprecated("Use SetTimestamp instead")
    @selector("fuchsia.posix.socket/BaseSocket.SetTimestamp2")
    SetTimestampDeprecated(struct {
        value TimestampOption;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_TIMESTAMP`.
    // TODO(https://fxbug.dev/87656): Remove after ABI transition.
    @deprecated("Use GetTimestamp instead")
    @selector("fuchsia.posix.socket/BaseSocket.GetTimestamp2")
    GetTimestampDeprecated() -> (struct {
        value TimestampOption;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_SOCKET` -> `SO_TIMESTAMP` or `SO_TIMESTAMPNS`.
    // These two options are mutually exclusive. Enabling one disables the
    // other. Disabling either disables both.
    // https://github.com/torvalds/linux/blob/dcd68326d29/net/core/sock.c#L790-L801
    SetTimestamp(struct {
        value TimestampOption;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_SOCKET` -> `SO_TIMESTAMP` or `SO_TIMESTAMPNS`.
    GetTimestamp() -> (struct {
        value TimestampOption;
    }) error fuchsia.posix.Errno;
};

/// A network socket.
protocol BaseNetworkSocket {
    compose BaseSocket;

    /// Sets the local address used for the socket.
    Bind(struct {
        addr fuchsia.net.SocketAddress;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Initiates a connection to a remote address.
    Connect(struct {
        addr fuchsia.net.SocketAddress;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Clears connection information from this socket.
    Disconnect() -> (struct {}) error fuchsia.posix.Errno;
    /// Retrieves the local socket address.
    GetSockName() -> (struct {
        addr fuchsia.net.SocketAddress;
    }) error fuchsia.posix.Errno;
    /// Retrieves the remote socket address.
    GetPeerName() -> (struct {
        addr fuchsia.net.SocketAddress;
    }) error fuchsia.posix.Errno;
    /// Shuts down part of the socket.
    Shutdown(struct {
        mode ShutdownMode;
    }) -> (struct {}) error fuchsia.posix.Errno;

    /// Set `SOL_IP` -> `IP_TOS`.
    SetIpTypeOfService(struct {
        value uint8;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IP` -> `IP_TOS`.
    GetIpTypeOfService() -> (struct {
        value uint8;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IP` -> `IP_TTL`.
    // [1, 255] but unset means default, which is `sysctl net.ipv4.ip_default_ttl`.
    // https://github.com/torvalds/linux/blob/6f38be8f2cc/net/ipv4/ip_sockglue.c#L1605-L1612
    SetIpTtl(struct {
        value OptionalUint8;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IP` -> `IP_TTL`.
    GetIpTtl() -> (struct {
        value uint8;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IP` -> `IP_PKTINFO`.
    SetIpPacketInfo(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IP` -> `IP_PKTINFO`.
    GetIpPacketInfo() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IP` -> `IP_RECVTOS`.
    SetIpReceiveTypeOfService(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IP` -> `IP_RECVTOS`.
    GetIpReceiveTypeOfService() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IP` -> `IP_RECVTTL`.
    SetIpReceiveTtl(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IP` -> `IP_RECVTTL`.
    GetIpReceiveTtl() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IP` -> `IP_MULTICAST_IF`.
    SetIpMulticastInterface(struct {
        iface fuchsia.net.interface_id;
        address fuchsia.net.Ipv4Address;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IP` -> `IP_MULTICAST_IF`.
    GetIpMulticastInterface() -> (struct {
        value fuchsia.net.Ipv4Address;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IP` -> `IP_MULTICAST_TTL`.
    // [1, 255] but unset means kernel default, which is 1.
    // https://github.com/torvalds/linux/blob/6f38be8f2cc/net/ipv4/ip_sockglue.c#L1088-L1098
    SetIpMulticastTtl(struct {
        value OptionalUint8;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IP` -> `IP_MULTICAST_TTL`.
    GetIpMulticastTtl() -> (struct {
        value uint8;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IP` -> `IP_MULTICAST_LOOP`.
    SetIpMulticastLoopback(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IP` -> `IP_MULTICAST_LOOP`.
    GetIpMulticastLoopback() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IP` -> `IP_ADD_MEMBERSHIP`
    AddIpMembership(struct {
        membership IpMulticastMembership;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Set `SOL_IP` -> `IP_DROP_MEMBERSHIP`
    DropIpMembership(struct {
        membership IpMulticastMembership;
    }) -> (struct {}) error fuchsia.posix.Errno;

    /// Set `SOL_IPV6` -> `IPV6_ADD_MEMBERSHIP`.
    AddIpv6Membership(struct {
        membership Ipv6MulticastMembership;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Set `SOL_IPV6` -> `IPV6_DROP_MEMBERSHIP`.
    DropIpv6Membership(struct {
        membership Ipv6MulticastMembership;
    }) -> (struct {}) error fuchsia.posix.Errno;

    /// Set `SOL_IPV6` -> `IPV6_MULTICAST_IF`.
    SetIpv6MulticastInterface(struct {
        value fuchsia.net.interface_id;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IPV6` -> `IPV6_MULTICAST_IF`.
    GetIpv6MulticastInterface() -> (struct {
        value fuchsia.net.interface_id;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IPV6` -> `IPV6_UNICAST_HOPS`.
    // [0, 255] but unset means use default, which is `sysctl net.ipv6.conf.<device>.hop_limit`.
    // https://github.com/torvalds/linux/blob/6f38be8f2cc/net/ipv6/ipv6_sockglue.c#L742-L749
    // https://github.com/torvalds/linux/blob/6f38be8f2cc/net/ipv6/ip6_output.c#L291-L294
    SetIpv6UnicastHops(struct {
        value OptionalUint8;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IPV6` -> `IPV6_UNICAST_HOPS`.
    GetIpv6UnicastHops() -> (struct {
        value uint8;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IPV6` -> `IPV6_RECVHOPLIMIT`.
    SetIpv6ReceiveHopLimit(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IPV6` -> `IPV6_RECVHOPLIMIT`.
    GetIpv6ReceiveHopLimit() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IPV6` -> `IPV6_MULTICAST_HOPS`.
    // [0, 255] but unset means kernel default, which is 1.
    // https://github.com/torvalds/linux/blob/6f38be8f2cc/net/ipv6/ipv6_sockglue.c#L751-L760
    SetIpv6MulticastHops(struct {
        value OptionalUint8;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IPV6` -> `IPV6_MULTICAST_HOPS`.
    GetIpv6MulticastHops() -> (struct {
        value uint8;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IPV6` -> `IPV6_MULTICAST_LOOP`.
    SetIpv6MulticastLoopback(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IPV6` -> `IPV6_MULTICAST_LOOP`.
    GetIpv6MulticastLoopback() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IPV6` -> `IPV6_V6ONLY`.
    SetIpv6Only(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IPV6` -> `IPV6_V6ONLY`.
    GetIpv6Only() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    // NOTE: get `SOL_IPV6` -> `IPV6_PATHMTU` not supported in netstack.

    /// Set `SOL_IPV6` -> `IPV6_RECVTCLASS`.
    SetIpv6ReceiveTrafficClass(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IPV6` -> `IPV6_RECVTCLASS`.
    GetIpv6ReceiveTrafficClass() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IPV6` -> `IPV6_TCLASS`
    // NOTE: see https://tools.ietf.org/html/rfc3542.html for definitions.
    //
    // [0, 255] but unset means kernel default, which is 0.
    // https://github.com/torvalds/linux/blob/6f38be8f2cc/net/ipv6/ipv6_sockglue.c#L594-L611
    SetIpv6TrafficClass(struct {
        value OptionalUint8;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IPV6` -> `IPV6_TCLASS`.
    GetIpv6TrafficClass() -> (struct {
        value uint8;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_IPV6` -> `IPV6_RECVPKTINFO`.
    SetIpv6ReceivePacketInfo(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_IPV6` -> `IPV6_RECVPKTINFO`.
    GetIpv6ReceivePacketInfo() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;
};

/// IPv4 multicast membership options.
type IpMulticastMembership = struct {
    /// Interface index for membership.
    iface fuchsia.net.interface_id;
    /// Local interface address requesting or relinquishing ownership.
    local_addr fuchsia.net.Ipv4Address;
    /// Address of the multicast group the membership refers to.
    mcast_addr fuchsia.net.Ipv4Address;
};

/// IPv6 multicast membership options.
type Ipv6MulticastMembership = struct {
    /// Interface index for membership.
    iface fuchsia.net.interface_id;
    /// Address of the multicast group the membership refers to.
    mcast_addr fuchsia.net.Ipv6Address;
};

/// An optional byte value.
// This exists because FIDL does not allow optional integers.
type OptionalUint8 = strict union {
    1: value uint8;
    2: unset Empty;
};

/// An optional uint32 value.
// This exists because FIDL does not allow optional integers.
type OptionalUint32 = strict union {
    1: value uint32;
    2: unset Empty;
};

// TODO(https://fxbug.dev/7913): Use built-in empty struct when available.
type Empty = struct {};

// TODO(https://fxbug.dev/87656): Inline in SocketRecvControlData after
// SocketRecvControlData.timestamp_deprecated is deleted.
type Timestamp = strict union {
    /// Time in nanoseconds since epoch (January 1 1970 GMT).
    1: nanoseconds int64;
    /// Time in microseconds since epoch (January 1 1970 GMT).
    2: microseconds int64;
};

/// Socket level ancillary data that can be received.
///
/// These match control messages with a `SOL_SOCKET` level.
type SocketRecvControlData = table {
    /// The time at which a packet was received.
    ///
    /// Present if a timestamp option is enabled. Refer to
    /// [`fuchsia.posix.socket.BaseSocket/GetTimestamp`] and
    /// [`fuchsia.posix.socket.BaseSocket/SetTimestamp`].
    1: timestamp Timestamp;

    /// The time at which a packet was received.
    ///
    /// Present if a timestamp option is enabled. Refer to
    /// [`fuchsia.posix.socket.BaseSocket/GetTimestamp`] and
    /// [`fuchsia.posix.socket.BaseSocket/SetTimestamp`].
    // TODO(https://fxbug.dev/87656): Remove after ABI transition.
    2: timestamp_deprecated Timestamp;
};

/// Network socket (L3) ancillary data that can be received.
type NetworkSocketRecvControlData = table {
    /// Socket level ancillary data.
    1: socket SocketRecvControlData;

    /// IPv4 level ancillary data.
    ///
    /// These match POSIX `SOL_IP` control messages.
    2: ip @generated_name("IpRecvControlData") table {
        /// The Type of Service value found in a received packet's IPv4 header.
        ///
        /// Present if the `SOL_IP` -> `IP_RECVTOS` option is enabled.
        1: tos uint8;

        /// The Time to Live value found in a received packet's IPv4 header.
        ///
        /// Present if the `SOL_IP` -> `IP_RECVTTL` option is enabled.
        2: ttl uint8;
    };

    /// IPv6 level ancillary data.
    ///
    /// These match POSIX `SOL_IPV6` control messages.
    3: ipv6 @generated_name("Ipv6RecvControlData") table {
        /// The Traffic Class of a packet that was received.
        ///
        /// Present if the `SOL_IPV6` -> `IPV6_RECVTCLASS` option is enabled.
        1: tclass uint8;

        /// The Hop Limit of a packet that was received.
        ///
        /// Present if the `SOL_IPV6` -> `IPV6_RECVHOPLIMIT` option is enabled.
        2: hoplimit uint8;

        /// The packet information of a packet that was received.
        ///
        /// Present if the `SOL_IPV6` -> `IPV6_RECVPKTINFO` option is enabled.
        3: pktinfo @generated_name("Ipv6PktInfoRecvControlData") struct {
            /// The index of the interface on which the IP packet was received.
            iface fuchsia.net.interface_id;
            /// The destination address specified in the received packet's IP
            /// header.
            header_destination_addr fuchsia.net.Ipv6Address;
        };
    };
};

/// Socket level ancillary data that can be sent.
///
/// These match the POSIX `SOL_SOCKET` control messages.
type SocketSendControlData = table {};

/// Network socket (L3) ancillary data that can be sent.
type NetworkSocketSendControlData = table {
    /// Socket level ancillary data.
    1: socket SocketSendControlData;

    /// IPv4 level ancillary data.
    ///
    /// These match POSIX `SOL_IP` control messages.
    2: ip @generated_name("IpSendControlData") table {
        // Reserved for `SOL_IP` -> `IP_TOS` control message, to maintain
        // a consistent order with the similar IpRecvControlData table.
        // TODO(https://fxbug.dev/96028): Replace with `IP_TOS` cmsg.
        1: reserved;

        /// The Time to Live value to set in the IPv4 header of an outgoing
        /// packet.
        // Values from range [1, 255] are valid.
        2: ttl uint8;
    };

    /// IPv6 level ancillary data.
    ///
    /// These match POSIX `SOL_IPV6` control messages.
    3: ipv6 @generated_name("Ipv6SendControlData") table {
        // Reserved for `SOL_IPV6` -> `IPV6_TCLASS` control message, to maintain
        // a consistent order with the similar IpSendControlData table.
        // TODO(https://fxbug.dev/96028): Replace with `IPV6_TCLASS` cmsg.
        1: reserved;

        /// The Hop Limit value to set in the IPv6 header of an outgoing
        /// packet.
        2: hoplimit uint8;
    };
};

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

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

/// Base protocol shared by all datagram sockets.
///
/// Complete implementations of a datagram socket should compose this protocol.
protocol BaseDatagramSocket {
    compose BaseNetworkSocket;

    /// Retrieves creation information from the socket.
    ///
    /// - response `domain` the socket's associated domain.
    /// - response `proto` the socket's associated protocol.
    GetInfo() -> (struct {
        domain Domain;
        proto DatagramSocketProtocol;
    }) error fuchsia.posix.Errno;

    /// Retrieves creation information from the socket.
    ///
    /// - response `domain` the socket's associated domain.
    /// - response `proto` the socket's associated protocol.
    // TODO(https://fxbug.dev/96469): Remove this method once no more rely on it.
    @deprecated("Use GetInfo instead")
    @selector("fuchsia.posix.socket/DatagramSocket.GetInfo")
    GetInfoDeprecated() -> (struct {
        domain Domain;
        proto DatagramSocketProtocol;
    }) error fuchsia.posix.Errno;
};

type DatagramSocketSendControlData = table {
    /// Network socket ancillary data.
    1: network NetworkSocketSendControlData;
};

type DatagramSocketRecvControlData = table {
    /// Network socket ancillary data.
    1: network NetworkSocketRecvControlData;
};

/// Metadata of a received datagram.
type RecvMsgMeta = table {
    /// The from address of the datagram.
    1: from fuchsia.net.SocketAddress;
    /// Ancillary control message data describing the datagram.
    2: control DatagramSocketRecvControlData;
    /// The length of the payload, in bytes.
    3: payload_len uint16;
};

/// Metadata of a sent datagram.
type SendMsgMeta = table {
    /// The destination address, if specified.
    1: to fuchsia.net.SocketAddress;
    /// Ancillary control message data used for sending the payload.
    2: control DatagramSocketSendControlData;
};

/// Matches the definition in //zircon/system/public/zircon/types.h.
const ZX_WAIT_MANY_MAXIMUM_ITEMS uint32 = 64;

/// A datagram socket.
///
/// This type's [`fuchsia.io.Node/Describe`] method returns a zircon socket which can be
/// used to perform unacknowledged IO.
protocol DatagramSocket {
    compose BaseDatagramSocket;

    /// Validates that data can be sent.
    ///
    /// + request `args` the requested disposition of data to be sent.
    /// - response the constraints sent data must satisfy.
    /// * error the error code indicating the reason for validation failure.
    SendMsgPreflight(table {
        /// The destination address.
        ///
        /// If absent, interpreted as the method receiver's connected address and
        /// causes the connected address to be returned.
        ///
        /// Required if the method receiver is not connected.
        1: to fuchsia.net.SocketAddress;
    }) -> (resource table {
        /// The validated destination address.
        ///
        /// Present only in response to an unset `to` addreess.
        1: to fuchsia.net.SocketAddress;
        /// Represents the validity of this structure.
        ///
        /// The structure is invalid if any of the elements' peer is closed.
        /// Datagrams sent with the associated metadata after invalidation will be
        /// silently dropped.
        2: validity vector<zx.handle:<EVENTPAIR, zx.RIGHTS_BASIC>>:ZX_WAIT_MANY_MAXIMUM_ITEMS;
        /// The maximum datagram size that can be sent.
        ///
        /// Datagrams exceeding this will be silently dropped.
        3: maximum_size uint32;
    }) error fuchsia.posix.Errno;

    /// Returns the set of requested control messages.
    ///
    /// - response the set of currently requested control messages.
    RecvMsgPostflight() -> (resource table {
        /// Represents the validity of this structure.
        ///
        /// The structure is invalid if the peer is closed.
        1: validity zx.handle:<EVENTPAIR, zx.RIGHTS_BASIC>;
        /// Identifies whether the `SO_TIMESTAMP` or `SO_TIMESTAMPNS` control messages are
        /// requested.
        2: timestamp TimestampOption;
        /// Identifies the status (requested or not) of up to 32 control messages.
        /// This set size should be large enough to signal the status of all cmsgs supported
        /// by POSIX systems as of 2022. If that changes, the set can be extended by adding
        /// additional bits fields.
        3: requests @generated_name("CmsgRequests") flexible bits : uint32 {
            /// Identifies whether the `IP_RECVTOS` control message is requested.
            IP_TOS = 0x1;
            /// Identifies whether the `IP_RECVTTL` control message is requested.
            IP_TTL = 0x2;
            /// Identifies whether the `IPV6_RECVTCLASS` control message is requested.
            IPV6_TCLASS = 0x4;
            /// Identifies whether the `IPV6_RECVHOPLIMIT` control message is requested.
            IPV6_HOPLIMIT = 0x8;
        };
    }) error fuchsia.posix.Errno;
};

/// A synchronous datagram socket.
///
/// This protocol defines synchronous methods for sending and receiving datagram
/// payloads over a channel. All methods are nonblocking; their behavior roughly
/// matches their Linux counterparts.
///
/// This protocol'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.
///
/// *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 SynchronousDatagramSocket {
    compose BaseDatagramSocket;

    /// Receives a message from the socket.
    ///
    /// + request `want_addr` request message's source address information to be
    ///   returned.
    /// + request `data_len` the maximum allowed length of the response data
    ///   buffer.
    /// + request `want_control` request ancillary data to be returned.
    /// + request `flags` flags for the receive request.
    /// - response `addr` the message's source address information, if requested.
    /// - response `data` the message.
    /// - response `control` control messages, if requested.
    /// - response `truncated` indicates whether or not the returned message was
    ///   truncated.
    // TODO(https://fxbug.dev/96469): Remove this method once no more callers rely on it.
    @deprecated("Use RecvMsg instead")
    @selector("fuchsia.posix.socket/DatagramSocket.RecvMsg")
    RecvMsgDeprecated(struct {
        want_addr bool;
        data_len uint32;
        want_control bool;
        flags RecvMsgFlags;
    }) -> (struct {
        addr fuchsia.net.SocketAddress:optional;
        data bytes;
        control DatagramSocketRecvControlData;
        truncated uint32;
    }) error fuchsia.posix.Errno;


    /// Receives a message from the socket.
    ///
    /// + request `want_addr` request message's source address information to
    ///   be returned.
    /// + request `data_len` the maximum allowed length of the response data
    ///   buffer.
    /// + request `want_control` request ancillary data to be returned.
    /// + request `flags` flags for the receive request.
    /// - response `addr` the message's source address information, if
    ///   requested.
    /// - response `data` the message.
    /// - response `control` control messages, if requested.
    /// - response `truncated` indicates whether or not the returned message
    ///   was truncated.
    RecvMsg(struct {
        want_addr bool;
        data_len uint32;
        want_control bool;
        flags RecvMsgFlags;
    }) -> (struct {
        addr fuchsia.net.SocketAddress:optional;
        data bytes;
        control DatagramSocketRecvControlData;
        truncated uint32;
    }) error fuchsia.posix.Errno;

    /// Sends a message on the socket.
    ///
    /// + request `addr` the address to send the message to. If unset, will
    ///   send to the connected peer.
    /// + request `data` the message.
    /// + request `control` ancillary data.
    /// + request `flags` flags for the send request.
    /// - response `len` the number of bytes sent.
    // TODO(https://fxbug.dev/96469): Remove this method once no more callers rely on it.
    @deprecated("Use SendMsg instead")
    @selector("fuchsia.posix.socket/DatagramSocket.SendMsg")
    SendMsgDeprecated(struct {
        addr fuchsia.net.SocketAddress:optional;
        data bytes:MAX;
        control DatagramSocketSendControlData;
        flags SendMsgFlags;
    }) -> (struct {
        len int64;
    }) error fuchsia.posix.Errno;

    /// Sends a message on the socket.
    ///
    /// + request `addr` the address to send the message to. If unset, will send
    ///   to the connected peer.
    /// + request `data` the message.
    /// + request `control` ancillary data.
    /// + request `flags` flags for the send request.
    /// - response `len` the number of bytes sent.
    SendMsg(struct {
        addr fuchsia.net.SocketAddress:optional;
        data bytes:MAX;
        control DatagramSocketSendControlData;
        flags SendMsgFlags;
    }) -> (struct {
        len int64;
    }) 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.
///
/// *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 StreamSocket {
    compose BaseNetworkSocket;

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

    /// Retrieves creation information from the socket.
    GetInfo() -> (struct {
        domain Domain;
        proto StreamSocketProtocol;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_NODELAY`.
    SetTcpNoDelay(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_NODELAY`.
    GetTcpNoDelay() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_MAXSEG`.
    SetTcpMaxSegment(struct {
        value_bytes uint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_MAXSEG`.
    GetTcpMaxSegment() -> (struct {
        value_bytes uint32;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_CORK`.
    SetTcpCork(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_CORK`.
    GetTcpCork() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_KEEPIDLE`.
    SetTcpKeepAliveIdle(struct {
        value_secs uint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_KEEPIDLE`.
    GetTcpKeepAliveIdle() -> (struct {
        value_secs uint32;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_KEEPINTVL`.
    SetTcpKeepAliveInterval(struct {
        value_secs uint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_KEEPINTVL`.
    GetTcpKeepAliveInterval() -> (struct {
        value_secs uint32;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_KEEPCNT`.
    SetTcpKeepAliveCount(struct {
        value uint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_KEEPCNT`.
    GetTcpKeepAliveCount() -> (struct {
        value uint32;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_SYNCNT`.
    SetTcpSynCount(struct {
        value uint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_SYNCNT`.
    GetTcpSynCount() -> (struct {
        value uint32;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_LINGER2`.
    SetTcpLinger(struct {
        value_secs OptionalUint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_LINGER2`.
    GetTcpLinger() -> (struct {
        value_secs OptionalUint32;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_DEFER_ACCEPT`.
    SetTcpDeferAccept(struct {
        value_secs uint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_DEFER_ACCEPT`.
    GetTcpDeferAccept() -> (struct {
        value_secs uint32;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_WINDOW_CLAMP`.
    SetTcpWindowClamp(struct {
        value uint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_WINDOW_CLAMP`.
    GetTcpWindowClamp() -> (struct {
        value uint32;
    }) error fuchsia.posix.Errno;

    /// Get `SOL_TCP` -> `TCP_INFO`.
    GetTcpInfo() -> (struct {
        info TcpInfo;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_QUICKACK`.
    SetTcpQuickAck(struct {
        value bool;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_QUICKACK`.
    GetTcpQuickAck() -> (struct {
        value bool;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_CONGESTION`.
    SetTcpCongestion(struct {
        value TcpCongestionControl;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_CONGESTION`.
    GetTcpCongestion() -> (struct {
        value TcpCongestionControl;
    }) error fuchsia.posix.Errno;

    /// Set `SOL_TCP` -> `TCP_USER_TIMEOUT`.
    SetTcpUserTimeout(struct {
        value_millis uint32;
    }) -> (struct {}) error fuchsia.posix.Errno;
    /// Get `SOL_TCP` -> `TCP_USER_TIMEOUT`.
    GetTcpUserTimeout() -> (struct {
        value_millis uint32;
    }) error fuchsia.posix.Errno;

    // NOTE: set `SOL_TCP` -> `TCP_REPAIR_OPTIONS` not supported in netstack.
    // NOTE: get `SOL_CTP` -> `TCP_NOTSENT_LOWAT` not supported in netstack.
    // NOTE: get `SOL_TCP` -> `TCP_CC_INFO` not supported in netstack.
};

/// TCP congestion control modes.
type TcpCongestionControl = strict enum {
    RENO = 1;
    CUBIC = 2;
};

/// TCP state machine state.
type TcpState = strict enum {
    ESTABLISHED = 1;
    SYN_SENT = 2;
    SYN_RECV = 3;
    FIN_WAIT1 = 4;
    FIN_WAIT2 = 5;
    TIME_WAIT = 6;
    CLOSE = 7;
    CLOSE_WAIT = 8;
    LAST_ACK = 9;
    LISTEN = 10;
    CLOSING = 11;
};

/// TCP congestion control state machine state.
type TcpCongestionControlState = strict enum {
    OPEN = 0;
    DISORDER = 1;
    CONGESTION_WINDOW_REDUCED = 2;
    RECOVERY = 3;
    LOSS = 4;
};

/// TCP protocol state.
type TcpInfo = table {
    1: state TcpState;
    2: ca_state TcpCongestionControlState;
    3: reserved; // uint8_t tcpi_retransmits;
    4: reserved; // uint8_t tcpi_probes;
    5: reserved; // uint8_t tcpi_backoff;
    6: reserved; // uint8_t tcpi_options;
    7: reserved; // uint8_t tcpi_snd_wscale : 4, tcpi_rcv_wscale : 4;
    8: reserved;
    9: reserved; // uint8_t tcpi_delivery_rate_app_limited : 1, tcpi_fastopen_client_fail : 2;
   10: reserved;
   11: rto_usec uint32;
   12: reserved; // uint32_t tcpi_ato;
   13: reserved; // uint32_t tcpi_snd_mss;
   14: reserved; // uint32_t tcpi_rcv_mss;
   15: reserved; // uint32_t tcpi_unacked;
   16: reserved; // uint32_t tcpi_sacked;
   17: reserved; // uint32_t tcpi_lost;
   18: reserved; // uint32_t tcpi_retrans;
   19: reserved; // uint32_t tcpi_fackets;
   20: reserved; // uint32_t tcpi_last_data_sent;
   21: reserved; // uint32_t tcpi_last_ack_sent;
   22: reserved; // uint32_t tcpi_last_data_recv;
   23: reserved; // uint32_t tcpi_last_ack_recv;
   24: reserved; // uint32_t tcpi_pmtu;
   25: reserved; // uint32_t tcpi_rcv_ssthresh;
   26: rtt_usec uint32;
   27: rtt_var_usec uint32;
   28: snd_ssthresh uint32;
   29: snd_cwnd uint32;
   30: reserved; // uint32_t tcpi_advmss;
   31: reserved; // uint32_t tcpi_reordering;
   32: reserved; // uint32_t tcpi_rcv_rtt;
   33: reserved; // uint32_t tcpi_rcv_space;
   34: reserved; // uint32_t tcpi_total_retrans;
   35: reserved; // uint64_t tcpi_pacing_rate;
   36: reserved; // uint64_t tcpi_max_pacing_rate;
   37: reserved; // uint64_t tcpi_bytes_acked;
   38: reserved; // uint64_t tcpi_bytes_received;
   39: reserved; // uint32_t tcpi_segs_out;
   40: reserved; // uint32_t tcpi_segs_in;
   41: reserved; // uint32_t tcpi_notsent_bytes;
   42: reserved; // uint32_t tcpi_min_rtt;
   43: reserved; // uint32_t tcpi_data_segs_in;
   44: reserved; // uint32_t tcpi_data_segs_out;
   45: reserved; // uint64_t tcpi_delivery_rate;
   46: reserved; // uint64_t tcpi_busy_time;
   47: reserved; // uint64_t tcpi_rwnd_limited;
   48: reserved; // uint64_t tcpi_sndbuf_limited;
   49: reserved; // uint32_t tcpi_delivered;
   50: reserved; // uint32_t tcpi_delivered_ce;
   51: reserved; // uint64_t tcpi_bytes_sent;
   52: reserved; // uint64_t tcpi_bytes_retrans;
   53: reserved; // uint32_t tcpi_dsack_dups;
   54: reorder_seen bool;
   55: reserved; // uint32_t tcpi_rcv_ooopack;
   56: reserved; // uint32_t tcpi_snd_wnd;
};

/// Holds information about an interface and its addresses.
type InterfaceAddresses = table {
    /// ID of the interface.
    1: id uint64;
    /// Name of the interface.
    2: name fuchsia.net.interfaces.name;
    3: reserved;
    /// All addresses currently assigned to the interface.
    4: addresses vector<fuchsia.net.Subnet>:MAX;
    /// Contains the interface flags, as returned by the SIOCGIFFLAGS ioctl
    /// operation.
    5: interface_flags InterfaceFlags;
};

/// A socket's domain.
///
/// Determines the addressing domain for a socket.
type Domain = strict enum : 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.
type DatagramSocketProtocol = strict enum {
    /// 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.
type StreamSocketProtocol = strict enum {
    /// 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.
type InterfaceFlags = strict bits : 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.
///
/// *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.
@discoverable
protocol Provider {
    /// Requests a stream socket with the specified parameters.
    StreamSocket(struct {
        domain Domain;
        proto StreamSocketProtocol;
    }) -> (resource struct {
        s client_end:StreamSocket;
    }) error fuchsia.posix.Errno;
    /// Requests a datagram socket with the specified parameters.
    DatagramSocket(struct {
        domain Domain;
        proto DatagramSocketProtocol;
    }) -> (resource struct {
        s client_end:SynchronousDatagramSocket;
    }) 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(struct {
        index uint64;
    }) -> (struct {
        name fuchsia.net.interfaces.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(struct {
        name fuchsia.net.interfaces.name;
    }) -> (struct {
        index uint64;
    }) 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(struct {
        name fuchsia.net.interfaces.name;
    }) -> (struct {
        flags InterfaceFlags;
    }) error zx.status;

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