lokinet/llarp/config/definition.hpp

#pragma once

#include <llarp/util/fs.hpp>
#include <llarp/util/str.hpp>

#include <fmt/core.h>

#include <cassert>
#include <functional>
#include <initializer_list>
#include <iostream>
#include <memory>
#include <optional>
#include <set>
#include <sstream>
#include <stdexcept>
#include <type_traits>
#include <unordered_map>
#include <vector>

namespace llarp
{
  namespace config
  {
    namespace flag
    {
      // Base class for the following option flag types
      struct opt
      {};

      struct REQUIRED : opt
      {};
      struct HIDDEN : opt
      {};
      struct MULTIVALUE : opt
      {};
      struct RELAYONLY : opt
      {};
      struct CLIENTONLY : opt
      {};
      struct DEPRECATED : opt
      {};
    }  // namespace flag

    /// Value to pass for an OptionDefinition to indicate that the option is required
    inline constexpr flag::REQUIRED Required{};
    /// Value to pass for an OptionDefinition to indicate that the option should be hidden from the
    /// generate config file if it is unset (and has no comment).  Typically for deprecated, renamed
    /// options that still do something, and for internal dev options that aren't usefully exposed.
    /// (For do-nothing deprecated options use Deprecated instead).
    inline constexpr flag::HIDDEN Hidden{};
    /// Value to pass for an OptionDefinition to indicate that the option takes multiple values
    inline constexpr flag::MULTIVALUE MultiValue{};
    /// Value to pass for an option that should only be set for relay configs. If found in a client
    /// config it be ignored (but will produce a warning).
    inline constexpr flag::RELAYONLY RelayOnly{};
    /// Value to pass for an option that should only be set for client configs. If found in a relay
    /// config it will be ignored (but will produce a warning).
    inline constexpr flag::CLIENTONLY ClientOnly{};
    /// Value to pass for an option that is deprecated and does nothing and should be ignored (with
    /// a deprecation warning) if specified.  Note that Deprecated implies Hidden, and that
    /// {client,relay}-only options in a {relay,client} config are also considered Deprecated.
    inline constexpr flag::DEPRECATED Deprecated{};

    /// Wrapper to specify a default value to an OptionDefinition
    template <typename T>
    struct Default
    {
      T val;
      constexpr explicit Default(T val) : val{std::move(val)}
      {}
    };

    /// Adds one or more comment lines to the option definition.
    struct Comment
    {
      std::vector<std::string> comments;
      explicit Comment(std::initializer_list<std::string> comments) : comments{std::move(comments)}
      {}
    };

    /// A convenience function that returns an acceptor which assigns to a reference.
    ///
    /// Note that this holds on to the reference; it must only be used when this is safe to do. In
    /// particular, a reference to a local variable may be problematic.
    template <typename T>
    auto
    assignment_acceptor(T& ref)
    {
      return [&ref](T arg) { ref = std::move(arg); };
    }

    // C++20 backport:
    template <typename T>
    using remove_cvref_t = std::remove_cv_t<std::remove_reference_t<T>>;

    template <typename T>
    constexpr bool is_default = false;
    template <typename T>
    constexpr bool is_default<Default<T>> = true;
    template <typename U>
    constexpr bool is_default<U&> = is_default<remove_cvref_t<U>>;

    template <typename T>
    constexpr bool is_default_array = false;
    template <typename T, size_t N>
    constexpr bool is_default_array<std::array<Default<T>, N>> = true;
    template <typename U>
    constexpr bool is_default_array<U&> = is_default_array<remove_cvref_t<U>>;

    template <typename T, typename Option>
    constexpr bool is_option = std::is_base_of_v<flag::opt, remove_cvref_t<Option>>
        or std::is_same_v<Comment, Option> or is_default<Option> or is_default_array<Option>
        or std::is_invocable_v<remove_cvref_t<Option>, T>;
  }  // namespace config

