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

using fuchsia.hardware.ethernet;
using fuchsia.hardware.network;
using fuchsia.logger;
using fuchsia.net;
using fuchsia.net.name;
using fuchsia.posix.socket;

/// A list of IP addresses for an interface.
alias interface_address_list = vector<fuchsia.net.Subnet>:MAX;

/// A path to a device node.
alias device_path = string:255;

/// A list of interface descriptors.
alias interface_list = vector<InterfaceInfo>:255;

enum PresenceStatus {
    /// The interface is added.
    ADDED = 1;
    /// The interface is removed.
    REMOVED = 2;
};

enum PhysicalStatus {
    /// The link is not attached to the medium.
    DOWN = 1;
    /// The link is attached to the medium.
    UP = 2;
};

enum AdministrativeStatus {
    /// The interface is administratively disabled.
    DISABLED = 1;
    /// The interface is administratively enabled.
    ENABLED = 2;
};

union InterfaceStatus {
    1: PresenceStatus presence;
    2: PhysicalStatus physical;
    3: AdministrativeStatus administrative;
};

struct InterfaceInfo {
    /// An opaque identifier for the interface, assigned by the stack.
    /// This identifier will never be 0, and will not be reused even if the device is removed and
    /// subsequently re-added. It is not stable across netstack instances.
    fuchsia.net.interface_id id;

    /// All info of an interface except the interface name.
    InterfaceProperties properties;
};

struct InterfaceProperties {
    /// Human-readable name of the interface. eg. eth001, wlanx35.
    fuchsia.posix.socket.interface_name name;

    /// The topological path to the device, representing a stable identifier for the interface
    /// hardware.
    device_path topopath;

    /// An unstable file path corresponding to the interface. Used in watching the creation
    /// and destruction of the interface, or in accessing the interface using netdump.
    device_path filepath;

    /// The MAC address of the interface, if available.
    fuchsia.hardware.ethernet.MacAddress? mac;

    /// The maximum transmission unit for the interface in bytes.
    uint32 mtu;

    /// The features present on the interface.
    fuchsia.hardware.ethernet.Features features;

    /// The administrative status of the interface.
    AdministrativeStatus administrative_status;

    /// The physical link status of the interface.
    PhysicalStatus physical_status;

    /// The list of addresses currently assigned to the interface.
    interface_address_list addresses;
};

/// A ForwardingDestination represents either the device that should transmit a packet or the address
/// of the next hop in the route.
union ForwardingDestination {
    /// The opaque identifier of the device to which packets should be forwarded.
    1: fuchsia.net.interface_id device_id;

    /// The IP address of the next hop, used to look up the next forwarding entry.
    2: fuchsia.net.IpAddress next_hop;
};

/// An entry in the forwarding table for the network stack.
struct ForwardingEntry {
    /// The subnet is the key for the entry in the table.
    fuchsia.net.Subnet subnet;

    /// The destination that will receive the forwarded packet.
    ForwardingDestination destination;
};

struct InterfaceStatusChange {
    /// The opaque identifier of the device that had its status change.
    fuchsia.net.interface_id id;

    /// The new status.
    InterfaceStatus status;
};

enum Error {
    INTERNAL = 1;
    NOT_SUPPORTED = 2;
    INVALID_ARGS = 3;
    BAD_STATE = 4;
    TIME_OUT = 5;
    NOT_FOUND = 6;
    ALREADY_EXISTS = 7;
    IO = 8;
};

/// An Ethernet device.
/// The provided `network_device` is expected to support `Ethernet` frames.
/// Its MAC address and MAC filtering is controlled by the provided `mac` channel.
resource struct EthernetDeviceDefinition {
    /// The connection to the device's data plane.
    fuchsia.hardware.network.Device network_device;
    /// The connection to the device's addressing control plane.
    fuchsia.hardware.network.MacAddressing mac;
};

/// Devices that can be used to back a `Stack` interface.
resource union DeviceDefinition {
    /// A `fuchsia.hardware.network.Device` that exchanges only IP frames. It either doesn't have a
    /// layer 2 or its layer 2 is irrelevant to the `Stack`.
    1: fuchsia.hardware.network.Device ip;
    /// An Ethernet device.
    2: EthernetDeviceDefinition ethernet;
};

