volcano-sdk 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 296cdb524e3552873235adccfe2d5c98b39a3da451c06777020b59d45c6a4be0
-  data.tar.gz: 9ca783889458304d91b40601f673a4f5015f117ee4f30f90c23891e351cafe3a
+  metadata.gz: 36cf6c142c98f421f086d919b4d5e83034e95831d2b4246a892be57ebfaea9d5
+  data.tar.gz: 877909af108367683c4cbb434235baa27669af9d303dd0b52307919446f8c348
 SHA512:
-  metadata.gz: 81067b14e84482e5dfebf935d27051c109ff14b87d144814a36db6ef5a7de6003e0cde0fe4ed4c54c1e06dcd9db79d8f5088c1aa21fbd4bbc3419da9a585f44e
-  data.tar.gz: 4346575e985ab233b5afd723f36e1044b4e9e001b1eefa461a2514977f10a240a88a73978f30d88b2b74a3ec2a6bd4565d1e1ab92968e1988069492cbae9c739
+  metadata.gz: 832893a1b1ba6caa88f144b81d8b8e155d2041be82fccffe4328eeb1f59f4fc8e3ce84adbb476f3b1a6b26ed719da7293f9dfb6a563270cdcb5222125661f378
+  data.tar.gz: acfb489b98c3e8dcca7918ee1136d4e04f62fec2a7287fcc16fcd952edd3bfae2d4973b6307ef53d577a08cb4104511666917e4435c3d7722bb3cde544d7ad3d

data/lib/volcano/auth.rb

@@ -9,9 +9,7 @@ module Volcano
     include AuthUpdateUser
     include AuthEmailChange
     include AuthSessions
-
-    INCOMPLETE_SESSION = 'Expected a complete Volcano::Session'
-    private_constant :INCOMPLETE_SESSION
+    include AuthSessionConstruction
 
     def initialize(client, transport, api_url:)
       @client = client
@@ -27,10 +25,10 @@ module Volcano
       @client.store_session(owned_complete_session(session), event: nil)
     end
 
-    def on_auth_state_change(&callback)
-      raise ArgumentError, 'callback block required' unless callback
+    def on_auth_state_change(&)
+      raise ArgumentError, 'callback block required' unless block_given?
 
-      @client.subscribe_auth_state_change(&callback)
+      @client.subscribe_auth_state_change(&)
     end
 
     def sign_in(email:, password:)
@@ -77,47 +75,5 @@ module Volcano
         )
       end
     end
-
-    def build_session(payload)
-      owned_session(
-        access_token: payload.fetch('access_token'),
-        refresh_token: payload.fetch('refresh_token'),
-        user_id: payload.fetch('user').fetch('id'),
-        user: payload.fetch('user')
-      )
-    end
-
-    def parse_refresh_session(payload)
-      owned_complete_session(build_session(payload))
-    rescue KeyError, TypeError, NoMethodError, ArgumentError => e
-      raise Error::TransportError, INCOMPLETE_SESSION, cause: e
-    end
-
-    def complete_session?(session)
-      return false unless session.is_a?(Session)
-
-      values = [session.access_token, session.refresh_token, session.user_id]
-      values.all? { |value| value.is_a?(String) && !value.strip.empty? } &&
-        matching_session_user?(session)
-    end
-
-    def matching_session_user?(session)
-      session.user.nil? || (session.user.is_a?(Hash) && session.user['id'] == session.user_id)
-    end
-
-    def owned_complete_session(session)
-      raise ArgumentError, INCOMPLETE_SESSION unless complete_session?(session)
-
-      owned_session(**session.to_h)
-    end
-
-    def owned_session(access_token:, refresh_token:, user_id:, user: nil)
-      Session.new(
-        access_token: access_token.dup.freeze,
-        refresh_token: refresh_token.dup.freeze,
-        user_id: user_id.dup.freeze,
-        user: user
-      )
-    end
   end
 end

