// 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 fuchsia.net.root;

using fuchsia.net.filter;

/// Provides administrative access to all filtering state.
///
/// This protocol provides the ability to bypass regular ownership controls
/// which allow only the owner of each controller to modify or remove resources
/// they added.
///
/// Circumventing the strong-ownership semantics through use of this protocol
/// is highly discouraged and applications considering use of this protocol
/// are encouraged to exhaust other options first by working with the Netstack
/// team to find an alternative solution.
@discoverable
closed protocol Filter {
    /// Open a new *or* existing `NamespaceController`. The server end is
    /// "auto-detached": in other words, it behaves as if the client has called
    /// `Detach` on creation, and the lifetime of the filtering state is not
    /// tied to the client end of the protocol. If the client does call
    /// `Detach` on the `NamespaceController`, the server will close the
    /// channel.
    ///
    /// Clients have unilateral access to add or remove resources owned by the
    /// controller, irrespective of other clients' ownership. This includes the
    /// ability to remove resources installed by other clients.
    strict OpenController(resource struct {
        id fuchsia.net.filter.ControllerId;
        request server_end:fuchsia.net.filter.NamespaceController;
    });
};