volcano-sdk 0.31.0 → 0.32.1

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/session.rb

@@ -10,15 +10,26 @@ module Volcano
   private_constant :SESSION_USER_CODER
 
   # Local credentials; refresh credentials and user identity may be unknown.
-  Session = Data.define(:access_token, :refresh_token, :user_id, :user) do
+  Session = Data.define(:access_token, :refresh_token, :user_id, :user)
+
+  # Reopens the generated record for checked initialization.
+  class Session
+    # @dynamic access_token, refresh_token, user_id, user, members, with, to_h
+    # @dynamic deconstruct, deconstruct_keys, self.[], self.members
     def initialize(access_token:, refresh_token: nil, user_id: nil, user: nil)
-      super(access_token:, refresh_token:, user_id:, user: immutable_user(user))
+      user = immutable_user(user)
+      super
     end
 
     private
 
     def immutable_user(value)
-      SESSION_USER_CODER.load(SESSION_USER_CODER.dump(value))
+      return if value.nil?
+
+      snapshot = SESSION_USER_CODER.load(SESSION_USER_CODER.dump(value))
+      raise TypeError, 'Session user snapshot must be a Hash' unless snapshot.is_a?(Hash)
+
+      snapshot
     rescue JSON::GeneratorError, JSON::NestingError
       raise TypeError, 'Session user snapshot must contain JSON values or timestamps', cause: nil
     end

data/lib/volcano/transport.rb

@@ -20,21 +20,20 @@ module Volcano
 
     NETWORK_ERRORS = [IOError, SystemCallError, SocketError, Timeout::Error].freeze
 
-    module_function
-
-    def invoke
+    def self.invoke
       yield
-    rescue *NETWORK_ERRORS => e
+    rescue IOError, SystemCallError, SocketError, Timeout::Error => e
       raise Error::TransportError, e.message, cause: e
     end
 
-    def body(response, expected_status)
+    def self.body(response, expected_status)
       return response.body if response.status == expected_status
 
       raise response_error(response)
     end
 
-    def response_error(response)
+    def self.response_error(response)
+      # @type var payload: Hash[String, Object?]
       payload = response.body.is_a?(Hash) ? response.body : {}
       retry_after = integer_header(response.headers, 'Retry-After') if response.status == 429
       error_type(response.status).new(
@@ -45,20 +44,63 @@ module Volcano
       )
     end
 
-    def error_message(payload)
-      payload['error'] || payload['message'] || 'Volcano request failed'
+    def self.error_message(payload)
+      error = payload['error']
+      return error if error.is_a?(String)
+
+      message = payload['message']
+      message.is_a?(String) ? message : 'Volcano request failed'
+    end
+
+    def self.json_value(value)
+      case value
+      when Array then value.map { |entry| json_value(entry) }
+      when Hash then json_object(value)
+      else json_scalar(value)
+      end
+    end
+
+    def self.json_object(value, message: 'Expected a JSON object')
+      raise TypeError, message unless value.is_a?(Hash)
+
+      value.to_h do |key, item|
+        raise TypeError, message unless key.is_a?(String)
+
+        [key, json_value(item)]
+      end
+    end
+
+    def self.json_rows(value)
+      rows = json_object(value)['data']
+      raise TypeError, 'Expected database rows' unless rows.is_a?(Array)
+
+      rows.map { |row| json_object(row) }
+    end
+
+    def self.finite_float(value)
+      raise TypeError, 'Expected a finite JSON number' unless value.finite?
+
+      value
+    end
+
+    def self.json_scalar(value)
+      case value
+      when NilClass, TrueClass, FalseClass, Integer, String then value
+      when Float then finite_float(value)
+      else raise TypeError, 'Expected a JSON response'
+      end
     end
 
-    def error_type(status)
+    def self.error_type(status)
       ERROR_TYPES.fetch(status) do
         status.between?(500, 599) ? Error::ServerError : Error::VolcanoError
       end
     end
 
-    def integer_header(headers, name)
+    def self.integer_header(headers, name)
       value = headers&.find { |key, _| key.casecmp?(name) }&.last
       Integer(value, exception: false)
     end
-    private_class_method :error_type, :integer_header, :response_error
+    private_class_method :error_type, :integer_header, :response_error, :finite_float, :json_scalar
   end
 end

