feat: expose Big Segments via public Client and Config APIs (#552)

# Expose Big Segments to customer code

Makes the server-side Big Segments feature reachable from customer code:
a public config method to wire a store, and a status provider on the
client for querying store health and subscribing to changes. Builds on
SDK-2366-2.

## What's in

- Promotes `BigSegmentsBuilder` to the public include tree and adds
`ConfigBuilder::BigSegments(BigSegmentsBuilder)`, surfaced as an
optional `Config::BigSegments()`.
- New public `IBigSegmentStoreStatusProvider` and
`BigSegmentStoreStatus` (`IsAvailable()`/`IsStale()`), plus
`Client::BigSegmentStoreStatus()`.
- `ClientImpl` constructs the `BigSegmentStoreWrapper` from config,
hands it to the evaluator, and starts its background poll. An internal
adapter exposes the wrapper's status broadcaster as the public provider.
- `BigSegmentsBuilder::Build()` now returns a new error code when the
store is null.

## Design notes

- The status surface mirrors `DataSourceStatus`: the accessor is
`Status()`, and listeners use `OnBigSegmentStoreStatusChange(handler) ->
IConnection`.
- When no store is configured, the provider reports the store as
unavailable and registered listeners never fire.

## Testing

Unit tests added for the new behavior.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes flag evaluation wiring and add a new public config surface;
misconfiguration or store outages can affect Big Segment targeting,
though behavior is gated on optional config and mirrors existing
data-source status patterns.
> 
> **Overview**
> This PR wires **Big Segments** into the public server SDK: customers
can attach a store via config and observe store health on the client,
similar to data source status.
> 
> **Configuration:** `ConfigBuilder::BigSegments(BigSegmentsBuilder)`
stores an optional `BigSegmentsConfig` on `Config`.
`BigSegmentsBuilder::Build()` now returns `tl::expected` and fails with
`kConfig_BigSegments_NullStore` when the store pointer is null
(previously a null store was allowed through).
> 
> **Client runtime:** When Big Segments are configured, `ClientImpl`
creates `BigSegmentStoreWrapper`, passes it to the evaluator, starts
background metadata polling, and exposes status through
`Client::BigSegmentStoreStatus()`.
> 
> **Public status API:** New `BigSegmentStoreStatus` (`IsAvailable` /
`IsStale`) and `IBigSegmentStoreStatusProvider` with `Status()` and
`OnBigSegmentStoreStatusChange` → `IConnection`. An internal adapter
maps the wrapper to this API; with no store configured, status is
unavailable/not stale and listeners are no-ops.
> 
> Unit tests cover builder validation, config round-trip, and status
provider behavior (including transitions).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
11902fa. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: beekld

libs/common/include/launchdarkly/error.hpp

@@ -24,6 +24,7 @@ enum class Error : std::uint32_t {
     /* Client-side errors: 10000-19999 */
     /* Server-side errors: 20000-29999 */
     kConfig_DataSystem_LazyLoad_MissingSource = 20000,
+    kConfig_BigSegments_NullStore = 20001,
     kMax = std::numeric_limits<std::uint32_t>::max()
 };
 

libs/common/src/error.cpp

@@ -32,6 +32,8 @@ char const* ErrorToString(Error err) {
             return "sdk key: cannot be empty";
         case Error::kConfig_DataSystem_LazyLoad_MissingSource:
             return "data system: lazy load config requires a source";
+        case Error::kConfig_BigSegments_NullStore:
+            return "big segments: store must not be null";
         case Error::kMax:
             break;
     }

libs/server-sdk/include/launchdarkly/server_side/big_segment_store_status.hpp

@@ -0,0 +1,77 @@
+#pragma once
+
+#include <launchdarkly/connection.hpp>
+
+#include <functional>
+#include <memory>
+#include <ostream>
+
+namespace launchdarkly::server_side {
+
+/**
+ * The current health of a Big Segments store, independent of any single
+ * context's membership.
+ */
+class BigSegmentStoreStatus {
+   public:
+    BigSegmentStoreStatus(bool available, bool stale);
+
+    /**
+     * True if the most recent store query or metadata poll succeeded. If false,
+     * Big Segments membership cannot currently be evaluated reliably.
+     */
+    [[nodiscard]] bool IsAvailable() const;
+
+    /**
+     * True if the store's data has not been updated within the configured
+     * stale-after threshold. The data may still be queried; it is just older
+     * than desired.
+     */
+    [[nodiscard]] bool IsStale() const;
+
+   private:
+    bool available_;
+    bool stale_;
+};
+
+bool operator==(BigSegmentStoreStatus const& a, BigSegmentStoreStatus const& b);
+bool operator!=(BigSegmentStoreStatus const& a, BigSegmentStoreStatus const& b);
+
+/**
+ * Interface for accessing and listening to the Big Segments store status.
+ */
+class IBigSegmentStoreStatusProvider {
+   public:
+    /**
+     * The current status of the Big Segments store. If no store is configured,
+     * reports unavailable and not stale.
+     */
+    [[nodiscard]] virtual BigSegmentStoreStatus Status() const = 0;
+
+    /**
+     * Listen to changes to the Big Segments store status. The handler is
+     * invoked only when the status changes, not on every metadata poll.
+     *
+     * @param handler Function which will be called with the new status.
+     * @return A IConnection which can be used to stop listening to the status.
+     */
+    virtual std::unique_ptr<IConnection> OnBigSegmentStoreStatusChange(
+        std::function<void(BigSegmentStoreStatus status)> handler) = 0;
+
+    virtual ~IBigSegmentStoreStatusProvider() = default;
+    IBigSegmentStoreStatusProvider(IBigSegmentStoreStatusProvider const&) =
+        delete;
+    IBigSegmentStoreStatusProvider(IBigSegmentStoreStatusProvider&&) = delete;
+    IBigSegmentStoreStatusProvider& operator=(
+        IBigSegmentStoreStatusProvider const&) = delete;
+    IBigSegmentStoreStatusProvider& operator=(
+        IBigSegmentStoreStatusProvider&&) = delete;
+
+   protected:
+    IBigSegmentStoreStatusProvider() = default;
+};
+
+std::ostream& operator<<(std::ostream& out,
+                         BigSegmentStoreStatus const& status);
+
+}  // namespace launchdarkly::server_side

libs/server-sdk/include/launchdarkly/server_side/client.hpp

@@ -7,6 +7,7 @@
 #include <launchdarkly/value.hpp>
 
 #include <launchdarkly/server_side/all_flags_state.hpp>
+#include <launchdarkly/server_side/big_segment_store_status.hpp>
 #include <launchdarkly/server_side/data_source_status.hpp>
 
 #include <chrono>
@@ -277,10 +278,11 @@ class IClient {
      * @return The variation for the selected context, or default_value if the
      * flag is disabled in the LaunchDarkly control panel
      */
-    virtual std::string StringVariation(Context const& ctx,
-                                        FlagKey const& key,
-                                        std::string default_value,
-                                        hooks::HookContext const& hook_context) = 0;
+    virtual std::string StringVariation(
+        Context const& ctx,
+        FlagKey const& key,
+        std::string default_value,
+        hooks::HookContext const& hook_context) = 0;
 
     /**
      * Returns the string value of a feature flag for a given flag key, in an
@@ -499,6 +501,14 @@ class IClient {
      */
     virtual IDataSourceStatusProvider& DataSourceStatus() = 0;
 
+    /**
+     * Returns an interface for querying the status of a Big Segment store and
+     * subscribing to status changes. If Big Segments are not configured, the
+     * provider reports the store as unavailable.
+     * @return A Big Segment store status provider.
+     */
+    virtual IBigSegmentStoreStatusProvider& BigSegmentStoreStatus() = 0;
+
     virtual ~IClient() = default;
     IClient(IClient const& item) = delete;
     IClient(IClient&& item) = delete;
@@ -574,10 +584,11 @@ class Client : public IClient {
                                 FlagKey const& key,
                                 std::string default_value) override;
 
-    std::string StringVariation(Context const& ctx,
-                                FlagKey const& key,
-                                std::string default_value,
-                                hooks::HookContext const& hook_context) override;
+    std::string StringVariation(
+        Context const& ctx,
+        FlagKey const& key,
+        std::string default_value,
+        hooks::HookContext const& hook_context) override;
 
     EvaluationDetail<std::string> StringVariationDetail(
         Context const& ctx,
@@ -650,6 +661,8 @@ class Client : public IClient {
 
     IDataSourceStatusProvider& DataSourceStatus() override;
 
+    IBigSegmentStoreStatusProvider& BigSegmentStoreStatus() override;
+
     /**
      * Returns the version of the SDK.
      * @return String representing version of the SDK.

libs/server-sdk/include/launchdarkly/server_side/config/builders/all_builders.hpp

@@ -12,6 +12,8 @@
 #include <launchdarkly/server_side/config/builders/data_system/data_system_builder.hpp>
 #include <launchdarkly/server_side/config/builders/data_system/lazy_load_builder.hpp>
 
+#include <launchdarkly/server_side/config/builders/big_segments_builder.hpp>
+
 namespace launchdarkly::server_side::config::builders {
 
 using SDK = launchdarkly::config::shared::ServerSDK;

…config/builders/big_segments_builder.hpp …config/builders/big_segments_builder.hpplibs/server-sdk/src/config/builders/big_segments_builder.hpp renamed to libs/server-sdk/include/launchdarkly/server_side/config/builders/big_segments_builder.hpp libs/server-sdk/src/config/builders/big_segments_builder.hpp renamed to libs/server-sdk/include/launchdarkly/server_side/config/builders/big_segments_builder.hpp

@@ -3,6 +3,10 @@
 #include <launchdarkly/server_side/config/built/big_segments_config.hpp>
 #include <launchdarkly/server_side/integrations/big_segments/ibig_segment_store.hpp>
 
+#include <launchdarkly/error.hpp>
+
+#include <tl/expected.hpp>
+
 #include <chrono>
 #include <cstddef>
 #include <memory>
@@ -68,12 +72,14 @@ class BigSegmentsBuilder {
     /**
      * @brief Resolves the configuration.
      *
+     * Returns an error if the store passed to the constructor was null.
+     *
      * If the configured @ref StatusPollInterval exceeds @ref StaleAfter,
      * 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;
+    [[nodiscard]] tl::expected<built::BigSegmentsConfig, Error> Build() const;
 
    private:
     std::shared_ptr<integrations::IBigSegmentStore> store_;

libs/server-sdk/include/launchdarkly/server_side/config/config.hpp

@@ -1,10 +1,12 @@
 #pragma once
 
 #include <launchdarkly/server_side/config/built/all_built.hpp>
+#include <launchdarkly/server_side/config/built/big_segments_config.hpp>
 #include <launchdarkly/server_side/config/built/data_system/data_system_config.hpp>
 #include <launchdarkly/server_side/hooks/hook.hpp>
 
 #include <memory>
+#include <optional>
 #include <vector>
 
 namespace launchdarkly::server_side {
@@ -17,6 +19,7 @@ struct Config {
            config::built::Events events,
            std::optional<std::string> application_tag,
            config::built::DataSystemConfig data_system_config,
+           std::optional<config::built::BigSegmentsConfig> big_segments,
            config::built::HttpProperties http_properties,
            std::vector<std::shared_ptr<hooks::Hook>> hooks);
 
@@ -31,6 +34,13 @@ struct Config {
 
     config::built::DataSystemConfig const& DataSystemConfig() const;
 
+    /**
+     * The Big Segments configuration, or nullopt if Big Segments were not
+     * enabled via ConfigBuilder::BigSegments.
+     */
+    [[nodiscard]] std::optional<config::built::BigSegmentsConfig> const&
+    BigSegments() const;
+
     [[nodiscard]] config::built::HttpProperties const& HttpProperties() const;
 
     [[nodiscard]] config::built::Logging const& Logging() const;
@@ -46,6 +56,7 @@ struct Config {
     std::optional<std::string> application_tag_;
     config::built::Events events_;
     config::built::DataSystemConfig data_system_config_;
+    std::optional<config::built::BigSegmentsConfig> big_segments_;
     config::built::HttpProperties http_properties_;
     std::vector<std::shared_ptr<hooks::Hook>> hooks_;
 };

libs/server-sdk/include/launchdarkly/server_side/config/config_builder.hpp

@@ -5,6 +5,7 @@
 #include <launchdarkly/server_side/hooks/hook.hpp>
 
 #include <memory>
+#include <optional>
 #include <vector>
 
 namespace launchdarkly::server_side {
@@ -50,6 +51,16 @@ class ConfigBuilder {
      */
     config::builders::DataSystemBuilder& DataSystem();
 
+    /**
+     * Configures the SDK's Big Segments behavior. Pass a BigSegmentsBuilder
+     * constructed with the Big Segments store to use. If never called, Big
+     * Segments are not enabled and flags referencing them evaluate as if the
+     * context were not a member.
+     * @param builder A configured BigSegmentsBuilder.
+     * @return Reference to this.
+     */
+    ConfigBuilder& BigSegments(config::builders::BigSegmentsBuilder builder);
+
     /**
      * Sets the SDK's networking configuration, using an HttpPropertiesBuilder.
      * The builder has methods for setting individual HTTP-related properties.
@@ -99,6 +110,7 @@ class ConfigBuilder {
     config::builders::AppInfoBuilder app_info_builder_;
     config::builders::EventsBuilder events_builder_;
     config::builders::DataSystemBuilder data_system_builder_;
+    std::optional<config::builders::BigSegmentsBuilder> big_segments_builder_;
     config::builders::HttpPropertiesBuilder http_properties_builder_;
     config::builders::LoggingBuilder logging_config_builder_;
     std::vector<std::shared_ptr<hooks::Hook>> hooks_;

libs/server-sdk/src/CMakeLists.txt

@@ -22,6 +22,7 @@ target_sources(${LIBNAME}
         client.cpp
         client_impl.cpp
         data_source_status.cpp
+        big_segment_store_status.cpp
         instance_id.hpp
         instance_id.cpp
         config/config.cpp
@@ -49,6 +50,8 @@ target_sources(${LIBNAME}
         data_components/big_segments/membership_cache.cpp
         data_components/big_segments/big_segment_store_wrapper.hpp
         data_components/big_segments/big_segment_store_wrapper.cpp
+        data_components/big_segments/big_segment_store_status_provider.hpp
+        data_components/big_segments/big_segment_store_status_provider.cpp
         data_interfaces/destination/itransactional_destination.hpp
         data_components/memory_store/memory_store.hpp
         data_components/memory_store/memory_store.cpp

libs/server-sdk/src/big_segment_store_status.cpp

@@ -0,0 +1,34 @@
+#include <launchdarkly/server_side/big_segment_store_status.hpp>
+
+namespace launchdarkly::server_side {
+
+BigSegmentStoreStatus::BigSegmentStoreStatus(bool const available,
+                                             bool const stale)
+    : available_(available), stale_(stale) {}
+
+bool BigSegmentStoreStatus::IsAvailable() const {
+    return available_;
+}
+
+bool BigSegmentStoreStatus::IsStale() const {
+    return stale_;
+}
+
+bool operator==(BigSegmentStoreStatus const& a,
+                BigSegmentStoreStatus const& b) {
+    return a.IsAvailable() == b.IsAvailable() && a.IsStale() == b.IsStale();
+}
+
+bool operator!=(BigSegmentStoreStatus const& a,
+                BigSegmentStoreStatus const& b) {
+    return !(a == b);
+}
+
+std::ostream& operator<<(std::ostream& out,
+                         BigSegmentStoreStatus const& status) {
+    out << "BigSegmentStoreStatus(available=" << std::boolalpha
+        << status.IsAvailable() << ", stale=" << status.IsStale() << ")";
+    return out;
+}
+
+}  // namespace launchdarkly::server_side