// Copyright (C) 2015-2026 Internet Systems Consortium, Inc. ("ISC")

//

// This Source Code Form is subject to the terms of the Mozilla Public

// License, v. 2.0. If a copy of the MPL was not distributed with this

// file, You can obtain one at http://mozilla.org/MPL/2.0/.

#ifndef CLIENT_CLASS_DEF_H

#define CLIENT_CLASS_DEF_H

#include <cc/cfg_to_element.h>

#include <cc/stamped_element.h>

#include <cc/user_context.h>

#include <dhcpsrv/cfg_option.h>

#include <dhcpsrv/cfg_option_def.h>

#include <eval/token.h>

#include <exceptions/exceptions.h>

#include <util/triplet.h>

#include <util/optional.h>

#include <string>

#include <unordered_map>

#include <list>

#include <vector>

/// @file client_class_def.h

///

/// @brief Defines classes for storing client class definitions

///

/// The file defines the class, ClientClassDef, which houses the

/// information for single client class such as the class name, the

/// logical expression used to identify members of the class, and options

/// that may be attributed to class members.

///

/// In addition it defines a container class, ClientClassDictionary, which

/// is houses class definitions keyed by class name.

///

namespace isc {

namespace dhcp {

/// @brief Error that occurs when an attempt is made to add a duplicate class

/// to a class dictionary.

class DuplicateClientClassDef : public isc::Exception {

public:

    DuplicateClientClassDef(const char* file, size_t line, const char* what)

        : isc::Exception(file, line, what) {}

};

/// @brief Embodies a single client class definition

class ClientClassDef : public data::UserContext,

                       public data::CfgToElement,

