volcano-sdk 0.5.2

data/lib/volcano/realtime/protocol_io.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Centrifuge protocol implementation extended with socket IO helpers.
+    class Protocol
+      # Coordinates protocol requests and the socket reader loop.
+      module IO
+        private
+
+        def request(on_reply: nil)
+          ensure_open!
+          id, reply_queue = register_request(on_reply)
+          write_frame(yield(id))
+          reply = await_reply(reply_queue)
+          raise reply.error if reply.is_a?(Failure)
+
+          reply
+        rescue StandardError => e
+          raise Redaction.exception(e, secrets: @secrets), cause: nil
+        ensure
+          @pending.delete(id) if defined?(id)
+        end
+
+        def register_request(on_reply)
+          if @pending.length >= @max_pending
+            raise PendingLimitError, "realtime pending command limit #{@max_pending} reached"
+          end
+
+          @next_id += 1
+          queue = Async::Queue.new
+          @pending[@next_id] = Pending.new(queue: queue, on_reply: on_reply)
+          [@next_id, queue]
+        end
+
+        def write_frame(frame) = write_serialized_frame("#{JSON.generate(frame)}\n")
+
+        def write_serialized_frame(frame)
+          @write_lock.acquire do
+            @socket.write(frame)
+            @socket.flush
+          end
+        rescue StandardError => e
+          failure = closed_error(e)
+          close_with(failure, notify_error: true)
+          raise failure
+        end
+
+        def await_reply(reply_queue)
+          Async::Task.current.with_timeout(
+            @request_timeout,
+            RequestTimeoutError,
+            "realtime command timed out after #{@request_timeout} seconds"
+          ) { reply_queue.dequeue }
+        end
+
+        def read_loop
+          while (message = read_message)
+            process_message(message)
+          end
+        rescue JSON::ParserError => e
+          close_with(ClosedError.new(invalid_frame_message(e)), notify_error: true)
+        rescue StandardError => e
+          close_with(closed_error(e), notify_error: true)
+        ensure
+          close_with(ClosedError.new('realtime connection closed'))
+        end
+
+        def read_message
+          Async::Task.current.yield
+          @socket.read
+        end
+
+        def process_message(message)
+          message.to_str.each_line do |line|
+            process(JSON.parse(line)) unless line.strip.empty?
+          end
+        end
+
+        def invalid_frame_message(error)
+          Redaction.message("invalid realtime frame: #{error.message}", secrets: @secrets)
+        end
+
+        def closed_error(error)
+          ClosedError.new(Redaction.message(error.message, secrets: @secrets)).tap do |closed|
+            closed.set_backtrace(error.backtrace)
+          end
+        end
+      end
+
+      include IO
+
+      private_constant :IO
+    end
+  end
+end

