parse-stack-next 4.5.0

data/lib/parse/live_query/configuration.rb

@@ -0,0 +1,224 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module LiveQuery
+    # Centralized configuration for LiveQuery client.
+    #
+    # @example Configure LiveQuery
+    #   Parse::LiveQuery.configure do |config|
+    #     config.url = "wss://your-server.com"
+    #     config.ping_interval = 20.0
+    #     config.logging_enabled = true
+    #   end
+    #
+    class Configuration
+      # Connection settings
+      # @return [String] WebSocket URL for LiveQuery server
+      attr_accessor :url
+
+      # @return [String] Parse application ID
+      attr_accessor :application_id
+
+      # @return [String] Parse client key
+      attr_accessor :client_key
+
+      # @return [String] Parse master key (optional)
+      attr_accessor :master_key
+
+      # @return [Boolean] automatically connect on client creation (default: true)
+      attr_accessor :auto_connect
+
+      # @return [Boolean] automatically reconnect on disconnect (default: true)
+      attr_accessor :auto_reconnect
+
+      # Health monitoring settings
+      # @return [Float] seconds between ping frames (default: 30.0)
+      attr_accessor :ping_interval
+
+      # @return [Float] seconds to wait for pong response (default: 10.0)
+      attr_accessor :pong_timeout
+
+      # Circuit breaker settings
+      # @return [Integer] failures before circuit opens (default: 5)
+      attr_accessor :circuit_failure_threshold
+
+      # @return [Float] seconds before circuit transitions to half-open (default: 60.0)
+      attr_accessor :circuit_reset_timeout
+
+      # Reconnection backoff settings
+      # @return [Float] initial reconnect delay in seconds (default: 1.0)
+      attr_accessor :initial_reconnect_interval
+
+      # @return [Float] maximum reconnect delay in seconds (default: 30.0)
+      attr_accessor :max_reconnect_interval
+
+      # @return [Float] reconnect delay multiplier (default: 1.5)
+      attr_accessor :reconnect_multiplier
+
+      # @return [Float] jitter factor for reconnect delay, 0.0-1.0 (default: 0.2)
+      attr_accessor :reconnect_jitter
+
+      # Event queue settings
+      # @return [Integer] maximum queued events before backpressure (default: 1000)
+      attr_accessor :event_queue_size
+
+      # @return [Symbol] backpressure strategy :block, :drop_oldest, :drop_newest (default: :drop_oldest)
+      attr_accessor :backpressure_strategy
+
+      # Security settings
+      # @return [Integer] maximum WebSocket message size in bytes (default: 1MB)
+      #   Prevents memory exhaustion from malicious oversized frames
+      attr_accessor :max_message_size
+
+      # @return [Integer] frame read timeout in seconds (default: 30)
+      #   Prevents indefinite blocking when reading from socket
+      attr_accessor :frame_read_timeout
+
+      # @return [Boolean] when false (default), refuse to derive a `ws://`
+      #   URL from an `http://` server URL on any non-loopback host. The
+      #   default `Parse::LiveQuery::Client#derive_websocket_url` path
+      #   silently picks `ws://` when the Parse server URL is `http://`,
+      #   carrying master keys and session tokens over a cleartext
+      #   socket. Set to `true` to explicitly opt into insecure
+      #   WebSocket transport (local development, container-internal
+      #   networks). Loopback hosts (`localhost`, `127.0.0.1`, `::1`)
+      #   are exempt and emit a warning instead.
+      attr_accessor :allow_insecure
+
+      # @return [Symbol, nil] minimum TLS version :TLSv1, :TLSv1_1, :TLSv1_2, :TLSv1_3 (default: :TLSv1_2)
+      #   Enforces minimum TLS version for WebSocket connections
+      attr_accessor :ssl_min_version
+
+      # @return [Symbol, nil] maximum TLS version :TLSv1, :TLSv1_1, :TLSv1_2, :TLSv1_3 (default: nil = highest available)
+      #   Caps the maximum TLS version (rarely needed, use for compatibility)
+      attr_accessor :ssl_max_version
+
+      # Map of TLS version symbols to OpenSSL constants
+      TLS_VERSION_MAP = {
+        TLSv1: OpenSSL::SSL::TLS1_VERSION,
+        TLSv1_1: OpenSSL::SSL::TLS1_1_VERSION,
+        TLSv1_2: OpenSSL::SSL::TLS1_2_VERSION,
+        TLSv1_3: OpenSSL::SSL::TLS1_3_VERSION,
+      }.freeze
+
+      # Valid TLS version symbols
+      VALID_TLS_VERSIONS = [nil, :TLSv1, :TLSv1_1, :TLSv1_2, :TLSv1_3].freeze
+
+      # Convert a TLS version symbol to OpenSSL constant
+      # @param version [Symbol, nil] TLS version symbol
+      # @return [Integer, nil] OpenSSL TLS version constant or nil
+      def self.tls_version_constant(version)
+        return nil if version.nil?
+        TLS_VERSION_MAP[version]
+      end
+
+      # Logging settings
+      # @return [Boolean] enable structured logging (default: false)
+      attr_accessor :logging_enabled
+
+      # @return [Symbol] log level :debug, :info, :warn, :error (default: :info)
+      attr_accessor :log_level
+
+      # @return [Logger, nil] custom logger instance (default: nil, uses STDOUT)
+      attr_accessor :logger
+
+      # Initialize with sensible defaults
+      def initialize
+        # Connection
+        @url = nil
+        @application_id = nil
+        @client_key = nil
+        @master_key = nil
+        @auto_connect = true
+        @auto_reconnect = true
+
+        # Health monitoring
+        @ping_interval = 30.0
+        @pong_timeout = 10.0
+
+        # Circuit breaker
+        @circuit_failure_threshold = 5
+        @circuit_reset_timeout = 60.0
+
+        # Reconnection backoff
+        @initial_reconnect_interval = 1.0
+        @max_reconnect_interval = 30.0
+        @reconnect_multiplier = 1.5
+        @reconnect_jitter = 0.2
+
+        # Event queue
+        @event_queue_size = 1000
+        @backpressure_strategy = :drop_oldest
+
+        # Security
+        @max_message_size = 1_048_576  # 1MB
+        @frame_read_timeout = 30       # 30 seconds
+        @ssl_min_version = :TLSv1_2    # Enforce modern TLS by default
+        @ssl_max_version = nil         # No maximum (use highest available)
+        @allow_insecure = false        # Refuse ws:// downgrade on non-loopback hosts
+
+        # Logging
+        @logging_enabled = false
+        @log_level = :info
+        @logger = nil
+      end
+
+      # Validate configuration
+      # @return [Array<String>] list of validation errors
+      def validate
+        errors = []
+        errors << "ping_interval must be positive" if @ping_interval && @ping_interval <= 0
+        errors << "pong_timeout must be positive" if @pong_timeout && @pong_timeout <= 0
+        errors << "circuit_failure_threshold must be positive" if @circuit_failure_threshold && @circuit_failure_threshold <= 0
+        errors << "event_queue_size must be positive" if @event_queue_size && @event_queue_size <= 0
+        errors << "reconnect_jitter must be between 0.0 and 1.0" if @reconnect_jitter && (@reconnect_jitter < 0.0 || @reconnect_jitter > 1.0)
+        errors << "backpressure_strategy must be :block, :drop_oldest, or :drop_newest" unless [:block, :drop_oldest, :drop_newest].include?(@backpressure_strategy)
+        errors << "max_message_size must be positive" if @max_message_size && @max_message_size <= 0
+        errors << "frame_read_timeout must be positive" if @frame_read_timeout && @frame_read_timeout <= 0
+        errors << "log_level must be :debug, :info, :warn, or :error" unless [:debug, :info, :warn, :error].include?(@log_level)
+
+        # SSL/TLS version validation
+        errors << "ssl_min_version must be nil, :TLSv1, :TLSv1_1, :TLSv1_2, or :TLSv1_3" unless VALID_TLS_VERSIONS.include?(@ssl_min_version)
+        errors << "ssl_max_version must be nil, :TLSv1, :TLSv1_1, :TLSv1_2, or :TLSv1_3" unless VALID_TLS_VERSIONS.include?(@ssl_max_version)
+
+        errors
+      end
+
+      # Check if configuration is valid
+      # @return [Boolean]
+      def valid?
+        validate.empty?
+      end
+
+      # Convert to hash
+      # @return [Hash]
+      def to_h
+        {
+          url: @url,
+          application_id: @application_id,
+          client_key: @client_key.nil? ? nil : "[REDACTED]",
+          master_key: @master_key.nil? ? nil : "[REDACTED]",
+          auto_connect: @auto_connect,
+          auto_reconnect: @auto_reconnect,
+          ping_interval: @ping_interval,
+          pong_timeout: @pong_timeout,
+          circuit_failure_threshold: @circuit_failure_threshold,
+          circuit_reset_timeout: @circuit_reset_timeout,
+          initial_reconnect_interval: @initial_reconnect_interval,
+          max_reconnect_interval: @max_reconnect_interval,
+          reconnect_multiplier: @reconnect_multiplier,
+          reconnect_jitter: @reconnect_jitter,
+          event_queue_size: @event_queue_size,
+          backpressure_strategy: @backpressure_strategy,
+          max_message_size: @max_message_size,
+          frame_read_timeout: @frame_read_timeout,
+          ssl_min_version: @ssl_min_version,
+          ssl_max_version: @ssl_max_version,
+          logging_enabled: @logging_enabled,
+          log_level: @log_level,
+        }
+      end
+    end
+  end
+end