  /// A base class for specifying config options and their constraints. The basic to/from string
  /// type functions are provided pure-virtual. The type-aware implementations which implement these
  /// functions are templated classes. One reason for providing a non-templated base class is so
  /// that they can all be mixed into the same containers (albiet as pointers).
  struct OptionDefinitionBase
  {
    template <typename... T>
    OptionDefinitionBase(std::string section_, std::string name_, const T&...)
        : section(std::move(section_))
        , name(std::move(name_))
        , required{(std::is_same_v<T, config::flag::REQUIRED> || ...)}
        , multi_valued{(std::is_same_v<T, config::flag::MULTIVALUE> || ...)}
        , deprecated{(std::is_same_v<T, config::flag::DEPRECATED> || ...)}
        , hidden{deprecated || (std::is_same_v<T, config::flag::HIDDEN> || ...)}
        , relay_only{(std::is_same_v<T, config::flag::RELAYONLY> || ...)}
        , clientOnly{(std::is_same_v<T, config::flag::CLIENTONLY> || ...)}
    {}

    virtual ~OptionDefinitionBase() = default;

    /// Subclasses should provide their default value as a string
    ///
    /// @return the option's default value represented as a string
    virtual std::vector<std::string>
    default_values_as_string() = 0;

    /// Subclasses should parse and store the provided input
    ///
    /// @param input is the string input to interpret
    virtual void
    parse_value(const std::string& input) = 0;

    /// Subclasses should provide the number of values found.
    ///
    /// @return number of values found
    virtual size_t
    get_number_found() const = 0;

    /// Subclasess should write their parsed values as strings.
    ///
    /// @return the option's value(s) as strings
    virtual std::vector<std::string>
    values_as_string() = 0;

    /// Subclassess should call their acceptor, if present. See OptionDefinition for more details.
    ///
    /// @throws if the acceptor throws or the option is required but missing
    virtual void
    try_accept() const = 0;

    std::string section;
    std::string name;
    bool required = false;
    bool multi_valued = false;
    bool deprecated = false;
    bool hidden = false;
    bool relay_only = false;
    bool clientOnly = false;
    // Temporarily holds comments given during construction until the option is actually added to
    // the owning ConfigDefinition.
    std::vector<std::string> comments;
  };

  /// The primary type-aware implementation of OptionDefinitionBase, this templated class allows for
  /// implementations which can use fmt::format for conversion to string and std::istringstream for
  /// input from string.
  ///
  /// Note that types (T) used as template parameters here must be used verbatim when calling
  /// ConfigDefinition::getConfigValue(). Similar types such as uint32_t and int32_t cannot be
  /// mixed.
  template <typename T>
  struct OptionDefinition : public OptionDefinitionBase
  {
    /// Constructor. Arguments are passed directly to OptionDefinitionBase.
    ///
    /// @param defaultValue_ is used in the following situations:
    /// 1) as the return value for getValue() if there is no parsed value and required==false
    /// 2) as the output in default_values_as_string(), used to generate config files
    /// 3) as the output in valueAsString(), used to generate config files
    ///
    /// @param opts - 0 or more of config::Required, config::Hidden, config::Default{...}, etc.
    /// tagged options or an invocable acceptor validate and internalize input (e.g. copy it for
    /// runtime use). The acceptor should throw an exception with a useful message if it is not
    /// acceptable.  Parameters may be passed in any order.
    template <
        typename... Options,
        std::enable_if_t<(config::is_option<T, Options> && ...), int> = 0>
    OptionDefinition(std::string section_, std::string name_, Options&&... opts)
        : OptionDefinitionBase(section_, name_, opts...)
    {
      constexpr bool has_default =
          ((config::is_default_array<Options> || config::is_default<Options>) || ...);
      constexpr bool has_required =
          (std::is_same_v<config::remove_cvref_t<Options>, config::flag::REQUIRED> || ...);
      constexpr bool has_hidden =
          (std::is_same_v<config::remove_cvref_t<Options>, config::flag::HIDDEN> || ...);
      static_assert(
          not(has_default and has_required), "Default{...} and Required are mutually exclusive");
      static_assert(not(has_hidden and has_required), "Hidden and Required are mutually exclusive");

      (extract_default(std::forward<Options>(opts)), ...);
      (extract_acceptor(std::forward<Options>(opts)), ...);
      (extract_comments(std::forward<Options>(opts)), ...);
    }

    /// Extracts a default value from an config::Default<U> or an array of defaults (for
    /// multi-valued options with multi-value default); ignores anything else.
    template <typename U>
    void
    extract_default(U&& defaultValue_)
    {
      if constexpr (config::is_default_array<U>)
      {
        if (!multi_valued)
          throw std::logic_error{"Array config defaults require multiValue mode"};

        default_values.clear();
        default_values.reserve(defaultValue_.size());
        for (const auto& def : defaultValue_)
          default_values.push_back(def.val);
      }
      else if constexpr (config::is_default<U>)
      {
        static_assert(
            std::is_convertible_v<decltype(std::forward<U>(defaultValue_).val), T>,
            "Cannot convert given llarp::config::Default to the required value type");
        default_values = {std::forward<U>(defaultValue_).val};
      }
    }

    /// Extracts an acceptor (i.e. something callable with a `T`) from options; ignores anything
    /// that isn't callable.
    template <typename U>
    void
    extract_acceptor(U&& acceptor_)
    {
      if constexpr (std::is_invocable_v<U, T>)
        acceptor = std::forward<U>(acceptor_);
    }

    /// Extracts option Comments and forwards them addOptionComments.
    template <typename U>
    void
    extract_comments(U&& comment)
    {
      if constexpr (std::is_same_v<config::remove_cvref_t<U>, config::Comment>)
        comments = std::forward<U>(comment).comments;
    }

    /// Returns the first parsed value, if available. Otherwise, provides the (first) default value
    /// if the option is not required. Otherwise, returns an empty optional.
    ///
    /// @return an optional with the parsed value, the (first) default value, or no value.
    std::optional<T>
    get_value() const
    {
      if (parsed_values.empty())
      {
        if (required || default_values.empty())
          return std::nullopt;
        return default_values.front();
      }
      return parsed_values.front();
    }

    /// Returns the number of values found.
    ///
    /// @return number of values found
    size_t
    get_number_found() const override
    {
      return parsed_values.size();
    }

    std::vector<std::string>
    default_values_as_string() override
    {
      if (default_values.empty())
        return {};
      if constexpr (std::is_same_v<fs::path, T>)
        return {{default_values.front().u8string()}};
      else
      {
        std::vector<std::string> def_strs;
        def_strs.reserve(default_values.size());
        for (const auto& v : default_values)
        {
          if constexpr (std::is_same_v<bool, T>)
            def_strs.push_back(fmt::format("{}", (bool)v));
          else
            def_strs.push_back(fmt::format("{}", v));
        }
        return def_strs;
      }
    }

    void
    parse_value(const std::string& input) override
    {
      if (not multi_valued and parsed_values.size() > 0)
      {
        throw std::invalid_argument{fmt::format("duplicate value for {}", name)};
      }

      parsed_values.emplace_back(from_string(input));
    }

    T
    from_string(const std::string& input)
    {
      if constexpr (std::is_same_v<T, std::string>)
      {
        return input;
      }
      else
      {
        std::istringstream iss(input);
        T t;
        iss >> t;
        if (iss.fail())
          throw std::invalid_argument{fmt::format("{} is not a valid {}", input, typeid(T).name())};
        return t;
      }
    }

    std::vector<std::string>
    values_as_string() override
    {
      if (parsed_values.empty())
        return {};
      std::vector<std::string> result;
      result.reserve(parsed_values.size());
      for (const auto& v : parsed_values)
      {
        if constexpr (std::is_same_v<bool, T>)
          result.push_back(fmt::format("{}", (bool)v));
        else
          result.push_back(fmt::format("{}", v));
      }
      return result;
    }

