volcano-sdk 0.31.0 → 0.32.1

data/lib/volcano/models.rb

@@ -7,7 +7,14 @@ module Volcano
   ].freeze
   private_constant :AUTH_SESSION_ATTRIBUTES
 
-  AuthSession = Data.define(*AUTH_SESSION_ATTRIBUTES) do
+  AuthSession = Data.define(*AUTH_SESSION_ATTRIBUTES)
+
+  # Reopens the generated record for checked initialization.
+  class AuthSession
+    # @dynamic id, user_id, provider, expires_at, is_active, is_current, user_agent
+    # @dynamic ip_address, last_ip_address, last_activity_at, session_started_at
+    # @dynamic created_at, updated_at, members, with, to_h, deconstruct
+    # @dynamic deconstruct_keys, self.[], self.members
     def initialize(**attributes)
       unknown = attributes.keys - AUTH_SESSION_ATTRIBUTES
       raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
@@ -18,7 +25,8 @@ module Volcano
       values = AUTH_SESSION_ATTRIBUTES.to_h do |name|
         [name, freeze_session_value(attributes[name])]
       end
-      super(**values)
+      attributes = values
+      super
     end
 
     private
@@ -28,19 +36,28 @@ module Volcano
     end
   end
 
-  SessionPage = Data.define(:sessions, :total, :page, :limit, :total_pages) do
+  SessionPage = Data.define(:sessions, :total, :page, :limit, :total_pages)
+
+  # Reopens the generated record for checked initialization.
+  class SessionPage
+    # @dynamic sessions, total, page, limit, total_pages, members, with, to_h
+    # @dynamic deconstruct, deconstruct_keys, self.[], self.members
     def initialize(sessions:, total:, page:, limit:, total_pages:)
-      super(sessions: sessions.to_a.dup.freeze, total: total, page: page, limit: limit,
-            total_pages: total_pages)
+      sessions = sessions.to_a.dup.freeze
+      super
     end
   end
-  LinkedOAuthProvider = Data.define(:provider, :linked_at, :updated_at) do
+  LinkedOAuthProvider = Data.define(:provider, :linked_at, :updated_at)
+
+  # Reopens the generated record for checked initialization.
+  class LinkedOAuthProvider
+    # @dynamic provider, linked_at, updated_at, members, with, to_h, deconstruct
+    # @dynamic deconstruct_keys, self.[], self.members
     def initialize(provider:, linked_at:, updated_at:)
-      super(
-        provider: immutable_value(provider),
-        linked_at: immutable_value(linked_at),
-        updated_at: immutable_value(updated_at)
-      )
+      provider = immutable_value(provider)
+      linked_at = immutable_value(linked_at)
+      updated_at = immutable_value(updated_at)
+      super
     end
 
     private
@@ -49,30 +66,46 @@ module Volcano
       value.frozen? ? value : value.dup.freeze
     end
   end
-  OAuthProviderTokenStatus = Data.define(:message, :provider, :expires_in) do
+  OAuthProviderTokenStatus = Data.define(:message, :provider, :expires_in)
+
+  # Reopens the generated record for checked initialization.
+  class OAuthProviderTokenStatus
+    # @dynamic message, provider, expires_in, members, with, to_h, deconstruct
+    # @dynamic deconstruct_keys, self.[], self.members
     def initialize(message:, provider:, expires_in:)
       values = [message, provider]
       valid = values.all? { |value| value.is_a?(String) && !value.strip.empty? }
       raise TypeError, 'Expected complete OAuth provider token status' unless valid && expires_in.is_a?(Integer)
 
-      super(message: message.dup.freeze, provider: provider.dup.freeze, expires_in: expires_in)
+      message = message.dup.freeze
+      provider = provider.dup.freeze
+      super
     end
   end
   EmailChangeResult = Data.define(:message, :new_email)
-  LockLease = Data.define(:key, :token, :expires_at, :fencing_token) do
+  LockLease = Data.define(:key, :token, :expires_at, :fencing_token)
+
+  # Reopens the generated record for checked initialization.
+  class LockLease
+    # @dynamic key, token, expires_at, fencing_token, members, with, to_h
+    # @dynamic deconstruct, deconstruct_keys, self.[], self.members
     def initialize(key:, token:, expires_at:, fencing_token:)
-      super(
-        key: key.dup.freeze,
-        token: token.dup.freeze,
-        expires_at: expires_at&.dup&.freeze,
-        fencing_token: fencing_token
-      )
+      key = key.dup.freeze
+      token = token.dup.freeze
+      expires_at = expires_at&.dup&.freeze
+      super
     end
   end