data/lib/parse/live_query/event.rb

@@ -0,0 +1,115 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module LiveQuery
+    # Represents an event received from the LiveQuery server.
+    # Events are emitted when objects matching a subscription's query are
+    # created, updated, deleted, or enter/leave the query results.
+    #
+    # @example
+    #   subscription.on(:update) do |event|
+    #     puts "Object updated: #{event.object.id}"
+    #     puts "Original state: #{event.original&.to_h}"
+    #     puts "Event type: #{event.type}"
+    #   end
+    #
+    class Event
+      # @return [Symbol] the type of event (:create, :update, :delete, :enter, :leave)
+      attr_reader :type
+
+      # @return [Parse::Object] the object affected by this event (current state)
+      attr_reader :object
+
+      # @return [Parse::Object, nil] the original state of the object (for :update, :enter, :leave)
+      attr_reader :original
+
+      # @return [Integer] the subscription request ID this event belongs to
+      attr_reader :request_id
+
+      # @return [String] the Parse class name
+      attr_reader :class_name
+
+      # @return [Time] when the event was received
+      attr_reader :received_at
+
+      # @return [Hash] raw payload from the server
+      attr_reader :raw
+
+      # Create a new Event from a LiveQuery server message
+      # @param type [Symbol] event type
+      # @param class_name [String] Parse class name
+      # @param object_data [Hash] object data from server
+      # @param original_data [Hash, nil] original object data (for update/enter/leave)
+      # @param request_id [Integer] subscription request ID
+      # @param raw [Hash] raw server payload
+      def initialize(type:, class_name:, object_data:, original_data: nil, request_id:, raw: {})
+        @type = type.to_sym
+        @class_name = class_name
+        @request_id = request_id
+        @received_at = Time.now
+        @raw = raw
+
+        # Convert object data to Parse::Object instances
+        @object = build_object(class_name, object_data) if object_data
+        @original = build_object(class_name, original_data) if original_data
+      end
+
+      # @return [Boolean] true if this is a create event
+      def create?
+        type == :create
+      end
+
+      # @return [Boolean] true if this is an update event
+      def update?
+        type == :update
+      end
+
+      # @return [Boolean] true if this is a delete event
+      def delete?
+        type == :delete
+      end
+
+      # @return [Boolean] true if this is an enter event (object now matches query)
+      def enter?
+        type == :enter
+      end
+
+      # @return [Boolean] true if this is a leave event (object no longer matches query)
+      def leave?
+        type == :leave
+      end
+
+      # @return [String] the Parse object ID
+      def parse_object_id
+        object&.id
+      end
+
+      # @return [Hash] event as a hash
+      def to_h
+        {
+          type: type,
+          class_name: class_name,
+          object_id: parse_object_id,
+          request_id: request_id,
+          received_at: received_at,
+          object: object&.as_json,
+          original: original&.as_json,
+        }
+      end
+
+      private
+
+      # Build a Parse::Object from hash data
+      # @param class_name [String] Parse class name
+      # @param data [Hash] object attributes
+      # @return [Parse::Object]
+      def build_object(class_name, data)
+        return nil unless data.is_a?(Hash)
+
+        # Use Parse::Object.build which handles class lookup and data application
+        Parse::Object.build(data, class_name)
+      end
+    end
+  end
+end

