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

using fuchsia.net;

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

/// A protocol for filtering TCP/IP traffic and Network Address Translation.
// TODO(https://fxbug.dev/91503): Modernize/upgrade filter/NAT APIs.
@discoverable
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.
    EnableInterface(struct {
        id fuchsia.net.interface_id;
    }) -> (struct {}) error strict enum {
        NOT_FOUND = 1;
    };

    /// 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.
    DisableInterface(struct {
        id fuchsia.net.interface_id;
    }) -> (struct {}) error strict enum {
        NOT_FOUND = 1;
    };

    /// 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.
    GetRules() -> (struct {
        rules vector<Rule>:MAX_RULES;
        generation uint32;
    }) error strict enum {
        RESERVED = 0;
    };

    /// 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.
    UpdateRules(struct {
        rules vector<Rule>:MAX_RULES;
        generation uint32;
    }) -> (struct {}) 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.
    GetNatRules() -> (struct {
        rules vector<Nat>:MAX_RULES;
        generation uint32;
    }) error strict enum {
        RESERVED = 0;
    };

    /// 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.
    UpdateNatRules(struct {
        rules vector<Nat>:MAX_RULES;
        generation uint32;
    }) -> (struct {}) 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.
    GetRdrRules() -> (struct {
        rules vector<Rdr>:MAX_RULES;
        generation uint32;
    }) error strict enum {
        RESERVED = 0;
    };

    /// 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.
    UpdateRdrRules(struct {
        rules vector<Rdr>:MAX_RULES;
        generation uint32;
    }) -> (struct {}) error strict enum {
        // TODO(https://fxbug.dev/68279): Implement RDR API using gvisor iptables.
        NOT_SUPPORTED = 1;
    };
};