sdk/fidl/fuchsia.net.masquerade/client.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 containing methods to enable address masquerading for a given interface pair.
library fuchsia.net.masquerade;

using fuchsia.net;

/// All possible error types that may be returned by calls to `Control` or `Factory`.
type Error = enum {
    /// An unsupported configuration was provided. It may be one of:
    /// - A masquerade instance already exists for the current `input_interface`.
    /// - The provided `src_subnet` was unspecified (`0/0`)
    UNSUPPORTED = 0;

    /// One or more of the configuration fields was invalid (e.g. `src_if` can't
    /// fit in u32)
    INVALID_ARGUMENTS = 1;

    /// The provided `src_if` was not found.
    NOT_FOUND = 2;

    /// The provided `src_subnet`/`outgoing_nic` pair already exist in the Nat
    /// rules.
    ALREADY_EXISTS = 3;

    /// The call to `fuchsia.net.filter.deprecated.Filter::UpdateNatRules`
    /// returned `BadRule`.
    BAD_RULE = 4;

    /// The attempt to update the Nat rules failed with `GenerationMismatch` too
    /// many times.
    RETRY_EXCEEDED = 5;
};

/// Control provides a IP masquerade instance.
///
/// This protocol is associated with the lifetime of the IP masquerade
/// between interfaces for the configured network. This configuration will
/// be torn down whenever either end of the protocol is closed.
closed protocol Control {
    /// SetEnabled enables or disabled IP masquerading for the configured
    /// instance. Newly created instances are disabled and must be enabled
    /// via this API.
    ///
    /// + request `enabled` True to enable masquerade; false to disable.
    /// - response `was_enabled` True if the interface was enabled before this call.
    strict SetEnabled(struct {
        enabled bool;
    }) -> (struct {
        was_enabled bool;
    }) error Error;
};

/// Factory instantiates Control protocol instances for IP masquerading.
///
/// This protocol is used to create instances allowing for the control of
/// IP masquerade of a particular network.
@discoverable
closed protocol Factory {
    /// Create a new IP masquerade instance using the supplied
    /// configuration.
    ///
    /// Configurations cannot be changed once instantiated. If a different
    /// configuration is to be applied, the prior instance should first be
    /// disabled and the channel torn down.
    ///
    /// The instance that is returned is initially in a disabled state and
    /// must be explicitly enabled prior to use.
    ///
    /// + request `config` Configuration to use for the IP masquerade
    ///   instance.
    /// + request `control` Control handle to use for configuring the
    ///   instance.
    strict Create(resource struct {
        config @generated_name("ControlConfig") struct {
            /// The interface carrying the network to be masqueraded.
            input_interface fuchsia.net.InterfaceId;
            /// The network to be masqueraded.
            src_subnet fuchsia.net.Subnet;
            /// The interface through which to masquerade.
            output_interface fuchsia.net.InterfaceId;
        };
        control server_end:Control;
    }) -> () error Error;
};