kessel-sdk 1.11.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f118f8d4a64bb88e16061100917338de50a57456725240592395e4e9469eb18
-  data.tar.gz: 0cdba6a003c929eb0e111ef832fdc602b13a0dc48dc52ea773522c096408cea8
+  metadata.gz: 6a800ed3c85f59d9a3c3693b03a930d0c15c3f9469afcf7415439c1df6ce0ed5
+  data.tar.gz: 7af05d6be0c40cac48b26ce2a4e62168561b9b8291bbb320984676cc1a95385c
 SHA512:
-  metadata.gz: d172c0dc4223a7aca090c58a14ab2c86421383ad1fc0c7931690f576fa1d88130bde656b495455f0fcd91c331d4f2dcb935963a3f9f7a5708640849102d26ddd
-  data.tar.gz: 1112d3a51e7c23f00371d88adf7cc17e8323e20d4d80663272f7a55c87e52c5b50374582c2c203a75d14954773b0ebb982c4df79553a067edcfc737d44721eb9
+  metadata.gz: a2606225a968c861b8097c89f11076e111b48f2873cddcdce7784bb08e67c51df5cc7ef313686ebf4991c3d357323f8e35d751e68be2af27130aaa9faed99915
+  data.tar.gz: f9707c137cffaf0d86546da1986078baa60c887adde5e65835403e8fecd6f19ce3b781a9330c59455da3046e6cab80ef3163aea01b01cfad6e786657b5415689

data/README.md

@@ -97,7 +97,8 @@ discovery = fetch_oidc_discovery('https://sso.example.com/auth/realms/my-realm')
 oauth = OAuth2ClientCredentials.new(
   client_id: 'my-app',
   client_secret: 'my-secret',
-  token_endpoint: discovery.token_endpoint
+  token_endpoint: discovery.token_endpoint,
+  retry: { max_retries: 3, base_delay: 0.5, max_delay: 2.0, jitter: :full }
 )
 
 # Build the client -- tokens are cached and refreshed automatically
@@ -106,6 +107,13 @@ client = KesselInventoryService::ClientBuilder.new('kessel.example.com:443')
                                               .build
 ```
 
+Token fetch retries apply only to the token endpoint, not OIDC discovery. By default, network/timeout errors and HTTP
+429/5xx responses receive four total attempts (initial plus three retries), with full-jitter delay caps of 0.5, 1,
+and 2 seconds and total added sleep below 3.5 seconds. `retry` accepts non-negative integer `max_retries` (0
+disables retries), positive finite-second `base_delay` and `max_delay`, and `jitter: :full` or `:none`; defaults are
+`3`, `0.5`, `2.0`, and `:full`. Invalid retry configuration raises `ArgumentError`. Permanent OAuth/configuration
+failures are not retried. Refresh is synchronous, so a transient SSO failure may delay an RPC.
+
 #### Custom or No Credentials
 
 ```ruby
@@ -122,6 +130,31 @@ client = KesselInventoryService::ClientBuilder.new(target)
 
 Build the client **once at application startup and reuse it**. The underlying gRPC channel manages its own HTTP/2 connection pool.
 
+### HTTP/2 Keepalive
+
+All inventory clients now use these transport keepalive defaults, including clients created by existing builder chains:
+
+- Ping interval: 45 seconds
+- Ping acknowledgement timeout: 10 seconds
+- Permit pings while there are no active calls: enabled
+
+Override these values with the fluent `keepalive` method. Durations are finite positive real numbers in seconds and
+are converted to integer milliseconds by truncating any fractional millisecond downward. The resulting value must be
+between 1 and 2,147,483,647 milliseconds. Passing `nil` leaves that setting unchanged; `permit_without_calls` accepts
+only `true` or `false` (including `false` as an explicit override).
+
+```ruby
+client = Kessel::Inventory::V1beta2::KesselInventoryService::ClientBuilder
+  .new(ENV.fetch('KESSEL_ENDPOINT', nil))
+  .keepalive(interval: 60, timeout: 10, permit_without_calls: false)
+  .build
+```
+
+The Ruby SDK sets `grpc.http2.max_pings_without_data` internally to avoid a local cap; it is not a public configuration
+option. Before rollout, confirm that the Kessel server and any gateway enforce compatible keepalive policies
+(RHCLOUD-51673). Keepalive is a transport-level ping mechanism, not an RPC health check and does not provide retries
+or load-balancer guarantees. The builder still returns a gRPC stub; build it once and reuse it as usual.
+
 ### Check Permissions
 
 ```ruby
@@ -339,6 +372,7 @@ The `examples/` directory contains working examples. Set up environment variable
 | `check_for_update_bulk.rb` | Bulk strongly consistent update checks |
 | `delete_resource.rb` | Deleting resources |
 | `fetch_workspaces.rb` | Fetching workspaces via RBAC HTTP API |
+| `keepalive.rb` | Configuring HTTP/2 keepalive on an inventory client |
 | `list_workspaces.rb` | Listing workspaces with auto-pagination |
 | `report_resource.rb` | Reporting resource state |
 | `console_principal.rb` | Building principals from `x-rh-identity` headers |

data/lib/kessel/auth.rb

@@ -2,6 +2,8 @@
 
 require 'grpc'
 require 'kessel/version'
+require 'socket'
+require 'timeout'
 
 module Kessel
   # OpenID Connect authentication module for Kessel services.
@@ -105,6 +107,7 @@ module Kessel
     #
     #   # Get current access token (automatically cached and refreshed)
     #   token = oauth.get_token
+    # rubocop:disable Metrics/ClassLength
     class OAuth2ClientCredentials
       include Kessel::Auth
 
@@ -113,9 +116,14 @@ module Kessel
       # @param client_id [String] OIDC client identifier
       # @param client_secret [String] OIDC client secret
       # @param token_endpoint [String] OIDC token endpoint URL
+      # @param retry [Hash] Optional token-endpoint retry settings. Keys are
+      #   `max_retries` (non-negative Integer; 0 disables retries), `base_delay`
+      #   and `max_delay` (positive finite seconds), and `jitter` (`:full` or
+      #   `:none`). Defaults are 3, 0.5, 2.0, and `:full`, respectively.
       #
       # @raise [OAuthDependencyError] if the openid_connect gem is not available
       # @raise [OAuthAuthenticationError] if authentication fails
+      # @raise [ArgumentError] if retry settings are invalid
       #
       # @example
       #   oauth = OAuth2ClientCredentials.new(
@@ -123,13 +131,20 @@ module Kessel
       #     client_secret: 'secret',
       #     token_endpoint: 'https://my-domain/auth/realms/my-realm/protocol/openid-connect/token'
       #   )
-      def initialize(client_id:, client_secret:, token_endpoint:)
+      def initialize(client_id:, client_secret:, token_endpoint:, **options)
+        validate_retry_options!(options)
+        retry_config = normalize_retry_config(options.fetch(:retry, {}))
         check_dependencies!
 
         @client_id = client_id
         @client_secret = client_secret
         @token_endpoint = token_endpoint
+        @retry_config = retry_config
         @token_mutex = Mutex.new
+        @generation_state_mutex = Mutex.new
+        @generation_users = Hash.new(0)
+        @generation_failures = {}
+        @cached_token_generation = nil
         @generation = 0
       end
 
@@ -147,23 +162,80 @@ module Kessel
       def get_token(force_refresh: false)
         return @cached_token if !force_refresh && token_valid?
 
-        generation = @generation
+        generation = register_generation
 
-        @token_mutex.synchronize do
-          # Another thread already refreshed while we waited on the lock
-          return @cached_token if @generation != generation && token_valid?
+        begin
+          @token_mutex.synchronize do
+            failure = generation_failure(generation)
 
-          @cached_token = refresh
-          @generation += 1
+            # A later successful generation may have recovered after this caller's failure.
+            return @cached_token if newer_cached_token?(generation)
+            raise failure if failure
+
+            begin
+              token = refresh
+            rescue StandardError => e
+              record_failure_and_advance(generation, e)
+              raise
+            end
+            cache_token_and_advance(token)
 
-          return @cached_token
+            @cached_token
+          end
         rescue StandardError => e
-          raise OAuthAuthenticationError, "Failed to obtain client credentials token: #{e.message}"
+          raise OAuthAuthenticationError, "Failed to obtain client credentials token: #{e.message}", cause: e
+        ensure
+          unregister_generation(generation)
         end
       end
 
       private
 
+      def register_generation
+        @generation_state_mutex.synchronize do
+          generation = @generation
+          @generation_users[generation] += 1
+          generation
+        end
+      end
+
+      def generation_failure(generation)
+        @generation_state_mutex.synchronize { @generation_failures[generation] }
+      end
+
+      def record_failure_and_advance(generation, error)
+        @generation_state_mutex.synchronize do
+          @generation_failures[generation] = error
+          @generation += 1
+        end
+      end
+
+      def advance_generation
+        @generation_state_mutex.synchronize { @generation += 1 }
+      end
+
+      def cache_token_and_advance(token)
+        @generation_state_mutex.synchronize do
+          @cached_token = token
+          @generation += 1
+          @cached_token_generation = @generation
+        end
+      end
+
+      def newer_cached_token?(generation)
+        !!(@cached_token_generation && @cached_token_generation > generation && token_valid?)
+      end
+
+      def unregister_generation(generation)
+        @generation_state_mutex.synchronize do
+          @generation_users[generation] -= 1
+          next unless @generation_users[generation].zero?
+
+          @generation_users.delete(generation)
+          @generation_failures.delete(generation)
+        end
+      end
+
       def refresh
         client = create_oidc_client
 
@@ -173,13 +245,117 @@ module Kessel
           client_secret: @client_secret
         }
 
-        token_data = client.access_token!(request_params)
+        token_data = access_token_with_retries(client, request_params)
         RefreshTokenResponse.new(
           access_token: token_data.access_token,
           expires_at: Time.now + (token_data.expires_in || DEFAULT_EXPIRES_IN)
         ).freeze
       end
 
+      def access_token_with_retries(client, request_params)
+        retry_index = 0
+
+        begin
+          client.access_token!(request_params)
+        rescue StandardError => e
+          raise unless retryable_token_error?(e) && retry_index < @retry_config[:max_retries]
+
+          sleep(retry_delay(retry_index))
+          retry_index += 1
+          retry
+        end
+      end
+
+      def validate_retry_options!(options)
+        unknown_keys = options.keys - [:retry]
+        return if unknown_keys.empty?
+
+        raise ArgumentError, "unknown keyword: #{unknown_keys.first.inspect}"
+      end
+
+      def normalize_retry_config(retry_options)
+        unless retry_options.is_a?(Hash) && retry_options.keys.all?(Symbol)
+          raise ArgumentError, 'retry must be a symbol-keyed Hash'
+        end
+
+        unknown_keys = retry_options.keys - %i[max_retries base_delay max_delay jitter]
+        raise ArgumentError, "unknown retry option: #{unknown_keys.first.inspect}" unless unknown_keys.empty?
+
+        config = {
+          max_retries: 3,
+          base_delay: 0.5,
+          max_delay: 2.0,
+          jitter: :full
+        }.merge(retry_options)
+        validate_retry_config_values!(config)
+        config.freeze
+      end
+
+      def validate_retry_config_values!(config)
+        unless config[:max_retries].is_a?(Integer) && config[:max_retries] >= 0
+          raise ArgumentError, 'retry max_retries must be a non-negative Integer'
+        end
+
+        %i[base_delay max_delay].each do |key|
+          next if valid_delay?(config[key])
+
+          raise ArgumentError, "retry #{key} must be a positive finite Integer or Float"
+        end
+
+        return if %i[full none].include?(config[:jitter])
+
+        raise ArgumentError, 'retry jitter must be :full or :none'
+      end
+
+      def valid_delay?(value)
+        (value.is_a?(Integer) || value.is_a?(Float)) && value.positive? &&
+          (!value.is_a?(Float) || value.finite?)
+      end
+
+      def retry_delay(retry_index)
+        cap = [@retry_config[:max_delay], @retry_config[:base_delay] * (2**retry_index)].min
+        return cap if @retry_config[:jitter] == :none
+
+        rand(cap.to_f)
+      end
+
+      def retryable_token_error?(error)
+        retryable_rack_oauth_error?(error) || retryable_transient_error?(error)
+      end
+
+      def retryable_rack_oauth_error?(error)
+        return false unless defined?(::Rack::OAuth2::Client::Error)
+        return false unless error.is_a?(::Rack::OAuth2::Client::Error)
+
+        status = error.status
+        status == 429 || (status.is_a?(Integer) && status.between?(500, 599))
+      end
+
+      def retryable_transient_error?(error)
+        transient_error_classes.any? { |error_class| error.is_a?(error_class) }
+      end
+
+      def transient_error_classes
+        %w[
+          Faraday::ConnectionFailed
+          Faraday::TimeoutError
+          Timeout::Error
+          SocketError
+          EOFError
+          Errno::ECONNREFUSED
+          Errno::ECONNRESET
+          Errno::ETIMEDOUT
+          Errno::EHOSTUNREACH
+          Errno::ENETUNREACH
+        ].map { |name| optional_error_class(name) }.compact
+      end
+
+      def optional_error_class(name)
+        Object.const_get(name, false)
+      rescue NameError
+        nil
+      end
+
       # Checks if we have a valid cached token.
       #
       # @return [Boolean] true if token exists and not expired
@@ -206,5 +382,6 @@ module Kessel
         )
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/kessel/inventory/GUIDELINES.md

@@ -59,6 +59,25 @@ client = KesselInventoryService::ClientBuilder.new(target)
 
 `build` returns a single gRPC stub instance (not a tuple). The underlying gRPC channel manages its own HTTP/2 connection pool. Build once at application startup and reuse -- do not create a new stub per request.
 
+### HTTP/2 Keepalive
+
+Every `ClientBuilder` passes these channel arguments to its service stub, including builders that do not call `keepalive`:
+
+- `grpc.keepalive_time_ms`: 45,000 (45 seconds)
+- `grpc.keepalive_timeout_ms`: 10,000 (10 seconds)
+- `grpc.keepalive_permit_without_calls`: 1 (enabled)
+- `grpc.http2.max_pings_without_data`: 0 (internal Ruby gRPC setting; not exposed as a public option)
+
+`keepalive(interval: nil, timeout: nil, permit_without_calls: nil)` is fluent. Duration keywords are finite positive real
+numbers in seconds, converted to integer milliseconds by truncating fractional milliseconds downward; the result must
+be 1 through 2,147,483,647. `nil` leaves the existing setting unchanged, and `permit_without_calls` accepts only the
+actual boolean values `true` and `false`. Each call validates every supplied value before changing any builder state.
+
+These are transport ping settings, not RPC health checks, retries, or load-balancer guarantees. Check server and gateway
+keepalive enforcement compatibility before rollout (RHCLOUD-51673); in particular, the 45-second interval may be
+affected by an infrastructure-enforced minimum. Ruby's `grpc.http2.max_pings_without_data` value is internal and is not a
+cross-SDK configuration knob.
+
 ## Service Wiring Pattern
 
 Every gRPC service module must follow this exact pattern:

data/lib/kessel/inventory.rb

@@ -14,9 +14,24 @@ module Kessel
     class ClientBuilder
       include Kessel::GRPC
 
+      MAX_KEEPALIVE_MILLISECONDS = 2_147_483_647
+      private_constant :MAX_KEEPALIVE_MILLISECONDS
+
       def initialize(target)
         @target = target
         raise 'Invalid target type' if @target.nil? || !@target.is_a?(String)
+
+        @channel_args = {
+          'grpc.keepalive_time_ms' => 45_000,
+          'grpc.keepalive_timeout_ms' => 10_000,
+          'grpc.keepalive_permit_without_calls' => 1,
+          'grpc.http2.max_pings_without_data' => 0
+        }
+      end
+
+      def keepalive(interval: nil, timeout: nil, permit_without_calls: nil)
+        @channel_args.merge!(keepalive_channel_args(interval, timeout, permit_without_calls))
+        self
       end
 
       def oauth2_client_authenticated(oauth2_client_credentials:, channel_credentials: nil)
@@ -52,7 +67,7 @@ module Kessel
 
         credentials = @channel_credentials
         credentials = credentials.compose(@call_credentials) unless @call_credentials.nil?
-        self.class.stub_class.new(@target, credentials)
+        self.class.stub_class.new(@target, credentials, channel_args: @channel_args.dup)
       end
 
       private
@@ -66,6 +81,41 @@ module Kessel
 
         raise 'Invalid credential configuration: can not authenticate with insecure channel'
       end
+
+      def keepalive_channel_args(interval, timeout, permit_without_calls)
+        channel_args = {}
+        channel_args['grpc.keepalive_time_ms'] = duration_to_milliseconds(interval, 'interval') unless interval.nil?
+        channel_args['grpc.keepalive_timeout_ms'] = duration_to_milliseconds(timeout, 'timeout') unless timeout.nil?
+
+        unless permit_without_calls.nil?
+          unless permit_without_calls.equal?(true) || permit_without_calls.equal?(false)
+            raise 'Invalid keepalive permit_without_calls: must be true, false, or nil'
+          end
+
+          channel_args['grpc.keepalive_permit_without_calls'] = permit_without_calls ? 1 : 0
+        end
+
+        channel_args
+      end
+
+      def duration_to_milliseconds(value, name)
+        unless value.is_a?(Numeric) && !value.is_a?(Complex) && value.respond_to?(:finite?) && value.finite?
+          raise "Invalid keepalive #{name}: must be a finite real number of seconds"
+        end
+
+        scaled_milliseconds = value * 1000
+        unless valid_scaled_keepalive_milliseconds?(scaled_milliseconds)
+          raise "Invalid keepalive #{name}: must convert to 1..#{MAX_KEEPALIVE_MILLISECONDS} milliseconds"
+        end
+
+        scaled_milliseconds.floor
+      end
+
+      def valid_scaled_keepalive_milliseconds?(milliseconds)
+        milliseconds.respond_to?(:finite?) &&
+          milliseconds.finite? &&
+          (1...(MAX_KEEPALIVE_MILLISECONDS + 1)).cover?(milliseconds)
+      end
     end
   end
 end

data/lib/kessel/version.rb

@@ -2,6 +2,6 @@
 
 module Kessel
   module Inventory
-    VERSION = '1.11.0'
+    VERSION = '1.13.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kessel-sdk
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Project Kessel
@@ -314,7 +314,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.7
+rubygems_version: 4.0.22
 specification_version: 4
 summary: Ruby SDK for Project Kessel
 test_files: []