volcano-sdk 0.30.0 → 0.32.0

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

@@ -6,8 +6,8 @@ module Volcano
   # Entry point for project object storage.
   class Storage
     def initialize(client, transport, api_url:, anon_key:)
-      @client = client
-      @transport = transport
+      @client = client.is_a?(StorageSessionAdapter) ? client : StorageSessionAdapter.new(client)
+      @transport = transport.is_a?(StorageTransportAdapter) ? transport : StorageTransportAdapter.new(transport)
       @api_url = api_url
       @anon_key = anon_key
     end
@@ -25,9 +25,11 @@ module Volcano
 
   # Operates on objects in one storage bucket.
   class StorageBucket
+    include StorageObjectResponse
+
     def initialize(client, transport, name, api_url:, anon_key:)
-      @client = client
-      @transport = transport
+      @client = client.is_a?(StorageSessionAdapter) ? client : StorageSessionAdapter.new(client)
+      @transport = transport.is_a?(StorageTransportAdapter) ? transport : StorageTransportAdapter.new(transport)
       @name = name.dup.freeze
       @api_url = api_url.dup.freeze
       @anon_key = anon_key.dup.freeze
@@ -36,7 +38,7 @@ module Volcano
 
     def upload(path, value, content_type: nil)
       mime_type = upload_content_type(content_type)
-      path = storage_paths(path).first
+      path = storage_paths(path).fetch(0)
       binding = @client.capture_session_binding
       @client.session_token
       content = upload_bytes(value).freeze
@@ -49,11 +51,11 @@ module Volcano
           content_type: mime_type
         )
       end
-      Transport.body(response, 201)
+      storage_payload(Transport.body(response, 201))
     end
 
     def download(path, range: nil)
-      path = storage_paths(path).first
+      path = storage_paths(path).fetch(0)
       range = range&.dup&.freeze
       response = storage_request do |token|
         @transport.download_storage_object(
@@ -65,7 +67,7 @@ module Volcano
       end
       expected_status = range && response.status == 206 ? 206 : 200
       Transport.body(response, expected_status)
-      response.data.b
+      storage_string(response.data).b
     end
 
     def list(prefix = '', limit: nil, cursor: nil)
@@ -80,11 +82,10 @@ module Volcano
           cursor: cursor
         )
       end
-      payload = Transport.body(response, 200)
-      next_cursor = payload['next_cursor']
+      payload = storage_payload(Transport.body(response, 200))
       StoragePage.new(
-        objects: payload.fetch('objects', []).map { |object| storage_object(object) },
-        next_cursor: next_cursor == '' ? nil : next_cursor
+        objects: storage_object_list(payload.fetch('objects', [])),
+        next_cursor: storage_cursor(payload['next_cursor'])
       )
     end
 
@@ -102,31 +103,14 @@ module Volcano
     end
 
     def upload_bytes(value)
-      bytes = value.respond_to?(:read) ? value.read : value
+      bytes = if value.is_a?(String)
+                value
+              elsif value.respond_to?(:read)
+                value.read
+              end
       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

@@ -6,7 +6,13 @@ module Volcano
   ].freeze
   private_constant :STORAGE_OBJECT_ATTRIBUTES
 
-  StorageObject = Data.define(*STORAGE_OBJECT_ATTRIBUTES) do
+  StorageObject = Data.define(*STORAGE_OBJECT_ATTRIBUTES)
+
+  # Validates and freezes object metadata returned by storage.
+  class StorageObject
+    # @dynamic id, bucket_id, name, size, mime_type, is_public, owner_id, etag
+    # @dynamic metadata, created_at, updated_at, public_url
+    # @dynamic members, with, to_h, deconstruct, deconstruct_keys, self.[], self.members
     def initialize(**attributes)
       unknown = attributes.keys - STORAGE_OBJECT_ATTRIBUTES
       raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
@@ -17,7 +23,8 @@ module Volcano
       values = STORAGE_OBJECT_ATTRIBUTES.to_h do |name|
         [name, immutable_value(attributes[name])]
       end
