volcano-sdk 0.5.2

data/lib/volcano/realtime/channel_lifecycle.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Coordinates a channel's protocol subscription and local lifecycle state.
+    module ChannelLifecycle
+      def mark_closed
+        @closed = true
+        @subscription_desired = @subscribed = false
+        end_postgres_delivery
+        reset_presence
+      end
+
+      def protocol_lost(protocol)
+        remember_recovery_position(protocol)
+        @subscribed = false
+        end_postgres_delivery
+        detach_publication_handler(protocol)
+        @handler_registered = false
+        reset_presence
+      end
+
+      private
+
+      def unsubscribe_protocol
+        ensure_open!
+        return clear_subscription_intent unless @subscribed
+
+        protocol = @protocol_provider.call
+        protocol.unsubscribe(channel: @name)
+        complete_unsubscribe(protocol)
+      end
+
+      def clear_subscription_intent = @subscription_desired = false
+
+      def complete_unsubscribe(protocol)
+        if broadcast?
+          remember_recovery_position(protocol)
+          detach_publication_handler(protocol)
+          @handler_registered = false
+        end
+        @subscription_desired = @subscribed = false
+        end_postgres_delivery
+        invalidate_presence_subscription(protocol)
+        clear_presence
+      end
+
+      def subscribe_protocol(protocol)
+        epoch = next_presence_epoch
+        recovery_binding = recovery_binding()
+        prepare_protocol_subscription(protocol, epoch)
+        complete_protocol_subscription(protocol, epoch, recovery_binding)
+      rescue StandardError => e
+        reject_failed_subscription(protocol, e)
+        end_postgres_delivery
+        invalidate_presence_subscription(protocol)
+        raise
+      end
+
+      def complete_protocol_subscription(protocol, epoch, recovery_binding)
+        protocol.subscribe(channel: @name, **subscription_options(recovery_binding))
+        validate_recovery_binding!(recovery_binding)
+        remember_recovery_position(protocol)
+        @subscribed = true
+        [protocol, epoch]
+      end
+
+      def prepare_protocol_subscription(protocol, epoch)
+        begin_postgres_delivery
+        register_handlers(protocol, epoch)
+      end
+
+      def detach_from_protocol
+        return unless @subscribed || @publication_handler
+
+        protocol = @protocol_provider.call
+        protocol.unsubscribe(channel: @name) if @subscribed && protocol.connected?
+        detach_publication_handler(protocol)
+      end
+
+      def subscription_options(binding) = { recovery: binding&.last, recoverable: presence?, join_leave: presence? }
+
+      def recovery_binding
+        return unless broadcast?
+
+        _, lineage, = @realtime.__send__(:capture_protocol_session)
+        [lineage, recovery_position(lineage)].freeze
+      end
+
+      def recovery_position(lineage)
+        return @recovery_position if @recovery_lineage == lineage
+
+        @recovery_lineage = lineage
+        @recovery_position = {}.freeze
+      end
+
+      def validate_recovery_binding!(binding)
+        return unless binding
+
+        _, lineage, = @realtime.__send__(:capture_protocol_session)
+        raise Error::SessionChangedError unless lineage == binding.first
+      end
+
+      def reject_failed_subscription(protocol, error)
+        detach_publication_handler(protocol)
+        @handler_registered = false
+        protocol.close if protocol.connected? && !error.is_a?(ServerError)
+      end
+
+      def remember_recovery_position(protocol)
+        return unless broadcast?
+
+        @recovery_position = protocol.__send__(:position, @name) || @recovery_position
+      end
+
+      def clear_channel_recovery_state
+        return unless broadcast?
+
+        @recovery_position = {}.freeze
+        @recovery_lineage = nil
+      end
+
+      def mark_removed
+        @callbacks.each_value(&:clear)
+        @handler_registered = @subscription_desired = @subscribed = false
+        end_postgres_delivery
+        reset_presence
+        @closed = true
+      end
+    end
+    private_constant :ChannelLifecycle
+  end
+end

data/lib/volcano/realtime/connection.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Opens the WebSocket transport and maps its failures to public errors.
+    module Connection
+      private
+
+      def connect_protocol
+        @protocol_error_reported = false
+        session_lineage = active_session_lineage
+        socket = @socket_factory.call(address)
+        session = session_for_lineage(session_lineage)
+        protocol = build_protocol(socket)
+        result = protocol.connect(token: session.access_token)
+        session = session_for_lineage(session_lineage)
+        activate_protocol(protocol, session, result)
+      rescue StandardError => e
+        handle_connection_failure(socket, e)
+      end
+
+      def active_session_lineage
+        _, lineage, session = @client.capture_session_binding
+        return lineage if session
+
+        raise Error::AuthenticationError, 'No active session'
+      end
+
+      def session_for_lineage(expected_lineage)
+        _, lineage, session = @client.capture_session_binding
+        return session if session && lineage == expected_lineage
+
+        raise Error::SessionChangedError
+      end
+
+      def activate_protocol(protocol, session, result)
+        @protocol = protocol
+        @protocol_user_id = session.user_id
+        protocol_connected(result)
+        protocol
+      end
+
+      def close_protocol
+        return nil if @closed
+
+        @closed = true
+        stop_reconnect
+        close_connected_protocol
+        nil
+      end
+
+      def close_connected_protocol
+        @manual_disconnect = true
+        @protocol&.close
+      ensure
+        @manual_disconnect = false
+        @channels.each_value(&:mark_closed)
+        @protocol_user_id = nil
+      end
+
+      def handle_connection_failure(socket, error)
+        failure = public_error(error)
+        protocol_error(failure) unless @protocol_error_reported
+        close_socket(socket)
+        raise failure, cause: nil
+      end
+
+      def build_protocol(socket)
+        Protocol.new(
+          socket: socket,
+          secrets: realtime_secrets,
+          events: Protocol::Events.new(
+            on_close: method(:protocol_closed),
+            on_error: method(:protocol_error_started),
+            on_failure: method(:protocol_failed)
+          )
+        )
+      end
+
+      def close_socket(socket)
+        socket&.close
+      rescue StandardError
+        nil
+      end
+
+      def address
+        uri = URI(@api_url)
+        uri.scheme = uri.scheme == 'https' ? 'wss' : 'ws'
+        uri.path = "#{uri.path.delete_suffix('/')}/realtime/v1/websocket"
+        encoded_key = URI.encode_www_form_component(@client.anon_token).gsub('+', '%20')
+        uri.query = "apikey=#{encoded_key}"
+        uri.to_s
+      end
+
+      def open_socket(address)
+        require 'async/http/endpoint'
+        require 'async/websocket/client'
+        Async::WebSocket::Client.connect(Async::HTTP::Endpoint.parse(address))
+      end
+
+      def realtime_secrets = [@client.anon_token, @client.current_session&.access_token]
+
+      def public_error(error)
+        redacted = Redaction.exception(error, secrets: realtime_secrets)
+        return redacted unless Transport::NETWORK_ERRORS.any? { |type| error.is_a?(type) }
+
+        transport_error = Error::TransportError.new(redacted.message)
+        transport_error.set_backtrace(redacted.backtrace)
+        transport_error
+      end
+    end
+    private_constant :Connection
+  end
+end

