HTTP::CookieJar - A minimalist HTTP user agent cookie jar

       David Golden <dagolden@cpan.org>

new
           my $jar = HTTP::CookieJar->new;

       Return a new, empty cookie jar

       •   Dan Book <grinnz@grinnz.com>

       •   David Golden <xdg@xdg.me>

       •   jvolkening <jdv@base2bio.com>

       This software is Copyright (c) 2013 by David Golden.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004

perl v5.36.0                                       2023-08-07                               HTTP::CookieJar(3pm)

       This module implements a minimalist HTTP user agent cookie jar in conformance with RFC 6265
       <http://tools.ietf.org/html/rfc6265>.

       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.

RFC6265vspriorstandards
       This  modules adheres as closely as possible to the user-agent rules of RFC 6265.  Therefore, it does not
       handle nor generate "Set-Cookie2" and "Cookie2" headers, implement ".local" suffixes, or  do  path/domain
       matching in accord with prior RFC's.

   Internationalizeddomainnames
       Internationalized domain names given in requests must be properly encoded in ASCII form.

   Publicsuffixes
       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-partycookies
       According to RFC 6265, a cookie may be accepted only if has no "Domain" attribute (in which  case  it  is
       "host-only")  or  if  the  "Domain" 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.

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.  A "Max-Age" attribute will be
       converted to an absolute "Expires" 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 is "https".  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 time when the cookie was first stored

       •   last_access_time -- epoch time when the cookie was last accessed (i.e. "now")

       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  with
       "load_cookies" to allow cookie jar persistence.

       If  a  hash  reference with a true "persistent" key is given as an argument, cookies without an "Expires"
       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
           );

       HTTP::CookieJar - A minimalist HTTP user agent cookie jar

       •   HTTP::Cookies

       •   Mojo::UserAgent::CookieJar

Bugs/FeatureRequests
       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.

   SourceCode
       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

         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/" );

       version 0.014