data/lib/volcano/auth_session_construction.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Builds and validates owned credential snapshots for the auth facade.
+  module AuthSessionConstruction
+    INCOMPLETE_SESSION = 'Expected a complete Volcano::Session'
+    private_constant :INCOMPLETE_SESSION
+
+    private
+
+    def build_session(payload)
+      raise TypeError, INCOMPLETE_SESSION unless payload.is_a?(Hash)
+
+      user = payload.fetch('user')
+      raise TypeError, INCOMPLETE_SESSION unless user.is_a?(Hash)
+
+      owned_session(
+        access_token: required_session_string(payload.fetch('access_token')),
+        refresh_token: required_session_string(payload.fetch('refresh_token')),
+        user_id: required_session_string(user.fetch('id')),
+        user: user
+      )
+    end
+
+    def parse_refresh_session(payload)
+      owned_complete_session(build_session(payload))
+    rescue KeyError, TypeError, NoMethodError, ArgumentError => e
+      raise Error::TransportError, INCOMPLETE_SESSION, cause: e
+    end
+
+    def complete_session?(session)
+      values = [session.access_token, session.refresh_token, session.user_id]
+      values.all? { |value| value.is_a?(String) && !value.strip.empty? } &&
+        matching_session_user?(session)
+    end
+
+    def matching_session_user?(session)
+      session.user.nil? || (session.user.is_a?(Hash) && session.user['id'] == session.user_id)
+    end
+
+    def owned_complete_session(session)
+      raise ArgumentError, INCOMPLETE_SESSION unless session.is_a?(Session) && complete_session?(session)
+
+      owned_session(
+        access_token: required_session_string(session.access_token),
+        refresh_token: required_session_string(session.refresh_token),
+        user_id: required_session_string(session.user_id),
+        user: session.user
+      )
+    end
+
+    def required_session_string(value)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, INCOMPLETE_SESSION
+    end
+
+    def owned_session(access_token:, refresh_token:, user_id:, user: nil)
+      Session.new(
+        access_token: access_token.dup.freeze,
+        refresh_token: refresh_token.dup.freeze,
+        user_id: user_id.dup.freeze,
+        user: user
+      )
+    end
+  end
+end

data/lib/volcano/auth_sign_up.rb

@@ -29,6 +29,8 @@ module Volcano
     end
 
     def build_sign_up_result(payload)
+      raise TypeError, INVALID_SIGN_UP_RESULT unless payload.is_a?(Hash)
+
       confirmation_required = payload.fetch('confirmation_required')
       message = payload.fetch('message')
       valid = [true, false].include?(confirmation_required) && message.is_a?(String)

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

data/lib/volcano/storage_resumable_upload.rb

@@ -30,7 +30,7 @@ module Volcano
     def upload_session_parts(path, source, session, total_size, on_progress)
       uploaded = 0
       session.total_parts.times do |part_index|
