parse-stack-next 4.5.0

data/lib/parse/live_query/health_monitor.rb

@@ -0,0 +1,214 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "monitor"
+
+module Parse
+  module LiveQuery
+    # Monitors WebSocket connection health via ping/pong and activity tracking.
+    #
+    # Schedules periodic ping frames and detects stale connections when pong
+    # responses are not received within the configured timeout.
+    #
+    # @example
+    #   monitor = HealthMonitor.new(client: client, ping_interval: 30.0, pong_timeout: 10.0)
+    #   monitor.start
+    #   # ... connection activity ...
+    #   monitor.stop
+    #
+    class HealthMonitor
+      # Default ping interval in seconds
+      DEFAULT_PING_INTERVAL = 30.0
+
+      # Default pong timeout in seconds
+      DEFAULT_PONG_TIMEOUT = 10.0
+
+      # @return [Float] seconds between ping frames
+      attr_reader :ping_interval
+
+      # @return [Float] seconds to wait for pong response
+      attr_reader :pong_timeout
+
+      # @return [Time, nil] when connection was established
+      attr_reader :connection_established_at
+
+      # @return [Time, nil] last activity (any message received)
+      attr_reader :last_activity_at
+
+      # @return [Time, nil] last pong received
+      attr_reader :last_pong_at
+
+      # Create a new health monitor
+      # @param client [Client] the LiveQuery client to monitor
+      # @param ping_interval [Float] seconds between pings
+      # @param pong_timeout [Float] seconds to wait for pong
+      def initialize(client:, ping_interval: DEFAULT_PING_INTERVAL, pong_timeout: DEFAULT_PONG_TIMEOUT)
+        @client = client
+        @ping_interval = ping_interval
+        @pong_timeout = pong_timeout
+
+        @monitor = Monitor.new
+        @running = false
+        @ping_thread = nil
+        @awaiting_pong = false
+
+        @connection_established_at = nil
+        @last_activity_at = nil
+        @last_pong_at = nil
+      end
+
+      # Start the health monitoring thread
+      # @return [void]
+      def start
+        @monitor.synchronize do
+          return if @running
+
+          @running = true
+          @connection_established_at = Time.now
+          @last_activity_at = Time.now
+          @last_pong_at = Time.now
+          @awaiting_pong = false
+
+          @ping_thread = Thread.new { ping_loop }
+          @ping_thread.abort_on_exception = false
+
+          Logging.debug("Health monitor started", ping_interval: @ping_interval, pong_timeout: @pong_timeout)
+        end
+      end
+
+      # Stop the health monitoring thread
+      # @return [void]
+      def stop
+        @monitor.synchronize do
+          return unless @running
+
+          @running = false
+          @ping_thread&.kill
+          @ping_thread = nil
+          @awaiting_pong = false
+
+          Logging.debug("Health monitor stopped")
+        end
+      end
+
+      # Record that a pong was received
+      # @return [void]
+      def record_pong
+        @monitor.synchronize do
+          @last_pong_at = Time.now
+          @last_activity_at = Time.now
+          @awaiting_pong = false
+        end
+        Logging.debug("Pong received")
+      end
+
+      # Record that activity was received (any message)
+      # @return [void]
+      def record_activity
+        @monitor.synchronize do
+          @last_activity_at = Time.now
+        end
+      end
+
+      # Check if monitor is running
+      # @return [Boolean]
+      def running?
+        @monitor.synchronize { @running }
+      end
+
+      # Check if connection is stale (no pong within timeout)
+      # @return [Boolean]
+      def stale?
+        @monitor.synchronize do
+          return false unless @awaiting_pong
+          return false unless @last_pong_at
+
+          Time.now - @last_pong_at > (@ping_interval + @pong_timeout)
+        end
+      end
+
+      # Check if connection appears healthy
+      # @return [Boolean]
+      def healthy?
+        @monitor.synchronize do
+          return false unless @running
+          return true unless @last_activity_at
+
+          # Consider unhealthy if no activity for 2x ping interval + pong timeout
+          max_idle = (@ping_interval * 2) + @pong_timeout
+          Time.now - @last_activity_at < max_idle
+        end
+      end
+
+      # Seconds since last activity
+      # @return [Float, nil]
+      def seconds_since_activity
+        @monitor.synchronize do
+          return nil unless @last_activity_at
+          Time.now - @last_activity_at
+        end
+      end
+
+      # Seconds since last pong
+      # @return [Float, nil]
+      def seconds_since_pong
+        @monitor.synchronize do
+          return nil unless @last_pong_at
+          Time.now - @last_pong_at
+        end
+      end
+
+      # Get health information as a hash
+      # @return [Hash]
+      def health_info
+        @monitor.synchronize do
+          {
+            running: @running,
+            healthy: healthy?,
+            stale: stale?,
+            awaiting_pong: @awaiting_pong,
+            connection_established_at: @connection_established_at,
+            last_activity_at: @last_activity_at,
+            last_pong_at: @last_pong_at,
+            seconds_since_activity: seconds_since_activity,
+            seconds_since_pong: seconds_since_pong,
+            ping_interval: @ping_interval,
+            pong_timeout: @pong_timeout,
+          }
+        end
+      end
+
+      private
+
+      # Main ping loop - runs in background thread
+      def ping_loop
+        while @running
+          begin
+            sleep @ping_interval
+            break unless @running
+
+            # Send ping and mark as awaiting pong
+            @monitor.synchronize { @awaiting_pong = true }
+
+            Logging.debug("Sending ping")
+            @client.send(:send_ping)
+
+            # Wait for pong timeout
+            sleep @pong_timeout
+            break unless @running
+
+            # Check if pong was received
+            if @awaiting_pong
+              Logging.warn("Connection stale: no pong received", seconds_waited: @ping_interval + @pong_timeout)
+              @client.send(:handle_stale_connection)
+              break
+            end
+          rescue StandardError => e
+            Logging.error("Ping loop error", error: e)
+            break
+          end
+        end
+      end
+    end
+  end
+end

