/ 
App-Context-0.968
River stage one • 2 direct dependents • 2 total dependents
/ App::Session::Cookie

NAME

App::Session::Cookie - a session whose state is maintained across HTML requests by being embedded in an HTTP cookie.

SYNOPSIS

# ... official way to get a Session object ...
use App;
$session = App->session();
$session = $session->session();   # get the session

# any of the following named parameters may be specified
$session = $session->session(
);

# ... alternative way (used internally) ...
use App::Session::Cookie;
$session = App::Session->new();

DESCRIPTION

A Session class models the sequence of events associated with a use of the system. These events may occur in different processes. Yet the accumulated state of the session needs to be propagated from one process to the next.

This Session::Cookie maintains its state across HTML requests by being embedded in an HTTP cookie. As a result, it requires no server-side storage, so the sessions never need to time out.

The Session::Cookie has an advantage over Session::HTMLHidden in that data does not need to be posted to a URL for the session data to be transmitted to it. This allows that the state can be propagated properly to sub-components of an HTML page such as

* frame documents within a frameset (<frame src=...>)
* dynamically generated images (<img src=...>, <input type=image src=...>)

Limits on cookie storage are as follows, according to "Dynamic HTML, The Definitive Reference" by O'Reilly in the DOM Reference under "document.cookie".

* max 2000 chars per cookie (recommended, although 4000 supposedly allowed)
* max 20 cookies per domain

This allows for roughly 40K of session storage. It is quite conceivable that this amount of storage could be overrun, so Session::Cookie is only appropriate in situations where you are confident it will not be. Also, session_objects should take care to clean up after themselves, and static values stored in the session can alternatively be provided in the config.

Constructor Methods:

new()

The constructor is inherited from App::Service.

Public Methods:

get_session_id()

* Signature: $session_id = $session->get_session_id();
* Param:  void
* Return: $session_id      string
* Throws: <none>
* Since:  0.01

Sample Usage: 

$session->get_session_id();

The get_session_id() returns the session_id of this particular session. This session_id is unique for all time. If a session_id does not yet exist, one will be created. The session_id is only created when first requested, and not when the session is instantiated.

html()

The html() method ...

* Signature: $html = $session->html();
* Param:  void
* Return: $html      string
* Throws: <none>
* Since:  0.01

Sample Usage: 

$session->html();

This method returns the empty string ("") as the HTML to be embedded in the page. This is because a session_id does not need to be stored. However, it has the side effect that cookies are prepared for the HTTP response headers.

Protected Methods:

The following methods are intended to be called by subclasses of the current class.

create()

The create() method is used to create the Perl structure that will be blessed into the class and returned by the constructor.

* Signature: $ref = App::Reference->create($hashref)
* Param:     $hashref            {}
* Return:    $ref                ref
* Throws:    App::Exception
* Since:     0.01

Sample Usage:

_init()

The _init() method is called from within the constructor.

* Signature: _init($named)
* Param:     $named        {}    [in]
* Return:    void
* Throws:    App::Exception
* Since:     0.01

Sample Usage: 

$ref->_init($args);

The _init() method looks at the cookies in the request and restores the session state information from the cookies named "app_sessiondata" (and "app_sessiondata[2..n]").

When the values of these cookies are concatenated, they form a Base64-encoded, gzipped, frozen multi-level hash of session state data. To retrieve the state data, the text is therefore decoded, gunzipped, and thawed (a la Storable).

Notes on length of cookies: See

http://developer.netscape.com/docs/manuals/js/client/jsref/cookies.htm

An excerpt is included here.

The Navigator can receive and store the following:

* 300 total cookies 
* 4 kilobytes per cookie, where the name and the OPAQUE_STRING
  combine to form the 4 kilobyte limit. 
* 20 cookies per server or domain. Completely specified hosts
  and domains are considered separate entities, and each has
  a 20 cookie limitation.

When the 300 cookie limit or the 20 cookie per server limit is exceeded, Navigator deletes the least recently used cookie. When a cookie larger than 4 kilobytes is encountered the cookie should be trimmed to fit, but the name should remain intact as long as it is less than 4 kilobytes.

TODO: encrypt and MAC