/// Base configuration for `Stack` interfaces.
table InterfaceConfig {
    /// Human-readable name of the interface. eg. eth001, wlanx35.
    /// Will be set to a default generic name if not provided.
    1: fuchsia.posix.socket.interface_name name;

    /// The topological path to the device, representing a stable identifier for the interface
    /// hardware.
    2: device_path topopath;

    /// The default metric value used for routes to this interface.
    3: uint32 metric;
};

[Discoverable]
protocol Stack {
    /// Add an Ethernet interface to the network stack. On success, returns the identifier assigned
    /// by the stack for use in subsequent calls.
    AddEthernetInterface(device_path topological_path, fuchsia.hardware.ethernet.Device device) -> (fuchsia.net.interface_id id) error Error;

    /// Add a new interface to the network stack backed by the provided `DeviceDefinition`. On
    /// success, returns the identifier assigned by the stack for use in subsequent calls.
    AddInterface(InterfaceConfig config, DeviceDefinition device) -> (fuchsia.net.interface_id id) error Error;

    /// Remove an Ethernet interface from the network stack.
    DelEthernetInterface(fuchsia.net.interface_id id) -> () error Error;

    /// List all the interfaces available in the network stack.
    ListInterfaces() -> (interface_list ifs);

    /// Retrieve info about a specific interface.
    GetInterfaceInfo(fuchsia.net.interface_id id) -> (InterfaceInfo info) error Error;

    /// Enable the interface. Packets may be processed by the stack after this call is processed.
    EnableInterface(fuchsia.net.interface_id id) -> () error Error;

    /// Disable the interface. The stack will no longer process packets after this call.
    DisableInterface(fuchsia.net.interface_id id) -> () error Error;

    /// Add an address to the interface. If the interface already has an address of a given type that
    /// does not allow duplicates, this method will return an error.
    AddInterfaceAddress(fuchsia.net.interface_id id, fuchsia.net.Subnet addr) -> () error Error;

    /// Remove the address from the interface. If the address is not assigned to the interface, an
    /// error is returned.
    DelInterfaceAddress(fuchsia.net.interface_id id, fuchsia.net.Subnet addr) -> () error Error;

    /// List all the entries in the forwarding table for the network stack.
    // TODO(fxbug.dev/38528): This is unbounded for now, until we change the API to allow for
    // pagination.
    GetForwardingTable() -> (vector<ForwardingEntry>:MAX table);

    /// Add a new entry to the forwarding table. If the table already contains an entry with the same
    /// subnet, an error is returned. The entry may be deleted using DelForwardingEntry first.
    AddForwardingEntry(ForwardingEntry entry) -> () error Error;

    /// Removes the forwarding entry with the given subnet. This will not affect any overlapping
    /// subnets (superset or subset) so the subnet must exactly match an entry in the forwarding
    /// table. If no entry for the subnet exists, an error is returned.
    DelForwardingEntry(fuchsia.net.Subnet subnet) -> () error Error;

    /// Enable the packet filter on a specific interface.
    EnablePacketFilter(fuchsia.net.interface_id id) -> () error Error;

    /// Disable the packet filter on a specific interface.
    DisablePacketFilter(fuchsia.net.interface_id id) -> () error Error;

    /// Enable IP Forwarding.
    EnableIpForwarding() -> ();

    /// Disable IP Forwarding.
    DisableIpForwarding() -> ();

    /// Get a [`fuchsia.net.name/DnsServerWatcher`].
    GetDnsServerWatcher(request<fuchsia.net.name.DnsServerWatcher> watcher);

    // Events

    /// A status change event is triggered whenever an interface's status changes.
    -> OnInterfaceStatusChange(InterfaceStatusChange info);
};

[Discoverable]
protocol Log {
    /// Dynamically set a syslog level.
    // TODO(fxbug.dev/54198): replace by responding to the system wide
    // fuchsia.logger.LogSink.OnInterestChanged event.
    SetLogLevel(fuchsia.logger.LogLevelFilter level) -> () error Error;

    /// Dynamically set packet logging.
    // TODO(fxbug.dev/42432): replace with optional packet captures in Inspect
    // output.
    SetLogPackets(bool enabled) -> ();
};