sdk/fidl/fuchsia.net.settings/settings.fidl

// Copyright 2025 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.

/// Provides control and access to namespace-wide network stack settings.
@available(added=HEAD)
library fuchsia.net.settings;

using fuchsia.net.interfaces.admin;

alias Interface = fuchsia.net.interfaces.admin.Configuration;

/// Errors exposed when changing settings via [`Control`].
type UpdateError = flexible enum {
    /// Indicates that a zero value was provided for a field that must be
    /// nonzero.
    ILLEGAL_ZERO_VALUE = 1;
    /// Indicates that a negative value was provided for a field that must
    /// be non-negative.
    ILLEGAL_NEGATIVE_VALUE = 2;
    /// Indicates that a configured value is out of the allowed range.
    OUT_OF_RANGE = 3;
    /// Requested setting is not supported.
    NOT_SUPPORTED = 4;
};

/// Provides control over the network stack namespace-wide configuration.
@discoverable
closed protocol Control {
    /// Updates the default configurations for interfaces.
    ///
    /// New interfaces created take default values from this configuration.
    ///
    /// Note that some interface types may not support specific configurations,
    /// in which case the value is either ignored or the network stack assigns a
    /// server-assigned value.
    ///
    /// Only fields present in the provided [`Interface`] are set; unset fields
    /// are left unmodified. The server returns a `Interface` which holds the
    /// previous configuration for fields that were set in the request.
    ///
    /// No values are changed if an error is returned.
    ///
    /// + request configuration fields to update on the interface defaults.
    /// - response a partial snapshot of the previous default configuration.
    strict UpdateInterfaceDefaults(Interface) -> (Interface) error UpdateError;

    /// Updates TCP settings.
    ///
    /// Only fields present in the provided [`Tcp`] are set; unset fields are
    /// left unmodified. The server returns a `Tcp` which holds the previous
    /// settings for fields that were set in the request.
    ///
    /// No values are changed if an error is returned.
    ///
    /// + request TCP settings fields to update.
    /// - response a partial snapshot of the previous TCP settings.
    strict UpdateTcp(Tcp) -> (Tcp) error UpdateError;


    /// Updates UDP settings.
    ///
    /// Only fields present in the provided [`Udp`] are set; unset fields are
    /// left unmodified. The server returns a `Udp` which holds the previous
    /// settings for fields that were set in the request.
    ///
    /// No values are changed if an error is returned.
    ///
    /// + request UDP settings fields to update.
    /// - response a partial snapshot of the previous UDP settings.
    strict UpdateUdp(Udp) -> (Udp) error UpdateError;

    /// Updates ICMP settings.
    ///
    /// Only fields present in the provided [`Icmp`] are set; unset fields are
    /// left unmodified. The server returns a `Icmp` which holds the previous
    /// settings for fields that were set in the request.
    ///
    /// No values are changed if an error is returned.
    ///
    /// + request ICMP settings fields to update.
    /// - response a partial snapshot of the previous ICMP settings.
    strict UpdateIcmp(Icmp) -> (Icmp) error UpdateError;

    /// Updates IP settings.
    ///
    /// Only fields present in the provided [`Ip`] are set; unset fields are
    /// left unmodified. The server returns a `Ip` which holds the previous
    /// settings for fields that were set in the request.
    ///
    /// No values are changed if an error is returned.
    ///
    /// + request IP settings fields to update.
    /// - response a partial snapshot of the previous IP settings.
    strict UpdateIp(Ip) -> (Ip) error UpdateError;


    /// Updates device layer settings.
    ///
    /// Only fields present in the provided [`Device`] are set; unset
    /// fields are left unmodified. The server returns a `Device` which
    /// holds the previous settings for fields that were set in the
    /// request.
    ///
    /// No values are changed if an error is returned.
    ///
    /// + request device layer settings fields to update.
    /// - response a partial snapshot of the previous device layer.
    strict UpdateDevice(Device) -> (Device) error UpdateError;
};


/// Provides read access to the network stack namespace-wide settings.
@discoverable
closed protocol State {
    /// Returns the current default settings for interfaces.
    strict GetInterfaceDefaults() -> (Interface);
    /// Returns the current TCP settings values.
    strict GetTcp() -> (Tcp);
    /// Returns the current UDP settings values.
    strict GetUdp() -> (Udp);
    /// Returns the current ICMP settings values.
    strict GetIcmp() -> (Icmp);
    /// Returns the current IP settings values.
    strict GetIp() -> (Ip);
    /// Returns the current device layer settings values.
    strict GetDevice() -> (Device);
};


/// TCP protocol settings.
type Tcp = table {
    /// Controls TCP socket buffer sizes.
    1: buffer_sizes SocketBufferSizes;
};

/// UDP protocol settings.
type Udp = table {
    /// Controls UDP socket buffer sizes.
    1: buffer_sizes SocketBufferSizes;
};

/// ICMP protocol settings.
type Icmp = table {
    /// Controls the ICMP echo socket buffer sizes.
    1: echo_buffer_sizes SocketBufferSizes;
    /// ICMPv4 configs.
    2: icmpv4 Icmpv4;
    /// ICMPv6 configs.
    3: icmpv6 Icmpv6;
};

/// ICMPv4 protocol settings.
type Icmpv4 = table {};

/// ICMPv6 protocol settings.
type Icmpv6 = table {};

/// Device layer settings.
type Device = table {
    /// Controls the buffer sizes for packet (a.k.a device) sockets.
    1: packet_buffer_sizes SocketBufferSizes;
};

/// IPv4 protocol settings.
type Ipv4 = table {};

/// IPv6 protocol settings.
type Ipv6 = table {};

/// IP protocol settings.
type Ip = table {
    /// Controls raw IP socket buffer sizes.
    1: raw_buffer_sizes SocketBufferSizes;
    /// IPv4 configs.
    2: ipv4 Ipv4;
    /// IPv6 configs.
    3: ipv6 Ipv6;
};


/// Socket buffer size range settings.
type SocketBufferSizeRange = table {
    /// The maximum allowed buffer size.
    ///
    /// Must be nonzero and greater than or equal to `min`.
    1: max uint32;
    /// The default buffer size for newly created sockets.
    ///
    /// When updating, must be between `min` and `max`.
    ///
    /// Must be nonzero.
    2: default uint32;
    /// The minimum allowed buffer size.
    ///
    /// Must be nonzero and less than or equal to `max`.
    3: min uint32;
};

/// Settings for socket buffer sizes.
type SocketBufferSizes = table {
    /// Send buffer sizes settings.
    1: send SocketBufferSizeRange;
    /// Receive buffer sizes settings.
    2: receive SocketBufferSizeRange;
};