// 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.neighbor;

using fuchsia.net;
using zx;

/// Information on a neighboring device in the local network.
///
/// There are two types of entries available in the neighbor table.
///   1. Dynamic entries are discovered automatically by neighbor discovery
///      protocols (e.g. ARP, NDP). These protocols will attempt to reconfirm
///      reachability with the device once its `state` becomes
///      [`EntryState.STALE`].
///   2. Static entries are explicitly added by a user with
///      [`Controller.AddEntry`] and have no expiration. Their `state` is
///      always [`EntryState.STATIC`].
type Entry = table {
    /// Identifier for the interface used for communicating with the neighbor.
    ///
    /// Required.
    1: interface fuchsia.net.InterfaceId;

    /// IP address of the neighbor.
    ///
    /// Required.
    2: neighbor fuchsia.net.IpAddress;

    /// State of the entry within the Neighbor Unreachability Detection (NUD)
    /// state machine.
    ///
    /// Modeled after RFC 4861 section 7.3.2. Descriptions are kept
    /// implementation-independent by using a set of generic terminology.
    ///
    /// ,------------------------------------------------------------------.
    /// | Generic Term              | ARP Term    | NDP Term               |
    /// |---------------------------+-------------+------------------------|
    /// | Reachability Probe        | ARP Request | Neighbor Solicitation  |
    /// | Reachability Confirmation | ARP Reply   | Neighbor Advertisement |
    /// `---------------------------+-------------+------------------------'
    ///
    /// Required.
    3: state @generated_name("EntryState") strict enum {
        /// Reachability is in the process of being confirmed for a newly
        /// created, non-static entry.
        INCOMPLETE = 1;

        /// Positive reachability has been confirmed; the path to the neighbor
        /// is functioning properly.
        REACHABLE = 2;

        /// Reachability is considered unknown.
        ///
        /// Occurs in one of two ways:
        ///   1. Too much time has elapsed since the last positive reachability
        ///      confirmation was received.
        ///   2. Received a reachability confirmation from a neighbor with a
        ///      different MAC address than the one cached.
        STALE = 3;

        /// A packet was recently sent while reachability was considered
        /// unknown.
        ///
        /// This state is an optimization that gives non-Neighbor-Discovery
        /// related protocols time to confirm reachability after the last
        /// confirmation of reachability has expired due to lack of recent
        /// traffic.
        DELAY = 4;

        /// A reachability confirmation is actively sought by periodically
        /// retransmitting reachability probes until a reachability confirmation
        /// is received, or until the maximum number of probes has been sent.
        PROBE = 5;

        /// Static entries are explicitly added with [`Controller.AddEntry`].
        /// They do not expire and are not deleted until explicitly removed with
        /// [`Controller.RemoveEntry`].
        STATIC = 6;

        /// Negative reachability has been confirmed; the path to the neighbor
        /// may not be functioning properly. A reachability confirmation was not
        /// received after transmitting the maximum number of reachability
        /// probes.
        UNREACHABLE = 7;
    };

    /// MAC address of the neighboring device's network interface controller.
    ///
    /// May be absent for dynamic entries in [`EntryState.UNREACHABLE`] or
    /// [`EntryState.INCOMPLETE`].
    // TODO(https://fxbug.dev/42056594): Consider pulling the address into a union
    // encoding the state and its presence for better type safety.
    4: mac fuchsia.net.MacAddress;

    /// Timestamp when this entry has changed `state`.
    ///
    /// Required.
    5: updated_at zx.Time;
};