From Code to Community: Sponsoring The Perl and Raku Conference 2025 Learn more

 / 
Protocol-HTTP-1.1.6
River stage one • 5 direct dependents • 5 total dependents
/ Protocol::HTTP::CookieJar

NAME

Protocol::HTTP::CookieJar - Cookie jar for HTTP user agents

SYNOPSIS


            

              
              
use Protocol::HTTP::CookieJar;
my $jar = Protocol::HTTP::CookieJar->new;
# request will be populated with relevant cookies for the requested URI
my $request = Protocol::HTTP::Request->new({ uri => "http://crazypanda.ru/" });
$jar->populate($request);
my ($response, ...) =  $response_parser->parse($network_data);
# pull-in or update cookies in the jar
$jar->collect($response);
# cookies jar (de)serialization
my $binary_data = $jar->serialize();
my $jar = Protocol::HTTP::CookieJar->new($binary_data);
# inspect cookies
my $cookies = $jar->all_cookies;
while(my ($domain, cookies) = each %$cookies) {
    say "Domain '$domain' has cookie named ', $_->{name}, "'" for (@$cookies);
}
my $cookies = $jar->find(URI::XS->new('http://crazypanda.ru/'));
say "A cookie named ', $_->{name}, "' will be sent" for (@$cookies);
# manual cookies injection
$jar->add("sid", { value => "1234", domain => 'ya.ru' }, URI::XS->new('http://ya.ru/'));
# cookies removal
$jar->remove("crazypanda.ru");       # remove cookies by domain
$jar->remove("", "session_id");      # remove cookies by cookie name
$jar->remove("", "/secure");         # remove cookies by path
$jar->remove("google.com", "session_id", "/secure");

DESCRIPTION

This is simple CookieJar, implemented in accordance with RFC 6265. and Same Site Cookies draft.

The user agents can use the Protocol::HTTP::CookieJar to maintain state over stateless HTTP protocol.

METHODS

new($serialized = "")

Constructs new cookie jar, optionally parsing the previously serialized state of cookies jar.

to_string($include_session = false, $now = Date::now())

Serializes cookies jar into a binary string.

By default session cookies are not stored; this is similar behaviour when browser's tab is closed. $include_session can be set to true to preserve them.

The non-session expired at the $now moment cookies are not stored too.

add($name, $cookie, $origin, $now = Date::now())


            

              
              
my $origin = URI::XS->new('http://crazypanda.ru/');
$jar->add("hello", { value => "world", domain => 'crazypanda.ru' }, $origin);

Add new cookie hash $cookie with name $name, as it comes from Protocol::HTTP::Response within the $origin context (i.e. request URI).

If non-session cookie is expired at the $now time moment, then it is ignored.

remove($domain = "" , $name = "" , $path = "/")


            

              
              
my $removed_cookies = $cookie_jar->remove("yandex.ru", "session");

Remove all cookies matching the specified criteria. The empty string mean "match all", so, the call


            

              
              
$cookie_jar->remove();

will erase all cookies.

The $path will match all cookies by prefix, i.e. "/" means "all paths".

The $domain will also match all subdomains. If subdomains should be excluded from removal, the domain should be dot-prefixed, e.g.


            

              
              
$cookie_jar->remove(".ya.ru");

will remove all cookies for ya.ru domain, but the cookies for my.ya.ru will be kept.

clear()

Removes all cookies from the Protocol::HTTP::CookieJar.

find($request_uri, $context_uri = $request_uri, $now = Date::now(), $top_level = true)


            

              
              
my $cookies = $jar->find(URI::XS->new('http://crazypanda.ru/'));

Returns all cookies, which will be sent to $request_uri with in $context_uri; The expired at the $now moment cookies will be not included.

For the meaning of the $top_level please refer Same-Site Cookies.

collect($response, $request_uri, $now = Date::now())

Cookie jar pulls in all cookies, set by server response in the Protocol::HTTP::Response as the response to the $request_uri.

If non-session cookie is expired at the $now time moment, then it is ignored.

If user-provided cookie ignore-filrer is set, then each cookies will by quereied for addition, see set_ignore.

set_ignore(sub { ... });


            

              
              
$jar->set_ignore(sub {
    my ($name, $coo) = @_;
    return scalar($name =~ /^unsecure/);
});

Sets cookies collection ignore predicate. If true is returned, then cookie will not be added into cookie jar.

populate($request, $context_uri = $request->uri, $top_level = true, $now = $now = Date::now())

Fills the Protocol::HTTP::Response with the relevant cookies. The $context_uri and $top_level parameters are needed to inject cross-site request context to correclty check Same Site cookies property, see Same-Site Cookies for the details.

The expired at the $now moment cookies will be not be populated inot the $request.

all_cookies()

Returns hashref of all cookies within the jar. The key is domain, and the values is the array of cookies.

FUNCTIONS

parse_cookies($data)


            

              
              
my ($err, $cookies) = Protocol::HTTP::CookieJar::parse_cookies($data)

Parses previouly stored cookies jar.

SEE ALSO

Protocol::HTTP

Protocol::HTTP::Request

Protocol::HTTP::Response

URI::XS

Mojo::UserAgent::CookieJar

Date

REFERENCES

https://tools.ietf.org/html/rfc6265

https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00