volcano-sdk 0.10.1 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59e652b75cb01f8a353cca787d8e97ecce893091202389d6eb05d16898553fe4
-  data.tar.gz: 1aaab53a45bb753db900c0dbb5fe0d95d27c17f36a0bc4487e396a37f10e0a7c
+  metadata.gz: 0a5a8e6d0c0958a19588efaa73c12721eee47e710bc397ce18a4a2a383d0ba9f
+  data.tar.gz: ec32d121d29074aece0ed41d30599f575e90535c66ad93c82b073d1a3d1b8eaf
 SHA512:
-  metadata.gz: f1c408840aeabf36d2880bb13f8fa9ef602ecb1fa5de7e0b3db936ca48f02ce8b8dc667c6dcf52ec4637f4418f6c9b45bbf157081cbc167406752980d1c56bc2
-  data.tar.gz: 641095882ee98d37672f0c7c9a59a2051d98f4a392682df91753b999fffd2aae91a65a62e9c299569f5e1d3c96f73b4095247e168954ae7c75f6e36f5a71fed2
+  metadata.gz: ed4e6a000be0491dc2edfcb72e6bc03a87a49bdd3eb835c0d29455010852e5a645b6323e65e7740cd3a9c98898726bb0bc7ba7bb68cd5a37992f6f2049661105
+  data.tar.gz: b1ef9f3c793ad18bd26a7d347b8b48b85dc792d10de410d88340b945bb9f19c67a25bc3fa612f7889ca88b5962bd89fe20ef2ef4e4d1e2dee273ca5380876cd2

data/README.md

@@ -907,3 +907,7 @@ Run `npm ci && bin/check-openapi` to verify generated provenance. Use
 `bundle exec rubocop -A` to apply safe formatting and lint fixes. Before
 changing the facade, run `bundle exec rubocop --parallel`, `bundle exec rspec`,
 and the shared Cucumber contract suite.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for cross-language coordination and the full verification workflow.

data/lib/volcano/auth_get_user.rb

@@ -72,8 +72,12 @@ module Volcano
     def valid_user?(payload)
       return false unless payload.is_a?(Hash)
 
-      required_user_fields?(payload) && valid_email_confirmation?(payload) &&
-        valid_metadata?(payload) && valid_optional_strings?(payload) && valid_timestamps?(payload)
+      required_user_fields?(payload) && valid_optional_user_fields?(payload)
+    end
+
+    def valid_optional_user_fields?(payload)
+      valid_email_confirmation?(payload) && valid_metadata?(payload) &&
+        valid_optional_strings?(payload) && valid_timestamps?(payload)
     end
 
     def required_user_fields?(payload)

data/lib/volcano/auth_oauth.rb

@@ -77,13 +77,16 @@ module Volcano
       provider = attributes.fetch('provider')
       linked_at = attributes.fetch('linked_at')
       updated_at = attributes.fetch('updated_at')
-      valid = provider.is_a?(String) && !provider.strip.empty? &&
-              linked_at.is_a?(Time) && updated_at.is_a?(Time)
+      valid = valid_linked_oauth_provider?(provider, linked_at, updated_at)
       raise TypeError, 'Expected complete linked OAuth providers' unless valid
 
       LinkedOAuthProvider.new(provider:, linked_at:, updated_at:)
     rescue KeyError
       raise TypeError, 'Expected complete linked OAuth providers'
     end
+
+    def valid_linked_oauth_provider?(provider, linked_at, updated_at)
+      complete_string?(provider) && linked_at.is_a?(Time) && updated_at.is_a?(Time)
+    end
   end
 end

data/lib/volcano/auth_oauth_api.rb

@@ -32,15 +32,22 @@ module Volcano
 
     def freeze_oauth_api_data(value)
       case value
-      when Hash
-        value.to_h { |key, item| [freeze_oauth_api_data(key), freeze_oauth_api_data(item)] }.freeze
+      when Hash then freeze_oauth_api_data_hash(value)
       when Array
         value.map { |item| freeze_oauth_api_data(item) }.freeze
       when String
         value.dup.freeze
       else
-        value.frozen? ? value : value.dup.freeze
+        freeze_oauth_api_data_scalar(value)
       end
     end