-  LockState = Data.define(:held, :expires_at, :fencing_token) do
+  LockState = Data.define(:held, :expires_at, :fencing_token)
+
+  # Reopens the generated record for checked initialization.
+  class LockState
+    # @dynamic held, expires_at, fencing_token, members, with, to_h, deconstruct
+    # @dynamic deconstruct_keys, self.[], self.members
     def initialize(held:, expires_at:, fencing_token:)
       immutable_expiry = expires_at&.then { |value| value.frozen? ? value : value.dup.freeze }
-      super(held: held, expires_at: immutable_expiry, fencing_token: fencing_token)
+      expires_at = immutable_expiry
+      super
     end
   end
 end

data/lib/volcano/realtime/broadcast_delivery.rb

@@ -4,9 +4,16 @@ module Volcano
   class Realtime
     # Delivers broadcasts only while their subscription generation is current.
     module BroadcastDelivery
-      PublicationContext = Data.define(:protocol, :publication, :generation, :recovered) do
+      # @dynamic emit, with_lifecycle_lock, broadcast?
+      # Captures the subscription generation alongside an immutable publication.
+      PublicationContext = Data.define(:protocol, :publication, :generation, :recovered)
+
+      # Freezes the publication before callbacks can observe or modify it.
+      class PublicationContext
+        # @dynamic protocol, publication, generation, recovered
         def initialize(protocol:, publication:, generation:, recovered:)
-          super(protocol:, publication: Immutable.call(publication), generation:, recovered:)
+          publication = Immutable.call(publication)
+          super
         end
       end
       private_constant :PublicationContext
@@ -30,6 +37,14 @@ module Volcano
         PublicationContext.new(protocol:, publication:, generation:, recovered:)
       end
 
+      def publication_rejection(protocol, generation)
+        return unless broadcast?
+
+        lambda do |publication|
+          reject_broadcast(publication_context(protocol, publication, generation, false))
+        end
+      end
+
       def reject_broadcast(context)
         with_current_publication(context) do
           context.protocol.__send__(:drop_publication, @name, context.publication)
@@ -57,6 +72,15 @@ module Volcano
         @publication_protocol.__send__(:delete_recovery_state, @name)
         @publication_protocol = nil
       end
+
+      def clear_channel_recovery_state
+        return unless broadcast?
+
+        # @type var position: Hash[Symbol, String | Integer]
+        position = {}
+        @recovery_position = position.freeze
+        @recovery_lineage = nil
+      end
     end
     private_constant :BroadcastDelivery
   end

data/lib/volcano/realtime/channel_callbacks.rb

@@ -4,10 +4,16 @@ module Volcano
   class Realtime
     # Registers channel callbacks and connects them to protocol pushes.
     module ChannelCallbacks
+      # @dynamic presence?, postgres?, broadcast?, register_presence_handler, detach_presence_handler
+      # @dynamic deliver_broadcast, publication_context, reject_broadcast, publication_rejection
+      # @dynamic dispatch_postgres_change
       def on(event, callback = nil, &block)
         raise ArgumentError, "unsupported realtime event: #{event}" unless allowed_event?(event)
 
-        @callbacks[event] << (callback || block || raise(ArgumentError, 'callback or block is required'))
+        handler = callback || block || raise(ArgumentError, 'callback or block is required')
+        raise ArgumentError, 'callback must respond to call' unless handler.respond_to?(:call)
+
+        @callbacks[event] << handler
         self
       end
 
@@ -37,21 +43,21 @@ module Volcano
         generation = @publication_generation
         @publication_protocol = protocol if broadcast?
         @publication_handler = protocol.on_publication(
-          @name, on_rejection: publication_rejection(protocol, generation)
-        ) do |event, data, publication, recovered:|
-          next deliver_publication(event, data) unless broadcast?
-
-          context = publication_context(protocol, publication, generation, recovered)
-          deliver_broadcast(event, data, context)
-        end
+          @name, on_rejection: publication_rejection(protocol, generation),
+          &publication_callback(protocol, generation)
+        )
         @handler_registered = true
       end
 
-      def publication_rejection(protocol, generation)
-        return unless broadcast?
-
-        lambda do |publication|
-          reject_broadcast(publication_context(protocol, publication, generation, false))
+      def publication_callback(protocol, generation)
+        lambda do |event, data, publication, recovered:|
+          # @type var recovered: bool
+          if broadcast?
+            context = publication_context(protocol, publication, generation, recovered)
+            deliver_broadcast(event, data, context)
+          else
+            deliver_publication(event, data)
+          end
         end
       end
 
