volcano-sdk 0.5.2

data/lib/volcano/realtime/reconnect.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Volcano
+  class Realtime
+    # Reconnects unexpected transport losses and restores subscription intent.
+    module Reconnect
+      RECONNECT_MIN_DELAY = 0.1
+      RECONNECT_MAX_DELAY = 20.0
+      MAX_BACKOFF_EXPONENT = 8
+
+      private
+
+      def start_reconnect
+        return if @closed || @reconnect_task || !reconnect_needed?
+
+        @reconnect_task = Async::Task.current.async { reconnect_loop }
+      end
+
+      def stop_reconnect
+        task = @reconnect_task
+        @reconnect_task = nil
+        task&.stop unless task.equal?(Async::Task.current)
+      end
+
+      def reconnect_loop
+        attempt = 0
+        loop do
+          break if reconnect_attempt_finished?(attempt)
+
+          attempt += 1
+        end
+      ensure
+        @reconnect_task = nil if @reconnect_task.equal?(Async::Task.current)
+      end
+
+      def reconnect_attempt_finished?(attempt)
+        wait_before_reconnect(attempt)
+        return true unless reconnect_needed?
+
+        protocol = current_or_connect_protocol
+        return false unless protocol
+
+        restore_subscriptions(protocol)
+        subscriptions_restored?(protocol)
+      end
+
+      def wait_before_reconnect(attempt)
+        delay = @reconnect_delay.call(attempt)
+        Async::Task.current.sleep(delay) if delay.positive?
+      end
+
+      def current_or_connect_protocol
+        protocol_lock.acquire do
+          next @protocol if @protocol&.connected?
+
+          connect_protocol
+        end
+      rescue StandardError
+        nil
+      end
+
+      def restore_subscriptions(protocol)
+        channels_snapshot.each do |channel|
+          channel.restore_subscription(protocol)
+        rescue StandardError => e
+          report_channel_error(e)
+        end
+      end
+
+      def subscriptions_restored?(protocol)
+        return false unless @protocol.equal?(protocol) && protocol.connected?
+
+        channels_snapshot.none?(&:restoration_needed?)
+      end
+
+      def channels_snapshot = channel_lock.acquire { @channels.values }
+
+      def reconnect_needed? = !@closed && @channels.each_value.any?(&:restoration_needed?)
+
+      def default_reconnect_delay(attempt)
+        exponent = [attempt, MAX_BACKOFF_EXPONENT].min
+        ceiling = [RECONNECT_MIN_DELAY * (2**exponent), RECONNECT_MAX_DELAY].min
+        rand * ceiling
+      end
+    end
+    private_constant :Reconnect
+  end
+end

