httpx 1.7.8 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b725c719f0e33c27285f1f228dc9c9b19869d65f43d75c9e7b7f95dc8f262278
-  data.tar.gz: 92efa77ade2bae77b3d983a08038305a557953653f5e37236254b12060b0a494
+  metadata.gz: 74104ce6c4d05053e2a005974de5f0cd66346a1cb4558b7c0887d3a2d691d226
+  data.tar.gz: ca0ce3e30f509d44e4c0daac30a0b5d9949c118c19a715561c276f1debaf5dbf
 SHA512:
-  metadata.gz: 2c52b06329f4d13d95242ec6043cf615e077a6dcdef6ad3cfe06d8893eb27555df4d5cdbcd95b621f9d43b4c40281becfbdb4005a074ea34463ca6e951537363
-  data.tar.gz: 4060403c67050b2d9603ec801330d0e32d24c86bf10094ce396e646ab2649870981df0eb66f042a5da1835ba349ef69024148458b6fa3e23657ae2c1a8bc7cfc
+  metadata.gz: 0de3c6baf56c86272cc45bdc06e1187655e759ddf329414d71fcbf4603c9d0e03791641e05f5c07ef84cd578a3bba1a855fde77b5b0f1f2e11df1cf60ea0815a
+  data.tar.gz: a276c6ed937c8d04103382d517d56d9df805886f23b05a38f6e654fcd6935e17407101e1eedc2b6605b4f347a37262116024a61633ebdd660131b06fc1f3fde9

data/doc/release_notes/1_8_0.md

