volcano-sdk 0.30.0 → 0.32.0

data/lib/volcano/realtime/presence.rb

@@ -4,6 +4,7 @@ module Volcano
   class Realtime
     # Presence behavior mixed into realtime channels.
     module Presence
+      # @dynamic on, emit, with_lifecycle_lock, ensure_open!, replace_presence, apply_presence_event
       def on_presence_sync(callback = nil, &)
         ensure_presence!
         on('presence_sync', callback, &)
@@ -14,7 +15,8 @@ module Volcano
           ensure_open!
           ensure_presence!
           raise ClosedError, 'realtime channel is not subscribed' unless @subscribed
-          raise ArgumentError, 'presence state must be a hash' unless state.is_a?(Hash)
+
+          validate_presence_state(state)
 
           @tracked_state = Immutable.call(state)
         end
@@ -24,14 +26,19 @@ module Volcano
       def presence_state = @presence_state
       def tracked_state = @tracked_state
 
+      # @dynamic get_presence_state
       alias get_presence_state presence_state
 
       private
 
       def initialize_presence(type)
         @type = type
-        @presence_state = Immutable.call({})
-        @tracked_state = Immutable.call({})
+        # @type var empty_presence: Hash[String, PresenceInfo]
+        empty_presence = {}
+        # @type var empty_tracked: Hash[String, json_value]
+        empty_tracked = {}
+        @presence_state = Immutable.call(empty_presence)
+        @tracked_state = Immutable.call(empty_tracked)
         @presence_handler = nil
         @presence_lock = nil
         @subscription_epoch = 0
@@ -45,6 +52,10 @@ module Volcano
         raise ArgumentError, 'operation is only available for presence channels'
       end
 
+      def validate_presence_state(state)
+        raise ArgumentError, 'presence state must be a hash' unless state.is_a?(Hash)
+      end
+
       def register_presence_handler(protocol, epoch)
         return unless presence?
 
@@ -67,6 +78,8 @@ module Volcano
           next unless active_presence_epoch?(epoch)
 
           result = protocol.presence(channel: @name)
+          raise TypeError, 'realtime presence result must be an object' unless result.is_a?(Hash)
+
           replace_presence(result['presence']) if active_presence_epoch?(epoch)
         end
       end
@@ -108,7 +121,8 @@ module Volcano
       end
 
       def detach_presence_handler(protocol)
-        protocol.off_presence(@name, @presence_handler) if @presence_handler
+        handler = @presence_handler
+        protocol.off_presence(@name, handler) if handler
         @presence_handler = nil
       end
 

data/lib/volcano/realtime/presence_state.rb

@@ -4,10 +4,16 @@ module Volcano
   class Realtime
     # Maintains immutable presence state independently of protocol lifecycle.
     module PresenceState
+      # @dynamic presence_lock, active_presence_epoch?, presence?
+
       private
 
       def replace_presence(clients)
-        clients = {} unless clients.is_a?(Hash)
+        unless clients.is_a?(Hash)
+          # @type var empty_clients: Hash[String, Object?]
+          empty_clients = {}
+          clients = empty_clients
+        end
         @presence_state = clients.to_h do |client_id, info|
           [client_id.to_s.freeze, presence_info(info, client_id)]
         end.freeze
@@ -32,7 +38,10 @@ module Volcano
       end
 
       def presence_info(info, fallback_client)
