-
-
16 Jun 2021 09:35:30 UTC
- Distribution: HTTP-CookieJar
- Module version: 0.012
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues (1)
- Testers (2740 / 0 / 0)
- Kwalitee
Bus factor: 1- 78.55% Coverage
- License: apache_2_0
- Perl: v5.8.1
- Activity
24 month- Tools
- Download (27.56KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 2 contributors-
Dan Book
-
jvolkening
- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- CONSTRUCTORS
- METHODS
- LIMITATIONS AND CAVEATS
- SEE ALSO
- SUPPORT
- AUTHOR
- CONTRIBUTORS
- COPYRIGHT AND LICENSE
NAME
HTTP::CookieJar - A minimalist HTTP user agent cookie jar
VERSION
version 0.012
SYNOPSIS
use HTTP::CookieJar; my $jar = HTTP::CookieJar->new; # add cookie received from a request $jar->add( "http://www.example.com/", "CUSTOMER=WILE_E_COYOTE; Path=/; Domain=example.com" ); # extract cookie header for a given request my $cookie = $jar->cookie_header( "http://www.example.com/" );
DESCRIPTION
This module implements a minimalist HTTP user agent cookie jar in conformance with RFC 6265.
Unlike the commonly used HTTP::Cookies module, this module does not require use of HTTP::Request and HTTP::Response objects. An LWP-compatible adapter is available as HTTP::CookieJar::LWP.
CONSTRUCTORS
new
my $jar = HTTP::CookieJar->new;
Return a new, empty cookie jar
METHODS
add
$jar->add( "http://www.example.com/", "lang=en-US; Path=/; Domain=example.com" );
Given a request URL and a
Set-Cookie
header string, attempts to adds the cookie to the jar. If the cookie is expired, instead it deletes any matching cookie from the jar. AMax-Age
attribute will be converted to an absoluteExpires
attribute.It will throw an exception if the request URL is missing or invalid. Returns true if successful cookie processing or undef/empty-list on failure.
clear
$jar->clear
Empties the cookie jar.
cookies_for
my @cookies = $jar->cookies_for("http://www.example.com/foo/bar");
Given a request URL, returns a list of hash references representing cookies that should be sent. The hash references are copies -- changing values will not change the cookies in the jar.
Cookies set
secure
will only be returned if the request scheme ishttps
. Expired cookies will not be returned.Keys of a cookie hash reference might include:
name -- the name of the cookie
value -- the value of the cookie
domain -- the domain name to which the cookie applies
path -- the path to which the cookie applies
expires -- if present, when the cookie expires in epoch seconds
secure -- if present, the cookie was set
Secure
httponly -- if present, the cookie was set
HttpOnly
hostonly -- if present, the cookie may only be used with the domain as a host
creation_time -- epoch seconds since the cookie was first stored
last_access_time -- epoch seconds since the cookie was last stored
Keep in mind that
httponly
means it should only be used in requests and not made available via Javascript, etc. This is pretty meaningless for Perl user agents.Generally, user agents should use the
cookie_header
method instead.It will throw an exception if the request URL is missing or invalid.
cookie_header
my $header = $jar->cookie_header("http://www.example.com/foo/bar");
Given a request URL, returns a correctly-formatted string with all relevant cookies for the request. This string is ready to be used in a
Cookie
header in an HTTP request. E.g.:SID=31d4d96e407aad42; lang=en-US
It follows the same exclusion rules as
cookies_for
.If the request is invalid or no cookies apply, it will return an empty string.
dump_cookies
my @list = $jar->dump_cookies; my @list = $jar->dump_cookies( { persistent => 1 } );
Returns a list of raw cookies in string form. The strings resemble what would be received from
Set-Cookie
headers, but with additional internal fields. The list is only intended for use withload_cookies
to allow cookie jar persistence.If a hash reference with a true
persistent
key is given as an argument, cookies without anExpires
time (i.e. "session cookies") will be omitted.Here is a trivial example of saving a cookie jar file with Path::Tiny:
path("jar.txt")->spew( join "\n", $jar->dump_cookies );
load_cookies
$jar->load_cookies( @cookies );
Given a list of cookie strings from
dump_cookies
, it adds them to the cookie jar. Cookies added in this way will supersede any existing cookies with similar domain, path and name.It returns the jar object for convenience when loading a new object:
my $jar = HTTP::CookieJar->new->load_cookies( @cookies );
Here is a trivial example of loading a cookie jar file with Path::Tiny:
my $jar = HTTP::CookieJar->new->load_cookies( path("jar.txt")->lines );
LIMITATIONS AND CAVEATS
RFC 6265 vs prior standards
This modules adheres as closely as possible to the user-agent rules of RFC 6265. Therefore, it does not handle nor generate
Set-Cookie2
andCookie2
headers, implement.local
suffixes, or do path/domain matching in accord with prior RFC's.Internationalized domain names
Internationalized domain names given in requests must be properly encoded in ASCII form.
Public suffixes
If Mozilla::PublicSuffix is installed, cookie domains will be checked against the public suffix list. Public suffix cookies are only allowed as host-only cookies.
Third-party cookies
According to RFC 6265, a cookie may be accepted only if has no
Domain
attribute (in which case it is "host-only") or if theDomain
attribute is a suffix of the request URL. This effectively prohibits Site A from setting a cookie for unrelated Site B, which is one potential third-party cookie vector.SEE ALSO
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker at https://github.com/dagolden/HTTP-CookieJar/issues. You will be notified automatically of any progress on your issue.
Source Code
This is open source software. The code repository is available for public review and contribution under the terms of the license.
https://github.com/dagolden/HTTP-CookieJar
git clone https://github.com/dagolden/HTTP-CookieJar.git
AUTHOR
David Golden <dagolden@cpan.org>
CONTRIBUTORS
Dan Book <grinnz@grinnz.com>
David Golden <xdg@xdg.me>
jvolkening <jdv@base2bio.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2013 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
Module Install Instructions
To install HTTP::CookieJar, copy and paste the appropriate command in to your terminal.
cpanm HTTP::CookieJar
perl -MCPAN -e shell install HTTP::CookieJar
For more information on module installation, please visit the detailed CPAN module installation guide.