sdk/fidl/fuchsia.net.root/routes.fidl

// Copyright 2023 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.root;

using fuchsia.net.routes.admin;

/// Provides access to IPv4 routes.
///
/// This protocol provides the ability to bypass regular ownership-controls
/// which allow only the route set owner to remove routes it added.
///
/// Circumventing the strong-ownership semantics through use of this protocol
/// is highly discouraged and applications considering use of this protocol
/// are encouraged to exhaust other options first by working with the Netstack
/// team to find an alternative solution.
@discoverable
closed protocol RoutesV4 {
    /// Returns a `RouteSetV4` containing all IPv4 routes from the global
    /// routing table. Clients have unilateral access to add or remove routes
    /// from the set. This includes the ability to remove routes installed by
    /// the system, or routes installed by other clients of the `RouteSetV4`
    /// protocol.
    ///
    /// Note that the established connection to the `RouteSetV4` protocol will
    /// have a few notable differences from a `RouteSetV4` obtained by
    /// [`fuchsia.net.routes.admin/RouteTableV4.NewRouteSet`]:
    ///   - When removing a route from this route set, the route will be
    ///     completely removed from the system, including removal from all other
    ///     route sets to which it belongs.
    ///   - The protocol does not encode the lifetime of the route set or its
    ///     routes. Closing the client end will not cause the routes within this
    ///     route set to be removed from the system. Thus, routes added via this
    ///     route set will effectively be abandoned/unowned after this
    ///     client-end closes.
    ///
    /// + request `route set` grants access to the `RouteSetV4` protocol.
    strict GlobalRouteSet(resource struct {
        route_set server_end:fuchsia.net.routes.admin.RouteSetV4;
    });
};


/// Provides access to IPv6 routes.
///
/// This protocol provides the ability to bypass regular ownership-controls
/// which allow only the route set owner to remove routes it added.
///
/// Circumventing the strong-ownership semantics through use of this protocol
/// is highly discouraged and applications considering use of this protocol
/// are encouraged to exhaust other options first by working with the Netstack
/// team to find an alternative solution.
@discoverable
closed protocol RoutesV6 {
    /// Returns a `RouteSetV6` containing all IPv6 routes from the global
    /// routing table. Clients have unilateral access to add or remove routes
    /// from the set. This includes the ability to remove routes installed by
    /// the system, or routes installed by other clients of the `RouteSetV6`
    /// protocol.
    ///
    /// Note that the established connection to the `RouteSetV6` protocol will
    /// have a few notable differences from a `RouteSetV6` obtained by
    /// [`fuchsia.net.routes.admin/RouteTableV6.NewRouteSet`]:
    ///   - When removing a route from this route set, the route will be
    ///     completely removed from the system, including removal from all other
    ///     route sets to which it belongs.
    ///   - The protocol does not encode the lifetime of the route set or its
    ///     routes. Closing the client end will not cause the routes within this
    ///     route set to be removed from the system. Thus, routes added via this
    ///     route set will effectively be abandoned/unowned after this
    ///     client-end closes.
    ///
    /// + request `route set` grants access to the `RouteSetV6` protocol.
    strict GlobalRouteSet(resource struct {
        route_set server_end:fuchsia.net.routes.admin.RouteSetV6;
    });
};