HTTP::Cookie
HTTP::Cookie
is a ruby library to handle HTTP cookies in a way both
compliant with RFCs and compatible with today's major browsers.
It was originally a part of the Mechanize library, separated as an independent library in the hope of serving as a common component that is reusable from any HTTP related piece of software.
Installation
Add this line to your application's Gemfile
:
gem 'http-cookie'
And then execute:
$ bundle
Or install it yourself as:
$ gem install http-cookie
Usage
########################
# Client side example
########################
# Initialize a cookie jar
jar = HTTP::CookieJar.new
# Load from a file
jar.load(filename) if File.exist?(filename)
# Store received cookies
HTTP::Cookie.parse(, origin: uri) { ||
jar <<
}
# Get the value for the Cookie field of a request header
= jar.(uri).join(', ')
# Save to a file
jar.save(filename)
########################
# Server side example
########################
# Generate a cookie
= HTTP::Cookie.new("uid", "a12345", domain: 'example.org',
for_domain: true,
path: '/',
max_age: 7*86400)
# Get the value for the Set-Cookie field of a response header
= .(my_url)
Incompatibilities with Mechanize::Cookie
/CookieJar
There are several incompatibilities between
Mechanize::Cookie
/CookieJar
and HTTP::Cookie
/CookieJar
. Below
is how to rewrite existing code written for Mechanize::Cookie
with
equivalent using HTTP::Cookie
:
Mechanize::Cookie.parse
# before = Mechanize::Cookie.parse(uri, ) = Mechanize::Cookie.parse(uri, , log) # after = HTTP::Cookie.parse(, :origin => uri) = HTTP::Cookie.parse(, :origin => uri, :logger => log)
Mechanize::Cookie#set_domain
# before .set_domain(domain) # after .domain = domain
Mechanize::CookieJar#add
,#add!
# before jar.add!() jar.add(uri, ) # after jar.add() .origin = uri; jar.add() # or specify origin in parse() or new()
Mechanize::CookieJar#clear!
# before jar.clear! # after jar.clear
Mechanize::CookieJar#save_as
# before jar.save_as(file) # after jar.save(file)
HTTP::Cookie
/CookieJar
raise runtime errors to help migration, so
after replacing the class names, try running your test code once to
find out how to fix your code base.
File formats
The YAML serialization format has changed, and HTTP::CookieJar#load
cannot import what is written in a YAML file saved by
Mechanize::CookieJar#save_as
. HTTP::CookieJar#load
will not raise
an exception if an incompatible YAML file is given, but the content is
silently ignored.
Note that there is (obviously) no forward compatibillity with this.
Trying to load a YAML file saved by HTTP::CookieJar
with
Mechanize::CookieJar
will fail in runtime error.
On the other hand, there has been (and will ever be) no change in the cookies.txt format, so use it instead if compatibility is required.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request