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

using fuchsia.net;

/// A `RouteV4` specifies an IPv4 network route.
@available(added=HEAD)
type RouteV4 = struct {
    /// The destination subnet of the route. When making a routing decision
    /// for a given packet the route whose destination forms the longest
    /// matching prefix will be selected, with ties being broken by the route's
    /// metric.
    destination fuchsia.net.Ipv4AddressWithPrefix;
    /// Packets matching this route will have the specified action applied to
    /// them.
    action @generated_name("RouteActionV4") flexible union {
        /// Forward the packet to the specified target.
        1: forward @generated_name("RouteTargetV4") struct {
            /// The interface ID of the target's outbound interface.
            outbound_interface fuchsia.net.InterfaceId;
            /// The optional next-hop of the target. If provided, the address
            /// must be a unicast address.
            next_hop box<fuchsia.net.Ipv4Address>;
        };
    };
    /// The additional properties of the IPv4 route.
    properties @generated_name("RoutePropertiesV4") table {
        /// The route's specified properties.
        1: specified_properties SpecifiedRouteProperties;
    };
};

/// An `InstalledRouteV4` specifies an IPv4 network route that is installed in
/// the system's routing table.
@available(added=HEAD)
type InstalledRouteV4 = table {
    /// The route.
    1: route RouteV4;
    /// The route's effective properties.
    2: effective_properties EffectiveRouteProperties;
    /// The ID of the table to which this route belongs.
    3: table_id TableId;
};

/// Provides observability to the system's IPv4 routing state.
@discoverable
@available(added=HEAD)
closed protocol StateV4 {
    /// Initialize a watcher for IPv4 routing state.
    ///
    /// + request 'watcher' grants access to the `WatcherV4` Protocol.
    /// + request `watch_options` specifies the behavior of the `WatcherV4`.
    strict GetWatcherV4(resource struct {
        watcher server_end:WatcherV4;
        options @generated_name("WatcherOptionsV4") table {
            /// Only watch for events on the specified table.
            1: table_id TableId;
        };
    });

    /// Initialize a watcher for IPv4 rules state.
    ///
    /// + request 'watcher' grants access to the `RuleWatcherV4` Protocol.
    /// + request `watch_options` specifies the behavior of the `RuleWatcherV4`.
    strict GetRuleWatcherV4(resource struct {
        watcher server_end:RuleWatcherV4;
        options @generated_name("RuleWatcherOptionsV4") table {};
    });
};

/// An observer protocol for changes in system's IPv4 routing state.
@available(added=HEAD)
closed protocol WatcherV4 {
    /// Hanging-Get style API for observing routing changes.
    ///
    /// Clients must only have one pending `Watch` call at a time. Calling
    /// `Watch` while a request is already pending will cause the protocol to
    /// close.
    ///
    /// The first N events will always be `existing` where N is the number of
    /// IPv4 routes that already existed when the server-end of the protocol was
    /// initialized. The following event will be `idle` signaling the end of the
    /// `existing` events. At this point the client has watched all existing
    /// state and will never again observe an `existing` event.
    ///
    /// Events are returned in batches of up to `MAX_EVENTS` events. There is no
    /// correlation between the batch size/boundary and it's contents: it is
    /// perfectly valid for the server to split the block of `existing` events,
    /// across several batches. Clients should view this API as providing a
    /// stream of events, where batches are used to reduce IPC load on the
    /// system.
    ///
    /// - response `events` A vector of at most `MAX_EVENTS` events.
    strict Watch() -> (struct {
        events vector<@generated_name("EventV4") flexible union {
            /// A route that already existed when watching started.
            1: existing InstalledRouteV4;
            /// Sentinel value indicating no more `existing` events will be
            /// received.
            2: idle Empty;
            /// A route that was added while watching.
            3: added InstalledRouteV4;
            /// A route that was removed while watching.
            4: removed InstalledRouteV4;
        }>:MAX_EVENTS;
    });
};

/// An installed IPv4 routing rule.
@available(added=HEAD)
type InstalledRuleV4 = struct {
    /// Rule sets are ordered by the rule set priority, rule sets are disjoint
    /// and don’t have interleaving rules among them.
    rule_set_priority RuleSetPriority;
    /// Rules within a rule set are locally ordered, together with the rule set
    /// priority, this defines a global order for all installed rules.
    rule_index RuleIndex;
    /// The selector part of the rule, the rule is a no-op if the selector does
    /// not match the packet.
    selector RuleSelectorV4;
    /// The action part of the rule that describes what to do if the selector
    /// matches the packet.
    action RuleAction;
};


/// An observer protocol for changes in the system's IPv4 rules table.
@available(added=HEAD)
closed protocol RuleWatcherV4 {
    /// Hanging-Get style API for observing routing rule changes.
    ///
    /// Clients must only have one pending `Watch` call at a time. Calling
    /// `Watch` while a request is already pending will cause the protocol to
    /// close.
    ///
    /// The first N events will always be `existing` where N is the number of
    /// IPv4 rules that already existed when the server-end of the protocol was
    /// initialized. The following event will be `idle` signaling the end of the
    /// `existing` events. At this point the client has watched all existing
    /// state and will never again observe an `existing` event.
    ///
    /// - response `events` A vector of at most `MAX_EVENTS` events.
    strict Watch() -> (struct {
        events vector<@generated_name("RuleEventV4") flexible union {
            /// A rule that already existed when watching started.
            1: existing InstalledRuleV4;
            /// Sentinel value indicating no more `existing` events will be
            /// received.
            2: idle Empty;
            /// A rule that was added while watching.
            3: added InstalledRuleV4;
            /// A rule that was removed while watching.
            4: removed InstalledRuleV4;
        }>:MAX_EVENTS;
    });
};

/// The selector part of the rule that is used to match packets.
///
/// A selector matches a packet if all of the present fields match the
/// corresponding properties.
@available(added=HEAD)
type RuleSelectorV4 = table {
    /// Matches whether the source address of the packet is from the subnet.
    1: from fuchsia.net.Ipv4AddressWithPrefix;
    /// The rest of the selectors that is common between IP versions.
    2: base BaseSelector;
};
// LINT.ThenChange(ipv6.fidl)