-      super(**values)
+      attributes = values
+      super
     end
 
     private
@@ -40,10 +47,16 @@ module Volcano
     end
   end
 
-  StoragePage = Data.define(:objects, :next_cursor) do
+  StoragePage = Data.define(:objects, :next_cursor)
+
+  # Freezes a page of storage objects and its cursor.
+  class StoragePage
+    # @dynamic objects, next_cursor, members, with, to_h, deconstruct, deconstruct_keys
+    # @dynamic self.[], self.members
     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)
+      objects = objects.to_a.dup.freeze
+      next_cursor = next_cursor.nil? ? nil : next_cursor.dup.freeze
+      super
     end
   end
 end

data/lib/volcano/storage_mutations.rb

@@ -11,7 +11,9 @@ module Volcano
     end
 
     def move(from_path, to_path)
-      source, destination = storage_paths([from_path, to_path])
+      paths = storage_paths([from_path, to_path])
+      source = paths.fetch(0)
+      destination = paths.fetch(1)
       response = storage_request do |token|
         @transport.move_storage_object(
           authorization: token,
@@ -24,7 +26,9 @@ module Volcano
     end
 
     def copy(from_path, to_path)
-      source, destination = storage_paths([from_path, to_path])
+      paths = storage_paths([from_path, to_path])
+      source = paths.fetch(0)
+      destination = paths.fetch(1)
       response = storage_request do |token|
         @transport.copy_storage_object(
           authorization: token,
@@ -75,7 +79,8 @@ module Volcano
     end
 
     def visibility_value(value)
-      return value if [true, false].include?(value)
+      return true if value == true
+      return false if value == false
 
       raise ArgumentError, 'public must be true or false'
     end

data/lib/volcano/storage_object_response.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Validates object metadata and paginated storage responses.
+  module StorageObjectResponse
+    include StorageResponse
+
+    private
+
+    def storage_object(payload)
+      payload = storage_payload(payload)
+      required = storage_object_required(payload)
+      optional = storage_object_optional(payload)
+      StorageObject.new(
+        id: required.fetch(0), bucket_id: required.fetch(1), name: required.fetch(2),
+        size: required.fetch(3), mime_type: required.fetch(4), is_public: required.fetch(5),
+        owner_id: optional.fetch(0), etag: optional.fetch(1), metadata: optional.fetch(2),
+        created_at: optional.fetch(3), updated_at: optional.fetch(4), public_url: optional.fetch(5)
+      )
+    end
+
+    def storage_object_required(payload)
+      [
+        storage_string(payload.fetch('id')), storage_string(payload.fetch('bucket_id')),
+        storage_string(payload.fetch('name')), storage_integer(payload.fetch('size')),
+        storage_string(payload.fetch('mime_type')), storage_boolean(payload.fetch('is_public'))
+      ]
+    end
+
+    def storage_object_optional(payload)
+      [
+        storage_optional_string(payload['owner_id']), storage_optional_string(payload['etag']),
+        storage_optional_metadata(payload['metadata']), storage_optional_time(payload['created_at']),
+        storage_optional_time(payload['updated_at']), storage_optional_string(payload['public_url'])
+      ]
+    end
+
+    def storage_object_list(value)
+      raise Error::TransportError, 'invalid storage objects' unless value.is_a?(Array)
+
+      value.map { |object| storage_object(object) }
+    end
+
+    def storage_cursor(value)
+      return if value.nil? || value == ''
+
+      storage_string(value)
+    end
+
+    def storage_boolean(value)
+      return true if value == true
+      return false if value == false
+
+      raise Error::TransportError, 'invalid storage boolean'
+    end
+
+    def storage_optional_string(value)
+      value.nil? ? nil : storage_string(value)
+    end
+
+    def storage_optional_time(value)
+      value.nil? ? nil : storage_time(value)
+    end
+
+    def storage_optional_metadata(value)
+      value.nil? ? nil : storage_json_hash(value)
+    end
+
+    def storage_json_hash(value)
+      raise Error::TransportError, 'invalid storage JSON object' unless value.is_a?(Hash)
+
+      value.to_h do |key, item|
+        raise Error::TransportError, 'invalid storage JSON key' unless key.is_a?(String)
+
+        [key, storage_json_value(item)]
+      end
+    end
+
+    def storage_json_value(value)
+      case value
+      when NilClass, TrueClass, FalseClass, Integer, Float, String then value
+      when Array then value.map { |item| storage_json_value(item) }
+      when Hash then storage_json_hash(value)
+      else raise Error::TransportError, 'invalid storage JSON value'
+      end
+    end
+  end
+end

data/lib/volcano/storage_response.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Decodes resumable-upload responses before creating public records.
+  module StorageResponse
+    private
+
+    def upload_session(payload)
+      payload = storage_payload(payload)
+      UploadSession.new(
+        session_id: storage_string(payload.fetch('session_id')),
+        part_size: storage_integer(payload.fetch('part_size')),
+        total_parts: storage_integer(payload.fetch('total_parts')),
+        expires_at: storage_time(payload.fetch('expires_at'))
+      )
+    end
+
+    def upload_part_metadata(payload)
+      payload = storage_payload(payload)
+      UploadPart.new(
+        part_number: storage_integer(payload.fetch('part_number')),
+        etag: storage_string(payload.fetch('etag')),
+        size: storage_integer(payload.fetch('size'))
+      )
+    end
+
+    def upload_session_status(payload)
+      payload = storage_payload(payload)
+      text = storage_status_text(payload)
+      counts = storage_status_counts(payload)
+      storage_status_record(payload, text, counts)
+    end
+
+    def storage_status_record(payload, text, counts)
+      UploadSessionStatus.new(
+        session_id: text.fetch(0), status: text.fetch(1), path: text.fetch(2),
+        content_type: text.fetch(3), total_size: counts.fetch(0), part_size: counts.fetch(1),
+        total_parts: counts.fetch(2), parts_uploaded: counts.fetch(3),
+        bytes_uploaded: counts.fetch(4), parts: storage_parts(payload.fetch('parts', [])),
+        expires_at: storage_time(payload.fetch('expires_at')),
+        created_at: storage_time(payload.fetch('created_at'))
+      )
+    end
+
+    def storage_status_text(payload)
+      [
+        storage_string(payload.fetch('session_id')), storage_string(payload.fetch('status')),
+        storage_string(payload.fetch('path')), storage_string(payload.fetch('content_type'))
+      ]
+    end
+
+    def storage_status_counts(payload)
+      [
+        storage_integer(payload.fetch('total_size')), storage_integer(payload.fetch('part_size')),
+        storage_integer(payload.fetch('total_parts')), storage_integer(payload.fetch('parts_uploaded')),
+        storage_integer(payload.fetch('bytes_uploaded'))
+      ]
+    end
+
+    def storage_parts(value)
+      raise Error::TransportError, 'invalid upload parts' unless value.is_a?(Array)
+
+      value.map { |part| upload_part_metadata(part) }
+    end
+
+    def storage_payload(value)
+      raise Error::TransportError, 'invalid storage response' unless value.is_a?(Hash)
+      raise Error::TransportError, 'invalid storage response key' unless value.keys.all?(String)
+
+      value
+    end
+
+    def storage_string(value)
+      raise Error::TransportError, 'invalid storage string' unless value.is_a?(String)
+
+      value
+    end
+
+    def storage_integer(value)
+      raise Error::TransportError, 'invalid storage integer' unless value.is_a?(Integer)
+
+      value
+    end
+
+    def storage_time(value)
+      return value if value.is_a?(Time)
+      return Time.iso8601(value) if value.is_a?(String)
+
+      raise Error::TransportError, 'invalid storage time'
+    end
+  end
+end