refactor: tighten BigSegmentsBuilder defaults and docs

Author: beekld

libs/server-sdk/src/config/builders/big_segments_builder.cpp

@@ -1,10 +1,22 @@
 #include "big_segments_builder.hpp"
 
 #include <algorithm>
+#include <chrono>
 #include <utility>
 
 namespace launchdarkly::server_side::config::builders {
 
+namespace {
+
+using namespace std::chrono_literals;
+
+constexpr std::size_t kDefaultContextCacheSize = 1000;
+constexpr std::chrono::milliseconds kDefaultContextCacheTime = 5s;
+constexpr std::chrono::milliseconds kDefaultStatusPollInterval = 5s;
+constexpr std::chrono::milliseconds kDefaultStaleAfter = 2min;
+
+}  // namespace
+
 BigSegmentsBuilder::BigSegmentsBuilder(
     std::shared_ptr<integrations::IBigSegmentStore> store)
     : store_(std::move(store)),

libs/server-sdk/src/config/builders/big_segments_builder.hpp

@@ -12,24 +12,11 @@ namespace launchdarkly::server_side::config::builders {
 /**
  * @brief Configures the SDK's Big Segments behavior.
  *
- * A Big Segments store implementation is required at construction. The
- * tunables that control the SDK's Big Segments caching and staleness
- * detection have sensible defaults and can be overridden via the fluent
- * setters.
- *
- * Non-positive durations passed to a setter are coerced back to the
- * default for that field.
- *
  * Not thread-safe. Construct, configure, and call @ref Build on a single
  * thread; the resulting @ref built::BigSegmentsConfig is safe to share.
  */
 class BigSegmentsBuilder {
    public:
-    static constexpr std::size_t kDefaultContextCacheSize = 1000;
-    static constexpr std::chrono::milliseconds kDefaultContextCacheTime{5000};
-    static constexpr std::chrono::milliseconds kDefaultStatusPollInterval{5000};
-    static constexpr std::chrono::milliseconds kDefaultStaleAfter{120000};
-
     /**
      * @brief Constructs a builder for the given Big Segments store.
      *
@@ -41,7 +28,7 @@ class BigSegmentsBuilder {
 
     /**
      * @brief Sets the maximum number of context membership lookups cached
-     * by the SDK.
+     * by the SDK. Defaults to 1000.
      *
      * To reduce store traffic, the SDK maintains an LRU cache keyed by
      * context key. A higher value reduces store queries for
@@ -50,40 +37,41 @@ class BigSegmentsBuilder {
     BigSegmentsBuilder& ContextCacheSize(std::size_t size);
 
     /**
-     * @brief Sets the time-to-live for cached membership lookups.
+     * @brief Sets the time-to-live for cached membership lookups. Defaults
+     * to 5 seconds.
      *
      * A higher value reduces store queries for any given context, but
      * delays the SDK noticing membership changes. Zero or negative
-     * durations are coerced to @ref kDefaultContextCacheTime.
+     * durations are coerced to the default.
      */
     BigSegmentsBuilder& ContextCacheTime(std::chrono::milliseconds ttl);
 
     /**
      * @brief Sets the interval at which the SDK polls the store's metadata
-     * to determine availability and staleness.
+     * to determine availability and staleness. Defaults to 5 seconds.
      *
-     * Zero or negative durations are coerced to
-     * @ref kDefaultStatusPollInterval.
+     * Zero or negative durations are coerced to the default.
      */
     BigSegmentsBuilder& StatusPollInterval(std::chrono::milliseconds interval);
 
     /**
      * @brief Sets how long the SDK waits before treating store data as
-     * stale.
+     * stale. Defaults to 2 minutes.
      *
      * If the store's last-updated timestamp falls behind the current time
      * by more than this duration, evaluations report a big segments status
      * of `STALE` and the status provider reports the store as stale. Zero
-     * or negative durations are coerced to @ref kDefaultStaleAfter.
+     * or negative durations are coerced to the default.
      */
     BigSegmentsBuilder& StaleAfter(std::chrono::milliseconds threshold);
 
     /**
      * @brief Resolves the configuration.
      *
      * If the configured @ref StatusPollInterval exceeds @ref StaleAfter,
-     * the poll interval is clamped to the stale-after value so the SDK can
-     * detect staleness within one poll cycle (per BIGSEG §1.4.6).
+     * the poll interval in the returned config is clamped to the
+     * stale-after value so the SDK can detect staleness within one poll
+     * cycle.
      */
     [[nodiscard]] built::BigSegmentsConfig Build() const;
 

libs/server-sdk/tests/big_segments_builder_test.cpp

@@ -15,6 +15,8 @@ using launchdarkly::server_side::integrations::StoreMetadata;
 
 namespace {
 
+using namespace std::chrono_literals;
+
 // Minimal stub used only to obtain a shared_ptr<IBigSegmentStore>. The builder
 // never invokes the store; it only stores the pointer for later use by the
 // wrapper, so the methods here are unreachable in these tests.
@@ -39,13 +41,10 @@ TEST(BigSegmentsBuilderTest, DefaultsMatchSpec) {
     auto store = MakeStubStore();
     auto const cfg = BigSegmentsBuilder(store).Build();
 
-    EXPECT_EQ(cfg.context_cache_size,
-              BigSegmentsBuilder::kDefaultContextCacheSize);
-    EXPECT_EQ(cfg.context_cache_time,
-              BigSegmentsBuilder::kDefaultContextCacheTime);
-    EXPECT_EQ(cfg.status_poll_interval,
-              BigSegmentsBuilder::kDefaultStatusPollInterval);
-    EXPECT_EQ(cfg.stale_after, BigSegmentsBuilder::kDefaultStaleAfter);
+    EXPECT_EQ(cfg.context_cache_size, 1000u);
+    EXPECT_EQ(cfg.context_cache_time, 5s);
+    EXPECT_EQ(cfg.status_poll_interval, 5s);
+    EXPECT_EQ(cfg.stale_after, 2min);
 }
 
 TEST(BigSegmentsBuilderTest, BuildPreservesStoreIdentity) {
@@ -62,7 +61,6 @@ TEST(BigSegmentsBuilderTest, AcceptsNullStore) {
 }
 
 TEST(BigSegmentsBuilderTest, SettersOverrideEachField) {
-    using namespace std::chrono_literals;
     auto store = MakeStubStore();
     auto const cfg = BigSegmentsBuilder(store)
                          .ContextCacheSize(7)
@@ -80,37 +78,32 @@ TEST(BigSegmentsBuilderTest, SettersOverrideEachField) {
 TEST(BigSegmentsBuilderTest, ZeroDurationsAreCoercedToDefaults) {
     auto store = MakeStubStore();
     auto const cfg = BigSegmentsBuilder(store)
-                         .ContextCacheTime(std::chrono::milliseconds::zero())
-                         .StatusPollInterval(std::chrono::milliseconds::zero())
-                         .StaleAfter(std::chrono::milliseconds::zero())
+                         .ContextCacheTime(0ms)
+                         .StatusPollInterval(0ms)
+                         .StaleAfter(0ms)
                          .Build();
 
-    EXPECT_EQ(cfg.context_cache_time,
-              BigSegmentsBuilder::kDefaultContextCacheTime);
-    EXPECT_EQ(cfg.status_poll_interval,
-              BigSegmentsBuilder::kDefaultStatusPollInterval);
-    EXPECT_EQ(cfg.stale_after, BigSegmentsBuilder::kDefaultStaleAfter);
+    EXPECT_EQ(cfg.context_cache_time, 5s);
+    EXPECT_EQ(cfg.status_poll_interval, 5s);
+    EXPECT_EQ(cfg.stale_after, 2min);
 }
 
 TEST(BigSegmentsBuilderTest, NegativeDurationsAreCoercedToDefaults) {
     auto store = MakeStubStore();
     auto const cfg = BigSegmentsBuilder(store)
-                         .ContextCacheTime(std::chrono::milliseconds{-1})
-                         .StatusPollInterval(std::chrono::milliseconds{-1})
-                         .StaleAfter(std::chrono::milliseconds{-1})
+                         .ContextCacheTime(-1ms)
+                         .StatusPollInterval(-1ms)
+                         .StaleAfter(-1ms)
                          .Build();
 
-    EXPECT_EQ(cfg.context_cache_time,
-              BigSegmentsBuilder::kDefaultContextCacheTime);
-    EXPECT_EQ(cfg.status_poll_interval,
-              BigSegmentsBuilder::kDefaultStatusPollInterval);
-    EXPECT_EQ(cfg.stale_after, BigSegmentsBuilder::kDefaultStaleAfter);
+    EXPECT_EQ(cfg.context_cache_time, 5s);
+    EXPECT_EQ(cfg.status_poll_interval, 5s);
+    EXPECT_EQ(cfg.stale_after, 2min);
 }
 
 TEST(BigSegmentsBuilderTest, BuildClampsPollIntervalToStaleAfter) {
-    // BIGSEG §1.4.6: when poll interval > stale-after, clamp poll to
-    // stale-after so the SDK detects staleness within one poll cycle.
-    using namespace std::chrono_literals;
+    // When poll interval > stale-after, clamp poll to stale-after so the
+    // SDK detects staleness within one poll cycle.
     auto store = MakeStubStore();
     auto const cfg = BigSegmentsBuilder(store)
                          .StatusPollInterval(10s)
@@ -122,7 +115,6 @@ TEST(BigSegmentsBuilderTest, BuildClampsPollIntervalToStaleAfter) {
 }
 
 TEST(BigSegmentsBuilderTest, BuildPreservesPollIntervalWhenWithinStaleAfter) {
-    using namespace std::chrono_literals;
     auto store = MakeStubStore();
     auto const cfg = BigSegmentsBuilder(store)
                          .StatusPollInterval(3s)
@@ -134,7 +126,6 @@ TEST(BigSegmentsBuilderTest, BuildPreservesPollIntervalWhenWithinStaleAfter) {
 }
 
 TEST(BigSegmentsBuilderTest, BuildIsRepeatable) {
-    using namespace std::chrono_literals;
     auto store = MakeStubStore();
     BigSegmentsBuilder builder(store);
     builder.ContextCacheSize(42).ContextCacheTime(2s);