Class: HTTP::Options

Inherits:
Object
  • Object
show all
Defined in:
lib/http/options.rb,
lib/http/options/definitions.rb,
sig/http.rbs

Overview

Configuration options for HTTP requests and clients

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(response: :auto, encoding: nil, nodelay: false, keep_alive_timeout: 5, proxy: {}, ssl: {}, headers: {}, features: {}, timeout_class: self.class.default_timeout_class, timeout_options: {}, socket_class: self.class.default_socket_class, ssl_socket_class: self.class.default_ssl_socket_class, params: nil, form: nil, json: nil, body: nil, follow: nil, retriable: nil, base_uri: nil, persistent: nil, ssl_context: nil) ⇒ HTTP::Options

Initializes options with keyword arguments

Examples:

HTTP::Options.new(response: :auto, follow: true)


134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/http/options.rb', line 134

def initialize(
  response: :auto,
  encoding: nil,
  nodelay: false,
  keep_alive_timeout: 5,
  proxy: {},
  ssl: {},
  headers: {},
  features: {},
  timeout_class: self.class.default_timeout_class,
  timeout_options: {},
  socket_class: self.class.default_socket_class,
  ssl_socket_class: self.class.default_ssl_socket_class,
  params: nil,
  form: nil,
  json: nil,
  body: nil,
  follow: nil,
  retriable: nil,
  base_uri: nil,
  persistent: nil,
  ssl_context: nil
)
  assign_options(binding)
end

Class Attribute Details

.available_features ⇒ Hash (readonly)

Registered feature implementations

Examples:

HTTP::Options.available_features

Returns:

  • (Hash) —

    registered feature implementations



51
52
53
 
# File 'lib/http/options.rb', line 51

def available_features
  @available_features
end

.default_socket_class ⇒ Class

Default TCP socket class

Examples:

HTTP::Options.default_socket_class # => TCPSocket

Returns:

  • (Class) —

    default socket class



24
25
26
 
# File 'lib/http/options.rb', line 24

def default_socket_class
  @default_socket_class
end

.default_ssl_socket_class ⇒ Class

Default SSL socket class

Examples:

HTTP::Options.default_ssl_socket_class

Returns:

  • (Class) —

    default SSL socket class



33
34
35
 
# File 'lib/http/options.rb', line 33

def default_ssl_socket_class
  @default_ssl_socket_class
end

.default_timeout_class ⇒ Class

Default timeout handler class

Examples:

HTTP::Options.default_timeout_class

Returns:

  • (Class) —

    default timeout class



42
43
44
 
# File 'lib/http/options.rb', line 42

def default_timeout_class
  @default_timeout_class
end

Instance Attribute Details

#base_uri ⇒ URI?

Returns the value of attribute base_uri.

Returns:



685
686
687
 
# File 'sig/http.rbs', line 685

def base_uri
  @base_uri
end

#body ⇒ Object

Returns the value of attribute body.

Returns:

  • (Object) 


672
673
674
 
# File 'sig/http.rbs', line 672

def body
  @body
end

#encoding ⇒ Encoding?

Returns the value of attribute encoding.

Returns:

  • (Encoding, nil) 


682
683
684
 
# File 'sig/http.rbs', line 682

def encoding
  @encoding
end

#features ⇒ Hash[Symbol, Feature]

Returns the value of attribute features.

Returns:



653
654
655
 
# File 'sig/http.rbs', line 653

def features
  @features
end

#follow ⇒ Hash[Symbol, untyped]?

Returns the value of attribute follow.

Returns:

  • (Hash[Symbol, untyped], nil) 


683
684
685
 
# File 'sig/http.rbs', line 683

def follow
  @follow
end

#form ⇒ Object

Returns the value of attribute form.

Returns:

  • (Object) 


670
671
672
 
# File 'sig/http.rbs', line 670

def form
  @form
end

#headers ⇒ Headers

Dynamic options generated by def_option

Returns:



667
668
669
 
# File 'sig/http.rbs', line 667

def headers
  @headers
end

#json ⇒ Object

Returns the value of attribute json.

Returns:

  • (Object) 


671
672
673
 
# File 'sig/http.rbs', line 671

def json
  @json
end

#keep_alive_timeout ⇒ Integer

Returns the value of attribute keep_alive_timeout.

