// Copyright 2020 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.interfaces;

using fuchsia.hardware.network;
using fuchsia.net;
using fuchsia.posix.socket;
using zx;

struct Empty {
};

/// An interface-state change event.
union Event {
    /// Properties of an interface that existed when watching started.
    ///
    /// All fields are set.
    1: Properties existing;
    /// Properties of an interface that was added while watching.
    ///
    /// All fields are set.
    2: Properties added;
    /// ID of an interface that was removed while watching.
    3: fuchsia.net.interface_id removed;
    /// Properties of an interface that changed while watching.
    ///
    /// Only [`Properties.id`] and changed fields are set.
    4: Properties changed;
    /// Sentinel value indicating no more [`existing`] events will be sent.
    5: Empty idle;
};

/// An interface's device class.
union DeviceClass {
    /// The interface is loopback.
    1: Empty loopback;
    /// The interface's network device class.
    2: fuchsia.hardware.network.DeviceClass device;
};

/// An address and its properties.
// This address type is expected to grow to include additional properties such
// as IPv6 address state.
table Address {
    /// The address and prefix length.
    1: fuchsia.net.Subnet addr;
    /// The time after which the address will no longer be valid.
    ///
    /// Its value must be greater than 0. A value of `ZX_TIME_INFINITE`
    /// indicates that the address will always be valid. The value is derived
    /// from the monotonic clock.
    ///
    /// As a `zx.time`, the value has [monotonic clock
    /// semantics](https://fuchsia.dev/fuchsia-src/concepts/time/monotonic),
    /// which implies that it has no meaning outside of the host on which it was
    /// generated and no meaning across host restarts.
    2: zx.time valid_until;
};

/// Properties of a network interface.
table Properties {
    /// An opaque identifier for the interface. Its value will not be reused
    /// even if the device is removed and subsequently re-added. Immutable.
    1: fuchsia.net.interface_id id;
    /// The addresses currently assigned to the interface.
    2: vector<Address>:MAX addresses;
    /// The device is enabled and its physical state is online.
    3: bool online;
    /// The device class of the interface. Immutable.
    4: DeviceClass device_class;
    /// Whether there is a default IPv4 route through this interface.
    5: bool has_default_ipv4_route;
    /// Whether there is a default IPv6 route through this interface.
    6: bool has_default_ipv6_route;
    /// The name of the interface. Immutable.
    7: fuchsia.posix.socket.interface_name name;
};

/// Options for configuring the interface state watcher.
// This type is currently empty, but may grow to allow behavior tuning of the
// watcher, e.g. allow subscribing to a subset of the available events.
table WatcherOptions {
};

/// Network interface state inspection and observation.
[Discoverable]
protocol State {
    /// Initialize a watcher for interface state.
    ///
    /// The server enqueues interface addition, deletion and property changes as
    /// they occur, which can then be retrieved via the pipelined protocol. If
    /// the queue cannot be allocated, the channel will be closed. Also, if the
    /// queue is full and a change event cannot be enqueued, the channel will be
    /// closed.
    ///
    /// + request `watcher` the protocol channel over which changes can be
    ///   observed.
    GetWatcher(WatcherOptions options, request<Watcher> watcher);
};

/// Observer protocol for changes to network interfaces (addition, deletion, and
/// interface property changes).
protocol Watcher {
    /// Hanging get for an interface addition/deletion change.
    ///
    /// Clients should only have one call of this method at a time; a second
    /// call to this method while a call is already pending will cause
    /// the channel to be closed.
    ///
    /// If there are N interfaces present at the time the channel was
    /// initialized, then the first N invocations of this method will return
    /// [`Event.existing`] followed by a single [`Event.idle`] indicating that
    /// all existing interfaces have been sent. Subsequent calls will
    /// immediately return if there is a change to be reported, or block until a
    /// change occurs.
    ///
    /// The server may choose to coalesce property change events, e.g. when
    /// multiple independent property changes occur. As a result, clients cannot
    /// assume that the order in which they observe the interface changes is the
    /// order in which the changes occurred.
    ///
    /// - response `event` the interface change event. Properties of an added or
    ///   existing interface will have all fields present. Property change
    ///   events will always have the interface ID field present (the ID never
    ///   changes); while other fields will only be present with the new value
    ///   if the property has changed.
    Watch() -> (Event event);
};