volcano-sdk 0.5.2

data/lib/volcano/realtime/postgres_delivery.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    PostgresDeliveryRequest = Data.define(
+      :change, :database_name, :session_lineage, :subscription_epoch
+    )
+    private_constant :PostgresDeliveryRequest
+
+    # Serializes Postgres publications and expands lightweight row identities.
+    module PostgresDelivery
+      QUEUE_LIMIT = 128
+      STOP = Object.new.freeze
+      private_constant :QUEUE_LIMIT, :STOP
+
+      private
+
+      def initialize_postgres_delivery(batch_config)
+        require 'async/queue'
+        @postgres_batch_config = batch_config
+        @postgres_filters = {}
+        @postgres_queue = Async::LimitedQueue.new(QUEUE_LIMIT)
+        @postgres_worker = nil
+        @postgres_epoch = 0
+        @postgres_session_lineage = 0
+      end
+
+      def ensure_fetch_config!(batch_config)
+        return if @postgres_batch_config == batch_config
+        if @postgres_batch_config.auto_fetch != batch_config.auto_fetch
+          raise ArgumentError, "conflicting auto_fetch option for #{@name}"
+        end
+
+        raise ArgumentError, "conflicting fetch options for #{@name}"
+      end
+
+      def begin_postgres_delivery
+        return unless postgres?
+
+        @postgres_epoch += 1
+        _, lineage, = @realtime.__send__(:capture_protocol_session)
+        @postgres_session_lineage = lineage
+      end
+
+      def end_postgres_delivery
+        return unless postgres?
+
+        @postgres_epoch += 1
+        @postgres_queue.dequeue until @postgres_queue.empty?
+        worker = @postgres_worker
+        return unless worker
+
+        @postgres_queue.enqueue(STOP)
+        @postgres_worker = nil
+        worker.wait unless worker.equal?(Async::Task.current)
+      end
+
+      def enqueue_postgres_delivery(change)
+        return unless @subscribed
+
+        database_name = @realtime.__send__(:database_name)
+        fetch = fetch_postgres_change?(change, database_name)
+        request = PostgresDeliveryRequest.new(
+          change:, database_name: fetch ? database_name : nil,
+          session_lineage: @postgres_session_lineage,
+          subscription_epoch: @postgres_epoch
+        )
+        return report_postgres_queue_overflow if @postgres_queue.limited?
+
+        start_postgres_worker
+        @postgres_queue.enqueue(request)
+      end
+
+      def fetch_postgres_change?(change, database_name)
+        change.mode == 'lightweight' && change.type != 'DELETE' &&
+          @postgres_batch_config.auto_fetch && database_name
+      end
+
+      def report_postgres_queue_overflow
+        error = PendingLimitError.new("realtime Postgres delivery queue limit #{QUEUE_LIMIT} reached")
+        @realtime.__send__(:report_channel_error, error)
+      end
+
+      def start_postgres_worker
+        return if @postgres_worker
+
+        @postgres_worker = Async::Task.current.async { run_postgres_worker }
+      end
+
+      def run_postgres_worker
+        pending = nil
+        loop do
+          request = pending || @postgres_queue.dequeue
+          break if postgres_stop?(request)
+
+          requests, pending = collect_postgres_batch(request)
+          deliver_postgres_batch(requests)
+        end
+      ensure
+        @postgres_worker = nil if @postgres_worker.equal?(Async::Task.current)
+      end
+
+      def postgres_stop?(request) = request.equal?(STOP)
+
+      def current_postgres_request?(request)
+        _, lineage, = @realtime.__send__(:capture_session_binding)
+        @subscribed && request.subscription_epoch == @postgres_epoch &&
+          request.session_lineage == lineage
+      end
+    end
+    private_constant :PostgresDelivery
+  end
+end

data/lib/volcano/realtime/postgres_expansion.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Expands lightweight Postgres identities into callback-ready changes.
+    module PostgresExpansion
+      private
+
+      def expanded_postgres_changes(requests)
+        return requests.map { |request| local_postgres_change(request.change) } unless requests.first.database_name
+
+        records = fetch_postgres_records(requests)
+        requests.map { |request| expanded_postgres_record(request, records) }
+      rescue Error::VolcanoError, KeyError, TypeError => e
+        report_postgres_fetch_error(requests.first, e)
+        requests.map(&:change)
+      end
+
+      def lightweight_delete?(change)
+        change.mode == 'lightweight' && change.type == 'DELETE'
+      end
+
+      def fetch_postgres_records(requests)
+        request = requests.first
+        access_token = @realtime.__send__(
+          :access_token_for_protocol_lineage, request.session_lineage
+        )
+        rows = @realtime.__send__(
+          :fetch_postgres_rows, request.change, postgres_ids(requests),
+          request.database_name, access_token
+        )
+        rows.to_h { |row| [row.fetch('id').to_s, row] }
+      end
+
+      def postgres_ids(requests)
+        requests.to_h { |request| [request.change.id.to_s, request.change.id] }.values
+      end
+
+      def expanded_postgres_record(request, records)
+        record = records[request.change.id.to_s]
+        unless record
+          report_postgres_fetch_error(request, Error::NotFoundError.new('Postgres row not found'))
+          return request.change
+        end
+
+        request.change.with(record: record, id: nil, mode: nil)
+      end
+
+      def report_postgres_fetch_error(request, error)
+        @realtime.__send__(:report_channel_error, error) if current_postgres_request?(request)
+      end
+
+      def delete_postgres_change(change)
+        old_record = change.old_record || (change.id && { 'id' => change.id })
+        change.with(old_record:, id: nil, mode: nil)
+      end
+
+      def local_postgres_change(change)
+        return delete_postgres_change(change) if lightweight_delete?(change)
+
+        change
+      end
+    end
+    private_constant :PostgresExpansion
+  end
+end

data/lib/volcano/realtime/presence.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Presence behavior mixed into realtime channels.
+    module Presence
+      def on_presence_sync(callback = nil, &)
+        ensure_presence!
+        on('presence_sync', callback, &)
+      end
+
+      def track(state = {})
+        with_lifecycle_lock do
+          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)
+
+          @tracked_state = Immutable.call(state)
+        end
+        nil
+      end
+
+      def presence_state = @presence_state
+      def tracked_state = @tracked_state
+
+      alias get_presence_state presence_state
+
+      private
+
+      def initialize_presence(type)
+        @type = type
+        @presence_state = Immutable.call({})
+        @tracked_state = Immutable.call({})
+        @presence_handler = nil
+        @presence_lock = nil
+        @subscription_epoch = 0
+      end
+
+      def presence? = @type == :presence
+
+      def ensure_presence!
+        return if presence?
+
+        raise ArgumentError, 'operation is only available for presence channels'
+      end
+
+      def register_presence_handler(protocol, epoch)
+        return unless presence?
+
+        detach_presence_handler(protocol)
+        @presence_handler = protocol.on_presence(@name) do |event, info|
+          presence_event(event, info, epoch)
+        end
+      end
+
+      def sync_presence(protocol, epoch)
+        return unless presence?
+
+        emit_presence_sync(fetch_presence_state(protocol, epoch))
+      rescue StandardError => e
+        report_presence_error(protocol, epoch, e)
+      end
+
+      def fetch_presence_state(protocol, epoch)
+        presence_lock.acquire do
+          next unless active_presence_epoch?(epoch)
+
+          result = protocol.presence(channel: @name)
+          replace_presence(result['presence']) if active_presence_epoch?(epoch)
+        end
+      end
+
+      def presence_event(event, info, epoch)
+        return sync_presence(@protocol_provider.call, epoch) if event == 'sync_required'
+
+        delivery = apply_presence_event(event, info, epoch)
+        return unless delivery
+
+        snapshot, state = delivery
+        emit(event, snapshot)
+        emit('presence_sync', state) if active_presence_epoch?(epoch)
+      end
+
+      def emit_presence_sync(state)
+        emit('presence_sync', state) if state
+      end
+
+      def report_presence_error(protocol, epoch, error)
+        return unless protocol.connected? && active_presence_epoch?(epoch)
+
+        @realtime.__send__(:report_channel_error, error)
+      end
+
+      def next_presence_epoch
+        @subscription_epoch += 1
+      end
+
+      def active_presence_epoch?(epoch)
+        @subscribed && epoch == @subscription_epoch
+      end
+
+      def invalidate_presence_subscription(protocol)
+        return unless presence?
+
+        @subscription_epoch += 1
+        detach_presence_handler(protocol)
+      end
+
+      def detach_presence_handler(protocol)
+        protocol.off_presence(@name, @presence_handler) if @presence_handler
+        @presence_handler = nil
+      end
+
+      def presence_lock
+        require 'async/semaphore'
+        @presence_lock ||= Async::Semaphore.new(1)
+      end
+    end
+    private_constant :Presence
+  end
+end

