Class: HTTPX::Session

Inherits:
Object
  • Object
show all
Includes:
Chainable, Loggable
Defined in:
lib/httpx/session.rb,
lib/httpx/session2.rb

Overview

Class implementing the APIs being used publicly.

HTTPX.get(..) #=> delegating to an internal HTTPX::Session object.
HTTPX.plugin(..).get(..) #=> creating an intermediate HTTPX::Session with plugin, then sending the GET request

Constant Summary

Constants included from Loggable

Loggable::COLORS

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Chainable

#accept, #plugin, #with

Methods included from Loggable

#log, #log_exception

Constructor Details

#initialize(options = EMPTY_HASH, &blk) ⇒ Session

initializes the session with a set of options, which will be shared by all requests sent from it.

When pass a block, it’ll yield itself to it, then closes after the block is evaluated.



18
19
20
21
22
23
 
# File 'lib/httpx/session.rb', line 18

def initialize(options = EMPTY_HASH, &blk)
  @options = self.class.default_options.merge(options)
  @responses = {}
  @persistent = @options.persistent
  wrap(&blk) if blk
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class HTTPX::Chainable

Class Attribute Details

.default_options ⇒ Object (readonly)

Returns the value of attribute default_options.



296
297
298
 
# File 'lib/httpx/session.rb', line 296

def default_options
  @default_options
end

Class Method Details

.inherited(klass) ⇒ Object 



298
299
300
301
302
303
 
# File 'lib/httpx/session.rb', line 298

def inherited(klass)
  super
  klass.instance_variable_set(:@default_options, @default_options)
  klass.instance_variable_set(:@plugins, @plugins.dup)
  klass.instance_variable_set(:@callbacks, @callbacks.dup)
end

.plugin(pl, options = nil, &block) ⇒ Object

returns a new HTTPX::Session instance, with the plugin pointed by pl loaded.

session_with_retries = session.plugin(:retries)
session_with_custom = session.plugin(CustomPlugin)



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/httpx/session.rb', line 310

def plugin(pl, options = nil, &block)
  # raise Error, "Cannot add a plugin to a frozen config" if frozen?
  pl = Plugins.load_plugin(pl) if pl.is_a?(Symbol)
  if !@plugins.include?(pl)
    @plugins << pl
    pl.load_dependencies(self, &block) if pl.respond_to?(:load_dependencies)

    @default_options = @default_options.dup

    include(pl::InstanceMethods) if defined?(pl::InstanceMethods)
    extend(pl::ClassMethods) if defined?(pl::ClassMethods)

    opts = @default_options
    opts.extend_with_plugin_classes(pl)
    if defined?(pl::OptionsMethods)

      (pl::OptionsMethods.instance_methods - Object.instance_methods).each do |meth|
        opts.options_class.method_added(meth)
      end
      @default_options = opts.options_class.new(opts)
    end

    @default_options = pl.extra_options(@default_options) if pl.respond_to?(:extra_options)
    @default_options = @default_options.merge(options) if options

    pl.configure(self, &block) if pl.respond_to?(:configure)

    @default_options.freeze
  elsif options
    # this can happen when two plugins are loaded, an one of them calls the other under the hood,
    # albeit changing some default.
    @default_options = pl.extra_options(@default_options) if pl.respond_to?(:extra_options)
    @default_options = @default_options.merge(options) if options

    @default_options.freeze
  end
  self
end

Instance Method Details

#build_request(verb, uri, params = EMPTY_HASH, options = @options) ⇒ Object

returns a HTTP::Request instance built from the HTTP verb, the request uri, and the optional set of request-specific options. This request must be sent through the same session it was built from.

req = session.build_request("GET", "https://server.com")
resp = session.request(req)



84
85
86
87
88
89
90
 
# File 'lib/httpx/session.rb', line 84

def build_request(verb, uri, params = EMPTY_HASH, options = @options)
  rklass = options.request_class
  request = rklass.new(verb, uri, options, params)
  request.persistent = @persistent
  set_request_callbacks(request)
  request
end

#close(*args) ⇒ Object

closes all the active connections from the session



44
45
46
 
# File 'lib/httpx/session.rb', line 44

def close(*args)
  pool.close(*args)
end

#request(*args, **params) ⇒ Object

performs one, or multple requests; it accepts:

  1. one or multiple HTTPX::Request objects;

  2. an HTTP verb, then a sequence of URIs or URI/options tuples;

  3. one or multiple HTTP verb / uri / (optional) options tuples;

when present, the set of options kwargs is applied to all of the sent requests.

respectively returns a single HTTPX::Response response, or all of them in an Array, in the same order.

resp1 = session.request(req1)
resp1, resp2 = session.request(req1, req2)
resp1 = session.request("GET", "https://server.org/a")
resp1, resp2 = session.request("GET", ["https://server.org/a", "https://server.org/b"])
resp1, resp2 = session.request(["GET", "https://server.org/a"], ["GET", "https://server.org/b"])
resp1 = session.request("POST", "https://server.org/a", form: { "foo" => "bar" })
resp1, resp2 = session.request(["POST", "https://server.org/a", form: { "foo" => "bar" }], ["GET", "https://server.org/b"])
resp1, resp2 = session.request("GET", ["https://server.org/a", "https://server.org/b"], headers: { "x-api-token" => "TOKEN" })

Raises:

  • (ArgumentError) 


68
69
70
71
72
73
74
75
76
 
# File 'lib/httpx/session.rb', line 68

def request(*args, **params)
  raise ArgumentError, "must perform at least one request" if args.empty?

  requests = args.first.is_a?(Request) ? args : build_requests(*args, params)
  responses = send_requests(*requests)
  return responses.first if responses.size == 1

  responses
end

#wrap ⇒ Object

Yields itself the block, then closes it after the block is evaluated.

session.wrap do |http|
  http.get("https://wikipedia.com")
end # wikipedia connection closes here



30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/httpx/session.rb', line 30

def wrap
  prev_persistent = @persistent
  @persistent = true
  pool.wrap do
    begin
      yield self
    ensure
      @persistent = prev_persistent
      close unless @persistent
    end
  end
end