sdk/fidl/fuchsia.net.policy.properties/networks.fidl

// Copyright 2025 The Fuchsia Authors.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@available(added=HEAD)
library fuchsia.net.policy.properties;

using fuchsia.net;
using fuchsia.net.name;
using zx;

/// The NetworkToken is an opaque token minted by [`Networks::WatchDefault`]
/// that represents a logical network for the purpose of accessing network
/// properties.
type NetworkToken = resource table {
    1: value zx.Handle:EVENTPAIR;
};

type DefaultNetworkUpdate = table {
    /// The value of the new interface id.
    /// NOTE: Required if `socket_marks` is set.
    1: interface_id fuchsia.net.InterfaceId;

    /// The socket marks associated with that interface.
    /// NOTE: Required if `interface_id` is set.
    2: socket_marks fuchsia.net.Marks;
};

/// A single update from [`Networks.WatchProperties`].
type PropertyUpdate = flexible union {
    /// The socket marks associated with this network.
    1: socket_marks fuchsia.net.Marks;
    /// The DNS Configuration associated with this network.
    2: dns_configuration @generated_name("DnsConfiguration") table {
        /// A preference ordered list of [`fuchsia.net.name.DnsServer`]s.
        /// NOTE: Required, this field must always be set.
        1: servers vector<fuchsia.net.name.DnsServer>:MAX;
    };
};

/// Protocol to allow `netcfg` to watch `socket-proxy` for changes in default
/// network and its associated socket marks. Only one connection to this
/// protocol is supported at once. If a second connection is made it will be
/// shut down with a `CONNECTION_ABORTED` error.
@discoverable
open protocol DefaultNetworkWatcher {
    /// Watch the current default network. On first call, an update will be
    /// immediately be sent. Subsequent calls will return only when a change
    /// occurs.
    /// NOTE: An empty update signifies that the default network has been lost.
    strict Watch() -> (DefaultNetworkUpdate);
};

// TODO(https://fxbug.dev/42159332): Use built-in empty struct when available.
type Empty = struct {};

/// Protocol for acquiring [`NetworkToken`]s, and querying properties of that
/// network.
@discoverable
open protocol Networks {
    /// Watches for changes in the default network.
    ///
    /// The first call always returns a [`NetworkToken`] representing the
    /// current default network, or if one is not present, blocks until a
    /// default network is set. Subsequent calls will block until the default
    /// network has changed, or has been lost, returning a new [`NetworkToken`]
    /// for the updated default network, or [`no_default_network`] if the
    /// network is lost.
    ///
    /// Only one call to this method should be pending per connection.
    flexible WatchDefault() -> (flexible resource union {
        1: network NetworkToken;
        2: no_default_network Empty;
    });

    /// Watches for changes in requested properties for the given [`NetworkToken`]
    ///
    /// The first call will always return a snapshot of all requested
    /// properties. Subsequent calls will block until any property changes, at
    /// which point the changed property or properties will be sent. If the set
    /// of requested [`properties`] changes on a subsequent call, the previously
    /// unreported property will be sent immediately, before future calls will
    /// return to the hanging get pattern. If the network represented by
    /// `network` is no longer the default network, the connection will be
    /// closed with `DEFAULT_NETWORK_CHANGED`.
    ///
    /// Only one call to this method should be pending per [`NetworkToken`] per connection.
    flexible WatchProperties(resource table {
        /// A network token acquired from [`WatchDefault`].
        /// NOTE: REQUIRED
        1: network NetworkToken;

        /// List of properties for which changes should be reported. Must be
        /// non-empty, duplicates will be ignored.
        /// NOTE: REQUIRED
        2: properties vector<@generated_name("Property") flexible enum {
            SOCKET_MARKS = 1;
            DNS_CONFIGURATION = 2;
        }>:MAX;
    }) -> (struct {
        /// A list of updates that have happened since the last call to
        /// `WatchProperties` returned. There is no guarantee of ordering. If a
        /// property changes multiple times between updates, only the most
        /// recent version will be reported.
        updates vector<PropertyUpdate>:MAX;
    }) error @generated_name("WatchError") flexible enum : uint32 {
        /// The provided `properties` list was empty.
        NO_PROPERTIES = 1;
        /// The provided NetworkToken was either not acquired from
        /// [`WatchDefault`] or is no longer valid.
        INVALID_NETWORK_TOKEN = 2;
        /// When the network represented by `network` no longer exists, a new
        /// [`NetworkToken`] must be acquired.
        NETWORK_GONE = 3;
        /// When the network represented by `network` is no longer the default
        /// network, a new [`NetworkToken`] must be acquired.
        DEFAULT_NETWORK_CHANGED = 4;
        /// When there is no longer a default network, a new [`NetworkToken`]
        /// must be acquired.
        DEFAULT_NETWORK_LOST = 5;

        /// An argument marked above as REQUIRED was not provided.
        MISSING_REQUIRED_ARGUMENT = 99;
    };
};