data/lib/volcano/user.rb

@@ -10,15 +10,20 @@ module Volcano
   User = Data.define(
     :id, :project_id, :email, :email_confirmed, :user_metadata, :app_metadata,
     :avatar_url, :status, :banned_until, :last_sign_in_at, :created_at, :updated_at
-  ) do
+  )
+
+  # Reopens the generated record for checked initialization.
+  class User
+    # @dynamic id, project_id, email, email_confirmed, user_metadata, app_metadata
+    # @dynamic avatar_url, status, banned_until, last_sign_in_at, created_at, updated_at
+    # @dynamic members, with, to_h, deconstruct, deconstruct_keys, self.[], self.members
     def initialize(id:, email:, status:, **attributes)
       validate_optional_attributes(attributes)
-      super(
-        id: freeze_value(id),
-        email: freeze_value(email),
-        status: freeze_value(status),
-        **USER_OPTIONAL_ATTRIBUTES.to_h { |name| [name, freeze_value(attributes[name])] }
-      )
+      id = freeze_value(id)
+      email = freeze_value(email)
+      status = freeze_value(status)
+      attributes = USER_OPTIONAL_ATTRIBUTES.to_h { |name| [name, freeze_value(attributes[name])] }
+      super
     end
 
     private

data/lib/volcano/version.rb

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

data/lib/volcano.rb

@@ -16,6 +16,7 @@ require_relative 'volcano/auth_state'
 require_relative 'volcano/errors'
 require_relative 'volcano/redaction'
 require_relative 'volcano/transport'
+require_relative 'volcano/immutable_request_value'
 require_relative 'volcano/generated_transport'
 require_relative 'volcano/auth_notification_dispatch'
 require_relative 'volcano/auth_session_binding'

data/sig/auth_session_records.rbs

@@ -20,7 +20,7 @@ module Volcano
                | (id: String, user_id: String, provider: String, expires_at: Time, is_active: bool, is_current: bool, ?user_agent: String?, ?ip_address: String?, ?last_ip_address: String?, ?last_activity_at: Time?, ?session_started_at: Time?, ?created_at: Time?, ?updated_at: Time?) -> AuthSession
     def self.members: () -> [:id, :user_id, :provider, :expires_at, :is_active, :is_current, :user_agent, :ip_address, :last_ip_address, :last_activity_at, :session_started_at, :created_at, :updated_at]
 
-    def initialize: (id: String, user_id: String, provider: String, expires_at: Time, is_active: bool, is_current: bool, ?user_agent: String?, ?ip_address: String?, ?last_ip_address: String?, ?last_activity_at: Time?, ?session_started_at: Time?, ?created_at: Time?, ?updated_at: Time?) -> void
+    private def initialize: (**Object? attributes) -> void
     def members: () -> [:id, :user_id, :provider, :expires_at, :is_active, :is_current, :user_agent, :ip_address, :last_ip_address, :last_activity_at, :session_started_at, :created_at, :updated_at]
     def with: (?id: String, ?user_id: String, ?provider: String, ?expires_at: Time, ?is_active: bool, ?is_current: bool, ?user_agent: String?, ?ip_address: String?, ?last_ip_address: String?, ?last_activity_at: Time?, ?session_started_at: Time?, ?created_at: Time?, ?updated_at: Time?) -> AuthSession
     def to_h: () -> { id: String, user_id: String, provider: String, expires_at: Time, is_active: bool, is_current: bool, user_agent: String?, ip_address: String?, last_ip_address: String?, last_activity_at: Time?, session_started_at: Time?, created_at: Time?, updated_at: Time? }

data/sig/client.rbs

@@ -0,0 +1,15 @@
+module Volcano
+  class Client
+    attr_reader auth: Auth
+    attr_reader functions: Functions
+    attr_reader durable: Durable
+    attr_reader logs: Logs
+    attr_reader storage: Storage
+    attr_reader locks: Locks
+    attr_reader realtime: Realtime
+
+    def initialize: (anon_key: String, ?api_url: String, ?service_key: String?, ?timeout: (Integer | Float), ?access_token: String?, ?refresh_token: String?) -> void
+    def current_session: () -> Session?
+    def database: (String name) -> Database
+  end
+end

data/sig/core_facades.rbs

