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 => ENV.key?("HTTPX_DEBUG") ? $stderr : nil, :debug_level => (ENV["HTTPX_DEBUG"] || 1).to_i, :ssl => {}, :http2_settings => { settings_enable_push: 0 }, :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), :headers => {}, :window_size => WINDOW_SIZE, :buffer_size => BUFFER_SIZE, :body_threshold_size => MAX_BODY_THRESHOLD_SIZE, :request_class => Class.new(Request), :response_class => Class.new(Response), :request_body_class => Class.new(Request::Body), :response_body_class => Class.new(Response::Body), :connection_class => Class.new(Connection), :options_class => Class.new(self), :transport => nil, :addresses => nil, :persistent => false, :resolver_class => (ENV["HTTPX_RESOLVER"] || :native).to_sym, :resolver_options => { cache: true }, :ip_families => ip_address_families, }.freeze  
KEEP_ALIVE_TIMEOUT = 20  
MAX_BODY_THRESHOLD_SIZE = (1 << 10) * 112  
OTHER_LOOKUP = ->(obj, k, ivar_map) { case obj when Hash obj[ivar_map[k]] else obj.instance_variable_get(k) end }  
REQUEST_BODY_IVARS = %i[@headers @params @form @xml @json @body].freeze  
REQUEST_TIMEOUT = OPERATION_TIMEOUT = nil  
SETTINGS_TIMEOUT = 10  
WINDOW_SIZE = 1 << 14  

Public Class methods

method_added(meth)
[show source]
   # File lib/httpx/options.rb
78 def method_added(meth)
79   super
80 
81   return unless meth =~ /^option_(.+)$/
82 
83   optname = Regexp.last_match(1).to_sym
84 
85   attr_reader(optname)
86 end
new(options = {})
[show source]
   # File lib/httpx/options.rb
70 def new(options = {})
71   # let enhanced options go through
72   return options if self == Options && options.class < self
73   return options if options.is_a?(self)
74 
75   super
76 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 HTTP2Next::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

: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

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

:params

hash or array of key-values which will be encoded and set in the query string of request uris.

:form

hash of array of key-values which will be form-or-multipart-encoded in requests body payload.

:json

hash of array of key-values which will be JSON-encoded in requests body payload.

:xml

Nokogiri XML nodes which will be encoded in requests body payload.

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

[show source]
    # File lib/httpx/options.rb
133 def initialize(options = {})
134   do_initialize(options)
135   freeze
136 end

Public Instance methods

==(other)
[show source]
    # File lib/httpx/options.rb
233 def ==(other)
234   super || options_equals?(other)
235 end
extend_with_plugin_classes(pl)
[show source]
    # File lib/httpx/options.rb
302 def extend_with_plugin_classes(pl)
303   if defined?(pl::RequestMethods) || defined?(pl::RequestClassMethods)
304     @request_class = @request_class.dup
305     @request_class.__send__(:include, pl::RequestMethods) if defined?(pl::RequestMethods)
306     @request_class.extend(pl::RequestClassMethods) if defined?(pl::RequestClassMethods)
307   end
308   if defined?(pl::ResponseMethods) || defined?(pl::ResponseClassMethods)
309     @response_class = @response_class.dup
310     @response_class.__send__(:include, pl::ResponseMethods) if defined?(pl::ResponseMethods)
311     @response_class.extend(pl::ResponseClassMethods) if defined?(pl::ResponseClassMethods)
312   end
313   if defined?(pl::HeadersMethods) || defined?(pl::HeadersClassMethods)
314     @headers_class = @headers_class.dup
315     @headers_class.__send__(:include, pl::HeadersMethods) if defined?(pl::HeadersMethods)
316     @headers_class.extend(pl::HeadersClassMethods) if defined?(pl::HeadersClassMethods)
317   end
318   if defined?(pl::RequestBodyMethods) || defined?(pl::RequestBodyClassMethods)
319     @request_body_class = @request_body_class.dup
320     @request_body_class.__send__(:include, pl::RequestBodyMethods) if defined?(pl::RequestBodyMethods)
321     @request_body_class.extend(pl::RequestBodyClassMethods) if defined?(pl::RequestBodyClassMethods)
322   end
323   if defined?(pl::ResponseBodyMethods) || defined?(pl::ResponseBodyClassMethods)
324     @response_body_class = @response_body_class.dup
325     @response_body_class.__send__(:include, pl::ResponseBodyMethods) if defined?(pl::ResponseBodyMethods)
326     @response_body_class.extend(pl::ResponseBodyClassMethods) if defined?(pl::ResponseBodyClassMethods)
327   end
328   if defined?(pl::ConnectionMethods)
329     @connection_class = @connection_class.dup
330     @connection_class.__send__(:include, pl::ConnectionMethods)
331   end
332   return unless defined?(pl::OptionsMethods)
333 
334   @options_class = @options_class.dup
335   @options_class.__send__(:include, pl::OptionsMethods)
336 end
freeze()
[show source]
    # File lib/httpx/options.rb
