launchdarkly-server-sdk 8.11.2-java → 8.12.0-java

data/lib/ldclient-rb/impl/data_system/protocolv2.rb

@@ -0,0 +1,264 @@
+require 'json'
+
+module LaunchDarkly
+  module Impl
+    module DataSystem
+      module ProtocolV2
+        #
+        # This module contains the protocol definitions and data types for the
+        # LaunchDarkly data system version 2 (FDv2).
+        #
+
+        #
+        # DeleteObject specifies the deletion of a particular object.
+        #
+        # This type is not stable, and not subject to any backwards
+        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+        #
+        class DeleteObject
+          # @return [Integer] The version
+          attr_reader :version
+
+          # @return [String] The object kind ({LaunchDarkly::Interfaces::DataSystem::ObjectKind})
+          attr_reader :kind
+
+          # @return [Symbol] The key
+          attr_reader :key
+
+          #
+          # @param version [Integer] The version
+          # @param kind [String] The object kind ({LaunchDarkly::Interfaces::DataSystem::ObjectKind})
+          # @param key [Symbol] The key
+          #
+          def initialize(version:, kind:, key:)
+            @version = version
+            @kind = kind
+            @key = key
+          end
+
+          #
+          # Returns the event name.
+          #
+          # @return [Symbol]
+          #
+          def name
+            LaunchDarkly::Interfaces::DataSystem::EventName::DELETE_OBJECT
+          end
+
+          #
+          # Serializes the DeleteObject to a JSON-compatible hash.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            {
+              version: @version,
+              kind: @kind,
+              key: @key,
+            }
+          end
+
+          #
+          # Deserializes a DeleteObject from a JSON-compatible hash.
+          #
+          # @param data [Hash] The hash representation
+          # @return [DeleteObject]
+          # @raise [ArgumentError] if required fields are missing
+          #
+          def self.from_h(data)
+            version = data[:version]
+            kind = data[:kind]
+            key = data[:key]
+
+            raise ArgumentError, "Missing required fields in DeleteObject" if version.nil? || kind.nil? || key.nil?
+
+            new(version: version, kind: kind, key: key.to_sym)
+          end
+        end
+
+        #
+        # PutObject specifies the addition of a particular object with upsert semantics.
+        #
+        # This type is not stable, and not subject to any backwards
+        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+        #
+        class PutObject
+          # @return [Integer] The version
+          attr_reader :version
+
+          # @return [String] The object kind ({LaunchDarkly::Interfaces::DataSystem::ObjectKind})
+          attr_reader :kind
+
+          # @return [Symbol] The key
+          attr_reader :key
+
+          # @return [Hash] The object data
+          attr_reader :object
+
+          #
+          # @param version [Integer] The version
+          # @param kind [String] The object kind ({LaunchDarkly::Interfaces::DataSystem::ObjectKind})
+          # @param key [Symbol] The key
+          # @param object [Hash] The object data
+          #
+          def initialize(version:, kind:, key:, object:)
+            @version = version
+            @kind = kind
+            @key = key
+            @object = object
+          end
+
+          #
+          # Returns the event name.
+          #
+          # @return [Symbol]
+          #
+          def name
+            LaunchDarkly::Interfaces::DataSystem::EventName::PUT_OBJECT
+          end
+
+          #
+          # Serializes the PutObject to a JSON-compatible hash.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            {
+              version: @version,
+              kind: @kind,
+              key: @key,
+              object: @object,
+            }
+          end
+
+          #
+          # Deserializes a PutObject from a JSON-compatible hash.
+          #
+          # @param data [Hash] The hash representation
+          # @return [PutObject]
+          # @raise [ArgumentError] if required fields are missing
+          #
+          def self.from_h(data)
+            version = data[:version]
+            kind = data[:kind]
+            key = data[:key]
+            object_data = data[:object]
+
+            raise ArgumentError, "Missing required fields in PutObject" if version.nil? || kind.nil? || key.nil? || object_data.nil?
+
+            new(version: version, kind: kind, key: key.to_sym, object: object_data)
+          end
+        end
+
+        #
+        # Goodbye represents a goodbye event.
+        #
+        # This type is not stable, and not subject to any backwards
+        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+        #
+        class Goodbye
+          # @return [String] The reason for goodbye
+          attr_reader :reason
+
+          # @return [Boolean] Whether the goodbye is silent
+          attr_reader :silent
+
+          # @return [Boolean] Whether this represents a catastrophic failure
+          attr_reader :catastrophe
+
+          #
+          # @param reason [String] The reason for goodbye
+          # @param silent [Boolean] Whether the goodbye is silent
+          # @param catastrophe [Boolean] Whether this represents a catastrophic failure
+          #
+          def initialize(reason:, silent:, catastrophe:)
+            @reason = reason
+            @silent = silent
+            @catastrophe = catastrophe
+          end
+
+          #
+          # Serializes the Goodbye to a JSON-compatible hash.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            {
+              reason: @reason,
+              silent: @silent,
+              catastrophe: @catastrophe,
+            }
+          end
+
+          #
+          # Deserializes a Goodbye event from a JSON-compatible hash.
+          #
+          # @param data [Hash] The hash representation
+          # @return [Goodbye]
+          # @raise [ArgumentError] if required fields are missing
+          #
+          def self.from_h(data)
+            reason = data[:reason]
+            silent = data[:silent]
+            catastrophe = data[:catastrophe]
+
+            raise ArgumentError, "Missing required fields in Goodbye" if reason.nil? || silent.nil? || catastrophe.nil?
+
+            new(reason: reason, silent: silent, catastrophe: catastrophe)
+          end
+        end
+
+        #
+        # Error represents an error event.
+        #
+        # This type is not stable, and not subject to any backwards
+        # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+        #
+        class Error
+          # @return [String] The payload ID
+          attr_reader :payload_id
+
+          # @return [String] The reason for the error
+          attr_reader :reason
+
+          #
+          # @param payload_id [String] The payload ID
+          # @param reason [String] The reason for the error
+          #
+          def initialize(payload_id:, reason:)
+            @payload_id = payload_id
+            @reason = reason
+          end
+
+          #
+          # Serializes the Error to a JSON-compatible hash.
+          #
+          # @return [Hash]
+          #
+          def to_h
+            {
+              payloadId: @payload_id,
+              reason: @reason,
+            }
+          end
+
+          #
+          # Deserializes an Error from a JSON-compatible hash.
+          #
+          # @param data [Hash] The hash representation
+          # @return [Error]
+          # @raise [ArgumentError] if required fields are missing
+          #
+          def self.from_h(data)
+            payload_id = data[:payloadId]
+            reason = data[:reason]
+
+            raise ArgumentError, "Missing required fields in Error" if payload_id.nil? || reason.nil?
+
+            new(payload_id: payload_id, reason: reason)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ldclient-rb/impl/data_system/streaming.rb