+
+    def freeze_oauth_api_data_scalar(value)
+      value.frozen? ? value : value.dup.freeze
+    end
+
+    def freeze_oauth_api_data_hash(value)
+      value.to_h { |key, item| [freeze_oauth_api_data(key), freeze_oauth_api_data(item)] }.freeze
+    end
   end
 end

data/lib/volcano/auth_refresh.rb

@@ -75,7 +75,7 @@ module Volcano
 
     def rejected_refresh?(binding, active)
       generation, lineage, = binding
-      @rejected_refresh == [generation, lineage] &&
+      @client.refresh_rejected?(generation, lineage) &&
         active.first == generation + 1 && active.last.nil?
     end
 
@@ -115,9 +115,7 @@ module Volcano
       Transport.body(refresh_response(binding.last.refresh_token), 200)
     rescue Error::AuthenticationError
       generation, owner, = binding
-      if !owner.closing? && @client.clear_session_if_current?(generation, notifications: notifications)
-        @rejected_refresh = [generation, owner]
-      end
+      @client.reject_refresh_if_current?(generation, notifications: notifications) unless owner.closing?
       raise
     end
   end

data/lib/volcano/auth_sessions.rb

@@ -114,6 +114,10 @@ module Volcano
       uncertain = error.nil? || error.is_a?(Error::TransportError)
       return @client.clear_session_if_current?(binding.first, lineage: binding[1]) if deletes_current && uncertain
 
+      deletion_binding_current?(binding, error)
+    end
+
+    def deletion_binding_current?(binding, error)
       active = @client.capture_session_binding
       (active.last && active[1] == binding[1]) || (error && rejected_refresh?(binding, active))
     end

data/lib/volcano/auth_sign_out.rb

@@ -46,23 +46,37 @@ module Volcano
       session_id = access_token_session_id(session.access_token)
       verified = owner.verified_pair?(session)
       return revoke_access_session(session, session_id, refresh_error, joined: joined) if session_id && !verified
-      return refresh_error if refresh_error && !verified
-      return unless session.refresh_token
 
-      Transport.body(logout_response(session.refresh_token), 204)
-      nil
+      refresh_revocation_error(session, refresh_error, verified: verified)
     rescue Error::VolcanoError => e
       e
     end
 
+    def refresh_revocation_error(session, refresh_error, verified:)
+      return refresh_error if refresh_error && !verified
+
+      revoke_refresh_session(session.refresh_token)
+    end
+
+    def revoke_refresh_session(refresh_token)
+      return unless refresh_token
+
+      Transport.body(logout_response(refresh_token), 204)
+      nil
+    end
+
     def revoke_access_session(session, session_id, refresh_error, joined:)
       error = delete_session_error(session.access_token, session_id)