-        part = source.read(session.part_size)
+        part = source.read(session.part_size) || raise(IOError, 'upload source ended before completion')
         upload_part(
           path,
           session_id: session.session_id,
@@ -64,11 +64,22 @@ module Volcano
     def remaining_upload_bytes(source)
       return unless source.respond_to?(:size) && source.respond_to?(:pos)
 
-      source.size - source.pos
+      dimensions = upload_source_dimensions(source)
+      return unless dimensions
+
+      dimensions.fetch(0) - dimensions.fetch(1)
     rescue IOError, SystemCallError
       nil
     end
 
+    def upload_source_dimensions(source)
+      size = source.method(:size).call
+      position = source.method(:pos).call
+      return unless size.is_a?(Integer) && position.is_a?(Integer)
+
+      [size, position]
+    end
+
     def with_spooled_upload_source(source)
       Tempfile.create('volcano-upload') do |file|
         file.binmode

data/lib/volcano/storage_session_adapter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Validates the client methods that storage uses for session-scoped requests.
+  class StorageSessionAdapter
+    def initialize(client)
+      @client = client
+    end
+
+    def capture_session_binding
+      binding = storage_binding_array(@client.method(:capture_session_binding).call)
+      generation, owner, session = binding
+      [storage_generation(generation), storage_owner(owner), storage_session(session)]
+    end
+
+    def session_token
+      token = @client.method(:session_token).call
+      raise Error::TransportError, 'invalid storage session token' unless token.is_a?(String)
+
+      token
+    end
+
+    def session_request(binding:, &)
+      method_name = :session_request
+      response = @client.public_send(method_name, binding: binding) do |token|
+        raise Error::TransportError, 'invalid storage session token' unless token.is_a?(String)
+
+        yield token
+      end
+      raise Error::TransportError, 'invalid storage session response' unless response.is_a?(Transport::Response)
+
+      response
+    end
+
+    private
+
+    def storage_binding_array(value)
+      raise Error::TransportError, 'invalid storage session binding' unless value.is_a?(Array) && value.size == 3
+
+      value
+    end
+
+    def storage_generation(value)
+      raise Error::TransportError, 'invalid storage session binding' unless value.is_a?(Integer)
+
+      value
+    end
+
+    def storage_owner(value)
+      raise Error::TransportError, 'invalid storage session binding' unless value.is_a?(SessionOperations)
+
+      value
+    end
+
+    def storage_session(value)
+      raise Error::TransportError, 'invalid storage session binding' unless value.nil? || value.is_a?(Session)
+
+      value
+    end
+  end
+end

data/lib/volcano/storage_transport_adapter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Narrows generated and test transport calls to checked storage responses.
+  class StorageTransportAdapter
+    def initialize(transport)
+      @transport = transport
+    end
+
+    def upload_storage_object(authorization:, bucket_name:, path:, data:, content_type:)
+      invoke(:upload_storage_object, authorization: authorization, bucket_name: bucket_name,
+                                     path: path, data: data, content_type: content_type)
+    end
+
+    def download_storage_object(authorization:, bucket_name:, path:, byte_range:)
+      invoke(:download_storage_object, authorization: authorization, bucket_name: bucket_name,
+                                       path: path, byte_range: byte_range)
+    end
+
+    def list_storage_objects(authorization:, bucket_name:, prefix:, limit:, cursor:)
+      invoke(:list_storage_objects, authorization: authorization, bucket_name: bucket_name,
+                                    prefix: prefix, limit: limit, cursor: cursor)
+    end
+
+    def delete_storage_object(authorization:, bucket_name:, path:)
+      invoke(:delete_storage_object, authorization: authorization, bucket_name: bucket_name, path: path)
+    end
+
+    def move_storage_object(authorization:, bucket_name:, from_path:, to_path:)
+      invoke(:move_storage_object, authorization: authorization, bucket_name: bucket_name,
+                                   from_path: from_path, to_path: to_path)
+    end
+
+    def copy_storage_object(authorization:, bucket_name:, from_path:, to_path:)
+      invoke(:copy_storage_object, authorization: authorization, bucket_name: bucket_name,
+                                   from_path: from_path, to_path: to_path)
+    end
+
+    def update_storage_object_visibility(authorization:, bucket_name:, path:, is_public:)
+      invoke(:update_storage_object_visibility, authorization: authorization, bucket_name: bucket_name,
+                                                path: path, is_public: is_public)
+    end
+
+    def create_upload_session(authorization:, bucket_name:, request:)
+      invoke(:create_upload_session, authorization: authorization, bucket_name: bucket_name, request: request)
+    end
+
+    def upload_part(authorization:, bucket_name:, request:)
+      invoke(:upload_part, authorization: authorization, bucket_name: bucket_name, request: request)
+    end
+
+    def complete_upload_session(authorization:, bucket_name:, request:)
+      invoke(:complete_upload_session, authorization: authorization, bucket_name: bucket_name, request: request)
+    end
+
+    def get_upload_session(authorization:, bucket_name:, request:)
+      invoke(:get_upload_session, authorization: authorization, bucket_name: bucket_name, request: request)
+    end
+
+    def abort_upload_session(authorization:, bucket_name:, request:)
+      invoke(:abort_upload_session, authorization: authorization, bucket_name: bucket_name, request: request)
+    end
+
+    private
+
+    def invoke(name, **arguments)
+      response = @transport.public_send(name, **arguments)
+      raise Error::TransportError, 'invalid storage transport response' unless response.is_a?(Transport::Response)
+
+      response
+    end
+  end
+end

data/lib/volcano/storage_upload_models.rb

@@ -1,51 +1,68 @@
 # frozen_string_literal: true
 
 module Volcano
-  UploadSessionRequest = Data.define(:path, :content_type, :total_size, :part_size) do
+  UploadSessionRequest = Data.define(:path, :content_type, :total_size, :part_size)
+
+  # Freezes the arguments sent to create a resumable upload.
+  class UploadSessionRequest
+    # @dynamic path, content_type, total_size, part_size
     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
-      )
+      path = path.dup.freeze
+      content_type = content_type.dup.freeze
+      super
     end
   end
   private_constant :UploadSessionRequest
 
