Module: HTTP::Chainable

Includes:
Base64
Included in:
HTTP, Client
Defined in:
lib/http/chainable.rb

Instance Method Summary collapse

Methods included from Base64

encode64

Instance Method Details

#accept(type) ⇒ Object

Accept the given MIME type(s)

Parameters:

  • type 


199
200
201
 
# File 'lib/http/chainable.rb', line 199

def accept(type)
  headers Headers::ACCEPT => MimeType.normalize(type)
end

#auth(value) ⇒ Object

Make a request with the given Authorization header

Parameters:

  • value (#to_s) —

    Authorization header value



205
206
207
 
# File 'lib/http/chainable.rb', line 205

def auth(value)
  headers Headers::AUTHORIZATION => value.to_s
end

#basic_auth(opts) ⇒ Object

Make a request with the given Basic authorization header

Parameters:

  • opts (#fetch)

Options Hash (opts):

  • :user (#to_s)
  • :pass (#to_s)

See Also:



214
215
216
217
218
219
220
 
# File 'lib/http/chainable.rb', line 214

def basic_auth(opts)
  user  = opts.fetch(:user)
  pass  = opts.fetch(:pass)
  creds = "#{user}:#{pass}"

  auth("Basic #{encode64(creds)}")
end

#build_request(*args) ⇒ Object

Prepare an HTTP request with the given verb



81
82
83
 
# File 'lib/http/chainable.rb', line 81

def build_request(*args)
  branch(default_options).build_request(*args)
end

#connect(uri, options = {}) ⇒ Object

Convert to a transparent TCP/IP tunnel

Parameters:

  • uri
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • (Hash) 


62
63
64
 
# File 'lib/http/chainable.rb', line 62

def connect(uri, options = {})
  request :connect, uri, options
end

#cookies(cookies) ⇒ Object

Make a request with the given cookies



188
189
190
 
# File 'lib/http/chainable.rb', line 188

def cookies(cookies)
  branch default_options.with_cookies(cookies)
end

#default_options ⇒ HTTP::Options

Get options for HTTP

Returns:



224
225
226
 
# File 'lib/http/chainable.rb', line 224

def default_options
  @default_options ||= HTTP::Options.new
end

#default_options=(opts) ⇒ HTTP::Options

Set options for HTTP

Parameters:

  • opts

Returns:



231
232
233
 
# File 'lib/http/chainable.rb', line 231

def default_options=(opts)
  @default_options = HTTP::Options.new(opts)
end

#delete(uri, options = {}) ⇒ Object

Delete a resource

Parameters:

  • uri
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • (Hash) 


41
42
43
 
# File 'lib/http/chainable.rb', line 41

def delete(uri, options = {})
  request :delete, uri, options
end

#encoding(encoding) ⇒ Object

Force a specific encoding for response body



193
194
195
 
# File 'lib/http/chainable.rb', line 193

def encoding(encoding)
  branch default_options.with_encoding(encoding)
end

#follow(options = {}) ⇒ HTTP::Client

Make client follow redirects.

Parameters:

  • options (defaults to: {})

Returns:

See Also:



177
178
179
 
# File 'lib/http/chainable.rb', line 177

def follow(options = {})
  branch default_options.with_follow options
end

#get(uri, options = {}) ⇒ Object

Get a resource

Parameters:

  • uri
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • (Hash) 


20
21
22
 
# File 'lib/http/chainable.rb', line 20

def get(uri, options = {})
  request :get, uri, options
end

#head(uri, options = {}) ⇒ Object

Request a get sans response body

Parameters:

  • uri
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • (Hash) 


13
14
15
 
# File 'lib/http/chainable.rb', line 13

def head(uri, options = {})
  request :head, uri, options
end

#headers(headers) ⇒ Object

Make a request with the given headers

Parameters:

  • headers 


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

def headers(headers)
  branch default_options.with_headers(headers)
end

#nodelay ⇒ Object

Set TCP_NODELAY on the socket



236
237
238
 
# File 'lib/http/chainable.rb', line 236

def nodelay
  branch default_options.with_nodelay(true)
end

#options(uri, options = {}) ⇒ Object

Return the methods supported on the given URI

Parameters:

  • uri
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • (Hash) 


55
56
57
 
# File 'lib/http/chainable.rb', line 55

def options(uri, options = {})
  request :options, uri, options
end

#patch(uri, options = {}) ⇒ Object

Apply partial modifications to a resource

Parameters:

  • uri
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • (Hash) 


69
70
71
 
# File 'lib/http/chainable.rb', line 69

def patch(uri, options = {})
  request :patch, uri, options
end

#persistent(host, timeout: 5) ⇒ HTTP::Client #persistent(host, timeout: 5) {|client| ... } ⇒ Object

Overloads:

  • #persistent(host, timeout: 5) ⇒ HTTP::Client

    Flags as persistent

    Parameters:

    • host (String)

    Returns:

    Raises:

    • (Request::Error) —

      if Host is invalid

  • #persistent(host, timeout: 5) {|client| ... } ⇒ Object

    Executes given block with persistent client and automatically closes connection at the end of execution.

    Examples:

    
def keys(users)
  HTTP.persistent("https://github.com") do |http|
    users.map { |u| http.get("/#{u}.keys").to_s }
  end
end

# same as

def keys(users)
  http = HTTP.persistent "https://github.com"
  users.map { |u| http.get("/#{u}.keys").to_s }
ensure
  http.close if http
end

    Yield Parameters:

    Returns:

    • (Object) —

      result of last expression in the block



145
146
147
148
149
150
151
152
153
 
# File 'lib/http/chainable.rb', line 145

def persistent(host, timeout: 5)
  options  = {keep_alive_timeout: timeout}
  p_client = branch default_options.merge(options).with_persistent host
  return p_client unless block_given?

  yield p_client
ensure
  p_client&.close
end

#post(uri, options = {}) ⇒ Object

Post to a resource

Parameters:

  • uri
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • (Hash) 


27
28
29
 
# File 'lib/http/chainable.rb', line 27

def post(uri, options = {})
  request :post, uri, options
end

#put(uri, options = {}) ⇒ Object

Put to a resource

Parameters:

  • uri
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • (Hash) 


34
35
36
 
# File 'lib/http/chainable.rb', line 34

def put(uri, options = {})
  request :put, uri, options
end

#request(*args) ⇒ Object

Make an HTTP request with the given verb



75
76
77
 
# File 'lib/http/chainable.rb', line 75

def request(*args)
  branch(default_options).request(*args)
end

#retriable(**options) ⇒ Object

Returns retriable client instance, which retries requests if they failed due to some socket errors or response status is 5xx.

Examples:

Usage


# Retry max 5 times with randomly growing delay between retries
HTTP.retriable.get(url)

# Retry max 3 times with randomly growing delay between retries
HTTP.retriable(times: 3).get(url)

# Retry max 3 times with 1 sec delay between retries
HTTP.retriable(times: 3, delay: proc { 1 }).get(url)

# Retry max 3 times with geometrically progressed delay between retries
HTTP.retriable(times: 3, delay: proc { |i| 1 + i*i }).get(url)


270
271
272
 
# File 'lib/http/chainable.rb', line 270

def retriable(**options)
  Retriable::Client.new(Retriable::Performer.new(options), default_options)
end

#timeout(options = {}) ⇒ Object #timeout(global_timeout) ⇒ Object

Overloads:

  • #timeout(options = {}) ⇒ Object

    Adds per operation timeouts to the request

    Parameters:

    • options (Hash) (defaults to: {})

    Options Hash (options):

    • :read (Float) —

      Read timeout

    • :write (Float) —

      Write timeout

    • :connect (Float) —

      Connect timeout

  • #timeout(global_timeout) ⇒ Object

    Adds a global timeout to the full request

    Parameters:

    • global_timeout (Numeric) 


94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/http/chainable.rb', line 94

def timeout(options)
  klass, options = case options
                   when Numeric then [HTTP::Timeout::Global, {global: options}]
                   when Hash    then [HTTP::Timeout::PerOperation, options.dup]
                   when :null   then [HTTP::Timeout::Null, {}]
                   else raise ArgumentError, "Use `.timeout(global_timeout_in_seconds)` or `.timeout(connect: x, write: y, read: z)`."

                   end

  %i[global read write connect].each do |k|
    next unless options.key? k

    options[:"#{k}_timeout"] = options.delete k
  end

  branch default_options.merge(
    timeout_class:   klass,
    timeout_options: options
  )
end

#trace(uri, options = {}) ⇒ Object

Echo the request back to the client

Parameters:

  • uri
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • (Hash) 


48
49
50
 
# File 'lib/http/chainable.rb', line 48

def trace(uri, options = {})
  request :trace, uri, options
end

#use(*features) ⇒ Object

Turn on given features. Available features are:

  • auto_inflate
  • auto_deflate
  • instrumentation
  • logging
  • normalize_uri
  • raise_error

Parameters:

  • features 


248
249
250
 
# File 'lib/http/chainable.rb', line 248

def use(*features)
  branch default_options.with_features(features)
end

#via(*proxy) ⇒ Object Also known as: through

Make a request through an HTTP proxy

Parameters:

  • proxy (Array)

Raises:

  • (Request::Error) —

    if HTTP proxy is invalid



158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/http/chainable.rb', line 158

def via(*proxy)
  proxy_hash = {}
  proxy_hash[:proxy_address]  = proxy[0] if proxy[0].is_a?(String)
  proxy_hash[:proxy_port]     = proxy[1] if proxy[1].is_a?(Integer)
  proxy_hash[:proxy_username] = proxy[2] if proxy[2].is_a?(String)
  proxy_hash[:proxy_password] = proxy[3] if proxy[3].is_a?(String)
  proxy_hash[:proxy_headers]  = proxy[2] if proxy[2].is_a?(Hash)
  proxy_hash[:proxy_headers]  = proxy[4] if proxy[4].is_a?(Hash)

  raise(RequestError, "invalid HTTP proxy: #{proxy_hash}") unless (2..5).cover?(proxy_hash.keys.size)

  branch default_options.with_proxy(proxy_hash)
end