data/lib/volcano/realtime/protocol_lifecycle.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    class Protocol
+      # Exposes connection state and manages publication handlers.
+      module Lifecycle
+        def connected? = @connected && !@closed
+
+        def on_publication(channel, on_rejection: nil, &handler)
+          ensure_open!
+          @publication_handlers[channel] << ProtocolPublicationDispatch::Registration.new(
+            handler: handler, on_rejection: on_rejection
+          )
+          handler
+        end
+
+        def off_publication(channel, handler)
+          registrations = @publication_handlers[channel]
+          registrations.reject! { |registration| registration.handler.equal?(handler) }
+          @publication_handlers.delete(channel) if registrations.empty?
+          nil
+        end
+
+        def on_presence(channel, &handler)
+          ensure_open!
+          @presence_handlers[channel] << handler
+          handler
+        end
+
+        def off_presence(channel, handler)
+          handlers = @presence_handlers[channel]
+          handlers.delete(handler)
+          @presence_handlers.delete(channel) if handlers.empty?
+          @pending_presence_resyncs.delete(channel)
+          nil
+        end
+
+        private
+
+        def initialize_state
+          @next_id = 0
+          @pending = {}
+          initialize_locks
+          initialize_handlers
+          initialize_recovery_positions
+          initialize_publication_producer
+          @callback_stopping = @connected = @closed = false
+          @subscriptions = Set.new
+          @closed_error = nil
+        end
+
+        def initialize_locks
+          @write_lock = Async::Semaphore.new(1)
+          @subscription_lock = Async::Semaphore.new(1)
+        end
+
+        def initialize_handlers
+          @publication_handlers = Hash.new { |hash, key| hash[key] = [] }
+          @presence_handlers = Hash.new { |hash, key| hash[key] = [] }
+          @pending_presence_resyncs = {}
+          @callback_queue = Async::LimitedQueue.new(@max_callback_queue)
+        end
+
+        def start_tasks(task)
+          @callback_task = task.async { dispatch_callbacks }
+          @producer_task = task.async { dispatch_publication_batches }
+          @reader_task = task.async { read_loop }
+        end
+
+        def reject_pending(error) = @pending.each_value { |pending| pending.queue.enqueue(Failure.new(error: error)) }
+
+        def close_socket
+          @socket.close
+        rescue StandardError
+          nil
+        end
+
+        def stop_protocol_tasks
+          @callback_stopping = true
+          @producer_stopping = true
+          current = Async::Task.current?
+          [@reader_task, @producer_task, @callback_task].compact.each do |task|
+            task.stop unless task.equal?(current)
+          end
+        end
+
+        def close_with(error, notify_error: false)
+          return if @closed
+
+          was_connected = @connected
+          close_state(error)
+          notify_protocol_error(error) if notify_error
+          stop_protocol(error)
+          if notify_error
+            notify_protocol_failure(error, was_connected)
+          elsif was_connected
+            notify_protocol_close(error)
+          end
+        end
+
+        def close_state(error)
+          @connected = false
+          @closed = true
+          @closed_error = error
+          @subscriptions.clear
+        end
+
+        def stop_protocol(error)
+          reject_pending(error)
+          stop_protocol_tasks
+          close_socket
+        end
+
+        def notify_protocol_error(error) = @events&.on_error&.call(error)
+        def notify_protocol_failure(error, disconnected) = @events&.on_failure&.call(error, disconnected)
+        def notify_protocol_close(error) = @events&.on_close&.call(error)
+      end
+      private_constant :Lifecycle
+    end
+  end
+end

data/lib/volcano/realtime/protocol_publication_dispatch.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Normalizes publications and admits live deliveries without blocking the reader.
+    module ProtocolPublicationDispatch
+      Registration = Data.define(:handler, :on_rejection)
+      PublicationDelivery = Data.define(
+        :channel, :handlers, :event, :data, :publication, :recovered, :on_rejection, :rejection_key
+      )
+      private_constant :PublicationDelivery
+
+      private
+
+      def dispatch_publication(push)
+        channel = push['channel'].to_s
+        publication = push['pub']
+        delivery = publication_delivery(channel, publication, recovered: false)
+        return unless delivery
+
+        enqueue_live_publication(delivery)
+      end
+
+      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)
+        unless @publication_handlers.key?(matched_channel)
+          return drop_handlerless_publication(matched_channel, publication)
+        end
+
+        build_publication_delivery(matched_channel, publication, recovered: recovered)
+      end
+
+      def matching_publication_channel(channel)
+        handler_channel = matching_channel(@publication_handlers, channel)
+        recovery_channel = matching_channel(@stream_positions, channel)
+        [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)
+        return unless channel
+
+        if publication.is_a?(Hash)
+          drop_publication(channel, publication)
+        else
+          mark_unknown_gap(channel)
+        end
+        nil
+      end
+
+      def drop_handlerless_publication(channel, publication)
+        drop_publication(channel, publication) if channel
+        nil
+      end
+
+      def build_publication_delivery(channel, publication, recovered:)
+        registrations = @publication_handlers.fetch(channel).dup.freeze
+        data = publication.fetch('data')
+        PublicationDelivery.new(
+          channel: channel.dup.freeze,
+          handlers: registrations.map(&:handler).freeze,
+          event: data['event'],
+          data: data,
+          publication: publication,
+          recovered: recovered,
+          on_rejection: combined_rejection_hook(registrations),
+          rejection_key: registrations
+        )
+      end
+
+      def combined_rejection_hook(registrations)
+        hooks = registrations.filter_map(&:on_rejection).freeze
+        return if hooks.empty?
+        return hooks.first if hooks.one?
+
+        ->(publication) { hooks.each { |hook| hook.call(publication) } }
+      end
+
+      def admit_live_publication(delivery)
+        return reject_publication_delivery(delivery) if callback_queue_full?
+
+        @callback_queue.enqueue(delivery)
+      end
+
+      def callback_queue_full? = @callback_queue.limited?
+
+      def reject_publication_delivery(delivery)
+        if delivery.on_rejection
+          delivery.on_rejection.call(delivery.publication)
+        else
+          drop_publication(delivery.channel, delivery.publication)
+        end
+      end
+
+      def dispatch_queued_callback(delivery)
+        if delivery.is_a?(PublicationDelivery)
+          dispatch_publication_callbacks(delivery)
+        else
+          dispatch_callback_delivery(*delivery)
+        end
+      end
+
+      def dispatch_publication_callbacks(delivery)
+        delivery.handlers.each do |handler|
+          break if @callback_stopping
+
+          handler.call(
+            delivery.event, delivery.data, delivery.publication, recovered: delivery.recovered
+          )
+        rescue StandardError
+          next
+        end
+      end
+    end
+  end
+end