138 def freeze
139   super
140   @origin.freeze
141   @base_path.freeze
142   @timeout.freeze
143   @headers.freeze
144   @addresses.freeze
145   @supported_compression_formats.freeze
146 end
merge(other)
[show source]
    # File lib/httpx/options.rb
260 def merge(other)
261   ivar_map = nil
262   other_ivars = case other
263                 when Hash
264                   ivar_map = other.keys.to_h { |k| [:"@#{k}", k] }
265                   ivar_map.keys
266                 else
267                   other.instance_variables
268   end
269 
270   return self if other_ivars.empty?
271 
272   return self if other_ivars.all? { |ivar| instance_variable_get(ivar) == OTHER_LOOKUP[other, ivar, ivar_map] }
273 
274   opts = dup
275 
276   other_ivars.each do |ivar|
277     v = OTHER_LOOKUP[other, ivar, ivar_map]
278 
279     unless v
280       opts.instance_variable_set(ivar, v)
281       next
282     end
283 
284     v = opts.__send__(:"option_#{ivar[1..-1]}", v)
285 
286     orig_v = instance_variable_get(ivar)
287 
288     v = orig_v.merge(v) if orig_v.respond_to?(:merge) && v.respond_to?(:merge)
289 
290     opts.instance_variable_set(ivar, v)
291   end
292 
293   opts
294 end
option_addresses(value)
[show source]
    # File lib/httpx/options.rb
210 def option_addresses(value)
211   Array(value)
212 end
option_base_path(value)
[show source]
    # File lib/httpx/options.rb
152 def option_base_path(value)
153   String(value)
154 end
option_body_threshold_size(value)
[show source]
    # File lib/httpx/options.rb
196 def option_body_threshold_size(value)
197   bytes = Integer(value)
198   raise TypeError, ":body_threshold_size must be positive" unless bytes.positive?
199 
200   bytes
201 end
option_buffer_size(value)
[show source]
    # File lib/httpx/options.rb
188 def option_buffer_size(value)
189   value = Integer(value)
190 
191   raise TypeError, ":buffer_size must be positive" unless value.positive?
192 
193   value
194 end
option_headers(value)
[show source]
    # File lib/httpx/options.rb
156 def option_headers(value)
157   headers_class.new(value)
158 end
option_ip_families(value)
[show source]
    # File lib/httpx/options.rb
214 def option_ip_families(value)
215   Array(value)
216 end
option_max_concurrent_requests(value)
[show source]
    # File lib/httpx/options.rb
168 def option_max_concurrent_requests(value)
169   raise TypeError, ":max_concurrent_requests must be positive" unless value.positive?
170 
171   value
172 end
option_max_requests(value)
[show source]
    # File lib/httpx/options.rb
174 def option_max_requests(value)
175   raise TypeError, ":max_requests must be positive" unless value.positive?
176 
177   value
178 end
option_origin(value)
[show source]
    # File lib/httpx/options.rb
148 def option_origin(value)
149   URI(value)
150 end
option_supported_compression_formats(value)
[show source]
    # File lib/httpx/options.rb
164 def option_supported_compression_formats(value)
165   Array(value).map(&:to_s)
166 end
option_timeout(value)
[show source]
    # File lib/httpx/options.rb
160 def option_timeout(value)
161   Hash[value]
162 end
option_transport(value)
[show source]
    # File lib/httpx/options.rb
203 def option_transport(value)
204   transport = value.to_s
205   raise TypeError, "#{transport} is an unsupported transport type" unless %w[unix].include?(transport)
206 
207   transport
208 end
option_window_size(value)
[show source]
    # File lib/httpx/options.rb
180 def option_window_size(value)
181   value = Integer(value)
182 
183   raise TypeError, ":window_size must be positive" unless value.positive?
184 
185   value
186 end
options_equals?(other, ignore_ivars = REQUEST_BODY_IVARS)
[show source]
    # File lib/httpx/options.rb
237 def options_equals?(other, ignore_ivars = REQUEST_BODY_IVARS)
238   # headers and other request options do not play a role, as they are
239   # relevant only for the request.
240   ivars = instance_variables - ignore_ivars
241   other_ivars = other.instance_variables - ignore_ivars
242 
243   return false if ivars.size != other_ivars.size
244 
245   return false if ivars.sort != other_ivars.sort
246 
247   ivars.all? do |ivar|
248     instance_variable_get(ivar) == other.instance_variable_get(ivar)
249   end
250 end
to_hash()
[show source]
    # File lib/httpx/options.rb
296 def to_hash
297   instance_variables.each_with_object({}) do |ivar, hs|
298     hs[ivar[1..-1].to_sym] = instance_variable_get(ivar)
299   end
300 end