@@ -67,6 +73,7 @@ module Volcano
         callbacks = @callbacks[event].dup
         return if callbacks.empty?
 
+        # @type var delivery: delivery
         delivery = [event, data, callbacks, before_delivery]
         return defer_callback_delivery(delivery) if callback_dispatching?
 
@@ -109,8 +116,9 @@ module Volcano
       end
 
       def detach_publication_handler(protocol)
-        if @publication_handler
-          protocol.off_publication(@name, @publication_handler)
+        handler = @publication_handler
+        if handler
+          protocol.off_publication(@name, handler)
           @publication_generation += 1 if broadcast?
         end
         detach_presence_handler(protocol)

data/lib/volcano/realtime/channel_lifecycle.rb

@@ -4,6 +4,9 @@ module Volcano
   class Realtime
     # Coordinates a channel's protocol subscription and local lifecycle state.
     module ChannelLifecycle
+      # @dynamic end_postgres_delivery, reset_presence, detach_publication_handler, ensure_open!
+      # @dynamic broadcast?, next_presence_epoch, register_handlers, begin_postgres_delivery
+      # @dynamic invalidate_presence_subscription, clear_presence, presence?
       def mark_closed
         @closed = true
         @subscription_desired = @subscribed = false
@@ -84,14 +87,18 @@ module Volcano
         return unless broadcast?
 
         _, lineage, = @realtime.__send__(:capture_protocol_session)
-        [lineage, recovery_position(lineage)].freeze
+        # @type var binding: recovery_binding
+        binding = [lineage, recovery_position(lineage)]
+        binding.freeze
       end
 
       def recovery_position(lineage)
         return @recovery_position if @recovery_lineage == lineage
 
         @recovery_lineage = lineage
-        @recovery_position = {}.freeze
+        # @type var position: recovery_position
+        position = {}
+        @recovery_position = position.freeze
       end
 
       def validate_recovery_binding!(binding)
@@ -113,13 +120,6 @@ module Volcano
         @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

data/lib/volcano/realtime/connection.rb

@@ -4,6 +4,9 @@ module Volcano
   class Realtime
     # Opens the WebSocket transport and maps its failures to public errors.
     module Connection
+      # @dynamic protocol_connected, protocol_error, protocol_closed, protocol_error_started
+      # @dynamic protocol_failed, stop_reconnect
+
       private
 
       def connect_protocol
@@ -71,9 +74,9 @@ module Volcano
           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)
+            on_close: ->(error) { protocol_closed(error) },
+            on_error: ->(error) { protocol_error_started(error) },
+            on_failure: ->(error, disconnected) { protocol_failed(error, disconnected) }
           )
         )
       end
@@ -87,7 +90,7 @@ module Volcano
       def address
         uri = URI(@api_url)
         uri.scheme = uri.scheme == 'https' ? 'wss' : 'ws'
-        uri.path = "#{uri.path.delete_suffix('/')}/realtime/v1/websocket"
+        uri.path = "#{uri.path.to_s.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
@@ -106,7 +109,8 @@ module Volcano
         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)
+        trace = redacted.backtrace
+        transport_error.set_backtrace(trace) if trace
         transport_error
       end
     end

data/lib/volcano/realtime/connection_callbacks.rb

@@ -4,6 +4,7 @@ module Volcano
   class Realtime
     # Registers and dispatches public connection lifecycle callbacks.
     module ConnectionCallbacks
+      # @dynamic start_reconnect
       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)
@@ -76,6 +77,7 @@ module Volcano
 
       def protocol_failed(error, disconnected)
         reset_after_protocol_loss if disconnected
+        # @type var events: Array[[connection_event, connection_context]]
         events = [[:error, error_context(error)]]
         events << [:disconnect, disconnect_context(error)] if disconnected
         emit_connection_events(events)
@@ -84,8 +86,10 @@ module Volcano
 
       def error_context(error)
         snapshot = immutable_exception(error)
+        code = snapshot.respond_to?(:code) ? snapshot.method(:code).call : nil
+        code = nil unless code.is_a?(String) || code.is_a?(Integer)
         ErrorContext.new(
-          code: snapshot.respond_to?(:code) ? snapshot.code : nil,
+          code: code,
           message: immutable_string(snapshot.message), error: snapshot
         )
       end

data/lib/volcano/realtime/lifecycle.rb

@@ -4,6 +4,7 @@ module Volcano
   class Realtime
     # Channel collection and connection-state lifecycle operations.
     module Lifecycle
+      # @dynamic channel_lock, normalize_channel_type
       def connected? = !@closed && (@protocol&.connected? || false)
 
       def remove_channel(name, type: :broadcast)