data/lib/volcano/realtime/presence_state.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Maintains immutable presence state independently of protocol lifecycle.
+    module PresenceState
+      private
+
+      def replace_presence(clients)
+        clients = {} unless clients.is_a?(Hash)
+        @presence_state = clients.to_h do |client_id, info|
+          [client_id.to_s.freeze, presence_info(info, client_id)]
+        end.freeze
+      end
+
+      def apply_presence_event(event, info, epoch)
+        return unless info.is_a?(Hash)
+
+        presence_lock.acquire do
+          next unless active_presence_epoch?(epoch)
+
+          snapshot = presence_info(info, info['client'])
+          update_presence_state(event, snapshot)
+          [snapshot, @presence_state]
+        end
+      end
+
+      def update_presence_state(event, snapshot)
+        next_state = @presence_state.dup
+        event == 'join' ? next_state[snapshot.client] = snapshot : next_state.delete(snapshot.client)
+        @presence_state = next_state.freeze
+      end
+
+      def presence_info(info, fallback_client)
+        data = info['conn_info'].is_a?(Hash) ? info.fetch('conn_info') : {}
+        PresenceInfo.new(
+          client: info.fetch('client', fallback_client).to_s,
+          user: info['user']&.to_s,
+          data: data
+        )
+      end
+
+      def clear_presence
+        return unless presence?
+
+        presence_lock.acquire do
+          @presence_state = Immutable.call({})
+          @tracked_state = Immutable.call({})
+          @presence_state
+        end
+      end
+
+      def reset_presence
+        @subscription_epoch += 1
+        @presence_state = Immutable.call({})
+        @tracked_state = Immutable.call({})
+      end
+    end
+    private_constant :PresenceState
+  end
+end

data/lib/volcano/realtime/protocol.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'protocol_dispatch'
+require_relative 'protocol_lifecycle'
+require_relative 'protocol_publication_dispatch'
+require_relative 'protocol_recovery'
+require_relative 'protocol_recovery_dispatch'
+require_relative 'protocol_recovery_position'
+
+module Volcano
+  class Realtime
+    # Error returned by the realtime server for a command.
+    class ServerError < StandardError
+      attr_reader :code
+
+      def initialize(message, code: nil)
+        super(message)
+        @code = code.is_a?(String) ? code.dup.freeze : code
+      end
+    end
+
+    class ClosedError < StandardError; end
+    class DuplicateSubscriptionError < StandardError; end
+    class PendingLimitError < StandardError; end
+    class RequestTimeoutError < StandardError; end
+
+    # Implements the Centrifuge request and publication protocol.
+    class Protocol
+      include ProtocolDispatch
+      include Lifecycle
+      include ProtocolPublicationDispatch
+      include ProtocolRecovery
+      include ProtocolRecoveryDispatch
+      include ProtocolRecoveryPosition
+
+      Failure = Data.define(:error)
+      Pending = Data.define(:queue, :on_reply)
+      private_constant :Pending
+      Events = Data.define(:on_close, :on_error, :on_failure)
+      DEFAULT_REQUEST_TIMEOUT = 10
+      DEFAULT_MAX_PENDING = 128
+      DEFAULT_MAX_CALLBACK_QUEUE = 128
+      LIMIT_KEYS = %i[request_timeout max_pending max_callback_queue].freeze
+
+      def self.connect(id:, token:) = { 'id' => id, 'connect' => { 'token' => token } }
+
+      def self.subscribe(id:, channel:, recoverable: false, join_leave: false, recovery: nil)
+        options = { 'channel' => channel }
+        if recovery
+          options.merge!('recover' => true, 'positioned' => true, 'recoverable' => true)
+          options['epoch'] = recovery[:epoch] if recovery.key?(:epoch)
+          options['offset'] = recovery[:offset] if recovery.key?(:offset)
+        elsif recoverable
+          options['recoverable'] = true
+        end
+        options['join_leave'] = true if join_leave
+        { 'id' => id, 'subscribe' => options }
+      end
+
+      def self.publish(id:, channel:, data:) = { 'id' => id, 'publish' => { 'channel' => channel, 'data' => data } }
+
+      def self.unsubscribe(id:, channel:) = { 'id' => id, 'unsubscribe' => { 'channel' => channel } }
+
+      def self.presence(id:, channel:) = { 'id' => id, 'presence' => { 'channel' => channel } }
+
+      def initialize(
+        socket:,
+        task: nil,
+        secrets: [],
+        events: nil,
+        **limits
+      )
+        load_async
+        @socket = socket
+        @secrets = secrets.freeze
+        @events = events
+        configure_limits(limits)
+        initialize_state
+        start_tasks(task || Async::Task.current)
+      end
+
+      def connect(token:)
+        result = request { |id| self.class.connect(id: id, token: token) }
+        ensure_open!
+        @connected = true
+        result
+      end
+
+      def subscribe(channel:, recoverable: false, join_leave: false, recovery: nil)
+        @subscription_lock.acquire do
+          ensure_open!
+          raise DuplicateSubscriptionError, "already subscribed to #{channel}" if @subscriptions.include?(channel)
+
+          result = subscribe_request(channel:, recoverable:, join_leave:, recovery:)
+          ensure_open!
+          @subscriptions.add(channel)
+          result
+        end
+      end
+
+      def publish(channel:, data:) = request { |id| self.class.publish(id: id, channel: channel, data: data) }
+
+      def unsubscribe(channel:)
+        @subscription_lock.acquire do
+          ensure_open!
+          next {} unless @subscriptions.include?(channel)
+
+          result = request { |id| self.class.unsubscribe(id: id, channel: channel) }
+          @subscriptions.delete(channel)
+          result
+        end
+      end
+
+      def presence(channel:) = request { |id| self.class.presence(id: id, channel: channel) }
+
+      def close
+        return nil if @closed
+
+        close_with(ClosedError.new('realtime connection closed'))
+        nil
+      end
+
+      private
+
+      def load_async
+        require 'async'
+        require 'async/queue'
+        require 'async/semaphore'
+      end
+
+      def configure_limits(limits)
+        unknown = limits.keys - LIMIT_KEYS
+        raise ArgumentError, "unknown keyword: #{unknown.first}" unless unknown.empty?
+
+        @request_timeout = limits.fetch(:request_timeout, DEFAULT_REQUEST_TIMEOUT)
+        @max_pending = limits.fetch(:max_pending, DEFAULT_MAX_PENDING)
+        @max_callback_queue = limits.fetch(:max_callback_queue, DEFAULT_MAX_CALLBACK_QUEUE)
+      end
+
+      def ensure_open!
+        raise @closed_error if @closed
+
+        self
+      end
+    end
+  end
+end
+
+require_relative 'protocol_io'