data/lib/volcano/realtime.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative 'realtime/connection_callbacks'
+require_relative 'realtime/connection'
+require_relative 'realtime/reconnect'
+require_relative 'realtime/lifecycle'
+require_relative 'realtime/channel_lifecycle'
+require_relative 'realtime/presence_state'
+require_relative 'realtime/presence'
+require_relative 'realtime/postgres_database'
+require_relative 'realtime/blocking_call'
+require_relative 'realtime/postgres_changes'
+require_relative 'realtime/postgres_expansion'
+require_relative 'realtime/postgres_batch'
+require_relative 'realtime/postgres_delivery'
+require_relative 'realtime/broadcast_delivery'
+require_relative 'realtime/channel_callbacks'
+
+module Volcano
+  # Manages a project's realtime connection and broadcast channels.
+  class Realtime
+    include Lifecycle
+    include ConnectionCallbacks
+    include Connection
+    include Reconnect
+    include PostgresDatabase
+
+    ConnectContext = Data.define(:client)
+    DisconnectContext = Data.define(:code, :reason)
+    ErrorContext = Data.define(:code, :message, :error)
+
+    # Recursively snapshots JSON-compatible values for callback and state safety.
+    module Immutable
+      module_function
+
+      def call(value)
+        case value
+        when Hash then value.to_h { |key, child| [call(key), call(child)] }.freeze
+        when Array then value.map { |child| call(child) }.freeze
+        when String then value.dup.freeze
+        else value.freeze
+        end
+      end
+    end
+    private_constant :Immutable
+
+    PresenceInfo = Data.define(:client, :user, :data) do
+      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)
+        )
+      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
+
+    def initialize_realtime_state
+      @protocol = nil
+      @protocol_lock = nil
+      @channel_lock = nil
+      @channels = {}
+      @connection_callbacks = { connect: {}, disconnect: {}, error: {} }
+      @next_connection_callback_id = 0
+      @protocol_user_id = 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
+      )
+      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)
+      end
+    end
+
+    def protocol
+      ensure_open!
+      return @protocol if @protocol
+
+      protocol_lock.acquire do
+        ensure_open!
+        @protocol ||= connect_protocol
+      end
+    rescue StandardError => e
+      raise public_error(e), cause: nil
+    end
+    private :protocol
+
+    def disconnect
+      @protocol_lock ? @protocol_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
+
+      self
+    end
+
+    private
+
+    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
+
+    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 build_channel(name, type, batch_config)
+      Channel.new(self, method(:protocol), name, type, batch_config:)
+    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)
+    end
+
+    # Represents one realtime broadcast channel.
+    class Channel
+      include ChannelLifecycle
+      include PresenceState
+      include Presence
+      include PostgresChanges
+      include PostgresExpansion
+      include PostgresBatch
+      include PostgresDelivery
+      include BroadcastDelivery
+      include ChannelCallbacks
+
+      attr_reader :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_callback_dispatch
+        initialize_presence(type)
+        initialize_postgres_delivery(batch_config)
+      end
+
+      def subscribe
+        protocol, epoch = with_lifecycle_lock { subscribe_with_intent }
+        sync_presence(protocol, epoch)
+        nil
+      end
+
+      def send(event:, **payload)
+        with_lifecycle_lock do
+          ensure_open!
+          raise ClosedError, 'realtime channel is not subscribed' unless @subscribed
+          raise ArgumentError, 'send is only available for broadcast channels' unless broadcast?
+
+          data = { 'event' => event.to_s, **payload.transform_keys(&:to_s) }
+          @protocol_provider.call.publish(channel: @name, data: data)
+        end
+        nil
+      end
+
+      def unsubscribe
+        state = with_lifecycle_lock { unsubscribe_protocol }
+        emit_presence_sync(state)
+        nil
+      end
+
+      def subscription_desired? = @subscription_desired && !@closed
+
+      def restoration_needed? = subscription_desired? && !@subscribed
+
+      def restore_subscription(protocol)
+        state = with_lifecycle_lock do
+          next unless restoration_needed?
+
+          subscribe_protocol(protocol)
+        end
+        sync_presence(*state) if state
+        nil
+      end
+
+      def remove
+        with_lifecycle_lock do
+          ensure_open!
+          detach_from_protocol
+          clear_broadcast_recovery_state
+          clear_channel_recovery_state
+          mark_removed
+        end
+        nil
+      end
+      private :remove
+
+      private
+
+      def subscribe_with_intent
+        ensure_open!
+        raise DuplicateSubscriptionError, "already subscribed to #{@name}" if @subscription_desired
+
+        @subscription_desired = true
+        protocol = @protocol_provider.call
+        subscribe_protocol(protocol)
+      rescue StandardError
+        @subscription_desired = false unless protocol && !protocol.connected?
+        raise
+      end
+
+      def with_lifecycle_lock(&)
+        require 'async/semaphore'
+        @lifecycle_lock ||= Async::Semaphore.new(1)
+        @lifecycle_lock.acquire(&)
+      end
+
+      def ensure_open!
+        raise ClosedError, 'realtime connection closed' if @closed
+
+        @realtime.ensure_open!
+      end
+    end
+  end
+end

