HOME

Mini Shell 1.0
Current File : //usr/local/share/man/man3/HTTP::CookieJar.3pm
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTTP::CookieJar 3"
.TH HTTP::CookieJar 3 "2022-07-25" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTTP::CookieJar \- A minimalist HTTP user agent cookie jar
.SH "VERSION"
.IX Header "VERSION"
version 0.014
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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/" );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements a minimalist \s-1HTTP\s0 user agent cookie jar in
conformance with \s-1RFC 6265\s0 <http://tools.ietf.org/html/rfc6265>.
.PP
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.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    my $jar = HTTP::CookieJar\->new;
.Ve
.PP
Return a new, empty cookie jar
.SH "METHODS"
.IX Header "METHODS"
.SS "add"
.IX Subsection "add"
.Vb 3
\&    $jar\->add(
\&        "http://www.example.com/", "lang=en\-US; Path=/; Domain=example.com"
\&    );
.Ve
.PP
Given a request \s-1URL\s0 and a \f(CW\*(C`Set\-Cookie\*(C'\fR header string, attempts to adds the
cookie to the jar.  If the cookie is expired, instead it deletes any matching
cookie from the jar.  A \f(CW\*(C`Max\-Age\*(C'\fR attribute will be converted to an absolute
\&\f(CW\*(C`Expires\*(C'\fR attribute.
.PP
It will throw an exception if the request \s-1URL\s0 is missing or invalid.  Returns true if
successful cookie processing or undef/empty\-list on failure.
.SS "clear"
.IX Subsection "clear"
.Vb 1
\&    $jar\->clear
.Ve
.PP
Empties the cookie jar.
.SS "cookies_for"
.IX Subsection "cookies_for"
.Vb 1
\&    my @cookies = $jar\->cookies_for("http://www.example.com/foo/bar");
.Ve
.PP
Given a request \s-1URL,\s0 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.
.PP
Cookies set \f(CW\*(C`secure\*(C'\fR will only be returned if the request scheme is \f(CW\*(C`https\*(C'\fR.
Expired cookies will not be returned.
.PP
Keys of a cookie hash reference might include:
.IP "\(bu" 4
name \*(-- the name of the cookie
.IP "\(bu" 4
value \*(-- the value of the cookie
.IP "\(bu" 4
domain \*(-- the domain name to which the cookie applies
.IP "\(bu" 4
path \*(-- the path to which the cookie applies
.IP "\(bu" 4
expires \*(-- if present, when the cookie expires in epoch seconds
.IP "\(bu" 4
secure \*(-- if present, the cookie was set \f(CW\*(C`Secure\*(C'\fR
.IP "\(bu" 4
httponly \*(-- if present, the cookie was set \f(CW\*(C`HttpOnly\*(C'\fR
.IP "\(bu" 4
hostonly \*(-- if present, the cookie may only be used with the domain as a host
.IP "\(bu" 4
creation_time \*(-- epoch time when the cookie was first stored
.IP "\(bu" 4
last_access_time \*(-- epoch time when the cookie was last accessed (i.e. \*(L"now\*(R")
.PP
Keep in mind that \f(CW\*(C`httponly\*(C'\fR means it should only be used in requests and not
made available via Javascript, etc.  This is pretty meaningless for Perl user
agents.
.PP
Generally, user agents should use the \f(CW\*(C`cookie_header\*(C'\fR method instead.
.PP
It will throw an exception if the request \s-1URL\s0 is missing or invalid.
.SS "cookie_header"
.IX Subsection "cookie_header"
.Vb 1
\&    my $header = $jar\->cookie_header("http://www.example.com/foo/bar");
.Ve
.PP
Given a request \s-1URL,\s0 returns a correctly-formatted string with all relevant
cookies for the request.  This string is ready to be used in a \f(CW\*(C`Cookie\*(C'\fR header
in an \s-1HTTP\s0 request.  E.g.:
.PP
.Vb 1
\&    SID=31d4d96e407aad42; lang=en\-US
.Ve
.PP
It follows the same exclusion rules as \f(CW\*(C`cookies_for\*(C'\fR.
.PP
If the request is invalid or no cookies apply, it will return an empty string.
.SS "dump_cookies"
.IX Subsection "dump_cookies"
.Vb 2
\&    my @list = $jar\->dump_cookies;
\&    my @list = $jar\->dump_cookies( { persistent => 1 } );
.Ve
.PP
Returns a list of raw cookies in string form.  The strings resemble what
would be received from \f(CW\*(C`Set\-Cookie\*(C'\fR headers, but with additional internal
fields.  The list is only intended for use with \f(CW\*(C`load_cookies\*(C'\fR to allow
cookie jar persistence.
.PP
If a hash reference with a true \f(CW\*(C`persistent\*(C'\fR key is given as an argument,
cookies without an \f(CW\*(C`Expires\*(C'\fR time (i.e. \*(L"session cookies\*(R") will be omitted.
.PP
Here is a trivial example of saving a cookie jar file with Path::Tiny:
.PP
.Vb 1
\&    path("jar.txt")\->spew( join "\en", $jar\->dump_cookies );
.Ve
.SS "load_cookies"
.IX Subsection "load_cookies"
.Vb 1
\&    $jar\->load_cookies( @cookies );
.Ve
.PP
Given a list of cookie strings from \f(CW\*(C`dump_cookies\*(C'\fR, it adds them to
the cookie jar.  Cookies added in this way will supersede any existing
cookies with similar domain, path and name.
.PP
It returns the jar object for convenience when loading a new object:
.PP
.Vb 1
\&    my $jar = HTTP::CookieJar\->new\->load_cookies( @cookies );
.Ve
.PP
Here is a trivial example of loading a cookie jar file with Path::Tiny:
.PP
.Vb 3
\&    my $jar = HTTP::CookieJar\->new\->load_cookies(
\&        path("jar.txt")\->lines
\&    );
.Ve
.SH "LIMITATIONS AND CAVEATS"
.IX Header "LIMITATIONS AND CAVEATS"
.SS "\s-1RFC 6265\s0 vs prior standards"
.IX Subsection "RFC 6265 vs prior standards"
This modules adheres as closely as possible to the user-agent rules
of \s-1RFC 6265. \s0 Therefore, it does not handle nor generate \f(CW\*(C`Set\-Cookie2\*(C'\fR
and \f(CW\*(C`Cookie2\*(C'\fR headers, implement \f(CW\*(C`.local\*(C'\fR suffixes, or do path/domain
matching in accord with prior \s-1RFC\s0's.
.SS "Internationalized domain names"
.IX Subsection "Internationalized domain names"
Internationalized domain names given in requests must be properly
encoded in \s-1ASCII\s0 form.
.SS "Public suffixes"
.IX Subsection "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.
.SS "Third-party cookies"
.IX Subsection "Third-party cookies"
According to \s-1RFC 6265,\s0 a cookie may be accepted only if has no \f(CW\*(C`Domain\*(C'\fR
attribute (in which case it is \*(L"host-only\*(R") or if the \f(CW\*(C`Domain\*(C'\fR attribute is a
suffix of the request \s-1URL. \s0 This effectively prohibits Site A from setting a
cookie for unrelated Site B, which is one potential third-party cookie vector.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
HTTP::Cookies
.IP "\(bu" 4
Mojo::UserAgent::CookieJar
.SH "SUPPORT"
.IX Header "SUPPORT"
.SS "Bugs / Feature Requests"
.IX Subsection "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.
.SS "Source Code"
.IX Subsection "Source Code"
This is open source software.  The code repository is available for
public review and contribution under the terms of the license.
.PP
<https://github.com/dagolden/HTTP\-CookieJar>
.PP
.Vb 1
\&  git clone https://github.com/dagolden/HTTP\-CookieJar.git
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
David Golden <dagolden@cpan.org>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Dan Book <grinnz@grinnz.com>
.IP "\(bu" 4
David Golden <xdg@xdg.me>
.IP "\(bu" 4
jvolkening <jdv@base2bio.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2013 by David Golden.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve