volcano-sdk 0.29.0 → 0.31.0

data/lib/volcano/auth_sessions.rb

@@ -1,49 +1,10 @@
 # frozen_string_literal: true
 
-require 'json'
+require_relative 'session_page_mapping'
 
 module Volcano
-  # Maps the internal wire response to immutable public session values.
-  module SessionPageMapping
-    SESSION_FIELDS = %i[
-      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
-    ].freeze
-    REQUIRED_SESSION_FIELDS = SESSION_FIELDS.first(6).freeze
-
-    private
-
-    def session_page(body)
-      raise TypeError, 'Expected a complete session page' unless body.is_a?(Hash)
-
-      sessions = body.fetch('sessions')
-      raise TypeError, 'Expected a complete session page' unless sessions.is_a?(Array)
-
-      SessionPage.new(
-        sessions: sessions.map { |attributes| auth_session(attributes) },
-        total: body.fetch('total'), page: body.fetch('page'), limit: body.fetch('limit'),
-        total_pages: body.fetch('total_pages')
-      )
-    rescue KeyError
-      raise TypeError, 'Expected a complete session page'
-    end
-
-    def auth_session(attributes)
-      raise TypeError, 'Expected a complete authentication session' unless attributes.is_a?(Hash)
-
-      required = REQUIRED_SESSION_FIELDS.to_h { |name| [name, attributes.fetch(name.to_s)] }
-      optional = (SESSION_FIELDS - REQUIRED_SESSION_FIELDS).to_h do |name|
-        [name, attributes[name.to_s]]
-      end
-      AuthSession.new(**required, **optional)
-    rescue KeyError
-      raise TypeError, 'Expected a complete authentication session'
-    end
-  end
-  private_constant :SessionPageMapping
-
   # Multi-device session behavior for the authentication facade.
-  class Auth
+  module AuthSessions
     include SessionPageMapping
 
     def list_sessions(page: 1, limit: 20)
@@ -57,10 +18,11 @@ module Volcano
 
     def delete_session(session_id)
       binding = @client.capture_session_binding
-      raise Error::AuthenticationError, 'No active session' unless binding.last
+      session = binding.last
+      raise Error::AuthenticationError, 'No active session' unless session
 
       request_id = session_id.dup.freeze
-      deletes_current = same_session_id?(binding.last.access_token, request_id)
+      deletes_current = same_session_id?(session.access_token, request_id)
       error = delete_bound_session_error(binding, request_id)
       current_unchanged = session_unchanged_after_deletion?(deletes_current, error, binding)
       raise Error::SessionChangedError, cause: error unless current_unchanged
@@ -119,12 +81,14 @@ module Volcano
 
     def deletion_binding_current?(binding, error)
       active = @client.capture_session_binding
-      (active.last && active[1] == binding[1]) || (error && rejected_refresh?(binding, active))
+      return true if active.last && active[1] == binding[1]
+
+      !error.nil? && rejected_refresh?(binding, active)
     end
 
     def same_session_id?(access_token, session_id)
       current_session_id = access_token_session_id(access_token)
-      session_id.is_a?(String) && current_session_id&.casecmp?(session_id)
+      session_id.is_a?(String) && current_session_id&.casecmp?(session_id) == true
     end
 
     def access_token_session_id(access_token)

data/lib/volcano/auth_sign_out.rb

@@ -2,24 +2,28 @@
 
 module Volcano
   # Revokes the captured server session and clears its local lineage.
-  class Auth
+  module AuthSignOut
+    include AuthNotificationDispatch
+
     def sign_out
+      # @type var notifications: Array[Method]
+      notifications = []
       binding = @client.capture_session_binding
-      return binding[1].wait_for_sign_out unless binding.last
+      session = binding.last
+      return binding[1].wait_for_sign_out unless session
 
-      notifications = []
       binding[1].sign_out do |preceding, pending|
-        sign_out_captured(binding, preceding, pending, notifications)
+        sign_out_captured(binding, session, preceding, pending, notifications)
       end
     ensure
-      notifications&.each(&:call)
+      run_auth_notifications(notifications)
     end
 
     private
 
-    def sign_out_captured(binding, preceding, pending, notifications)
+    def sign_out_captured(binding, session, preceding, pending, notifications)
       generation, owner, = binding
-      current, refresh_error = revocation_credentials(binding, preceding)
+      current, refresh_error = revocation_credentials(owner, session, preceding)
       error = revocation_error(current, owner, pending ? refresh_error : nil, joined: pending)
       cleared = @client.clear_session_if_current?(generation, lineage: owner, notifications: notifications)
       raise Error::SessionChangedError, cause: error unless cleared
