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

: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
144 def initialize(options = {})
145   do_initialize(options)
146   freeze
147 end

Public Instance methods

==(other)
[show source] 
    # File lib/httpx/options.rb
246 def ==(other)
247   super || options_equals?(other)
248 end
extend_with_plugin_classes(pl)
[show source] 
    # File lib/httpx/options.rb
307 def extend_with_plugin_classes(pl)
308   if defined?(pl::RequestMethods) || defined?(pl::RequestClassMethods)
309     @request_class = @request_class.dup
310     SET_TEMPORARY_NAME[@request_class, pl]
311     @request_class.__send__(:include, pl::RequestMethods) if defined?(pl::RequestMethods)
312     @request_class.extend(pl::RequestClassMethods) if defined?(pl::RequestClassMethods)
313   end
314   if defined?(pl::ResponseMethods) || defined?(pl::ResponseClassMethods)
315     @response_class = @response_class.dup
316     SET_TEMPORARY_NAME[@response_class, pl]
317     @response_class.__send__(:include, pl::ResponseMethods) if defined?(pl::ResponseMethods)
318     @response_class.extend(pl::ResponseClassMethods) if defined?(pl::ResponseClassMethods)
319   end
320   if defined?(pl::HeadersMethods) || defined?(pl::HeadersClassMethods)
321     @headers_class = @headers_class.dup
322     SET_TEMPORARY_NAME[@headers_class, pl]
323     @headers_class.__send__(:include, pl::HeadersMethods) if defined?(pl::HeadersMethods)
324     @headers_class.extend(pl::HeadersClassMethods) if defined?(pl::HeadersClassMethods)
325   end
326   if defined?(pl::RequestBodyMethods) || defined?(pl::RequestBodyClassMethods)
327     @request_body_class = @request_body_class.dup
328     SET_TEMPORARY_NAME[@request_body_class, pl]
329     @request_body_class.__send__(:include, pl::RequestBodyMethods) if defined?(pl::RequestBodyMethods)
330     @request_body_class.extend(pl::RequestBodyClassMethods) if defined?(pl::RequestBodyClassMethods)
331   end
332   if defined?(pl::ResponseBodyMethods) || defined?(pl::ResponseBodyClassMethods)
333     @response_body_class = @response_body_class.dup
334     SET_TEMPORARY_NAME[@response_body_class, pl]
335     @response_body_class.__send__(:include, pl::ResponseBodyMethods) if defined?(pl::ResponseBodyMethods)
336     @response_body_class.extend(pl::ResponseBodyClassMethods) if defined?(pl::ResponseBodyClassMethods)
337   end
338   if defined?(pl::PoolMethods)
339     @pool_class = @pool_class.dup
340     SET_TEMPORARY_NAME[@pool_class, pl]
341     @pool_class.__send__(:include, pl::PoolMethods)
342   end
343   if defined?(pl::ConnectionMethods)
344     @connection_class = @connection_class.dup
345     SET_TEMPORARY_NAME[@connection_class, pl]
346     @connection_class.__send__(:include, pl::ConnectionMethods)
347   end
348   return unless defined?(pl::OptionsMethods)
349 
350   @options_class = @options_class.dup
351   @options_class.__send__(:include, pl::OptionsMethods)
352 end
freeze()
[show source] 
    # File lib/httpx/options.rb
149 def freeze
150   super
151   @origin.freeze
152   @base_path.freeze
153   @timeout.freeze
154   @headers.freeze
155   @addresses.freeze
156   @supported_compression_formats.freeze
157 end
merge(other)
[show source] 
    # File lib/httpx/options.rb