@@ -26,7 +27,7 @@ module Volcano
       private
 
       def remove_channel_locked(name)
-        channel = @channels[name]
+        channel = @channels.fetch(name, nil)
         return unless channel
 
         channel.__send__(:remove)

data/lib/volcano/realtime/postgres_batch.rb

@@ -2,9 +2,14 @@
 
 module Volcano
   class Realtime
+    # Immutable limits for one channel's automatic row-fetch queue.
     PostgresBatchConfig = Data.define(
       :auto_fetch, :batch_window_ms, :max_batch_size
-    ) do
+    )
+
+    # Validates the queue limits supplied to a Postgres channel.
+    class PostgresBatchConfig
+      # @dynamic auto_fetch, batch_window_ms, max_batch_size
       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'
@@ -20,6 +25,8 @@ module Volcano
 
     # Collects compatible row lookups and preserves their callback order.
     module PostgresBatch
+      # @dynamic postgres_stop?, current_postgres_request?, expanded_postgres_changes, emit
+
       private
 
       def collect_postgres_batch(first)
@@ -35,6 +42,7 @@ module Volcano
         while requests.length < @postgres_batch_config.max_batch_size
           request = dequeue_postgres_before(deadline)
           return unless request
+          return request unless request.is_a?(PostgresDeliveryRequest)
           return request unless compatible_postgres_request?(requests.first, request)
 
           requests << request
@@ -72,8 +80,8 @@ module Volcano
         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)
+        requests.each_with_index do |request, index|
+          deliver_expanded_postgres_change(request, changes.fetch(index))
         end
       end
 

data/lib/volcano/realtime/postgres_changes.rb

@@ -4,23 +4,34 @@ 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: Immutable.optional(record),
-          old_record: Immutable.optional(old_record),
-          columns: Immutable.optional(columns), timestamp: Immutable.call(timestamp.to_s),
-          id: Immutable.optional(id), mode: mode && Immutable.call(mode.to_s)
-        )
+    )
+
+    # Immutable snapshot of a Postgres change publication.
+    class PostgresChange
+      # @dynamic type, schema, table, record, old_record, columns, timestamp, id, mode
+      # @dynamic members, with, to_h, deconstruct, deconstruct_keys, self.[], self.members
+      def initialize(type:, schema:, table:, timestamp:, **payload)
+        type = Immutable.call(type.to_s)
+        schema = Immutable.call(schema.to_s)
+        table = Immutable.call(table.to_s)
+        timestamp = Immutable.call(timestamp.to_s)
+        payload = snapshot_payload(payload)
+        super
+      end
+
+      private
+
+      def snapshot_payload(payload)
+        payload = { record: nil, old_record: nil, columns: nil, id: nil, mode: nil }.merge(payload)
+        %i[record old_record columns id].each { |field| payload[field] = Immutable.optional(payload[field]) }
+        payload[:mode] &&= Immutable.call(payload[:mode].to_s)
+        payload
       end
     end
 
     # Registers filtered callbacks for Postgres change publications.
     module PostgresChanges
+      # @dynamic on, enqueue_postgres_delivery
       CHANGE_EVENTS = %w[INSERT UPDATE DELETE].freeze
       EVENTS = [*CHANGE_EVENTS, '*'].freeze
 
@@ -28,6 +39,8 @@ module Volcano
         ensure_postgres!
         event = postgres_event(event)
         handler = callback || block || raise(ArgumentError, 'callback or block is required')
+        raise ArgumentError, 'callback must respond to call' unless handler.respond_to?(:call)
+
         register_postgres_listener(event, schema.to_s, table.to_s, handler)
       end
 
@@ -41,7 +54,7 @@ module Volcano
       end
 
       def postgres_change(data)
