refactor: define new Synchronizer and Initializer interfaces for FDv2 (#517)

This PR introduces `IFDv2Initializer` and `IFDv2Synchronizer`
interfaces.

I based this on the Java design, but with some significant changes:

```
FDv2SourceResult Next(std::chrono::milliseconds timeout,
                      data_model::Selector selector) 
```

1. I made this a blocking call with a timeout, because C++ doesn't have
any equivalent to "anyOf" for waiting on multiple racing promises, and
this was the cleanest alternative I could come up with.
2. It doesn't have the same "conditions" structure as Java, but it seems
like that's only used to implement timeouts, so I think we don't need
it, unless I missed something.
3. Rather than introduce a SelectorProvider interface for the
initializers/synchronizers to use, I am passing the selector directly
into `Next`. I think this is acceptable, as Next only return a single
result, which I think will only use one selector. This avoids having to
deal with the ownership complications a shared provider would entail.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk because it only adds new FDv2 interface headers and a result
type without changing existing runtime behavior; main risk is future
integration/implementation mismatches around the blocking `Next()`
timeout/selector contract.
> 
> **Overview**
> Introduces new FDv2 source abstractions for the server SDK: a one-shot
`IFDv2Initializer` (blocking `Run()` + `Close()`) and a continuous
`IFDv2Synchronizer` with a blocking `Next(timeout, selector)` API.
> 
> Adds `FDv2SourceResult` as a unified variant return type covering
successful changesets, transient/terminal errors, shutdown,
goodbye/rotation signals, and timeout-based wakeups (including an
`fdv1_fallback` flag where applicable). Also updates `.gitignore` to
ignore `.cache`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
ed22857. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: beekld

.gitignore

@@ -42,6 +42,7 @@ build-dynamic
 build-static-debug
 build-dynamic-debug
 cmake-build-*
+.cache
 
 # For Macs..
 .DS_Store

libs/server-sdk/src/data_interfaces/source/fdv2_source_result.hpp

@@ -0,0 +1,70 @@
+#pragma once
+
+#include <launchdarkly/data_model/fdv2_change.hpp>
+#include <launchdarkly/data_sources/data_source_status_error_info.hpp>
+
+#include <optional>
+#include <string>
+#include <variant>
+
+namespace launchdarkly::server_side::data_interfaces {
+
+/**
+ * Result returned by IFDv2Initializer::Run and IFDv2Synchronizer::Next.
+ *
+ * Mirrors Java's FDv2SourceResult.
+ */
+struct FDv2SourceResult {
+    using ErrorInfo = common::data_sources::DataSourceStatusErrorInfo;
+
+    /**
+     * A changeset was successfully received and is ready to apply.
+     */
+    struct ChangeSet {
+        data_model::FDv2ChangeSet change_set;
+        /** If true, the server signaled that the client should fall back to
+         * FDv1. */
+        bool fdv1_fallback;
+    };
+
+    /**
+     * A transient error occurred; the source may recover.
+     */
+    struct Interrupted {
+        ErrorInfo error;
+        bool fdv1_fallback;
+    };
+
+    /**
+     * A non-recoverable error occurred; the source should not be retried.
+     */
+    struct TerminalError {
+        ErrorInfo error;
+        bool fdv1_fallback;
+    };
+
+    /**
+     * The source was closed cleanly (via Close()).
+     */
+    struct Shutdown {};
+
+    /**
+     * The server sent a goodbye; the orchestrator should rotate sources.
+     */
+    struct Goodbye {
+        std::optional<std::string> reason;
+        bool fdv1_fallback;
+    };
+
+    /**
+     * Next() returned because the timeout expired before a result arrived.
+     */
+    struct Timeout {};
+
+    using Value = std::variant<ChangeSet, Interrupted, TerminalError, Shutdown,
+                               Goodbye, Timeout>;
+
+    Value value;
+};
+
+}  // namespace launchdarkly::server_side::data_interfaces

libs/server-sdk/src/data_interfaces/source/ifdv2_initializer.hpp

@@ -0,0 +1,46 @@
+#pragma once
+
+#include "fdv2_source_result.hpp"
+
+#include <string>
+
+namespace launchdarkly::server_side::data_interfaces {
+
+/**
+ * Defines a one-shot data source that runs to completion and returns a single
+ * result. Used during the initialization phase of FDv2, before handing off to
+ * an IFDv2Synchronizer.
+ */
+class IFDv2Initializer {
+   public:
+    /**
+     * Run the initializer to completion. Blocks until a result is available.
+     * Called at most once per instance.
+     *
+     * Close() may be called from another thread to unblock Run(), in which
+     * case Run() returns FDv2SourceResult::Shutdown.
+     */
+    virtual FDv2SourceResult Run() = 0;
+
+    /**
+     * Unblocks any in-progress Run() call, causing it to return
+     * FDv2SourceResult::Shutdown.
+     */
+    virtual void Close() = 0;
+
+    /**
+     * @return A display-suitable name of the initializer.
+     */
+    [[nodiscard]] virtual std::string const& Identity() const = 0;
+
+    virtual ~IFDv2Initializer() = default;
+    IFDv2Initializer(IFDv2Initializer const&) = delete;
+    IFDv2Initializer(IFDv2Initializer&&) = delete;
+    IFDv2Initializer& operator=(IFDv2Initializer const&) = delete;
+    IFDv2Initializer& operator=(IFDv2Initializer&&) = delete;
+
+   protected:
+    IFDv2Initializer() = default;
+};
+
+}  // namespace launchdarkly::server_side::data_interfaces

libs/server-sdk/src/data_interfaces/source/ifdv2_synchronizer.hpp

@@ -0,0 +1,62 @@
+#pragma once
+
+#include "fdv2_source_result.hpp"
+
+#include <launchdarkly/data_model/selector.hpp>
+
+#include <chrono>
+#include <string>
+
+namespace launchdarkly::server_side::data_interfaces {
+
+/**
+ * Defines a continuous data source that produces a stream of results. Used
+ * during the synchronization phase of FDv2, after initialization is complete.
+ *
+ * The stream is started lazily on the first call to Next(). The synchronizer
+ * runs until Close() is called.
+ */
+class IFDv2Synchronizer {
+   public:
+    /**
+     * Block until the next result is available or the timeout expires.
+     *
+     * On the first call, the synchronizer starts its underlying connection.
+     * Subsequent calls continue reading from the same connection.
+     *
+     * If the timeout expires before a result arrives, returns
+     * FDv2SourceResult::Timeout. The orchestrator uses this to evaluate
+     * fallback conditions.
+     *
+     * Close() may be called from another thread to unblock Next(), in which
+     * case Next() returns FDv2SourceResult::Shutdown.
+     *
+     * @param timeout  Maximum time to wait for the next result.
+     * @param selector The selector to send with the request, reflecting any
+     *                 changesets applied since the previous call.
+     */
+    virtual FDv2SourceResult Next(std::chrono::milliseconds timeout,
+                                  data_model::Selector selector) = 0;
+
+    /**
+     * Unblocks any in-progress Next() call, causing it to return
+     * FDv2SourceResult::Shutdown, and releases underlying resources.
+     */
+    virtual void Close() = 0;
+
+    /**
+     * @return A display-suitable name of the synchronizer.
+     */
+    [[nodiscard]] virtual std::string const& Identity() const = 0;
+
+    virtual ~IFDv2Synchronizer() = default;
+    IFDv2Synchronizer(IFDv2Synchronizer const&) = delete;
+    IFDv2Synchronizer(IFDv2Synchronizer&&) = delete;
+    IFDv2Synchronizer& operator=(IFDv2Synchronizer const&) = delete;
+    IFDv2Synchronizer& operator=(IFDv2Synchronizer&&) = delete;
+
+   protected:
+    IFDv2Synchronizer() = default;
+};
+
+}  // namespace launchdarkly::server_side::data_interfaces