/ 
CGI-Cookie-Jam-0.05
/ CGI::Cookie::Jam

NAME

CGI::Cookie::Jam - Jam a large number of cookies to a small one.

SYNOPSIS

use CGI::Cookie::Jam;

my %param1(
    name    => 'Masanori HATA'           ,
    mail    => 'lovewing@dream.big.or.jp',
    sex     => 'male'                    ,
    birth   => '2003-04-09'              ,
    nation  => 'Japan'                   ,
    pref    => 'Saitama'                 ,
    city    => 'Kawaguchi'               ,
    tel     => '+81-48-2XX-XXXX'         ,
    fax     => '+81-48-2XX-XXXX'         ,
    job     => 'student'                 ,
    role    => 'president'               ,
    hobby   => 'exaggeration'            ,
    );
my @cookie = enjam('cookie_jammed', '4096', %param1);

my %param2 = dejam($ENV{'HTTP_COOKIE'});

DESCRIPTION

This module provides jamming method about WWW cookie. Cookie is convenient but there are some limitations on number of cookies that a client can store at a time:

300 total cookies
4KB per cookie, where the NAME and the VALUE combine to form the 4KB limit.
20 cookies per server or domain.

Especially, 20 cookies limitation could be a bottle neck. So this module try to jam some cookies (which holds single pair of the NAME and the VALUE) to a cookie at maximum size of 4KB, that you can save total number of cookies to a minimum one.

FUNCTIONS

enjam($cookie_name, $maximum_size, %hash)

This function jams a lot number of multiple NAME=VALUE strings for Set-Cookie: HTTP header to a minimum number of NAME=VALUE strings for Set-Cookie: HTTP header. It returns a list of multiple enjammed strings.

The enjamming algorithm is realized by twice uri-escaping. At first, each cookie's NAME and VALUE pairs are uri-escaped and joined with = (an equal mark). Then, multiple NAME=VALUE pairs are joined with & (an ampersand mark). This procedure is very the uri-encoding (see http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1).

Still a cookie has only one NAME=VALUE pair, the uri-encoded string must be re-uri-escaped at the second procedure. As a result:

'=' is converted to '%3D'
'&' is converted to '%26'
'%' is converted to '%25'

At last, this module uses the jam's $cookie_name (which is, of course, uri-escaped, and coupled with a serial number like $cookie_name_XX) as cookie NAME and uses the twice uri_escaped string as cookie VALUE, then join both with = to make a NAME=VALUE string. The final product is very the enjammed multi-spanning cookies.

With size attribute you can specify the size (bytes) of a cookie (that is the size of NAME=VALUE string). Generally, to set 4096 bytes (4KB) is recommended. If you set 0 byte, no size limitation will work and only one cookie will be generated without filename numbering (_XX).

When you use enjammed cookies, you may dejam to reverse the above procedure:

1: Extract VALUEs
   and join the splitted enjammed VALUE strings to a string.
2: uri-unescape '%3D' to '=', '%26' to '&', '%25' to '%'.
3: uri-decode the uri-encoded string to multiple NAME and VALUE pairs.

This module implements above the function as dejam() method except for the first procedure. Otherwise, you may implement dejam() function by client side using with JavaScript and so on.

dejam($cookie_string)

This function dejams an enjammed cookie string. It returns NAME and VALUE pairs as a list. You may use those dejammed data to put into an hash.

Note that this method does not care multi-spanning enjammed cookies.

enjam_crypt( $cookie_string [, $magic] )
dejam_crypt( $cookie_string [, $magic] )

These importable functions (you must import these functions to use) are used to encrypt/decrypt a cookie string (NAME and VALUE pair). Magic number should be an integer number from 1 to 6. If it is omitted or invalid one, the default number 4 will be used. To decrypt an encrypted cookie string, you must use the same magic number for the string.

These functions are not independently usable with enjam() or dejam() function. Below is a sample code:

$jam = enjam('jam', 0, %hash1);   # enjam
$encrypt = enjam_crypt($jam);     # encrypt

$decrypt = dejam_crypt($encrypt); # decrypt
%hash2 = dejam($crypt);           # dejam (%hash2 is equal to %hash1)

SEE ALSO

Netscape: http://wp.netscape.com/newsref/std/cookie_spec.html (Cookie)
RFC 2965: http://www.ietf.org/rfc/rfc2965.txt (Cookie)
HTML 4: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1 (uri-encode)

AUTHOR

Masanori HATA <lovewing@dream.big.or.jp> (Saitama, JAPAN)

COPYRIGHT

Copyright (c) 2003-2005 Masanori HATA. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.