// 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 zx;

/// Configuration options related to the operation of Neighbor Unreachability
/// Detection (NUD), as defined by RFC 4861 section 7.3.
///
/// Field names loosely follow RFC 4861 sections 6.3.2 and 10, any deviations
/// are noted. Descriptions are kept implementation-independent by using a set
/// of generic terminology.
///
/// ,-------------------------------------------------------------------.
/// | Generic Term              | ARP Protocol | NDP Protocol           |
/// |---------------------------+--------------+------------------------|
/// | Reachability Probe        | ARP Request  | Neighbor Solicitation  |
/// | Reachability Confirmation | ARP Reply    | Neighbor Advertisement |
/// `---------------------------+--------------+------------------------'
type UnreachabilityConfig = table {
    /// A base duration for computing the random reachable time.
    ///
    /// Reachable time is the duration for which a neighbor is considered
    /// reachable after a positive reachability confirmation is received. It is
    /// a function of a uniformly distributed random value between
    /// [`min_random_factor`] and [`max_random_factor`] multiplied by
    /// [`base_reachable_time`]. Using a random component eliminates the
    /// possibility that Neighbor Unreachability Detection messages will
    /// synchronize with each other.
    ///
    /// After this time, an entry will transition from REACHABLE to STALE state.
    ///
    /// Referred to as "BaseReachableTime" by RFC 4861.
    ///
    /// Must be greater than 0.
    1: base_reachable_time zx.duration;

    /// Learn [`base_reachable_time`] during runtime from the neighbor discovery
    /// protocol, if supported.
    2: learn_base_reachable_time bool;

    /// The minimum value of the random factor used for computing reachable
    /// time.
    ///
    /// See [`base_reachable_time`] for more information on computing the
    /// reachable time.
    ///
    /// Must be greater than 0.
    3: min_random_factor float32;

    /// The maximum value of the random factor used for computing reachable
    /// time.
    ///
    /// See [`base_reachable_time`] for more information on computing the
    /// reachable time.
    ///
    /// Must be greater than or equal to [`min_random_factor`].
    4: max_random_factor float32;

    /// Duration between retransmissions of reachability probes in the PROBE
    /// state.
    ///
    /// Referred to as "RetransTimer" by RFC 4861.
    ///
    /// Must be greater than 0.
    5: retransmit_timer zx.duration;

    /// Learn [`retransmit_timer`] during runtime from the neighbor discovery
    /// protocol, if supported.
    6: learn_retransmit_timer bool;

    /// Duration to wait for a non-Neighbor-Discovery related protocol to
    /// reconfirm reachability after entering the DELAY state. After this time,
    /// a reachability probe will be sent and the entry will transition to the
    /// PROBE state.
    ///
    /// Must be greater than 0.
    7: delay_first_probe_time zx.duration;

    /// The number of reachability probes to send before concluding negative
    /// reachability and deleting the entry from the INCOMPLETE state.
    ///
    /// Referred to as "MAX_MULTICAST_SOLICIT" by RFC 4861.
    ///
    /// Must be greater than 0.
    8: max_multicast_probes uint32;

    /// The number of reachability probes to send before concluding
    /// retransmissions from within the PROBE state should cease and the entry
    /// SHOULD be deleted.
    ///
    /// Referred to as "MAX_UNICAST_SOLICIT" by RFC 4861.
    ///
    /// Must be greater than 0.
    9: max_unicast_probes uint32;

    /// If the target address is an anycast address, the stack SHOULD delay
    /// sending a response for a random time between 0 and this duration.
   10: max_anycast_delay_time zx.duration;

    /// A node MAY send up to this amount of unsolicited reachability
    /// confirmations messages to all-nodes multicast address when a node
    /// determines its link-layer address has changed.
    ///
    /// Referred to as "MAX_NEIGHBOR_ADVERTISEMENT" by RFC 4861.
   11: max_reachability_confirmations uint32;
};

/// Default value for [`UnreachabilityConfig.base_reachable_time`] as
/// recommended by RFC 4861 section 10.
const DEFAULT_BASE_REACHABLE_TIME zx.duration = 30000000000; // 30 seconds

/// Default value for [`UnreachabilityConfig.retransmit_timer`] as recommended
/// by RFC 4861 section 10.
const DEFAULT_RETRANSMIT_TIMER zx.duration = 1000000000; // 1 second

/// Default value for [`UnreachabilityConfig.delay_first_probe_time`] as
/// recommended by RFC
/// 4861 section 10.
const DEFAULT_DELAY_FIRST_PROBE_TIME zx.duration = 5000000000; // 5 seconds

/// Default value for [`UnreachabilityConfig.max_anycast_delay_time`] as
/// recommended by RFC 4861 section 10.
const DEFAULT_MAX_ANYCAST_DELAY_TIME zx.duration = 1000000000; // 1 second

/// Default value for [`UnreachabilityConfig.min_random_factor`] as recommended
/// by RFC 4861 section 10.
const DEFAULT_MIN_RANDOM_FACTOR float32 = 0.5;

/// Default value for [`UnreachabilityConfig.max_random_factor`] as recommended
/// by RFC 4861 section 10.
const DEFAULT_MAX_RANDOM_FACTOR float32 = 1.5;

/// Default value for [`UnreachabilityConfig.max_multicast_probes`] as
/// recommended by RFC 4861 section 10.
const DEFAULT_MAX_MULTICAST_PROBES uint32 = 3;

/// Default value for [`UnreachabilityConfig.max_unicast_probes`] as
/// recommended by RFC 4861 section 10.
const DEFAULT_MAX_UNICAST_PROBES uint32 = 3;

/// Default value for [`UnreachabilityConfig.max_reachability_confirmations`] as
/// recommended by RFC 4861 section 10.
const DEFAULT_MAX_REACHABILITY_CONFIRMATIONS uint32 = 3;