data/lib/volcano/realtime/protocol_recovery.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Validates recovery subscribe results before updating stream positions.
+    module ProtocolRecovery
+      private
+
+      def subscribe_request(channel:, recoverable:, join_leave:, recovery:)
+        on_reply = nil
+        if recovery
+          on_reply = lambda do |reply|
+            publications = parse_recovery_result(channel: channel, recovery: recovery, result: reply)
+            dispatch_recovered_publications(channel, publications)
+          end
+        end
+
+        request(on_reply:) do |id|
+          self.class.subscribe(
+            id: id,
+            channel: channel,
+            recoverable: recoverable,
+            join_leave: join_leave,
+            recovery: recovery
+          )
+        end
+      end
+
+      def parse_recovery_result(channel:, recovery:, result:)
+        result_position, publications = validated_recovery_result(result)
+        return block_malformed_recovery_result(channel, recovery) unless result_position
+
+        requested_position = requested_recovery_position(recovery)
+        return block_recovery_result(channel, requested_position) if unrecovered_empty_result?(
+          result, requested_position, publications
+        )
+        return install_empty_recovery_result(channel, result_position) if publications.empty?
+
+        install_retained_recovery_result(channel, requested_position, publications)
+      end
+
+      def block_malformed_recovery_result(channel, recovery)
+        block_recovery_result(channel, requested_recovery_position(recovery))
+      end
+
+      def block_recovery_result(channel, requested_position)
+        replace_recovery_position(channel, requested_position) if requested_position
+        mark_unknown_gap(channel)
+        []
+      end
+
+      def unrecovered_empty_result?(result, requested_position, publications)
+        requested_position && result['recovered'] == false && publications.empty?
+      end
+
+      def validated_recovery_result(result)
+        return [nil, nil] unless result.is_a?(Hash)
+
+        result_position = recovery_position(result['epoch'], result['offset'])
+        return [nil, nil] unless result_position
+
+        publications = result.fetch('publications', [])
+        return [nil, nil] unless publications.is_a?(Array)
+
+        validated = publications.map { |publication| validated_recovery_publication(publication, result_position) }
+        return [nil, nil] if validated.any?(&:nil?)
+
+        [result_position, validated]
+      end
+
+      def validated_recovery_publication(publication, fallback_position)
+        return unless publication.is_a?(Hash)
+
+        position = recovery_position(publication.fetch('epoch', fallback_position.fetch(:epoch)), publication['offset'])
+        return unless position
+
+        [publication, position]
+      end
+
+      def requested_recovery_position(recovery)
+        return unless recovery.is_a?(Hash)
+
+        recovery_position(recovery[:epoch], recovery[:offset])
+      end
+
+      def install_empty_recovery_result(channel, result_position)
+        replace_recovery_position(channel, result_position)
+        []
+      end
+
+      def install_retained_recovery_result(channel, requested_position, publications)
+        first_publication, first_position = publications.fetch(0)
+        position = requested_position || recovery_position(
+          first_position.fetch(:epoch), first_position.fetch(:offset) - 1
+        )
+        return [] unless position
+
+        replace_recovery_position(channel, position)
+        mark_retained_gap(channel, position, first_position, first_publication) if requested_position
+        publications.map(&:first)
+      end
+
+      def replace_recovery_position(channel, position)
+        delete_recovery_state(channel)
+        set_recovery_position(channel, position.fetch(:epoch), position.fetch(:offset))
+      end
+
+      def mark_retained_gap(channel, current, first_position, first_publication)
+        if same_epoch?(current, first_position) && first_position.fetch(:offset) > current.fetch(:offset) + 1
+          mark_publication_gap(channel, { 'epoch' => current.fetch(:epoch), 'offset' => current.fetch(:offset) + 1 })
+        elsif !same_epoch?(current, first_position)
+          mark_publication_gap(channel, first_publication)
+        end
+      end
+    end
+  end
+end

