diff --git a/libs/client-sdk/src/client_impl.cpp b/libs/client-sdk/src/client_impl.cpp index 84ea433e9..72942b70e 100644 --- a/libs/client-sdk/src/client_impl.cpp +++ b/libs/client-sdk/src/client_impl.cpp @@ -1,4 +1,6 @@ #include "client_impl.hpp" +#include "data_sources/fdv2/fdv2_data_source.hpp" +#include "data_sources/fdv2/mode_sources.hpp" #include "data_sources/null_data_source.hpp" #include "data_sources/polling_data_source.hpp" #include "data_sources/streaming_data_source.hpp" @@ -31,12 +33,67 @@ using launchdarkly::client_side::data_sources::DataSourceStatus; using launchdarkly::config::shared::built::DataSourceConfig; using launchdarkly::config::shared::built::HttpProperties; +using FDv2Config = config::shared::built::FDv2Config; + +namespace { + +template +struct overloaded : Ts... { + using Ts::operator()...; +}; +template +overloaded(Ts...) -> overloaded; + +} // namespace + +static bool UsesFDv2(Config const& config) { + return std::holds_alternative(config.DataSourceConfig().method); +} + +static std::shared_ptr MakeFDv2DataSource( + HttpProperties const& http_properties, + Config const& config, + FDv2Config const& fdv2, + Context const& context, + boost::asio::any_io_executor const& executor, + flag_manager::FlagManager& flag_manager, + data_sources::DataSourceStatusManager& status_manager, + Logger& logger) { + auto const& endpoints = config.ServiceEndpoints(); + + if (config.DataSourceConfig().use_report) { + LD_LOG(logger, LogLevel::kWarn) + << "UseReport is not applicable to FDv2 and will be ignored"; + } + + data_sources::ModeSourceParams const params{ + executor, + logger, + http_properties, + endpoints, + context, + config.DataSourceConfig().with_reasons, + &flag_manager.Cache()}; + + auto sources = + data_sources::BuildModeSources(fdv2, fdv2.initial_mode, params); + + return std::make_shared( + std::move(sources.initializers), std::move(sources.synchronizers), + std::make_unique( + executor, fdv2.fallback_timeout), + std::make_unique( + executor, fdv2.recovery_timeout), + executor, context, &flag_manager.Updater(), &flag_manager.Store(), + &status_manager, logger); +} + static std::shared_ptr MakeDataSource( HttpProperties const& http_properties, Config const& config, Context const& context, boost::asio::any_io_executor const& executor, - IDataSourceUpdateSink& flag_updater, + flag_manager::FlagManager& flag_manager, data_sources::DataSourceStatusManager& status_manager, Logger& logger) { if (config.Offline()) { @@ -48,18 +105,30 @@ static std::shared_ptr MakeDataSource( auto data_source_properties = builder.Build(); - if (config.DataSourceConfig().method.index() == 0) { - return std::make_shared< - launchdarkly::client_side::data_sources::StreamingDataSource>( - config.ServiceEndpoints(), config.DataSourceConfig(), - data_source_properties, executor, context, flag_updater, - status_manager, logger); - } - return std::make_shared< - launchdarkly::client_side::data_sources::PollingDataSource>( - config.ServiceEndpoints(), config.DataSourceConfig(), - data_source_properties, executor, context, flag_updater, status_manager, - logger); + return std::visit( + overloaded{ + [&](config::shared::built::StreamingConfig const&) + -> std::shared_ptr { + return std::make_shared( + config.ServiceEndpoints(), config.DataSourceConfig(), + data_source_properties, executor, context, + flag_manager.Updater(), status_manager, logger); + }, + [&](config::shared::built::PollingConfig const&) + -> std::shared_ptr { + return std::make_shared( + config.ServiceEndpoints(), config.DataSourceConfig(), + data_source_properties, executor, context, + flag_manager.Updater(), status_manager, logger); + }, + [&](FDv2Config const& fdv2) + -> std::shared_ptr { + return MakeFDv2DataSource(data_source_properties, config, fdv2, + context, executor, flag_manager, + status_manager, logger); + }, + }, + config.DataSourceConfig().method); } static Logger MakeLogger(config::shared::built::Logging const& config) { @@ -101,13 +170,17 @@ ClientImpl::ClientImpl(Config in_cfg, MakePersistence(config_)), data_source_factory_([this]() { return MakeDataSource(http_properties_, config_, context_, - ioc_.get_executor(), flag_manager_.Updater(), + ioc_.get_executor(), flag_manager_, status_manager_, logger_); }), data_source_(nullptr), event_processor_(nullptr), eval_reasons_available_(config_.DataSourceConfig().with_reasons) { - flag_manager_.LoadCache(context_); + // Under FDv2 the cache is loaded by an initializer, so that it enters the + // store through the same path as every other source. + if (!UsesFDv2(config_)) { + flag_manager_.LoadCache(context_); + } if (auto custom_ca = http_properties_.Tls().CustomCAFile()) { LD_LOG(logger_, LogLevel::kInfo) @@ -160,7 +233,9 @@ static bool IsInitializedSuccessfully(DataSourceStatus::DataSourceState state) { std::future ClientImpl::IdentifyAsync(Context context) { UpdateContextSynchronized(context); - flag_manager_.LoadCache(context); + if (!UsesFDv2(config_)) { + flag_manager_.LoadCache(context); + } event_processor_->SendAsync(events::IdentifyEventParams{ std::chrono::system_clock::now(), std::move(context)}); diff --git a/libs/client-sdk/tests/fdv2_client_test.cpp b/libs/client-sdk/tests/fdv2_client_test.cpp new file mode 100644 index 000000000..47f35afeb --- /dev/null +++ b/libs/client-sdk/tests/fdv2_client_test.cpp @@ -0,0 +1,295 @@ +#include + +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "../../server-sent-events/tests/mock_sse_server.hpp" + +using namespace launchdarkly; +using namespace launchdarkly::client_side; +using namespace std::chrono_literals; + +namespace { + +class TestPersistence : public IPersistence { + public: + using StoreType = + std::map>>; + + explicit TestPersistence(StoreType store) : store_(std::move(store)) {} + + void Set(std::string storageNamespace, + std::string key, + std::string data) noexcept override { + std::lock_guard lock{mutex_}; + store_[storageNamespace][key] = data; + } + + void Remove(std::string storageNamespace, + std::string key) noexcept override { + std::lock_guard lock{mutex_}; + store_[storageNamespace].erase(key); + } + + std::optional Read(std::string storageNamespace, + std::string key) noexcept override { + std::lock_guard lock{mutex_}; + auto const ns = store_.find(storageNamespace); + if (ns == store_.end()) { + return std::nullopt; + } + auto const entry = ns->second.find(key); + if (entry == ns->second.end()) { + return std::nullopt; + } + return entry->second; + } + + private: + // The SDK reads from its own thread while the test writes from the main + // one. + std::mutex mutex_; + StoreType store_; +}; + +// Offline mode makes no requests, so the whole FDv2 path can be exercised +// without a service to talk to. +Config OfflineFDv2Config(std::shared_ptr persistence) { + auto builder = ConfigBuilder("the-key"); + builder.DataSource().Method( + DataSourceBuilder::FDv2().InitialMode(ConnectionMode::kOffline)); + builder.Events().Disable(); + if (persistence) { + builder.Persistence().Custom(std::move(persistence)); + } else { + builder.Persistence().None(); + } + return builder.Build().value(); +} + +// The namespace and context id the client derives for SDK key "the-key" and +// context user:user-key. +char const* const kEnvironment = + "LaunchDarkly_rUTcjlHPv6Vegd27YmtGYkEGkEUGaEbn5M0JYTFQUpA="; +char const* const kContextId = "CEXjZY7cHJG_ydFy7q4-YEFwVrG3_pkJwA4FAjrbfx0="; + +} // namespace + +// The cache is the only source offline mode has, so a miss still starts the +// SDK with no flags, evaluating to defaults. +TEST(FDv2ClientTest, OfflineModeStartsWithNoCachedData) { + Client client(OfflineFDv2Config(nullptr), + ContextBuilder().Kind("user", "user-key").Build()); + + auto started = client.StartAsync(); + + ASSERT_EQ(std::future_status::ready, started.wait_for(5s)); + EXPECT_TRUE(started.get()); + EXPECT_TRUE(client.Initialized()); + EXPECT_TRUE(client.AllFlags().empty()); +} + +TEST(FDv2ClientTest, OfflineModeEvaluatesAgainstTheCache) { + auto persistence = + std::make_shared(TestPersistence::StoreType{ + {kEnvironment, + {{kContextId, R"({"treat":{"version":1,"value":"fish"}})"}}}}); + + Client client(OfflineFDv2Config(persistence), + ContextBuilder().Kind("user", "user-key").Build()); + + auto started = client.StartAsync(); + + ASSERT_EQ(std::future_status::ready, started.wait_for(5s)); + EXPECT_TRUE(started.get()); + EXPECT_EQ("fish", client.StringVariation("treat", "chicken")); +} + +// During identify, the old stream can deliver one more update. The first +// request for the new context must not contain the selector from that update. +TEST(FDv2ClientTest, IdentifyDoesNotSendThePreviousContextsBasis) { + namespace http = boost::beast::http; + + std::mutex mutex; + std::vector targets; + std::function send_to_first; + async::Promise second_connected; + auto second_connected_future = second_connected.GetFuture(); + async::Promise applied; + auto applied_future = applied.GetFuture(); + std::once_flag pushed_once; + bool late_update_applied = false; + + sse::test::MockSSEServer server; + server.start([&](http::request const& req, + std::function)> + send_response, + std::function send_sse_event, + std::function /* close_connection */) { + http::response res{http::status::ok, req.version()}; + res.set(http::field::content_type, "text/event-stream"); + res.chunked(true); + send_response(res); + + std::lock_guard lock{mutex}; + // Record the target of each request. + targets.emplace_back(req.target()); + if (targets.size() == 1) { + send_to_first = send_sse_event; + // Send a full data set on the first stream. + send_sse_event( + "event: server-intent\n" + R"(data: {"payloads":[{"id":"p1","target":1,)" + R"("intentCode":"xfer-full"}]})" + "\n\n" + "event: put-object\n" + R"(data: {"version":1,"kind":"flag-eval","key":"flagA",)" + R"("object":{"value":"a-1","variation":0}})" + "\n\n" + "event: payload-transferred\n" + R"(data: {"state":"a-1","version":1})" + "\n\n"); + } else if (targets.size() == 2) { + second_connected.Resolve(std::monostate{}); + } + }); + + auto builder = ConfigBuilder("the-key"); + builder.DataSource().Method( + DataSourceBuilder::FDv2() + .InitialMode(ConnectionMode::kStreaming) + .CustomizeMode(ConnectionMode::kStreaming, + FDv2Builder::Mode() + .Initializer(FDv2Builder::Cache()) + .Synchronizer(FDv2Builder::Streaming().BaseUrl( + server.url())))); + builder.Events().Disable(); + builder.Persistence().None(); + + Client client(builder.Build().value(), + ContextBuilder().Kind("user", "first").Build()); + auto started = client.StartAsync(); + ASSERT_EQ(std::future_status::ready, started.wait_for(5s)); + ASSERT_TRUE(started.get()); + + // A change to flagA shows that the SDK applied the update. + auto flag_connection = client.FlagNotifier().OnFlagChange( + "flagA", [&](std::shared_ptr) { + applied.Resolve(std::monostate{}); + }); + + auto status_connection = client.DataSourceStatus().OnDataSourceStatusChange( + [&](data_sources::DataSourceStatus status) { + // Identify sets this status before the old source closes. + if (status.State() != data_sources::DataSourceStatus:: + DataSourceState::kInitializing) { + return; + } + std::call_once(pushed_once, [&] { + std::function send; + { + std::lock_guard lock{mutex}; + send = send_to_first; + } + // Send an update on the old stream. + send( + "event: put-object\n" + R"(data: {"version":2,"kind":"flag-eval","key":"flagA",)" + R"("object":{"value":"a-2","variation":1}})" + "\n\n" + "event: payload-transferred\n" + R"(data: {"state":"a-2","version":2})" + "\n\n"); + // Wait until the SDK applies the update. + late_update_applied = + applied_future.WaitForResult(5s).has_value(); + }); + }); + + // Identify the second context. + client.IdentifyAsync(ContextBuilder().Kind("user", "second").Build()); + + // The SDK applied the update from the old stream. + ASSERT_TRUE(late_update_applied); + // The SDK opened a stream for the second context. + ASSERT_TRUE(second_connected_future.WaitForResult(5s).has_value()); + std::lock_guard lock{mutex}; + // The first request for the second context has no basis. + EXPECT_EQ(std::string::npos, targets[1].find("basis=")) + << "The second context requested " << targets[1]; +} + +// A customized mode that sets no FDv1 fallback still falls back to FDv1. +TEST(FDv2ClientTest, CustomizedModeKeepsTheBuiltInFDv1Fallback) { + namespace http = boost::beast::http; + + async::Promise polled; + auto polled_future = polled.GetFuture(); + + sse::test::MockSSEServer server; + server.start([&](http::request const& req, + std::function)> + send_response, + std::function send_sse_event, + std::function /* close_connection */) { + std::string const target(req.target()); + // Answer FDv1 polls with no flags. + if (target.rfind("/msdk/evalx/contexts", 0) == 0) { + http::response res{http::status::ok, + req.version()}; + res.set(http::field::content_type, "application/json"); + res.body() = "{}"; + res.prepare_payload(); + send_response(res); + // Record the FDv1 poll. + polled.Resolve(std::monostate{}); + return; + } + + http::response res{http::status::ok, req.version()}; + res.set(http::field::content_type, "text/event-stream"); + res.chunked(true); + send_response(res); + // Direct the SDK to FDv1. + send_sse_event( + "event: goodbye\n" + R"(data: {"reason":"fallback","protocolFallbackTTL":60})" + "\n\n"); + }); + + auto builder = ConfigBuilder("the-key"); + builder.ServiceEndpoints() + .PollingBaseUrl(server.url()) + .StreamingBaseUrl(server.url()) + .EventsBaseUrl(server.url()); + builder.DataSource().Method( + DataSourceBuilder::FDv2() + .InitialMode(ConnectionMode::kStreaming) + .CustomizeMode( + ConnectionMode::kStreaming, + FDv2Builder::Mode().Synchronizer(FDv2Builder::Streaming()))); + builder.Events().Disable(); + builder.Persistence().None(); + + Client client(builder.Build().value(), + ContextBuilder().Kind("user", "user-key").Build()); + + // Start the SDK in the customized streaming mode. + client.StartAsync(); + + // The SDK polls the FDv1 endpoint. + EXPECT_TRUE(polled_future.WaitForResult(5s).has_value()); +} diff --git a/libs/client-sdk/tests/fdv2_config_builder_test.cpp b/libs/client-sdk/tests/fdv2_config_builder_test.cpp new file mode 100644 index 000000000..f2e33058e --- /dev/null +++ b/libs/client-sdk/tests/fdv2_config_builder_test.cpp @@ -0,0 +1,153 @@ +#include + +#include + +#include +#include + +using launchdarkly::client_side::ConfigBuilder; +using launchdarkly::client_side::ConnectionMode; +using launchdarkly::client_side::DataSourceBuilder; +using launchdarkly::client_side::Defaults; +using launchdarkly::client_side::FDv2Builder; +using launchdarkly::config::shared::ClientSDK; + +using FDv2Config = launchdarkly::config::shared::built::FDv2Config; +using PollingConfig = + launchdarkly::config::shared::built::PollingConfig; +using StreamingConfig = + launchdarkly::config::shared::built::StreamingConfig; + +using namespace std::chrono_literals; + +namespace { + +FDv2Config BuildFDv2(FDv2Builder fdv2) { + auto config = + ConfigBuilder("sdk-key").DataSource().Method(std::move(fdv2)).Build(); + return std::get(config.method); +} + +} // namespace + +// The streaming and polling methods speak FDv1. FDv2 replaces them. +TEST(FDv2ConfigBuilderTest, TheDefaultDataSourceIsStillFDv1Streaming) { + auto config = ConfigBuilder("sdk-key").Build(); + + ASSERT_TRUE(config.has_value()); + EXPECT_TRUE(std::holds_alternative( + config->DataSourceConfig().method)); +} + +TEST(FDv2ConfigBuilderTest, SelectingFDv2ReplacesTheFDv1Method) { + auto builder = ConfigBuilder("sdk-key"); + builder.DataSource().Method(DataSourceBuilder::FDv2()); + + auto config = builder.Build(); + + ASSERT_TRUE(config.has_value()); + EXPECT_TRUE( + std::holds_alternative(config->DataSourceConfig().method)); +} + +// The builder starts from the SDK's defaults, whatever they are. +TEST(FDv2ConfigBuilderTest, AnUncustomizedBuilderYieldsTheSDKDefaults) { + auto const config = BuildFDv2(FDv2Builder()); + auto const defaults = Defaults::FDv2Config(); + + EXPECT_EQ(defaults.initial_mode, config.initial_mode); + EXPECT_EQ(defaults.modes.size(), config.modes.size()); + EXPECT_EQ(defaults.fallback_timeout, config.fallback_timeout); + EXPECT_EQ(defaults.recovery_timeout, config.recovery_timeout); +} + +TEST(FDv2ConfigBuilderTest, DefaultsSendTheContextInTheRequestPath) { + auto const config = BuildFDv2(FDv2Builder()); + + EXPECT_FALSE(config.use_post); +} + +TEST(FDv2ConfigBuilderTest, InitialModeIsSelectable) { + auto const config = + BuildFDv2(FDv2Builder().InitialMode(ConnectionMode::kPolling)); + + EXPECT_EQ(ConnectionMode::kPolling, config.initial_mode); +} + +TEST(FDv2ConfigBuilderTest, UsePostIsSettable) { + auto const config = BuildFDv2(FDv2Builder().UsePost(true)); + + EXPECT_TRUE(config.use_post); +} + +TEST(FDv2ConfigBuilderTest, CustomizingAModeReplacesItsPipeline) { + FDv2Builder builder; + builder.CustomizeMode( + ConnectionMode::kStreaming, + FDv2Builder::Mode() + .Initializer(FDv2Builder::Cache()) + .Synchronizer(FDv2Builder::Streaming().InitialReconnectDelay(2s)) + .DisableFDv1Fallback()); + + auto const config = BuildFDv2(std::move(builder)); + auto const& mode = config.modes.at(ConnectionMode::kStreaming); + + ASSERT_EQ(1u, mode.initializers.size()); + EXPECT_TRUE( + std::holds_alternative(mode.initializers[0])); + ASSERT_EQ(1u, mode.synchronizers.size()); + auto const* streaming = + std::get_if(&mode.synchronizers[0]); + ASSERT_NE(nullptr, streaming); + EXPECT_EQ(2s, streaming->initial_reconnect_delay); + EXPECT_TRUE( + std::holds_alternative(mode.fdv1_fallback)); +} + +TEST(FDv2ConfigBuilderTest, CustomizingOneModeLeavesTheOthersAlone) { + FDv2Builder builder; + builder.CustomizeMode(ConnectionMode::kPolling, + FDv2Builder::Mode().Synchronizer( + FDv2Builder::Polling().PollInterval(60s))); + + auto const config = BuildFDv2(std::move(builder)); + + EXPECT_EQ(3u, config.modes.size()); + EXPECT_EQ(2u, + config.modes.at(ConnectionMode::kStreaming).initializers.size()); +} + +TEST(FDv2ConfigBuilderTest, SourcesCanOverrideTheirOwnBaseUrl) { + FDv2Builder builder; + builder.CustomizeMode( + ConnectionMode::kStreaming, + FDv2Builder::Mode().Synchronizer( + FDv2Builder::Polling().BaseUrl("https://relay.example.com"))); + + auto const config = BuildFDv2(std::move(builder)); + auto const* polling = std::get_if( + &config.modes.at(ConnectionMode::kStreaming).synchronizers[0]); + + ASSERT_NE(nullptr, polling); + ASSERT_TRUE(polling->base_url_override.has_value()); + EXPECT_EQ("https://relay.example.com", *polling->base_url_override); +} + +TEST(FDv2ConfigBuilderTest, TheFDv1FallbackIsConfigurable) { + FDv2Builder builder; + builder.CustomizeMode( + ConnectionMode::kStreaming, + FDv2Builder::Mode() + .Synchronizer(FDv2Builder::Streaming()) + .FDv1Fallback(FDv2Builder::FDv1Polling().PollInterval(600s).BaseUrl( + "https://relay.example.com"))); + + auto const config = BuildFDv2(std::move(builder)); + auto const* fallback = std::get_if( + &config.modes.at(ConnectionMode::kStreaming).fdv1_fallback); + + ASSERT_NE(nullptr, fallback); + EXPECT_EQ(600s, fallback->poll_interval); + ASSERT_TRUE(fallback->base_url_override.has_value()); + EXPECT_EQ("https://relay.example.com", *fallback->base_url_override); +} diff --git a/libs/common/include/launchdarkly/config/client.hpp b/libs/common/include/launchdarkly/config/client.hpp index dd288a82a..5fa1ffb6b 100644 --- a/libs/common/include/launchdarkly/config/client.hpp +++ b/libs/common/include/launchdarkly/config/client.hpp @@ -4,7 +4,9 @@ #include #include #include +#include #include +#include #include #include @@ -20,6 +22,8 @@ using EventsBuilder = config::shared::builders::EventsBuilder; using HttpPropertiesBuilder = config::shared::builders::HttpPropertiesBuilder; using DataSourceBuilder = config::shared::builders::DataSourceBuilder; +using FDv2Builder = config::shared::builders::FDv2Builder; +using ConnectionMode = config::shared::ConnectionMode; using LoggingBuilder = config::shared::builders::LoggingBuilder; using PersistenceBuilder = config::shared::builders::PersistenceBuilder; using TlsBuilder = config::shared::builders::TlsBuilder; diff --git a/libs/common/include/launchdarkly/config/shared/builders/data_source_builder.hpp b/libs/common/include/launchdarkly/config/shared/builders/data_source_builder.hpp index a69bac6e1..dbcbd3d0c 100644 --- a/libs/common/include/launchdarkly/config/shared/builders/data_source_builder.hpp +++ b/libs/common/include/launchdarkly/config/shared/builders/data_source_builder.hpp @@ -1,5 +1,6 @@ #pragma once +#include #include #include #include @@ -134,6 +135,7 @@ class DataSourceBuilder { public: using Streaming = StreamingBuilder; using Polling = PollingBuilder; + using FDv2 = FDv2Builder; DataSourceBuilder(); @@ -189,6 +191,18 @@ class DataSourceBuilder { */ DataSourceBuilder& Method(Polling polling_builder); + /** + * Set the FDv2 configuration for the builder. + * + * FDv2 is the current flag delivery protocol. It supersedes the + * streaming and polling methods above, which speak FDv1, and configures + * both transports itself through named connection modes. + * + * @param fdv2_builder The FDv2 builder. + * @return Reference to this builder. + */ + DataSourceBuilder& Method(FDv2 fdv2_builder); + /** * Build a data source config. This is used internal to the SDK. * @@ -197,7 +211,7 @@ class DataSourceBuilder { [[nodiscard]] built::DataSourceConfig Build() const; private: - std::variant method_; + std::variant method_; bool with_reasons_; bool use_report_; }; diff --git a/libs/common/include/launchdarkly/config/shared/builders/endpoints_builder.hpp b/libs/common/include/launchdarkly/config/shared/builders/endpoints_builder.hpp index 166822cbb..d2e818f42 100644 --- a/libs/common/include/launchdarkly/config/shared/builders/endpoints_builder.hpp +++ b/libs/common/include/launchdarkly/config/shared/builders/endpoints_builder.hpp @@ -27,8 +27,8 @@ bool operator==(EndpointsBuilder const& lhs, template class EndpointsBuilder { public: - friend bool operator==(EndpointsBuilder const& lhs, - EndpointsBuilder const& rhs); + friend bool operator== (EndpointsBuilder const& lhs, + EndpointsBuilder const& rhs); /** * Constructs an EndpointsBuilder. */ diff --git a/libs/common/include/launchdarkly/config/shared/builders/fdv2_builder.hpp b/libs/common/include/launchdarkly/config/shared/builders/fdv2_builder.hpp new file mode 100644 index 000000000..a9a98b954 --- /dev/null +++ b/libs/common/include/launchdarkly/config/shared/builders/fdv2_builder.hpp @@ -0,0 +1,289 @@ +#pragma once + +#include +#include +#include + +#include +#include +#include + +namespace launchdarkly::config::shared::builders { + +template +class FDv2Builder; + +/** + * Contains methods for configuring the FDv2 data system, which determines how + * the SDK obtains flag data and how it keeps that data current. + * + * A default-constructed builder is the configuration the SDK uses when the + * application customizes nothing. It starts in streaming mode, and provides + * streaming, polling, and offline modes. + */ +template <> +class FDv2Builder { + public: + using Config = built::FDv2Config; + + /** + * Configures the local cache as a source. It has no options. + * + * Reading persisted flag data lets evaluation begin before the network + * answers. + */ + class Cache { + public: + /** + * Build the cache config. Used internal to the SDK. + * @return The built config. + */ + [[nodiscard]] Config::CacheConfig Build() const; + }; + + /** + * Contains methods for configuring a streaming source, which receives + * updates as the service publishes them. + */ + class Streaming { + public: + /** + * Sets the initial reconnect delay for the streaming connection. + * + * The delay for the first reconnection will start near this value, + * and then increase exponentially for any subsequent connection + * failures. + * + * @param delay The initial delay for a reconnection attempt. + * @return Reference to this builder. + */ + Streaming& InitialReconnectDelay(std::chrono::milliseconds delay); + + /** + * Sets the base URL for this source alone. + * + * Requests from this source are sent to the given URL instead of the + * streaming URL the rest of the SDK uses. This is useful for routing + * one tier to different infrastructure, such as a Relay Proxy used + * only as a fallback. + * + * @param base_url The base URL for this source. + * @return Reference to this builder. + */ + Streaming& BaseUrl(std::string base_url); + + /** + * Build the streaming config. Used internal to the SDK. + * @return The built config. + */ + [[nodiscard]] Config::StreamingConfig Build() const; + + private: + std::chrono::milliseconds initial_reconnect_delay_{1000}; + std::optional base_url_override_; + }; + + /** + * Contains methods for configuring a polling source, which asks the + * service for updates on an interval. + */ + class Polling { + public: + /** + * Sets the interval at which the SDK will poll for feature flag + * updates. + * + * Intervals shorter than the minimum the SDK permits are raised to + * it. + * + * @param interval The polling interval. + * @return Reference to this builder. + */ + Polling& PollInterval(std::chrono::seconds interval); + + /** + * Sets the base URL for this source alone. + * + * Requests from this source are sent to the given URL instead of the + * polling URL the rest of the SDK uses. + * + * @param base_url The base URL for this source. + * @return Reference to this builder. + */ + Polling& BaseUrl(std::string base_url); + + /** + * Build the polling config. Used internal to the SDK. + * @return The built config. + */ + [[nodiscard]] Config::PollingConfig Build() const; + + private: + std::chrono::seconds poll_interval_{std::chrono::minutes(5)}; + std::optional base_url_override_; + }; + + /** + * Contains methods for configuring the FDv1 polling source the SDK uses + * while the service has directed it away from FDv2. + * + * The SDK returns to FDv2 on its own once the service's fallback period + * has elapsed. + */ + class FDv1Polling { + public: + /** + * Sets the interval at which the SDK will poll while on FDv1. + * @param interval The polling interval. + * @return Reference to this builder. + */ + FDv1Polling& PollInterval(std::chrono::seconds interval); + + /** + * Sets the base URL for the fallback alone. + * + * Requests from the fallback are sent to the given URL instead of the + * polling URL the rest of the SDK uses. + * + * @param base_url The base URL for the fallback. + * @return Reference to this builder. + */ + FDv1Polling& BaseUrl(std::string base_url); + + /** + * Build the FDv1 fallback config. Used internal to the SDK. + * @return The built config. + */ + [[nodiscard]] Config::FDv1FallbackConfig Build() const; + + private: + std::chrono::seconds poll_interval_{std::chrono::minutes(5)}; + std::optional base_url_override_; + }; + + /** + * Contains methods for configuring what one connection mode does, meaning + * which sources load flag data and which keep it current. + * + * A mode built this way replaces the built-in initializers and + * synchronizers, so it should list every source it needs, cache included. + * + * The mode keeps the built-in FDv1 fallback. Call FDv1Fallback() to + * replace it, or DisableFDv1Fallback() to remove it. + */ + class Mode { + public: + /** + * Appends a source to the list that loads flag data. + * + * The sources run in order until one loads a complete data set. + * + * @param source The cache source. + * @return Reference to this builder. + */ + Mode& Initializer(Cache source); + + /** + * Appends a source to the list that loads flag data. + * + * The sources run in order until one loads a complete data set. + * + * @param source The polling source. + * @return Reference to this builder. + */ + Mode& Initializer(Polling source); + + /** + * Appends a source to the list that keeps flag data current. + * + * Order is preference. The first entry is the primary, and the SDK + * falls back to later entries when it cannot keep the primary + * running. + * + * @param source The streaming source. + * @return Reference to this builder. + */ + Mode& Synchronizer(Streaming source); + + /** + * Appends a source to the list that keeps flag data current. + * + * Order is preference. The first entry is the primary, and the SDK + * falls back to later entries when it cannot keep the primary + * running. + * + * @param source The polling source. + * @return Reference to this builder. + */ + Mode& Synchronizer(Polling source); + + /** + * Sets the FDv1 source to use if the service directs the SDK to it. + * @param source The FDv1 fallback source. + * @return Reference to this builder. + */ + Mode& FDv1Fallback(FDv1Polling source); + + /** + * Leaves the mode with no FDv1 source. + * + * A fallback directive then stops the mode's synchronizer until the + * SDK returns to FDv2. + * + * @return Reference to this builder. + */ + Mode& DisableFDv1Fallback(); + + /** + * Build the mode definition. Used internal to the SDK. + * @return The built config. + */ + [[nodiscard]] Config::ModeDefinition Build() const; + + private: + Config::ModeDefinition definition_; + }; + + FDv2Builder(); + + /** + * Sets the mode the SDK starts in. Defaults to streaming. + * @param mode The initial connection mode. + * @return Reference to this builder. + */ + FDv2Builder& InitialMode(ConnectionMode mode); + + /** + * Replaces what the given mode does. + * + * Modes left uncustomized keep their built-in definitions. + * + * @param mode The connection mode to replace. + * @param definition What the mode does. + * @return Reference to this builder. + */ + FDv2Builder& CustomizeMode(ConnectionMode mode, Mode definition); + + /** + * Whether to send the evaluation context in a request body rather than + * encoded into the request path. + * + * This keeps the context out of URL-based request logs and CDN logs, at + * the cost of CDN caching. + * + * @param use_post True to send the context in a request body. + * @return Reference to this builder. + */ + FDv2Builder& UsePost(bool use_post); + + /** + * Build the FDv2 config. Used internal to the SDK. + * @return The built config. + */ + [[nodiscard]] Config Build() const; + + private: + Config config_; +}; + +} // namespace launchdarkly::config::shared::builders diff --git a/libs/common/include/launchdarkly/config/shared/built/data_source_config.hpp b/libs/common/include/launchdarkly/config/shared/built/data_source_config.hpp index 32b9cc5b2..560e08eea 100644 --- a/libs/common/include/launchdarkly/config/shared/built/data_source_config.hpp +++ b/libs/common/include/launchdarkly/config/shared/built/data_source_config.hpp @@ -1,5 +1,6 @@ #pragma once +#include #include #include @@ -56,9 +57,16 @@ struct DataSourceConfig; template <> struct DataSourceConfig { - std::variant, PollingConfig> method; + std::variant, + PollingConfig, + FDv2Config> + method; bool with_reasons; + /** + * Ignored when the method is FDv2, which supersedes the REPORT + * transport with its own choice of GET or POST. + */ bool use_report; }; diff --git a/libs/common/src/CMakeLists.txt b/libs/common/src/CMakeLists.txt index c39644fd0..f78a7691a 100644 --- a/libs/common/src/CMakeLists.txt +++ b/libs/common/src/CMakeLists.txt @@ -41,6 +41,7 @@ add_library(${LIBNAME} OBJECT config/app_info_builder.cpp config/http_properties.cpp config/data_source_builder.cpp + config/fdv2_builder.cpp config/http_properties_builder.cpp bindings/c/value.cpp bindings/c/array_builder.cpp diff --git a/libs/common/src/config/data_source_builder.cpp b/libs/common/src/config/data_source_builder.cpp index e19a9417e..79a60091d 100644 --- a/libs/common/src/config/data_source_builder.cpp +++ b/libs/common/src/config/data_source_builder.cpp @@ -8,8 +8,9 @@ struct MethodVisitor {}; template <> struct MethodVisitor { using SDK = ClientSDK; - using Result = - std::variant, built::PollingConfig>; + using Result = std::variant, + built::PollingConfig, + built::FDv2Config>; Result operator()(StreamingBuilder const& streaming) const { return streaming.Build(); @@ -18,6 +19,10 @@ struct MethodVisitor { Result operator()(PollingBuilder const& polling) const { return polling.Build(); } + + Result operator()(FDv2Builder const& fdv2) const { + return fdv2.Build(); + } }; template @@ -79,6 +84,12 @@ DataSourceBuilder& DataSourceBuilder::Method( return *this; } +DataSourceBuilder& DataSourceBuilder::Method( + FDv2Builder builder) { + method_ = std::move(builder); + return *this; +} + built::DataSourceConfig DataSourceBuilder::Build() const { return {std::visit(MethodVisitor(), method_), with_reasons_, use_report_}; diff --git a/libs/common/src/config/fdv2_builder.cpp b/libs/common/src/config/fdv2_builder.cpp new file mode 100644 index 000000000..ba21c158d --- /dev/null +++ b/libs/common/src/config/fdv2_builder.cpp @@ -0,0 +1,131 @@ +#include +#include + +#include + +namespace launchdarkly::config::shared::builders { + +FDv2Builder::Config::CacheConfig +FDv2Builder::Cache::Build() const { + return {}; +} + +FDv2Builder::Streaming& +FDv2Builder::Streaming::InitialReconnectDelay( + std::chrono::milliseconds delay) { + initial_reconnect_delay_ = delay; + return *this; +} + +FDv2Builder::Streaming& FDv2Builder::Streaming::BaseUrl( + std::string base_url) { + base_url_override_ = std::move(base_url); + return *this; +} + +FDv2Builder::Config::StreamingConfig +FDv2Builder::Streaming::Build() const { + return {initial_reconnect_delay_, base_url_override_}; +} + +FDv2Builder::Polling& FDv2Builder::Polling::PollInterval( + std::chrono::seconds interval) { + poll_interval_ = interval; + return *this; +} + +FDv2Builder::Polling& FDv2Builder::Polling::BaseUrl( + std::string base_url) { + base_url_override_ = std::move(base_url); + return *this; +} + +FDv2Builder::Config::PollingConfig +FDv2Builder::Polling::Build() const { + return {poll_interval_, base_url_override_}; +} + +FDv2Builder::FDv1Polling& FDv2Builder< + ClientSDK>::FDv1Polling::PollInterval(std::chrono::seconds interval) { + poll_interval_ = interval; + return *this; +} + +FDv2Builder::FDv1Polling& +FDv2Builder::FDv1Polling::BaseUrl(std::string base_url) { + base_url_override_ = std::move(base_url); + return *this; +} + +FDv2Builder::Config::FDv1FallbackConfig +FDv2Builder::FDv1Polling::Build() const { + return {poll_interval_, base_url_override_}; +} + +FDv2Builder::Mode& FDv2Builder::Mode::Initializer( + Cache source) { + definition_.initializers.emplace_back(source.Build()); + return *this; +} + +FDv2Builder::Mode& FDv2Builder::Mode::Initializer( + Polling source) { + definition_.initializers.emplace_back(source.Build()); + return *this; +} + +FDv2Builder::Mode& FDv2Builder::Mode::Synchronizer( + Streaming source) { + definition_.synchronizers.emplace_back(source.Build()); + return *this; +} + +FDv2Builder::Mode& FDv2Builder::Mode::Synchronizer( + Polling source) { + definition_.synchronizers.emplace_back(source.Build()); + return *this; +} + +FDv2Builder::Mode& FDv2Builder::Mode::FDv1Fallback( + FDv1Polling source) { + definition_.fdv1_fallback = source.Build(); + return *this; +} + +FDv2Builder::Mode& +FDv2Builder::Mode::DisableFDv1Fallback() { + definition_.fdv1_fallback = Config::NoFDv1Fallback{}; + return *this; +} + +FDv2Builder::Config::ModeDefinition +FDv2Builder::Mode::Build() const { + return definition_; +} + +FDv2Builder::FDv2Builder() + : config_(Defaults::FDv2Config()) {} + +FDv2Builder& FDv2Builder::InitialMode( + ConnectionMode mode) { + config_.initial_mode = mode; + return *this; +} + +FDv2Builder& FDv2Builder::CustomizeMode( + ConnectionMode mode, + Mode definition) { + config_.modes[mode] = definition.Build(); + return *this; +} + +FDv2Builder& FDv2Builder::UsePost(bool use_post) { + config_.use_post = use_post; + return *this; +} + +FDv2Builder::Config FDv2Builder::Build() const { + return config_; +} + +} // namespace launchdarkly::config::shared::builders