@@ -27,10 +31,13 @@ module Volcano
       raise error if error
     end
 
-    def revocation_credentials(binding, preceding)
-      [binding[1].result(preceding) || binding.last, nil]
+    def revocation_credentials(owner, session, preceding)
+      resolved = owner.result(preceding) || session
+      raise TypeError, 'Expected a session from refresh' unless resolved.is_a?(Session)
+
+      [resolved, nil]
     rescue Error::VolcanoError => e
-      [binding.last, e]
+      [session, e]
     end
 
     def logout_response(refresh_token)
@@ -67,16 +74,17 @@ module Volcano
 
     def revoke_access_session(session, session_id, refresh_error, joined:)
       error = delete_session_error(session.access_token, session_id)
-      return error unless refreshable_revocation?(error, session)
+      refresh_token = refreshable_revocation_token(error, session)
+      return error unless refresh_token
       return refresh_error || error if joined
 
-      refreshed = parse_refresh_session(Transport.body(refresh_response(session.refresh_token), 200))
+      refreshed = parse_refresh_session(Transport.body(refresh_response(refresh_token), 200))
       SessionCredentials.validate_refresh(session, refreshed)
       delete_session_error(refreshed.access_token, session_id)
     end
 
-    def refreshable_revocation?(error, session)
-      error&.status == 401 && session.refresh_token
+    def refreshable_revocation_token(error, session)
+      session.refresh_token if error&.status == 401
     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/auth_state.rb

@@ -81,9 +81,10 @@ module Volcano
 
     def update_user_if_current?(user, generation)
       @mutex.synchronize do
-        return false unless generation == @generation && @session
+        current = @session
+        return false unless generation == @generation && current
 
-        @session = SessionCredentials.with_user(@session, user)
+        @session = SessionCredentials.with_user(current, user)
         true
       end
     end

data/lib/volcano/auth_state_notifications.rb

@@ -3,8 +3,8 @@
 module Volcano
   # Queues auth events under the state mutex and invokes subscribers outside it.
   module AuthStateNotifications
-    CALLBACK_FAILURES = [Exception].freeze
-    private_constant :CALLBACK_FAILURES
+    CALLBACK_FAILURE = Exception
+    private_constant :CALLBACK_FAILURE
 
     private
 
@@ -26,12 +26,14 @@ module Volcano
     end
 
     def drain_notifications
+      # @type var failure: Exception?
       failure = nil
       loop do
         notification = next_notification
         break unless notification
 
-        current_failure = notify(*notification)
+        callback_ids, event, session = notification
+        current_failure = notify(callback_ids, event, session)
         failure ||= current_failure
       end
       raise failure if failure
@@ -48,12 +50,13 @@ module Volcano
     end
 
     def notify(callback_ids, event, session)
+      # @type var failure: Exception?
       failure = nil
       callback_ids.each do |callback_id|
         @mutex.synchronize { @callbacks[callback_id] }&.call(event, session)
       rescue StandardError => e
         Warning.warn("Volcano auth-state callback failed (#{e.class})\n")
-      rescue *CALLBACK_FAILURES => e
+      rescue CALLBACK_FAILURE => e
         unsubscribe(callback_id)
         failure ||= e
       end

data/lib/volcano/auth_update_user.rb

@@ -2,7 +2,7 @@
 
 module Volcano
   # Current-user update behavior for the authentication facade.
-  class Auth
+  module AuthUpdateUser
     def update_user(password: nil, metadata: nil)
       profile_request do
         request_password = password&.dup&.freeze

data/lib/volcano/session.rb

@@ -9,79 +9,6 @@ module Volcano
   end
   private_constant :SESSION_USER_CODER
 