data/lib/volcano/realtime/protocol_recovery_dispatch.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Preserves publication order while recovered deliveries wait for callback capacity.
+    module ProtocolRecoveryDispatch
+      PublicationBatch = Data.define(:channel, :deliveries, :rejection_key)
+      private_constant :PublicationBatch
+
+      private
+
+      def initialize_publication_producer
+        @publication_queue = Async::Queue.new
+        @publication_queue_size = 0
+        @publication_pending_by_channel = Hash.new(0)
+        @publication_rejections = {}
+        @producer_stopping = false
+      end
+
+      def dispatch_recovered_publications(channel, publications)
+        deliveries = publications.filter_map do |publication|
+          publication_delivery(channel, publication, recovered: true)
+        end
+        return if deliveries.empty?
+
+        enqueue_recovered_batch(publication_batch(channel, deliveries))
+      end
+
+      def publication_batch(channel, deliveries, rejection_key: nil)
+        PublicationBatch.new(
+          channel: channel.dup.freeze, deliveries: deliveries.freeze, rejection_key: rejection_key
+        )
+      end
+
+      def enqueue_recovered_batch(batch)
+        if publication_queue_full?
+          batch.deliveries.each { |delivery| enqueue_publication_rejection(delivery) }
+          raise PendingLimitError, "realtime publication producer limit #{@max_callback_queue} reached"
+        end
+
+        enqueue_publication_batch(batch)
+      end
+
+      def enqueue_live_publication(delivery)
+        return enqueue_publication_rejection(delivery) if publication_queue_full?
+
+        enqueue_publication_batch(publication_batch(delivery.channel, [delivery]))
+      end
+
+      def enqueue_publication_rejection(delivery)
+        key = [delivery.channel, delivery.rejection_key].freeze
+        return if @publication_rejections.key?(key)
+
+        @publication_rejections[key] = true
+        enqueue_publication_batch(
+          publication_batch(delivery.channel, [delivery], rejection_key: key), bounded: false
+        )
+      end
+
+      def enqueue_publication_batch(batch, bounded: true)
+        @publication_queue_size += 1 if bounded
+        @publication_pending_by_channel[batch.channel] += 1
+        @publication_queue.enqueue(batch)
+      end
+
+      def publication_queue_full? = @publication_queue_size >= @max_callback_queue
+
+      def dispatch_publication_batches
+        until @producer_stopping
+          batch = next_publication_batch
+          begin
+            dispatch_publication_batch(batch)
+          ensure
+            complete_publication_batch(batch)
+          end
+        end
+      rescue StandardError => e
+        close_with(closed_error(e), notify_error: true)
+      end
+
+      def next_publication_batch
+        batch = @publication_queue.dequeue
+        @publication_queue_size -= 1 unless batch.rejection_key
+        batch
+      end
+
+      def dispatch_publication_batch(batch)
+        return batch.deliveries.each { |delivery| reject_publication_delivery(delivery) } if batch.rejection_key
+
+        batch.deliveries.each do |delivery|
+          if delivery.recovered
+            @callback_queue.enqueue(delivery)
+          else
+            admit_live_publication(delivery)
+          end
+        end
+      end
+
+      def complete_publication_batch(batch)
+        @publication_rejections.delete(batch.rejection_key) if batch.rejection_key
+        @publication_pending_by_channel[batch.channel] -= 1
+        @publication_pending_by_channel.delete(batch.channel) if @publication_pending_by_channel[batch.channel].zero?
+      end
+    end
+  end
+end