    /// Attempts to call the acceptor function, if present. This function may throw if the value
    /// is not acceptable. Additionally, try_accept should not be called if the option is required
    /// and no value has been provided.
    ///
    /// @throws if required and no value present or if the acceptor throws
    void
    try_accept() const override
    {
      if (required and parsed_values.empty())
      {
        throw std::runtime_error{fmt::format(
            "cannot call try_accept() on [{}]:{} when required but no value available",
            section,
            name)};
      }

      if (acceptor)
      {
        if (multi_valued)
        {
          // add default value in multi value mode
          if (parsed_values.empty() and not default_values.empty())
            for (const auto& v : default_values)
              acceptor(v);

          for (auto value : parsed_values)
          {
            acceptor(value);
          }
        }
        else
        {
          auto maybe = get_value();
          if (maybe)
            acceptor(*maybe);
        }
      }
    }

    std::vector<T> default_values;
    std::vector<T> parsed_values;
    std::function<void(T)> acceptor;
  };

  /// Specialization for bool types. We don't want to use stringstream parsing in this
  /// case because we want to accept "truthy" and "falsy" string values (e.g. "off" == false)
  template <>
  bool
  OptionDefinition<bool>::from_string(const std::string& input);

  using UndeclaredValueHandler =
      std::function<void(std::string_view section, std::string_view name, std::string_view value)>;

  // map of k:v pairs
  using DefinitionMap = std::unordered_map<std::string, std::unique_ptr<OptionDefinitionBase>>;

  // map of section-name to map-of-definitions
  using SectionMap = std::unordered_map<std::string, DefinitionMap>;

  /// A ConfigDefinition holds an ordered set of OptionDefinitions defining the allowable values
  /// and their constraints (specified through calls to defineOption()).
  ///
  /// The layout and grouping of the config options are modelled after the INI file format; each
  /// option has a name and is grouped under a section. Duplicate option names are allowed only if
  /// they exist in a different section. The ConfigDefinition can be serialized in the INI file
  /// format using the generateINIConfig() function.
  ///
  /// Configured values (e.g. those encountered when parsing a file) can be provided through calls
  /// to addConfigValue(). These take a std::string as a value, which is automatically parsed.
  ///
  /// The ConfigDefinition can be used to print out a full config string (or file), including
  /// fields with defaults and optionally fields which have a specified value (values provided
  /// through calls to addConfigValue()).
  struct ConfigDefinition
  {
    explicit ConfigDefinition(bool relay) : relay{relay}
    {}

    /// Specify the parameters and type of a configuration option. The parameters are members of
    /// OptionDefinitionBase; the type is inferred from OptionDefinition's template parameter T.
    ///
    /// This function should be called for every option that this Configuration supports, and
    /// should be done before any other interactions involving that option.
    ///
    /// @param def should be a unique_ptr to a valid subclass of OptionDefinitionBase
    /// @return `*this` for chaining calls
    /// @throws std::invalid_argument if the option already exists
    ConfigDefinition&
    define_option(std::unique_ptr<OptionDefinitionBase> def);

    /// Convenience function which calls defineOption with a OptionDefinition of the specified
    /// type and with parameters passed through to OptionDefinition's constructor.
    template <typename T, typename... Params>
    ConfigDefinition&
    define_option(Params&&... args)
    {
      return define_option(std::make_unique<OptionDefinition<T>>(std::forward<Params>(args)...));
    }

    /// Specify a config value for the given section and name. The value should be a valid string
    /// representing the type used by the option (e.g. the type provided when defineOption() was
    /// called).
    ///
    /// If the specified option doesn't exist, an exception will be thrown. Otherwise, the
    /// option's parse_value() will be invoked, and should throw an exception if the string can't
    /// be parsed.
    ///
    /// @param section is the section this value resides in
    /// @param name is the name of the value
    /// @return `*this` for chaining calls
    /// @throws if the option doesn't exist or the provided string isn't parseable
    ConfigDefinition&
    add_config_value(std::string_view section, std::string_view name, std::string_view value);

    /// Get a config value. If the value hasn't been provided but a default has, the default will
    /// be returned. If no value and no default is provided, an empty optional will be returned.
    ///
    /// The type T should exactly match that provided by the definition; it is not sufficient for
    /// one type to be a valid substitution for the other.
    ///
    /// @param section is the section this value resides in
    /// @param name is the name of the value
    /// @return an optional providing the configured value, the default, or empty
    /// @throws std::invalid_argument if there is no such config option or the wrong type T was
    //          provided
    template <typename T>
    std::optional<T>
    get_config_value(std::string_view section, std::string_view name)
    {
      std::unique_ptr<OptionDefinitionBase>& definition = lookup_definition_or_throw(section, name);

      auto derived = dynamic_cast<const OptionDefinition<T>*>(definition.get());
      if (not derived)
        throw std::invalid_argument{
            fmt::format("{} is the incorrect type for [{}]:{}", typeid(T).name(), section, name)};

      return derived->getValue();
    }