-        return unless valid_postgres_change?(data)
+        return unless data.is_a?(Hash) && valid_postgres_change?(data)
 
         PostgresChange.new(
           type: data.fetch('type'), schema: data.fetch('schema'), table: data.fetch('table'),
@@ -58,7 +71,10 @@ module Volcano
       end
 
       def register_postgres_listener(event, schema, table, handler)
-        filtered = proc { |change| handler.call(change) if change.schema == schema && change.table == table }
+        # @type var filtered: ^(Object?) -> void
+        filtered = lambda do |change|
+          handler.call(change) if change.is_a?(PostgresChange) && change.schema == schema && change.table == table
+        end
         @postgres_filters[filtered] = [event, schema, table]
         on(event, filtered)
       end
@@ -77,7 +93,7 @@ module Volcano
       end
 
       def valid_postgres_change?(data)
-        valid_postgres_identity?(data) && valid_postgres_payload?(data)
+        data.is_a?(Hash) && valid_postgres_identity?(data) && valid_postgres_payload?(data)
       end
 
       def valid_postgres_identity?(data)
@@ -87,8 +103,9 @@ module Volcano
       end
 
       def valid_postgres_payload?(data)
+        mode = data['mode']
         optional_hash?(data['record']) && optional_hash?(data['old_record']) &&
-          optional_array?(data['columns']) && [nil, 'lightweight'].include?(data['mode'])
+          optional_array?(data['columns']) && (mode.nil? || mode == 'lightweight')
       end
 
       def optional_hash?(value) = value.nil? || value.is_a?(Hash)

data/lib/volcano/realtime/postgres_database.rb

@@ -10,6 +10,8 @@ module Volcano
 
       attr_reader :database_name
 
+      # @dynamic database_name
+
       def database_name=(name)
         unless valid_database_name?(name)
           raise ArgumentError,
@@ -48,12 +50,23 @@ module Volcano
 
       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
+        rows = 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
+        validate_postgres_rows(rows)
+      end
+
+      def validate_postgres_rows(rows)
+        raise TypeError, 'Postgres row lookup must return an array' unless rows.is_a?(Array)
+
+        rows.map do |row|
+          raise TypeError, 'Postgres row lookup must return objects' unless row.is_a?(Hash)
+
+          row
+        end
       end
 
       def postgres_fetch_semaphore

data/lib/volcano/realtime/postgres_delivery.rb

@@ -9,6 +9,7 @@ module Volcano
 
     # Serializes Postgres publications and expands lightweight row identities.
     module PostgresDelivery
+      # @dynamic postgres?, collect_postgres_batch, deliver_postgres_batch
       QUEUE_LIMIT = 128
       STOP = Object.new.freeze
       private_constant :QUEUE_LIMIT, :STOP
@@ -18,7 +19,9 @@ module Volcano
       def initialize_postgres_delivery(batch_config)
         require 'async/queue'
         @postgres_batch_config = batch_config
-        @postgres_filters = {}
+        # @type var empty_filters: Hash[^(Object?) -> void, [String, String, String]]
+        empty_filters = {}
+        @postgres_filters = empty_filters
         @postgres_queue = Async::LimitedQueue.new(QUEUE_LIMIT)
         @postgres_worker = nil
         @postgres_epoch = 0
@@ -88,10 +91,12 @@ module Volcano
       end
 
       def run_postgres_worker
+        # @type var pending: Object?
         pending = nil
         loop do
           request = pending || @postgres_queue.dequeue
           break if postgres_stop?(request)
+          raise TypeError, 'invalid Postgres delivery request' unless request.is_a?(PostgresDeliveryRequest)
 
           requests, pending = collect_postgres_batch(request)
           deliver_postgres_batch(requests)

data/lib/volcano/realtime/postgres_expansion.rb

@@ -4,6 +4,8 @@ module Volcano
   class Realtime
     # Expands lightweight Postgres identities into callback-ready changes.
     module PostgresExpansion
+      # @dynamic current_postgres_request?, postgres_batch_key
+
       private
 
       def expanded_postgres_changes(requests)
@@ -26,12 +28,16 @@ module Volcano
 
       def fetch_postgres_records(requests)
         request = requests.first
+        database_name = request.database_name
+        lineage = request.session_lineage
+        raise TypeError, 'invalid Postgres fetch request' unless database_name && lineage.is_a?(SessionOperations)
+
         access_token = @realtime.__send__(
-          :access_token_for_protocol_lineage, request.session_lineage
+          :access_token_for_protocol_lineage, lineage
         )
         rows = @realtime.__send__(
           :fetch_postgres_rows, request.change, postgres_ids(requests),
-          request.database_name, access_token
+          database_name, access_token
         )
         rows.to_h { |row| [row.fetch('id').to_s, row] }
       end
@@ -41,7 +47,7 @@ module Volcano
       end
 
       def expanded_postgres_record(request, records)
-        record = records[request.change.id.to_s]
+        record = records.fetch(request.change.id.to_s, nil)
         unless record
           report_postgres_fetch_error(request, Error::NotFoundError.new('Postgres row not found'))
           return request.change
@@ -55,7 +61,7 @@ module Volcano
       end
 
       def delete_postgres_change(change)
-        old_record = change.old_record || (change.id && { 'id' => change.id })
+        old_record = change.old_record || (change.id ? { 'id' => change.id } : nil)
         change.with(old_record:, id: nil, mode: nil)
       end