// Copyright 2018 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.deprecated;

using fuchsia.net;

/// The maximum number of rules.
const MAX_RULES uint32 = 128;

/// The possible errors that result from enabling/disabling filtering on an
/// interface.
type EnableDisableInterfaceError = strict enum {
    NOT_FOUND = 1;
};

/// A protocol for filtering TCP/IP traffic and Network Address Translation.
// TODO(https://fxbug.dev/42173074): Modernize/upgrade filter/NAT APIs.
@discoverable
closed protocol Filter {
    /// Enable the filter on a specific interface.
    ///
    /// The filter is disabled by default. If the filter is already enabled,
    /// no error is returned.
    ///
    /// + request `id` The id of the network interface.
    /// * error Reports `NOT_FOUND` if `id` is not a valid interface.
    strict EnableInterface(struct {
        id fuchsia.net.InterfaceId;
    }) -> () error EnableDisableInterfaceError;

    /// Disable the filter on a specific interface.
    ///
    /// The filter is disabled by default. If the filter is already disabled,
    /// no error is returned.
    ///
    /// + request `id` The id of the network interface.
    /// * error Reports `NOT_FOUND` if `id` is not a valid interface.
    strict DisableInterface(struct {
        id fuchsia.net.InterfaceId;
    }) -> () error EnableDisableInterfaceError;

    /// GetRules gets the current rules. They do not include NAT or RDR rules.
    /// (use GetNatRules or GetRdrRules instead).
    ///
    /// - response `rules` The current filter rules.
    /// - response `generation` The generation number associated with the current
    ///   rules.
    strict GetRules() -> (struct {
        rules vector<Rule>:MAX_RULES;
        generation uint32;
    });

    /// UpdateRules updates the current rules. It does not update NAT or RDR rules
    /// (use UpdateNatRules or UpdateRdrRules instead).
    ///
    /// UpdateRules takes a generation number that is previously returned from
    /// GetRules. The generation number has to be up-to-date, i.e. it has to
    /// match with the one associated with the current rules. The service will
    /// assign a new generation number to the new rules.
    ///
    /// + request `rules` The new filter rules to install.
    /// + request `generation` The generation number previously returned from
    ///   GetRules.
    /// * error Reports `GENERATION_MISMATCH` if `generation` is not the
    ///   generation number for the current rules.
    /// * error Reports `BAD_RULE` if `rules` are not valid.
    strict UpdateRules(struct {
        rules vector<Rule>:MAX_RULES;
        generation uint32;
    }) -> () error strict enum {
        GENERATION_MISMATCH = 1;
        BAD_RULE = 2;
    };

    /// GetNatRules gets the current NAT rules.
    ///
    /// - response `rules` The current NAT rules.
    /// - response `generation` The generation number associated with the current
    ///   NAT rules.
    strict GetNatRules() -> (struct {
        rules vector<Nat>:MAX_RULES;
        generation uint32;
    });

    /// UpdateNatRules updates the current NAT rules.
    ///
    /// UpdateNatRules takes a generation number that is previously returned from
    /// GetRules. The generation number has to be up-to-date, i.e. it has to
    /// match with the one associated with the current NAT rules. The service will
    /// assign a new generation number to the new NAT rules.
    ///
    /// + request `rules` The new NAT rules to install.
    /// + request `generation` The generation number previously returned from
    ///   GetNATRules.
    /// * error Reports `GENERATION_MISMATCH` if `generation` is not the
    ///   generation number for the current rules.
    /// * error Reports `BAD_RULE` if `rules` are not valid.
    strict UpdateNatRules(struct {
        rules vector<Nat>:MAX_RULES;
        generation uint32;
    }) -> () error strict enum {
        GENERATION_MISMATCH = 1;
        BAD_RULE = 2;
    };

    /// GetRdrRules gets the current RDR rules.
    ///
    /// - response `rules` The current RDR rules.
    /// - response `generation` The generation number associated with the current
    ///   RDR rules.
    strict GetRdrRules() -> (struct {
        rules vector<Rdr>:MAX_RULES;
        generation uint32;
    });

    /// UpdateRdrRules updates the previous RDR rules with new rules.
    ///
    /// UpdateRdrRules takes a generation number that is previously returned from
    /// GetRules. The generation number has to be up-to-date, i.e. it has to
    /// match with the one associated with the current RDR rules. The service will
    /// assign a new generation number to the new RDR rules.
    ///
    /// + request `rules` The new RDR rules to install.
    /// + request `generation` The generation number previously returned from
    ///   GetRDRRules.
    /// * error Reports `NOT_SUPPORTED` if the operation is not supported.
    strict UpdateRdrRules(struct {
        rules vector<Rdr>:MAX_RULES;
        generation uint32;
    }) -> () error strict enum {
        // TODO(https://fxbug.dev/42147284): Implement RDR API using gvisor iptables.
        NOT_SUPPORTED = 1;
    };

    /// No-op method that allows checking for presence.
    ///
    /// It's not currently possible for a client with an optionally-provided
    /// protocol to check whether there's someone on the other end without
    /// making a FIDL call (https://fxbug.dev/296283299). This method provides a
    /// workaround by giving a client a two-way method that it can call to check
    /// for liveness.
    strict CheckPresence() -> ();
};