                       public data::StampedElement {

public:

    /// @brief Constructor

    ///

    /// @param name Name to assign to this class

    /// @param match_expr Expression the class will use to determine membership

    /// @param options Collection of options members should be given

    ClientClassDef(const std::string& name, const ExpressionPtr& match_expr,

                   const CfgOptionPtr& options = CfgOptionPtr());

    /// Copy constructor

    ClientClassDef(const ClientClassDef& rhs);

    /// @brief Destructor

    virtual ~ClientClassDef();

    /// @brief Fetches the class's name

    std::string getName() const;

    /// @brief Sets the class's name

    ///

    /// @param name the name to assign the class

    void setName(const std::string& name);

    /// @brief Fetches the class's match expression

    const ExpressionPtr& getMatchExpr() const;

    /// @brief Sets the class's match expression

    ///

    /// @param match_expr the expression to assign the class

    void setMatchExpr(const ExpressionPtr& match_expr);

    /// @brief Fetches the class's original match expression

    std::string getTest() const;

    /// @brief Sets the class's original match expression

    ///

    /// @param test the original expression to assign the class

    void setTest(const std::string& test);

    /// @brief Fetches the only if additional flag

    bool getAdditional() const;

    /// @brief Sets the only if additional flag

    ///

    /// @param additional the value of the only if additional flag

    void setAdditional(bool additional);

    /// @brief Fetches the depend on known flag aka use host flag

    bool getDependOnKnown() const;

    /// @brief Sets the depend on known flag aka use host flag

    ///

    /// @param depend_on_known the value of the depend on known flag

    void setDependOnKnown(bool depend_on_known);

    /// @brief Fetches the class's option definitions

    const CfgOptionDefPtr& getCfgOptionDef() const;

    /// @brief Sets the class's option definition collection

    ///

    /// @param cfg_option_def the option definitions to assign the class

    void setCfgOptionDef(const CfgOptionDefPtr& cfg_option_def);

    /// @brief Fetches the class's option collection

    const CfgOptionPtr& getCfgOption() const;

    /// @brief Sets the class's option collection

    ///

    /// @param cfg_option the option collection to assign the class

    void setCfgOption(const CfgOptionPtr& cfg_option);

    /// @brief Checks direct dependency.

    ///

    /// @param name The client class name.

    ///

    /// @return true if the definition depends on the class name, false if not.

    bool dependOnClass(const std::string& name) const;

    /// @brief Compares two @c ClientClassDef objects for equality.

    ///

    /// @param other Other client class definition to compare to.

    ///

    /// @return true if objects are equal, false otherwise.

    bool equals(const ClientClassDef& other) const;

    /// @brief Equality operator.

    ///

    /// @param other Other client class definition to compare to.

    ///

    /// @return true if the definitions equal, false otherwise.

    bool operator==(const ClientClassDef& other) const {

        return (equals(other));

    }

    /// @brief Inequality operator.

    ///

    /// @param other Other client class definition to compare to.

    ///

    /// @return true if the definitions are not equal, false otherwise.

    bool operator!=(const ClientClassDef& other) const {

        return (!(equals(other)));

    }

    /// @brief Provides a convenient text representation of the class

    friend std::ostream& operator<<(std::ostream& os, const ClientClassDef& x);

    /// @brief returns next-server value

    /// @return next-server value

    const asiolink::IOAddress& getNextServer() const {

        return (next_server_);

    }

    /// @brief sets the next-server value

    ///

    /// @param addr the value to be set

    void setNextServer(const asiolink::IOAddress& addr) {

        next_server_ = addr;

    }

    /// @brief sets the server-name value

    ///

    /// @param sname the value to be set

    void setSname(const std::string& sname) {

        sname_ = sname;

    }

    /// @brief returns server-hostname value

    /// @return the vector that contains server-hostname (may be empty if not defined)

    const std::string& getSname() const {

        return (sname_);

    }

    /// @brief sets the boot-file-name value

    ///

    /// @param filename the value to be set

    void setFilename(const std::string& filename) {

        filename_ = filename;

    }

    /// @brief returns boot-file-name value

    /// @return the vector that contains boot-file-name (may be empty if not defined)

    const std::string& getFilename() const {

        return (filename_);

    }

    /// @brief Return valid-lifetime value

    ///

    /// @return a triplet containing the valid lifetime.

    util::Triplet<uint32_t> getValid() const {

        return (valid_);

    }

    /// @brief Sets new valid lifetime

    ///

    /// @param valid New valid lifetime in seconds.

    void setValid(const util::Triplet<uint32_t>& valid) {

        valid_ = valid;

    }

    /// @brief Return preferred-lifetime value

    ///

    /// @return a triplet containing the preferred lifetime.

    util::Triplet<uint32_t> getPreferred() const {

        return (preferred_);

    }

    /// @brief Sets new preferred lifetime

    ///

    /// @param preferred New valid lifetime in seconds.

    void setPreferred(const util::Triplet<uint32_t>& preferred) {

        preferred_ = preferred;

    }

    /// @brief Sets offer lifetime for the class.

    ///

    /// @param offer_lft the offer lifetime assigned to the class (may be empty if not defined)

    void setOfferLft(const util::Optional<uint32_t>& offer_lft) {

        offer_lft_ = offer_lft;

    }

    /// @brief Returns offer lifetime for the class.

    ///

    /// @return offer lifetime value

    util::Optional<uint32_t> getOfferLft() const {

        return (offer_lft_);

    }

    /// @brief Test method which checks if the packet belongs to the class

    ///

    /// If the packet belongs to the class, the class is added to the packet.

    ///

    /// @param pkt The packet checked if it belongs to the class.

    /// @param expr_ptr Expression the class will use to determine membership

    virtual void test(PktPtr pkt, const ExpressionPtr& expr_ptr);

    /// @brief Unparse a configuration object

    ///

    /// @return a pointer to unparsed configuration

    virtual isc::data::ElementPtr toElement() const;

private:

    /// @brief Unique text identifier by which this class is known.

    std::string name_;

    /// @brief The logical expression which determines membership in

    /// this class.

    ExpressionPtr match_expr_;

    /// @brief The original expression which determines membership in

    /// this class.

    std::string test_;

    /// @brief The only-in-additional-list flag: when false (the default) membership

    /// is determined during classification so is available for instance for

    /// subnet selection. When true, membership is evaluated only when additional

    /// and is usable only for option configuration.

    bool additional_;

    /// @brief The depend on known aka use host flag: when false (the default),

    /// the additional flag is false and the class has a match expression

    /// the expression is evaluated in the first pass. When true and the

    /// two other conditions stand the expression is evaluated later when

    /// the host reservation membership was determined.

    /// This flag is set to true during the match expression parsing if

    /// direct or indirect dependency on the builtin [UN]KNOWN classes is

    /// detected.

    bool depend_on_known_;

    /// @brief The option definition configuration for this class

    CfgOptionDefPtr cfg_option_def_;

    /// @brief The option data configuration for this class

    CfgOptionPtr cfg_option_;

    /// @brief Next server field

    /// If set by the next-server parameter, this value will be set

    /// in the siaddr field of the DHCPv4 packet.

    asiolink::IOAddress next_server_;

    /// @brief server-hostname

    /// If set by the server-hostname parameter, this value will be

    /// set in the sname field of the DHCPv4 packet.

    /// This can be up to 64 octets long.

    std::string sname_;

    /// @brief boot-file-name

    /// If set by the boot-file-name parameter, this value will be

    /// set in the file field of the DHCPv4 packet.

    /// This can be up to 128 octets long.

    std::string filename_;

    /// @brief a Triplet (min/default/max) holding allowed valid lifetime values

    util::Triplet<uint32_t> valid_;

    /// @brief a Triplet (min/default/max) holding allowed preferred lifetime values

    util::Triplet<uint32_t> preferred_;

    /// @brief offer lifetime for this class (V4 only).

    util::Optional<uint32_t> offer_lft_;

};

class TemplateClientClassDef : public ClientClassDef {

public:

    /// @brief Constructor

    ///

    /// @param name Name to assign to this class

    /// @param match_expr Expression the class will use to determine membership

    /// @param options Collection of options members should be given

    TemplateClientClassDef(const std::string& name, const ExpressionPtr& match_expr,

                           const CfgOptionPtr& options = CfgOptionPtr());

    /// @brief Test method which checks if the packet belongs to the class

    ///

    /// If the packet belongs to the class, the class is added to the packet.

    ///

    /// @param pkt The packet checked if it belongs to the class.

    /// @param expr_ptr Expression the class will use to determine membership

    virtual void test(PktPtr pkt, const ExpressionPtr& expr_ptr) override;

    /// @brief Unparse a configuration object

    ///

    /// @return a pointer to unparsed configuration

    virtual isc::data::ElementPtr toElement() const override;

    /// @brief This is a prefix added to the spawned class name

    ///

    /// If incoming packet is associated with the template class, the name of

    /// generated spawned class is prepended with this prefix.

    /// For example, a packet that associates with the template class "FOO" by

    /// evaluating the template class expression to BAR will cause the packet to

    /// be assigned to class SPAWN_FOO_BAR.

    static const std::string SPAWN_CLASS_PREFIX;

};

/// @brief a pointer to an ClientClassDef

typedef boost::shared_ptr<ClientClassDef> ClientClassDefPtr;

/// @brief Defines a map of ClientClassDef's, keyed by the class name.

typedef std::unordered_map<std::string, ClientClassDefPtr> ClientClassDefMap;

/// @brief Defines a pointer to a ClientClassDefMap

typedef boost::shared_ptr<ClientClassDefMap> ClientClassDefMapPtr;

/// @brief Defines a list of ClientClassDefPtr's, using insert order.

typedef std::vector<ClientClassDefPtr> ClientClassDefList;

/// @brief Defines a pointer to a ClientClassDefList

typedef boost::shared_ptr<ClientClassDefList> ClientClassDefListPtr;

/// @brief Maintains a list of ClientClassDef's

class ClientClassDictionary : public isc::data::CfgToElement {

public:

    /// @brief Constructor

    ClientClassDictionary();

    ClientClassDictionary(const ClientClassDictionary& rhs);

    /// @brief Destructor

    ~ClientClassDictionary();

    /// @brief Adds a new class to the list

    ///

    /// @param name Name to assign to this class

    /// @param match_expr Expression the class will use to determine membership

    /// @param test Original version of match_expr

    /// @param additional Original value of the only if additional flag

    /// @param depend_on_known Using host so will be evaluated later

    /// @param options Collection of options members should be given

    /// @param defs Option definitions (optional)

    /// @param user_context User context (optional)

    /// @param next_server next-server value for this class (optional)

    /// @param sname server-name value for this class (optional)

    /// @param filename boot-file-name value for this class (optional)

    /// @param valid valid-lifetime triplet (optional)

    /// @param preferred preferred-lifetime triplet (optional)

    /// @param is_template true if class is a template class. Defaults to false.

    /// @param offer_lft the offer lifetime assigned to the class (may be empty if not defined)

    ///

    /// @throw DuplicateClientClassDef if class already exists within the

    /// dictionary.  See @ref dhcp::ClientClassDef::ClientClassDef() for

    /// others.

    void addClass(const std::string& name, const ExpressionPtr& match_expr,

                  const std::string& test, bool additional, bool depend_on_known,

                  const CfgOptionPtr& options,

                  CfgOptionDefPtr defs = CfgOptionDefPtr(),

                  isc::data::ConstElementPtr user_context = isc::data::ConstElementPtr(),

                  asiolink::IOAddress next_server = asiolink::IOAddress("0.0.0.0"),

                  const std::string& sname = std::string(),

                  const std::string& filename = std::string(),

                  const util::Triplet<uint32_t>& valid = util::Triplet<uint32_t>(),

                  const util::Triplet<uint32_t>& preferred = util::Triplet<uint32_t>(),

                  bool is_template = false,

                  const util::Optional<uint32_t>& offer_lft = util::Optional<uint32_t>());

    /// @brief Adds a new class to the list

    ///

    /// @param class_def pointer to class definition to add

    ///

    /// @throw DuplicateClientClassDef if class already exists within the