-  UploadPartRequest = Data.define(:path, :session_id, :part_number, :data) do
+  UploadPartRequest = Data.define(:path, :session_id, :part_number, :data)
+
+  # Freezes one resumable upload part before transport dispatch.
+  class UploadPartRequest
+    # @dynamic path, session_id, part_number, data
     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
-      )
+      path = path.dup.freeze
+      session_id = session_id.dup.freeze
+      data = data.dup.freeze
+      super
     end
   end
   private_constant :UploadPartRequest
 
-  UploadSessionReference = Data.define(:path, :session_id) do
+  UploadSessionReference = Data.define(:path, :session_id)
+
+  # Freezes the path and identifier used for upload session operations.
+  class UploadSessionReference
+    # @dynamic path, session_id
     def initialize(path:, session_id:)
-      super(path: path.dup.freeze, session_id: session_id.dup.freeze)
+      path = path.dup.freeze
+      session_id = session_id.dup.freeze
+      super
     end
   end
   private_constant :UploadSessionReference
 
-  UploadSession = Data.define(:session_id, :part_size, :total_parts, :expires_at) do
+  UploadSession = Data.define(:session_id, :part_size, :total_parts, :expires_at)
+
+  # Describes a newly created upload session.
+  class UploadSession
+    # @dynamic session_id, part_size, total_parts, expires_at, members, with, to_h, deconstruct, deconstruct_keys
+    # @dynamic self.[], self.members
     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
-      )
+      session_id = session_id.dup.freeze
+      expires_at = expires_at.dup.freeze
+      super
     end
   end
 
-  UploadPart = Data.define(:part_number, :etag, :size) do
+  UploadPart = Data.define(:part_number, :etag, :size)
+
+  # Describes an accepted upload part.
+  class UploadPart
+    # @dynamic part_number, etag, size, members, with, to_h, deconstruct, deconstruct_keys
+    # @dynamic self.[], self.members
     def initialize(part_number:, etag:, size:)
-      super(part_number: part_number, etag: etag.dup.freeze, size: size)
+      etag = etag.dup.freeze
+      super
     end
   end
 
@@ -55,7 +72,13 @@ module Volcano
   ].freeze
   private_constant :UPLOAD_SESSION_STATUS_ATTRIBUTES
 
-  UploadSessionStatus = Data.define(*UPLOAD_SESSION_STATUS_ATTRIBUTES) do
+  UploadSessionStatus = Data.define(*UPLOAD_SESSION_STATUS_ATTRIBUTES)
+
+  # Freezes upload progress returned by storage.
+  class UploadSessionStatus
+    # @dynamic session_id, status, path, content_type, total_size, part_size
+    # @dynamic total_parts, parts_uploaded, bytes_uploaded, parts, expires_at, created_at
+    # @dynamic members, with, to_h, deconstruct, deconstruct_keys, self.[], self.members
     def initialize(**attributes)
       unknown = attributes.keys - UPLOAD_SESSION_STATUS_ATTRIBUTES
       raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
