Class: HTTPX::Session

Inherits:
Object
  • Object
show all
Includes:
Chainable, Loggable, ForkTracker
Defined in:
lib/httpx/session.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

Defined Under Namespace

Modules: ForkTracker

Constant Summary

Constants included from Loggable

Loggable::COLORS, Loggable::USE_DEBUG_LOG

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, #log_redact

Methods included from ForkTracker

#_fork

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.



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

def initialize(options = EMPTY_HASH, &blk)
  @options = self.class.default_options.merge(options)
  @persistent = @options.persistent
  @pool = @options.pool_class.new(@options.pool_options)
  @wrapped = false
  @closing = false
  INSTANCES[self] = self if @persistent && @options.close_on_fork && INSTANCES
  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.



490
491
492
 
# File 'lib/httpx/session.rb', line 490

def default_options
  @default_options
end

Class Method Details

.inherited(klass) ⇒ Object 



492
493
494
495
496
497
 
# File 'lib/httpx/session.rb', line 492

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)

Raises:

  • (ArgumentError) 


504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
 
# File 'lib/httpx/session.rb', line 504

def plugin(pl, options = nil, &block)
  label = pl
  # raise Error, "Cannot add a plugin to a frozen config" if frozen?
  pl = Plugins.load_plugin(pl) if pl.is_a?(Symbol)
  raise ArgumentError, "Invalid plugin type: #{pl.class.inspect}" unless pl.is_a?(Module)

  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)
      # when a class gets dup'ed, the #initialize_dup callbacks isn't triggered.
      # moreover, and because #method_added does not get triggered on mixin include,
      # the callback is also forcefully manually called here.
      opts.options_class.instance_variable_set(:@options_names, opts.options_class.options_names.dup)
      (pl::OptionsMethods.instance_methods + pl::OptionsMethods.private_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

    if pl.respond_to?(:subplugins)
      pl.subplugins.transform_keys(&Plugins.method(:load_plugin)).each do |main_pl, sub_pl|
        # in case the main plugin has already been loaded, then apply subplugin functionality
        # immediately
        next unless @plugins.include?(main_pl)

        plugin(sub_pl, options, &block)
      end
    end

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

    if label.is_a?(Symbol)
      # in case an already-loaded plugin complements functionality of
      # the plugin currently being loaded, loaded it now
      @plugins.each do |registered_pl|
        next if registered_pl == pl

        next unless registered_pl.respond_to?(:subplugins)

        sub_pl = registered_pl.subplugins[label]

        next unless sub_pl

        plugin(sub_pl, options, &block)
      end
    end

    @default_options.freeze
    set_temporary_name("#{superclass}/#{pl}") if respond_to?(:set_temporary_name) # ruby 3.4 only
  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)



114
115
116
117
118
119
120
 
# File 'lib/httpx/session.rb', line 114

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(selector = Selector.new) ⇒ Object

closes all the active connections from the session.

when called directly without specifying selector, all available connections will be picked up from the connection pool and closed. Connections in use by other sessions, or same session in a different thread, will not be reaped.



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

def close(selector = Selector.new)
  # throw resolvers away from the pool
  @pool.reset_resolvers

  # preparing to throw away connections
  while (connection = @pool.pop_connection)
    next if connection.state == :closed

    select_connection(connection, selector)
  end

  selector_close(selector)
end

#deselect_connection(connection, selector, cloned = false) ⇒ Object 



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/httpx/session.rb', line 134

def deselect_connection(connection, selector, cloned = false)
  connection.log(level: 2) do
    "deregistering connection##{connection.object_id}(#{connection.state}) from selector##{selector.object_id}"
  end
  selector.deregister(connection)

  # when connections coalesce
  return if connection.state == :idle

  return if cloned

  return if @closing && connection.state == :closed

  connection.log(level: 2) { "check-in connection##{connection.object_id}(#{connection.state}) in pool##{@pool.object_id}" }
  @pool.checkin_connection(connection)
end

#deselect_resolver(resolver, selector) ⇒ Object 



151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/httpx/session.rb', line 151

def deselect_resolver(resolver, selector)
  resolver.log(level: 2) do
    "deregistering resolver##{resolver.object_id}(#{resolver.state}) from selector##{selector.object_id}"
  end
  selector.deregister(resolver)

  return if @closing && resolver.closed?

  resolver.log(level: 2) { "check-in resolver##{resolver.object_id}(#{resolver.state}) in pool##{@pool.object_id}" }
  @pool.checkin_resolver(resolver)
end

#find_connection(request_uri, selector, options) ⇒ Object

returns the HTTPX::Connection through which the request should be sent through.



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/httpx/session.rb', line 179

def find_connection(request_uri, selector, options)
  if (connection = selector.find_connection(request_uri, options))
    connection.idling if connection.state == :closed
    connection.log(level: 2) { "found connection##{connection.object_id}(#{connection.state}) in selector##{selector.object_id}" }
    return connection
  end

  connection = @pool.checkout_connection(request_uri, options)

  connection.log(level: 2) { "found connection##{connection.object_id}(#{connection.state}) in pool##{@pool.object_id}" }

  case connection.state
  when :idle
    do_init_connection(connection, selector)
  when :open
    if options.io
      select_connection(connection, selector)
    else
      pin_connection(connection, selector)
    end
  when :closing, :closed
    connection.idling
    if connection.addresses?
      select_connection(connection, selector)
    else
      # if addresses expired, resolve again
      resolve_connection(connection, selector)
    end
  else
    pin_connection(connection, selector)
  end

  connection
end

#pin_connection(connection, selector) ⇒ Object 



127
128
129
130
 
# File 'lib/httpx/session.rb', line 127

def pin_connection(connection, selector)
  connection.current_session = self
  connection.current_selector = selector
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) 


98
99
100
101
102
103
104
105
106
 
# File 'lib/httpx/session.rb', line 98

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

#select_connection(connection, selector) ⇒ Object Also known as: select_resolver 



122
123
124
125
 
# File 'lib/httpx/session.rb', line 122

def select_connection(connection, selector)
  pin_connection(connection, selector)
  selector.register(connection)
end

#try_clone_connection(connection, selector, family) ⇒ Object 



163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/httpx/session.rb', line 163

def try_clone_connection(connection, selector, family)
  connection.family ||= family

  return connection if connection.family == family

  new_connection = connection.class.new(connection.origin, connection.options)

  new_connection.family = family

  connection.sibling = new_connection

  do_init_connection(new_connection, selector)
  new_connection
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



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/httpx/session.rb', line 31

def wrap
  prev_wrapped = @wrapped
  @wrapped = true
  was_initialized = false
  current_selector = get_current_selector do
    selector = Selector.new

    set_current_selector(selector)

    was_initialized = true

    selector
  end
  begin
    yield self
  ensure
    unless prev_wrapped
      if @persistent
        deactivate(current_selector)
      else
        close(current_selector)
      end
    end
    @wrapped = prev_wrapped
    set_current_selector(nil) if was_initialized
  end
end