mirror of
https://github.com/samsonjs/http-cookie.git
synced 2026-03-25 08:55:53 +00:00
131 lines
3.4 KiB
Markdown
131 lines
3.4 KiB
Markdown
# 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(set_cookie_header_value, origin: uri) { |cookie|
|
|
jar << cookie
|
|
}
|
|
|
|
# Get the value for the Cookie field of a request header
|
|
cookie_header_value = jar.cookies(uri).join(', ')
|
|
|
|
# Save to a file
|
|
jar.save(filename)
|
|
|
|
|
|
########################
|
|
# Server side example
|
|
########################
|
|
|
|
# Generate a cookie
|
|
cookies = 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
|
|
set_cookie_header_value = cookies.set_cookie_value(my_url)
|
|
|
|
|
|
## Incompatibilities with Mechanize::Cookie and CookieJar
|
|
|
|
There are several incompatibilities with Mechanize::Cookie and
|
|
CookieJar. Below is how to rewrite existing code written for
|
|
Mechanize::Cookie with equivalent using HTTP::Cookie:
|
|
|
|
- Mechanize::Cookie.parse
|
|
|
|
# before
|
|
cookie1 = Mechanize::Cookie.parse(uri, set_cookie1)
|
|
cookie2 = Mechanize::Cookie.parse(uri, set_cookie2, log)
|
|
|
|
# after
|
|
cookie1 = HTTP::Cookie.parse(set_cookie1, :origin => uri)
|
|
cookie2 = HTTP::Cookie.parse(set_cookie2, :origin => uri, :logger => log)
|
|
|
|
- Mechanize::Cookie#set_domain
|
|
|
|
# before
|
|
cookie.set_domain(domain)
|
|
|
|
# after
|
|
cookie.domain = domain
|
|
|
|
- Mechanize::CookieJar#add, #add!
|
|
|
|
# before
|
|
jar.add!(cookie1)
|
|
jar.add(uri, cookie2)
|
|
|
|
# after
|
|
jar.add(cookie1)
|
|
cookie2.origin = uri; jar.add(cookie2) # 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 and CookieJar raises runtime errors to help migration, so
|
|
try running your test code once to find out how to fix your code base.
|
|
|
|
The YAML serialization format has changed. Loading YAML files
|
|
generated by Mechanize::CookieJar#save_as will not raise an exception,
|
|
but the content is simply ignored. Note that there is (obviously) no
|
|
forward compatibillity in the YAML serialization. Trying to load a
|
|
YAML file saved by HTTP::CookieJar with Mechanize::CookieJar will fail
|
|
in ArgumentError.
|
|
|
|
On the other hand, there has been (and will ever be) no change in the
|
|
cookies.txt format.
|
|
|
|
## Contributing
|
|
|
|
1. Fork it
|
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
|
4. Push to the branch (`git push origin my-new-feature`)
|
|
5. Create new Pull Request
|