Module: HTTP::Chainable

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

Instance Method Summary collapse

Instance Method Details

#accept(type) ⇒ Object

Accept the given MIME type(s)

Parameters:

  • type 


202
203
204
 
# File 'lib/http/chainable.rb', line 202

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

#auth(value, opts = nil) ⇒ Object

Make a request with the given Authorization header

Parameters:

  • value (#to_s) —

    Authorization header value



208
209
210
211
212
213
 
# File 'lib/http/chainable.rb', line 208

def auth(value, opts = nil)
  # shim for deprecated auth(:basic, opts).
  # will be removed in 0.8.0
  return basic_auth(opts) if :basic == 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:



220
221
222
223
224
225
 
# File 'lib/http/chainable.rb', line 220

def basic_auth(opts)
  user = opts.fetch :user
  pass = opts.fetch :pass

  auth("Basic " << Base64.strict_encode64("#{user}:#{pass}"))
end

#cache(cache) ⇒ Object Also known as: with_cache 



173
174
175
 
# File 'lib/http/chainable.rb', line 173

def cache(cache)
  branch default_options.with_cache(cache)
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) 


59
60
61
 
# File 'lib/http/chainable.rb', line 59

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

#cookies(cookies) ⇒ Object

Make a request with the given cookies



196
197
198
 
# File 'lib/http/chainable.rb', line 196

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

#default_headers ⇒ Object

Deprecated.

Will be removed in 1.0.0; Use #default_options#headers

Get headers of HTTP options



242
243
244
 
# File 'lib/http/chainable.rb', line 242

def default_headers
  default_options.headers
end

#default_headers=(headers) ⇒ Object

Deprecated.

Will be removed in 1.0.0; Use #headers

Set headers of HTTP options

Parameters:

  • headers 


249
250
251
252
253
 
# File 'lib/http/chainable.rb', line 249

def default_headers=(headers)
  @default_options = default_options.dup do |opts|
    opts.headers = headers
  end
end

#default_options ⇒ HTTP::Options

Get options for HTTP

Returns:



229
230
231
 
# File 'lib/http/chainable.rb', line 229

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

#default_options=(opts) ⇒ HTTP::Options

Set options for HTTP

Parameters:

  • opts

Returns:



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

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) 


38
39
40
 
# File 'lib/http/chainable.rb', line 38

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

#follow(opts = {}) ⇒ HTTP::Client Also known as: with_follow

Make client follow redirects.

Parameters:

  • opts (defaults to: {})

Returns:

See Also:



165
166
167
 
# File 'lib/http/chainable.rb', line 165

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

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

Get a resource

Parameters:

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

    a customizable set of options

Options Hash (options):

  • (Hash) 


17
18
19
 
# File 'lib/http/chainable.rb', line 17

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) 


10
11
12
 
# File 'lib/http/chainable.rb', line 10

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

#headers(headers) ⇒ Object Also known as: with, with_headers

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

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


52
53
54
 
# File 'lib/http/chainable.rb', line 52

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) 


66
67
68
 
# File 'lib/http/chainable.rb', line 66

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

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

Overloads:

  • #persistent(host) ⇒ HTTP::Client

    Flags as persistent

    Parameters:

    • host (String)

    Returns:

    Raises:

    • (Request::Error) —

      if Host is invalid

  • #persistent(host) {|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



135
136
137
138
139
140
141
 
# File 'lib/http/chainable.rb', line 135

def persistent(host)
  p_client = branch default_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) 


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

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) 


31
32
33
 
# File 'lib/http/chainable.rb', line 31

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

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

Make an HTTP request with the given verb

Parameters:

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

    a customizable set of options

Options Hash (options):

  • (Hash) 


73
74
75
 
# File 'lib/http/chainable.rb', line 73

def request(verb, uri, options = {})
  branch(options).request verb, uri
end

#timeout(klass, options = {}) ⇒ Object

@overload(options = {}) Syntax sugar for timeout(:per_operation, options) @overload(klass, options = {}) @param [#to_sym] klass @param [Hash] options @option options [Float] :read Read timeout @option options [Float] :write Write timeout @option options [Float] :connect Connect timeout



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/http/chainable.rb', line 85

def timeout(klass, options = {})
  klass, options = :per_operation, klass if klass.is_a? Hash

  klass = case klass.to_sym
          when :null          then HTTP::Timeout::Null
          when :global        then HTTP::Timeout::Global
          when :per_operation then HTTP::Timeout::PerOperation
          else fail ArgumentError, "Unsupported Timeout class: #{klass}"
          end

  [:read, :write, :connect].each do |k|
    next unless options.key? k
    options["#{k}_timeout".to_sym] = 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) 


45
46
47
 
# File 'lib/http/chainable.rb', line 45

def trace(uri, options = {})
  request :trace, uri, options
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



146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/http/chainable.rb', line 146

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)

  if [2, 4].include?(proxy_hash.keys.size)
    branch default_options.with_proxy(proxy_hash)
  else
    fail(RequestError, "invalid HTTP proxy: #{proxy_hash}")
  end
end