volcano-sdk 0.31.0 → 0.32.0

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

data/lib/volcano/realtime.rb

@@ -32,134 +32,148 @@ module Volcano
 
     # Recursively snapshots JSON-compatible values for callback and state safety.
     module Immutable
-      module_function
-
-      def optional(value)
-        value && call(value)
+      def self.optional(value)
+        value && snapshot(value)
       end
 
-      def call(value)
+      def self.call(value) = snapshot(value)
+
+      def self.snapshot(value)
         case value
         when Hash then call_hash(value)
-        when Array then value.map { |child| call(child) }.freeze
+        when Array then value.map { |child| snapshot(child) }.freeze
         when String then value.dup.freeze
         else value.freeze
         end
       end
 
-      def call_hash(value)
-        value.to_h { |key, item| [call(key), call(item)] }.freeze
+      def self.call_hash(value)
+        value.to_h { |key, item| [snapshot(key), snapshot(item)] }.freeze
       end
     end
     private_constant :Immutable
 
-    PresenceInfo = Data.define(:client, :user, :data) do
+    PresenceInfo = Data.define(:client, :user, :data)
+
+    # An immutable snapshot of one presence client.
+    class PresenceInfo
+      # @dynamic client, user, data, members, with, to_h, deconstruct, deconstruct_keys
+      # @dynamic self.[], self.members
       def initialize(client:, user: nil, data: {})
-        super(
-          client: Immutable.call(client.to_s),
-          user: user.nil? ? nil : Immutable.call(user.to_s),
-          data: Immutable.call(data)
-        )
+        client = Immutable.call(client.to_s)
+        user = user.nil? ? nil : Immutable.call(user.to_s)
+        data = Immutable.call(data)
+        super
       end
     end
 
     CHANNEL_TYPES = %i[broadcast presence postgres].freeze
 
-    def initialize(client, api_url:, socket_factory: nil, reconnect_delay: nil)
-      @client = client
-      @api_url = api_url
-      @socket_factory = socket_factory || method(:open_socket)
-      @reconnect_delay = reconnect_delay || method(:default_reconnect_delay)
-      initialize_realtime_state
-      initialize_postgres_database
-    end
+    # Owns the public realtime facade and its channel collection.
+    module Core
+      # @dynamic initialize_postgres_database, connect_protocol, close_protocol, public_error
+      # @dynamic protocol_error, open_socket, default_reconnect_delay, __send__
+      def initialize(client, api_url:, socket_factory: nil, reconnect_delay: nil)
+        @client = client
+        @api_url = api_url
+        @socket_factory = socket_factory || ->(address) { open_socket(address) }
+        @reconnect_delay = reconnect_delay || ->(attempt) { default_reconnect_delay(attempt) }
+        initialize_realtime_state
+        initialize_postgres_database
+      end
 
-    def initialize_realtime_state
-      @protocol = nil
-      @protocol_lock = nil
-      @channel_lock = nil
-      @channels = {}
-      @connection_callbacks = { connect: {}, disconnect: {}, error: {} }
-      @next_connection_callback_id = 0
-      @protocol_session_lineage = nil
-      @reconnect_task = nil
-      @closed = false
-    end
-    private :initialize_realtime_state
-
-    def channel(
-      name, type: :broadcast, auto_fetch: true,
-      fetch_batch_window_ms: 20, fetch_max_batch_size: 50
-    )
-      type = normalize_channel_type(type)
-      batch_config = PostgresBatchConfig.new(
-        auto_fetch:, batch_window_ms: fetch_batch_window_ms,
-        max_batch_size: fetch_max_batch_size
+      def initialize_realtime_state
+        @protocol = nil
+        @protocol_lock = nil
+        @channel_lock = nil
+        @channels = {}
+        @connection_callbacks = { connect: {}, disconnect: {}, error: {} }
+        @next_connection_callback_id = 0
+        @protocol_session_lineage = nil
+        @reconnect_task = nil
+        @closed = false
+      end
+      private :initialize_realtime_state
+
+      def channel(
+        name, type: :broadcast, auto_fetch: true,
+        fetch_batch_window_ms: 20, fetch_max_batch_size: 50
       )
-      channel_lock.acquire do
-        ensure_open!
-        channel_name = "#{type}:#{name}"
-        channel = @channels[channel_name]
-        next cached_channel(channel, batch_config) if channel
+        type = normalize_channel_type(type)
+        batch_config = PostgresBatchConfig.new(
+          auto_fetch:, batch_window_ms: fetch_batch_window_ms,
+          max_batch_size: fetch_max_batch_size
+        )
+        channel_lock.acquire do
+          ensure_open!
+          channel_name = "#{type}:#{name}"
+          channel = @channels[channel_name]
+          next cached_channel(channel, batch_config) if channel
 
-        @channels[channel_name] = build_channel(channel_name, type, batch_config)
+          @channels[channel_name] = build_channel(channel_name, type, batch_config)
+        end
       end
-    end
-
-    def protocol
-      ensure_open!
-      return @protocol if @protocol
 
-      protocol_lock.acquire do
+      def protocol
         ensure_open!
-        @protocol ||= connect_protocol
+        current_protocol = @protocol
+        return current_protocol if current_protocol
+
+        protocol_lock.acquire do
+          ensure_open!
+          @protocol ||= connect_protocol
+        end
+      rescue StandardError => e
+        raise public_error(e), cause: nil
       end
-    rescue StandardError => e
-      raise public_error(e), cause: nil
-    end
-    private :protocol
+      private :protocol
 
-    def disconnect
-      @protocol_lock ? @protocol_lock.acquire { close_protocol } : close_protocol
-    rescue StandardError => e
-      raise public_error(e), cause: nil
-    end
+      def disconnect
+        lock = @protocol_lock
+        lock ? lock.acquire { close_protocol } : close_protocol
+      rescue StandardError => e
+        raise public_error(e), cause: nil
+      end
 
-    def ensure_open!
-      raise ClosedError, 'realtime connection closed' if @closed
+      def ensure_open!
+        raise ClosedError, 'realtime connection closed' if @closed
 
-      self
-    end
+        self
+      end
 
-    private
+      private
 
-    def normalize_channel_type(type)
-      normalized = type.to_s.to_sym
-      return normalized if CHANNEL_TYPES.include?(normalized)
+      def normalize_channel_type(type)
+        normalized = type.to_s.to_sym
+        return normalized if CHANNEL_TYPES.include?(normalized)
 
-      raise ArgumentError, "unsupported realtime channel type: #{type}"
-    end
+        raise ArgumentError, "unsupported realtime channel type: #{type}"
+      end
 
-    def report_channel_error(error) = protocol_error(public_error(error))
+      def report_channel_error(error) = protocol_error(public_error(error))
 
-    def cached_channel(channel, batch_config)
-      channel.__send__(:ensure_fetch_config!, batch_config)
-      channel
-    end
+      def cached_channel(channel, batch_config)
+        channel.__send__(:ensure_fetch_config!, batch_config)
+        channel
+      end
 
-    def build_channel(name, type, batch_config)
-      Channel.new(self, method(:protocol), name, type, batch_config:)
-    end
+      def build_channel(name, type, batch_config)
+        Channel.new(self, -> { protocol }, name, type, batch_config:)
+      end
 
-    def protocol_lock
-      require 'async/semaphore'
-      @protocol_lock ||= Async::Semaphore.new(1)
-    end
+      def protocol_lock
+        require 'async/semaphore'
+        @protocol_lock ||= Async::Semaphore.new(1)
+      end
 
-    def channel_lock
-      require 'async/semaphore'
-      @channel_lock ||= Async::Semaphore.new(1)
+      def channel_lock
+        require 'async/semaphore'
+        @channel_lock ||= Async::Semaphore.new(1)
+      end
     end
+    include Core
+
+    private_constant :Core
 
     # Represents one realtime broadcast channel.
     class Channel
@@ -175,14 +189,15 @@ module Volcano
 
       attr_reader :name
 
+      # @dynamic name
+
       def initialize(realtime, protocol_provider, name, type, batch_config:)
         @realtime = realtime
         @protocol_provider = protocol_provider
         @name = name.freeze
         @handler_registered = @subscribed = @subscription_desired = @closed = false
         @lifecycle_lock = nil
-        @recovery_position = {}.freeze
-        @recovery_lineage = nil
+        initialize_recovery_state
         initialize_callback_dispatch
         initialize_presence(type)
         initialize_postgres_delivery(batch_config)
@@ -208,7 +223,7 @@ module Volcano
 
       def unsubscribe
         state = with_lifecycle_lock { unsubscribe_protocol }
-        emit_presence_sync(state)
+        emit_presence_sync(state) if state.is_a?(Hash)
         nil
       end
 
@@ -218,11 +233,12 @@ module Volcano
 
       def restore_subscription(protocol)
         state = with_lifecycle_lock do
-          next unless restoration_needed?
-
-          subscribe_protocol(protocol)
+          restoration_needed? ? subscribe_protocol(protocol) : nil
+        end
+        if state
+          subscribed_protocol, epoch = state
+          sync_presence(subscribed_protocol, epoch)
         end
-        sync_presence(*state) if state
         nil
       end
 
@@ -240,6 +256,13 @@ module Volcano
 
       private
 
+      def initialize_recovery_state
+        # @type var recovery_position: Hash[Symbol, String | Integer]
+        recovery_position = {}
+        @recovery_position = recovery_position.freeze
+        @recovery_lineage = nil
+      end
+
       def subscribe_with_intent
         ensure_open!
         raise DuplicateSubscriptionError, "already subscribed to #{@name}" if @subscription_desired
@@ -254,8 +277,8 @@ module Volcano
 
       def with_lifecycle_lock(&)
         require 'async/semaphore'
-        @lifecycle_lock ||= Async::Semaphore.new(1)
-        @lifecycle_lock.acquire(&)
+        lock = @lifecycle_lock ||= Async::Semaphore.new(1)
+        lock.acquire(&)
       end
 
       def ensure_open!

data/lib/volcano/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Volcano
-  VERSION = '0.31.0'
+  VERSION = '0.32.0'
 end