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::IO::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   do_initialize(options)
148   freeze
149 end

Public Instance methods

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