data/lib/parse/live_query/logging.rb

@@ -0,0 +1,149 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "logger"
+
+module Parse
+  module LiveQuery
+    # Structured logging module for LiveQuery.
+    #
+    # Provides leveled logging with context support. Disabled by default.
+    #
+    # @example Enable logging
+    #   Parse::LiveQuery::Logging.enabled = true
+    #   Parse::LiveQuery::Logging.log_level = :debug
+    #
+    # @example Use custom logger
+    #   Parse::LiveQuery::Logging.logger = Rails.logger
+    #
+    module Logging
+      # Log levels in order of verbosity
+      LEVELS = [:debug, :info, :warn, :error].freeze
+
+      class << self
+        # @return [Boolean] whether logging is enabled
+        attr_accessor :enabled
+
+        # @return [Logger, nil] custom logger instance
+        attr_accessor :logger
+
+        # @return [Symbol] current log level (:debug, :info, :warn, :error)
+        attr_reader :log_level
+
+        # Set log level with validation
+        # @param level [Symbol] one of :debug, :info, :warn, :error
+        def log_level=(level)
+          unless LEVELS.include?(level)
+            raise ArgumentError, "Invalid log level: #{level}. Must be one of #{LEVELS.inspect}"
+          end
+          @log_level = level
+        end
+
+        # Get or create the default logger
+        # @return [Logger]
+        def default_logger
+          @default_logger ||= begin
+              l = ::Logger.new($stdout)
+              l.progname = "Parse::LiveQuery"
+              l.formatter = proc do |severity, datetime, progname, msg|
+                "[#{datetime.strftime("%Y-%m-%d %H:%M:%S")}] #{severity} -- #{progname}: #{msg}\n"
+              end
+              l
+            end
+        end
+
+        # Get the current logger (custom or default)
+        # @return [Logger]
+        def current_logger
+          logger || default_logger
+        end
+
+        # Log a debug message
+        # @param message [String] the message
+        # @param context [Hash] optional context data
+        def debug(message, **context)
+          log(:debug, message, context)
+        end
+
+        # Log an info message
+        # @param message [String] the message
+        # @param context [Hash] optional context data
+        def info(message, **context)
+          log(:info, message, context)
+        end
+
+        # Log a warning message
+        # @param message [String] the message
+        # @param context [Hash] optional context data
+        def warn(message, **context)
+          log(:warn, message, context)
+        end
+
+        # Log an error message
+        # @param message [String] the message
+        # @param context [Hash] optional context data
+        def error(message, **context)
+          log(:error, message, context)
+        end
+
+        # Reset logging configuration to defaults
+        def reset!
+          @enabled = false
+          @logger = nil
+          @log_level = :info
+          @default_logger = nil
+        end
+
+        private
+
+        # Check if a level should be logged based on current log_level
+        # @param level [Symbol] the level to check
+        # @return [Boolean]
+        def should_log?(level)
+          return false unless enabled
+
+          current_level_index = LEVELS.index(@log_level || :info)
+          message_level_index = LEVELS.index(level)
+          message_level_index >= current_level_index
+        end
+
+        # Internal log method
+        # @param level [Symbol] log level
+        # @param message [String] the message
+        # @param context [Hash] context data
+        def log(level, message, context)
+          return unless should_log?(level)
+
+          formatted = if context.any?
+              "#{message} #{format_context(context)}"
+            else
+              message
+            end
+
+          current_logger.send(level, formatted)
+        end
+
+        # Format context hash for logging
+        # @param context [Hash] context data
+        # @return [String]
+        def format_context(context)
+          context.map do |k, v|
+            value = case v
+              when Exception
+                "#{v.class}: #{v.message}"
+              when String
+                v.length > 100 ? "#{v[0..97]}..." : v
+              else
+                v.inspect
+              end
+            "#{k}=#{value}"
+          end.join(" ")
+        end
+      end
+
+      # Initialize defaults
+      @enabled = false
+      @log_level = :info
+    end
+  end
+end

