volcano-sdk 0.27.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d244570ed2e33751efeb30aa873400168dd80c0c490cf4536ce5dbb6a33f057b
-  data.tar.gz: ef977dcbbff49ebcb7e43ab1cfdf9aa292a58816281a48988af2de203c8c4dca
+  metadata.gz: e946d4476603cf2c234194f51e63aadd8ca1327719bcae02bf098de61049b65b
+  data.tar.gz: 38d3aa7dbbc508796620f75285b2a483b70a9e2d49a255aded0dba3fa023334b
 SHA512:
-  metadata.gz: c8f7c362b7f9c3c7c00dc91409e8816c941e2c2244b2b2e1f2035c3c4c40f2aef9a91eec84701cb4230c4ad741ec3a4fe80063a42592012ce8024532b753f698
-  data.tar.gz: f1c26e610f4739303885d5a1d4aa03f86117bc74e4228329e21ef91e379e9f39c55bbee46569dc73ceecb4a68e03d13853e15dcf4cec712ea44fe7d7e6d47bff
+  metadata.gz: 014b16629b5d06e89d39f010b1c8cb550582f3f7f224b6c6911324c6b2b07196eed9729305c2edd623d6fbedb2ba12a9460d4d128bda61202c9c88874823fada
+  data.tar.gz: d98691e237fd5cdb277f701701e3549aa6e533179d36c0039e188a66143fe5992a1ac9565f210304704838d2e855a9512e9e2e60de7ec0b2abfa9a8a30ae4cb2

data/lib/volcano/function_resolution.rb

@@ -16,11 +16,7 @@ module Volcano
     # A cached resolve result. A nil resolution is a remembered miss.
     Outcome = Data.define(:resolution, :failure)
 
-    Failure = Data.define(:message, :code, :retry_after) do
-      def exception
-        Error::NotFoundError.new(message.dup, status: 404, code: code&.dup, retry_after: retry_after)
-      end
-    end
+    Failure = Data.define(:message, :code, :retry_after)
     private_constant :Failure
 
     Entry = Data.define(:outcome, :expires_at)
@@ -51,21 +47,23 @@ 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 nonempty_url?(value)
+        url = nonempty_url(value)
+        return nil unless url
 
-        uri = URI.parse(value)
+        uri = URI.parse(url)
         return nil unless usable_address?(uri)
 
-        usable_scheme?(uri.scheme, api_url) ? value : nil
+        usable_scheme?(uri.scheme, api_url) ? url : nil
       rescue URI::InvalidURIError
         nil
       end
 
       # Returns the cached Outcome for a name, or nil when it must be resolved.
       def lookup(api_url, authorization, name)
+        # @type var key: [String, String, String]
         key = [api_url, authorization, name]
         @lock.synchronize do
-          entry = @entries[key]
+          entry = @entries.fetch(key, nil)
           next nil if entry.nil?
 
           if entry.expires_at <= now
@@ -89,6 +87,11 @@ module Volcano
         write([api_url, authorization, name], Outcome.new(resolution: nil, failure: failure), NEGATIVE_TTL_SECONDS)
       end
 
+      def error_for(failure)
+        Error::NotFoundError.new(failure.message.dup, status: 404, code: failure.code&.dup,
+                                                      retry_after: failure.retry_after)
+      end
+
       # Drops one cached resolution that turned out to be stale.
       def forget(api_url, authorization, name)
         @lock.synchronize { @entries.delete([api_url, authorization, name]) }
@@ -106,8 +109,8 @@ module Volcano
 
       private
 
-      def nonempty_url?(value)
-        value.is_a?(String) && !value.empty?
+      def nonempty_url(value)
+        value if value.is_a?(String) && !value.empty?
       end
 
       def usable_address?(uri)
@@ -126,15 +129,15 @@ module Volcano
       def write(key, outcome, ttl_seconds)
         @lock.synchronize do
           @entries[key] = Entry.new(outcome: outcome, expires_at: now + ttl_seconds)
-          next if @entries.size <= MAX_ENTRIES
-
-          evict_expired_entries
+          evict_expired_entries if @entries.size > MAX_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
+        while @entries.size > MAX_ENTRIES
+          @entries.min_by(1) { |_, entry| entry.expires_at }.each { |pair| @entries.delete(pair.first) }
+        end
       end
     end
   end

data/lib/volcano/function_response.rb