    /// dictionary, BadValue if the pointer is empty.

    void addClass(const ClientClassDefPtr& class_def);

    /// @brief Fetches the class definition for a given class name

    ///

    /// @param name the name of the desired class

    ///

    /// @return ClientClassDefPtr to the desired class if found, or

    /// an empty pointer if not.

    ClientClassDefPtr findClass(const std::string& name) const;

    /// @brief Removes a given class definition from the dictionary

    ///

    /// Removes the class definition from the map if it exists, otherwise

    /// no harm, no foul.

    ///

    /// @param name the name of the class to remove

    void removeClass(const std::string& name);

    /// @brief Removes a client class by id.

    ///

    /// @param id class id.

    void removeClass(const uint64_t id);

    /// @brief Fetches the dictionary's list of classes

    ///

    /// @return ClientClassDefListPtr to the list of classes

    const ClientClassDefListPtr& getClasses() const;

    /// @brief Checks if the class dictionary is empty.

    ///

    /// @return true if there are no classes, false otherwise.

    bool empty() const;

    /// @brief Checks direct dependency.

    ///

    /// @param name The client class name.

    /// @param [out] dependent_class Reference to a variable where the

    /// name of the first class depending on the checked class is set.

    ///

    /// @return true if a definition depends on the class name, false if none.

    bool dependOnClass(const std::string& name, std::string& dependent_class) const;

    /// @brief Compares two @c ClientClassDictionary objects for equality.

    ///

    /// @param other Other client class definition to compare to.

    ///

    /// @return true if descriptors equal, false otherwise.

    bool equals(const ClientClassDictionary& other) const;

    /// @brief Iterates over the classes in the dictionary and ensures that

    /// that match expressions are initialized.

    ///

    /// @param family Class universe, e.g. AF_INET or AF_INET6.

    void initMatchExpr(uint16_t family);

    /// @brief Iterates over the classes in the dictionary and recreates

    /// the options.

    ///

    /// @param cfg_option_def set of option definitions to use.

    void createOptions(const CfgOptionDefPtr& cfg_option_def);

    /// @brief Iterates over the classes in the dictionary and encapsulates

    /// suboptions.

    void encapsulateOptions() const;

    /// @brief Equality operator.

    ///

    /// @param other Other client class dictionary to compare to.

    ///

    /// @return true if the dictionaries are equal, false otherwise.

    bool operator==(const ClientClassDictionary& other) const {

        return (equals(other));

    }

    /// @brief Inequality operator.

    ///

    /// @param other Other client class dictionary to compare to.

    ///

    /// @return true if the dictionaries are not equal, false otherwise.

    bool operator!=(const ClientClassDictionary& other) const {

        return (!equals(other));

    }

    /// @brief Copy assignment operator.

    ///

    /// @param rhs Client class dictionary to be copied from.

    /// @return Instance copy.

    ClientClassDictionary& operator=(const ClientClassDictionary& rhs);

    /// @brief Unparse a configuration object

    ///

    /// @return a pointer to unparsed configuration

    virtual isc::data::ElementPtr toElement() const;

private:

    /// @brief Map of the class definitions

    ClientClassDefMapPtr map_;

    /// @brief List of the class definitions

    ClientClassDefListPtr list_;

};

/// @brief Defines a pointer to a ClientClassDictionary

typedef boost::shared_ptr<ClientClassDictionary> ClientClassDictionaryPtr;

/// @brief List of built-in client class names.

/// i.e. ALL, KNOWN, UNKNOWN and BOOTP but not DROP nor REJECT.

extern std::list<std::string> builtinNames;

/// @brief List of built-in client class prefixes

/// i.e. VENDOR_CLASS_, HA_, AFTER_ and EXTERNAL_.

extern std::list<std::string> builtinPrefixes;

/// @brief Check if a client class name is builtin.

///

/// @param client_class A client class name to look for.

/// @return true if built-in, false if not.

bool isClientClassBuiltIn(const ClientClass& client_class);

/// @brief Check if a client class name is already defined,

/// i.e. is built-in or in the dictionary,

///

/// The reference to depend on known flag is set to true if the class

/// is KNOWN or UNKNOWN (direct dependency) or has this flag set

/// (indirect dependency).

///

/// @param class_dictionary A class dictionary where to look for.

/// @param depend_on_known A reference to depend on known flag.

/// @param client_class A client class name to look for.

/// @return true if defined or built-in, false if not.

bool isClientClassDefined(ClientClassDictionaryPtr& class_dictionary,

                          bool& depend_on_known,

                          const ClientClass& client_class);

} // namespace isc::dhcp

} // namespace isc

#endif // CLIENT_CLASS_DEF_H