keycardai-oauth 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fda3b3f30a1e8ccdf5d8c1dad0a9bc3ef99145990b1952c3382be766bffdd753
-  data.tar.gz: e4bb93fb097bc3dfd4cf894926860c241413c21b8e1cc05aff6432a632062e68
+  metadata.gz: b6be65f06dd7f30c0f08b133a505e32646582465a0c29df5b98307839dc9fbc8
+  data.tar.gz: b84732c663f023466399b27a6189683a15621c9808f85efc12063d02c29a5b3d
 SHA512:
-  metadata.gz: 1a48955a16091ebec04bc7bef9b7effa8e1036a8dd273a9c351724bd86c729cf60f305c2d396dad3bbd50ff8b34af34bf6d8db7db6ccbd9c4d1e4fd91f058b1e
-  data.tar.gz: 8ed634c0e436e8a6ea9603bce24a7e861a56ac22df7caff2971e089ed641fc698d998c8b5750a2d1c746162c1437243fa0c8524bd31e617096ae00be9a5710f4
+  metadata.gz: 7d5800dd06a3fe192e813f75703b1e0a419213fe812bc8328a540447e348f0953d6d21f305ec839e23ac3469fc0ddf7941271f5b241ea73d3e9cf77191c112a8
+  data.tar.gz: 9bcd9bdbdc892ced3f104a63fecb868821769f7f5a14897ac25bda322d3404ed3a00efed458ce30130436b8b0ca59a24e0e5253f1ff7aa22962cdb6d8840a42b

data/CHANGELOG.md

@@ -15,6 +15,19 @@ the loopback flow (RFC 8252), JWT signing and verification with a caching JWKS
 keyring, the three application credentials (ClientSecret with multi-zone,
 WebIdentity, WorkloadIdentity with pluggable token sources), and AccessContext.
 
+## 0.5.0-keycardai-oauth (2026-09-08)
+
+
+- feat(keycardai-oauth): reuse Net::HTTP sessions in the default transport
+- ECO-383. NetHTTPClient#perform built a fresh Net::HTTP per request, so every oauth call (and every verify and token exchange in the mcp gem, whose AuthProvider holds one NetHTTPClient) paid a new TCP and TLS handshake. Sessions are now kept per instance, per thread, per (host, port, scheme): the request path takes no lock, a small mutex guards only the registry of per-thread session maps, and dead threads are swept when the registry is touched. close finishes every session; an unclosed throwaway instance keeps its sessions until garbage collection, the same abandonment doctrine as the Python fix (python-sdk #291). Timeouts are applied per request, restoring Net::HTTP's own defaults when absent. No new dependencies; the gem stays stdlib-only.
+- Behavior change: a keepalive connection the server dropped while idle surfaces as NetworkError on the next request, where a fresh-connection design could not fail that way; the session reconnects on the attempt after. The Ruby retryability classification (ECO-360) is the consumer-side answer when it lands.
+
+## 0.4.0-keycardai-oauth (2026-09-05)
+
+
+- feat(keycardai-oauth): expire the cached token endpoint after discovery_ttl
+- ECO-366 Ruby leg, audited against keycard-sdk-spec's metadata-failures-are-not-sticky contract. The sticky-failure defect does not exist in Ruby: token-endpoint discovery stored outcomes with ||= under a mutex, so a raise cached nothing and an interrupted caller left nothing behind. The one gap was the endpoint being cached for the client lifetime; it is now cached for discovery_ttl (3600s default, the JWKS keyring's knob and default) with a clock: keyword mirroring TokenVerifier. No negative cache and no retryable field: the spec makes deterministic-failure caching optional and Ruby never stored failures, and retryability classification is ECO-360's Ruby leg. Conformance tests cover the spec's discovery rows on both clients via one shared example group.
+
 ## 0.3.0-keycardai-oauth (2026-09-01)
 
 

data/lib/keycardai/oauth/client_credentials_client.rb

@@ -8,7 +8,8 @@ module Keycardai
     # client assertion carried on the request.
     #
     # The token endpoint is discovered from the issuer on first use and
-    # cached. Requests do not retry transparently.
+    # cached for discovery_ttl; a failed discovery is not cached. Requests do
+    # not retry transparently.
     class ClientCredentialsClient
       include TokenRequests
 
@@ -21,12 +22,16 @@ module Keycardai
       #   provide both or neither
       # @param http_client [#get, #post_form] pluggable transport
       # @param timeout [Numeric, nil] request timeout in seconds
+      # @param discovery_ttl [Numeric] token-endpoint cache lifetime in seconds
+      # @param clock [#call] returns the current Time; override in tests
       # @raise [ConfigurationError] when only one of client_id/client_secret is
       #   given, or a credential is combined with a raw pair
       def initialize(issuer:, credential: nil, client_id: nil, client_secret: nil,
-                     http_client: HTTP::NetHTTPClient.new, timeout: nil)
+                     http_client: HTTP::NetHTTPClient.new, timeout: nil,
+                     discovery_ttl: TokenRequests::DEFAULT_DISCOVERY_TTL, clock: -> { Time.now })
         initialize_token_client(issuer: issuer, credential: credential, client_id: client_id,
-                                client_secret: client_secret, http_client: http_client, timeout: timeout)
+                                client_secret: client_secret, http_client: http_client, timeout: timeout,
+                                discovery_ttl: discovery_ttl, clock: clock)
       end
 
       # Request a token for the client itself.

data/lib/keycardai/oauth/http.rb

@@ -27,7 +27,41 @@ module Keycardai
       end
 
       # Default transport backed by Net::HTTP. TLS is used for https URLs.
+      #
+      # Sessions are kept open and reused per instance, per thread, per
+      # (host, port, scheme). A thread only ever touches its own sessions, so
+      # the request path takes no lock; a small mutex guards only the registry
+      # of per-thread session maps, and dead threads are swept from it whenever
+      # it is touched. There is no transparent retry: a keepalive connection
+      # the server dropped while idle surfaces as NetworkError on the next
+      # request, the same as any other failure.
+      #
+      # Call {#close} when no requests are in flight to finish every session.
+      # An instance that is never closed, such as the throwaway client built by
+      # module-level function defaults, keeps its sessions until it is garbage
+      # collected, which closes the underlying sockets.
       class NetHTTPClient
+        DEFAULT_OPEN_TIMEOUT = Net::HTTP.new("localhost").open_timeout
+        DEFAULT_READ_TIMEOUT = Net::HTTP.new("localhost").read_timeout
+        private_constant :DEFAULT_OPEN_TIMEOUT, :DEFAULT_READ_TIMEOUT
+
+        def initialize
+          @registry = {}
+          @registry_mutex = Mutex.new
+        end
+
+        # Finish every open session and clear the registry. The client stays
+        # usable; the next request opens fresh sessions. Call only when no
+        # requests are in flight on any thread.
+        #
+        # @return [void]
+        def close
+          maps = @registry_mutex.synchronize do
+            @registry.values.tap { @registry.clear }
+          end
+          maps.each { |sessions| sessions.each_value { |http| finish(http) } }
+        end
+
         # @param url [String]
         # @param headers [Hash{String => String}]
         # @param timeout [Numeric, nil] open/read timeout in seconds
@@ -72,17 +106,53 @@ module Keycardai
         private
 
         def perform(uri, request, timeout)
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = uri.scheme == "https"
-          if timeout
-            http.open_timeout = timeout
-            http.read_timeout = timeout
-          end
+          http = session_for(uri)
+          # Timeouts are per request; a request without one gets Net::HTTP's
+          # defaults back rather than the previous request's values.
+          http.open_timeout = timeout || DEFAULT_OPEN_TIMEOUT
+          http.read_timeout = timeout || DEFAULT_READ_TIMEOUT
+          http.start unless http.started?
           response = http.request(request)
           Response.new(status: response.code.to_i, headers: response.to_hash, body: response.body.to_s)
         rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError, EOFError => e
           raise NetworkError, "request to #{uri.host} failed: #{e.class}"
         end
+
+        def session_for(uri)
+          sessions = sessions_for_current_thread
+          key = [uri.host, uri.port, uri.scheme]
+          http = sessions[key]
+          return http if http&.started?
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          sessions[key] = http
+        end
+
+        # A thread's own map is read without the mutex once it exists; the mutex
+        # is taken only to register a new thread or to close.
+        def sessions_for_current_thread
+          @registry[Thread.current] || @registry_mutex.synchronize do
+            sweep_dead_threads
+            @registry[Thread.current] ||= {}
+          end
+        end
+
+        # Caller holds @registry_mutex.
+        def sweep_dead_threads
+          @registry.delete_if do |thread, sessions|
+            next false if thread.alive?
+
+            sessions.each_value { |http| finish(http) }
+            true
+          end
+        end
+
+        def finish(http)
+          http.finish if http.started?
+        rescue IOError
+          nil
+        end
       end
     end
   end

data/lib/keycardai/oauth/token_exchange_client.rb

@@ -9,7 +9,8 @@ module Keycardai
     # authentication.
     #
     # The token endpoint is discovered from the issuer on first use and
-    # cached. Requests do not retry transparently.
+    # cached for discovery_ttl; a failed discovery is not cached. Requests do
+    # not retry transparently.
     class TokenExchangeClient
       include TokenRequests
 
@@ -21,12 +22,16 @@ module Keycardai
       #   provide both or neither
       # @param http_client [#get, #post_form] pluggable transport
       # @param timeout [Numeric, nil] request timeout in seconds
+      # @param discovery_ttl [Numeric] token-endpoint cache lifetime in seconds
+      # @param clock [#call] returns the current Time; override in tests
       # @raise [ConfigurationError] when only one of client_id/client_secret is
       #   given, or a credential is combined with a raw pair
       def initialize(issuer:, credential: nil, client_id: nil, client_secret: nil,
-                     http_client: HTTP::NetHTTPClient.new, timeout: nil)
+                     http_client: HTTP::NetHTTPClient.new, timeout: nil,
+                     discovery_ttl: TokenRequests::DEFAULT_DISCOVERY_TTL, clock: -> { Time.now })
         initialize_token_client(issuer: issuer, credential: credential, client_id: client_id,
-                                client_secret: client_secret, http_client: http_client, timeout: timeout)
+                                client_secret: client_secret, http_client: http_client, timeout: timeout,
+                                discovery_ttl: discovery_ttl, clock: clock)
       end
 
       # Exchange a subject token (RFC 8693).

data/lib/keycardai/oauth/token_requests.rb

@@ -8,6 +8,10 @@ module Keycardai
     # endpoint discovery with caching, shared-secret (HTTP Basic) client
     # authentication, and RFC 6749 §5.2 error parsing. Not public API.
     module TokenRequests
+      # Default lifetime of a discovered token endpoint, in seconds; the same
+      # knob and default as the JWKS keyring's jwks_uri cache.
+      DEFAULT_DISCOVERY_TTL = 3600
+
       # Parse a token-endpoint response: a TokenResponse on 2xx, a raised
       # typed error otherwise.
       #
@@ -52,13 +56,16 @@ module Keycardai
 
       private
 
-      def initialize_token_client(issuer:, credential:, client_id:, client_secret:, http_client:, timeout:)
+      def initialize_token_client(issuer:, credential:, client_id:, client_secret:, http_client:, timeout:,
+                                  discovery_ttl: DEFAULT_DISCOVERY_TTL, clock: -> { Time.now })
         validate_client_auth(credential, client_id, client_secret)
 
         @issuer = issuer
         @credential = credential || (client_id ? ClientSecret.new(client_id, client_secret) : nil)
         @http_client = http_client
         @timeout = timeout
+        @discovery_ttl = discovery_ttl
+        @clock = clock
         @token_endpoints = {}
         @token_endpoint_mutex = Mutex.new
       end
@@ -72,19 +79,33 @@ module Keycardai
         raise ConfigurationError, "client_id and client_secret must be provided together"
       end
 
-      # Discover a zone's token endpoint once and cache it, keyed by issuer
-      # so multi-zone clients never reuse another zone's endpoint.
+      # Discover a zone's token endpoint and cache it for discovery_ttl, keyed
+      # by issuer so multi-zone clients never reuse another zone's endpoint.
+      # Only a success is recorded: a failed discovery raises to its caller and
+      # the next call discovers again. The mutex serializes cold-cache callers
+      # so concurrent first calls perform a single fetch; an interrupted caller
+      # releases it and leaves nothing behind for the others.
       def token_endpoint(issuer = @issuer)
         @token_endpoint_mutex.synchronize do
-          @token_endpoints[issuer] ||= begin
-            metadata = OAuth.fetch_authorization_server_metadata(issuer, http_client: @http_client,
-                                                                         timeout: @timeout)
-            metadata.token_endpoint ||
-              raise(ProtocolError.new("metadata for #{issuer} has no token_endpoint", code: "invalid_metadata"))
-          end
+          fresh_token_endpoint(issuer) || discover_token_endpoint(issuer)
         end
       end
 
+      def fresh_token_endpoint(issuer)
+        entry = @token_endpoints[issuer]
+        return nil unless entry
+
+        entry[:endpoint] if @clock.call - entry[:fetched_at] <= @discovery_ttl
+      end
+
+      def discover_token_endpoint(issuer)
+        metadata = OAuth.fetch_authorization_server_metadata(issuer, http_client: @http_client, timeout: @timeout)
+        endpoint = metadata.token_endpoint ||
+                   raise(ProtocolError.new("metadata for #{issuer} has no token_endpoint", code: "invalid_metadata"))
+        @token_endpoints[issuer] = { endpoint: endpoint, fetched_at: @clock.call }
+        endpoint
+      end
+
       def post_token_request(params, issuer: @issuer)
         headers = { "Accept" => "application/json" }
         authorization = @credential&.authorization_header(issuer: issuer)

data/lib/keycardai/oauth/version.rb

@@ -2,6 +2,6 @@
 
 module Keycardai
   module OAuth
-    VERSION = "0.3.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycardai-oauth
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Keycard