// Copyright 2022 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.lowpan.experimental;

using fuchsia.lowpan;
using fuchsia.net;

const MAX_ON_MESH_PREFIXES uint32 = 32;
const MAX_EXTERNAL_ROUTES uint32 = 32;

/// Route preference, as described in RFC4191.
type RoutePreference = strict enum : int8 {
    /// Low route preference.
    LOW = -1;

    /// Medium route preference.
    MEDIUM = 0;

    /// High route preference.
    HIGH = 1;
};

/// LoWPAN On-Mesh Prefix.
///
/// Informed by the Thread 1.1.1 Specification, section 5.13.2.
type OnMeshPrefix = table {
    /// Subnet to advertise for devices to use on the network. Required.
    1: subnet fuchsia.net.Ipv6AddressWithPrefix;

    /// If present, indicates that this device is offering a default route
    /// as well as indicating the what preference this default
    /// route should be given relative to other devices offering default
    /// routes. If not present, no default route is advertised.
    ///
    /// Based on `P_default` and `P_preference` from Section 5.13.2 of the
    /// Thread 1.1.1 Specification.
    2: default_route_preference RoutePreference;

    /// True if the route is expected to be available for at least Thread's
    /// `MIN_STABLE_LIFETIME`; otherwise `false`. If not present, assumed to
    /// be `false`.
    ///
    /// The Thread specification defines `MIN_STABLE_LIFETIME` as 168 hours.
    ///
    /// Based on `P_stable` from Section 5.13.2 of the
    /// Thread 1.1.1 Specification.
    3: stable bool;

    /// True if network devices are allowed to use previously configured
    /// addresses using this prefix. If not present, assumed to be `false`.
    ///
    /// "SLAAC" referrs to StateLess Address Auto Configuration, described in
    /// [RFC4862](https://tools.ietf.org/html/rfc4862).
    ///
    /// Based on `P_slaac_preferred` from Section 5.13.2 of the
    /// Thread 1.1.1 Specification.
    4: slaac_preferred bool;

    /// True if network devices are allowed to autoconfigure addresses using
    /// this prefix. If not present, assumed to be `false`.
    ///
    /// "SLAAC" referrs to StateLess Address Auto Configuration, described in
    /// [RFC4862](https://tools.ietf.org/html/rfc4862).
    ///
    /// Based on `P_slaac_valid` from Section 5.13.2 of the
    /// Thread 1.1.1 Specification.
    5: slaac_valid bool;
};

/// LoWPAN External Route.
///
/// Informed by the Thread 1.1.1 Specification, section 5.13.3.
type ExternalRoute = table {
    /// Subnet for route. Required.
    1: subnet fuchsia.net.Ipv6AddressWithPrefix;

    /// Indicates the what preference this route should be given relative
    /// to other devices offering the same external route. If not present,
    /// `MEDIUM` preference is assumed.
    ///
    /// Based on `R_preference` from Section 5.13.3 of the Thread 1.1.1
    /// Specification.
    2: route_preference RoutePreference;

    /// True if the route is expected to be available for at least Thread's
    /// `MIN_STABLE_LIFETIME`; otherwise, `false`. If not present, assumed to
    /// be `false`.
    ///
    /// The Thread specification defines `MIN_STABLE_LIFETIME` as 168 hours.
    ///
    /// Based on `R_stable` from Section 5.13.3 of the Thread 1.1.1
    /// Specification.
    3: stable bool;
};

/// Protocol for connecting to `fuchsia.lowpan.device.DeviceRoute` on a LoWPAN
/// interface.
@discoverable
closed protocol DeviceRouteConnector {
    /// Connects to the `fuchsia.lowpan.device.DeviceRoute` protocol on the
    /// named LoWPAN interface.
    ///
    /// The name of the interface can be learned by calling
    /// `fuchsia.lowpan.Lookup.GetDevices()`.
    ///
    /// If there is an error in processing this request
    /// the given channel is closed and an epitaph code used
    /// to describe the reason for the failure:
    ///
    /// * `ZX_ERR_INVALID_ARGUMENT`: The given interface name
    ///   was not formatted correctly or otherwise invalid.
    /// * `ZX_ERR_NOT_FOUND`: No interface was found with the
    ///   given name.
    /// * `ZX_ERR_NOT_SUPPORTED`: The interface exists but
    ///   does not support this protocol.
    strict Connect(resource struct {
        name fuchsia.lowpan.InterfaceName;
        server_end server_end:DeviceRoute;
    });
};