@@ -2,14 +2,15 @@
 
 module Volcano
   # Immutable result of one function invocation.
-  FunctionResponse = Data.define(:data, :status, :headers, :version) do
+  FunctionResponse = Data.define(:data, :status, :headers, :version)
+
+  # Reopen the generated Data class so Steep can check its initializer.
+  class FunctionResponse
     def initialize(data:, status:, headers:, version:)
-      super(
-        data: immutable_json(data),
-        status: status,
-        headers: immutable_json(headers),
-        version: version&.dup&.freeze
-      )
+      data = immutable_json(data)
+      headers = immutable_json(headers)
+      version = version&.dup&.freeze
+      super
     end
 
     private

data/lib/volcano/functions.rb

@@ -98,7 +98,7 @@ module Volcano
     end
 
     def cached_resolution(cached)
-      cached.resolution || raise(cached.failure.exception)
+      cached.resolution || raise(FunctionResolution.error_for(cached.failure))
     end
 
     def validate_invocation(name, payload)

data/lib/volcano/generated_transport.rb

@@ -52,7 +52,9 @@ module Volcano
       invoke do
         apis = @api_factory.call(authorization)
         body = Generated::ProjectLockLeaseRequest.new(ttl_seconds: ttl)
-        result = apis.locks.acquire_project_lock_with_http_info(key, token, request_id, body)
+        result = apis.locks.acquire_project_lock_with_http_info(
+          key, token, request_id, body, debug_return_type: 'Object'
+        )
         data, status, headers = result
         response(data, status, headers)
       end
@@ -63,7 +65,8 @@ module Volcano
         apis = @api_factory.call(authorization)
         data, status, headers = apis.locks.get_project_lock_with_http_info(
           key,
-          request_id
+          request_id,
+          debug_return_type: 'Object'
         )
         response(data, status, headers)
       end
@@ -85,7 +88,7 @@ module Volcano
         apis = @api_factory.call(authorization)
         body = Generated::ProjectLockLeaseRequest.new(ttl_seconds: ttl)
         result = apis.locks.renew_project_lock_with_http_info(
-          key, token, request_id, body
+          key, token, request_id, body, debug_return_type: 'Object'
         )
         data, status, headers = result
         response(data, status, headers)

data/lib/volcano/lock_guard.rb

@@ -84,7 +84,7 @@ module Volcano
         wait = wait_duration(deadline)
         return false unless wait
 
-        @changed.wait(@mutex, wait)
+        @changed.wait(@mutex, Float(wait))
       end
     end
 
@@ -129,7 +129,11 @@ module Volcano
     def remaining_time = @lease_clock.remaining
 
     def wait_deadline(timeout)
-      timeout && (@lease_clock.monotonic_now + timeout)
+      return unless timeout
+
+      raise ArgumentError, 'invalid timeout' unless timeout.is_a?(Numeric) && timeout.real? && timeout.finite?
+
+      @lease_clock.monotonic_now + timeout
     end
   end
 end

data/lib/volcano/lock_renewer.rb

@@ -22,10 +22,11 @@ module Volcano
 
     def stop
       request_stop
-      return unless @thread
+      thread = @thread
+      return unless thread
 
       # Renew requires current token ownership, so a late request cannot resurrect a released lease.
-      @thread.join(@config.shutdown_timeout)
+      thread.join(@config.shutdown_timeout)
     end
 
     private

data/lib/volcano/lock_response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Volcano
+  # Validates lock response fields before creating public records.
+  module LockResponse
+    private
+
+    def parse_time(value)
+      return Time.iso8601(value) if value.is_a?(String)
+      return value if value.nil? || value.is_a?(Time)
+
+      raise Error::TransportError, 'invalid lock expiry'
+    rescue ArgumentError => e
+      raise Error::TransportError, 'invalid lock expiry', cause: e
+    end
+
+    def required_time(value)
+      parse_time(value) || raise(Error::TransportError, 'invalid lock expiry')
+    end
+
+    def lock_payload(body)
+      raise Error::TransportError, 'invalid lock response' unless body.is_a?(Hash)
+
+      body
+    end
+
+    def lock_held(value)
+      return true if value == true
+      return false if value == false
+
+      raise Error::TransportError, 'invalid lock held flag'
+    end
+
+    def required_fencing_token(value)
+      raise Error::TransportError, 'invalid lock fencing token' unless value.is_a?(Integer)
+
+      value
+    end
+
+    def optional_fencing_token(value)
+      return if value.nil?
+
+      required_fencing_token(value)
+    end
+  end
+end

