launchdarkly-server-sdk 8.11.2 → 8.11.3

data/lib/ldclient-rb/interfaces/data_system.rb

@@ -0,0 +1,755 @@
+# frozen_string_literal: true
+
+module LaunchDarkly
+  module Interfaces
+    module DataSystem
+      #
+      # EventName represents the name of an event that can be sent by the server for FDv2.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      module EventName
+        # Specifies that an object should be added to the data set with upsert semantics.
+        PUT_OBJECT = "put-object"
+
+        # Specifies that an object should be removed from the data set.
+        DELETE_OBJECT = "delete-object"
+
+        # Specifies the server's intent.
+        SERVER_INTENT = "server-intent"
+
+        # Specifies that all data required to bring the existing data set to a new version has been transferred.
+        PAYLOAD_TRANSFERRED = "payload-transferred"
+
+        # Keeps the connection alive.
+        HEARTBEAT = "heart-beat"
+
+        # Specifies that the server is about to close the connection.
+        GOODBYE = "goodbye"
+
+        # Specifies that an error occurred while serving the connection.
+        ERROR = "error"
+      end
+
+      #
+      # ObjectKind represents the kind of object.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      module ObjectKind
+        # Represents a feature flag.
+        FLAG = "flag"
+
+        # Represents a segment.
+        SEGMENT = "segment"
+      end
+
+      #
+      # ChangeType specifies if an object is being upserted or deleted.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      module ChangeType
+        # Represents an object being upserted.
+        PUT = "put"
+
+        # Represents an object being deleted.
+        DELETE = "delete"
+      end
+
+      #
+      # IntentCode represents the various intents that can be sent by the server.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      module IntentCode
+        # The server intends to send a full data set.
+        TRANSFER_FULL = "xfer-full"
+
+        # The server intends to send only the necessary changes to bring an existing data set up-to-date.
+        TRANSFER_CHANGES = "xfer-changes"
+
+        # The server intends to send no data (payload is up to date).
+        TRANSFER_NONE = "none"
+      end
+
+      #
+      # DataStoreMode represents the mode of operation of a Data Store in FDV2 mode.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      module DataStoreMode
+        # Indicates that the data store is read-only. Data will never be written back to the store by the SDK.
+        READ_ONLY = :read_only
+
+        # Indicates that the data store is read-write. Data from initializers/synchronizers may be written
+        # to the store as necessary.
+        READ_WRITE = :read_write
+      end
+
+      #
+      # Selector represents a particular snapshot of data.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      class Selector
+        # @return [String] The state
+        attr_reader :state
+
+        # @return [Integer] The version
+        attr_reader :version
+
+        #
+        # @param state [String] The state
+        # @param version [Integer] The version
+        #
+        def initialize(state: "", version: 0)
+          @state = state
+          @version = version
+        end
+
+        #
+        # Returns an empty Selector.
+        #
+        # @return [Selector]
+        #
+        def self.no_selector
+          Selector.new
+        end
+
+        #
+        # Returns true if the Selector has a value.
+        #
+        # @return [Boolean]
+        #
+        def defined?
+          self != Selector.no_selector
+        end
+
+        #
+        # Returns the event name for payload transfer.
+        #
+        # @return [String]
+        #
+        def name
+          EventName::PAYLOAD_TRANSFERRED
+        end
+
+        #
+        # Creates a new Selector from a state string and version.
+        #
+        # @param state [String] The state
+        # @param version [Integer] The version
+        # @return [Selector]
+        #
+        def self.new_selector(state, version)
+          Selector.new(state: state, version: version)
+        end
+
+        #
+        # Serializes the Selector to a Hash.
+        #
+        # @return [Hash]
+        #
+        def to_h
+          {
+            state: @state,
+            version: @version,
+          }
+        end
+
+        #
+        # Deserializes a Selector from a Hash.
+        #
+        # @param data [Hash] The hash representation
+        # @return [Selector]
+        # @raise [ArgumentError] if required fields are missing
+        #
+        def self.from_h(data)
+          state = data['state'] || data[:state]
+          version = data['version'] || data[:version]
+
+          raise ArgumentError, "Missing required fields in Selector" if state.nil? || version.nil?
+
+          Selector.new(state: state, version: version)
+        end
+
+        def ==(other)
+          other.is_a?(Selector) && @state == other.state && @version == other.version
+        end
+
+        def eql?(other)
+          self == other
+        end
+
+        def hash
+          [@state, @version].hash
+        end
+      end
+
+      #
+      # Change represents a change to a piece of data, such as an update or deletion.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      class Change
+        # @return [String] The action ({ChangeType})
+        attr_reader :action
+
+        # @return [String] The kind ({ObjectKind})
+        attr_reader :kind
+
+        # @return [String] The key
+        attr_reader :key
+
+        # @return [Integer] The version
+        attr_reader :version
+
+        # @return [Hash, nil] The object data (for PUT actions)
+        attr_reader :object
+
+        #
+        # @param action [String] The action type ({ChangeType})
+        # @param kind [String] The object kind ({ObjectKind})
+        # @param key [String] The key
+        # @param version [Integer] The version
+        # @param object [Hash, nil] The object data
+        #
+        def initialize(action:, kind:, key:, version:, object: nil)
+          @action = action
+          @kind = kind
+          @key = key
+          @version = version
+          @object = object
+        end
+      end
+
+      #
+      # ChangeSet represents a list of changes to be applied.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      class ChangeSet
+        # @return [String] The intent code ({IntentCode})
+        attr_reader :intent_code
+
+        # @return [Array<Change>] The changes
+        attr_reader :changes
+
+        # @return [Selector, nil] The selector
+        attr_reader :selector
+
+        #
+        # @param intent_code [String] The intent code ({IntentCode})
+        # @param changes [Array<Change>] The changes
+        # @param selector [Selector, nil] The selector
+        #
+        def initialize(intent_code:, changes:, selector:)
+          @intent_code = intent_code
+          @changes = changes
+          @selector = selector
+        end
+      end
+
+      #
+      # Basis represents the initial payload of data that a data source can provide.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      class Basis
+        # @return [ChangeSet] The change set
+        attr_reader :change_set
+
+        # @return [Boolean] Whether to persist
+        attr_reader :persist
+
+        # @return [String, nil] The environment ID
+        attr_reader :environment_id
+
+        #
+        # @param change_set [ChangeSet] The change set
+        # @param persist [Boolean] Whether to persist
+        # @param environment_id [String, nil] The environment ID
+        #
+        def initialize(change_set:, persist:, environment_id: nil)
+          @change_set = change_set
+          @persist = persist
+          @environment_id = environment_id
+        end
+      end
+
+      #
+      # Payload represents a payload delivered in a streaming response.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      class Payload
+        # @return [String] The payload ID
+        attr_reader :id
+
+        # @return [Integer] The target
+        attr_reader :target
+
+        # @return [String] The intent code ({IntentCode})
+        attr_reader :code
+
+        # @return [String] The reason
+        attr_reader :reason
+
+        #
+        # @param id [String] The payload ID
+        # @param target [Integer] The target
+        # @param code [String] The intent code ({IntentCode})
+        # @param reason [String] The reason
+        #
+        def initialize(id:, target:, code:, reason:)
+          @id = id
+          @target = target
+          @code = code
+          @reason = reason
+        end
+
+        #
+        # Serializes the Payload to a Hash.
+        #
+        # @return [Hash]
+        #
+        def to_h
+          {
+            id: @id,
+            target: @target,
+            intentCode: @code,
+            reason: @reason,
+          }
+        end
+
+        #
+        # Deserializes a Payload from a Hash.
+        #
+        # @param data [Hash] The hash representation
+        # @return [Payload]
+        # @raise [ArgumentError] if required fields are missing or invalid
+        #
+        def self.from_h(data)
+          intent_code = data['intentCode'] || data[:intentCode]
+
+          raise ArgumentError, "Invalid data for Payload: 'intentCode' key is missing or not a string" if intent_code.nil? || !intent_code.is_a?(String)
+
+          Payload.new(
+            id: data['id'] || data[:id] || "",
+            target: data['target'] || data[:target] || 0,
+            code: intent_code,
+            reason: data['reason'] || data[:reason] || ""
+          )
+        end
+      end
+
+      #
+      # ServerIntent represents the type of change associated with the payload.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      class ServerIntent
+        # @return [Payload] The payload
+        attr_reader :payload
+
+        #
+        # @param payload [Payload] The payload
+        #
+        def initialize(payload:)
+          @payload = payload
+        end
+
+        #
+        # Serializes the ServerIntent to a Hash.
+        #
+        # @return [Hash]
+        #
+        def to_h
+          {
+            payloads: [@payload.to_h],
+          }
+        end
+
+        #
+        # Deserializes a ServerIntent from a Hash.
+        #
+        # @param data [Hash] The hash representation
+        # @return [ServerIntent]
+        # @raise [ArgumentError] if required fields are missing or invalid
+        #
+        def self.from_h(data)
+          payloads = data['payloads'] || data[:payloads]
+
+          raise ArgumentError, "Invalid data for ServerIntent: 'payloads' key is missing or not an array" unless payloads.is_a?(Array)
+          raise ArgumentError, "Invalid data for ServerIntent: expected exactly one payload" unless payloads.length == 1
+
+          payload = payloads[0]
+          raise ArgumentError, "Invalid payload in ServerIntent: expected a hash" unless payload.is_a?(Hash)
+
+          ServerIntent.new(payload: Payload.from_h(payload))
+        end
+      end
+
+      #
+      # ChangeSetBuilder is a helper for constructing a ChangeSet.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      class ChangeSetBuilder
+        # @return [String, nil] The current intent ({IntentCode})
+        attr_accessor :intent
+
+        # @return [Array<Change>] The changes
+        attr_accessor :changes
+
+        def initialize
+          @intent = nil
+          @changes = []
+        end
+
+        #
+        # Represents an intent that the current data is up-to-date and doesn't require changes.
+        #
+        # @return [ChangeSet]
+        #
+        def self.no_changes
+          ChangeSet.new(
+            intent_code: IntentCode::TRANSFER_NONE,
+            selector: Selector.no_selector,
+            changes: []
+          )
+        end
+
+        #
+        # Returns an empty ChangeSet, useful for initializing without data.
+        #
+        # @param selector [Selector] The selector
+        # @return [ChangeSet]
+        #
+        def self.empty(selector)
+          ChangeSet.new(
+            intent_code: IntentCode::TRANSFER_FULL,
+            selector: selector,
+            changes: []
+          )
+        end
+
+        #
+        # Begins a new change set with a given intent.
+        #
+        # @param intent [String] The intent code ({IntentCode})
+        # @return [void]
+        #
+        def start(intent)
+          @intent = intent
+          @changes = []
+        end
+
+        #
+        # Ensures that the current ChangeSetBuilder is prepared to handle changes.
+        #
+        # @return [void]
+        # @raise [RuntimeError] if no server-intent has been set
+        #
+        def expect_changes
+          raise "changeset: cannot expect changes without a server-intent" if @intent.nil?
+
+          return unless @intent == IntentCode::TRANSFER_NONE
+
+          @intent = IntentCode::TRANSFER_CHANGES
+        end
+
+        #
+        # Clears any existing changes while preserving the current intent.
+        #
+        # @return [void]
+        #
+        def reset
+          @changes = []
+        end
+
+        #
+        # Identifies a changeset with a selector and returns the completed changeset.
+        #
+        # @param selector [Selector] The selector
+        # @return [ChangeSet]
+        # @raise [RuntimeError] if no server-intent has been set
+        #
+        def finish(selector)
+          raise "changeset: cannot complete without a server-intent" if @intent.nil?
+
+          changeset = ChangeSet.new(
+            intent_code: @intent,
+            selector: selector,
+            changes: @changes
+          )
+          @changes = []
+
+          # Once a full transfer has been processed, all future changes should be
+          # assumed to be changes. Flag delivery can override this behavior by
+          # sending a new server intent to any connected stream.
+          @intent = IntentCode::TRANSFER_CHANGES if @intent == IntentCode::TRANSFER_FULL
+
+          changeset
+        end
+
+        #
+        # Adds a new object to the changeset.
+        #
+        # @param kind [String] The object kind ({ObjectKind})
+        # @param key [String] The key
+        # @param version [Integer] The version
+        # @param obj [Hash] The object data
+        # @return [void]
+        #
+        def add_put(kind, key, version, obj)
+          @changes << Change.new(
+            action: ChangeType::PUT,
+            kind: kind,
+            key: key,
+            version: version,
+            object: obj
+          )
+        end
+
+        #
+        # Adds a deletion to the changeset.
+        #
+        # @param kind [String] The object kind ({ObjectKind})
+        # @param key [String] The key
+        # @param version [Integer] The version
+        # @return [void]
+        #
+        def add_delete(kind, key, version)
+          @changes << Change.new(
+            action: ChangeType::DELETE,
+            kind: kind,
+            key: key,
+            version: version
+          )
+        end
+      end
+
+      #
+      # Update represents the results of a synchronizer's ongoing sync method.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      class Update
+        # @return [Symbol] The data source state ({LaunchDarkly::Interfaces::DataSource::Status})
+        attr_reader :state
+
+        # @return [ChangeSet, nil] The change set
+        attr_reader :change_set
+
+        # @return [LaunchDarkly::Interfaces::DataSource::ErrorInfo, nil] Error information
+        attr_reader :error
+
+        # @return [Boolean] Whether to revert to FDv1
+        attr_reader :revert_to_fdv1
+
+        # @return [String, nil] The environment ID
+        attr_reader :environment_id
+
+        #
+        # @param state [Symbol] The data source state ({LaunchDarkly::Interfaces::DataSource::Status})
+        # @param change_set [ChangeSet, nil] The change set
+        # @param error [LaunchDarkly::Interfaces::DataSource::ErrorInfo, nil] Error information
+        # @param revert_to_fdv1 [Boolean] Whether to revert to FDv1
+        # @param environment_id [String, nil] The environment ID
+        #
+        def initialize(state:, change_set: nil, error: nil, revert_to_fdv1: false, environment_id: nil)
+          @state = state
+          @change_set = change_set
+          @error = error
+          @revert_to_fdv1 = revert_to_fdv1
+          @environment_id = environment_id
+        end
+      end
+
+      #
+      # SelectorStore represents a component capable of providing Selectors for data retrieval.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      module SelectorStore
+        #
+        # Returns a Selector object that defines the criteria for data retrieval.
+        #
+        # @return [Selector]
+        #
+        def selector
+          raise NotImplementedError, "#{self.class} must implement #selector"
+        end
+      end
+
+      #
+      # ReadOnlyStore represents a read-only store interface for retrieving data.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      module ReadOnlyStore
+        #
+        # Retrieves an item by kind and key.
+        #
+        # @param kind [LaunchDarkly::Impl::DataStore::DataKind] The data kind (e.g., LaunchDarkly::Impl::DataStore::FEATURES, LaunchDarkly::Impl::DataStore::SEGMENTS)
+        # @param key [String] The item key
+        # @return [Hash, nil] The item, or nil if not found or deleted
+        #
+        def get(kind, key)
+          raise NotImplementedError, "#{self.class} must implement #get"
+        end
+
+        #
+        # Retrieves all items of a given kind.
+        #
+        # @param kind [LaunchDarkly::Impl::DataStore::DataKind] The data kind (e.g., LaunchDarkly::Impl::DataStore::FEATURES, LaunchDarkly::Impl::DataStore::SEGMENTS)
+        # @return [Hash] Hash of keys to items (excluding deleted items)
+        #
+        def all(kind)
+          raise NotImplementedError, "#{self.class} must implement #all"
+        end
+
+        #
+        # Returns whether the store has been initialized.
+        #
+        # @return [Boolean]
+        #
+        def initialized?
+          raise NotImplementedError, "#{self.class} must implement #initialized?"
+        end
+      end
+
+      #
+      # Initializer represents a component capable of retrieving a single data result.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      module Initializer
+        #
+        # Returns the name of the initializer.
+        #
+        # @return [String]
+        #
+        def name
+          raise NotImplementedError, "#{self.class} must implement #name"
+        end
+
+        #
+        # Retrieves the initial data set for the data source.
+        #
+        # @param selector_store [SelectorStore] Provides the Selector
+        # @return [LaunchDarkly::Result<Basis, String>]
+        #
+        def fetch(selector_store)
+          raise NotImplementedError, "#{self.class} must implement #fetch"
+        end
+      end
+
+      #
+      # Synchronizer represents a component capable of synchronizing data from an external source.
+      #
+      # This type is not stable, and not subject to any backwards
+      # compatibility guarantees or semantic versioning. It is not suitable for production usage.
+      #
+      # Do not use it.
+      # You have been warned.
+      #
+      module Synchronizer
+        #
+        # Returns the name of the synchronizer.
+        #
+        # @return [String]
+        #
+        def name
+          raise NotImplementedError, "#{self.class} must implement #name"
+        end
+
+        #
+        # Begins the synchronization process, yielding Update objects.
+        #
+        # @param selector_store [SelectorStore] Provides the Selector
+        # @yieldparam update [Update] The update
+        # @return [void]
+        #
+        def sync(selector_store, &block)
+          raise NotImplementedError, "#{self.class} must implement #sync"
+        end
+
+        #
+        # Halts the synchronization process.
+        #
+        # @return [void]
+        #
+        def stop
+          raise NotImplementedError, "#{self.class} must implement #stop"
+        end
+      end
+    end
+  end
+end