HTTP::Session
HTTP::Session - a session abstraction for http.rb in order to support Cookies and Caching.
require "http-session"
require "logger"
http = HTTP.session(
cookies: true,
cache: {private: true, store: [:file_store, "./tmp/cache"]},
persistent: {pools: {"https://httpbin.org" => true}}
)
.timeout(8)
.follow
.use(logging: {logger: Logger.new($stdout)})
.freeze
http.get("https://httpbin.org/get")
Quickstart
Install
Add this line to your application's Gemfile:
gem 'ruby-http-session', require: "http-session"
Cookies
Use cookies: true
to enable this feature. Once enabled, the cookies are
automatically set each time a request is made.
require "http-session"
http = HTTP.session(cookies: true)
.freeze
r = http.get("https://httpbin.org/cookies/set/mycookies/abc", follow: true)
pp JSON.parse(r.body)["cookies"]
r = http.get("https://httpbin.org/cookies")
pp JSON.parse(r.body)["cookies"]
Caching
Use cache: true
to enable this feature. Once enabled, the Cache-Control
will be used to determine whether the response is cacheable or not.
require "http-session"
http = HTTP.session(cache: true)
.freeze
60.times do
http.get("https://cdn.jsdelivr.net/npm/jquery@3.6.4/dist/jquery.min.js")
end
Persistent Connections (Keep-Alive)
Use persistent: true
to enable this feature. Once enabled, the connection pools
will be used to manage persistent connections.
require "http-session"
http = HTTP.session(persistent: true)
.freeze
http.get("https://httpbin.org/get")
http.get("https://httpbin.org/get")
http.get("https://example.org")
http.get("https://example.org")
Reference
Caching
When responses can be reused from a cache, taking into account HTTP RFC 9111 rules for user agents and
shared caches. The following headers are used to determine whether the response is cacheable or not:
Cache-Control
request header
Cache-Control
response header
no-store
no-cache
private
public
max-age
s-maxage
Etag
& Last-Modified
response header for conditional requestsVary
response header for content negotiation
Shared Cache
A shared cache is a cache that stores responses for reuse by more than one user; shared caches
are usually (but not always) deployed as a part of an intermediary. This is used by default.
Note: Responses for requests with Authorization header fields will not be stored in a shared
cache unless explicitly allowed. Read rfc9111#section-3.5 for more.
http = HTTP.session(cache: true)
.freeze
res = http.get("https://cdn.jsdelivr.net/npm/jquery@3.6.4/dist/jquery.min.js")
pp "Cache-Status: #{res.headers["X-Httprb-Cache-Status"]}"
res = http.get("https://cdn.jsdelivr.net/npm/jquery@3.6.4/dist/jquery.min.js")
pp "Cache-Status: #{res.headers["X-Httprb-Cache-Status"]}"
res = http.get("https://cdn.jsdelivr.net/npm/jquery@3.6.4/dist/jquery.min.js", headers: {"Cache-Control" => "no-cache"})
pp "Cache-Status: #{res.headers["X-Httprb-Cache-Status"]}"
res = http.get("https://cdn.jsdelivr.net/npm/jquery@3.6.4/dist/jquery.min.js", headers: {"Cache-Control" => "no-store"})
pp "Cache-Status: #{res.headers["X-Httprb-Cache-Status"]}"
Private Cache
A private cache, in contrast, is dedicated to a single user; often, they are deployed as a
component of a user agent.
http = HTTP.session(cache: {private: true})
.freeze
Cache Store
The default cache store is ActiveSupport::Cache::MemoryStore
, which resides on the client instance. You
can use ths :store
option to set another store, e.g. ActiveSupport::Cache::MemCacheStore
.
store = ActiveSupport::Cache::MemCacheStore.new("localhost", "server-downstairs.localnetwork:8229")
http = HTTP.session(cache: {store: store})
.freeze
Cache Status
The following value is used in the X-Httprb-Cache-Status
response header:
- HIT: found in cache
- REVALIDATED: found in cache but stale, revalidated success
- EXPIRED: found in cache but stale, revalidated failure, served from the origin server
- MISS: not found in cache, served from the origin server
- UNCACHEABLE: the request can not use cached response
Persistent Connections (Keep-Alive)
http = HTTP.session(persistent: {
pools: {
"https://example.org" => false,
"https://httpbin.org" => {maxsize: 2},
"*" => true
}
}).freeze
http.get("https://example.org")
http.get("https://httpbin.org/get")
http.get("https://github.com")
Thread Safe
The following HTTP::Session methods are thread-safe:
- head
- get
- post
- put
- delete
- trace
- options
- connect
- patch
- request
HTTP::Features
logging
Log requests and responses.
require "http-session"
require "logger"
http = HTTP.session
.use(logging: { logger: Logger.new($stdout) })
.freeze
http.get("https://httpbin.org/get")
instrumentation
Instrument requests and responses. Expects an ActiveSupport::Notifications-compatible instrumenter.
require "http-session"
require "active_support/all"
ActiveSupport::Notifications.subscribe('start_request.http') do |name, start, finish, id, payload|
pp start: start, req: payload[:request].inspect
end
ActiveSupport::Notifications.subscribe('request.http') do |name, start, finish, id, payload|
pp start: start, req: payload[:request].inspect, res: payload[:response].inspect
end
http = HTTP.session
.use(instrumentation: { instrumenter: ActiveSupport::Notifications.instrumenter })
.freeze
http.get("https://httpbin.org/get")
hsf_auto_inflate
Simlar to auto_inflate
, used for automatically decompressing the response body.
require "http-session"
require "brotli"
http = HTTP.session
.use(hsf_auto_inflate: {br: true})
.freeze
res = http.get("https://cdn.jsdelivr.net/npm/jquery@3.6.4/dist/jquery.min.js", headers: {"Accept-Encoding" => "br"})
pp res.body.to_s
Intergate with WebMock
require "http-session/webmock"
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and the created tag, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/souk4711/http-session. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the HTTP::Session project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.