Class: HTTP::Options

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

Overview

Configuration options for HTTP requests and clients

Class 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

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

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

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

Sets the base URI for resolving relative request paths

Parameters:

Returns:



100
101
102
103
 
# File 'lib/http/options/definitions.rb', line 100

def base_uri=(value)
  @base_uri = value ? parse_base_uri(value) : nil
  validate_base_uri_and_persistent!
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

#features=(features) ⇒ Hash

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.

Sets and normalizes features hash

Parameters:

  • features (Hash)

Returns:

  • (Hash) 


39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/http/options/definitions.rb', line 39

def features=(features)
  result = {} #: Hash[Symbol, Feature]
  @features = features.each_with_object(result) do |(name, opts_or_feature), h|
    h[name] = if opts_or_feature.is_a?(Feature)
                opts_or_feature
              else
                unless (feature = self.class.available_features[name])
                  argument_error! "Unsupported feature: #{name}"
                end
                feature.new(**opts_or_feature) # steep:ignore
              end
  end
end

#follow=(value) ⇒ Hash?

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.

Sets follow redirect options

Parameters:

  • value (Boolean, Hash, nil)

Returns:

  • (Hash, nil) 


68
69
70
71
72
73
74
75
 
# File 'lib/http/options/definitions.rb', line 68

def follow=(value)
  @follow =
    if    !value                    then nil
    elsif true == value             then {} #: Hash[untyped, untyped]
    elsif value.respond_to?(:fetch) then value
    else argument_error! "Unsupported follow options: #{value}"
    end
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

#persistent=(value) ⇒ String?

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.

Sets persistent connection origin

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) 


124
125
126
127
 
# File 'lib/http/options/definitions.rb', line 124

def persistent=(value)
  @persistent = value ? URI.parse(value).origin : nil
  validate_base_uri_and_persistent!
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

#retriable=(value) ⇒ Hash?

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.

Sets retriable options

Parameters:

  • value (Boolean, Hash, nil)

Returns:

  • (Hash, nil) 


84
85
86
87
88
89
90
91
 
# File 'lib/http/options/definitions.rb', line 84

def retriable=(value)
  @retriable =
    if    !value                    then nil
    elsif true == value             then {} #: Hash[untyped, untyped]
    elsif value.respond_to?(:fetch) then value
    else argument_error! "Unsupported retriable options: #{value}"
    end
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