Class: HTTP::Session

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Chainable
Defined in:
lib/http/session.rb

Overview

Thread-safe options builder for configuring HTTP requests.

Session objects are returned by all chainable configuration methods (e.g., Chainable#headers, Chainable#timeout, Chainable#cookies). They hold an immutable Options object and create a new Client for each request, making them safe to share across threads.

When configured for persistent connections (via Chainable#persistent), the session maintains a pool of Client instances keyed by origin, enabling connection reuse within the same origin and transparent cross-origin redirect handling.

Examples:

Reuse a configured session across threads

session = HTTP.headers("Accept" => "application/json").timeout(10)
threads = 5.times.map do
  Thread.new { session.get("https://example.com") }
end
threads.each(&:join)

Persistent session with cross-origin redirects

HTTP.persistent("https://example.com").follow do |http|
  http.get("/redirect-to-other-domain")  # follows cross-origin redirect
end

See Also:

Constant Summary

Constants included from Chainable

Chainable::PROXY_ARG_MAP

Instance Method Summary collapse

Methods included from Chainable

#accept, #auth, #base_uri, #basic_auth, #cookies, #default_options, #default_options=, #digest_auth, #encoding, #follow, #headers, #nodelay, #persistent, #retriable, #timeout, #use, #via

Methods included from Chainable::Verbs

#connect, #delete, #get, #head, #options, #patch, #post, #put, #trace

Methods included from Base64

encode64

Constructor Details

#initialize(default_options = nil, clients: nil) ⇒ HTTP::Session

Initialize a new Session

Examples:

session = HTTP::Session.new(headers: {"Accept" => "application/json"})

Parameters:

  • default_options (HTTP::Options, nil) (defaults to: nil) —

    existing options instance

  • clients (Hash, nil) (defaults to: nil) —

    shared connection pool (internal use)

  • options (Hash) —

    keyword options (see HTTP::Options#initialize)



63
64
65
66
 
# File 'lib/http/session.rb', line 63

def initialize(default_options = nil, clients: nil, **)
  @default_options = HTTP::Options.new(default_options, **)
  @clients = clients || {}
end

Instance Method Details

#close ⇒ void

This method returns an undefined value.

Close all persistent connections held by this session

When the session is persistent, this closes every pooled Client and clears the pool. Safe to call on non-persistent sessions (no-op).

Examples:

session = HTTP.persistent("https://example.com")
session.get("/")
session.close



80
81
82
83
 
# File 'lib/http/session.rb', line 80

def close
  @clients.each_value(&:close)
  @clients.clear
end

#persistent? ⇒ Boolean

Indicate whether the session has persistent connection options

Examples:

session = HTTP::Session.new(persistent: "http://example.com")
session.persistent?

Returns:

  • (Boolean)

See Also:



51
 
# File 'lib/http/session.rb', line 51

def_delegator :default_options, :persistent?

#request(verb, uri, headers: nil, params: nil, form: nil, json: nil, body: nil, response: nil, encoding: nil, follow: nil, ssl: nil, ssl_context: nil, proxy: nil, nodelay: nil, features: nil, retriable: nil, socket_class: nil, ssl_socket_class: nil, timeout_class: nil, timeout_options: nil, keep_alive_timeout: nil, base_uri: nil, persistent: nil) {|response| ... } ⇒ HTTP::Response, Object

Make an HTTP request

For non-persistent sessions a fresh Client is created for each request, ensuring thread safety. For persistent sessions the pooled Client for the request’s origin is reused.

Manages cookies across redirect hops when following redirects.

Examples:

Without a block

session = HTTP::Session.new
session.request(:get, "https://example.com")

With a block (auto-closes connection)

session = HTTP::Session.new
session.request(:get, "https://example.com") { |res| res.status }

Parameters:

  • verb (Symbol) —

    the HTTP method

  • uri (#to_s) —

    the URI to request

Yield Parameters:

Returns:



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/http/session.rb', line 106

def request(verb, uri,
            headers: nil, params: nil, form: nil, json: nil, body: nil,
            response: nil, encoding: nil, follow: nil, ssl: nil, ssl_context: nil,
            proxy: nil, nodelay: nil, features: nil, retriable: nil,
            socket_class: nil, ssl_socket_class: nil, timeout_class: nil,
            timeout_options: nil, keep_alive_timeout: nil, base_uri: nil, persistent: nil, &block)
  merged = default_options.merge(
    { headers: headers, params: params, form: form, json: json, body: body,
      response: response, encoding: encoding, follow: follow, ssl: ssl,
      ssl_context: ssl_context, proxy: proxy, nodelay: nodelay, features: features,
      retriable: retriable, socket_class: socket_class, ssl_socket_class: ssl_socket_class,
      timeout_class: timeout_class, timeout_options: timeout_options,
      keep_alive_timeout: keep_alive_timeout, base_uri: base_uri, persistent: persistent }.compact
  )
  client = persistent? ? nil : make_client(default_options)
  res    = perform_request(client, verb, uri, merged)

  return res unless block

  yield res
ensure
  if block
    persistent? ? close : client&.close
  end
end