265 def merge(other)
266   ivar_map = nil
267   other_ivars = case other
268                 when Hash
269                   ivar_map = other.keys.to_h { |k| [:"@#{k}", k] }
270                   ivar_map.keys
271                 else
272                   other.instance_variables
273   end
274 
275   return self if other_ivars.empty?
276 
277   return self if other_ivars.all? { |ivar| instance_variable_get(ivar) == access_option(other, ivar, ivar_map) }
278 
279   opts = dup
280 
281   other_ivars.each do |ivar|
282     v = access_option(other, ivar, ivar_map)
283 
284     unless v
285       opts.instance_variable_set(ivar, v)
286       next
287     end
288 
289     v = opts.__send__(:"option_#{ivar[1..-1]}", v)
290 
291     orig_v = instance_variable_get(ivar)
292 
293     v = orig_v.merge(v) if orig_v.respond_to?(:merge) && v.respond_to?(:merge)
294 
295     opts.instance_variable_set(ivar, v)
296   end
297 
298   opts
299 end
option_addresses(value)
[show source] 
    # File lib/httpx/options.rb
221 def option_addresses(value)
222   Array(value)
223 end
option_base_path(value)
[show source] 
    # File lib/httpx/options.rb
163 def option_base_path(value)
164   String(value)
165 end
option_body_threshold_size(value)
[show source] 
    # File lib/httpx/options.rb
207 def option_body_threshold_size(value)
208   bytes = Integer(value)
209   raise TypeError, ":body_threshold_size must be positive" unless bytes.positive?
210 
211   bytes
212 end
option_buffer_size(value)
[show source] 
    # File lib/httpx/options.rb
199 def option_buffer_size(value)
200   value = Integer(value)
201 
202   raise TypeError, ":buffer_size must be positive" unless value.positive?
203 
204   value
205 end
option_headers(value)
[show source] 
    # File lib/httpx/options.rb
167 def option_headers(value)
168   headers_class.new(value)
169 end
option_ip_families(value)
[show source] 
    # File lib/httpx/options.rb
225 def option_ip_families(value)
226   Array(value)
227 end
option_max_concurrent_requests(value)
[show source] 
    # File lib/httpx/options.rb
179 def option_max_concurrent_requests(value)
180   raise TypeError, ":max_concurrent_requests must be positive" unless value.positive?
181 
182   value
183 end
option_max_requests(value)
[show source] 
    # File lib/httpx/options.rb
185 def option_max_requests(value)
186   raise TypeError, ":max_requests must be positive" unless value.positive?
187 
188   value
189 end
option_origin(value)
[show source] 
    # File lib/httpx/options.rb
159 def option_origin(value)
160   URI(value)
161 end
option_supported_compression_formats(value)
[show source] 
    # File lib/httpx/options.rb
175 def option_supported_compression_formats(value)
176   Array(value).map(&:to_s)
177 end
option_timeout(value)
[show source] 
    # File lib/httpx/options.rb
171 def option_timeout(value)
172   Hash[value]
173 end
option_transport(value)
[show source] 
    # File lib/httpx/options.rb
214 def option_transport(value)
215   transport = value.to_s
216   raise TypeError, "#{transport} is an unsupported transport type" unless %w[unix].include?(transport)
217 
218   transport
219 end
option_window_size(value)
[show source] 
    # File lib/httpx/options.rb
191 def option_window_size(value)
192   value = Integer(value)
193 
194   raise TypeError, ":window_size must be positive" unless value.positive?
195 
196   value
197 end
options_equals?(other, ignore_ivars = REQUEST_BODY_IVARS)
[show source] 
    # File lib/httpx/options.rb
250 def options_equals?(other, ignore_ivars = REQUEST_BODY_IVARS)
251   # headers and other request options do not play a role, as they are
252   # relevant only for the request.
253   ivars = instance_variables - ignore_ivars
254   other_ivars = other.instance_variables - ignore_ivars
255 
256   return false if ivars.size != other_ivars.size
257 
258   return false if ivars.sort != other_ivars.sort
259 
260   ivars.all? do |ivar|
261     instance_variable_get(ivar) == other.instance_variable_get(ivar)
262   end
263 end
to_hash()
[show source] 
    # File lib/httpx/options.rb
301 def to_hash
302   instance_variables.each_with_object({}) do |ivar, hs|
303     hs[ivar[1..-1].to_sym] = instance_variable_get(ivar)
304   end
305 end