chore: Add FDv2 payload types. (#183)

Adds payload types and support for JSON serialization/deserialization of
those types. These types are not used yet.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Introduces FDv2 payload types with custom JSON converters and an event
wrapper for partial deserialization, plus comprehensive tests.
> 
> - **Internal backend (FDv2 payloads)**:
> - Add models: `ServerIntent`, `ServerIntentPayload`, `PutObject`,
`DeleteObject`, `PayloadTransferred`, `Error`, `Goodbye`.
> - Implement `JsonConverter`s for each type with required-field
validation.
> - Add `FDv2PollEvent` wrapper and `FDv2PollEventConverter` supporting
lazy (`JsonElement`) data with typed accessors (`AsServerIntent`,
`AsPutObject`, etc.).
> - **Tests**:
> - Add unit tests covering round-trip serialization/deserialization,
missing-field errors, and end-to-end parsing of a full polling response
(flags and segments).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
110ebb3. 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/FDv2Payloads/DeleteObject.cs

@@ -0,0 +1,100 @@
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using static LaunchDarkly.Sdk.Internal.JsonConverterHelpers;
+
+namespace LaunchDarkly.Sdk.Server.Internal.FDv2Payloads
+{
+    /// <summary>
+    /// Represents the delete-object event, which contains a payload object that should be deleted.
+    /// </summary>
+    internal sealed class DeleteObject
+    {
+        /// <summary>
+        /// The minimum payload version this change applies to. May not match the target version of ServerIntent message.
+        /// </summary>
+        public int Version { get; }
+
+        /// <summary>
+        /// The kind of the object being deleted ("flag" or "segment").
+        /// <para>
+        /// This field is required and will never be null.
+        /// </para>
+        /// </summary>
+        public string Kind { get; }
+
+        /// <summary>
+        /// The identifier of the object.
+        /// <para>
+        /// This field is required and will never be null.
+        /// </para>
+        /// </summary>
+        public string Key { get; }
+
+        /// <summary>
+        /// Constructs a new DeleteObject.
+        /// </summary>
+        /// <param name="version">The minimum payload version this change applies to.</param>
+        /// <param name="kind">The kind of object being deleted ("flag" or "segment").</param>
+        /// <param name="key">The identifier of the object.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="kind"/> or <paramref name="key"/> is null.</exception>
+        public DeleteObject(int version, string kind, string key)
+        {
+            Version = version;
+            Kind = kind ?? throw new ArgumentNullException(nameof(kind));
+            Key = key ?? throw new ArgumentNullException(nameof(key));
+        }
+    }
+
+    /// <summary>
+    /// JsonConverter for DeleteObject events.
+    /// </summary>
+    internal sealed class DeleteObjectConverter : JsonConverter<DeleteObject>
+    {
+        private const string AttributeVersion = "version";
+        private const string AttributeKind = "kind";
+        private const string AttributeKey = "key";
+
+        internal static readonly DeleteObjectConverter Instance = new DeleteObjectConverter();
+
+        private static readonly string[] RequiredProperties =
+            { AttributeVersion, AttributeKind, AttributeKey };
+
+        public override DeleteObject Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            var version = 0;
+            string kind = null;
+            string key = null;
+
+            for (var obj = RequireObject(ref reader).WithRequiredProperties(RequiredProperties); obj.Next(ref reader);)
+            {
+                switch (obj.Name)
+                {
+                    case AttributeVersion:
+                        version = reader.GetInt32();
+                        break;
+                    case AttributeKind:
+                        kind = reader.GetString();
+                        break;
+                    case AttributeKey:
+                        key = reader.GetString();
+                        break;
+                    default:
+                        reader.Skip();
+                        break;
+                }
+            }
+
+            return new DeleteObject(version, kind, key);
+        }
+
+        public override void Write(Utf8JsonWriter writer, DeleteObject value, JsonSerializerOptions options)
+        {
+            writer.WriteStartObject();
+            writer.WriteNumber(AttributeVersion, value.Version);
+            writer.WriteString(AttributeKind, value.Kind);
+            writer.WriteString(AttributeKey, value.Key);
+            writer.WriteEndObject();
+        }
+    }
+}

pkgs/sdk/server/src/Internal/FDv2Payloads/Error.cs