data/lib/volcano/realtime/protocol_dispatch.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Dispatches protocol replies and publications to their waiting consumers.
+    module ProtocolDispatch
+      private
+
+      def process(frame)
+        if frame.empty?
+          write_frame({})
+        elsif frame.key?('id')
+          dispatch_reply(frame)
+        elsif frame.key?('push')
+          dispatch_push(frame.fetch('push'))
+        end
+      end
+
+      def dispatch_push(push)
+        if push.key?('pub')
+          dispatch_publication(push)
+        elsif push.key?('join')
+          dispatch_presence(push, 'join')
+        elsif push.key?('leave')
+          dispatch_presence(push, 'leave')
+        end
+      end
+
+      def dispatch_reply(frame)
+        pending = @pending[frame.fetch('id')]
+        return unless pending
+
+        reply = reply_value(frame)
+        pending.queue.enqueue(apply_reply_hook(pending, reply))
+      end
+
+      def apply_reply_hook(pending, reply)
+        return reply if reply.is_a?(Protocol::Failure) || !pending.on_reply
+
+        pending.on_reply.call(reply)
+        reply
+      rescue StandardError => e
+        Protocol::Failure.new(error: e)
+      end
+
+      def reply_value(frame)
+        error = frame['error']
+        return frame['result'] || frame.except('id') unless error
+
+        message = error['message'] || 'realtime command failed'
+        Protocol::Failure.new(error: ServerError.new(message, code: error['code']))
+      end
+
+      def dispatch_presence(push, event)
+        channel = matching_channel(@presence_handlers, push['channel'].to_s)
+        info = push.dig(event, 'info')
+        return unless channel && info.is_a?(Hash)
+
+        if @callback_queue.size >= @max_callback_queue
+          @pending_presence_resyncs[channel] = @presence_handlers.fetch(channel).dup
+          return
+        end
+
+        @callback_queue.enqueue([@presence_handlers.fetch(channel).dup, event, info])
+      end
+
+      def matching_channel(handlers, channel)
+        handlers.each_key.select do |candidate|
+          if candidate.start_with?('postgres:')
+            postgres_channel?(candidate, channel)
+          else
+            channel == candidate || channel.end_with?(":#{candidate}")
+          end
+        end.max_by(&:length)
+      end
+
+      def postgres_channel?(candidate, channel)
+        candidate_parts = candidate.split(':')
+        channel_parts = channel.split(':')
+        candidate_parts.length == 3 && candidate_parts.first == 'postgres' &&
+          channel_parts.length == 5 && channel_parts.slice(1, 3) == candidate_parts
+      end
+
+      def dispatch_callbacks
+        until @callback_stopping
+          delivery = @callback_queue.dequeue
+          dispatch_queued_callback(delivery)
+          enqueue_pending_presence_resync
+        end
+      rescue StandardError => e
+        close_with(closed_error(e), notify_error: true)
+      end
+
+      def dispatch_callback_delivery(handlers, event, data)
+        handlers.each do |handler|
+          break if @callback_stopping
+
+          handler.call(event, data)
+        rescue StandardError
+          next
+        end
+      end
+
+      def enqueue_pending_presence_resync
+        return if @callback_queue.size >= @max_callback_queue
+
+        channel, handlers = @pending_presence_resyncs.shift
+        return unless channel
+
+        @callback_queue.enqueue([handlers, 'sync_required', {}])
+      end
+    end
+  end
+end