Returns:

  • (Integer) 


679
680
681
 
# File 'sig/http.rbs', line 679

def keep_alive_timeout
  @keep_alive_timeout
end

#nodelay ⇒ Boolean

Returns the value of attribute nodelay.

Returns:

  • (Boolean) 


675
676
677
 
# File 'sig/http.rbs', line 675

def nodelay
  @nodelay
end

#params ⇒ Object

Returns the value of attribute params.

Returns:

  • (Object) 


669
670
671
 
# File 'sig/http.rbs', line 669

def params
  @params
end

#persistent ⇒ String?

Returns the value of attribute persistent.

Returns:

  • (String, nil) 


686
687
688
 
# File 'sig/http.rbs', line 686

def persistent
  @persistent
end

#proxy ⇒ Hash[Symbol, untyped]

Returns the value of attribute proxy.

Returns:

  • (Hash[Symbol, untyped]) 


668
669
670
 
# File 'sig/http.rbs', line 668

def proxy
  @proxy
end

#response ⇒ Symbol

Returns the value of attribute response.

Returns:

  • (Symbol) 


673
674
675
 
# File 'sig/http.rbs', line 673

def response
  @response
end

#retriable ⇒ Hash[Symbol, untyped]?

Returns the value of attribute retriable.

Returns:

  • (Hash[Symbol, untyped], nil) 


684
685
686
 
# File 'sig/http.rbs', line 684

def retriable
  @retriable
end

#socket_class ⇒ Class

Returns the value of attribute socket_class.

Returns:

  • (Class) 


674
675
676
 
# File 'sig/http.rbs', line 674

def socket_class
  @socket_class
end

#ssl ⇒ Hash[Symbol, untyped]

Returns the value of attribute ssl.

Returns:

  • (Hash[Symbol, untyped]) 


678
679
680
 
# File 'sig/http.rbs', line 678

def ssl
  @ssl
end

#ssl_context ⇒ OpenSSL::SSL::SSLContext?

Returns the value of attribute ssl_context.

Returns:

  • (OpenSSL::SSL::SSLContext, nil) 


677
678
679
 
# File 'sig/http.rbs', line 677

def ssl_context
  @ssl_context
end

#ssl_socket_class ⇒ Class

Returns the value of attribute ssl_socket_class.

Returns:

  • (Class) 


676
677
678
 
# File 'sig/http.rbs', line 676

def ssl_socket_class
  @ssl_socket_class
end

#timeout_class ⇒ Class

Returns the value of attribute timeout_class.

Returns:

  • (Class) 


680
681
682
 
# File 'sig/http.rbs', line 680

def timeout_class
  @timeout_class
end

#timeout_options ⇒ Hash[Symbol, Numeric]

Returns the value of attribute timeout_options.

Returns:

  • (Hash[Symbol, Numeric]) 


681
682
683
 
# File 'sig/http.rbs', line 681

def timeout_options
  @timeout_options
end

Class Method Details

.defined_options ⇒ Array<Symbol>

Returns list of defined option names

Examples:

HTTP::Options.defined_options

Returns:

  • (Array<Symbol>) 


74
75
76
 
# File 'lib/http/options.rb', line 74

def defined_options
  @defined_options ||= []
end

.new(options = nil, **kwargs) ⇒ HTTP::Options

Returns existing Options or creates new one

Examples:

HTTP::Options.new(response: :auto)

Parameters:

  • options (HTTP::Options, Hash, nil) (defaults to: nil) —

    existing Options or Hash to convert

  • kwargs (Object)

Returns:



61
62
63
64
65
 
# File 'lib/http/options.rb', line 61

def new(options = nil, **kwargs)
  return options if options.is_a?(self)

  super(**(options || kwargs)) # steep:ignore
end

.register_feature(name, impl) ⇒ Class

Registers a feature by name and implementation

Examples:

HTTP::Options.register_feature(:auto_inflate, AutoInflate)

Parameters:

  • name (Symbol)
  • impl (Class)

Returns:

  • (Class) 


87
88
89
 
# File 'lib/http/options.rb', line 87

def register_feature(name, impl)
  @available_features[name] = impl
end

Instance Method Details

#argument_error!(message) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Raises an argument error with adjusted backtrace

Parameters:

  • message (String) 


