mirror of
https://github.com/samsonjs/http-cookie.git
synced 2026-04-15 12:15:51 +00:00
134 lines
3.6 KiB
Markdown
134 lines
3.6 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](https://github.com/sparklemotion/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`/`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
|
|
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
|