data/lib/volcano/redaction.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Volcano
+  # Removes credentials from exception messages before they cross the SDK boundary.
+  module Redaction
+    MARKER = '[REDACTED]'
+
+    module_function
+
+    def message(value, secrets:)
+      variants(secrets).reduce(value.to_s.dup) do |redacted, secret|
+        redacted.gsub(secret, MARKER)
+      end
+    end
+
+    def exception(error, secrets:)
+      redacted = copy_exception(error, message(error.message, secrets: secrets))
+      redacted.set_backtrace(error.backtrace)
+      redacted
+    end
+
+    def copy_exception(error, redacted_message)
+      return copy_volcano_error(error, redacted_message) if volcano_error?(error)
+      return error.class.new(redacted_message, code: error.code) if realtime_server_error?(error)
+
+      error.exception(redacted_message)
+    end
+
+    def copy_volcano_error(error, redacted_message)
+      error.class.new(
+        redacted_message,
+        status: error.status,
+        code: error.code,
+        retry_after: error.retry_after
+      )
+    end
+
+    def volcano_error?(error)
+      defined?(Error::VolcanoError) && error.is_a?(Error::VolcanoError)
+    end
+
+    def realtime_server_error?(error)
+      defined?(Realtime::ServerError) && error.is_a?(Realtime::ServerError)
+    end
+
+    def variants(secrets)
+      values = Array(secrets).compact.flat_map do |value|
+        secret = value.to_s
+        next [] if secret.empty?
+
+        encoded = URI.encode_www_form_component(secret)
+        [secret, encoded, encoded.gsub('+', '%20')]
+      end
+      values.uniq.sort_by { |value| -value.length }
+    end
+    private_class_method :copy_exception, :copy_volcano_error, :realtime_server_error?, :variants, :volcano_error?
+  end
+end

data/lib/volcano/sign_up_result.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Volcano
+  SignUpResult = Data.define(:confirmation_required, :message, :session) do
+    def initialize(confirmation_required:, message:, session: nil)
+      super
+    end
+  end
+end

data/lib/volcano/storage.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Volcano
+  # Entry point for project object storage.
+  class Storage
+    def initialize(client, transport, api_url:, anon_key:)
+      @client = client
+      @transport = transport
+      @api_url = api_url
+      @anon_key = anon_key
+    end
+
+    def from(bucket)
+      StorageBucket.new(
+        @client,
+        @transport,
+        bucket,
+        api_url: @api_url,
+        anon_key: @anon_key
+      )
+    end
+  end
+
+  # Operates on objects in one storage bucket.
+  class StorageBucket
+    def initialize(client, transport, name, api_url:, anon_key:)
+      @client = client
+      @transport = transport
+      @name = name
+      @api_url = api_url.dup.freeze
+      @anon_key = anon_key.dup.freeze
+      freeze
+    end
+
+    def upload(path, value, content_type: nil)
+      mime_type = upload_content_type(content_type)
+      response = Transport.invoke do
+        @transport.upload_storage_object(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          path: path,
+          data: upload_bytes(value),
+          content_type: mime_type
+        )
+      end
+      Transport.body(response, 201)
+    end
+
+    def download(path, range: nil)
+      response = Transport.invoke do
+        @transport.download_storage_object(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          path: path,
+          byte_range: range
+        )
+      end
+      expected_status = range && response.status == 206 ? 206 : 200
+      Transport.body(response, expected_status)
+      response.data.b
+    end
+
+    def list(prefix = '', limit: nil, cursor: nil)
+      response = Transport.invoke do
+        @transport.list_storage_objects(
+          authorization: @client.session_token,
+          bucket_name: @name,
+          prefix: prefix,
+          limit: limit,
+          cursor: cursor
+        )
+      end
+      payload = Transport.body(response, 200)
+      next_cursor = payload['next_cursor']
+      StoragePage.new(
+        objects: payload.fetch('objects', []).map { |object| storage_object(object) },
+        next_cursor: next_cursor == '' ? nil : next_cursor
+      )
+    end
+
+    private
+
+    def upload_content_type(value)
+      return if value.nil?
+      return value.dup.freeze if value.is_a?(String) && value.match?(/\A[\x20-\x7e]+\z/) && !value.strip.empty?
+
+      raise ArgumentError, 'content_type must be a non-blank printable ASCII string'
+    end
+
+    def upload_bytes(value)
+      bytes = value.respond_to?(:read) ? value.read : value
+      raise ArgumentError, 'upload data must be a String or IO' unless bytes.is_a?(String)
+
+      bytes.b
+    end
+
+    def storage_object(payload)
+      StorageObject.new(
+        id: payload.fetch('id'),
+        bucket_id: payload.fetch('bucket_id'),
+        name: payload.fetch('name'),
+        size: payload.fetch('size'),
+        mime_type: payload.fetch('mime_type'),
+        is_public: payload.fetch('is_public'),
+        owner_id: payload['owner_id'],
+        etag: payload['etag'],
+        metadata: payload['metadata'],
+        created_at: parse_time(payload['created_at']),
+        updated_at: parse_time(payload['updated_at']),
+        public_url: payload['public_url']
+      )
+    end
+
+    def parse_time(value)
+      value.is_a?(String) ? Time.iso8601(value) : value
+    end
+  end
+end

