sdk/fidl/fuchsia.net.routes.admin/ipv4.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.

// The fuchsia.net.routes.admin API is split into two variants, one supporting
// IPv4 routes and the other supporting IPv6 routes. The two halves are a mirror
// image of one another, and should be kept in sync moving forward. Edits
// made here should also be applied to "ipv6.fidl".
// LINT.IfChange
library fuchsia.net.routes.admin;

using fuchsia.net.interfaces.admin;
using fuchsia.net.routes;

/// Vends isolated administrative access to the system's routing table.
@discoverable
protocol SetProviderV4 {
    /// Creates an empty route set.
    ///
    /// + request `route_set` grants access to the [`RouteSetV4`] protocol.
    NewRouteSet(resource struct {
        route_set server_end:RouteSetV4;
    });
};

/// Provides mutable access over a set of system's IPv4 routes.
///
/// The system maintains a single global routing table. A route set offers an
/// isolated window into a subset of the global routing table: clients are free
/// to manage the routes within their own route set, but not the route set of
/// others. Thus the global routing table represents the union of all existing
/// route sets. A route must be removed from all route sets to which it belongs
/// before it will be removed from the global table.
///
/// This protocol encodes the lifetime of the route set. Closing the client end
/// removes the route set, and will also remove any routes that were
/// solely-owned by this route set.
///
/// Note that the system reserves the right to remove routes out from underneath
/// this route set. This will always manifest as a `removed` event on the
/// [`fuchsia.net.routes/WatcherV4`] protocol.
protocol RouteSetV4 {
    /// Authenticate this route set to manage routes on the provided interface.
    /// Authentication is valid for the lifetime of the route set.
    ///
    /// + request `interface` the authentication credential for an interface.
    AuthenticateForInterface(resource struct {
        credential fuchsia.net.interfaces.admin.ProofOfInterfaceAuthorization;
    }) -> () error AuthenticateForInterfaceError;

    /// Adds a route to this route set.
    ///
    /// + request `route` the route to add.
    /// - response `did_add` true iff the route was added to this `RouteSet`
    ///            as a result of this call.
    AddRoute(resource struct {
        route fuchsia.net.routes.RouteV4;
    }) -> (struct {
        did_add bool;
    }) error RouteSetError;

    /// Removes a route from this route set.
    ///
    /// Note that if this route also exists other route sets, it will not be
    /// removed from the global routing table.
    ///
    /// + request `route` the route to remove.
    /// - response `did_remove` true iff the route was removed from this
    ///            `RouteSet` as a result of this call.
    RemoveRoute(resource struct {
        route fuchsia.net.routes.RouteV4;
    }) -> (struct {
        did_remove bool;
    }) error RouteSetError;
};

// LINT.ThenChange(ipv6.fidl)