/// LoWPAN protocol for IPv6 route and prefix management methods that
/// do not expose PII.
///
/// Note that methods that deal with PII are located in the
/// `DeviceRouteExtra` protocol.
closed protocol DeviceRoute {
    /// Registers an on-mesh prefix to be advertised on the
    /// current network.
    ///
    /// Subsequent calls with the same value for the `subnet` field will
    /// update the properties associated with that on-mesh prefix.
    ///
    /// These changes persist like adding an IP address would,
    /// and will stick around until explicitly removed or
    /// the interface component is reset/restarted.
    ///
    /// If the given `OnMeshPrefix` structure is invalid for some reason
    /// (missing required fields, invalid values, etc), the channel will be
    /// closed with the epitaph `ZX_ERR_INVALID_ARGS`.
    ///
    /// If registering a new on-mesh prefix and the maximum number of
    /// on-mesh prefixes has already been registered, this channel will
    /// be closed with the epitaph `ZX_ERR_NO_RESOURCES`.
    strict RegisterOnMeshPrefix(struct {
        prefix OnMeshPrefix;
    }) -> ();

    /// Unregisters any on-mesh prefix that was previously registered with
    /// `RegisterOnMeshPrefix`.  It returns once the on-mesh prefix has
    /// been removed locally.
    ///
    /// If the given mesh prefix was not previously registered,
    /// no action is taken.
    strict UnregisterOnMeshPrefix(struct {
        subnet fuchsia.net.Ipv6AddressWithPrefix;
    }) -> ();

    /// Registers an external route to be advertised on the
    /// current network.
    ///
    /// Subsequent calls with the same value for the `subnet` field will
    /// update the properties associated with that route.
    ///
    /// These changes persist like adding an IP address would,
    /// and will stick around until explicitly removed or
    /// the interface component is reset/restarted.
    ///
    /// If the given `ExternalRoute` structure is invalid for some reason
    /// (missing required fields, invalid values, etc), the channel will be
    /// closed with the epitaph `ZX_ERR_INVALID_ARGUMENT`.
    ///
    /// If registering a new external route and the maximum number of
    /// external routes has already been registered, this channel will
    /// be closed with the epitaph `ZX_ERR_NO_RESOURCES`.
    strict RegisterExternalRoute(struct {
        external_route ExternalRoute;
    }) -> ();

    /// Unregisters any external route that was previously registered with
    /// `RegisterExternalRoute`. It returns once the external route has
    /// been removed locally.
    ///
    /// If the given external route was not previously registered,
    /// no action is taken.
    strict UnregisterExternalRoute(struct {
        subnet fuchsia.net.Ipv6AddressWithPrefix;
    }) -> ();
};

/// Protocol for connecting to [`DeviceRouteExtra`] on a LoWPAN
/// interface.
@discoverable
closed protocol DeviceRouteExtraConnector {
    /// Connects to the [`DeviceRouteExtra`] protocol on the
    /// named LoWPAN interface.
    ///
    /// The name of the interface can be learned by calling
    /// [`fuchsia.lowpan/Lookup.GetDevices`].
    ///
    /// If there is an error in processing this request
    /// the given channel is closed and an epitaph code used
    /// to describe the reason for the failure:
    ///
    /// * `ZX_ERR_INVALID_ARGUMENT`: The given interface name
    ///   was not formatted correctly or otherwise invalid.
    /// * `ZX_ERR_NOT_FOUND`: No interface was found with the
    ///   given name.
    /// * `ZX_ERR_NOT_SUPPORTED`: The interface exists but
    ///   does not support this protocol.
    strict Connect(resource struct {
        name fuchsia.lowpan.InterfaceName;
        server_end server_end:DeviceRouteExtra;
    });
};

/// LoWPAN protocol for IPv6 route and prefix management methods that
/// expose PII.
///
/// Note that methods that do not deal with PII are located in the
/// `DeviceRoute` protocol.
closed protocol DeviceRouteExtra {
    /// Returns a vector containing all of the locally-added on-mesh prefixes.
    ///
    /// Locally-added on-mesh prefixes are those that have been registered
    /// with a prior call to [`DeviceRoute.RegisterOnMeshPrefix`].
    strict GetLocalOnMeshPrefixes() -> (struct {
        prefixes vector<OnMeshPrefix>:MAX_ON_MESH_PREFIXES;
    });

    /// Returns a vector containing all of the locally-added external routes.
    ///
    /// Locally-added external routes are those that have been registered
    /// with a prior call to [`DeviceRoute.RegisterExternalRoute`].
    strict GetLocalExternalRoutes() -> (struct {
        external_routes vector<ExternalRoute>:MAX_EXTERNAL_ROUTES;
    });
};