data/lib/parse/live_query/event_queue.rb

@@ -0,0 +1,272 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "monitor"
+
+module Parse
+  module LiveQuery
+    # Error raised when event queue is full and strategy is :error
+    class EventQueueFullError < Error
+      def initialize(max_size)
+        super("Event queue full (max: #{max_size})")
+      end
+    end
+
+    # Bounded event queue with configurable backpressure strategies.
+    #
+    # Provides a buffer between the WebSocket reader thread and callback
+    # execution, preventing high-frequency events from overwhelming the system.
+    #
+    # Backpressure Strategies:
+    # - :block - Block enqueue until space available (can cause reader thread to block)
+    # - :drop_oldest - Drop oldest events when full (default)
+    # - :drop_newest - Drop incoming events when full
+    #
+    # @example
+    #   queue = EventQueue.new(max_size: 1000, strategy: :drop_oldest)
+    #   queue.start { |event| process_event(event) }
+    #   queue.enqueue(event)
+    #   queue.stop(drain: true)
+    #
+    class EventQueue
+      # Valid backpressure strategies
+      STRATEGIES = [:block, :drop_oldest, :drop_newest].freeze
+
+      # Default maximum queue size
+      DEFAULT_MAX_SIZE = 1000
+
+      # Default backpressure strategy
+      DEFAULT_STRATEGY = :drop_oldest
+
+      # @return [Integer] maximum queue size
+      attr_reader :max_size
+
+      # @return [Symbol] backpressure strategy
+      attr_reader :strategy
+
+      # @return [Integer] number of dropped events
+      attr_reader :dropped_count
+
+      # @return [Integer] total events enqueued
+      attr_reader :enqueued_count
+
+      # @return [Integer] total events processed
+      attr_reader :processed_count
+
+      # Create a new event queue
+      # @param max_size [Integer] maximum queue size
+      # @param strategy [Symbol] backpressure strategy (:block, :drop_oldest, :drop_newest)
+      # @param on_drop [Proc, nil] callback when events are dropped (receives event, reason)
+      def initialize(max_size: DEFAULT_MAX_SIZE, strategy: DEFAULT_STRATEGY, on_drop: nil)
+        unless STRATEGIES.include?(strategy)
+          raise ArgumentError, "Invalid strategy: #{strategy}. Must be one of #{STRATEGIES.inspect}"
+        end
+
+        @max_size = max_size
+        @strategy = strategy
+        @on_drop = on_drop
+
+        @queue = []
+        @monitor = Monitor.new
+        @condition = @monitor.new_cond
+        @running = false
+        @processor_thread = nil
+
+        @dropped_count = 0
+        @enqueued_count = 0
+        @processed_count = 0
+      end
+
+      # Start the event processor thread
+      # @yield [event] Block to process each event
+      # @return [void]
+      def start(&processor)
+        raise ArgumentError, "Processor block required" unless block_given?
+
+        @monitor.synchronize do
+          return if @running
+
+          @running = true
+          @processor_thread = Thread.new { process_loop(&processor) }
+          @processor_thread.abort_on_exception = false
+
+          Logging.debug("Event queue started", max_size: @max_size, strategy: @strategy)
+        end
+      end
+
+      # Stop the event processor
+      # @param drain [Boolean] process remaining events before stopping
+      # @param timeout [Float] seconds to wait for drain
+      # @return [void]
+      def stop(drain: true, timeout: 5.0)
+        @monitor.synchronize do
+          return unless @running
+
+          @running = false
+          @condition.broadcast
+        end
+
+        if drain && @processor_thread
+          @processor_thread.join(timeout)
+        end
+
+        @processor_thread&.kill
+        @processor_thread = nil
+
+        remaining = @monitor.synchronize { @queue.size }
+        Logging.debug("Event queue stopped", remaining: remaining, dropped: @dropped_count)
+      end
+
+      # Add an event to the queue
+      # @param event [Object] the event to enqueue
+      # @return [Boolean] true if enqueued, false if dropped
+      def enqueue(event)
+        @monitor.synchronize do
+          return false unless @running
+
+          if @queue.size >= @max_size
+            handle_backpressure(event)
+          else
+            @queue << event
+            @enqueued_count += 1
+            @condition.signal
+            true
+          end
+        end
+      end
+
+      # Current queue size
+      # @return [Integer]
+      def size
+        @monitor.synchronize { @queue.size }
+      end
+
+      # Check if queue is full
+      # @return [Boolean]
+      def full?
+        @monitor.synchronize { @queue.size >= @max_size }
+      end
+
+      # Check if queue is empty
+      # @return [Boolean]
+      def empty?
+        @monitor.synchronize { @queue.empty? }
+      end
+
+      # Check if queue is running
+      # @return [Boolean]
+      def running?
+        @monitor.synchronize { @running }
+      end
+
+      # Get queue statistics
+      # @return [Hash]
+      def stats
+        @monitor.synchronize do
+          {
+            size: @queue.size,
+            max_size: @max_size,
+            strategy: @strategy,
+            running: @running,
+            enqueued_count: @enqueued_count,
+            processed_count: @processed_count,
+            dropped_count: @dropped_count,
+            utilization: @max_size > 0 ? (@queue.size.to_f / @max_size * 100).round(1) : 0,
+          }
+        end
+      end
+
+      # Clear the queue
+      # @return [Integer] number of events cleared
+      def clear
+        @monitor.synchronize do
+          count = @queue.size
+          @queue.clear
+          count
+        end
+      end
+
+      private
+
+      # Main processing loop - runs in background thread
+      def process_loop
+        while @running
+          event = nil
+
+          @monitor.synchronize do
+            # Wait for events or stop signal
+            while @queue.empty? && @running
+              @condition.wait(1.0)
+            end
+
+            event = @queue.shift if @running || !@queue.empty?
+          end
+
+          if event
+            begin
+              yield event
+              @monitor.synchronize { @processed_count += 1 }
+            rescue StandardError => e
+              Logging.error("Event processing error", error: e)
+            end
+          end
+        end
+
+        # Drain remaining events if requested
+        drain_remaining { |e| yield e }
+      end
+
+      # Drain remaining events after stop
+      def drain_remaining
+        loop do
+          event = @monitor.synchronize { @queue.shift }
+          break unless event
+
+          begin
+            yield event
+            @monitor.synchronize { @processed_count += 1 }
+          rescue StandardError => e
+            Logging.error("Event drain error", error: e)
+          end
+        end
+      end
+
+      # Handle backpressure when queue is full
+      # @param event [Object] the event being enqueued
+      # @return [Boolean] true if enqueued, false if dropped
+      def handle_backpressure(event)
+        case @strategy
+        when :block
+          # Wait until space available
+          @condition.wait until @queue.size < @max_size || !@running
+          if @running
+            @queue << event
+            @enqueued_count += 1
+            true
+          else
+            false
+          end
+        when :drop_oldest
+          dropped = @queue.shift
+          @dropped_count += 1
+          notify_drop(dropped, :oldest)
+          @queue << event
+          @enqueued_count += 1
+          true
+        when :drop_newest
+          @dropped_count += 1
+          notify_drop(event, :newest)
+          false
+        end
+      end
+
+      # Notify callback of dropped event
+      def notify_drop(event, reason)
+        Logging.warn("Event dropped", reason: reason, queue_size: @queue.size)
+        @on_drop&.call(event, reason)
+      rescue StandardError => e
+        Logging.error("Drop callback error", error: e)
+      end
+    end
+  end
+end