@@ -0,0 +1,100 @@
+# 1.8.0
+
+## Features
+
+### New plugins
+
+#### `:server_sent_events` plugin
+
+The `:server_sent_events` plugin provides a convenience API to deal with `text/event-stream` requests, on top of the `:stream` plugin.
+
+```ruby
+session = HTTPX.plugin(:server_sent_events)
+
+sse_response = session.get("https://example.com/event-stream", event_stream: true)
+
+sse_response.each_message do |message|
+  puts message.id
+  puts message.event
+  puts message.data
+end
+```
+
+You can read more about it in https://gitlab.com/os85/httpx/wikis/Server-Sent-Events .
+
+#### `:cache` plugin
+
+The `:cache` plugin allows caching responses. It exposes some options to determine some of its functionality, i.e. whether a request can use a cached response, whether a response can be cached, whether a cached response is still valid, etc.
+
+This functionality was extracted from the `:response_cache` plugin, which now uses it under the hood.
+
+You can read more about it in https://gitlab.com/os85/httpx/wikis/Cache .
+
+#### `:ntlm_v2_auth` plugin
+
+The `:ntlm_v2_auth` plugin is now available. It implements the most recent version of the NTLM authentication scheme supported by Microsoft products.
+
+You can read more about it in https://gitlab.com/os85/httpx/wikis/Auth#ntlm-v2-auth .
+
+### New timeouts
+
+#### `:total_request_timeout`
+
+You can use the `:total_request_timeout` to time the time it takes a request to get its final response. This includes when your requests follows redirects (via the `:follow_redirects` plugin) or is retried multiple times (via the `:retries´ plugin).
+
+#### `:ping_timeout`
+
+Defines the number of seconds a connection waits to receive a ping response when probing for a connection for liveness.
+
+Defaults to 2 seconds.
+
+### `:ssrf_filter` plugin new options
+
+#### `:extra_unsafe_ranges`
+
+A list of extra unsafe IPs or IP ranges to the default deny list.
+
+#### `:safe_private_ranges`
+
+A list of IPs or IP ranges which are allowed and would otherwise be denied.
+
+### `:auth` plugin new option
+
+#### `:reset_auth_header_expires_in/at`
+
+The `:reset_auth_header_expires_in` and `:reset_auth_header_expires_at`  options enable discarding an authorization token an X number of seconds after it has been generated, or at a particuar point in time, respectively. This is useful when the token is dynamically generated, so that you can preemptively renegotiate a new one.
+
+The `:oauth` plugin makes use of these fields, alongside the `expires_in` claim from token responses, to refresh the token as soon as the it expires.
+
+### `:max_response_body_size`
+
+Can be set to the maximum number of bytes a response may have, after which it'll return an `HTTPX::ErrorResponse`. The limit is enforced based on the `content-length` header and as bytes are received.
+
+### `:max_response_headers`
+
+Can be set to the maximum number of headers a response may have.
+
+### `:max_response_header_value_size`
+
+Can be set to the maximum number of bytes a header value may have. In cases where a header field may be spread across multiple entries (ex. `"cookie"`), the limit is enforced on the aggregate byte size.
+
+### resolver file cache
+
+By specifying `:file` as the resolver `:cache` option, the DNS entries will be cached in a known location in your file system. This will allow sharing entries across processes within the same machine to reduce overall DNS traffic. You can use it via:
+
+```ruby
+session = HTTPX.with(resolver_options: { cache: :file })
+session.get("https://example.com")
+```
+
+## Improvements
+
+* `http-2` minimum version is now 1.2.0, which brings performance benefits around frame parsing and other common operations.
+
+## Bugfixes
+
+* several fixes to make `httpx` usable inside a fiber scheduler in ruby 4.
+* `:proxy` plugin: unescape user/password from proxy options before reusing it (to avoid using percent-encoded values when p.ex. generating base64-encoding for basic auth).
+* `:retries` plugin: fixed the polynomial and exponential backoff `:retry_after` strategies calculation.
+* `:tracing` plugin: fixing span start time set up when request is sent to a closed connection, or when a long-lived connection will be probed for liveness.
+* datadog adapter: fixed integration with the `datadog` gem v2.34 or higher.

data/lib/httpx/adapters/datadog.rb

@@ -15,8 +15,10 @@ module Datadog::Tracing
 
       TAG_BASE_SERVICE = if Gem::Version.new(DATADOG_VERSION::STRING) < Gem::Version.new("1.15.0")
         "_dd.base_service"
-      else
+      elsif Gem::Version.new(DATADOG_VERSION::STRING) < Gem::Version.new("2.34.0")
         Datadog::Tracing::Contrib::Ext::Metadata::TAG_BASE_SERVICE
+      else
+        Datadog::Tracing::Metadata::Ext::TAG_BASE_SERVICE
       end
       TAG_PEER_HOSTNAME = Datadog::Tracing::Metadata::Ext::TAG_PEER_HOSTNAME
       TAG_PEER_SERVICE = Datadog::Tracing::Metadata::Ext::TAG_PEER_SERVICE

data/lib/httpx/connection/http1.rb

@@ -14,6 +14,7 @@ module HTTPX
       "www-authenticate" => "WWW-Authenticate",
       "http2-settings" => "HTTP2-Settings",
       "content-md5" => "Content-MD5",
+      "last-event-id" => "Last-Event-ID",
     }.freeze
     attr_reader :pending, :requests
 
@@ -23,7 +24,7 @@ module HTTPX
       @options = options
       @max_concurrent_requests = @options.max_concurrent_requests || MAX_REQUESTS
       @max_requests = @options.max_requests
-      @parser = Parser::HTTP1.new(self)
+      @parser = Parser::HTTP1.new(self, options.max_response_headers, options.max_response_header_value_size)
       @buffer = buffer
       @version = [1, 1]
       @pending = []
@@ -47,6 +48,10 @@ module HTTPX
     end
 
     def reset
+      if @ping_timer
+        @ping_timer.cancel
+        @ping_timer = nil
+      end
       @max_requests = @options.max_requests || MAX_REQUESTS
       @parser.reset!
       @handshake_completed = false
@@ -132,6 +137,10 @@ module HTTPX
       request.log(color: :yellow) { "-> HEADLINE: #{response.status} HTTP/#{@parser.http_version.join(".")}" }
       request.log(color: :yellow) { response.headers.each.map { |f, v| "-> HEADER: #{f}: #{log_redact_headers(v)}" }.join("\n") }
 
+      if response.content_length && response.content_length > request.options.max_response_body_size
+        raise HTTPX::Error, "maximum response body size exceeded"
+      end
+
       request.response = response
       on_complete if response.finished?
     end

data/lib/httpx/connection/http2.rb

@@ -118,7 +118,7 @@ module HTTPX
         return false
       end
       unless (stream = @streams[request])
-        stream = @connection.new_stream
+        stream = @connection.new_stream(**request.http2_stream_options)
         handle_stream(stream, request)
         @streams[request] = stream
         @max_requests -= 1
@@ -128,6 +128,8 @@ module HTTPX
     rescue ::HTTP2::Error::StreamLimitExceeded
       @pending.unshift(request)
       false
+    rescue StandardError => e
+      emit(:error, request, e)
     end
 
     def consume
@@ -312,7 +314,21 @@ module HTTPX
       end
       _, status = h.shift
       headers = request.options.headers_class.new(h)
+
+      raise HTTPX::Error, "maximum number of response headers exceeded" if h.size > @options.max_response_headers
+
+      if (max_header_value_size = @options.max_response_header_value_size)
+        headers.each do |_, v| # rubocop:disable Style/HashEachMethods
+          raise HTTPX::Error, "maximum header value size exceeded" if v.size > max_header_value_size
+        end
+      end
+
       response = request.options.response_class.new(request, status, "2.0", headers)
+
+      if response.content_length && response.content_length > request.options.max_response_body_size
+        raise HTTPX::Error.new, "maximum response body size exceeded"
+      end
+
       request.response = response
       @streams[request] = stream
 
@@ -428,11 +444,28 @@ module HTTPX
     end
 
     def frame_with_extra_info(frame)
+      flags_bits = frame.fetch(:flags, 0)
       case frame[:type]
       when :data
-        frame.merge(payload: frame[:payload].bytesize)
-      when :headers, :ping
-        frame.merge(payload: log_redact_headers(frame[:payload]))
+        flags = [] #: Array[Symbol]
+        flags << :end_stream if flags_bits.anybits?(0b0001)
+        flags << :padded if flags_bits.anybits?(0b1000)
+        frame.merge(payload: frame[:payload].bytesize, flags: flags)
+      when :push_promise, :headers
+        flags = [] #: Array[Symbol]
+        flags << :end_stream if flags_bits.anybits?(0b0001)
+        flags << :priority if flags_bits.anybits?(0b0010)
+        flags << :end_headers if flags_bits.anybits?(0b0100)
+        flags << :padded if flags_bits.anybits?(0b1000)
+        frame.merge(payload: log_redact_headers(frame[:payload]), flags: flags)
+      when :ping
+        flags = [] #: Array[Symbol]
+        flags << :ack if flags_bits.anybits?(0b0001)
+        frame.merge(payload: log_redact_headers(frame[:payload]), flags: flags)
+      when :settings
+        flags = [] #: Array[Symbol]
+        flags << :ack if flags_bits.anybits?(0b0001)
+        frame.merge(flags: flags)
       when :window_update
         connection_or_stream = if (id = frame[:stream]).zero?
           @connection

data/lib/httpx/connection.rb

@@ -47,8 +47,8 @@ module HTTPX
     def initialize(uri, options)
       @current_session = @current_selector = @max_concurrent_requests =
                            @parser = @sibling = @coalesced_connection = @altsvc_connection =
-                                                  @family = @io = @ssl_session = @timeout =
-                                                                    @connected_at = @response_received_at = nil
+                                                  @ping_timer = @family = @io = @ssl_session =
+                                                                            @timeout = @connected_at = @response_received_at = nil
 
       @exhausted = @cloned = @main_sibling = false
 
@@ -222,10 +222,27 @@ module HTTPX
 
         consume
       when :closed
-        return
+        return if @pending.empty?
+
+        # there are pending requests to send, restart the state machine.
+        idling
+
+        # @fiber-switch-guard
+        # fiber may have switch after ensuring that @io is closed.
+        return unless @state == :idle
+
+        call
       when :closing
         consume
         transition(:closed)
+
+        # @fiber-switch-guard
+        # fiber may have switch while closing @io.
+        return if @state == :closed &&
+                  # only remain here if there are pending requests.
+                  @pending.empty?
+
+        call
       when :open
         consume
       end
@@ -251,7 +268,12 @@ module HTTPX
       case @state
       when :idle
         purge_after_closed
-        disconnect
+
+        # @fiber-switch-guard
+        if @io.can_disconnect? && @pending.empty?
+          disconnect
+          return
+        end
       when :closed
         @connected_at = nil
       end
@@ -319,7 +341,7 @@ module HTTPX
           @pending << request
           transition(:active) if @state == :inactive
           request.ping!
-          ping
+          ping(request)
           return
         end
 
@@ -341,6 +363,9 @@ module HTTPX
 
     def idling
       purge_after_closed
+
+      return unless @state == :closed
+
       @write_buffer.clear
       transition(:idle)
       return unless @parser
@@ -421,6 +446,8 @@ module HTTPX
         if @timeout
           @timeout -= error.timeout
           return unless @timeout <= 0
+
+          @timeout = nil
         end
 
         error = error.to_connection_error if connecting?
@@ -660,7 +687,12 @@ module HTTPX
         @exhausted = true
         parser.close
 
+        # @fiber-switch-guard
+        # fiber may have switched while closing @io, check whether still in the exhausted loop.
+        next unless @exhausted
+
         idling
+
         @exhausted = false
       end
       parser.on(:origin) do |origin|
@@ -676,6 +708,9 @@ module HTTPX
         enqueue_pending_requests_from_parser(parser)
 
         reset
+
+        next unless @state == :closed
+
         # :reset event only fired in http/1.1, so this guarantees
         # that the connection will be closed here.
         idling unless @pending.empty?
@@ -766,6 +801,9 @@ module HTTPX
         return unless @write_buffer.empty?
 
         purge_after_closed
+
+        # @fiber-switch-guard
+        return unless @state == :closing && (@io.nil? || @io.can_disconnect?)
       when :already_open
         nextstate = :open
         # the first check for given io readiness must still use a timeout.
@@ -833,7 +871,15 @@ module HTTPX
     end
 
     def purge_after_closed
-      @io.close if @io
+      if @io
+        @io.close
+
+        # @fiber-switch-guard
+        # due to fiber scheduler, multiple fibers may be listening on the same connection
+        # and moving the state machine forward; in such cases, when the control flow reaches
+        # this line, the io object may not be closed anymore.
+        return unless @io&.can_disconnect?
+      end
       @read_buffer.clear
       @timeout = nil
     end
@@ -906,14 +952,24 @@ module HTTPX
       end
     end
 
-    def ping
+    def ping(_request)
       return if parser.waiting_for_ping?
 
       parser.ping
+
+      ping_timeout = @options.timeout[:ping_timeout]
+
+      @ping_timer = @current_selector.after(ping_timeout) do
+        error = PingTimeoutError.new(ping_timeout, "Timed out after #{ping_timeout} seconds")
+        on_error(error)
+      end
+
       call
     end
 
     def pong
+      @ping_timer.cancel
+      @ping_timer = nil
       @response_received_at = Utils.now
       @no_more_requests_counter = 0
       send_pending
@@ -964,6 +1020,7 @@ module HTTPX
       set_request_write_timeout(request)
       set_request_read_timeout(request)
       set_request_request_timeout(request)
+      set_request_total_request_timeout(request)
     end
 
     def set_request_read_timeout(request)
@@ -1016,6 +1073,18 @@ module HTTPX
       request.handle_error(error)
     end
 
+    def set_request_total_request_timeout(request)
+      return if request.started?
+
+      total_request_timeout = request.total_request_timeout
+
+      return if total_request_timeout.nil? || total_request_timeout.infinite?
+
+      set_request_timeout(:total_request_timeout, request, total_request_timeout, :headers, :complete) do
+        read_timeout_callback(request, total_request_timeout, TotalRequestTimeoutError)
+      end
+    end
+
     def set_request_timeout(label, request, timeout, start_event, finish_events, &callback)
       request.set_timeout_callback(start_event) do
         unless (selector = @current_selector)

data/lib/httpx/errors.rb

@@ -62,15 +62,22 @@ module HTTPX
   # Error raised when there was a timeout while sending a request from the server.
   class WriteTimeoutError < RequestTimeoutError; end
 
+  # Error raised when a response couldn't be received for a request after multiple interactions.
+  # This error should not be retriable.
+  class TotalRequestTimeoutError < RequestTimeoutError; end
+
   # Error raised when there was a timeout while waiting for the HTTP/2 settings frame from the server.
   class SettingsTimeoutError < TimeoutError; end
 
   # Error raised when there was a timeout while resolving a domain to an IP.
   class ResolveTimeoutError < TimeoutError; end
 
-  # Error raise when there was a timeout waiting for readiness of the socket the request is related to.
+  # Error raised when there was a timeout waiting for readiness of the socket the request is related to.
   class OperationTimeoutError < TimeoutError; end
 
+  # Error raised when a connection liveness probe (aka ping) times out.
+  class PingTimeoutError < TimeoutError; end
+
   # Error raised when there was an error while resolving a domain to an IP.
   class ResolveError < Error; end
 

data/lib/httpx/io/tcp.rb

@@ -190,10 +190,20 @@ module HTTPX
         log { "error closing socket" }
         log { e.full_message(highlight: false) }
       ensure
-        transition(:closed)
+        # @fiber-switch-guard
+        # ensure that all :closed IOs don't leave dangling sockets
+        # behind. This may happen in a fiber scheduler scenario where
+        # connection is reused across fibers.
+        transition(:closed) if @io.closed?
       end
     end
 
+    # signals that the connection that contains this IO can be checked back into the pool.
+    # that includes sockets opened outside of the scope of the session, or closed IOs.
+    def can_disconnect?
+      @keep_open || @state == :closed
+    end
+
     def connected?
       @state == :connected
     end

data/lib/httpx/options.rb

@@ -8,12 +8,12 @@ module HTTPX
     WINDOW_SIZE = 1 << 14 # 16K
     MAX_BODY_THRESHOLD_SIZE = (1 << 10) * 112 # 112K
     KEEP_ALIVE_TIMEOUT = 20
+    PING_TIMEOUT = 2
     SETTINGS_TIMEOUT = 10
     CLOSE_HANDSHAKE_TIMEOUT = 10
     CONNECT_TIMEOUT = READ_TIMEOUT = WRITE_TIMEOUT = 60
-    REQUEST_TIMEOUT = OPERATION_TIMEOUT = nil
+    REQUEST_TIMEOUT = OPERATION_TIMEOUT = TOTAL_REQUEST_TIMEOUT = nil
     RESOLVER_TYPES = %i[memory file].freeze
-
     # default value used for "user-agent" header, when not overridden.
     USER_AGENT = "httpx.rb/#{VERSION}".freeze # rubocop:disable Style/RedundantFreeze
 
@@ -79,9 +79,15 @@ module HTTPX
     # :decompress_response_body :: whether to auto-decompress response body (defaults to <tt>true</tt>).
     # :compress_request_body :: whether to auto-decompress response body (defaults to <tt>true</tt>)
     # :timeout :: hash of timeout configurations (supports <tt>:connect_timeout</tt>, <tt>:settings_timeout</tt>,
-    #             <tt>:operation_timeout</tt>, <tt>:keep_alive_timeout</tt>,  <tt>:read_timeout</tt>,  <tt>:write_timeout</tt>
-    #             and <tt>:request_timeout</tt>
+    #             <tt>:operation_timeout</tt>, <tt>:keep_alive_timeout</tt>, <tt>:read_timeout</tt>,  <tt>:write_timeout</tt>,
+    #             <tt>:request_timeout</tt>, <tt>:total_request_timeout</tt> and <tt>:ping_timeout</tt>,
     # :headers :: hash of HTTP headers (ex: <tt>{ "x-custom-foo" => "bar" }</tt>)
+    # :max_response_body_size :: maximum size (in bytes) that the response body can consume (no threshold by default), after which an
+    #                            error is raised.
+    # :max_response_headers :: maximum number of header fields that a response can receive, after which an error is raised.
+    # :max_response_header_value_size :: maximum size (in bytes) a header value can have (no threshold by default).
+    #                                    for cases where the value is broken into multiple header fields (such as "cookie" or "set-cookie"),
+    #                                    this is the total aggregated size.
     # :window_size :: number of bytes to read from a socket
     # :buffer_size :: internal read and write buffer size in bytes
     # :body_threshold_size :: maximum size in bytes of response payload that is buffered in memory.
@@ -387,6 +393,7 @@ module HTTPX
     # number options
     %i[
       max_concurrent_requests max_requests window_size buffer_size
+      max_response_body_size max_response_headers max_response_header_value_size
       body_threshold_size debug_level
     ].each do |option|
       class_eval(<<-OUT, __FILE__, __LINE__ + 1)
@@ -553,15 +560,20 @@ module HTTPX
       :supported_compression_formats => %w[gzip deflate],
       :decompress_response_body => true,
       :compress_request_body => true,
+      :max_response_headers => 1000,
+      :max_response_header_value_size => nil,
+      :max_response_body_size => Float::INFINITY,
       :timeout => {
         connect_timeout: CONNECT_TIMEOUT,
         settings_timeout: SETTINGS_TIMEOUT,
         close_handshake_timeout: CLOSE_HANDSHAKE_TIMEOUT,
         operation_timeout: OPERATION_TIMEOUT,
         keep_alive_timeout: KEEP_ALIVE_TIMEOUT,
+        ping_timeout: PING_TIMEOUT,
         read_timeout: READ_TIMEOUT,
         write_timeout: WRITE_TIMEOUT,
         request_timeout: REQUEST_TIMEOUT,
+        total_request_timeout: TOTAL_REQUEST_TIMEOUT,
       }.freeze,
       :headers_class => Class.new(Headers, &SET_TEMPORARY_NAME),
       :headers => EMPTY_HASH,

data/lib/httpx/parser/http1.rb

@@ -9,11 +9,13 @@ module HTTPX
 
       attr_reader :status_code, :http_version, :headers
 
-      def initialize(observer)
+      def initialize(observer, max_headers, max_header_value_size)
         @observer = observer
         @state = :idle
         @buffer = "".b
         @headers = {}
+        @max_headers = max_headers
+        @max_header_value_size = max_header_value_size
         @content_length = nil
         @_has_trailers = @upgrade = false
       end
@@ -117,7 +119,11 @@ module HTTPX
           value.strip!
           raise Error, "wrong header format" if value.nil?
 
-          (headers[key.downcase] ||= []) << value
+          values = (headers[key.downcase] ||= []) << value
+
+          raise Error, "maximum header value size exceeded" if @max_header_value_size && (values.sum(&:size) > @max_header_value_size)
+
+          raise Error, "maximum number of response headers exceeded" if headers.size > @max_headers
         end
       end
 

data/lib/httpx/plugins/auth.rb

@@ -20,6 +20,9 @@ module HTTPX
       #
       # :auth_header_value :: the token to use as a string, or a callable which returns a string when called.
       # :auth_header_type :: the authentication type to use in the "authorization" header value (i.e. "Bearer", "Digest"...)
+      # :auth_header_expires_at :: timestamp at which the auth header will be discarded. should be a callable (like a proc)
+      #                            receiving the request as an argument, and should return either a Time object, or an integer (UNIX time).
+      # :auth_header_expires_in :: time (in seconds) since the first use of an auth header after which that header will be discarded.
       # :generate_auth_value_on_retry :: callable which returns whether the request should regenerate the auth_header_value
       #                                  when the request is retried (this option will only work if the session also loads the
       #                                  <tt>:retries</tt> plugin).
@@ -32,6 +35,22 @@ module HTTPX
           value
         end
 
+        def option_auth_header_expires_at(value)
+          unless value.respond_to?(:call)
+            value = Float(value)
+            raise TypeError, "`:auth_header_expires_at` must be positive" unless value.positive?
+          end
+
+          value
+        end
+
+        def option_auth_header_expires_in(value)
+          value = Float(value)
+          raise TypeError, "`:auth_header_expires_in` must be positive" unless value.positive?
+
+          value
+        end
+
         def option_generate_auth_value_on_retry(value)
           raise TypeError, "`:generate_auth_value_on_retry` must be a callable" unless value.respond_to?(:call)
 
@@ -43,7 +62,7 @@ module HTTPX
         def initialize(*)
           super
 
-          @auth_header_value = nil
+          @auth_header_value = @auth_header_expires_at = nil
           @auth_header_value_mtx = Thread::Mutex.new
           @skip_auth_header_value = false
         end
@@ -65,7 +84,7 @@ module HTTPX
 
         def reset_auth_header_value!
           @auth_header_value_mtx.synchronize do
-            @auth_header_value = nil
+            @auth_header_value = @auth_header_expires_at = nil
           end
         end
 
@@ -75,7 +94,12 @@ module HTTPX
           return super if @skip_auth_header_value || request.authorized?
 
           auth_header_value = @auth_header_value_mtx.synchronize do
-            @auth_header_value ||= generate_auth_token
+            try_invalidate_auth_header_value
+
+            @auth_header_value ||= begin
+              set_auth_header_expires_at(request)
+              generate_auth_token
+            end
           end
 
           request.authorize(auth_header_value) if auth_header_value
@@ -83,6 +107,14 @@ module HTTPX
           super
         end
 
+        def try_invalidate_auth_header_value
+          return unless (expires_at = @auth_header_expires_at)
+
+          return if expires_at > Time.now.utc.to_i
+
+          @auth_header_value = @auth_header_expires_at = nil
+        end
+
         def generate_auth_token
           return unless (auth_value = @options.auth_header_value)
 
@@ -91,6 +123,19 @@ module HTTPX
           auth_value
         end
 
+        def set_auth_header_expires_at(request)
+          @auth_header_expires_at = if (expires_in = request.options.auth_header_expires_in)
+            Time.now.to_i + expires_in
+          elsif (expires_at = request.options.auth_header_expires_at)
+            if expires_at.respond_to?(:call)
+              expires_at = expires_at.call(request).to_f
+              raise Error, "`:auth_header_expires_at` must be positive" unless expires_at.positive?
+
+              expires_at
+            end
+          end
+        end
+
         def dynamic_auth_token?(auth_header_value)
           auth_header_value&.respond_to?(:call)
         end
@@ -150,7 +195,10 @@ module HTTPX
             # otherwise, it means that the first request already passed here, so this request should
             # use whatever was generated for it.
             @auth_header_value_mtx.synchronize do
-              @auth_header_value = generate_auth_token if request.auth_token_value == @auth_header_value
+              if request.auth_token_value == @auth_header_value
+                @auth_header_value = generate_auth_token
+                set_auth_header_expires_at(request)
+              end
             end
 
             request.unauthorize!

data/lib/httpx/plugins/{response_cache → cache}/file_store.rb

@@ -3,7 +3,7 @@
 require "pathname"
 
 module HTTPX::Plugins
-  module ResponseCache
+  module Cache
     # Implementation of a file system based cache store.
     #
     # It stores cached responses in a file under a directory pointed by the +dir+