snapshot.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/dynamic_config/snapshot.hpp
/// @brief @copybrief dynamic_config::Snapshot
 
#include <cstdint>
#include <string>
#include <type_traits>
 
#include <userver/compiler/impl/lifetime.hpp>
#include <userver/dynamic_config/impl/snapshot.hpp>
#include <userver/dynamic_config/impl/to_json.hpp>
#include <userver/dynamic_config/registered_config_meta.hpp>
#include <userver/formats/json_fwd.hpp>
#include <userver/utils/fast_pimpl.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace dynamic_config {
 
/// A strong typedef for usage in dynamic_config::Key constructors.
struct DefaultAsJsonString final {
    constexpr explicit DefaultAsJsonString(std::string_view json_string);
 
    std::string_view json_string;
};
 
/// A config name-value pair for usage in dynamic_config::Key constructors.
struct ConfigDefault final {
    template <typename T>
    ConfigDefault(std::string_view name, const T& value);
 
    ConfigDefault(std::string_view name, DefaultAsJsonString default_json);
 
    std::string_view name;
    std::string default_json;
};
 
/// A tag type for usage in dynamic_config::Key constructors.
struct ConstantConfig final {
    constexpr explicit ConstantConfig() = default;
};
 
/// @brief A config key is a unique identifier for a config variable
/// @snippet core/src/dynamic_config/config_test.cpp key bool
template <typename Variable>
class Key final {
public:
    /// The type of the parsed config variable.
    using VariableType = Variable;
 
    using JsonParser = Variable (*)(const formats::json::Value&);
    using DocsMapParser = Variable (*)(const DocsMap&);
 
    /// @brief The constructor for a trivial `VariableType`, e.g. `bool`, integer,
    /// `double`, `string`. The default is passed by value.
    ///
    /// Usage example:
    /// @snippet core/src/dynamic_config/config_test.cpp key bool
    Key(std::string_view name, const VariableType& default_value);
 
    /// @brief The constructor for a non-trivial `VariableType`. The default is
    /// passed as a JSON string.
    ///
    /// Uses formats::json::Value `Parse` customization point function to parse
    /// `VariableType`.
    ///
    /// Usage example:
    /// @snippet core/src/dynamic_config/config_test.cpp struct config cpp
    Key(std::string_view name, DefaultAsJsonString default_json);
 
    /// @brief The constructor that provides a special parser from JSON.
    /// @warning Prefer the constructors above whenever possible.
    /// @details Can be used when generic `Parse` is not applicable. Sometimes
    /// used to add validation, e.g. minimum, maximum, string pattern, etc.
    Key(std::string_view name, JsonParser parser, DefaultAsJsonString default_json);
 
    /// @brief Constructor with a schema_hash, used by chaotic codegen.
    /// @param schema_hash SHA-256(canonical JSON of schema with inlined definitions),
    ///        lowercase hex, 64 chars. Stored in the global registry and
    ///        retrievable via dynamic_config::impl::GetRegisteredConfigsMeta()
    ///        as dynamic_config::RegisteredConfigMeta::schema_hash.
    /// @warning This constructor is intended for use by chaotic codegen only,
    /// not for manual calls. Backwards-incompatible changes may be
    /// introduced in the future, e.g. adding additional parameters.
    Key(std::string_view name, JsonParser parser, DefaultAsJsonString default_json, std::string_view schema_hash);
 
    /// @brief The constructor that parses multiple JSON config items
    /// into a single C++ object.
    /// @warning Prefer to use a separate `Key` per JSON config item and use the
    /// constructors above whenever possible.
    template <std::size_t N>
    Key(DocsMapParser parser, const ConfigDefault (&default_json_map)[N]);
 
    /// Creates a config that always has the same value.
    Key(ConstantConfig, VariableType value);
 
    /// @cond
    Key(impl::InternalTag, std::string_view name);
 
    Key(impl::InternalTag, DocsMapParser parser);
    /// @endcond
 
    Key(const Key&) noexcept = delete;
    Key& operator=(const Key&) noexcept = delete;
 
    /// @returns the name of the config variable, as passed at the construction.
    std::string_view GetName() const noexcept;
 
    /// Parses the config. Useful only in some very niche scenarios. The config
    /// value should be typically be retrieved from dynamic_config::Snapshot,
    /// which is obtained from components::DynamicConfig in production or from
    /// dynamic_config::StorageMock in unit tests.
    VariableType Parse(const DocsMap& docs_map) const;
 
private:
    friend struct impl::ConfigIdGetter;
 
    const impl::ConfigId id_;
};
 
/// @brief The shared snapshot of
/// @ref scripts/docs/en/userver/dynamic_config.md "dynamic configs". Cheap to
/// copy, even cheaper to move. Thread safe, not updated with new dynamic
/// config values in background (it's a snapshot!).
///
/// When a config update comes in via new `DocsMap`, configs of all
/// the registered types are constructed and stored in `Config`. After that
/// the `DocsMap` is dropped.
///
/// Config types are automatically registered if they are used
/// somewhere in the program.
///
/// ## Usage example:
/// @snippet components/component_sample_test.cpp  Sample user component runtime config source
class Snapshot final {
public:
    Snapshot(const Snapshot&);
    Snapshot& operator=(const Snapshot&);
 