@@ -66,7 +89,8 @@ module Volcano
       values = UPLOAD_SESSION_STATUS_ATTRIBUTES.to_h do |name|
         [name, immutable_value(attributes.fetch(name))]
       end
-      super(**values)
+      attributes = values
+      super
     end
 
     private

data/lib/volcano/storage_upload_sessions.rb

@@ -51,7 +51,7 @@ module Volcano
           request: request
         )
       end
-      storage_object(Transport.body(response, 200).fetch('object'))
+      storage_object(storage_payload(Transport.body(response, 200)).fetch('object'))
     end
 
     def get_upload_session(path, session_id:)
@@ -78,39 +78,5 @@ module Volcano
       Transport.body(response, 200)
       nil
     end
-
-    private
-
-    def upload_session(payload)
-      UploadSession.new(
-        session_id: payload.fetch('session_id'),
-        part_size: payload.fetch('part_size'),
-        total_parts: payload.fetch('total_parts'),
-        expires_at: parse_time(payload.fetch('expires_at'))
-      )
-    end
-
-    def upload_part_metadata(payload)
-      UploadPart.new(
-        part_number: payload.fetch('part_number'),
-        etag: payload.fetch('etag'),
-        size: payload.fetch('size')
-      )
-    end
-
-    def upload_session_status(payload)
-      attributes = upload_session_status_attributes(payload)
-      attributes[:parts] = attributes.fetch(:parts).map { |part| upload_part_metadata(part) }
-      attributes[:expires_at] = parse_time(attributes.fetch(:expires_at))
-      attributes[:created_at] = parse_time(attributes.fetch(:created_at))
-      UploadSessionStatus.new(**attributes)
-    end
-
-    def upload_session_status_attributes(payload)
-      UPLOAD_SESSION_STATUS_ATTRIBUTES.to_h do |name|
-        value = name == :parts ? payload.fetch(name.to_s, []) : payload.fetch(name.to_s)
-        [name, value]
-      end
-    end
   end
 end

data/lib/volcano/version.rb

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

data/lib/volcano.rb

@@ -26,6 +26,7 @@ require_relative 'volcano/auth_get_user'
 require_relative 'volcano/auth_update_user'
 require_relative 'volcano/auth_email_change'
 require_relative 'volcano/auth_sessions'
+require_relative 'volcano/auth_session_construction'
 require_relative 'volcano/auth'
 require_relative 'volcano/auth_sign_up'
 require_relative 'volcano/sign_up_result'
@@ -44,6 +45,10 @@ require_relative 'volcano/function_resolution'
 require_relative 'volcano/functions'
 require_relative 'volcano/durable'
 require_relative 'volcano/logs'
+require_relative 'volcano/storage_session_adapter'
+require_relative 'volcano/storage_transport_adapter'
+require_relative 'volcano/storage_response'
+require_relative 'volcano/storage_object_response'
 require_relative 'volcano/storage'
 require_relative 'volcano/storage_upload_sessions'
 require_relative 'volcano/storage_resumable_upload'
@@ -63,7 +68,7 @@ require_relative 'volcano/client'
 # Public namespace for the Volcano Ruby SDK.
 module Volcano
   private_constant :AuthRefresh, :AuthSignOut, :AuthProfile, :AuthProfileFields, :AuthUpdateUser, :AuthEmailChange,
-                   :AuthSessions,
+                   :AuthSessions, :AuthSessionConstruction,
                    :GeneratedTransport, :LockAutoRenewal, :LockLeaseClock, :LockRenewer,
                    :LockSession, :LockResponse, :Redaction, :SessionOperations
 

data/sig/auth_credentials.rbs