data/lib/parse/live_query/subscription.rb

@@ -0,0 +1,294 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "monitor"
+
+module Parse
+  module LiveQuery
+    # Represents an active subscription to a LiveQuery.
+    # Manages event callbacks and subscription lifecycle.
+    #
+    # @example
+    #   subscription = Song.subscribe(where: { artist: "Beatles" })
+    #
+    #   # Register callbacks using on() method
+    #   subscription.on(:create) { |song| puts "New song!" }
+    #   subscription.on(:update) { |song, original| puts "Updated!" }
+    #
+    #   # Or use shorthand methods
+    #   subscription.on_create { |song| puts "New song!" }
+    #   subscription.on_update { |song, original| puts "Updated!" }
+    #   subscription.on_delete { |song| puts "Deleted!" }
+    #   subscription.on_enter { |song, original| puts "Entered query!" }
+    #   subscription.on_leave { |song, original| puts "Left query!" }
+    #
+    #   # Error handling
+    #   subscription.on_error { |error| puts "Error: #{error.message}" }
+    #
+    #   # Connection events
+    #   subscription.on_subscribe { puts "Subscribed!" }
+    #   subscription.on_unsubscribe { puts "Unsubscribed!" }
+    #
+    #   # Cleanup
+    #   subscription.unsubscribe
+    #
+    class Subscription
+      # Class-level monitor for request ID generation
+      @@id_monitor = Monitor.new
+      @@request_counter = 0
+
+      # @return [Integer] unique request ID for this subscription
+      attr_reader :request_id
+
+      # @return [String] Parse class name being subscribed to
+      attr_reader :class_name
+
+      # @return [Hash] the query constraints (where clause)
+      attr_reader :query
+
+      # @return [Parse::LiveQuery::Client] the LiveQuery client
+      attr_reader :client
+
+      # @return [Array<String>] fields to watch for changes (nil = all fields)
+      attr_reader :fields
+
+      # @return [String, nil] session token for ACL-aware subscriptions
+      attr_reader :session_token
+
+      # Create a new subscription
+      # @param client [Parse::LiveQuery::Client] the LiveQuery client
+      # @param class_name [String] Parse class name
+      # @param query [Hash] query constraints (where clause)
+      # @param fields [Array<String>, nil] specific fields to watch
+      # @param session_token [String, nil] session token for authentication
+      def initialize(client:, class_name:, query: {}, fields: nil, session_token: nil)
+        @monitor = Monitor.new
+        @client = client
+        @class_name = class_name
+        @query = query
+        @fields = fields
+        @session_token = session_token
+        @request_id = generate_request_id
+        @state = :pending
+        @callbacks = Hash.new { |h, k| h[k] = [] }
+
+        Logging.debug("Subscription created",
+                      request_id: @request_id,
+                      class_name: @class_name,
+                      query_keys: @query.keys)
+      end
+
+      # Current subscription state
+      # @return [Symbol] :pending, :subscribed, :unsubscribed, or :error
+      def state
+        @monitor.synchronize { @state }
+      end
+
+      # Register a callback for a specific event type
+      # @param event_type [Symbol] :create, :update, :delete, :enter, :leave, :error, :subscribe, :unsubscribe
+      # @yield [object, original] block to call when event occurs
+      # @return [self]
+      def on(event_type, &block)
+        return self unless block_given?
+
+        @monitor.synchronize do
+          @callbacks[event_type.to_sym] << block
+        end
+        self
+      end
+
+      # Register callback for create events
+      # @yield [Parse::Object] the created object
+      # @return [self]
+      def on_create(&block)
+        on(:create, &block)
+      end
+
+      # Register callback for update events
+      # @yield [Parse::Object, Parse::Object] updated object, original object
+      # @return [self]
+      def on_update(&block)
+        on(:update, &block)
+      end
+
+      # Register callback for delete events
+      # @yield [Parse::Object] the deleted object
+      # @return [self]
+      def on_delete(&block)
+        on(:delete, &block)
+      end
+
+      # Register callback for enter events (object now matches query)
+      # @yield [Parse::Object, Parse::Object] current object, original object
+      # @return [self]
+      def on_enter(&block)
+        on(:enter, &block)
+      end
+
+      # Register callback for leave events (object no longer matches query)
+      # @yield [Parse::Object, Parse::Object] current object, original object
+      # @return [self]
+      def on_leave(&block)
+        on(:leave, &block)
+      end
+
+      # Register callback for errors
+      # @yield [Exception] the error that occurred
+      # @return [self]
+      def on_error(&block)
+        on(:error, &block)
+      end
+
+      # Register callback for successful subscription
+      # @yield called when subscription is confirmed
+      # @return [self]
+      def on_subscribe(&block)
+        on(:subscribe, &block)
+      end
+
+      # Register callback for unsubscription
+      # @yield called when unsubscribed
+      # @return [self]
+      def on_unsubscribe(&block)
+        on(:unsubscribe, &block)
+      end
+
+      # Unsubscribe from this subscription
+      # @return [Boolean] true if unsubscribe message was sent
+      def unsubscribe
+        @monitor.synchronize do
+          return false if @state == :unsubscribed
+          @state = :unsubscribed
+        end
+
+        Logging.debug("Unsubscribing", request_id: @request_id)
+        client.unsubscribe(self)
+        emit(:unsubscribe)
+        true
+      end
+
+      # @return [Boolean] true if currently subscribed
+      def subscribed?
+        state == :subscribed
+      end
+
+      # @return [Boolean] true if pending subscription confirmation
+      def pending?
+        state == :pending
+      end
+
+      # @return [Boolean] true if unsubscribed
+      def unsubscribed?
+        state == :unsubscribed
+      end
+
+      # @return [Boolean] true if in error state
+      def error?
+        state == :error
+      end
+
+      # Build the subscription message to send to the server
+      # @return [Hash]
+      def to_subscribe_message
+        msg = {
+          op: "subscribe",
+          requestId: request_id,
+          query: {
+            className: class_name,
+            where: query,
+          },
+        }
+
+        msg[:query][:fields] = fields if fields&.any?
+        msg[:sessionToken] = session_token if session_token
+
+        msg
+      end
+
+      # Build the unsubscribe message
+      # @return [Hash]
+      def to_unsubscribe_message
+        {
+          op: "unsubscribe",
+          requestId: request_id,
+        }
+      end
+
+      # Handle an incoming event from the server
+      # @param event [Parse::LiveQuery::Event]
+      # @api private
+      def handle_event(event)
+        Logging.debug("Handling event",
+                      request_id: @request_id,
+                      event_type: event.type)
+        emit(event.type, event.object, event.original)
+      end
+
+      # Mark subscription as confirmed by server
+      # @api private
+      def confirm!
+        @monitor.synchronize { @state = :subscribed }
+        Logging.info("Subscription confirmed",
+                     request_id: @request_id,
+                     class_name: @class_name)
+        emit(:subscribe)
+      end
+
+      # Mark subscription as failed with error
+      # @param error [Exception, String]
+      # @api private
+      def fail!(error)
+        @monitor.synchronize { @state = :error }
+        error = SubscriptionError.new(error) if error.is_a?(String)
+        Logging.error("Subscription failed",
+                      request_id: @request_id,
+                      error: error)
+        emit(:error, error)
+      end
+
+      # @return [Hash] subscription info as hash
+      def to_h
+        @monitor.synchronize do
+          {
+            request_id: request_id,
+            class_name: class_name,
+            query: query,
+            state: @state,
+            fields: fields,
+          }
+        end
+      end
+
+      private
+
+      # Emit an event to registered callbacks
+      # @param event_type [Symbol]
+      # @param args [Array] arguments to pass to callbacks
+      def emit(event_type, *args)
+        # Copy callbacks under lock, iterate outside to prevent deadlocks
+        callbacks = @monitor.synchronize { @callbacks[event_type].dup }
+
+        callbacks.each do |callback|
+          begin
+            callback.call(*args)
+          rescue => e
+            # Don't let callback errors break the subscription
+            Logging.error("Callback error",
+                          request_id: @request_id,
+                          event_type: event_type,
+                          error: e)
+            emit(:error, e) unless event_type == :error
+          end
+        end
+      end
+
+      # Generate a unique request ID (thread-safe)
+      # @return [Integer]
+      def generate_request_id
+        @@id_monitor.synchronize do
+          @@request_counter += 1
+        end
+      end
+    end
+  end
+end