data/lib/volcano/lock_session.rb

@@ -44,6 +44,7 @@ module Volcano
     end
 
     def cleanup(completed)
+      # @type var failure: StandardError?
       failure = nil
       @guard.stop_expiry_watch
       failure = @guard.failure

data/lib/volcano/locks.rb

@@ -7,6 +7,7 @@ module Volcano
   # Acquires and releases project-scoped distributed locks.
   class Locks
     include LockAutoRenewal
+    include LockResponse
 
     def initialize(client, transport)
       @client = client
@@ -14,80 +15,103 @@ module Volcano
     end
 
     def get(key, request_id: nil)
-      payload = lock_request(:get_project_lock, 200, key: key, request_id: request_id)
-      LockState.new(
-        held: payload.fetch('held'),
-        expires_at: parse_time(payload['expires_at']),
-        fencing_token: payload['fencing_token']
-      )
+      payload = lock_payload(perform_request(200) do
+        @transport.get_project_lock(
+          authorization: @client.service_token, key: key, request_id: request_uuid(request_id, 'request_id')
+        )
+      end)
+      build_state(payload)
     end
 
     def acquire(key, ttl:, token: nil, request_id: nil)
       validate_ttl(ttl)
-      parameters = {
-        authorization: @client.service_token.dup.freeze, key: key.dup.freeze,
-        ttl: ttl, token: request_uuid(token, 'token'), request_id: request_uuid(request_id, 'request_id')
-      }.freeze
-      payload = acquire_payload(parameters)
-      build_lease(parameters[:key], parameters[:token], payload)
+      authorization = @client.service_token.dup.freeze
+      owned_key = key.dup.freeze
+      owned_token = request_uuid(token, 'token')
+      owned_request_id = request_uuid(request_id, 'request_id')
+      payload = acquire_payload(
+        authorization: authorization, key: owned_key, ttl: ttl, token: owned_token, request_id: owned_request_id
+      )
+      build_lease(owned_key, owned_token, payload)
     end
 
     def renew(key, lease, ttl:, request_id: nil)
       validate_ttl(ttl)
-      payload = lock_request(:renew_project_lock, 200, key: key, ttl: ttl,
-                                                       token: lease.token, request_id: request_id)
+      payload = lock_payload(perform_request(200) do
+        @transport.renew_project_lock(
+          authorization: @client.service_token, key: key, ttl: ttl,
+          token: lease.token, request_id: request_uuid(request_id, 'request_id')
+        )
+      end)
       build_lease(key, lease.token, payload)
     end
 
     def release(key, lease, request_id: nil)
-      lock_request(:release_project_lock, 204, key: key, token: lease.token, request_id: request_id)
+      perform_request(204) do
+        @transport.release_project_lock(
+          authorization: @client.service_token, key: key, token: lease.token,
+          request_id: request_uuid(request_id, 'request_id')
+        )
+      end
       nil
     end
 
     def force_release(key, request_id: nil)
-      lock_request(:force_release_project_lock, 204, key: key, request_id: request_id)
+      perform_request(204) do
+        @transport.force_release_project_lock(
+          authorization: @client.service_token, key: key, request_id: request_uuid(request_id, 'request_id')
+        )
+      end
       nil
     end
 
     private
 
-    def acquire_payload(parameters)
-      perform_request(:acquire_project_lock, 201, parameters)
+    def acquire_payload(authorization:, key:, ttl:, token:, request_id:)
+      lock_payload(perform_request(201) do
+        @transport.acquire_project_lock(authorization: authorization, key: key, ttl: ttl,
+                                        token: token, request_id: request_id)
+      end)
     rescue Error::TransportError, Error::ServerError => e
       raise unless e.status.nil? || e.status == 503
 
-      perform_request(:acquire_project_lock, 201, parameters)
-    end
-
-    def lock_request(operation, status, **parameters)
-      parameters[:authorization] = @client.service_token
-      parameters[:request_id] = request_uuid(parameters[:request_id], 'request_id')
-      perform_request(operation, status, parameters)
+      lock_payload(perform_request(201) do
+        @transport.acquire_project_lock(authorization: authorization, key: key, ttl: ttl,
+                                        token: token, request_id: request_id)
+      end)
     end
 
