// 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.net;
using fuchsia.net.name;
using fuchsia.posix.socket;

/// A list of IP addresses for an interface.
using interface_address_list = vector<InterfaceAddress>:255;

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

/// A list of interface descriptors.
using 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;
};

// TODO(https://fxbug.dev/54163): use `fuchsia.net.InterfaceAddress` instead.
struct InterfaceAddress {
    /// The IP address of the interface.
    fuchsia.net.IpAddress ip_address;

    /// The length of the network portion of the interface IP address.
    uint8 prefix_len;
};

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.
    uint64 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, as a bitfield. Valid flags are
    /// fuchsia.hardware.ethernet.`INFO_FEATURE_*`.
    uint32 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: uint64 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.
    uint64 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.
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.
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) -> (uint64 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) -> (uint64 id) error Error;

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

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

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

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

    /// Disable the interface. The stack will no longer process packets after this call.
    DisableInterface(uint64 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(uint64 id, InterfaceAddress addr) -> () error Error;

    /// Remove the address from the interface. If the address is not assigned to the interface, an
    /// error is returned.
    DelInterfaceAddress(uint64 id, InterfaceAddress 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(uint64 id) -> () error Error;

    /// Disable the packet filter on a specific interface.
    DisablePacketFilter(uint64 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);
};

// TODO(crbug.com/fuchsia/34987): Deprecate this protocol.
/// Note LogLevelFilter and protocol Log is transient,
/// and is planned to be deprecated by logger.fidl's LogLevelFilter.
/// This definition is to support syslog/logger.go and Netstack2.
enum LogLevelFilter : int8 {
    TRACE = 0x10;
    DEBUG = 0x20;
    INFO = 0x30;
    WARN = 0x40;
    ERROR = 0x50;
    FATAL = 0x60;
};

[Discoverable]
protocol Log {
    /// Dynamically set a syslog level.
    /// See syslog/logger.go for level definition.
    SetLogLevel(LogLevelFilter level) -> () error Error;
};