chore: Add FDv2 Protocol Handling (#184)

This implements a protocol handling state machine for FDv2. The state
machine handles each event type for a connection and returns an action
the caller should take.

The expectation is that streaming/polling create a new protocol handler
per connection. As events are received they are pushed into the the
protocol handler. For each event the protocol handler will return an
action to take. An action could be emitting a changeset, preparing for a
disconnect, or logging an informative message.

Currently the protocol handler doesn't directly include any event or
logging capability and delegates all responsibility to the caller.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds an FDv2 protocol state machine that processes events and emits
changesets, replaces the polling event wrapper with a unified event
type, introduces intent code handling, and changes PutObject to store
raw JSON strings with comprehensive tests.
> 
> - **FDv2 Protocol/State Machine**:
> - Add `FDv2ProtocolHandler` with actions (`Changeset`, `Error`,
`Goodbye`, `None`, `InternalError`) and error types; handles
`server-intent`, `put-object`, `delete-object`, `payload-transferred`,
`goodbye`, `heartbeat` and emits `FDv2ChangeSet`.
> - New data models: `FDv2Change`, `FDv2ChangeSet` (Full/Partial/None),
`FDv2Selector`, and `FDv2EventTypes`.
> - **Event/Payload Model**:
> - Replace `FDv2PollEvent` with unified `FDv2Event` (type + raw JSON)
and `FDv2PollEventConverter`.
> - Add `IntentCode` enum + converter; update
`ServerIntent`/`ServerIntentPayload` to use it.
> - Change `PutObject.Object` from `JsonElement` to raw JSON `string`;
update read/write to preserve raw payload.
> - **Tests**:
> - Add `Internal/FDv2DataSources/FDv2ProtocolHandlerTest` covering
state transitions, errors, resets, and changeset emission.
> - Update `Internal/FDv2Payloads/FDv2PayloadsTest` for new event
wrapper, `IntentCode`, and `PutObject` serialization.
> - **Project**:
> - Add test folder include `Internal/FDv2DataSources/` in
`LaunchDarkly.ServerSdk.Tests.csproj`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
9c4653b. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

pkgs/sdk/server/src/Internal/FDv2DataSources/FDv2ChangeSet.cs

@@ -0,0 +1,139 @@
+using System;
+using System.Collections.Immutable;
+using System.Text.Json;
+
+namespace LaunchDarkly.Sdk.Server.Internal.FDv2DataSources
+{
+    /// <summary>
+    /// Represents the type of change operation.
+    /// </summary>
+    internal enum FDv2ChangeType
+    {
+        /// <summary>
+        /// Indicates an upsert operation (insert or update).
+        /// </summary>
+        Put,
+
+        /// <summary>
+        /// Indicates a delete operation.
+        /// </summary>
+        Delete
+    }
+
+    internal enum FDv2ChangeSetType
+    {
+        /// <summary>
+        /// Changeset represent a full payload to use as a basis.
+        /// </summary>
+        Full,
+
+        /// <summary>
+        /// Changeset represents a partial payload to be applied to a basis.
+        /// </summary>
+        Partial,
+
+        /// <summary>
+        /// A changeset which indicates that no changes should be made.
+        /// </summary>
+        None,
+    }
+
+    /// <summary>
+    /// Represents a single change to a data object.
+    /// </summary>
+    internal sealed class FDv2Change
+    {
+        /// <summary>
+        /// The type of change operation.
+        /// </summary>
+        public FDv2ChangeType Type { get; }
+
+        /// <summary>
+        /// The kind of object being changed ("flag" or "segment").
+        /// <para>
+        /// This field is required and will never be null.
+        /// </para>
+        /// </summary>
+        public string Kind { get; }
+
+        /// <summary>
+        /// The key identifying the object.
+        /// <para>
+        /// This field is required and will never be null.
+        /// </para>
+        /// </summary>
+        public string Key { get; }
+
+        /// <summary>
+        /// The version of the change.
+        /// </summary>
+        public int Version { get; }
+
+        /// <summary>
+        /// The raw JSON string representing the object data (only present for Put operations).
+        /// </summary>
+        public string Object { get; }
+
+        /// <summary>
+        /// Constructs a new Change.
+        /// </summary>
+        /// <param name="type">The type of change operation.</param>
+        /// <param name="kind">The kind of object being changed.</param>
+        /// <param name="key">The key identifying the object.</param>
+        /// <param name="version">The version of the change.</param>
+        /// <param name="obj">The raw JSON string representing the object data (required for Put operations).</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="kind"/> or <paramref name="key"/> is null.</exception>
+        public FDv2Change(FDv2ChangeType type, string kind, string key, int version, string obj = null)
+        {
+            Type = type;
+            Kind = kind ?? throw new ArgumentNullException(nameof(kind));
+            Key = key ?? throw new ArgumentNullException(nameof(key));
+            Version = version;
+            Object = obj;
+        }
+    }
+
+    /// <summary>
+    /// Represents a collection of changes with metadata about the intent and version.
+    /// </summary>
+    internal sealed class FDv2ChangeSet
+    {
+        /// <summary>
+        /// The intent code indicating how the server intends to transfer data.
+        /// </summary>
+        public FDv2ChangeSetType Type { get; }
+
+        /// <summary>
+        /// The list of changes in this changeset.
+        /// <para>
+        /// Null if there are no changes to apply.
+        /// </para>
+        /// </summary>
+        public ImmutableList<FDv2Change> Changes { get; }
+
+        /// <summary>
+        /// The selector (version identifier) for this changeset.
+        /// </summary>
+        public FDv2Selector FDv2Selector { get; }
+
+        /// <summary>
+        /// Constructs a new ChangeSet.
+        /// </summary>
+        /// <param name="type">The type of the changeset.</param>
+        /// <param name="changes">The list of changes.</param>
+        /// <param name="fDv2Selector">The selector.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="changes"/> is null.</exception>
+        public FDv2ChangeSet(FDv2ChangeSetType type, ImmutableList<FDv2Change> changes, FDv2Selector fDv2Selector)
+        {
+            Type = type;
+            Changes = changes ?? throw new ArgumentNullException(nameof(changes));
+            FDv2Selector = fDv2Selector;
+        }
+
+        /// <summary>
+        /// An empty changeset that indicates no changes are required.
+        /// </summary>
+        public static FDv2ChangeSet None { get; } =
+            new FDv2ChangeSet(FDv2ChangeSetType.None, ImmutableList<FDv2Change>.Empty, FDv2Selector.Empty);
+    }
+}

pkgs/sdk/server/src/Internal/FDv2DataSources/FDv2EventTypes.cs

@@ -0,0 +1,16 @@
+namespace LaunchDarkly.Sdk.Server.Internal.FDv2DataSources
+{
+    /// <summary>
+    /// Types of events that FDv2 can receive.
+    /// </summary>
+    internal static class FDv2EventTypes
+    {
+        public const string ServerIntent = "server-intent";
+        public const string PutObject = "put-object";
+        public const string DeleteObject = "delete-object";
+        public const string Error = "error";
+        public const string Goodbye = "goodbye";
+        public const string HeartBeat = "heartbeat";
+        public const string PayloadTransferred = "payload-transferred";
+    }
+}