@@ -0,0 +1,87 @@
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using static LaunchDarkly.Sdk.Internal.JsonConverterHelpers;
+
+namespace LaunchDarkly.Sdk.Server.Internal.FDv2Payloads
+{
+    /// <summary>
+    /// Represents the error event, which indicates an error encountered server-side affecting the payload transfer.
+    /// SDKs must discard partially transferred data. The SDK remains connected and expects the server to recover.
+    /// </summary>
+    internal sealed class Error
+    {
+        /// <summary>
+        /// The unique string identifier of the entity the error relates to.
+        /// </summary>
+        public string Id { get; }
+
+        /// <summary>
+        /// Human-readable reason the error occurred.
+        /// <para>
+        /// This field is required and will never be null.
+        /// </para>
+        /// </summary>
+        public string Reason { get; }
+
+        /// <summary>
+        /// Constructs a new Error.
+        /// </summary>
+        /// <param name="id">The unique string identifier of the entity the error relates to.</param>
+        /// <param name="reason">Human-readable reason the error occurred.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="reason"/> is null.</exception>
+        public Error(string id, string reason)
+        {
+            Id = id;
+            Reason = reason ?? throw new ArgumentNullException(nameof(reason));
+        }
+    }
+
+    /// <summary>
+    /// JsonConverter for Error events.
+    /// </summary>
+    internal sealed class ErrorConverter : JsonConverter<Error>
+    {
+        private const string AttributeId = "id";
+        private const string AttributeReason = "reason";
+
+        internal static readonly ErrorConverter Instance = new ErrorConverter();
+        private static readonly string[] RequiredProperties = { AttributeReason };
+
+        public override Error Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            string id = null;
+            string reason = null;
+
+            for (var obj = RequireObject(ref reader).WithRequiredProperties(RequiredProperties); obj.Next(ref reader);)
+            {
+                switch (obj.Name)
+                {
+                    case AttributeId:
+                        id = reader.GetString();
+                        break;
+                    case AttributeReason:
+                        reason = reader.GetString();
+                        break;
+                    default:
+                        reader.Skip();
+                        break;
+                }
+            }
+
+            return new Error(id, reason);
+        }
+
+        public override void Write(Utf8JsonWriter writer, Error value, JsonSerializerOptions options)
+        {
+            writer.WriteStartObject();
+            if (value.Id != null)
+            {
+                writer.WriteString(AttributeId, value.Id);
+            }
+
+            writer.WriteString(AttributeReason, value.Reason);
+            writer.WriteEndObject();
+        }
+    }
+}

pkgs/sdk/server/src/Internal/FDv2Payloads/FDv2PollEvent.cs