@@ -0,0 +1,15 @@
+module Volcano
+  class Auth
+    def current_session: () -> Session?
+    def current_session=: (Session session) -> void
+    def on_auth_state_change: () { (Symbol, Session?) -> void } -> AuthSubscription
+    def sign_in: (email: String, password: String) -> Session
+    def sign_up: (email: String, password: String, ?metadata: session_user_input, ?sign_in_when_allowed: bool) -> SignUpResult
+    def sign_in_anonymously: (?metadata: session_user_input) -> Session
+    def convert_anonymous: (email: String, password: String, ?metadata: session_user_input) -> User
+    def confirm_email: (token: String) -> nil
+    def resend_confirmation: (email: String) -> nil
+    def reset_password_for_email: (email: String) -> nil
+    def reset_password: (token: String, new_password: String) -> nil
+  end
+end

data/sig/storage.rbs

@@ -0,0 +1,29 @@
+module Volcano
+  interface _StorageReadable
+    def read: (?Integer length) -> String?
+    def is_a?: (Class) -> bool
+    def respond_to?: (Symbol) -> bool
+    def method: (Symbol) -> Method
+  end
+
+  class Storage
+    def from: (String bucket) -> StorageBucket
+  end
+
+  class StorageBucket
+    def upload: (String path, String | _StorageReadable value, ?content_type: String?) -> Hash[String, Object?]
+    def download: (String path, ?range: String?) -> String
+    def list: (?String prefix, ?limit: Integer?, ?cursor: String?) -> StoragePage
+    def remove: (String | Array[String] paths) -> Array[String]
+    def move: (String from_path, String to_path) -> StorageObject
+    def copy: (String from_path, String to_path) -> StorageObject
+    def update_visibility: (String path, public: bool) -> StorageObject
+
+    def create_upload_session: (String path, total_size: Integer, ?content_type: String, ?part_size: Integer?) -> UploadSession
+    def upload_part: (String path, session_id: String, part_number: Integer, data: String | _StorageReadable) -> UploadPart
+    def complete_upload_session: (String path, session_id: String) -> StorageObject
+    def get_upload_session: (String path, session_id: String) -> UploadSessionStatus
+    def abort_upload_session: (String path, session_id: String) -> nil
+    def upload_resumable: (String path, String | _StorageReadable value, ?content_type: String, ?part_size: Integer?, ?on_progress: (^(Integer, Integer) -> void)?) -> StorageObject
+  end
+end

data/sig/storage_records.rbs

@@ -1,4 +1,6 @@
 module Volcano
+  type storage_object_attribute = String | Integer | bool | Hash[String, json_value] | Time | nil
+
   class StorageObject < Data
     attr_reader id: String
     attr_reader bucket_id: String
@@ -19,7 +21,7 @@ module Volcano
                | (id: String, bucket_id: String, name: String, size: Integer, mime_type: String, is_public: bool, ?owner_id: String?, ?etag: String?, ?metadata: Hash[String, json_value]?, ?created_at: Time?, ?updated_at: Time?, ?public_url: String?) -> StorageObject
     def self.members: () -> [:id, :bucket_id, :name, :size, :mime_type, :is_public, :owner_id, :etag, :metadata, :created_at, :updated_at, :public_url]
 
-    def initialize: (id: String, bucket_id: String, name: String, size: Integer, mime_type: String, is_public: bool, ?owner_id: String?, ?etag: String?, ?metadata: Hash[String, json_value]?, ?created_at: Time?, ?updated_at: Time?, ?public_url: String?) -> void
+    def initialize: (**storage_object_attribute attributes) -> void
     def members: () -> [:id, :bucket_id, :name, :size, :mime_type, :is_public, :owner_id, :etag, :metadata, :created_at, :updated_at, :public_url]
     def with: (?id: String, ?bucket_id: String, ?name: String, ?size: Integer, ?mime_type: String, ?is_public: bool, ?owner_id: String?, ?etag: String?, ?metadata: Hash[String, json_value]?, ?created_at: Time?, ?updated_at: Time?, ?public_url: String?) -> StorageObject
     def to_h: () -> { id: String, bucket_id: String, name: String, size: Integer, mime_type: String, is_public: bool, owner_id: String?, etag: String?, metadata: Hash[String, json_value]?, created_at: Time?, updated_at: Time?, public_url: String? }

