Class: Manticore::Client

Inherits:
Object
  • Object
show all
Includes:
ProxiesInterface
Defined in:
lib/manticore/client.rb,
lib/manticore/client/proxies.rb,
lib/manticore/client/trust_strategies.rb

Overview

Core Manticore client, with a backing PoolingHttpClientConnectionManager

Defined Under Namespace

Modules: ProxiesInterface, TrustStrategies Classes: AsyncProxy, BackgroundProxy, BaseProxy, CombinedTrustStrategy, CustomTrustStrategy, StubProxy

Constant Summary collapse

DEFAULT_MAX_POOL_SIZE =

The default maximum pool size for requests

50
DEFAULT_REQUEST_TIMEOUT = 
60
DEFAULT_SOCKET_TIMEOUT = 
10
DEFAULT_CONNECT_TIMEOUT = 
10
DEFAULT_MAX_REDIRECTS = 
5
DEFAULT_EXPECT_CONTINUE = 
false
DEFAULT_STALE_CHECK = 
false

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ProxiesInterface

#async, #background, #respond_with

Constructor Details

#initialize(options = {}) {|builder, request_config| ... } ⇒ Client

Create a new HTTP client with a backing request pool. if you pass a block to the initializer, the underlying HttpClientBuilder and RequestConfig.Builder will be yielded so that you can operate on them directly.

Examples:

Simple instantiation and usage

client = Manticore::Client.new
client.get("http://www.google.com")

Instantiation with a block

client = Manticore::Client.new(socket_timeout: 5) do |http_client_builder, request_builder|
  http_client_builder.disable_redirect_handling
end

Parameters:

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

    Client pool options

Options Hash (options):

  • user_agent (String) —

    The user agent used in requests.

  • pool_max (Integer) — default: 50 —

    The maximum number of active connections in the pool

  • pool_max_per_route (integer) — default: pool_max —

    Sets the maximum number of active connections for a given target endpoint

  • cookies (boolean) — default: true —

    enable or disable automatic cookie management between requests

  • compression (boolean) — default: true —

    enable or disable transparent gzip/deflate support

  • request_timeout (integer) — default: 60 —

    Sets the timeout for requests. Raises Timeout on failure.

  • connect_timeout (integer) — default: 10 —

    Sets the timeout for connections. Raises Manticore::Timeout on failure.

  • socket_timeout (integer) — default: 10 —

    Sets SO_TIMEOUT for open connections. A value of 0 is an infinite timeout. Raises Manticore::Timeout on failure.

  • tcp_no_delay (boolean) — default: true —

    Enable or disable Nagle’s algorithm

  • request_timeout (integer) — default: 60 —

    Sets the timeout for a given request. Raises Manticore::Timeout on failure.

  • max_redirects (integer) — default: 5 —

    Sets the maximum number of redirects to follow.

  • automatic_retries (integer) — default: 3 —

    Sets the number of times the client will automatically retry failed requests.

  • retry_non_idempotent (boolean) — default: false —

    If true, Manticore will automatically retry failed requests with non-idempotent verbs. Otherwise, it only automatically retries on GET, HEAD, PUT, DELETE, OPTIONS, and TRACE

  • expect_continue (boolean) — default: false —

    Enable support for HTTP 100

  • stale_check (boolean) — default: false —

    Enable support for stale connection checking. Adds overhead.

  • check_connection_timeout (integer) — default: 2_000 —

    Connections that haven’t been used in this many milliseconds will be validated before being used. Set to a negative number to disable.

  • proxy (String) —

    Proxy host in form: proxy.org:1234

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org’[, port: 80[, scheme: ‘http’[, user: ‘username@host’, password: ‘password’]]]

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org:1234’[, user: ‘username@host’, password: ‘password’]]]

  • proxy (URI) —

    Proxy host as a URI object

  • keepalive (Boolean) — default: true —

    Whether to allow connections to be reused. Defaults to true.

  • ssl (Hash) —

    Hash of options for configuring SSL

  • ssl[:protocols] (Array<String>) — default: nil —

    A list of protocols that Manticore should accept

  • ssl[:cipher_suites] (Array<String>) — default: nil —

    A list of cipher suites that Manticore should accept

  • ssl[:verify] (Symbol) — default: :default —

    Hostname verification setting. Set to ‘:none` to turn off hostname verification. Setting to `:browser` will cause Manticore to accept a certificate for *.foo.com for all subdomains and sub-subdomains (eg a.b.foo.com). The default `:default` is like `:browser` but more strict - only accepts a single level of subdomains for wildcards, eg `b.foo.com` will be accepted for a `*.foo.com` certificate, but `a.b.foo.com` will not be.

  • ssl[:trust_strategy] (Client::TrustStrategiesInterface) — default: nil —

    A trust strategy to use in addition to any built by ‘ssl`. @see Client::TrustStrategiesInterface#coerce

  • ssl[:truststore] (String) — default: nil —

    Path to a custom trust store to use the verifying SSL connections

  • ssl[:truststore_password] (String) — default: nil —

    Password used for decrypting the server trust store

  • ssl[:truststore_type] (String) — default: nil —

    Format of the trust store, ie “JKS” or “PKCS12”. If left nil, the type will be inferred from the truststore filename.

  • ssl[:keystore] (String) — default: nil —

    Path to a custom key store to use for client certificate authentication

  • ssl[:keystore_password] (String) — default: nil —

    Password used for decrypting the client auth key store

  • ssl[:keystore_type] (String) — default: nil —

    Format of the key store, ie “JKS” or “PKCS12”. If left nil, the type will be inferred from the keystore filename.

  • ssl[:ca_file] (String) — default: nil —

    OpenSSL-style path to an X.509 certificate to use to validate SSL certificates

  • ssl[:client_cert] (String|OpenSSL::X509::Certificate) — default: nil —

    A string containing a base64-encoded X.509 certificate, OR a path to an OpenSSL-style X.509 certificate, OR an instance of OpenSSL::X509::Certificate

  • ssl[:client_key] (String|OpenSSL::PKey::Pkey) — default: nil —

    A string containing a base64-encoded RSA key to use for client authentication, OR a path to an OpenSSL-style RSA key, OR an instance of OpenSSL::PKey::PKey

  • ssl[:track_state] (boolean) — default: false —

    Turn on or off connection state tracking. This helps prevent SSL information from leaking across threads, but means that connections can’t be shared across those threads. This should generally be left off unless you know what you’re doing.

Yields:

  • (builder, request_config)

See Also:



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/manticore/client.rb', line 199