-    def perform_request(operation, status, parameters)
-      response = Transport.invoke { @transport.public_send(operation, **parameters) }
+    def perform_request(status, &)
+      response = Transport.invoke(&)
       Transport.body(response, status)
     end
 
     def request_uuid(value, name)
       return SecureRandom.uuid.freeze if value.nil?
 
-      valid = value.is_a?(String) && value.match?(/\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
-      raise ArgumentError, "#{name} must be a UUID string" unless valid
+      unless value.is_a?(String) && value.match?(/\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
+        raise ArgumentError, "#{name} must be a UUID string"
+      end
 
       value.dup.freeze
     end
 
     def build_lease(key, token, payload)
       LockLease.new(
-        key: key, token: token, expires_at: parse_time(payload['expires_at']),
-        fencing_token: payload['fencing_token']
+        key: key, token: token, expires_at: required_time(payload['expires_at']),
+        fencing_token: required_fencing_token(payload['fencing_token'])
       )
     end
 
-    def parse_time(value)
-      value.is_a?(String) ? Time.iso8601(value) : value
+    def build_state(payload)
+      held = lock_held(payload['held'])
+      expiry = held ? required_time(payload['expires_at']) : parse_time(payload['expires_at'])
+      fencing = if held
+                  required_fencing_token(payload['fencing_token'])
+                else
+                  optional_fencing_token(payload['fencing_token'])
+                end
+      LockState.new(held: held, expires_at: expiry, fencing_token: fencing)
     end
   end
 end

data/lib/volcano/log_responses.rb

@@ -20,24 +20,28 @@ module Volcano
   end
   private_constant :ImmutableLogJSON
 
+  LogSearchResponse = Data.define(:data, :limit, :has_more, :next_cursor)
+
   # Immutable page returned by a project log search.
-  LogSearchResponse = Data.define(:data, :limit, :has_more, :next_cursor) do
+  class LogSearchResponse
     include ImmutableLogJSON
 
     def initialize(data:, limit:, has_more:, next_cursor: nil)
-      super(
-        data: immutable_json(data), limit: limit, has_more: has_more,
-        next_cursor: next_cursor&.dup&.freeze
-      )
+      data = immutable_json(data)
+      next_cursor = next_cursor&.dup&.freeze
+      super
     end
   end
 
+  LogActivityResponse = Data.define(:data, :total)
+
   # Immutable bucketed project log activity.
-  LogActivityResponse = Data.define(:data, :total) do
+  class LogActivityResponse
     include ImmutableLogJSON
 
     def initialize(data:, total:)
-      super(data: immutable_json(data), total: total)
+      data = immutable_json(data)
+      super
     end
   end
 end

data/lib/volcano/realtime/blocking_call.rb

@@ -4,26 +4,25 @@ module Volcano
   class Realtime
     # Runs one blocking operation off the Async reactor and returns its result.
     module BlockingCall
-      Result = Data.define(:value, :error)
-      private_constant :Result
+      Success = Data.define(:value)
+      Failure = Data.define(:error)
+      private_constant :Success, :Failure
 
-      module_function
-
-      def call(&operation)
+      def self.call(&operation)
         results = ::Queue.new
         worker = Thread.new { execute(results, operation) }
         worker.report_on_exception = false
         result = results.pop
         worker.join
-        raise result.error if result.error
+        raise result.error if result.is_a?(Failure)
 
         result.value
       end
 
-      def execute(results, operation)
-        results << Result.new(value: operation.call, error: nil)
+      def self.execute(results, operation)
+        results << Success.new(value: operation.call)
       rescue StandardError => e
-        results << Result.new(value: nil, error: e)
+        results << Failure.new(error: e)
       end
       private_class_method :execute
     end

data/lib/volcano/realtime/protocol_recovery_position.rb

@@ -21,7 +21,7 @@ module Volcano
       end
 
       def complete_publication(channel, publication)
-        current = @stream_positions[channel]
+        current = @stream_positions.fetch(channel, nil)
         return unless current
 
         completed = publication_position(publication, current)
@@ -49,7 +49,7 @@ module Volcano
       end
 
       def mark_publication_gap(channel, publication)
-        current = @stream_positions[channel]
+        current = @stream_positions.fetch(channel, nil)
         return unless current
 
         gap = publication_position(publication, current)
@@ -68,7 +68,7 @@ module Volcano
       def store_earliest_gap(channel, gap)
         existing = @position_gaps[channel]
         return if existing == true
-        return if existing && existing.fetch(:offset) <= gap.fetch(:offset)
+        return if existing.is_a?(Hash) && existing.fetch(:offset) <= gap.fetch(:offset)
 
         @position_gaps[channel] = gap
       end
@@ -84,7 +84,9 @@ module Volcano
         return unless epoch.is_a?(String) && !epoch.empty?
         return unless offset.is_a?(Integer) && offset >= 0
 
-        { epoch: epoch.dup.freeze, offset: offset.freeze }.freeze
+        # @type var position: position
+        position = { epoch: epoch.dup.freeze, offset: offset.freeze }
+        position.freeze
       end
 
       def same_epoch?(first, second) = first.fetch(:epoch) == second.fetch(:epoch)
@@ -95,7 +97,10 @@ module Volcano
 
       def completion_before_gap?(channel, completed)
         gap = @position_gaps[channel]
-        gap != true && (!gap || completed.fetch(:offset) < gap.fetch(:offset))
+        return false if gap == true
+        return true unless gap.is_a?(Hash)
+
+        completed.fetch(:offset) < gap.fetch(:offset)
       end
 
       def mark_unknown_gap(channel) = @position_gaps[channel] = true

data/lib/volcano/sign_up_result.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module Volcano
-  SignUpResult = Data.define(:confirmation_required, :message, :session) do
+  SignUpResult = Data.define(:confirmation_required, :message, :session)
+
+  # Reopen the generated Data class so Steep can check its initializer.
+  class SignUpResult
+    # @dynamic confirmation_required, message, session, members, with, to_h, deconstruct, deconstruct_keys
+    # @dynamic self.[], self.members
     def initialize(confirmation_required:, message:, session: nil)
       super
     end

data/lib/volcano/version.rb

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

data/lib/volcano.rb

@@ -50,6 +50,7 @@ require_relative 'volcano/lock_guard'
 require_relative 'volcano/lock_renewer'
 require_relative 'volcano/lock_session'
 require_relative 'volcano/lock_auto_renewal'
+require_relative 'volcano/lock_response'
 require_relative 'volcano/locks'
 require_relative 'volcano/realtime/protocol'
 require_relative 'volcano/realtime'
@@ -57,7 +58,7 @@ require_relative 'volcano/client'
 
 # Public namespace for the Volcano Ruby SDK.
 module Volcano
-  private_constant :GeneratedTransport, :LockAutoRenewal, :LockLeaseClock, :LockRenewer, :LockSession,
+  private_constant :GeneratedTransport, :LockAutoRenewal, :LockLeaseClock, :LockRenewer, :LockSession, :LockResponse,
                    :Redaction, :SessionOperations
 
   Realtime.private_constant :Protocol, :ProtocolDispatch, :ProtocolPublicationDispatch, :ProtocolRecovery,

data/sig/lock_guard.rbs

@@ -0,0 +1,21 @@
+module Volcano
+  interface _LeaseStartedAt
+    def monotonic: () -> Float
+    def wall: () -> Time
+  end
+
+  class LockGuard
+    EXPIRY_MESSAGE: String
+    MAX_EXPIRY_POLL_SECONDS: Float
+    UNSAFE_RENEWAL_MESSAGE: String
+
+    attr_reader ttl: Integer
+
+    def initialize: (LockLease lease, ttl: Integer, started_at: _LeaseStartedAt) -> void
+    def lease: () -> LockLease
+    def lost?: () -> bool
+    # The timeout must be a finite real number.
+    def wait_lost: (?timeout: Numeric?) -> bool
+    def failure: () -> StandardError?
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: volcano-sdk
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Kong
@@ -560,6 +560,7 @@ files:
 - lib/volcano/lock_guard.rb
 - lib/volcano/lock_lease_clock.rb
 - lib/volcano/lock_renewer.rb
+- lib/volcano/lock_response.rb
 - lib/volcano/lock_session.rb
 - lib/volcano/locks.rb
 - lib/volcano/log_responses.rb
@@ -609,6 +610,7 @@ files:
 - sig/email_change_result.rbs
 - sig/errors.rbs
 - sig/function_response.rbs
+- sig/lock_guard.rbs
 - sig/lock_records.rbs
 - sig/log_responses.rbs
 - sig/oauth_records.rbs