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 collapse

EMPTY_HASH = 
{}.freeze

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.



287
288
289
 
# File 'lib/httpx/session.rb', line 287

def default_options
  @default_options
end

Class Method Details

.inherited(klass) ⇒ Object 



289
290
291
292
293
294
 
# File 'lib/httpx/session.rb', line 289

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)



301
302
303
304
305
306
307
308
309
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
 
# File 'lib/httpx/session.rb', line 301

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, options = EMPTY_HASH) ⇒ 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)



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

def build_request(verb, uri, options = EMPTY_HASH)
  rklass = @options.request_class
  options = @options.merge(options) unless options.is_a?(Options)
  request = rklass.new(verb, uri, options)
  request.persistent = @persistent
  set_request_callbacks(request)
  request
end

#close(*args) ⇒ Object

closes all the active connections from the session



42
43
44
 
# File 'lib/httpx/session.rb', line 42

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

#request(*args, **options) ⇒ 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) 


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

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

  requests = args.first.is_a?(Request) ? args : build_requests(*args, options)
  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
 
# File 'lib/httpx/session.rb', line 30

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