// Copyright 2021 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 fuchsia.net.virtualization;

using fuchsia.hardware.network;
using fuchsia.net;

/// Provides control over virtualization network configuration.
@discoverable
closed protocol Control {
    /// Create a new network with configurable upstream connectivity.
    ///
    /// The network itself is always guaranteed to be created, but upstream
    /// connectivity may not be established initially and may be lost at
    /// any time.
    ///
    /// + request `config` network configuration.
    /// + request `network` provides control over the created network. The
    ///     protocol will be terminated after emitting a terminal event if the
    ///     network cannot be added.
    strict CreateNetwork(resource struct {
        config flexible union {
            // TODO(https://fxbug.dev/42167037): Currently bridged networks are not
            // isolated from each other (they are all on the same bridge). Provide
            // isolation via VLANs.
            /// Create a bridged network.
            ///
            /// The server will attempt to find a suitable interface to
            /// attach to the bridge for providing upstream connectivity. The
            /// selection process will be repeated to find a replacement
            /// iff the interface attached to the bridge with Internet
            /// connectivity is removed.
            1: bridged table {};
            /// Create a network that interacts with the host OS at the network
            /// layer.
            2: networked table {
                /// IPv4 configuration.
                ///
                /// Invalid if `connectivity` is `Ipv4Connectivity.routed`,
                /// but `addr_config` is not present.
                ///
                /// If not present, interpreted as the empty table.
                1: ipv4 @generated_name("Ipv4Config") table {
                    /// IPv4 address configuration options.
                    ///
                    /// If not present, no addresses will be assigned.
                    1: addr_config @generated_name("Ipv4AddressConfig") flexible union {
                        /// Static address configuration.
                        ///
                        /// The address and a subnet route will be configured.
                        1: static fuchsia.net.Ipv4AddressWithPrefix;
                        // TODO(https://fxbug.dev/42054627): Support running a DHCPv4 server.
                    };
                    /// IPv4 connectivity type.
                    ///
                    /// If present, IPv4 unicast packet forwarding will be enabled for this
                    /// network; otherwise, guests on the network will only be able to
                    /// communicate with each other and the host OS.
                    2: connectivity @generated_name("Ipv4Connectivity") flexible union {
                        /// IPv4 routing configuration.
                        ///
                        /// If present, a route to the subnet configured through
                        /// `Ipv4Config.addr_config` will be added.
                        1: routed @generated_name("Ipv4RoutedConfig") table {
                            /// NAT configuration.
                            ///
                            /// If present, perform IPv4 masquerading for packets originating
                            /// from the subnet configured through [`Ipv4Config.addr_config`]
                            /// going out all upstream-providing interfaces.
                            1: nat @generated_name("IPv4NatConfig") table {};
                        };
                        // TODO(https://fxbug.dev/42054621): Support Proxy ARP.
                    };
                    // TODO(https://fxbug.dev/42054528): Support multicast routing.
                };
                // TODO(https://fxbug.dev/42054622): Support IPv6 connectivity with Proxy NDP.
                // TODO(https://fxbug.dev/42054629): Support running a DHCPv6 server.
                // TODO(https://fxbug.dev/42055177): Support running a router advertising service.
            };
        };
        network server_end:Network;
    });
};

/// Provides control over a network.
///
/// This protocol encodes the lifetime of the underlying network in both
/// directions, that is:
/// - if the client end is closed: all interfaces added to the network
///     (not including any used to provide upstream connectivity) will be
///     removed and destroyed, and the network will be removed;
/// - if the server end is closed, all interfaces on the network and the
///     network itself have been destroyed.
closed protocol Network {
    /// Adds a port to the network.
    ///
    /// + request `port` port to be added.
    /// + request `interface` provides control over the interface.
    strict AddPort(resource struct {
        port client_end:fuchsia.hardware.network.Port;
        interface server_end:Interface;
    });

    /// Terminal event. Immediately precedes the closure of the server end of
    /// this protocol.
    ///
    /// - response `reason` the removal reason.
    strict -> OnRemoved(struct {
        reason @generated_name("NetworkRemovalReason") flexible enum {
            /// Failed to create the network due to invalid configuration.
            INVALID_CONFIG = 1;
        };
    });
};

// TODO(https://fxbug.dev/42168197): Add a terminal event and emit it to signal
// inability to add the interface due to incompatibility, e.g. if the network
// is bridged and the port added does not support the same L2 protocol as other
// ports on the bridge.
/// Provides control over an interface.
///
/// This protocol encodes the lifetime of the underlying interface in both
/// directions, that is:
/// - if the client end is closed, the server will detach the interface
///     from the network it belongs to and detach the network device;
/// - if the server end is closed, the interface has been detached from
///     the network it was attached to and destroyed.
closed protocol Interface {
    strict -> OnRemoved(struct {
        reason @generated_name("InterfaceRemovalReason") flexible enum {
            // TODO(https://fxbug.dev/42054781): Remove this variant once
            // multiple ports in networked mode is supported.
            /// Failed to create the network because the network supports only
            /// a single port.
            ONLY_ONE_PORT_SUPPORTED = 1;
        };
    });
};