// 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.net.icmp;

using fuchsia.net;
using zx;

/// Configuration for an ICMP echo socket.
table EchoSocketConfig {
    /// Local IPv4 or IPv6 address used as the source for ICMP echo requests
    /// sent through this EchoSocket.
    ///
    /// This field is currently ignored and has no effect, but may have an
    /// effect in the future for source-based routing. It is highly encouraged
    /// to specify this field, if possible.
    1: fuchsia.net.IpAddress local;

    /// Remote IPv4 or IPv6 address used as the destination for ICMP echo
    /// requests sent through this EchoSocket.
    ///
    /// The version of IP used for `remote` needs to match the version used
    /// by `source`. If this criterion is not met, an `EchoSocket.OnOpen` event
    /// will be sent with status `INVALID_ARGUMENT`.
    ///
    /// In other words, `source` and `remote` can either both be IPv4 or IPv6.
    /// Having `source` as IPv4 and `remote` as IPv6, or vice versa, will result
    /// in error.
    2: fuchsia.net.IpAddress remote;
};

/// Provides clients access to ICMP echo sockets through EchoSockets.
[Discoverable]
protocol Provider {
    /// Open an ICMP socket soley for sending ICMP echo requests and receiving
    /// ICMP echo replies. A protocol request `socket` provides an interface to
    /// the EchoSocket for the new ICMP echo socket.
    OpenEchoSocket(EchoSocketConfig config, request<EchoSocket> socket);
};

/// EchoSocket is a socket that allows sending ICMP echo requests and receiving
/// ICMP echo replies.
///
/// Other ICMP operations, such as sending and receiving error messages, are
/// handled by the network stack itself and not exposed by this API.
///
/// The OnOpen event will trigger with a status code once opened.
protocol EchoSocket {
    /// Send an ICMP echo request.
    ///
    /// The source address on the packet is chosen purely based on the remote
    /// address for the time being. The configured local address from
    /// `EchoSocketConfig` is ignored.
    SendRequest(EchoPacket request);

    /// Watch for an ICMP echo reply or error. If a reply or error hasn't been
    /// received yet, block until one arrives; otherwise, return immediately.
    ///
    /// Any incoming echo replies from the configured remote address will be
    /// received, regardless of their destination address. This is due to the
    /// ignored local address from `EchoSocketConfig`.
    ///
    /// Returns status:
    ///  - `ADDRESS_UNREACHABLE` when the remote host is unreachable
    ///  - `OUT_OF_RANGE` when the packet is larger than the MTU
    Watch() -> (EchoPacket reply) error zx.status;

    /// Triggers when the socket opens. Indicates the success or failure of the
    /// open operation.
    ///
    /// Returns status `INVALID_ARUGMENT` when the `local` and `remote` IP
    /// addresses do not match IP versions.
    -> OnOpen(zx.status s);
};

/// EchoPacket specifies ICMP fields for an echo request or reply. IP fields
/// are set and verified upon `OpenEchoSocket`.
struct EchoPacket {
    /// Sequence numbers are used to match requests and replies.
    uint16 sequence_num;

    /// The payload can be of arbitrary length and content. The size, including IP
    /// and ICMP headers, must be less than the Maximum Transmission Limit (MTU)
    /// of the network to avoid being fragmented.
    bytes payload;
};