    Snapshot(Snapshot&&) noexcept;
    Snapshot& operator=(Snapshot&&) noexcept;
 
    ~Snapshot();
 
    /// Used to access individual configs in the type-safe config map
    template <typename VariableType>
    const VariableType& operator[](const Key<VariableType>& key) const& USERVER_IMPL_LIFETIME_BOUND;
 
    /// Used to access individual configs in the type-safe config map
    template <typename VariableType>
    const VariableType& operator[](const Key<VariableType>&) &&;
 
private:
    // for the constructor
    friend class Source;
    friend class impl::StorageData;
    friend struct Diff;
 
    explicit Snapshot(const impl::StorageData& storage);
 
    const impl::SnapshotData& GetData() const;
 
    struct Impl;
    utils::FastPimpl<Impl, 16, 8> impl_;
};
 
// ========================== Implementation follows ==========================
 
constexpr DefaultAsJsonString::DefaultAsJsonString(std::string_view json_string)
    : json_string(json_string)
{}
 
template <typename T>
ConfigDefault::ConfigDefault(std::string_view name, const T& value)
    : name(name),
      default_json(impl::ToJsonString(value))
{}
 
template <typename Variable>
Key<Variable>::Key(std::string_view name, const VariableType& default_value)
    : id_(impl::Register(
          std::string{name},
          [name = std::string{name}](const auto& docs_map) -> std::any {
              return impl::DocsMapGet(docs_map, name).template As<VariableType>();
          },
          impl::ValueToDocsMapString(name, default_value)
      ))
{}
 
template <typename Variable>
Key<Variable>::Key(std::string_view name, DefaultAsJsonString default_json)
    : id_(impl::Register(
          std::string{name},
          [name = std::string{name}](const auto& docs_map) -> std::any {
              return impl::DocsMapGet(docs_map, name).template As<VariableType>();
          },
          impl::SingleToDocsMapString(name, default_json.json_string)
      ))
{}
 
template <typename Variable>
Key<Variable>::Key(std::string_view name, JsonParser parser, DefaultAsJsonString default_json)
    : id_(impl::Register(
          std::string{name},
          [name = std::string{name}, parser](const auto& docs_map) -> std::any {
              return parser(impl::DocsMapGet(docs_map, name));
          },
          impl::SingleToDocsMapString(name, default_json.json_string)
      ))
{}
 
template <typename Variable>
Key<Variable>::Key(
    std::string_view name,
    JsonParser parser,
    DefaultAsJsonString default_json,
    std::string_view schema_hash
)
    : id_(impl::Register(
          std::string{name},
          [name = std::string{name}, parser](const auto& docs_map) -> std::any {
              return parser(impl::DocsMapGet(docs_map, name));
          },
          impl::SingleToDocsMapString(name, default_json.json_string),
          std::string{schema_hash}
      ))
{}
 
template <typename Variable>
template <std::size_t N>
Key<Variable>::Key(DocsMapParser parser, const ConfigDefault (&default_json_map)[N])
    : id_(impl::Register(
          std::string{},
          [parser](const DocsMap& docs_map) -> std::any { return parser(docs_map); },
          impl::MultipleToDocsMapString(default_json_map, N)
      ))
{}
 
template <typename Variable>
Key<Variable>::Key(ConstantConfig /*tag*/, VariableType value)
    : id_(impl::Register(std::string{}, [value = std::move(value)](const DocsMap& /*unused*/) { return value; }, "{}"))
{}
 
template <typename Variable>
Key<Variable>::Key(impl::InternalTag, std::string_view name)
    : id_(impl::Register(
          std::string{name},
          [name = std::string{name}](const auto& docs_map) -> std::any {
              return impl::DocsMapGet(docs_map, name).template As<VariableType>();
          },
          "{}"
      ))
{}
 
template <typename Variable>
Key<Variable>::Key(impl::InternalTag, DocsMapParser parser)
    : id_(impl::Register(
          std::string{},
          [parser](const DocsMap& docs_map) -> std::any { return parser(docs_map); },
          "{}"
      ))
{}
 
template <typename VariableType>
std::string_view Key<VariableType>::GetName() const noexcept {
    return impl::GetName(id_);
}
 
template <typename VariableType>
VariableType Key<VariableType>::Parse(const DocsMap& docs_map) const {
    return std::any_cast<VariableType>(impl::MakeConfig(id_, docs_map));
}
 
template <typename VariableType>
const VariableType& Snapshot::operator[](const Key<VariableType>& key) const& USERVER_IMPL_LIFETIME_BOUND {
    return GetData().Get<VariableType>(impl::ConfigIdGetter::Get(key));
}
 
template <typename VariableType>
const VariableType& Snapshot::operator[](const Key<VariableType>&) && {
    static_assert(!sizeof(VariableType), "keep the Snapshot before using, please");
}
 
}  // namespace dynamic_config
 
USERVER_NAMESPACE_END