@@ -0,0 +1,141 @@
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using static LaunchDarkly.Sdk.Internal.JsonConverterHelpers;
+
+namespace LaunchDarkly.Sdk.Server.Internal.FDv2Payloads
+{
+    /// <summary>
+    /// Represents a FDv2 polling event with partial deserialization.
+    /// The event type is deserialized, but the data is kept as a JsonElement for lazy deserialization.
+    /// </summary>
+    internal sealed class FDv2PollEvent
+    {
+        /// <summary>
+        /// The event type string (e.g., "server-intent", "put-object", "delete-object", etc.).
+        /// </summary>
+        public string EventType { get; }
+
+        /// <summary>
+        /// The raw JSON element representing the event data.
+        /// This should be deserialized based on the EventType.
+        /// </summary>
+        public JsonElement Data { get; }
+
+        public FDv2PollEvent(string eventType, JsonElement data)
+        {
+            EventType = eventType;
+            Data = data;
+        }
+
+        /// <summary>
+        /// Deserializes the Data element as a ServerIntent.
+        /// </summary>
+        public ServerIntent AsServerIntent()
+        {
+            return JsonSerializer.Deserialize<ServerIntent>(Data.GetRawText(), GetSerializerOptions());
+        }
+
+        /// <summary>
+        /// Deserializes the Data element as a PutObject.
+        /// </summary>
+        public PutObject AsPutObject()
+        {
+            return JsonSerializer.Deserialize<PutObject>(Data.GetRawText(), GetSerializerOptions());
+        }
+
+        /// <summary>
+        /// Deserializes the Data element as a DeleteObject.
+        /// </summary>
+        public DeleteObject AsDeleteObject()
+        {
+            return JsonSerializer.Deserialize<DeleteObject>(Data.GetRawText(), GetSerializerOptions());
+        }
+
+        /// <summary>
+        /// Deserializes the Data element as a PayloadTransferred.
+        /// </summary>
+        public PayloadTransferred AsPayloadTransferred()
+        {
+            return JsonSerializer.Deserialize<PayloadTransferred>(Data.GetRawText(), GetSerializerOptions());
+        }
+
+        /// <summary>
+        /// Deserializes the Data element as an Error.
+        /// </summary>
+        public Error AsError()
+        {
+            return JsonSerializer.Deserialize<Error>(Data.GetRawText(), GetSerializerOptions());
+        }
+
+        /// <summary>
+        /// Deserializes the Data element as a Goodbye.
+        /// </summary>
+        public Goodbye AsGoodbye()
+        {
+            return JsonSerializer.Deserialize<Goodbye>(Data.GetRawText(), GetSerializerOptions());
+        }
+
+        private static JsonSerializerOptions GetSerializerOptions()
+        {
+            var options = new JsonSerializerOptions();
+            options.Converters.Add(ServerIntentConverter.Instance);
+            options.Converters.Add(PutObjectConverter.Instance);
+            options.Converters.Add(DeleteObjectConverter.Instance);
+            options.Converters.Add(PayloadTransferredConverter.Instance);
+            options.Converters.Add(ErrorConverter.Instance);
+            options.Converters.Add(GoodbyeConverter.Instance);
+            return options;
+        }
+    }
+
+    /// <summary>
+    /// JsonConverter for FDv2PollEvent wrapper with partial deserialization.
+    /// </summary>
+    internal sealed class FDv2PollEventConverter : JsonConverter<FDv2PollEvent>
+    {
+        private const string AttributeEvent = "event";
+        private const string AttributeData = "data";
+
+        internal static readonly FDv2PollEventConverter Instance = new FDv2PollEventConverter();
+        private static readonly string[] RequiredProperties = new string[] { AttributeEvent, AttributeData };
+
+        public override FDv2PollEvent Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            string eventType = null;
+            JsonElement data = default;
+
+            for (var obj = RequireObject(ref reader).WithRequiredProperties(RequiredProperties); obj.Next(ref reader);)
+            {
+                switch (obj.Name)
+                {
+                    case AttributeEvent:
+                        eventType = reader.GetString();
+                        break;
+                    case AttributeData:
+                        // Store the raw JSON element for later deserialization based on the event type
+                        data = JsonElement.ParseValue(ref reader);
+                        break;
+                    default:
+                        reader.Skip();
+                        break;
+                }
+            }
+
+            return new FDv2PollEvent(eventType, data);
+        }
+
+        public override void Write(Utf8JsonWriter writer, FDv2PollEvent value, JsonSerializerOptions options)
+        {
+            writer.WriteStartObject();
+            if (value.EventType != null)
+            {
+                writer.WriteString(AttributeEvent, value.EventType);
+            }
+
+            writer.WritePropertyName(AttributeData);
+            value.Data.WriteTo(writer);
+            writer.WriteEndObject();
+        }
+    }
+}

pkgs/sdk/server/src/Internal/FDv2Payloads/Goodbye.cs

@@ -0,0 +1,68 @@
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using static LaunchDarkly.Sdk.Internal.JsonConverterHelpers;
+
+namespace LaunchDarkly.Sdk.Server.Internal.FDv2Payloads
+{
+    /// <summary>
+    /// Represents the goodbye event, which indicates that the server is about to disconnect.
+    /// </summary>
+    internal sealed class Goodbye
+    {
+        /// <summary>
+        /// Reason for the disconnection.
+        /// </summary>
+        public string Reason { get; }
+
+        /// <summary>
+        /// Constructs a new Goodbye.
+        /// </summary>
+        /// <param name="reason">Reason for the disconnection.</param>
+        public Goodbye(string reason)
+        {
+            Reason = reason;
+        }
+    }
+
+    /// <summary>
+    /// JsonConverter for Goodbye events.
+    /// </summary>
+    internal sealed class GoodbyeConverter : JsonConverter<Goodbye>
+    {
+        private const string AttributeReason = "reason";
+
+        internal static readonly GoodbyeConverter Instance = new GoodbyeConverter();
+
+        public override Goodbye Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            string reason = null;
+
+            for (var obj = RequireObject(ref reader); obj.Next(ref reader);)
+            {
+                switch (obj.Name)
+                {
+                    case AttributeReason:
+                        reason = reader.GetString();
+                        break;
+                    default:
+                        reader.Skip();
+                        break;
+                }
+            }
+
+            return new Goodbye(reason);
+        }
+
+        public override void Write(Utf8JsonWriter writer, Goodbye value, JsonSerializerOptions options)
+        {
+            writer.WriteStartObject();
+            if (value.Reason != null)
+            {
+                writer.WriteString(AttributeReason, value.Reason);
+            }
+
+            writer.WriteEndObject();
+        }
+    }
+}