    /// Add an "undeclared" handler for the given section. This is a handler that will be called
    /// whenever a k:v pair is found that doesn't match a provided definition.
    ///
    /// Any exception thrown by the handler will progagate back through the call to
    /// addConfigValue().
    ///
    /// @param section is the section for which any undeclared values will invoke the provided
    ///        handler
    /// @param handler
    /// @throws if there is already a handler for this section
    void
    add_undeclared_handler(const std::string& section, UndeclaredValueHandler handler);

    /// Removes an "undeclared" handler for the given section.
    ///
    /// @param section is the section which we want to remove the handler for
    void
    remove_undeclared_handler(const std::string& section);

    /// Validate that all required fields are present.
    ///
    /// @throws std::invalid_argument if configuration constraints are not met
    void
    validate_required_fields();

    /// Accept all options. This will call the acceptor (if present) on each option. Note that
    /// this should only be called if all required fields are present (that is,
    /// validateRequiredFields() has been or could be called without throwing).
    ///
    /// @throws if any option's acceptor throws
    void
    accept_all_options();

    /// validates and accept all parsed options
    inline void
    process()
    {
      validate_required_fields();
      accept_all_options();
    }

    /// Add comments for a given section. Comments are replayed in-order during config file
    /// generation. A proper comment prefix will automatically be applied, and the entire comment
    /// will otherwise be used verbatim (no automatic line separation, etc.).
    ///
    /// @param section
    /// @param comment
    void
    add_section_comments(const std::string& section, std::vector<std::string> comments);

    /// Add comments for a given option. Similar to addSectionComment, but applies to a specific
    /// [section]:name pair.
    ///
    /// @param section
    /// @param name
    /// @param comment
    void
    add_option_comments(
        const std::string& section, const std::string& name, std::vector<std::string> comments);

    /// Generate a config string from the current config definition, optionally using overridden
    /// values. The generated config will preserve insertion order of both sections and their
    /// definitions.
    ///
    /// Definitions which are required or have an overriden value (and useValues == true) will be
    /// written normally. Otherwise, they will be written commented-out in order to provide a
    /// complete documentation of the configuration file.
    ///
    /// @param useValues specifies whether we use specified values (e.g. those from calls to
    ///        addConfigValue()) or only definitions
    /// @return a string containing the config in INI format
    std::string
    generate_ini_config(bool useValues = false);

   private:
    // If true skip client-only options; if false skip relay-only options.
    bool relay;

    std::unique_ptr<OptionDefinitionBase>&
    lookup_definition_or_throw(std::string_view section, std::string_view name);
    const std::unique_ptr<OptionDefinitionBase>&
    lookup_definition_or_throw(std::string_view section, std::string_view name) const;

    using SectionVisitor = std::function<void(const std::string&, const DefinitionMap&)>;
    void
    visit_sections(SectionVisitor visitor) const;

    using DefVisitor =
        std::function<void(const std::string&, const std::unique_ptr<OptionDefinitionBase>&)>;
    void
    visit_definitions(const std::string& section, DefVisitor visitor) const;

    SectionMap definitions;

    std::unordered_map<std::string, UndeclaredValueHandler> undeclared_handlers;

    // track insertion order. the vector<string>s are ordered list of section/option names.
    std::vector<std::string> section_ordering;
    std::unordered_map<std::string, std::vector<std::string>> definition_ordering;

    // comments for config file generation
    using CommentList = std::vector<std::string>;
    using CommentsMap = std::unordered_map<std::string, CommentList>;
    CommentsMap section_comments;
    std::unordered_map<std::string, CommentsMap> definition_comments;
  };

}  // namespace llarp