data/sig/upload_session_status.rbs

@@ -1,4 +1,6 @@
 module Volcano
+  type upload_status_attribute = String | Integer | Array[UploadPart] | Time
+
   class UploadSessionStatus < Data
     attr_reader session_id: String
     attr_reader status: String
@@ -19,7 +21,7 @@ module Volcano
                | (session_id: String, status: String, path: String, content_type: String, total_size: Integer, part_size: Integer, total_parts: Integer, parts_uploaded: Integer, bytes_uploaded: Integer, parts: Array[UploadPart], expires_at: Time, created_at: Time) -> UploadSessionStatus
     def self.members: () -> [:session_id, :status, :path, :content_type, :total_size, :part_size, :total_parts, :parts_uploaded, :bytes_uploaded, :parts, :expires_at, :created_at]
 
-    def initialize: (session_id: String, status: String, path: String, content_type: String, total_size: Integer, part_size: Integer, total_parts: Integer, parts_uploaded: Integer, bytes_uploaded: Integer, parts: Array[UploadPart], expires_at: Time, created_at: Time) -> void
+    def initialize: (**upload_status_attribute attributes) -> void
     def members: () -> [:session_id, :status, :path, :content_type, :total_size, :part_size, :total_parts, :parts_uploaded, :bytes_uploaded, :parts, :expires_at, :created_at]
     def with: (?session_id: String, ?status: String, ?path: String, ?content_type: String, ?total_size: Integer, ?part_size: Integer, ?total_parts: Integer, ?parts_uploaded: Integer, ?bytes_uploaded: Integer, ?parts: Array[UploadPart], ?expires_at: Time, ?created_at: Time) -> UploadSessionStatus
     def to_h: () -> { session_id: String, status: String, path: String, content_type: String, total_size: Integer, part_size: Integer, total_parts: Integer, parts_uploaded: Integer, bytes_uploaded: Integer, parts: Array[UploadPart], expires_at: Time, created_at: Time }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: volcano-sdk
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.31.0
 platform: ruby
 authors:
 - Kong
@@ -147,6 +147,7 @@ files:
 - lib/volcano/auth_reset_password.rb
 - lib/volcano/auth_reset_password_for_email.rb
 - lib/volcano/auth_session_binding.rb
+- lib/volcano/auth_session_construction.rb
 - lib/volcano/auth_sessions.rb
 - lib/volcano/auth_sign_out.rb
 - lib/volcano/auth_sign_up.rb
@@ -602,13 +603,18 @@ files:
 - lib/volcano/storage.rb
 - lib/volcano/storage_models.rb
 - lib/volcano/storage_mutations.rb
+- lib/volcano/storage_object_response.rb
 - lib/volcano/storage_public_url.rb
+- lib/volcano/storage_response.rb
 - lib/volcano/storage_resumable_upload.rb
+- lib/volcano/storage_session_adapter.rb
+- lib/volcano/storage_transport_adapter.rb
 - lib/volcano/storage_upload_models.rb
 - lib/volcano/storage_upload_sessions.rb
 - lib/volcano/transport.rb
 - lib/volcano/user.rb
 - lib/volcano/version.rb
+- sig/auth_credentials.rbs
 - sig/auth_oauth.rbs
 - sig/auth_profile.rbs
 - sig/auth_session_records.rbs
@@ -627,6 +633,7 @@ files:
 - sig/realtime_postgres_change.rbs
 - sig/session.rbs
 - sig/sign_up_result.rbs
+- sig/storage.rbs
 - sig/storage_public_url.rbs
 - sig/storage_records.rbs
 - sig/upload_records.rbs