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

/// A filtering resource.
type Resource = flexible union {
    1: namespace Namespace;
    2: routine Routine;
    3: rule Rule;
};

/// An identifier for a filtering resource, unique within a controller's scope.
type ResourceId = flexible union {
    1: namespace NamespaceId;
    2: routine RoutineId;
    3: rule RuleId;
};

/// Observer protocol for changes to packet filtering state (addition, deletion,
/// and updates to filtering resources).
closed protocol Watcher {
    /// Hanging get for filtering resource changes.
    ///
    /// Clients should only have one pending call of this method outstanding at
    /// a time; a second call to this method while a call is already pending
    /// will cause the server to close the channel.
    ///
    /// The first N events returned by this method will be [`Event.existing`],
    /// enumerating all existing N filtering resources, followed by a single
    /// [`Event.idle`] indicating that all existing resources have been sent.
    /// Subsequent calls will immediately return with new events if there is at
    /// least one to be reported, or will otherwise block until an event occurs.
    ///
    /// In order to communicate atomic updates, after the initial state is
    /// provided followed by [`Event.idle`], a sequence of events that occurred
    /// atomically will always be followed by [`Event.end_of_update`],
    /// demarcating the end of the atomic update.
    ///
    /// Note that each non-sentinel event is scoped to a controller; the
    /// [`ControllerId`] is provided along with the event to allow the client to
    /// disambiguate.
    strict Watch() -> (struct {
        events vector<@generated_name("Event") flexible union {
            1: existing @generated_name("ExistingResource") struct {
                controller ControllerId;
                resource Resource;
            };
            2: added @generated_name("AddedResource") struct {
                controller ControllerId;
                resource Resource;
            };
            3: removed @generated_name("RemovedResource") struct {
                controller ControllerId;
                resource ResourceId;
            };
            4: idle Empty;
            5: end_of_update Empty;
        }>:MAX_BATCH_SIZE;
    });
};

/// Provides view-only access to the system's packet filtering state.
@discoverable
closed protocol State {
    /// Initialize a watcher for filtering state.
    strict GetWatcher(resource struct {
        options @generated_name("WatcherOptions") table {};
        request server_end:Watcher;
    });
};