data/lib/volcano/storage_models.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Volcano
+  STORAGE_OBJECT_ATTRIBUTES = %i[
+    id bucket_id name size mime_type is_public owner_id etag metadata created_at updated_at public_url
+  ].freeze
+  private_constant :STORAGE_OBJECT_ATTRIBUTES
+
+  StorageObject = Data.define(*STORAGE_OBJECT_ATTRIBUTES) do
+    def initialize(**attributes)
+      unknown = attributes.keys - STORAGE_OBJECT_ATTRIBUTES
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+      missing = STORAGE_OBJECT_ATTRIBUTES.first(6) - attributes.keys
+      raise ArgumentError, "missing keywords: #{missing.join(', ')}" unless missing.empty?
+
+      values = STORAGE_OBJECT_ATTRIBUTES.to_h do |name|
+        [name, immutable_value(attributes[name])]
+      end
+      super(**values)
+    end
+
+    private
+
+    def immutable_value(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [immutable_value(key), immutable_value(item)] }.freeze
+      when Array then value.map { |item| immutable_value(item) }.freeze
+      when String then value.dup.freeze
+      else value.frozen? ? value : value.dup.freeze
+      end
+    end
+  end
+
+  StoragePage = Data.define(:objects, :next_cursor) do
+    def initialize(objects:, next_cursor: nil)
+      cursor = next_cursor.nil? ? nil : next_cursor.dup.freeze
+      super(objects: objects.to_a.dup.freeze, next_cursor: cursor)
+    end
+  end
+
+  UploadSessionRequest = Data.define(:path, :content_type, :total_size, :part_size) do
+    def initialize(path:, content_type:, total_size:, part_size: nil)
+      super(
+        path: path.dup.freeze,
+        content_type: content_type.dup.freeze,
+        total_size: total_size,
+        part_size: part_size
+      )
+    end
+  end
+  private_constant :UploadSessionRequest
+
+  UploadPartRequest = Data.define(:path, :session_id, :part_number, :data) do
+    def initialize(path:, session_id:, part_number:, data:)
+      super(
+        path: path.dup.freeze,
+        session_id: session_id.dup.freeze,
+        part_number: part_number,
+        data: data.dup.freeze
+      )
+    end
+  end
+  private_constant :UploadPartRequest
+
+  UploadSessionReference = Data.define(:path, :session_id) do
+    def initialize(path:, session_id:)
+      super(path: path.dup.freeze, session_id: session_id.dup.freeze)
+    end
+  end
+  private_constant :UploadSessionReference
+
+  UploadSession = Data.define(:session_id, :part_size, :total_parts, :expires_at) do
+    def initialize(session_id:, part_size:, total_parts:, expires_at:)
+      super(
+        session_id: session_id.dup.freeze,
+        part_size: part_size,
+        total_parts: total_parts,
+        expires_at: expires_at.dup.freeze
+      )
+    end
+  end
+
+  UploadPart = Data.define(:part_number, :etag, :size) do
+    def initialize(part_number:, etag:, size:)
+      super(part_number: part_number, etag: etag.dup.freeze, size: size)
+    end
+  end
+
+  UPLOAD_SESSION_STATUS_ATTRIBUTES = %i[
+    session_id status path content_type total_size part_size total_parts parts_uploaded
+    bytes_uploaded parts expires_at created_at
+  ].freeze
+  private_constant :UPLOAD_SESSION_STATUS_ATTRIBUTES
+
+  UploadSessionStatus = Data.define(*UPLOAD_SESSION_STATUS_ATTRIBUTES) do
+    def initialize(**attributes)
+      unknown = attributes.keys - UPLOAD_SESSION_STATUS_ATTRIBUTES
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+      missing = UPLOAD_SESSION_STATUS_ATTRIBUTES - attributes.keys
+      raise ArgumentError, "missing keywords: #{missing.join(', ')}" unless missing.empty?
+
+      values = UPLOAD_SESSION_STATUS_ATTRIBUTES.to_h do |name|
+        [name, immutable_value(attributes.fetch(name))]
+      end
+      super(**values)
+    end
+
+    private
+
+    def immutable_value(value)
+      case value
+      when Array then value.to_a.dup.freeze
+      when String then value.dup.freeze
+      else value.frozen? ? value : value.dup.freeze
+      end
+    end
+  end
+end