data/lib/volcano/realtime/connection_callbacks.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Registers and dispatches public connection lifecycle callbacks.
+    module ConnectionCallbacks
+      def on_connect(callback = nil, &block) = register_connection_callback(:connect, callback, block)
+      def on_disconnect(callback = nil, &block) = register_connection_callback(:disconnect, callback, block)
+      def on_error(callback = nil, &block) = register_connection_callback(:error, callback, block)
+
+      private
+
+      def register_connection_callback(event, callback, block)
+        handler = callback || block
+        raise ArgumentError, 'callback or block is required' unless handler
+        raise ArgumentError, 'callback must respond to call' unless handler.respond_to?(:call)
+
+        @next_connection_callback_id += 1
+        callback_id = @next_connection_callback_id
+        @connection_callbacks.fetch(event)[callback_id] = handler
+        -> { @connection_callbacks.fetch(event).delete(callback_id) }
+      end
+
+      def emit_connection_event(event, context)
+        emit_connection_events([[event, context]])
+      end
+
+      def emit_connection_events(events)
+        deliveries = connection_deliveries(events)
+        return if deliveries.empty?
+
+        Async::Task.current.async do
+          connection_callback_lock.acquire do
+            deliveries.each { |event, context, callbacks| dispatch_connection_callbacks(event, context, callbacks) }
+          end
+        end
+        nil
+      end
+
+      def connection_deliveries(events)
+        events.filter_map do |event, context|
+          callbacks = @connection_callbacks.fetch(event).dup
+          [event, context, callbacks] unless callbacks.empty?
+        end
+      end
+
+      def dispatch_connection_callbacks(event, context, callbacks)
+        callbacks.each do |callback_id, callback|
+          next unless @connection_callbacks.fetch(event)[callback_id].equal?(callback)
+
+          callback.call(context)
+        rescue StandardError
+          next
+        end
+      end
+
+      def protocol_connected(result)
+        client = result['client']
+        emit_connection_event(:connect, ConnectContext.new(client: immutable_string(client)))
+      end
+
+      def protocol_closed(error)
+        reset_after_protocol_loss
+        emit_connection_event(:disconnect, disconnect_context(error))
+        start_reconnect
+      end
+
+      def protocol_error(error)
+        @protocol_error_reported = true
+        emit_connection_event(:error, error_context(error))
+      end
+
+      def protocol_error_started(_error)
+        @protocol_error_reported = true
+      end
+
+      def protocol_failed(error, disconnected)
+        reset_after_protocol_loss if disconnected
+        events = [[:error, error_context(error)]]
+        events << [:disconnect, disconnect_context(error)] if disconnected
+        emit_connection_events(events)
+        start_reconnect if disconnected
+      end
+
+      def error_context(error)
+        snapshot = immutable_exception(error)
+        ErrorContext.new(
+          code: snapshot.respond_to?(:code) ? snapshot.code : nil,
+          message: immutable_string(snapshot.message), error: snapshot
+        )
+      end
+
+      def disconnect_context(error)
+        reason = @manual_disconnect ? 'manual' : error.message
+        DisconnectContext.new(code: nil, reason: immutable_string(reason))
+      end
+
+      def immutable_exception(error)
+        snapshot = Redaction.exception(error, secrets: [])
+        snapshot.message.freeze
+        backtrace = snapshot.backtrace
+        snapshot.set_backtrace(backtrace.map { |line| immutable_string(line) }.freeze) if backtrace
+        snapshot.freeze
+      end
+
+      def immutable_string(value)
+        return unless value
+
+        value.to_s.dup.freeze
+      end
+
+      def connection_callback_lock
+        require 'async/semaphore'
+        @connection_callback_lock ||= Async::Semaphore.new(1)
+      end
+
+      def reset_after_protocol_loss
+        protocol = @protocol
+        @protocol = nil
+        @protocol_user_id = nil
+        @channels.each_value { |channel| channel.protocol_lost(protocol) } if protocol
+      end
+    end
+    private_constant :ConnectionCallbacks
+  end
+end

data/lib/volcano/realtime/lifecycle.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Channel collection and connection-state lifecycle operations.
+    module Lifecycle
+      def connected? = !@closed && (@protocol&.connected? || false)
+
+      def remove_channel(name, type: :broadcast)
+        channel_type = normalize_channel_type(type)
+        channel_lock.acquire { remove_channel_locked("#{channel_type}:#{name}") }
+        nil
+      end
+
+      def remove_all_channels
+        first_error = channel_lock.acquire do
+          @channels.dup.filter_map do |name, channel|
+            remove_channel_entry(name, channel)
+          end.first
+        end
+        raise first_error if first_error
+
+        nil
+      end
+
+      private
+
+      def remove_channel_locked(name)
+        channel = @channels[name]
+        return unless channel
+
+        channel.__send__(:remove)
+        @channels.delete(name)
+      end
+
+      def remove_channel_entry(name, channel)
+        channel.__send__(:remove)
+        @channels.delete(name)
+        nil
+      rescue StandardError => e
+        e
+      end
+    end
+    private_constant :Lifecycle
+  end
+end