@@ -0,0 +1,81 @@
+module Volcano
+  type sdk_json = nil | bool | Integer | Float | String | Time | Array[sdk_json] | Hash[String | Symbol, sdk_json]
+  type sdk_payload = Hash[String | Symbol, sdk_json]
+  type database_rows = Array[Hash[String, json_value]]
+
+  class Database
+    def from: (String table) -> QueryBuilder
+  end
+
+  class QueryBuilder
+    def select: (*String columns) -> QueryBuilder
+    def insert: (sdk_payload values) -> InsertBuilder
+    def update: (sdk_payload values) -> UpdateBuilder
+    def delete: () -> DeleteBuilder
+    def order: (String column, ?ascending: bool) -> QueryBuilder
+    def limit: (Integer count) -> QueryBuilder
+    def offset: (Integer count) -> QueryBuilder
+    def execute: () -> database_rows
+
+    def eq: (String column, sdk_json value) -> QueryBuilder
+    def neq: (String column, sdk_json value) -> QueryBuilder
+    def gt: (String column, sdk_json value) -> QueryBuilder
+    def gte: (String column, sdk_json value) -> QueryBuilder
+    def lt: (String column, sdk_json value) -> QueryBuilder
+    def lte: (String column, sdk_json value) -> QueryBuilder
+    def like: (String column, String pattern) -> QueryBuilder
+    def ilike: (String column, String pattern) -> QueryBuilder
+    def is: (String column, sdk_json value) -> QueryBuilder
+    def in: (String column, Array[sdk_json] values) -> QueryBuilder
+  end
+
+  class InsertBuilder
+    def execute: () -> database_rows
+  end
+
+  class UpdateBuilder
+    def execute: () -> database_rows
+
+    def eq: (String column, sdk_json value) -> UpdateBuilder
+    def neq: (String column, sdk_json value) -> UpdateBuilder
+    def gt: (String column, sdk_json value) -> UpdateBuilder
+    def gte: (String column, sdk_json value) -> UpdateBuilder
+    def lt: (String column, sdk_json value) -> UpdateBuilder
+    def lte: (String column, sdk_json value) -> UpdateBuilder
+    def like: (String column, String pattern) -> UpdateBuilder
+    def ilike: (String column, String pattern) -> UpdateBuilder
+    def is: (String column, sdk_json value) -> UpdateBuilder
+    def in: (String column, Array[sdk_json] values) -> UpdateBuilder
+  end
+
+  class DeleteBuilder
+    def execute: () -> database_rows
+
+    def eq: (String column, sdk_json value) -> DeleteBuilder
+    def neq: (String column, sdk_json value) -> DeleteBuilder
+    def gt: (String column, sdk_json value) -> DeleteBuilder
+    def gte: (String column, sdk_json value) -> DeleteBuilder
+    def lt: (String column, sdk_json value) -> DeleteBuilder
+    def lte: (String column, sdk_json value) -> DeleteBuilder
+    def like: (String column, String pattern) -> DeleteBuilder
+    def ilike: (String column, String pattern) -> DeleteBuilder
+    def is: (String column, sdk_json value) -> DeleteBuilder
+    def in: (String column, Array[sdk_json] values) -> DeleteBuilder
+  end
+
+  class Functions
+    def invoke: (String name, ?sdk_payload payload) -> FunctionResponse
+  end
+
+  class Durable
+    def start: (String function_name, ?sdk_payload payload, ?execution_name: String?) -> DurableExecution
+    def get: (String project_id, String function_name, String execution_id) -> DurableExecution
+    def list: (String project_id, String function_name, ?status: String?, ?page: Integer?, ?limit: Integer?) -> DurableExecutionPage
+    def stop: (String project_id, String function_name, String execution_id) -> DurableExecution
+  end
+
+  class Logs
+    def search: (String project_id, sdk_payload request) -> LogSearchResponse
+    def activity: (String project_id, sdk_payload request) -> LogActivityResponse
+  end
+end

data/sig/durable_records.rbs

@@ -36,7 +36,7 @@ module Volcano
                | (id: String, function_id: String, name: String, status: String, region: String, created_at: Time, ?result: json_value, ?result_expired: bool?, ?error: DurableExecutionError?, ?completed_at: Time?) -> DurableExecution
     def self.members: () -> [:id, :function_id, :name, :status, :region, :created_at, :result, :result_expired, :error, :completed_at]
 