-        data = info['conn_info'].is_a?(Hash) ? info.fetch('conn_info') : {}
+        # @type var empty_data: Hash[String, json_value]
+        empty_data = {}
+        raw_data = info['conn_info']
+        data = raw_data.is_a?(Hash) ? raw_data : empty_data
         PresenceInfo.new(
           client: info.fetch('client', fallback_client).to_s,
           user: info['user']&.to_s,
@@ -44,16 +53,24 @@ module Volcano
         return unless presence?
 
         presence_lock.acquire do
-          @presence_state = Immutable.call({})
-          @tracked_state = Immutable.call({})
+          # @type var empty_presence: Hash[String, PresenceInfo]
+          empty_presence = {}
+          # @type var empty_tracked: Hash[String, json_value]
+          empty_tracked = {}
+          @presence_state = Immutable.call(empty_presence)
+          @tracked_state = Immutable.call(empty_tracked)
           @presence_state
         end
       end
 
       def reset_presence
         @subscription_epoch += 1
-        @presence_state = Immutable.call({})
-        @tracked_state = Immutable.call({})
+        # @type var empty_presence: Hash[String, PresenceInfo]
+        empty_presence = {}
+        # @type var empty_tracked: Hash[String, json_value]
+        empty_tracked = {}
+        @presence_state = Immutable.call(empty_presence)
+        @tracked_state = Immutable.call(empty_tracked)
       end
     end
     private_constant :PresenceState

data/lib/volcano/realtime/protocol.rb

@@ -14,6 +14,8 @@ module Volcano
     class ServerError < StandardError
       attr_reader :code
 
+      # @dynamic code
+
       def initialize(message, code: nil)
         super(message)
         @code = code.is_a?(String) ? code.dup.freeze : code
@@ -46,12 +48,10 @@ module Volcano
       def self.connect(id:, token:) = { 'id' => id, 'connect' => { 'token' => token } }
 
       def self.subscribe(id:, channel:, recoverable: false, join_leave: false, recovery: nil)
+        # @type var options: Hash[String, Object]
         options = { 'channel' => channel }
-        if recovery
-          add_recovery_options(options, recovery)
-        elsif recoverable
-          options['recoverable'] = true
-        end
+        add_recovery_options(options, recovery) if recovery
+        options['recoverable'] = true if !recovery && recoverable
         options['join_leave'] = true if join_leave
         { 'id' => id, 'subscribe' => options }
       end
@@ -88,8 +88,9 @@ module Volcano
       def connect(token:)
         result = request('connect') { |id| self.class.connect(id: id, token: token) }
         ensure_open!
-        @connected = true
-        result
+        raise TypeError, 'realtime connect result must be an object' unless result.is_a?(Hash)
+
+        result.tap { @connected = true }
       end
 
       def subscribe(channel:, recoverable: false, join_leave: false, recovery: nil)
@@ -111,7 +112,11 @@ module Volcano
       def unsubscribe(channel:)
         @subscription_lock.acquire do
           ensure_open!
-          next {} unless @subscriptions.include?(channel)
+          unless @subscriptions.include?(channel)
+            # @type var empty_reply: Hash[String, Object]
+            empty_reply = {}
+            next empty_reply
+          end
 
           result = request('unsubscribe') { |id| self.class.unsubscribe(id: id, channel: channel) }
           @subscriptions.delete(channel)
@@ -146,7 +151,7 @@ module Volcano
       end
 
       def ensure_open!
-        raise @closed_error if @closed
+        raise(@closed_error || ClosedError.new('realtime connection closed')) if @closed
 
         self
       end

data/lib/volcano/realtime/protocol_dispatch.rb

@@ -4,6 +4,9 @@ module Volcano
   class Realtime
     # Dispatches protocol replies and publications to their waiting consumers.
     module ProtocolDispatch
+      # @dynamic write_frame, dispatch_publication, dispatch_queued_callback, close_with, closed_error
+      PresenceDelivery = Data.define(:handlers, :event, :data)
+
       private
 
       def process(frame)
@@ -12,7 +15,10 @@ module Volcano
         elsif frame.key?('id')
           dispatch_reply(frame)
         elsif frame.key?('push')
-          dispatch_push(frame.fetch('push'))
+          push = frame.fetch('push')
+          raise TypeError, 'realtime push must be an object' unless push.is_a?(Hash)
+
+          dispatch_push(push)
         end
       end
 
@@ -27,7 +33,10 @@ module Volcano
       end
 
       def dispatch_reply(frame)
-        pending = @pending[frame.fetch('id')]
+        id = frame.fetch('id')
+        return unless id.is_a?(Integer)
+
+        pending = @pending.fetch(id, nil)
         return unless pending
 
         reply = reply_value(frame, pending.reply_key)
@@ -45,12 +54,18 @@ module Volcano
 
       def reply_value(frame, reply_key)
         error = frame['error']
-        return frame.fetch(reply_key) { frame.fetch('result') { frame.except('id') } } unless error
+        return successful_reply(frame, reply_key) unless error
+
+        raise TypeError, 'realtime error must be an object' unless error.is_a?(Hash)
 
         message = error['message'] || 'realtime command failed'
         Protocol::Failure.new(error: ServerError.new(message, code: error['code']))
       end
 
+      def successful_reply(frame, reply_key)
+        frame.fetch(reply_key) { frame.fetch('result') { frame.except('id') } }
+      end
+
       def dispatch_presence(push, event)
         channel = matching_channel(@presence_handlers, push['channel'].to_s)
         info = push.dig(event, 'info')
@@ -61,7 +76,8 @@ module Volcano
           return
         end
 
-        @callback_queue.enqueue([@presence_handlers.fetch(channel).dup, event, info])
+        delivery = PresenceDelivery.new(handlers: @presence_handlers.fetch(channel).dup, event:, data: info)
+        @callback_queue.enqueue(delivery)
       end
 
       def matching_channel(handlers, channel)
@@ -93,7 +109,7 @@ module Volcano
 
       def dispatch_callback_delivery(handlers, event, data)
         handlers.each do |handler|
-          break if @callback_stopping
+          break handlers if @callback_stopping
 
           handler.call(event, data)
         rescue StandardError
@@ -105,9 +121,11 @@ module Volcano
         return if @callback_queue.size >= @max_callback_queue
 
         channel, handlers = @pending_presence_resyncs.shift
-        return unless channel
+        return unless channel && handlers
 
-        @callback_queue.enqueue([handlers, 'sync_required', {}])
+        # @type var empty_info: Hash[String, Object?]
+        empty_info = {}
+        @callback_queue.enqueue(PresenceDelivery.new(handlers:, event: 'sync_required', data: empty_info))
       end
     end
   end

data/lib/volcano/realtime/protocol_io.rb

@@ -6,12 +6,15 @@ module Volcano
     class Protocol
       # Coordinates protocol requests and the socket reader loop.
       module IO
+        # @dynamic ensure_open!, close_with, process
+
         private
 
         def request(reply_key, on_reply: nil)
+          # @type var registered_id: Integer?
           ensure_open!
-          id, reply_queue = register_request(reply_key, on_reply)
-          write_frame(yield(id))
+          registered_id, reply_queue = register_request(reply_key, on_reply)
+          write_frame(yield(registered_id || raise(TypeError, 'invalid realtime request id')))
           reply = await_reply(reply_queue)
           raise reply.error if reply.is_a?(Failure)
 
@@ -19,7 +22,7 @@ module Volcano
         rescue StandardError => e
           raise Redaction.exception(e, secrets: @secrets), cause: nil
         ensure
-          @pending.delete(id)
+          @pending.delete(registered_id) if registered_id
         end
 
         def register_request(reply_key, on_reply)
@@ -83,7 +86,8 @@ module Volcano
 
         def closed_error(error)
           ClosedError.new(Redaction.message(error.message, secrets: @secrets)).tap do |closed|
-            closed.set_backtrace(error.backtrace)
+            trace = error.backtrace
+            closed.set_backtrace(trace) if trace
           end
         end
       end

data/lib/volcano/realtime/protocol_lifecycle.rb

@@ -5,6 +5,8 @@ module Volcano
     class Protocol
       # Exposes connection state and manages publication handlers.
       module Lifecycle
+        # @dynamic ensure_open!, initialize_recovery_positions, initialize_publication_producer, dispatch_callbacks
+        # @dynamic dispatch_publication_batches, read_loop
         def connected? = @connected && !@closed
 
         def on_publication(channel, on_rejection: nil, &handler)

data/lib/volcano/realtime/protocol_publication_dispatch.rb

@@ -4,6 +4,8 @@ module Volcano
   class Realtime
     # Normalizes publications and admits live deliveries without blocking the reader.
     module ProtocolPublicationDispatch
+      # @dynamic enqueue_live_publication, matching_channel, drop_publication, mark_unknown_gap
+      # @dynamic dispatch_callback_delivery
       Registration = Data.define(:handler, :on_rejection)
       PublicationDelivery = Data.define(
         :channel, :handlers, :event, :data, :publication, :recovered, :on_rejection, :rejection_key
@@ -24,12 +26,15 @@ module Volcano
       def publication_delivery(channel, publication, recovered:)
         matched_channel = matching_publication_channel(channel)
         return unless matched_channel
-        return reject_invalid_publication(matched_channel, publication) unless valid_publication?(publication)
+        return reject_invalid_publication(matched_channel, publication) unless publication.is_a?(Hash)
+
+        data = publication['data']
+        return reject_invalid_publication(matched_channel, publication) unless data.is_a?(Hash)
         unless @publication_handlers.key?(matched_channel)
           return drop_handlerless_publication(matched_channel, publication)
         end
 
-        build_publication_delivery(matched_channel, publication, recovered: recovered)
+        build_publication_delivery(matched_channel, publication, data, recovered: recovered)
       end
 
       def matching_publication_channel(channel)
@@ -38,10 +43,6 @@ module Volcano
         [handler_channel, recovery_channel].compact.max_by(&:length)
       end
 
-      def valid_publication?(publication)
-        publication.is_a?(Hash) && publication['data'].is_a?(Hash)
-      end
-
       def reject_invalid_publication(channel, publication)
         if publication.is_a?(Hash)
           drop_publication(channel, publication)
@@ -56,9 +57,8 @@ module Volcano
         nil
       end
 
-      def build_publication_delivery(channel, publication, recovered:)
+      def build_publication_delivery(channel, publication, data, recovered:)
         registrations = @publication_handlers.fetch(channel).dup.freeze
-        data = publication.fetch('data')
         PublicationDelivery.new(
           channel: channel.dup.freeze,
           handlers: registrations.map(&:handler).freeze,
@@ -98,14 +98,16 @@ module Volcano
       def dispatch_queued_callback(delivery)
         if delivery.is_a?(PublicationDelivery)
           dispatch_publication_callbacks(delivery)
+        elsif delivery.is_a?(ProtocolDispatch::PresenceDelivery)
+          dispatch_callback_delivery(delivery.handlers, delivery.event, delivery.data)
         else
-          dispatch_callback_delivery(*delivery)
+          raise TypeError, 'invalid realtime callback delivery'
         end
       end
 
       def dispatch_publication_callbacks(delivery)
         delivery.handlers.each do |handler|
-          break if @callback_stopping
+          break delivery.handlers if @callback_stopping
 
           handler.call(
             delivery.event, delivery.data, delivery.publication, recovered: delivery.recovered

data/lib/volcano/realtime/protocol_recovery.rb

@@ -4,6 +4,10 @@ module Volcano
   class Realtime
     # Validates recovery subscribe results before updating stream positions.
     module ProtocolRecovery
+      # @dynamic class, request, dispatch_recovered_publications, recovery_position
+      # @dynamic delete_recovery_state, set_recovery_position, mark_unknown_gap
+      # @dynamic mark_publication_gap, same_epoch?
+
       private
 
       def subscribe_request(channel:, recoverable:, join_leave:, recovery:)
@@ -28,7 +32,7 @@ module Volcano
 
       def parse_recovery_result(channel:, recovery:, result:)
         result_position, publications = validated_recovery_result(result)
-        return block_malformed_recovery_result(channel, recovery) unless result_position
+        return block_malformed_recovery_result(channel, recovery) unless result_position && publications
 
         requested_position = requested_recovery_position(recovery)
         return block_recovery_result(channel, requested_position) if unrecovered_empty_result?(
@@ -50,7 +54,7 @@ module Volcano
       end
 
       def unrecovered_empty_result?(result, requested_position, publications)
-        requested_position && result['recovered'] == false && publications.empty?
+        requested_position && result.is_a?(Hash) && result['recovered'] == false && publications.empty?
       end
 
       def validated_recovery_result(result)
@@ -68,7 +72,7 @@ module Volcano
         validated = publications.map { |publication| validated_recovery_publication(publication, result_position) }
         return [nil, nil] if validated.any?(&:nil?)
 
-        [result_position, validated]
+        [result_position, validated.compact]
       end
 
       def validated_recovery_publication(publication, fallback_position)

data/lib/volcano/realtime/protocol_recovery_dispatch.rb

@@ -4,6 +4,8 @@ module Volcano
   class Realtime
     # Preserves publication order while recovered deliveries wait for callback capacity.
     module ProtocolRecoveryDispatch
+      # @dynamic publication_delivery, reject_publication_delivery, admit_live_publication
+      # @dynamic close_with, closed_error
       PublicationBatch = Data.define(:channel, :deliveries, :rejection_key)
       private_constant :PublicationBatch
 

data/lib/volcano/realtime/reconnect.rb

@@ -4,6 +4,7 @@ module Volcano
   class Realtime
     # Reconnects unexpected transport losses and restores subscription intent.
     module Reconnect
+      # @dynamic channel_lock, protocol_lock, connect_protocol, report_channel_error
       RECONNECT_MIN_DELAY = 0.1
       RECONNECT_MAX_DELAY = 20.0
       MAX_BACKOFF_EXPONENT = 8
@@ -19,7 +20,9 @@ module Volcano
       def stop_reconnect
         task = @reconnect_task
         @reconnect_task = nil
-        task&.stop unless task.equal?(Async::Task.current)
+        return unless task
+
+        task.stop unless task.equal?(Async::Task.current)
       end
 
       def reconnect_loop