class HTTPX::Options

  1. lib/httpx/options.rb
  2. lib/httpx/transcoder/utils/deflater.rb
  3. show all
Superclass: Object

Contains a set of options which are passed and shared across from session to its requests or responses.

Constants

BUFFER_SIZE = 1 << 14  
CLOSE_HANDSHAKE_TIMEOUT = 10  
CONNECT_TIMEOUT = READ_TIMEOUT = WRITE_TIMEOUT = 60  
DEFAULT_OPTIONS = { :max_requests => Float::INFINITY, :debug => nil, :debug_level => (ENV["HTTPX_DEBUG"] || 1).to_i, :debug_redact => ENV.key?("HTTPX_DEBUG_REDACT"), :ssl => EMPTY_HASH, :http2_settings => { settings_enable_push: 0 }.freeze, :fallback_protocol => "http/1.1", :supported_compression_formats => %w[gzip deflate], :decompress_response_body => true, :compress_request_body => true, :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, read_timeout: READ_TIMEOUT, write_timeout: WRITE_TIMEOUT, request_timeout: REQUEST_TIMEOUT, }, :headers_class => Class.new(Headers, &SET_TEMPORARY_NAME), :headers => {}, :window_size => WINDOW_SIZE, :buffer_size => BUFFER_SIZE, :body_threshold_size => MAX_BODY_THRESHOLD_SIZE, :request_class => Class.new(Request, &SET_TEMPORARY_NAME), :response_class => Class.new(Response, &SET_TEMPORARY_NAME), :request_body_class => Class.new(Request::Body, &SET_TEMPORARY_NAME), :response_body_class => Class.new(Response::Body, &SET_TEMPORARY_NAME), :pool_class => Class.new(Pool, &SET_TEMPORARY_NAME), :connection_class => Class.new(Connection, &SET_TEMPORARY_NAME), :options_class => Class.new(self, &SET_TEMPORARY_NAME), :transport => nil, :addresses => nil, :persistent => false, :resolver_class => (ENV["HTTPX_RESOLVER"] || :native).to_sym, :resolver_options => { cache: true }.freeze, :pool_options => EMPTY_HASH, :ip_families => ip_address_families, :close_on_fork => false, }.freeze  
KEEP_ALIVE_TIMEOUT = 20  
MAX_BODY_THRESHOLD_SIZE = (1 << 10) * 112  
REQUEST_BODY_IVARS = %i[@headers].freeze  
REQUEST_TIMEOUT = OPERATION_TIMEOUT = nil  
SETTINGS_TIMEOUT = 10  
SET_TEMPORARY_NAME = ->(mod, pl = nil) do if mod.respond_to?(:set_temporary_name) # ruby 3.4 only name = mod.name || "#{mod.superclass.name}(plugin)" name = "#{name}/#{pl}" if pl mod.set_temporary_name(name) end end  
WINDOW_SIZE = 1 << 14  

Public Class methods

method_added(meth)
[show source] 
   # File lib/httpx/options.rb
90 def method_added(meth)
91   super
92 
93   return unless meth =~ /^option_(.+)$/
94 
95   optname = Regexp.last_match(1).to_sym
96 
97   attr_reader(optname)
98 end
new(options = {})
[show source] 
   # File lib/httpx/options.rb
82 def new(options = {})
83   # let enhanced options go through
84   return options if self == Options && options.class < self
85   return options if options.is_a?(self)
86 
87   super
88 end
new(options = {})

creates a new options instance from a given hash, which optionally define the following:

:debug

an object which log messages are written to (must respond to <<)

:debug_level

the log level of messages (can be 1, 2, or 3).

:debug_redact

whether header/body payload should be redacted (defaults to false).

:ssl

a hash of options which can be set as params of OpenSSL::SSL::SSLContext (see HTTPX::SSL)

:http2_settings

a hash of options to be passed to a HTTP2::Connection (ex: { max_concurrent_streams: 2 })

:fallback_protocol

version of HTTP protocol to use by default in the absence of protocol negotiation like ALPN (defaults to "http/1.1")

:supported_compression_formats

list of compressions supported by the transcoder layer (defaults to %w[gzip deflate]).

:decompress_response_body

whether to auto-decompress response body (defaults to true).

:compress_request_body

whether to auto-decompress response body (defaults to true)

:timeout