def initialize(options = {})
  @finalizer = Finalizer.new
  self.class.shutdown_on_finalize self, @finalizer

  builder = client_builder
  builder.set_user_agent options.fetch(:user_agent, "Manticore #{VERSION}")
  @options = options
  @use_cookies = options.fetch(:cookies, false)
  builder.disable_cookie_management unless @use_cookies
  builder.disable_content_compression if options.fetch(:compression, true) == false
  builder.set_proxy get_proxy_host(options[:proxy]) if options.key?(:proxy)

  builder.set_retry_handler LoggingStandardRetryHandler.new options.fetch(:automatic_retries, 3), options.fetch(:retry_non_idempotent, false)

  # http://hc.apache.org/httpcomponents-client-ga/tutorial/html/advanced.html#stateful_conn
  # By default this is used to prevent different contexts from accessing SSL data
  # Since we're running this for JRuby which does not have context separation within the JVM
  # We can disable this for connection reuse.
  builder.disable_connection_state unless options.fetch(:ssl, {}).fetch(:track_state, false)

  @keepalive = options.fetch(:keepalive, true)
  if @keepalive == false
    builder.set_connection_reuse_strategy NoConnectionReuseStrategy::INSTANCE # return false
  else
    builder.set_connection_reuse_strategy DefaultConnectionReuseStrategy.new
  end

  builder.set_default_socket_config socket_config_from_options(options)
  builder.set_connection_manager pool(options)

  request_config = RequestConfig.custom
  request_config.set_connection_request_timeout options.fetch(:request_timeout, DEFAULT_REQUEST_TIMEOUT) * 1000
  request_config.set_connect_timeout options.fetch(:connect_timeout, DEFAULT_CONNECT_TIMEOUT) * 1000
  request_config.set_socket_timeout options.fetch(:socket_timeout, DEFAULT_SOCKET_TIMEOUT) * 1000
  request_config.set_max_redirects options.fetch(:max_redirects, DEFAULT_MAX_REDIRECTS)
  request_config.set_expect_continue_enabled options.fetch(:expect_continue, DEFAULT_EXPECT_CONTINUE)
  request_config.set_stale_connection_check_enabled options.fetch(:stale_check, DEFAULT_STALE_CHECK)
  request_config.set_circular_redirects_allowed false

  yield builder, request_config if block_given?

  builder.set_default_request_config request_config.build
  @client = builder.build
  finalize @client, :close
  @options = options
  @async_requests = Queue.new
  @stubs = {}
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



138
139
140
 
# File 'lib/manticore/client.rb', line 138

def client
  @client
end

Class Method Details

.shutdown_on_finalize(client, finalizer) ⇒ Object 



417
418
419
 
# File 'lib/manticore/client.rb', line 417

def self.shutdown_on_finalize(client, finalizer)
  ObjectSpace.define_finalizer(client, finalizer)
end

Instance Method Details

#clear_pending ⇒ Object

Remove all pending asynchronous requests.

Returns:

  • nil



345
346
347
348
 
# File 'lib/manticore/client.rb', line 345

def clear_pending
  @async_requests.clear
  nil
end

#clear_stubs! ⇒ Object

Wipe all currently-set stubs.



338
339
340
 
# File 'lib/manticore/client.rb', line 338

def clear_stubs!
  @stubs.clear
end

#close(await: nil) ⇒ Object

Note:

In versions before 0.9 this method only closed the underlying ‘CloseableHttpClient`

Release resources held by this client, namely:

- close the internal http client
- shutdown the connection pool
- stops accepting async requests in the executor

After this call the client is no longer usable.



374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/manticore/client.rb', line 374

def close(await: nil)
  ObjectSpace.undefine_finalizer(self)
  @finalizer.call # which does ~ :
  # @executor&.shutdown rescue nil
  # @client&.close
  # @pool&.shutdown rescue nil
  case await
  when false, nil
    @executor&.shutdown_now rescue nil
  when Numeric
    # NOTE: the concept of awaiting gracefully might/should also be used with the pool/client closing
    millis = java.util.concurrent.TimeUnit::MILLISECONDS
    @executor&.await_termination(await * 1000, millis) rescue nil
  else
    nil
  end
  @async_requests.close
end

#delete(url, options = {}, &block) ⇒ Response

Perform a HTTP DELETE request

Examples:

Simple usage

body = client.delete("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).body

Passing a block as the success handler:

body = client.delete("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}) {|response| response.body }

Explicit success handler:

body = client.delete("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).
  on_success {|response| response.body }

Parameters:

  • url (String) —

    URL to request

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

Options Hash (options):

  • query (Hash) —

    Hash of options to be added to the URL as part of the query string

  • params (Hash) —

    Hash of options to pass as a request body. For GET, HEAD, and DELETE requests, :params will be treated as :query if :query is not present.

  • headers (Hash) —

    Hash of options to pass as additional request headers

  • proxy (String) —

    Proxy host in form: proxy.org:1234

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org’[, port: 80[, scheme: ‘http’]]

  • proxy (URI) —

    Proxy host as a URI object

  • connect_timeout (Float) —

    Request-specific connect timeout (in seconds)

  • socket_timeout (Float) —

    Request-specific socket timeout (in seconds)

  • request_timeout (Float) —

    Request-specific request timeout (in seconds)

  • max_redirects (Integer) —

    Request-specific maximum redirect limit

  • follow_redirects (Boolean) —

    Specify whether this request should follow redirects

  • auth (Hash) —

    Specify authentication for the request

  • auth[:user] (String) —

    Username to auth with

  • auth[:password] (String) —

    Password to auth with

  • auth[:eager] (Boolean) —

    Eagerly offer the Authorization header before the server challenges for it. You should not use this unless you know you specifically need it, as misuse of it can leak user credentials.

Returns:

Raises:



289
290
291
292
 
# File 'lib/manticore/client.rb', line 289

def delete(url, options = {}, &block)
  options = treat_params_as_query(options)
  request HttpDeleteWithEntity, url, options, &block
end

#execute! ⇒ Array

Execute all queued async requests

Returns:

  • (Array) —

    An array of the responses from the requests executed.



353
354
355
356
357
358
359
360
361
362
363
364
365
 
# File 'lib/manticore/client.rb', line 353

def execute!
  method = executor.java_method(:submit, [java.util.concurrent.Callable.java_class])

  result = []
  result << method.call(@async_requests.pop) until @async_requests.empty?
  result.map do |future|
    begin
      future.get
    rescue Java::JavaUtilConcurrent::ExecutionException => e
      # These exceptions should be handled in on_failure blocks.
    end
  end
end

#executor ⇒ Object

Get at the underlying ExecutorService used to invoke asynchronous calls.



412
413
414
 
# File 'lib/manticore/client.rb', line 412

def executor
  @executor ||= create_executor
end

#get(url, options = {}, &block) ⇒ Response

Perform a HTTP GET request

Examples:

Simple usage

body = client.get("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).body

Passing a block as the success handler:

body = client.get("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}) {|response| response.body }

Explicit success handler:

body = client.get("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).
  on_success {|response| response.body }

Parameters:

  • url (String) —

    URL to request

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

Options Hash (options):

  • query (Hash) —

    Hash of options to be added to the URL as part of the query string

  • params (Hash) —

    Hash of options to pass as a request body. For GET, HEAD, and DELETE requests, :params will be treated as :query if :query is not present.

  • headers (Hash) —

    Hash of options to pass as additional request headers

  • proxy (String) —

    Proxy host in form: proxy.org:1234

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org’[, port: 80[, scheme: ‘http’]]

  • proxy (URI) —

    Proxy host as a URI object

  • connect_timeout (Float) —

    Request-specific connect timeout (in seconds)

  • socket_timeout (Float) —

    Request-specific socket timeout (in seconds)

  • request_timeout (Float) —

    Request-specific request timeout (in seconds)

  • max_redirects (Integer) —

    Request-specific maximum redirect limit

  • follow_redirects (Boolean) —

    Specify whether this request should follow redirects

  • auth (Hash) —

    Specify authentication for the request

  • auth[:user] (String) —

    Username to auth with

  • auth[:password] (String) —

    Password to auth with

  • auth[:eager] (Boolean) —

    Eagerly offer the Authorization header before the server challenges for it. You should not use this unless you know you specifically need it, as misuse of it can leak user credentials.

Returns:

Raises:



263
264
265
266
 
# File 'lib/manticore/client.rb', line 263

def get(url, options = {}, &block)
  options = treat_params_as_query(options)
  request HttpGetWithEntity, url, options, &block
end

#head(url, options = {}, &block) ⇒ Response

Perform a HTTP HEAD request

Examples:

Simple usage

body = client.head("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).body

Passing a block as the success handler:

body = client.head("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}) {|response| response.body }

Explicit success handler:

body = client.head("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).
  on_success {|response| response.body }

Parameters:

  • url (String) —

    URL to request

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

Options Hash (options):

  • query (Hash) —

    Hash of options to be added to the URL as part of the query string

  • params (Hash) —

    Hash of options to pass as a request body. For GET, HEAD, and DELETE requests, :params will be treated as :query if :query is not present.

  • headers (Hash) —

    Hash of options to pass as additional request headers

  • proxy (String) —

    Proxy host in form: proxy.org:1234

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org’[, port: 80[, scheme: ‘http’]]

  • proxy (URI) —

    Proxy host as a URI object

  • connect_timeout (Float) —

    Request-specific connect timeout (in seconds)

  • socket_timeout (Float) —

    Request-specific socket timeout (in seconds)

  • request_timeout (Float) —

    Request-specific request timeout (in seconds)

  • max_redirects (Integer) —

    Request-specific maximum redirect limit

  • follow_redirects (Boolean) —

    Specify whether this request should follow redirects

  • auth (Hash) —

    Specify authentication for the request

  • auth[:user] (String) —

    Username to auth with

  • auth[:password] (String) —

    Password to auth with

  • auth[:eager] (Boolean) —

    Eagerly offer the Authorization header before the server challenges for it. You should not use this unless you know you specifically need it, as misuse of it can leak user credentials.

Returns:

Raises:



276
277
278
279
 
# File 'lib/manticore/client.rb', line 276

def head(url, options = {}, &block)
  options = treat_params_as_query(options)
  request HttpHead, url, options, &block
end

#http(method, url, options = {}, &block) ⇒ Response

Perform an HTTP request, passing the method as a parameter

Parameters:

  • method (String, Symbol) —

    Method to call (get put head post options patch)

  • url (String) —

    URL to request

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

Options Hash (options):

  • query (Hash) —

    Hash of options to be added to the URL as part of the query string

  • params (Hash) —

    Hash of options to pass as a request body. For GET, HEAD, and DELETE requests, :params will be treated as :query if :query is not present.

  • headers (Hash) —

    Hash of options to pass as additional request headers

  • proxy (String) —

    Proxy host in form: proxy.org:1234

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org’[, port: 80[, scheme: ‘http’]]

  • proxy (URI) —

    Proxy host as a URI object

  • connect_timeout (Float) —

    Request-specific connect timeout (in seconds)

  • socket_timeout (Float) —

    Request-specific socket timeout (in seconds)

  • request_timeout (Float) —

    Request-specific request timeout (in seconds)

  • max_redirects (Integer) —

    Request-specific maximum redirect limit

  • follow_redirects (Boolean) —

    Specify whether this request should follow redirects

  • auth (Hash) —

    Specify authentication for the request

  • auth[:user] (String) —

    Username to auth with

  • auth[:password] (String) —

    Password to auth with

  • auth[:eager] (Boolean) —

    Eagerly offer the Authorization header before the server challenges for it. You should not use this unless you know you specifically need it, as misuse of it can leak user credentials.

Returns:

Raises:



316
317
318
319
320
321
322
323
 
# File 'lib/manticore/client.rb', line 316

def http(method, url, options = {}, &block)
  case method.to_s.downcase
  when *%w(get put head post delete options patch)
    send method, url, options, &block
  else
    raise "Invalid method: #{method}"
  end
end

#options(url, options = {}, &block) ⇒ Response

Perform a HTTP OPTIONS request

Examples:

Simple usage

body = client.options("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).body

Passing a block as the success handler:

body = client.options("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}) {|response| response.body }

Explicit success handler:

body = client.options("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).
  on_success {|response| response.body }

Parameters:

  • url (String) —

    URL to request

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

Options Hash (options):

  • query (Hash) —

    Hash of options to be added to the URL as part of the query string

  • params (Hash) —

    Hash of options to pass as a request body. For GET, HEAD, and DELETE requests, :params will be treated as :query if :query is not present.

  • headers (Hash) —

    Hash of options to pass as additional request headers

  • proxy (String) —

    Proxy host in form: proxy.org:1234

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org’[, port: 80[, scheme: ‘http’]]

  • proxy (URI) —

    Proxy host as a URI object

  • connect_timeout (Float) —

    Request-specific connect timeout (in seconds)

  • socket_timeout (Float) —

    Request-specific socket timeout (in seconds)

  • request_timeout (Float) —

    Request-specific request timeout (in seconds)

  • max_redirects (Integer) —

    Request-specific maximum redirect limit

  • follow_redirects (Boolean) —

    Specify whether this request should follow redirects

  • auth (Hash) —

    Specify authentication for the request

  • auth[:user] (String) —

    Username to auth with

  • auth[:password] (String) —

    Password to auth with

  • auth[:eager] (Boolean) —

    Eagerly offer the Authorization header before the server challenges for it. You should not use this unless you know you specifically need it, as misuse of it can leak user credentials.

Returns:

Raises:



296
297
298
 
# File 'lib/manticore/client.rb', line 296

def options(url, options = {}, &block)
  request HttpOptions, url, options, &block
end

#patch(url, options = {}, &block) ⇒ Response

Perform a HTTP PATCH request

Examples:

Simple usage

body = client.patch("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).body

Passing a block as the success handler:

body = client.patch("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}) {|response| response.body }

Explicit success handler:

body = client.patch("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).
  on_success {|response| response.body }

Parameters:

  • url (String) —

    URL to request

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

Options Hash (options):

  • query (Hash) —

    Hash of options to be added to the URL as part of the query string

  • params (Hash) —

    Hash of options to pass as a request body. For GET, HEAD, and DELETE requests, :params will be treated as :query if :query is not present.

  • headers (Hash) —

    Hash of options to pass as additional request headers

  • proxy (String) —

    Proxy host in form: proxy.org:1234

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org’[, port: 80[, scheme: ‘http’]]

  • proxy (URI) —

    Proxy host as a URI object

  • connect_timeout (Float) —

    Request-specific connect timeout (in seconds)

  • socket_timeout (Float) —

    Request-specific socket timeout (in seconds)

  • request_timeout (Float) —

    Request-specific request timeout (in seconds)

  • max_redirects (Integer) —

    Request-specific maximum redirect limit

  • follow_redirects (Boolean) —

    Specify whether this request should follow redirects

  • auth (Hash) —

    Specify authentication for the request

  • auth[:user] (String) —

    Username to auth with

  • auth[:password] (String) —

    Password to auth with

  • auth[:eager] (Boolean) —

    Eagerly offer the Authorization header before the server challenges for it. You should not use this unless you know you specifically need it, as misuse of it can leak user credentials.

  • body (String) —

    Body to pass with the request

Returns:

Raises:



302
303
304
 
# File 'lib/manticore/client.rb', line 302

def patch(url, options = {}, &block)
  request HttpPatch, url, options, &block
end

#pool_stats ⇒ Object

Return a hash of statistics about this client’s HTTP connection pool



249
250
251
252
253
254
255
256
257
 
# File 'lib/manticore/client.rb', line 249

def pool_stats
  stats = @pool.get_total_stats
  {
    max: stats.get_max,
    leased: stats.get_leased,
    pending: stats.get_pending,
    available: stats.get_available,
  }
end

#post(url, options = {}, &block) ⇒ Response

Perform a HTTP POST request

Examples:

Simple usage

body = client.post("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).body

Passing a block as the success handler:

body = client.post("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}) {|response| response.body }

Explicit success handler:

body = client.post("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).
  on_success {|response| response.body }

Parameters:

  • url (String) —

    URL to request

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

Options Hash (options):

  • query (Hash) —

    Hash of options to be added to the URL as part of the query string

  • params (Hash) —

    Hash of options to pass as a request body. For GET, HEAD, and DELETE requests, :params will be treated as :query if :query is not present.

  • headers (Hash) —

    Hash of options to pass as additional request headers

  • proxy (String) —

    Proxy host in form: proxy.org:1234

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org’[, port: 80[, scheme: ‘http’]]

  • proxy (URI) —

    Proxy host as a URI object

  • connect_timeout (Float) —

    Request-specific connect timeout (in seconds)

  • socket_timeout (Float) —

    Request-specific socket timeout (in seconds)

  • request_timeout (Float) —

    Request-specific request timeout (in seconds)

  • max_redirects (Integer) —

    Request-specific maximum redirect limit

  • follow_redirects (Boolean) —

    Specify whether this request should follow redirects

  • auth (Hash) —

    Specify authentication for the request

  • auth[:user] (String) —

    Username to auth with

  • auth[:password] (String) —

    Password to auth with

  • auth[:eager] (Boolean) —

    Eagerly offer the Authorization header before the server challenges for it. You should not use this unless you know you specifically need it, as misuse of it can leak user credentials.

  • body (String) —

    Body to pass with the request

Returns:

Raises:



283
284
285
 
# File 'lib/manticore/client.rb', line 283

def post(url, options = {}, &block)
  request HttpPost, url, options, &block
end

#put(url, options = {}, &block) ⇒ Response

Perform a HTTP PUT request

Examples:

Simple usage

body = client.put("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).body

Passing a block as the success handler:

body = client.put("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}) {|response| response.body }

Explicit success handler:

body = client.put("http://example.com/some/resource", params: {foo: "bar"}, headers: {"X-Custom-Header" => "whee"}).
  on_success {|response| response.body }

Parameters:

  • url (String) —

    URL to request

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

Options Hash (options):

  • query (Hash) —

    Hash of options to be added to the URL as part of the query string

  • params (Hash) —

    Hash of options to pass as a request body. For GET, HEAD, and DELETE requests, :params will be treated as :query if :query is not present.

  • headers (Hash) —

    Hash of options to pass as additional request headers

  • proxy (String) —

    Proxy host in form: proxy.org:1234

  • proxy (Hash) —

    Proxy host in form: ‘proxy.org’[, port: 80[, scheme: ‘http’]]

  • proxy (URI) —

    Proxy host as a URI object

  • connect_timeout (Float) —

    Request-specific connect timeout (in seconds)

  • socket_timeout (Float) —

    Request-specific socket timeout (in seconds)

  • request_timeout (Float) —

    Request-specific request timeout (in seconds)

  • max_redirects (Integer) —

    Request-specific maximum redirect limit

  • follow_redirects (Boolean) —

    Specify whether this request should follow redirects

  • auth (Hash) —

    Specify authentication for the request

  • auth[:user] (String) —

    Username to auth with

  • auth[:password] (String) —

    Password to auth with

  • auth[:eager] (Boolean) —

    Eagerly offer the Authorization header before the server challenges for it. You should not use this unless you know you specifically need it, as misuse of it can leak user credentials.

  • body (String) —

    Body to pass with the request

Returns:

Raises:



270
271
272
 
# File 'lib/manticore/client.rb', line 270

def put(url, options = {}, &block)
  request HttpPut, url, options, &block
end

#stub(url, stubs) ⇒ Object

Cause this client to return a stubbed response for this URL

Parameters:

  • url (String) —

    URL to stub for

  • stubs (Hash) —

    Hash of options to return for the stubbed response



328
329
330
 
# File 'lib/manticore/client.rb', line 328

def stub(url, stubs)
  @stubs[url_as_regex(url)] = stubs
end

#unstub(url) ⇒ Object

Cause this client to unstubbed previously-stubbed URL



333
334
335
 
# File 'lib/manticore/client.rb', line 333

def unstub(url)
  @stubs.delete(url_as_regex(url))
end