data/lib/volcano/realtime/postgres_batch.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    PostgresBatchConfig = Data.define(
+      :auto_fetch, :batch_window_ms, :max_batch_size
+    ) do
+      def initialize(auto_fetch:, batch_window_ms:, max_batch_size:)
+        unless batch_window_ms.is_a?(Integer) && batch_window_ms.positive?
+          raise ArgumentError, 'fetch_batch_window_ms must be a positive integer'
+        end
+        unless max_batch_size.is_a?(Integer) && max_batch_size.between?(1, 128)
+          raise ArgumentError, 'fetch_max_batch_size must be between 1 and 128'
+        end
+
+        super
+      end
+    end
+    private_constant :PostgresBatchConfig
+
+    # Collects compatible row lookups and preserves their callback order.
+    module PostgresBatch
+      private
+
+      def collect_postgres_batch(first)
+        return [[first], nil] unless first.database_name
+
+        deadline = monotonic_time + (@postgres_batch_config.batch_window_ms / 1000.0)
+        requests = [first]
+        pending = collect_compatible_requests(requests, deadline)
+        [requests, pending]
+      end
+
+      def collect_compatible_requests(requests, deadline)
+        while requests.length < @postgres_batch_config.max_batch_size
+          request = dequeue_postgres_before(deadline)
+          return unless request
+          return request unless compatible_postgres_request?(requests.first, request)
+
+          requests << request
+        end
+        nil
+      end
+
+      def dequeue_postgres_before(deadline)
+        remaining = deadline - monotonic_time
+        return unless remaining.positive?
+
+        Async::Task.current.with_timeout(remaining) { @postgres_queue.dequeue }
+      rescue Async::TimeoutError
+        nil
+      end
+
+      def compatible_postgres_request?(first, candidate)
+        !postgres_stop?(candidate) && candidate.database_name &&
+          postgres_batch_key(first) == postgres_batch_key(candidate)
+      end
+
+      def postgres_batch_key(request)
+        change = request.change
+        [
+          request.database_name, request.session_lineage, request.subscription_epoch,
+          change.schema, change.table
+        ]
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def deliver_postgres_batch(requests)
+        return unless current_postgres_request?(requests.first)
+
+        changes = expanded_postgres_changes(requests)
+        requests.zip(changes).each do |request, change|
+          deliver_expanded_postgres_change(request, change)
+        end
+      end
+
+      def deliver_expanded_postgres_change(request, change)
+        return unless current_postgres_request?(request)
+
+        emit(change.type, change)
+        emit('*', change) if current_postgres_request?(request)
+      end
+    end
+    private_constant :PostgresBatch
+  end
+end