hash of timeout configurations (supports :connect_timeout, :settings_timeout, :operation_timeout, :keep_alive_timeout, :read_timeout, :write_timeout and :request_timeout

:headers

hash of HTTP headers (ex: { "x-custom-foo" => "bar" })

: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.

:request_class

class used to instantiate a request

:response_class

class used to instantiate a response

:headers_class

class used to instantiate headers

:request_body_class

class used to instantiate a request body

:response_body_class

class used to instantiate a response body

:connection_class

class used to instantiate connections

:pool_class

class used to instantiate the session connection pool

:options_class

class used to instantiate options

:transport

type of transport to use (set to “unix” for UNIX sockets)

:addresses

bucket of peer addresses (can be a list of IP addresses, a hash of domain to list of adddresses; paths should be used for UNIX sockets instead)

:io

open socket, or domain/ip-to-socket hash, which requests should be sent to

:persistent

whether to persist connections in between requests (defaults to true)

:resolver_class

which resolver to use (defaults to :native, can also be :system<tt> for using getaddrinfo or <tt>:https for DoH resolver, or a custom class)

:resolver_options

hash of options passed to the resolver. Accepted keys depend on the resolver type.

:pool_options

hash of options passed to the connection pool (See Pool#initialize).

:ip_families

which socket families are supported (system-dependent)

:origin

HTTP origin to set on requests with relative path (ex: “api.serv.com”)

:base_path

path to prefix given relative paths with (ex: “/v2”)

:max_concurrent_requests

max number of requests which can be set concurrently

:max_requests

max number of requests which can be made on socket before it reconnects.

:close_on_fork

whether the session automatically closes when the process is fork (defaults to false). it only works if the session is persistent (and ruby 3.1 or higher is used).

This list of options are enhanced with each loaded plugin, see the plugin docs for details.

[show source] 
    # File lib/httpx/options.rb
146 def initialize(options = {})
147   defaults = DEFAULT_OPTIONS.merge(options)
148   defaults.each do |k, v|
149     next if v.nil?
150 
151     option_method_name = :"option_#{k}"
152     raise Error, "unknown option: #{k}" unless respond_to?(option_method_name)
153 
154     value = __send__(option_method_name, v)
155     instance_variable_set(:"@#{k}", value)
156   end
157   freeze
158 end

Public Instance methods

==(other)
[show source] 
    # File lib/httpx/options.rb
252 def ==(other)
253   super || options_equals?(other)
254 end
extend_with_plugin_classes(pl)
[show source] 
    # File lib/httpx/options.rb
314 def extend_with_plugin_classes(pl)
315   if defined?(pl::RequestMethods) || defined?(pl::RequestClassMethods)
316     @request_class = @request_class.dup
317     SET_TEMPORARY_NAME[@request_class, pl]
318     @request_class.__send__(:include, pl::RequestMethods) if defined?(pl::RequestMethods)
319     @request_class.extend(pl::RequestClassMethods) if defined?(pl::RequestClassMethods)
320   end
321   if defined?(pl::ResponseMethods) || defined?(pl::ResponseClassMethods)
322     @response_class = @response_class.dup
323     SET_TEMPORARY_NAME[@response_class, pl]
324     @response_class.__send__(:include, pl::ResponseMethods) if defined?(pl::ResponseMethods)
325     @response_class.extend(pl::ResponseClassMethods) if defined?(pl::ResponseClassMethods)
326   end
327   if defined?(pl::HeadersMethods) || defined?(pl::HeadersClassMethods)
328     @headers_class = @headers_class.dup
329     SET_TEMPORARY_NAME[@headers_class, pl]
330     @headers_class.__send__(:include, pl::HeadersMethods) if defined?(pl::HeadersMethods)
331     @headers_class.extend(pl::HeadersClassMethods) if defined?(pl::HeadersClassMethods)
332   end
333   if defined?(pl::RequestBodyMethods) || defined?(pl::RequestBodyClassMethods)
334     @request_body_class = @request_body_class.dup
335     SET_TEMPORARY_NAME[@request_body_class, pl]
336     @request_body_class.__send__(:include, pl::RequestBodyMethods) if defined?(pl::RequestBodyMethods)
337     @request_body_class.extend(pl::RequestBodyClassMethods) if defined?(pl::RequestBodyClassMethods)
338   end
339   if defined?(pl::ResponseBodyMethods) || defined?(pl::ResponseBodyClassMethods)
340     @response_body_class = @response_body_class.dup
341     SET_TEMPORARY_NAME[@response_body_class, pl]
342     @response_body_class.__send__(:include, pl::ResponseBodyMethods) if defined?(pl::ResponseBodyMethods)
343     @response_body_class.extend(pl::ResponseBodyClassMethods) if defined?(pl::ResponseBodyClassMethods)
344   end
345   if defined?(pl::PoolMethods)
346     @pool_class = @pool_class.dup
347     SET_TEMPORARY_NAME[@pool_class, pl]
348     @pool_class.__send__(:include, pl::PoolMethods)
349   end
350   if defined?(pl::ConnectionMethods)
351     @connection_class = @connection_class.dup
352     SET_TEMPORARY_NAME[@connection_class, pl]
353     @connection_class.__send__(:include, pl::ConnectionMethods)
354   end
355   return unless defined?(pl::OptionsMethods)
356 
357   @options_class = @options_class.dup
358   @options_class.__send__(:include, pl::OptionsMethods)
359 end
freeze()
[show source] 
    # File lib/httpx/options.rb
160 def freeze
161   @origin.freeze
162   @base_path.freeze
163   @timeout.freeze
164   @headers.freeze
165   @addresses.freeze
166   @supported_compression_formats.freeze
167   @ssl.freeze
168   @http2_settings.freeze
169   @pool_options.freeze
170   @resolver_options.freeze
171   @ip_families.freeze
172   super
173 end
merge(other)
[show source] 
    # File lib/httpx/options.rb
271 def merge(other)
272   ivar_map = nil
273   other_ivars = case other
274                 when Options
275                   other.instance_variables
276                 else
277                   other = Hash[other] unless other.is_a?(Hash)
278                   ivar_map = other.keys.to_h { |k| [:"@#{k}", k] }
279                   ivar_map.keys
280   end
281 
282   return self if other_ivars.empty?
283 
284   return self if other_ivars.all? { |ivar| instance_variable_get(ivar) == access_option(other, ivar, ivar_map) }
285 
286   opts = dup
287 
288   other_ivars.each do |ivar|
289     v = access_option(other, ivar, ivar_map)
290 
291     unless v
292       opts.instance_variable_set(ivar, v)
293       next
294     end
295 
296     v = opts.__send__(:"option_#{ivar[1..-1]}", v)
297 
298     orig_v = instance_variable_get(ivar)
299 
300     v = orig_v.merge(v) if orig_v.respond_to?(:merge) && v.respond_to?(:merge)
301 
302     opts.instance_variable_set(ivar, v)
303   end
304 
305   opts
306 end
option_addresses(value)
[show source] 
    # File lib/httpx/options.rb
202 def option_addresses(value)
203   Array(value)
204 end
option_base_path(value)
[show source] 
    # File lib/httpx/options.rb
179 def option_base_path(value)
180   String(value)
181 end
option_headers(value)
[show source] 
    # File lib/httpx/options.rb
183 def option_headers(value)
184   headers_class.new(value)
185 end
option_ip_families(value)
[show source] 
    # File lib/httpx/options.rb
206 def option_ip_families(value)
207   Array(value)
208 end
option_origin(value)
[show source] 
    # File lib/httpx/options.rb
175 def option_origin(value)
176   URI(value)
177 end
option_supported_compression_formats(value)
[show source] 
    # File lib/httpx/options.rb
191 def option_supported_compression_formats(value)
192   Array(value).map(&:to_s)
193 end
option_timeout(value)
[show source] 
    # File lib/httpx/options.rb
187 def option_timeout(value)
188   Hash[value]
189 end
option_transport(value)
[show source] 
    # File lib/httpx/options.rb
195 def option_transport(value)
196   transport = value.to_s
197   raise TypeError, "#{transport} is an unsupported transport type" unless %w[unix].include?(transport)
198 
199   transport
200 end
options_equals?(other, ignore_ivars = REQUEST_BODY_IVARS)
[show source] 
    # File lib/httpx/options.rb
256 def options_equals?(other, ignore_ivars = REQUEST_BODY_IVARS)
257   # headers and other request options do not play a role, as they are
258   # relevant only for the request.
259   ivars = instance_variables - ignore_ivars
260   other_ivars = other.instance_variables - ignore_ivars
261 
262   return false if ivars.size != other_ivars.size
263 
264   return false if ivars.sort != other_ivars.sort
265 
266   ivars.all? do |ivar|
267     instance_variable_get(ivar) == other.instance_variable_get(ivar)
268   end
269 end
to_hash()
[show source] 
    # File lib/httpx/options.rb
308 def to_hash
309   instance_variables.each_with_object({}) do |ivar, hs|
310     hs[ivar[1..-1].to_sym] = instance_variable_get(ivar)
311   end
312 end