/ 
HTTP-State-v0.1.2
River stage zero No dependents
/ HTTP::State::Cookie

NAME

HTTP::State::Cookie - Cookie structure and functions

SYNOPSIS

# Default import only import "cookie_struct";
use HTTP::State::Cookie;

#Import the encoding functions
use HTTP::State::Cookie qw<:encode>;

#Import the decoding functions
use HTTP::State::Cookie qw<:decode>;

DESCRIPTION

Implements a structure representing a HTTP state fragment (cookie) and associated creation/encoding/decoding functions. This module can be used standalone but it's main purpose is to service HTTP::State for a fast and up to date client side 'cookie jar'.

API

Structure Creation

#Minimum required arguments
cookie_struct name=>"value";

#using constant keys
cookie_struct name=>"value" KEY()=>"value", ...;
cookie_struct name=>"value" KEY, "value", ...;

#using string names
cookie_struct name=>"value, key=>"value", ...;

Creates a cookie structure for later encoding or adding to a HTTP::State cookie jar. Minimal initialisation of the cookie structure is performed to allow expected processing of 'default' values for client side cookie jars.

The first two arguments are required. The first must be the name of the cookie, and the second must be the value.

Remaining arguments are taken as key/value pairs representing the attributes of a cookie.

The first attribute name is examined and expected to be a string or a integer, which then determines how all attribute names are handled:

string

A string matching the expected cookie attribute name (case insensitive) as per RFC6265bis-draft:

		Name
		Value
		Expires
		Max-Age
		Domain
		Path
		Secure
		HTTPOnly
		SameSite
    Partitioned

Any other name is silently ignored.

ie 
  my $struct = cookie_struct cool_name=>"some_value", Domain=>"somewhere.com"...
integer (constant)

An integer value equal to exported constants (use HTTP::State::Cookie ":constants"), allows for compile time attribute name checking and performance improvements:

		COOKIE_NAME
		COOKIE_VALUE
		COOKIE_EXPIRES
		COOKIE_MAX_AGE
		COOKIE_DOMAIN
		COOKIE_PATH
		COOKIE_SECURE
		COOKIE_HTTPONLY
		COOKIE_SAMESITE
    COOKIE_PARTITIONED

Any other integer value is ignored.

ie 
  my $struct = cookie_struct cool_name=>"some_value", COOKIE_DOMAIN, "somewhere.com", ...

Note that the () will need to used after the constant name when using fat arrows:

# Same as above using fat arrows for attribute key value pairs
ie 
  my $struct = cookie_struct cool_name=>"some_value", COOKIE_DOMAIN()=>"somewhere.com", ...

HTTP Client Side

encode_cookies

my $string = encode_cookies $struct1, struct2, ...

Encodes a list of cookie structures into a string suitable as the value of a HTTP 'Cookie' header. This will encode the name and value from multiple cookies supplied into a single string, with the HTTP list separator.

Returns a encoded http header value string.

my  $cookie=decode_set_cookie $string;
my  $cookie=decode_set_cookie $string, $offset;

Decodes a HTTP Set-Cookie header value into a cookie structure and returns it.

If the $offset argument is defined, it is subtracted from the creation and last access time fields, if they are present. This performs the reverse of the $store_and_offset argument in encode_set_cookie to covert from local time to GMT times. This is used by HTTP::State to load cookies in local time for storage compatible with HTTP::CookieJar.

HTTP Server Side

my $string=encode_set_cookie $cookie;
my $string=encode_set_cookie $cookie, $store_and_offset, $partition_key;

Encodes a cookie into a string suitable as the value of HTTP Set-Cookie header.

If the $store_and_offset argument is defined, internal fields for the cookie are also encoded. The value is also used as a time offset (in seconds) to add to the internal creation and last access times.

This is used by HTTP::State to dump cookies in local time for storage compatible with HTTP::CookieJar.

If $partition_key is defined, this is the partition key to store in the COOKIE_PARTITIONED field when $store_and_offset is defined.

decode_cookies

my @cookies = decode_cookies $string;
my @cookies = decode_cookies [$string, $string, ...];

Decodes a cookie string into cookie structures. Input arguments can be a single string from a HTTP Cookie header or an reference to an array of multiple HTTP cookie header values.

In the later case, the values are joined together and processed as if it was a single string.

Returns a list of cookie structures with only name and value fields set.

AUTHOR

Ruben Westerberg, <drclaw@mac.com>

COPYRIGHT AND LICENSE

Copyright (C) 2023 by Ruben Westerberg

Licensed under MIT

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.