-  # Owns credential snapshots and preserves validated identity during refresh.
-  module SessionCredentials
-    def self.build(access_token, refresh_token)
-      raise ArgumentError, 'refresh_token requires access_token' if access_token.nil? && !refresh_token.nil?
-      return if access_token.nil?
-
-      Session.new(access_token: credential(access_token, :access_token),
-                  refresh_token: credential(refresh_token, :refresh_token))
-    end
-
-    def self.credential(value, name)
-      return if value.nil?
-
-      raise ArgumentError, "#{name} must be a non-empty string" unless value.is_a?(String) && !value.strip.empty?
-
-      value.dup.freeze
-    end
-    private_class_method :credential
-
-    def self.validate_refresh_source(current, verified: false)
-      return if verified || session_id(current.access_token)
-
-      raise Error::AuthenticationError, 'Cannot refresh supplied credentials without a session identifier'
-    end
-
-    def self.validate_refresh(current, refreshed)
-      return unless current
-
-      validate_refresh_session_id(current, refreshed)
-      return unless current.user_id && current.user_id != refreshed&.user_id
-
-      raise Error::AuthenticationError, 'Refreshed session belongs to a different user'
-    end
-
-    def self.validate_refresh_session_id(current, refreshed)
-      expected = session_id(current.access_token)
-      return unless expected && expected != session_id(refreshed&.access_token)
-
-      raise Error::AuthenticationError, 'Refreshed credentials belong to a different server session'
-    end
-    private_class_method :validate_refresh_session_id
-
-    # Untrusted continuity constraint, never authenticated user identity.
-    def self.session_id(access_token)
-      payload = token_payload(access_token)
-      return unless payload.is_a?(Hash)
-
-      value = payload['session_id']
-      value.downcase if value.is_a?(String) && value.match?(/\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
-    end
-
-    def self.token_payload(access_token)
-      return unless access_token.is_a?(String)
-
-      parts = access_token.split('.')
-      return unless parts.length == 3
-
-      encoded = parts.fetch(1).tr('-_', '+/')
-      JSON.parse((encoded + ('=' * (-encoded.length % 4))).unpack1('m0'))
-    rescue ArgumentError, JSON::ParserError
-      nil
-    end
-    private_class_method :token_payload
-
-    def self.with_user(session, user)
-      user_id = (session.user_id || user.fetch('id')).dup.freeze
-      raise Error::AuthenticationError, 'Profile belongs to a different user' unless user['id'] == user_id
-
-      Session.new(**session.to_h, user_id: user_id, user: user)
-    end
-  end
-  private_constant :SessionCredentials
-
   # Local credentials; refresh credentials and user identity may be unknown.
   Session = Data.define(:access_token, :refresh_token, :user_id, :user) do
     def initialize(access_token:, refresh_token: nil, user_id: nil, user: nil)

data/lib/volcano/session_credentials.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require_relative 'session'
+
+module Volcano
+  # Owns credential snapshots and preserves validated identity during refresh.
+  module SessionCredentials
+    def self.build(access_token, refresh_token)
+      raise ArgumentError, 'refresh_token requires access_token' if access_token.nil? && !refresh_token.nil?
+      return if access_token.nil?
+
+      Session.new(access_token: credential(access_token, :access_token),
+                  refresh_token: refresh_token.nil? ? nil : credential(refresh_token, :refresh_token))
+    end
+
+    def self.credential(value, name)
+      raise ArgumentError, "#{name} must be a non-empty string" unless value.is_a?(String) && !value.strip.empty?
+
+      value.dup.freeze
+    end
+    private_class_method :credential
+
+    def self.validate_refresh_source(current, verified: false)
+      return if verified || session_id(current.access_token)
+
+      raise Error::AuthenticationError, 'Cannot refresh supplied credentials without a session identifier'
+    end
+
+    def self.validate_refresh(current, refreshed)
+      return unless current
+
+      validate_refresh_session_id(current, refreshed)
+      return unless current.user_id && current.user_id != refreshed&.user_id
+
+      raise Error::AuthenticationError, 'Refreshed session belongs to a different user'
+    end
+
+    def self.validate_refresh_session_id(current, refreshed)
+      expected = session_id(current.access_token)
+      return unless expected && expected != session_id(refreshed&.access_token)
+
+      raise Error::AuthenticationError, 'Refreshed credentials belong to a different server session'
+    end
+    private_class_method :validate_refresh_session_id
+
+    # Untrusted continuity constraint, never authenticated user identity.
+    def self.session_id(access_token)
+      payload = token_payload(access_token)
+      return unless payload.is_a?(Hash)
+
+      value = payload['session_id']
+      value.downcase if value.is_a?(String) && value.match?(/\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
+    end
+
+    def self.token_payload(access_token)
+      return unless access_token.is_a?(String)
+
+      parts = access_token.split('.')
+      return unless parts.length == 3
+
+      encoded = parts.fetch(1).tr('-_', '+/')
+      JSON.parse(Base64.strict_decode64(encoded + ('=' * (-encoded.length % 4))))
+    rescue ArgumentError, JSON::ParserError
+      nil
+    end
+    private_class_method :token_payload
+
+    def self.with_user(session, user)
+      user_id = session.user_id || user.fetch('id')
+      raise Error::AuthenticationError, 'Profile has no valid user identifier' unless user_id.is_a?(String)
+
+      user_id = user_id.dup.freeze
+      raise Error::AuthenticationError, 'Profile belongs to a different user' unless user['id'] == user_id
+
+      Session.new(access_token: session.access_token, refresh_token: session.refresh_token,
+                  user_id: user_id, user: user)
+    end
+  end
+  private_constant :SessionCredentials
+end

data/lib/volcano/session_operations.rb

@@ -42,7 +42,9 @@ module Volcano
     def refresh(&)
       operation, owner = @mutex.synchronize do
         raise Error::SessionChangedError if @sign_out || @locally_cleared
-        next [@refresh, false] if @refresh && !@refresh.done
+
+        current = @refresh
+        next [current, false] if current && !current.done
 
         @refresh = Outcome.new(false)
         [@refresh, true]
@@ -51,11 +53,7 @@ module Volcano
     end
 
     def sign_out
-      operation, owner, preceding, pending = @mutex.synchronize do
-        first = @sign_out.nil?
-        @sign_out ||= Outcome.new(false)
-        [@sign_out, first, @refresh, @refresh && !@refresh.done]
-      end
+      operation, owner, preceding, pending = @mutex.synchronize { claim_sign_out }
       execute(operation, owner) do
         yield(preceding, pending)
       ensure
@@ -79,10 +77,19 @@ module Volcano
 
     private
 
+    def claim_sign_out
+      first = @sign_out.nil? == true
+      operation = @sign_out ||= Outcome.new(false)
+      current = @refresh
+      [operation, first, current, current && !current.done]
+    end
+
     def execute(operation, owner)
       return result(operation) unless owner
 
       completed = false
+      # @type var value: Object?
+      value = nil
       begin
         value = yield
         completed = true

data/lib/volcano/session_page_mapping.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Maps the internal wire response to immutable public session values.
+  module SessionPageMapping
+    private
+
+    def session_page(body)
+      raise TypeError, 'Expected a complete session page' unless body.is_a?(Hash)
+
+      sessions = body.fetch('sessions')
+      raise TypeError, 'Expected a complete session page' unless sessions.is_a?(Array)
+
+      SessionPage.new(
+        sessions: sessions.map { |attributes| auth_session(attributes) },
+        total: required_integer(body, 'total'), page: required_integer(body, 'page'),
+        limit: required_integer(body, 'limit'), total_pages: required_integer(body, 'total_pages')
+      )
+    rescue KeyError
+      raise TypeError, 'Expected a complete session page'
+    end
+
+    def auth_session(attributes)
+      raise TypeError, 'Expected a complete authentication session' unless attributes.is_a?(Hash)
+
+      build_auth_session(attributes)
+    rescue KeyError
+      raise TypeError, 'Expected a complete authentication session'
+    end
+
+    def build_auth_session(attributes)
+      AuthSession.new(
+        id: required_string(attributes, 'id'), user_id: required_string(attributes, 'user_id'),
+        provider: required_string(attributes, 'provider'), expires_at: required_time(attributes, 'expires_at'),
+        is_active: required_boolean(attributes, 'is_active'), is_current: required_boolean(attributes, 'is_current'),
+        user_agent: optional_string(attributes, 'user_agent'), ip_address: optional_string(attributes, 'ip_address'),
+        last_ip_address: optional_string(attributes, 'last_ip_address'),
+        last_activity_at: optional_time(attributes, 'last_activity_at'),
+        session_started_at: optional_time(attributes, 'session_started_at'),
+        created_at: optional_time(attributes, 'created_at'), updated_at: optional_time(attributes, 'updated_at')
+      )
+    end
+
+    def required_integer(body, name)
+      value = body.fetch(name)
+      raise TypeError, 'Expected a complete session page' unless value.is_a?(Integer)
+
+      value
+    end
+
+    def required_string(body, name)
+      value = body.fetch(name)
+      raise TypeError, 'Expected a complete authentication session' unless value.is_a?(String)
+
+      value
+    end
+
+    def required_time(body, name)
+      value = body.fetch(name)
+      raise TypeError, 'Expected a complete authentication session' unless value.is_a?(Time)
+
+      value
+    end
+
+    def required_boolean(body, name)
+      value = body.fetch(name)
+      unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        raise TypeError, 'Expected a complete authentication session'
+      end
+
+      value
+    end
+
+    def optional_string(body, name)
+      value = body[name]
+      raise TypeError, 'Expected a complete authentication session' unless value.nil? || value.is_a?(String)
+
+      value
+    end
+
+    def optional_time(body, name)
+      value = body[name]
+      raise TypeError, 'Expected a complete authentication session' unless value.nil? || value.is_a?(Time)
+
+      value
+    end
+  end
+  private_constant :SessionPageMapping
+end

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