data/lib/volcano/realtime/protocol_recovery_position.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Tracks recoverable Centrifuge stream positions independently of subscriptions.
+    module ProtocolRecoveryPosition
+      private
+
+      def initialize_recovery_positions
+        @stream_positions = {}
+        @position_gaps = {}
+      end
+
+      def position(channel) = @stream_positions[channel]
+
+      def set_recovery_position(channel, epoch, offset)
+        position = recovery_position(epoch, offset)
+        return unless position
+
+        @stream_positions[channel] = position
+      end
+
+      def complete_publication(channel, publication)
+        current = @stream_positions[channel]
+        return unless current
+
+        completed = publication_position(publication, current)
+        return unless completed
+        return mark_unknown_gap(channel) unless same_epoch?(completed, current)
+        return if stale_position?(completed, current)
+        return mark_unknown_gap(channel) unless next_position?(completed, current)
+        return unless completion_before_gap?(channel, completed)
+
+        @stream_positions[channel] = completed
+      end
+
+      def drop_publication(channel, publication)
+        mark_publication_gap(channel, publication)
+      end
+
+      def delete_recovery_state(channel)
+        @stream_positions.delete(channel)
+        @position_gaps.delete(channel)
+      end
+
+      def mark_publication_gap(channel, publication)
+        current = @stream_positions[channel]
+        return unless current
+
+        gap = publication_position(publication, current)
+        return unless gap
+
+        store_publication_gap(channel, gap, current)
+      end
+
+      def store_publication_gap(channel, gap, current)
+        return @position_gaps[channel] = true unless same_epoch?(gap, current)
+        return if gap.fetch(:offset) <= current.fetch(:offset)
+
+        existing = @position_gaps[channel]
+        return if existing == true
+        return if existing && existing.fetch(:offset) <= gap.fetch(:offset)
+
+        @position_gaps[channel] = gap
+      end
+
+      def publication_position(publication, fallback)
+        return unless publication.is_a?(Hash)
+
+        epoch = publication.fetch('epoch', fallback.fetch(:epoch))
+        recovery_position(epoch, publication['offset'])
+      end
+
+      def recovery_position(epoch, offset)
+        return unless epoch.is_a?(String) && !epoch.empty?
+        return unless offset.is_a?(Integer) && offset >= 0
+
+        { epoch: epoch.dup.freeze, offset: offset.freeze }.freeze
+      end
+
+      def same_epoch?(first, second) = first.fetch(:epoch) == second.fetch(:epoch)
+
+      def stale_position?(position, current) = position.fetch(:offset) <= current.fetch(:offset)
+
+      def next_position?(position, current) = position.fetch(:offset) == current.fetch(:offset) + 1
+
+      def completion_before_gap?(channel, completed)
+        gap = @position_gaps[channel]
+        gap != true && (!gap || completed.fetch(:offset) < gap.fetch(:offset))
+      end
+
+      def mark_unknown_gap(channel) = @position_gaps[channel] = true
+    end
+  end
+end