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

/// Provides facilities for migrating from Netstack2 to Netstack3.
///
/// This library provides the protocols necessary to conduct the network stack
/// migration to the newer version. It will be removed as soon as migration is
/// completed across all users, and it's not intended to be used beyond that.
///
/// At the time of its introduction there aren't platform-wide mechanisms to
/// achieve this, so this one-off library was created to achieve the migration
/// goals.
///
/// It should not be extended to serve other uses and, if there appears a
/// central platform-wide mechanism to achieve this before migration is fully
/// completed it might be deleted before then.
// TODO(https://fxbug.dev/42081574): Remove this library as soon as migration is
// completed.
@available(added=14)
library fuchsia.net.stackmigrationdeprecated;

/// Known Network Stack versions.
type NetstackVersion = strict enum {
    NETSTACK2 = 1;
    NETSTACK3 = 2;
};


/// A wrapper type around [`NetstackVersion`] providing optionality for
/// [`Control`] methods.
type VersionSetting = struct {
    version NetstackVersion;
};

/// Provides access to controlling netstack migration configuration.
@discoverable
closed protocol Control {
    /// Sets the automated target network stack version.
    ///
    /// Takes effect on next boot.
    ///
    /// + request `version` requested network stack version. If unset, the
    ///   automated version preference is cleared.
    strict SetAutomatedNetstackVersion(struct {
        version box<VersionSetting>;
    }) -> ();

    /// Sets user selection target network stack version.
    ///
    /// Takes effect on next boot.
    ///
    /// If set, the user netstack version preference always takes precedence
    /// over the automated version selection.
    ///
    /// + request `version` requested network stack version. If unset, the user
    ///   version preference is cleared.
    strict SetUserNetstackVersion(struct {
        version box<VersionSetting>;
    }) -> ();
};


/// Provides access to reading netstack migration configuration.
@discoverable
closed protocol State {
    /// Gets the target network stack version.
    ///
    /// - response `in_effect_version` the configurations currently in effect.
    strict GetNetstackVersion() -> (struct {
        in_effect_version struct {
            /// The value of the netstack version setting at boot time. This
            /// reflects the currently running netstack.
            current_boot NetstackVersion;
            /// The automated netstack version selected. If set and no `user`
            /// version is set, it'll be applied on next boot. This reflects the
            /// last applied configuration through
            /// [`Control.SetAutomatedNetstackVersion`].
            automated box<VersionSetting>;
            /// The user netstack version selected. If set, it'll be applied on
            /// next boot. The `user` version always takes predence over the
            /// `automated` version. This reflects the last applied
            /// configuration through [`Control.SetUserNetstackVersion`].
            user box<VersionSetting>;
        };
    });
};