-    def initialize: (id: String, function_id: String, name: String, status: String, region: String, created_at: Time, ?result: json_value, ?result_expired: bool?, ?error: DurableExecutionError?, ?completed_at: Time?) -> void
+    private def initialize: (**(json_value | Time | DurableExecutionError) attributes) -> void
     def members: () -> [:id, :function_id, :name, :status, :region, :created_at, :result, :result_expired, :error, :completed_at]
     def with: (?id: String, ?function_id: String, ?name: String, ?status: String, ?region: String, ?created_at: Time, ?result: json_value, ?result_expired: bool?, ?error: DurableExecutionError?, ?completed_at: Time?) -> DurableExecution
     def to_h: () -> { id: String, function_id: String, name: String, status: String, region: String, created_at: Time, result: json_value, result_expired: bool?, error: DurableExecutionError?, completed_at: Time? }

data/sig/locks.rbs

@@ -0,0 +1,10 @@
+module Volcano
+  class Locks
+    def get: (String key, ?request_id: String?) -> LockState
+    def acquire: (String key, ttl: Integer, ?token: String?, ?request_id: String?) -> LockLease
+    def renew: (String key, LockLease lease, ttl: Integer, ?request_id: String?) -> LockLease
+    def release: (String key, LockLease lease, ?request_id: String?) -> nil
+    def force_release: (String key, ?request_id: String?) -> nil
+    def with_lock: [T] (String key, ttl: Integer, ?token: String?, ?request_id: String?) { (LockGuard) -> T } -> T
+  end
+end

data/sig/realtime.rbs

@@ -0,0 +1,45 @@
+module Volcano
+  class Realtime
+    def channel: (String name, ?type: String | Symbol, ?auto_fetch: bool, ?fetch_batch_window_ms: Integer, ?fetch_max_batch_size: Integer) -> Channel
+    def connected?: () -> bool
+    def disconnect: () -> void
+    def remove_channel: (String name, ?type: String | Symbol) -> nil
+    def remove_all_channels: () -> nil
+
+    def on_connect: (^(ConnectContext) -> void callback) -> ^() -> Proc?
+                  | () { (ConnectContext) -> void } -> ^() -> Proc?
+    def on_disconnect: (^(DisconnectContext) -> void callback) -> ^() -> Proc?
+                     | () { (DisconnectContext) -> void } -> ^() -> Proc?
+    def on_error: (^(ErrorContext) -> void callback) -> ^() -> Proc?
+                | () { (ErrorContext) -> void } -> ^() -> Proc?
+
+    def database_name: () -> String?
+    def database_name=: (String? name) -> String?
+
+    class Channel
+      attr_reader name: String
+
+      def subscribe: () -> nil
+      def unsubscribe: () -> nil
+      def send: (event: String | Symbol, **json_value payload) -> nil
+
+      def on: ("message" event, ^(Hash[String, json_value]) -> void callback) -> self
+            | ("message" event) { (Hash[String, json_value]) -> void } -> self
+            | ("join" | "leave" event, ^(PresenceInfo) -> void callback) -> self
+            | ("join" | "leave" event) { (PresenceInfo) -> void } -> self
+            | ("presence_sync" event, ^(Hash[String, PresenceInfo]) -> void callback) -> self
+            | ("presence_sync" event) { (Hash[String, PresenceInfo]) -> void } -> self
+            | ("INSERT" | "UPDATE" | "DELETE" | "*" event, ^(PostgresChange) -> void callback) -> self
+            | ("INSERT" | "UPDATE" | "DELETE" | "*" event) { (PostgresChange) -> void } -> self
+      def on_presence_sync: (^(Hash[String, PresenceInfo]) -> void callback) -> self
+                          | () { (Hash[String, PresenceInfo]) -> void } -> self
+      def on_postgres_changes: (String | Symbol event, schema: String, table: String, callback: ^(PostgresChange) -> void) -> self
+                             | (String | Symbol event, schema: String, table: String) { (PostgresChange) -> void } -> self
+
+      def track: (?Hash[String, json_value] state) -> nil
+      def presence_state: () -> Hash[String, PresenceInfo]
+      def get_presence_state: () -> Hash[String, PresenceInfo]
+      def tracked_state: () -> Hash[String, json_value]
+    end
+  end
+end