233
234
235
236
237
 
# File 'lib/http/options.rb', line 233

def argument_error!(message)
  error = Error.new(message)
  error.set_backtrace(caller(1) || [])
  raise error
end

#assign_options(env) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Assigns all option values from the initialize binding

Parameters:

  • env (Binding) —

    binding from initialize with keyword argument values



221
222
223
224
225
226
227
 
# File 'lib/http/options.rb', line 221

def assign_options(env)
  self.class.defined_options.each do |name|
    value = env.local_variable_get(name)
    value = Headers.coerce(value) if name.eql?(:headers)
    __send__(:"#{name}=", value)
  end
end

#base_uri? ⇒ Boolean

Checks whether a base URI is set

Examples:

opts = HTTP::Options.new(base_uri: "https://example.com")
opts.base_uri?

Returns:

  • (Boolean) 


113
114
115
 
# File 'lib/http/options/definitions.rb', line 113

def base_uri?
  !base_uri.nil?
end

#dup {|dupped| ... } ⇒ HTTP::Options

Duplicates the options object

Examples:

opts = HTTP::Options.new
opts.dup

Yields:

  • (dupped)

Returns:



195
196
197
198
199
 
# File 'lib/http/options.rb', line 195

def dup
  dupped = super
  yield(dupped) if block_given?
  dupped
end

#feature(name) ⇒ Feature?

Returns a feature by name

Examples:

opts = HTTP::Options.new
opts.feature(:auto_inflate)

Parameters:

  • name (Symbol)

Returns:



210
211
212
 
# File 'lib/http/options.rb', line 210

def feature(name)
  features[name]
end

#merge(other) ⇒ HTTP::Options

Merges two Options objects

Examples:

opts = HTTP::Options.new.merge(HTTP::Options.new(response: :body))

Parameters:

Returns:



168
169
170
171
172
173
174
 
# File 'lib/http/options.rb', line 168

def merge(other)
  merged = to_hash.merge(other.to_hash) do |k, v1, v2|
    k == :headers ? v1.merge(v2) : v2
  end

  self.class.new(**merged)
end

#parse_base_uri(value) ⇒ HTTP::URI

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parses and validates a base URI value

Parameters:

  • value (String, HTTP::URI) —

    the base URI to parse

Returns:



148
149
150
151
152
153
154
155
156
 
# File 'lib/http/options/definitions.rb', line 148

def parse_base_uri(value)
  uri = URI.parse(value)

  base = @base_uri
  return resolve_base_uri(base, uri) if base

  argument_error!(format("Invalid base URI: %s", value)) unless uri.scheme
  uri
end

#persistent? ⇒ Boolean

Checks whether persistent connection is enabled

Examples:

opts = HTTP::Options.new(persistent: "http://example.com")
opts.persistent?

Returns:

  • (Boolean) 


137
138
139
 
# File 'lib/http/options/definitions.rb', line 137

def persistent?
  !persistent.nil?
end

#resolve_base_uri(base, relative) ⇒ HTTP::URI

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Resolves a relative URI against an existing base URI

Parameters:

Returns:



164
165
166
167
168
169
170
171
 
# File 'lib/http/options/definitions.rb', line 164

def resolve_base_uri(base, relative)
  unless base.path.end_with?("/")
    base = base.dup
    base.path = "#{base.path}/"
  end

  URI.parse(base.join(relative))
end

#to_hash ⇒ Hash

Converts options to a Hash

Examples:

HTTP::Options.new.to_hash

Returns:

  • (Hash) 


183
184
185
 
# File 'lib/http/options.rb', line 183

def to_hash
  self.class.defined_options.to_h { |opt_name| [opt_name, public_send(opt_name)] }
end

#validate_base_uri_and_persistent! ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates that base URI and persistent origin are compatible



177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/http/options/definitions.rb', line 177

def validate_base_uri_and_persistent!
  base = @base_uri
  persistent = @persistent
  return unless base && persistent
  return if base.origin.eql?(persistent)

  argument_error!(
    format("Persistence origin (%s) conflicts with base URI origin (%s)",
           persistent, base.origin)
  )
end

#with_base_uri ⇒ Options

Parameters:

  • value (String, URI)

Returns:



693
 
# File 'sig/http.rbs', line 693

def with_base_uri: (String | URI value) -> Options

#with_body ⇒ Options

Parameters:

  • value (Object)

Returns:



699
 
# File 'sig/http.rbs', line 699

def with_body: (untyped value) -> Options

#with_encoding ⇒ Options

Parameters:

  • value (String, Encoding)

Returns:



689
 
# File 'sig/http.rbs', line 689

def with_encoding: (String | Encoding value) -> Options

#with_features ⇒ Options

Parameters:

  • value (Array[Symbol | Hash[Symbol, untyped]])

Returns:



690
 
# File 'sig/http.rbs', line 690

def with_features: (Array[Symbol | Hash[Symbol, untyped]] value) -> Options

#with_follow ⇒ Options

Parameters:

  • value (Hash[Symbol, untyped], bool)

Returns:



691
 
# File 'sig/http.rbs', line 691

def with_follow: (Hash[Symbol, untyped] | bool value) -> Options

#with_form ⇒ Options

Parameters:

  • value (Object)

Returns:



697
 
# File 'sig/http.rbs', line 697

def with_form: (untyped value) -> Options

#with_headers ⇒ Options

Parameters:

  • value (Hash[String | Symbol, untyped], Headers)

Returns:



688
 
# File 'sig/http.rbs', line 688

def with_headers: (Hash[String | Symbol, untyped] | Headers value) -> Options

#with_json ⇒ Options

Parameters:

  • value (Object)

Returns:



698
 
# File 'sig/http.rbs', line 698

def with_json: (untyped value) -> Options

#with_keep_alive_timeout ⇒ Options

Parameters:

  • value (Integer)

Returns:



706
 
# File 'sig/http.rbs', line 706

def with_keep_alive_timeout: (Integer value) -> Options

#with_nodelay ⇒ Options

Parameters:

  • value (Boolean)

Returns:



702
 
# File 'sig/http.rbs', line 702

def with_nodelay: (bool value) -> Options

#with_params ⇒ Options

Parameters:

  • value (Hash[String | Symbol, untyped])

Returns:



696
 
# File 'sig/http.rbs', line 696

def with_params: (Hash[String | Symbol, untyped] value) -> Options

#with_persistent ⇒ Options

Parameters:

  • value (String)

Returns:



694
 
# File 'sig/http.rbs', line 694

def with_persistent: (String value) -> Options

#with_proxy ⇒ Options

Parameters:

  • value (Hash[Symbol, untyped])

Returns:



695
 
# File 'sig/http.rbs', line 695

def with_proxy: (Hash[Symbol, untyped] value) -> Options

#with_response ⇒ Options

Parameters:

  • value (Symbol)

Returns:



700
 
# File 'sig/http.rbs', line 700

def with_response: (Symbol value) -> Options

#with_retriable ⇒ Options

Parameters:

  • value (Hash[Symbol, untyped], bool)

Returns:



692
 
# File 'sig/http.rbs', line 692

def with_retriable: (Hash[Symbol, untyped] | bool value) -> Options

#with_socket_class ⇒ Options

Parameters:

  • value (Class)

Returns:



701
 
# File 'sig/http.rbs', line 701

def with_socket_class: (Class value) -> Options

#with_ssl ⇒ Options

Parameters:

  • value (Hash[Symbol, untyped])

Returns:



705
 
# File 'sig/http.rbs', line 705

def with_ssl: (Hash[Symbol, untyped] value) -> Options

#with_ssl_context ⇒ Options

Parameters:

  • value (OpenSSL::SSL::SSLContext, nil)

Returns:



704
 
# File 'sig/http.rbs', line 704

def with_ssl_context: (OpenSSL::SSL::SSLContext? value) -> Options

#with_ssl_socket_class ⇒ Options

Parameters:

  • value (Class)

Returns:



703
 
# File 'sig/http.rbs', line 703

def with_ssl_socket_class: (Class value) -> Options

#with_timeout_class ⇒ Options

Parameters:

  • value (Class)

Returns:



707
 
# File 'sig/http.rbs', line 707

def with_timeout_class: (Class value) -> Options

#with_timeout_options ⇒ Options

Parameters:

  • value (Hash[Symbol, Numeric])

Returns:



708
 
# File 'sig/http.rbs', line 708

def with_timeout_options: (Hash[Symbol, Numeric] value) -> Options