data/lib/volcano/realtime/postgres_changes.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    PostgresChange = Data.define(
+      :type, :schema, :table, :record, :old_record, :columns, :timestamp, :id, :mode
+    ) do
+      def initialize(
+        type:, schema:, table:, timestamp:, record: nil, old_record: nil, columns: nil,
+        id: nil, mode: nil
+      )
+        super(
+          type: Immutable.call(type.to_s), schema: Immutable.call(schema.to_s),
+          table: Immutable.call(table.to_s), record: record && Immutable.call(record),
+          old_record: old_record && Immutable.call(old_record),
+          columns: columns && Immutable.call(columns), timestamp: Immutable.call(timestamp.to_s),
+          id: id && Immutable.call(id), mode: mode && Immutable.call(mode.to_s)
+        )
+      end
+    end
+
+    # Registers filtered callbacks for Postgres change publications.
+    module PostgresChanges
+      CHANGE_EVENTS = %w[INSERT UPDATE DELETE].freeze
+      EVENTS = [*CHANGE_EVENTS, '*'].freeze
+
+      def on_postgres_changes(event, schema:, table:, callback: nil, &block)
+        ensure_postgres!
+        event = postgres_event(event)
+        handler = callback || block || raise(ArgumentError, 'callback or block is required')
+        register_postgres_listener(event, schema.to_s, table.to_s, handler)
+      end
+
+      private
+
+      def dispatch_postgres_change(data)
+        change = postgres_change(data)
+        return unless change && postgres_listener?(change)
+
+        enqueue_postgres_delivery(change)
+      end
+
+      def postgres_change(data)
+        return unless valid_postgres_change?(data)
+
+        PostgresChange.new(
+          type: data.fetch('type'), schema: data.fetch('schema'), table: data.fetch('table'),
+          record: data['record'], old_record: data['old_record'], columns: data['columns'],
+          timestamp: data.fetch('timestamp'), id: data['id'], mode: data['mode']
+        )
+      end
+
+      def postgres_event(event)
+        event = event.to_s.upcase
+        return event if EVENTS.include?(event)
+
+        raise ArgumentError, "unsupported postgres change event: #{event}"
+      end
+
+      def register_postgres_listener(event, schema, table, handler)
+        filtered = proc { |change| handler.call(change) if change.schema == schema && change.table == table }
+        @postgres_filters[filtered] = [event, schema, table]
+        on(event, filtered)
+      end
+
+      def postgres_listener?(change)
+        callbacks = [*@callbacks[change.type], *@callbacks['*']]
+        return true if callbacks.any? { |callback| !@postgres_filters.key?(callback) }
+
+        @postgres_filters.any? do |callback, (event, schema, table)|
+          callbacks.include?(callback) && postgres_filter_matches?(event, schema, table, change)
+        end
+      end
+
+      def postgres_filter_matches?(event, schema, table, change)
+        (event == '*' || event == change.type) && schema == change.schema && table == change.table
+      end
+
+      def valid_postgres_change?(data)
+        valid_postgres_identity?(data) && valid_postgres_payload?(data)
+      end
+
+      def valid_postgres_identity?(data)
+        data.is_a?(Hash) && CHANGE_EVENTS.include?(data['type']) &&
+          data['schema'].is_a?(String) && data['table'].is_a?(String) &&
+          data['timestamp'].is_a?(String)
+      end
+
+      def valid_postgres_payload?(data)
+        optional_hash?(data['record']) && optional_hash?(data['old_record']) &&
+          optional_array?(data['columns']) && [nil, 'lightweight'].include?(data['mode'])
+      end
+
+      def optional_hash?(value) = value.nil? || value.is_a?(Hash)
+      def optional_array?(value) = value.nil? || value.is_a?(Array)
+      def broadcast? = @type == :broadcast
+      def postgres? = @type == :postgres
+
+      def ensure_postgres!
+        return if postgres?
+
+        raise ArgumentError, 'operation is only available for postgres channels'
+      end
+    end
+    private_constant :PostgresChanges
+  end
+end

data/lib/volcano/realtime/postgres_database.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Holds the database selection and performs token-bound row lookups.
+    module PostgresDatabase
+      DATABASE_NAME = /\A[a-z0-9_]{1,64}\z/
+      FETCH_CONCURRENCY = 4
+      private_constant :DATABASE_NAME, :FETCH_CONCURRENCY
+
+      attr_reader :database_name
+
+      def database_name=(name)
+        unless name.nil? || (name.is_a?(String) && DATABASE_NAME.match?(name))
+          raise ArgumentError,
+                'database name must match ^[a-z0-9_]+$ and contain at most 64 characters'
+        end
+        @database_name = name&.dup&.freeze
+      end
+
+      private
+
+      def initialize_postgres_database
+        @database_name = nil
+        @postgres_fetch_semaphore = nil
+      end
+
+      def capture_session = @client.capture_session
+      def capture_session_binding = @client.capture_session_binding
+
+      def capture_protocol_session
+        generation, lineage, session = capture_session_binding
+        return [generation, lineage, session] if session && session.user_id == @protocol_user_id
+
+        raise Error::SessionChangedError
+      end
+
+      def access_token_for_protocol_lineage(expected_lineage)
+        _, lineage, session = capture_session_binding
+        return session.access_token if session && lineage == expected_lineage &&
+                                       session.user_id == @protocol_user_id
+
+        raise Error::SessionChangedError
+      end
+
+      def fetch_postgres_rows(change, ids, database_name, access_token)
+        table = change.schema == 'public' ? change.table : "#{change.schema}.#{change.table}"
+        postgres_fetch_semaphore.acquire do
+          BlockingCall.call do
+            @client.__send__(:database_with_token, database_name, access_token)
+                   .from(table).select('*').in('id', ids).execute
+          end
+        end
+      end
+
+      def postgres_fetch_semaphore
+        require 'async/semaphore'
+        @postgres_fetch_semaphore ||= Async::Semaphore.new(FETCH_CONCURRENCY)
+      end
+    end
+    private_constant :PostgresDatabase
+  end
+end