-      return error unless error&.status == 401 && session.refresh_token
+      return error unless refreshable_revocation?(error, session)
       return refresh_error || error if joined
 
       refreshed = parse_refresh_session(Transport.body(refresh_response(session.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
+    end
   end
 end

data/lib/volcano/auth_state.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'auth_state_notifications'
+
 module Volcano
   # Idempotent handle for an authentication-state subscription.
   class AuthSubscription
@@ -21,14 +23,14 @@ module Volcano
 
   # Owns synchronized local session state and its subscribers.
   class AuthState
-    CALLBACK_FAILURES = [Exception].freeze
-    private_constant :CALLBACK_FAILURES
+    include AuthStateNotifications
 
     def initialize(session: nil)
       @mutex = Mutex.new
       @generation = 0
       @lineage = SessionOperations.new
       @session = session
+      @rejected_refresh = nil
       @callbacks = {}
       @next_callback_id = 0
       @notifications = []
@@ -50,17 +52,33 @@ module Volcano
 
     def store_if_current?(session, generation, event: :signed_in, notifications: nil, lineage: nil)
       dispatch = @mutex.synchronize do
-        return false unless lineage.nil? ? generation == @generation : lineage == @lineage
+        return false unless current_binding?(generation, lineage)
         return true if session.nil? && @session.nil?
 
         enqueue_notification(replace(session, event, verified_pair: session), event, session)
       end
       return true unless dispatch
 
-      notifications ? notifications.push(method(:drain_notifications)) : drain_notifications
+      dispatch_notifications(notifications)
+      true
+    end
+
+    def reject_refresh_if_current?(generation, notifications: nil)
+      dispatch = @mutex.synchronize do
+        return false unless generation == @generation && @session
+
+        # Publish rejection and credential removal as one synchronized transition.
+        @rejected_refresh = [generation, @lineage]
+        enqueue_notification(replace(nil, :signed_out), :signed_out, nil)
+      end
+      dispatch_notifications(notifications) if dispatch
       true
     end
 
+    def refresh_rejected?(generation, lineage)
+      @mutex.synchronize { @rejected_refresh == [generation, lineage] }
+    end
+
     def update_user_if_current?(user, generation)
       @mutex.synchronize do
         return false unless generation == @generation && @session
@@ -81,6 +99,10 @@ module Volcano
 
     private
 
+    def current_binding?(generation, lineage) = lineage.nil? ? generation == @generation : lineage == @lineage
+
+    def dispatch_notifications(queue) = queue ? queue.push(method(:drain_notifications)) : drain_notifications
+
     def replace(session, event, verified_pair: nil)
       SessionCredentials.validate_refresh(@session, session) if event == :token_refreshed
       @session = session
@@ -89,59 +111,5 @@ module Volcano
       @lineage = SessionOperations.new(verified_pair) if session && event != :token_refreshed
       @callbacks.keys
     end
-
-    def register(callback)
-      @next_callback_id += 1
-      @callbacks[@next_callback_id] = callback
-      [@next_callback_id, @session]
-    end
-
-    def unsubscribe(callback_id)
-      @mutex.synchronize { @callbacks.delete(callback_id) }
-    end
-
-    def enqueue_notification(callbacks, event, session)
-      return false if event.nil? || callbacks.empty?
-
-      @notifications << [callbacks, event, session]
-      return false if @dispatching_notifications
-
-      @dispatching_notifications = true
-    end
-
-    def drain_notifications
-      failure = nil
-      loop do
-        notification = next_notification
-        break unless notification
-
-        current_failure = notify(*notification)
-        failure ||= current_failure
-      end
-      raise failure if failure
-    end
-
-    def next_notification
-      @mutex.synchronize do
-        if @notifications.empty?
-          @dispatching_notifications = false
-          return
-        end
-        @notifications.shift
-      end
-    end
-
-    def notify(callback_ids, event, session)
-      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
-        unsubscribe(callback_id)
-        failure ||= e
-      end
-      failure
-    end
   end
 end

data/lib/volcano/auth_state_notifications.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Queues auth events under the state mutex and invokes subscribers outside it.
+  module AuthStateNotifications
+    CALLBACK_FAILURES = [Exception].freeze
+    private_constant :CALLBACK_FAILURES
+
+    private
+
+    def register(callback)
+      @next_callback_id += 1
+      @callbacks[@next_callback_id] = callback
+      [@next_callback_id, @session]
+    end
+
+    def unsubscribe(callback_id) = @mutex.synchronize { @callbacks.delete(callback_id) }
+
+    def enqueue_notification(callbacks, event, session)
+      return false if event.nil? || callbacks.empty?
+
+      @notifications << [callbacks, event, session]
+      return false if @dispatching_notifications
+
+      @dispatching_notifications = true
+    end
+
+    def drain_notifications
+      failure = nil
+      loop do
+        notification = next_notification
+        break unless notification
+
+        current_failure = notify(*notification)
+        failure ||= current_failure
+      end
+      raise failure if failure
+    end
+
+    def next_notification
+      @mutex.synchronize do
+        if @notifications.empty?
+          @dispatching_notifications = false
+          return
+        end
+        @notifications.shift
+      end
+    end
+
+    def notify(callback_ids, event, session)
+      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
+        unsubscribe(callback_id)
+        failure ||= e
+      end
+      failure
+    end
+  end
+  private_constant :AuthStateNotifications
+end

data/lib/volcano/client.rb

@@ -86,6 +86,10 @@ module Volcano
       @auth_state.store_if_current?(nil, generation, event: event, notifications: notifications, lineage: lineage)
     end
 
+    def reject_refresh_if_current?(...) = @auth_state.reject_refresh_if_current?(...)
+
+    def refresh_rejected?(...) = @auth_state.refresh_rejected?(...)
+
     def subscribe_auth_state_change(...)
       @auth_state.subscribe(...)
     end

data/lib/volcano/database.rb

@@ -9,10 +9,14 @@ module Volcano
       case value
       when String then value.dup.freeze
       when Array then value.map { |item| capture(item) }.freeze
-      when Hash then value.to_h { |key, item| [capture(key), capture(item)] }.freeze
+      when Hash then capture_hash(value)
       else value
       end
     end
+
+    def capture_hash(value)
+      value.to_h { |key, item| [capture(key), capture(item)] }.freeze
+    end
   end
   private_constant :ImmutableQueryValue
 
@@ -146,11 +150,17 @@ module Volcano
 
     def query_body
       { 'table' => @table }.tap do |body|
+        add_query_selection(body)
+        body['limit'] = @limit unless @limit.nil?
+        body['offset'] = @offset unless @offset.nil?
+      end
+    end
+
+    def add_query_selection(body)
+      body.tap do
         body['select'] = @columns unless @columns.empty? || @columns == ['*']
         body['filters'] = @filters unless @filters.empty?
         body['order'] = @order unless @order.empty?
-        body['limit'] = @limit unless @limit.nil?
-        body['offset'] = @offset unless @offset.nil?
       end
     end
   end

data/lib/volcano/durable.rb

@@ -124,6 +124,10 @@ module Volcano
     def validate_paging(page, limit)
       raise ArgumentError, 'page must be a positive Integer' unless page.nil? || positive_integer?(page)
 
+      validate_page_limit(limit)
+    end
+
+    def validate_page_limit(limit)
       return if limit.nil? || (positive_integer?(limit) && limit <= MAX_PAGE_SIZE)
 
       raise ArgumentError, "limit must be an Integer between 1 and #{MAX_PAGE_SIZE}"

data/lib/volcano/durable_models.rb

@@ -51,12 +51,16 @@ module Volcano
     # `result` is the function's own JSON, so it is frozen all the way down.
     def immutable_value(value)
       case value
-      when Hash then value.to_h { |key, item| [immutable_value(key), immutable_value(item)] }.freeze
+      when Hash then immutable_value_hash(value)
       when Array then value.map { |item| immutable_value(item) }.freeze
       when Time, String then value.dup.freeze
       else value
       end
     end
+
+    def immutable_value_hash(value)
+      value.to_h { |key, item| [immutable_value(key), immutable_value(item)] }.freeze
+    end
   end
 
   # One page of a durable function's executions, most recent first.

data/lib/volcano/function_resolution.rb

@@ -51,11 +51,10 @@ module Volcano
       # when the API itself is plaintext, so a resolve response cannot
       # downgrade a credential that is otherwise protected in transit.
       def valid_invoke_url(value, api_url)
-        return nil unless value.is_a?(String) && !value.empty?
+        return nil unless nonempty_url?(value)
 
         uri = URI.parse(value)
-        # URI accepts a port outside the range a connection can use.
-        return nil if uri.host.to_s.empty? || !uri.port.to_i.between?(1, 65_535)
+        return nil unless usable_address?(uri)
 
         usable_scheme?(uri.scheme, api_url) ? value : nil
       rescue URI::InvalidURIError
@@ -107,6 +106,15 @@ module Volcano
 
       private
 
+      def nonempty_url?(value)
+        value.is_a?(String) && !value.empty?
+      end
+
+      def usable_address?(uri)
+        # URI accepts a port outside the range a connection can use.
+        !uri.host.to_s.empty? && uri.port.to_i.between?(1, 65_535)
+      end
+
       def usable_scheme?(scheme, api_url)
         case scheme&.downcase
         when 'https' then true
@@ -120,10 +128,14 @@ module Volcano
           @entries[key] = Entry.new(outcome: outcome, expires_at: now + ttl_seconds)
           next if @entries.size <= MAX_ENTRIES
 
-          @entries.delete_if { |_, entry| entry.expires_at <= now }
-          @entries.delete(@entries.min_by { |_, entry| entry.expires_at }&.first) while @entries.size > MAX_ENTRIES
+          evict_expired_entries
         end
       end
+
+      def evict_expired_entries
+        @entries.delete_if { |_, entry| entry.expires_at <= now }
+        @entries.delete(@entries.min_by { |_, entry| entry.expires_at }.first) while @entries.size > MAX_ENTRIES
+      end
     end
   end
 end

data/lib/volcano/function_response.rb

@@ -16,11 +16,15 @@ module Volcano
 
     def immutable_json(value)
       case value
-      when Hash then value.to_h { |key, item| [immutable_json(key), immutable_json(item)] }.freeze
+      when Hash then immutable_json_hash(value)
       when Array then value.map { |item| immutable_json(item) }.freeze
       when String then value.dup.freeze
       else value
       end
     end
+
+    def immutable_json_hash(value)
+      value.to_h { |key, item| [immutable_json(key), immutable_json(item)] }.freeze
+    end
   end
 end

data/lib/volcano/generated_transport_functions.rb

@@ -82,6 +82,10 @@ module Volcano
       return nil if text.empty?
       return text unless function_json?(text, headers)
 
+      parse_function_json(text)
+    end
+
+    def parse_function_json(text)
       parsed = JSON.parse(text)
       valid_function_encoding?(parsed) ? parsed : text
     rescue JSON::ParserError
@@ -90,13 +94,17 @@ module Volcano
 
     def valid_function_encoding?(value)
       case value
-      when Hash then value.all? { |key, item| valid_function_encoding?(key) && valid_function_encoding?(item) }
+      when Hash then valid_function_hash_encoding?(value)
       when Array then value.all? { |item| valid_function_encoding?(item) }
       when String then value.valid_encoding?
       else true
       end
     end
 
+    def valid_function_hash_encoding?(value)
+      value.all? { |key, item| valid_function_encoding?(key) && valid_function_encoding?(item) }
+    end
+
     def function_json?(text, headers)
       return true if text.start_with?('{', '[')
 

data/lib/volcano/generated_transport_support.rb

@@ -10,7 +10,12 @@ module Volcano
       rescue NameError => e
         raise unless e.name == :Generated && e.message.include?('private constant Volcano::Generated')
 
-        klass = Generated.const_get(type)
+        deserialize_private_model(Generated.const_get(type), value)
+      end
+
+      private
+
+      def deserialize_private_model(klass, value)
         if klass.respond_to?(:openapi_any_of) || klass.respond_to?(:openapi_one_of)
           klass.build(value)
         else
@@ -139,12 +144,16 @@ module Volcano
       def plain_value(value)
         value = value.to_hash if value.respond_to?(:to_hash)
         case value
-        when Hash then value.to_h { |key, item| [key.to_s, plain_value(item)] }
+        when Hash then plain_hash(value)
         when Array then value.map { |item| plain_value(item) }
         else value
         end
       end
 
+      def plain_hash(value)
+        value.to_h { |key, item| [key.to_s, plain_value(item)] }
+      end
+
       def deep_symbolize(value)
         case value
         when Hash then value.to_h { |key, item| [key.to_sym, deep_symbolize(item)] }
@@ -163,10 +172,14 @@ module Volcano
       end
 
       def prepare_stream(value)
-        value.open if value.respond_to?(:closed?) && value.closed? && value.respond_to?(:open)
+        reopen_stream(value)
         value.binmode if value.respond_to?(:binmode)
         value.rewind if value.respond_to?(:rewind)
       end
+
+      def reopen_stream(value)
+        value.open if value.respond_to?(:closed?) && value.closed? && value.respond_to?(:open)
+      end
     end
 
     # Builds generated API wrappers with consistent authentication and timeouts.

data/lib/volcano/log_responses.rb

@@ -7,12 +7,16 @@ module Volcano
 
     def immutable_json(value)
       case value
-      when Hash then value.to_h { |key, item| [immutable_json(key), immutable_json(item)] }.freeze
+      when Hash then immutable_json_hash(value)
       when Array then value.map { |item| immutable_json(item) }.freeze
       when Time, String then value.dup.freeze
       else value
       end
     end
+
+    def immutable_json_hash(value)
+      value.to_h { |key, item| [immutable_json(key), immutable_json(item)] }.freeze
+    end
   end
   private_constant :ImmutableLogJSON
 

data/lib/volcano/models.rb

@@ -59,42 +59,6 @@ module Volcano
     end
   end
   EmailChangeResult = Data.define(:message, :new_email)
-  USER_OPTIONAL_ATTRIBUTES = %i[
-    project_id email_confirmed user_metadata app_metadata avatar_url banned_until
-    last_sign_in_at created_at updated_at
-  ].freeze
-  private_constant :USER_OPTIONAL_ATTRIBUTES
-
-  User = Data.define(
-    :id, :project_id, :email, :email_confirmed, :user_metadata, :app_metadata,
-    :avatar_url, :status, :banned_until, :last_sign_in_at, :created_at, :updated_at
-  ) do
-    def initialize(id:, email:, status:, **attributes)
-      validate_optional_attributes(attributes)
-      super(
-        id: freeze_value(id),
-        email: freeze_value(email),
-        status: freeze_value(status),
-        **USER_OPTIONAL_ATTRIBUTES.to_h { |name| [name, freeze_value(attributes[name])] }
-      )
-    end
-
-    private
-
-    def validate_optional_attributes(attributes)
-      unknown = attributes.keys - USER_OPTIONAL_ATTRIBUTES
-      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
-    end
-
-    def freeze_value(value)
-      case value
-      when Hash then value.to_h { |key, item| [freeze_value(key), freeze_value(item)] }.freeze
-      when Array then value.map { |item| freeze_value(item) }.freeze
-      when String then value.dup.freeze
-      else value.frozen? ? value : value.dup.freeze
-      end
-    end
-  end
   LockLease = Data.define(:key, :token, :expires_at, :fencing_token) do
     def initialize(key:, token:, expires_at:, fencing_token:)
       super(

data/lib/volcano/realtime/postgres_changes.rb

@@ -11,10 +11,10 @@ module Volcano
       )
         super(
           type: Immutable.call(type.to_s), schema: Immutable.call(schema.to_s),
-          table: Immutable.call(table.to_s), record: record && Immutable.call(record),
-          old_record: old_record && Immutable.call(old_record),
-          columns: columns && Immutable.call(columns), timestamp: Immutable.call(timestamp.to_s),
-          id: id && Immutable.call(id), mode: mode && Immutable.call(mode.to_s)
+          table: Immutable.call(table.to_s), record: Immutable.optional(record),
+          old_record: Immutable.optional(old_record),
+          columns: Immutable.optional(columns), timestamp: Immutable.call(timestamp.to_s),
+          id: Immutable.optional(id), mode: mode && Immutable.call(mode.to_s)
         )
       end
     end

data/lib/volcano/realtime/postgres_database.rb

@@ -11,7 +11,7 @@ module Volcano
       attr_reader :database_name
 
       def database_name=(name)
-        unless name.nil? || (name.is_a?(String) && DATABASE_NAME.match?(name))
+        unless valid_database_name?(name)
           raise ArgumentError,
                 'database name must match ^[a-z0-9_]+$ and contain at most 64 characters'
         end
@@ -20,6 +20,10 @@ module Volcano
 
       private
 
+      def valid_database_name?(name)
+        name.nil? || (name.is_a?(String) && DATABASE_NAME.match?(name))
+      end
+
       def initialize_postgres_database
         @database_name = nil
         @postgres_fetch_semaphore = nil

data/lib/volcano/realtime/postgres_expansion.rb

@@ -7,7 +7,7 @@ module Volcano
       private
 
       def expanded_postgres_changes(requests)
-        return requests.map { |request| local_postgres_change(request.change) } unless requests.first.database_name
+        return local_postgres_changes(requests) unless requests.first.database_name
 
         records = fetch_postgres_records(requests)
         requests.map { |request| expanded_postgres_record(request, records) }
@@ -16,6 +16,10 @@ module Volcano
         requests.map(&:change)
       end
 
+      def local_postgres_changes(requests)
+        requests.map { |request| local_postgres_change(request.change) }
+      end
+
       def lightweight_delete?(change)
         change.mode == 'lightweight' && change.type == 'DELETE'
       end

data/lib/volcano/realtime/protocol.rb

@@ -48,9 +48,7 @@ module Volcano
       def self.subscribe(id:, channel:, recoverable: false, join_leave: false, recovery: nil)
         options = { 'channel' => channel }
         if recovery
-          options.merge!('recover' => true, 'positioned' => true, 'recoverable' => true)
-          options['epoch'] = recovery[:epoch] if recovery.key?(:epoch)
-          options['offset'] = recovery[:offset] if recovery.key?(:offset)
+          add_recovery_options(options, recovery)
         elsif recoverable
           options['recoverable'] = true
         end
@@ -58,6 +56,13 @@ module Volcano
         { 'id' => id, 'subscribe' => options }
       end
 
+      def self.add_recovery_options(options, recovery)
+        options.merge!('recover' => true, 'positioned' => true, 'recoverable' => true)
+        options['epoch'] = recovery[:epoch] if recovery.key?(:epoch)
+        options['offset'] = recovery[:offset] if recovery.key?(:offset)
+      end
+      private_class_method :add_recovery_options
+
       def self.publish(id:, channel:, data:) = { 'id' => id, 'publish' => { 'channel' => channel, 'data' => data } }
 
       def self.unsubscribe(id:, channel:) = { 'id' => id, 'unsubscribe' => { 'channel' => channel } }

data/lib/volcano/realtime/protocol_recovery.rb

@@ -59,7 +59,10 @@ module Volcano
         result_position = recovery_position(result['epoch'], result['offset'])
         return [nil, nil] unless result_position
 
-        publications = result.fetch('publications', [])
+        validate_recovery_publications(result.fetch('publications', []), result_position)
+      end
+
+      def validate_recovery_publications(publications, result_position)
         return [nil, nil] unless publications.is_a?(Array)
 
         validated = publications.map { |publication| validated_recovery_publication(publication, result_position) }

data/lib/volcano/realtime/protocol_recovery_position.rb

@@ -26,6 +26,11 @@ module Volcano
 
         completed = publication_position(publication, current)
         return unless completed
+
+        advance_publication_position(channel, completed, current)
+      end
+
+      def advance_publication_position(channel, completed, current)
         return mark_unknown_gap(channel) unless same_epoch?(completed, current)
         return if stale_position?(completed, current)
         return mark_unknown_gap(channel) unless next_position?(completed, current)
@@ -57,6 +62,10 @@ module Volcano
         return @position_gaps[channel] = true unless same_epoch?(gap, current)
         return if gap.fetch(:offset) <= current.fetch(:offset)
 
+        store_earliest_gap(channel, gap)
+      end
+
+      def store_earliest_gap(channel, gap)
         existing = @position_gaps[channel]
         return if existing == true
         return if existing && existing.fetch(:offset) <= gap.fetch(:offset)

data/lib/volcano/realtime.rb

@@ -34,14 +34,22 @@ module Volcano
     module Immutable
       module_function
 
+      def optional(value)
+        value && call(value)
+      end
+
       def call(value)
         case value
-        when Hash then value.to_h { |key, child| [call(key), call(child)] }.freeze
+        when Hash then call_hash(value)
         when Array then value.map { |child| call(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
+      end
     end
     private_constant :Immutable
 

data/lib/volcano/session.rb

@@ -37,15 +37,20 @@ module Volcano
     def self.validate_refresh(current, refreshed)
       return unless current
 
-      expected = session_id(current.access_token)
-      if expected && expected != session_id(refreshed&.access_token)
-        raise Error::AuthenticationError, 'Refreshed credentials belong to a different server session'
-      end
+      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)

data/lib/volcano/storage_models.rb

@@ -24,98 +24,26 @@ module Volcano
 
     def immutable_value(value)
       case value
-      when Hash
-        value.to_h { |key, item| [immutable_value(key), immutable_value(item)] }.freeze
+      when Hash then immutable_value_hash(value)
       when Array then value.map { |item| immutable_value(item) }.freeze
       when String then value.dup.freeze
-      else value.frozen? ? value : value.dup.freeze
+      else immutable_value_scalar(value)
       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
-      )
+    def immutable_value_scalar(value)
+      value.frozen? ? value : value.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)
+    def immutable_value_hash(value)
+      value.to_h { |key, item| [immutable_value(key), immutable_value(item)] }.freeze
     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
+  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
 end

data/lib/volcano/storage_mutations.rb

@@ -54,13 +54,15 @@ module Volcano
 
     def storage_paths(paths)
       path_list = paths.is_a?(String) ? [paths] : paths.to_a
-      if path_list.empty? || !path_list.all? { |path| path.is_a?(String) && !path.empty? }
-        raise ArgumentError, 'storage paths must be non-empty strings'
-      end
+      raise ArgumentError, 'storage paths must be non-empty strings' unless valid_storage_paths?(path_list)
 
       path_list.map { |path| path.dup.freeze }.freeze
     end
 
+    def valid_storage_paths?(paths)
+      !paths.empty? && paths.all? { |path| path.is_a?(String) && !path.empty? }
+    end
+
     def delete_path(path, binding)
       response = storage_request(binding: binding) do |token|
         @transport.delete_storage_object(

data/lib/volcano/storage_upload_models.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Volcano
+  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

data/lib/volcano/transport.rb

@@ -38,13 +38,17 @@ module Volcano
       payload = response.body.is_a?(Hash) ? response.body : {}
       retry_after = integer_header(response.headers, 'Retry-After') if response.status == 429
       error_type(response.status).new(
-        payload['error'] || payload['message'] || 'Volcano request failed',
+        error_message(payload),
         status: response.status,
         code: payload['code']&.to_s,
         retry_after: retry_after
       )
     end
 
+    def error_message(payload)
+      payload['error'] || payload['message'] || 'Volcano request failed'
+    end
+
     def error_type(status)
       ERROR_TYPES.fetch(status) do
         status.between?(500, 599) ? Error::ServerError : Error::VolcanoError

data/lib/volcano/user.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Volcano
+  USER_OPTIONAL_ATTRIBUTES = %i[
+    project_id email_confirmed user_metadata app_metadata avatar_url banned_until
+    last_sign_in_at created_at updated_at
+  ].freeze
+  private_constant :USER_OPTIONAL_ATTRIBUTES
+
+  User = Data.define(
+    :id, :project_id, :email, :email_confirmed, :user_metadata, :app_metadata,
+    :avatar_url, :status, :banned_until, :last_sign_in_at, :created_at, :updated_at
+  ) do
+    def initialize(id:, email:, status:, **attributes)
+      validate_optional_attributes(attributes)
+      super(
+        id: freeze_value(id),
+        email: freeze_value(email),
+        status: freeze_value(status),
+        **USER_OPTIONAL_ATTRIBUTES.to_h { |name| [name, freeze_value(attributes[name])] }
+      )
+    end
+
+    private
+
+    def validate_optional_attributes(attributes)
+      unknown = attributes.keys - USER_OPTIONAL_ATTRIBUTES
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+    end
+
+    def freeze_value(value)
+      case value
+      when Hash then freeze_value_hash(value)
+      when Array then value.map { |item| freeze_value(item) }.freeze
+      when String then value.dup.freeze
+      else freeze_value_scalar(value)
+      end
+    end
+
+    def freeze_value_scalar(value)
+      value.frozen? ? value : value.dup.freeze
+    end
+
+    def freeze_value_hash(value)
+      value.to_h { |key, item| [freeze_value(key), freeze_value(item)] }.freeze
+    end
+  end
+end

data/lib/volcano/version.rb

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

data/lib/volcano.rb

@@ -3,11 +3,13 @@
 require_relative 'volcano/version'
 require_relative 'volcano/connection_string'
 require_relative 'volcano/models'
+require_relative 'volcano/user'
 require_relative 'volcano/session'
 require_relative 'volcano/function_response'
 require_relative 'volcano/durable_models'
 require_relative 'volcano/log_responses'
 require_relative 'volcano/storage_models'
+require_relative 'volcano/storage_upload_models'
 require_relative 'volcano/session_operations'
 require_relative 'volcano/auth_state'
 require_relative 'volcano/errors'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: volcano-sdk
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.10.2
 platform: ruby
 authors:
 - Kong
@@ -148,6 +148,7 @@ files:
 - lib/volcano/auth_sign_out.rb
 - lib/volcano/auth_sign_up.rb
 - lib/volcano/auth_state.rb
+- lib/volcano/auth_state_notifications.rb
 - lib/volcano/auth_update_user.rb
 - lib/volcano/client.rb
 - lib/volcano/connection_string.rb
@@ -597,8 +598,10 @@ files:
 - lib/volcano/storage_mutations.rb
 - lib/volcano/storage_public_url.rb
 - lib/volcano/storage_resumable_upload.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
 homepage: https://github.com/Kong/volcano-sdk-ruby
 licenses: