kessel-sdk 1.12.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 997a5d14ffc861c340630e331dfd5c34f367ed7f68b9f760363a817180c10711
-  data.tar.gz: 6144712b5dec3a5355bc3f7e6a35953a0b4a2c2beeee56b017eebc659c03f3bc
+  metadata.gz: 6a800ed3c85f59d9a3c3693b03a930d0c15c3f9469afcf7415439c1df6ce0ed5
+  data.tar.gz: 7af05d6be0c40cac48b26ce2a4e62168561b9b8291bbb320984676cc1a95385c
 SHA512:
-  metadata.gz: 7397b29d146033e8d2060af9e25195debd851f052b4c3fad903277bd13b25ed8a1588f5a712bc8952e18fc75315cb79bd32c3a8732c07604f0cf51d2689ba843
-  data.tar.gz: 0c3b20634ed5d7529d66ba4b3e06c15e677eddfaf676618eaa4864205d7157a3b57d9cbab91b77de8e3adbbdbb707e255ef3055e986de6064a87b9c284b0e7dc
+  metadata.gz: a2606225a968c861b8097c89f11076e111b48f2873cddcdce7784bb08e67c51df5cc7ef313686ebf4991c3d357323f8e35d751e68be2af27130aaa9faed99915
+  data.tar.gz: f9707c137cffaf0d86546da1986078baa60c887adde5e65835403e8fecd6f19ce3b781a9330c59455da3046e6cab80ef3163aea01b01cfad6e786657b5415689

data/README.md

@@ -130,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
@@ -347,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/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.12.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.12.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: []