@@ -0,0 +1,401 @@
+# frozen_string_literal: true
+
+require "ldclient-rb/interfaces"
+require "ldclient-rb/interfaces/data_system"
+require "ldclient-rb/impl/data_system"
+require "ldclient-rb/impl/data_system/protocolv2"
+require "ldclient-rb/impl/data_system/polling"  # For shared constants
+require "ldclient-rb/impl/data_system/data_source_builder_common"
+require "ldclient-rb/impl/util"
+require "concurrent"
+require "json"
+require "uri"
+require "ld-eventsource"
+
+module LaunchDarkly
+  module Impl
+    module DataSystem
+      FDV2_STREAMING_ENDPOINT = "/sdk/stream"
+
+      # Allows for up to 5 minutes to elapse without any data sent across the stream.
+      # The heartbeats sent as comments on the stream will keep this from triggering.
+      STREAM_READ_TIMEOUT = 5 * 60
+
+      #
+      # StreamingDataSource is a Synchronizer that uses Server-Sent Events (SSE)
+      # to receive real-time updates from LaunchDarkly's Flag Delivery services.
+      #
+      class StreamingDataSource
+        include LaunchDarkly::Interfaces::DataSystem::Synchronizer
+
+        attr_reader :name
+
+        #
+        # @param sdk_key [String]
+        # @param http_config [HttpConfigOptions] HTTP connection settings
+        # @param initial_reconnect_delay [Float] Initial delay before reconnecting after an error
+        # @param config [LaunchDarkly::Config] Used for global header settings
+        #
+        def initialize(sdk_key, http_config, initial_reconnect_delay, config)
+          @sdk_key = sdk_key
+          @http_config = http_config
+          @initial_reconnect_delay = initial_reconnect_delay
+          @config = config
+          @logger = config.logger
+          @name = "StreamingDataSourceV2"
+          @sse = nil
+          @stopped = Concurrent::Event.new
+          @diagnostic_accumulator = nil
+          @connection_attempt_start_time = 0
+        end
+
+        #
+        # Sets the diagnostic accumulator for streaming initialization metrics.
+        #
+        # @param diagnostic_accumulator [LaunchDarkly::Impl::DiagnosticAccumulator]
+        #
+        def set_diagnostic_accumulator(diagnostic_accumulator)
+          @diagnostic_accumulator = diagnostic_accumulator
+        end
+
+        #
+        # sync begins the synchronization process for the data source, yielding
+        # Update objects until the connection is closed or an unrecoverable error
+        # occurs.
+        #
+        # @param ss [LaunchDarkly::Interfaces::DataSystem::SelectorStore]
+        # @yieldparam update [LaunchDarkly::Interfaces::DataSystem::Update]
+        #
+        def sync(ss)
+          @logger.info { "[LDClient] Starting StreamingDataSourceV2 synchronizer" }
+          log_connection_started
+
+          change_set_builder = LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder.new
+          envid = nil
+
+          base_uri = @http_config.base_uri + FDV2_STREAMING_ENDPOINT
+          headers = Impl::Util.default_http_headers(@sdk_key, @config)
+          opts = {
+            headers: headers,
+            read_timeout: STREAM_READ_TIMEOUT,
+            logger: @logger,
+            socket_factory: @http_config.socket_factory,
+            reconnect_time: @initial_reconnect_delay,
+          }
+
+          @sse = SSE::Client.new(base_uri, **opts) do |client|
+            client.on_connect do |headers|
+              # Extract environment ID and check for fallback on successful connection
+              if headers
+                envid = headers[LD_ENVID_HEADER] || envid
+
+                # Check for fallback header on connection
+                if headers[LD_FD_FALLBACK_HEADER] == 'true'
+                  log_connection_result(true)
+                  yield LaunchDarkly::Interfaces::DataSystem::Update.new(
+                    state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
+                    revert_to_fdv1: true,
+                    environment_id: envid
+                  )
+                  stop
+                end
+              end
+            end
+
+            client.on_event do |event|
+              begin
+                update = process_message(event, change_set_builder, envid)
+                if update
+                  log_connection_result(true)
+                  @connection_attempt_start_time = 0
+                  yield update
+                end
+              rescue JSON::ParserError => e
+                @logger.info { "[LDClient] Error parsing stream event; will restart stream: #{e}" }
+                yield LaunchDarkly::Interfaces::DataSystem::Update.new(
+                  state: LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
+                  error: LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+                    LaunchDarkly::Interfaces::DataSource::ErrorInfo::INVALID_DATA,
+                    0,
+                    e.to_s,
+                    Time.now
+                  ),
+                  environment_id: envid
+                )
+
+                # Re-raise the exception so the SSE implementation can catch it and restart the stream.
+                raise
+              rescue => e
+                @logger.info { "[LDClient] Error while handling stream event; will restart stream: #{e}" }
+                yield LaunchDarkly::Interfaces::DataSystem::Update.new(
+                  state: LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
+                  error: LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+                    LaunchDarkly::Interfaces::DataSource::ErrorInfo::UNKNOWN,
+                    0,
+                    e.to_s,
+                    Time.now
+                  ),
+                  environment_id: envid
+                )
+
+                # Re-raise the exception so the SSE implementation can catch it and restart the stream.
+                raise
+              end
+            end
+
+            client.on_error do |error|
+              log_connection_result(false)
+              fallback = false
+
+              # Extract envid and fallback from error headers if available
+              if error.respond_to?(:headers) && error.headers
+                envid = error.headers[LD_ENVID_HEADER] || envid
+
+                if error.headers[LD_FD_FALLBACK_HEADER] == 'true'
+                  fallback = true
+                end
+              end
+
+              update = handle_error(error, envid, fallback)
+              yield update if update
+            end
+
+            client.query_params do
+              selector = ss.selector
+              {
+                "filter" => @config.payload_filter_key,
+                "basis" => (selector.state if selector&.defined?),
+              }.compact
+            end
+          end
+
+          unless @sse
+            @logger.error { "[LDClient] Failed to create SSE client for streaming updates" }
+            return
+          end
+
+          # Client auto-starts in background thread. Wait here until stop() is called.
+          @stopped.wait
+        end
+
+        #
+        # Stops the streaming synchronizer.
+        #
+        def stop
+          @logger.info { "[LDClient] Stopping StreamingDataSourceV2 synchronizer" }
+          @sse&.close
+          @stopped.set
+        end
+
+        #
+        # Processes a single SSE message and returns an Update if applicable.
+        #
+        # @param message [SSE::StreamEvent]
+        # @param change_set_builder [LaunchDarkly::Interfaces::DataSystem::ChangeSetBuilder]
+        # @param envid [String, nil]
+        # @return [LaunchDarkly::Interfaces::DataSystem::Update, nil]
+        #
+        private def process_message(message, change_set_builder, envid)
+          event_type = message.type
+
+          # Handle heartbeat
+          if event_type == LaunchDarkly::Interfaces::DataSystem::EventName::HEARTBEAT
+            return nil
+          end
+
+          @logger.debug { "[LDClient] Stream received #{event_type} message: #{message.data}" }
+
+          case event_type
+          when LaunchDarkly::Interfaces::DataSystem::EventName::SERVER_INTENT
+            server_intent = LaunchDarkly::Interfaces::DataSystem::ServerIntent.from_h(JSON.parse(message.data, symbolize_names: true))
+            change_set_builder.start(server_intent.payload.code)
+
+            if server_intent.payload.code == LaunchDarkly::Interfaces::DataSystem::IntentCode::TRANSFER_NONE
+              change_set_builder.expect_changes
+              return LaunchDarkly::Interfaces::DataSystem::Update.new(
+                state: LaunchDarkly::Interfaces::DataSource::Status::VALID,
+                environment_id: envid
+              )
+            end
+            nil
+
+          when LaunchDarkly::Interfaces::DataSystem::EventName::PUT_OBJECT
+            put = LaunchDarkly::Impl::DataSystem::ProtocolV2::PutObject.from_h(JSON.parse(message.data, symbolize_names: true))
+            change_set_builder.add_put(put.kind, put.key, put.version, put.object)
+            nil
+
+          when LaunchDarkly::Interfaces::DataSystem::EventName::DELETE_OBJECT
+            delete_object = LaunchDarkly::Impl::DataSystem::ProtocolV2::DeleteObject.from_h(JSON.parse(message.data, symbolize_names: true))
+            change_set_builder.add_delete(delete_object.kind, delete_object.key, delete_object.version)
+            nil
+
+          when LaunchDarkly::Interfaces::DataSystem::EventName::GOODBYE
+            goodbye = LaunchDarkly::Impl::DataSystem::ProtocolV2::Goodbye.from_h(JSON.parse(message.data, symbolize_names: true))
+            unless goodbye.silent
+              @logger.error { "[LDClient] SSE server received error: #{goodbye.reason} (catastrophe: #{goodbye.catastrophe})" }
+            end
+            nil
+
+          when LaunchDarkly::Interfaces::DataSystem::EventName::ERROR
+            error = LaunchDarkly::Impl::DataSystem::ProtocolV2::Error.from_h(JSON.parse(message.data, symbolize_names: true))
+            @logger.error { "[LDClient] Error on #{error.payload_id}: #{error.reason}" }
+
+            # Reset any previous change events but continue with last server intent
+            change_set_builder.reset
+            nil
+
+          when LaunchDarkly::Interfaces::DataSystem::EventName::PAYLOAD_TRANSFERRED
+            selector = LaunchDarkly::Interfaces::DataSystem::Selector.from_h(JSON.parse(message.data, symbolize_names: true))
+            change_set = change_set_builder.finish(selector)
+
+            LaunchDarkly::Interfaces::DataSystem::Update.new(
+              state: LaunchDarkly::Interfaces::DataSource::Status::VALID,
+              change_set: change_set,
+              environment_id: envid
+            )
+
+          else
+            @logger.info { "[LDClient] Unexpected event found in stream: #{event_type}" }
+            nil
+          end
+        end
+
+        #
+        # Handles errors that occur during streaming.
+        #
+        # @param error [Exception]
+        # @param envid [String, nil]
+        # @param fallback [Boolean]
+        # @return [LaunchDarkly::Interfaces::DataSystem::Update, nil]
+        #
+        private def handle_error(error, envid, fallback)
+          return nil if @stopped.set?
+
+          update = nil
+
+          case error
+          when SSE::Errors::HTTPStatusError
+            error_info = LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+              LaunchDarkly::Interfaces::DataSource::ErrorInfo::ERROR_RESPONSE,
+              error.status,
+              Impl::Util.http_error_message(error.status, "stream connection", "will retry"),
+              Time.now
+            )
+
+            if fallback
+              update = LaunchDarkly::Interfaces::DataSystem::Update.new(
+                state: LaunchDarkly::Interfaces::DataSource::Status::OFF,
+                error: error_info,
+                revert_to_fdv1: true,
+                environment_id: envid
+              )
+              stop
+              return update
+            end
+
+            is_recoverable = Impl::Util.http_error_recoverable?(error.status)
+
+            update = LaunchDarkly::Interfaces::DataSystem::Update.new(
+              state: is_recoverable ? LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED : LaunchDarkly::Interfaces::DataSource::Status::OFF,
+              error: error_info,
+              environment_id: envid
+            )
+
+            unless is_recoverable
+              @logger.error { "[LDClient] #{error_info.message}" }
+              stop
+              return update
+            end
+
+            @logger.warn { "[LDClient] #{error_info.message}" }
+
+          when SSE::Errors::HTTPContentTypeError, SSE::Errors::HTTPProxyError, SSE::Errors::ReadTimeoutError
+            @logger.warn { "[LDClient] Network error on stream connection: #{error}, will retry" }
+
+            update = LaunchDarkly::Interfaces::DataSystem::Update.new(
+              state: LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
+              error: LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+                LaunchDarkly::Interfaces::DataSource::ErrorInfo::NETWORK_ERROR,
+                0,
+                error.to_s,
+                Time.now
+              ),
+              environment_id: envid
+            )
+
+          else
+            @logger.warn { "[LDClient] Unexpected error on stream connection: #{error}, will retry" }
+
+            update = LaunchDarkly::Interfaces::DataSystem::Update.new(
+              state: LaunchDarkly::Interfaces::DataSource::Status::INTERRUPTED,
+              error: LaunchDarkly::Interfaces::DataSource::ErrorInfo.new(
+                LaunchDarkly::Interfaces::DataSource::ErrorInfo::UNKNOWN,
+                0,
+                error.to_s,
+                Time.now
+              ),
+              environment_id: envid
+            )
+          end
+
+          update
+        end
+
+        private def log_connection_started
+          @connection_attempt_start_time = Impl::Util.current_time_millis
+        end
+
+        private def log_connection_result(is_success)
+          return unless @diagnostic_accumulator
+          return unless @connection_attempt_start_time > 0
+
+          current_time = Impl::Util.current_time_millis
+          elapsed = current_time - @connection_attempt_start_time
+          @diagnostic_accumulator.record_stream_init(@connection_attempt_start_time, !is_success, elapsed >= 0 ? elapsed : 0)
+          @connection_attempt_start_time = 0
+        end
+      end
+
+      #
+      # Builder for a StreamingDataSource.
+      #
+      class StreamingDataSourceBuilder
+        include DataSourceBuilderCommon
+
+        DEFAULT_BASE_URI = "https://stream.launchdarkly.com"
+        DEFAULT_INITIAL_RECONNECT_DELAY = 1
+
+        def initialize
+          # No initialization needed - defaults applied in build via nil-check
+        end
+
+        #
+        # Sets the initial delay before reconnecting after an error.
+        #
+        # @param delay [Float] Delay in seconds
+        # @return [StreamingDataSourceBuilder]
+        #
+        def initial_reconnect_delay(delay)
+          @initial_reconnect_delay = delay
+          self
+        end
+
+        #
+        # Builds the StreamingDataSource with the configured parameters.
+        #
+        # @param sdk_key [String]
+        # @param config [LaunchDarkly::Config]
+        # @return [StreamingDataSource]
+        #
+        def build(sdk_key, config)
+          http_opts = build_http_config
+          StreamingDataSource.new(
+            sdk_key, http_opts,
+            @initial_reconnect_delay || DEFAULT_INITIAL_RECONNECT_DELAY,
+            config
+          )
+        end
+      end
+    end
+  end
+end