<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Session Package</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="index.html" title="Apache Rivet"><link rel="prev" href="diodisplay_package.html" title="DIODisplay"><link rel="next" href="form.html" title="Form: An HTML Form Fields Generation Utility"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Session Package</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="diodisplay_package.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="form.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div class="section" title="Session Package"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="session_package"></a>Session Package</h2></div></div></div><div class="section" title="Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="idp7617904"></a>Introduction</h3></div></div></div><p style="width:90%"> | |
This is session management code. It provides an interface | |
to allow you to generate and track a browser's visit as a | |
"session", giving you a unique session ID and an interface | |
for storing and retrieving data for that session on the | |
server. | |
</p><p style="width:90%"> | |
This is an alpha/beta release -- documentation is not in | |
final form, but everything you need should be in this file. | |
</p><p style="width:90%"> | |
Using sessions and their included ability to store and | |
retrieve session-related data on the server, programmers can | |
generate more secure and higher-performance websites. For | |
example, hidden fields do not have to be included in forms | |
(and the risk of them being manipulated by the user | |
mitigated) since data that would be stored in hidden fields | |
can now be stored in the session cache on the server. Forms | |
are then faster since no hidden data is transmitted -- | |
hidden fields must be sent twice, once in the form to the | |
broswer and once in the response from it. | |
</p><p style="width:90%"> | |
Robust login systems, etc, can be built on top of this code. | |
</p></div><div class="section" title="Requirements"><div class="titlepage"><div><div><h3 class="title"><a name="requirements"></a>Requirements</h3></div></div></div><p style="width:90%"> | |
Currently has only been tested with Postgresql, MySql and Oracle. | |
All DB interfacing is done through DIO, though, so it | |
should be relatively easy to add support for other | |
databases. | |
</p></div><div class="section" title="Preparing To Use It"><div class="titlepage"><div><div><h3 class="title"><a name="idp7666256"></a>Preparing To Use It</h3></div></div></div><p style="width:90%">Create the tables in your SQL server. With Postgres, | |
do a <span style="font-family:monospace"><span class="command"><strong>psql www</strong></span></span> or whatever DB you | |
connect as, then a backslash-i on | |
<code class="filename">session-create.sql</code></p><p style="width:90%">(If you need to delete the tables, use <code class="filename">session-drop.sql</code>)</p><p style="width:90%">The session code by default requires a DIO handle | |
called <code class="varname">DIO</code> (the name of which can be | |
overridden). We get it by doing a</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> | |
RivetServerConf ChildInitScript "package require DIO" | |
RivetServerConf ChildInitScript "::DIO::handle Postgresql DIO -user www" | |
</pre></div><div class="section" title="Example Usage"><div class="titlepage"><div><div><h3 class="title"><a name="idp7671712"></a>Example Usage</h3></div></div></div><p style="width:90%">In your httpd.conf, add:</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">RivetServerConf ChildInitScript "package require Session; Session SESSION"</pre><p style="width:90%"> | |
This tells Rivet you want to create a session object named | |
SESSION in every child process Apache creates.</p><p style="width:90%"> | |
You can configure the session at this point using numerous | |
key-value pairs (which are defined later in this doc). | |
Here's a quick example:</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">RivetServerConf ChildInitScript "package require Session; Session SESSION \ | |
-cookieLifetime 120 -debugMode 1"</pre><p style="width:90%"> | |
Turn debugging on -debugMode 1 to figure | |
out what's going on -- it's really useful, if | |
verbose.</p><p style="width:90%"> | |
In your .rvt file, when you're generating the <HEAD> | |
section: | |
</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">SESSION activate</pre><p style="width:90%"> | |
Activate handles everything for you with respect to | |
creating new sessions, and for locating, validating, and | |
updating existing sessions. Activate will either locate | |
an existing session, or create a new one. Sessions will | |
automatically be refreshed (their lifetimes extended) as | |
additional requests are received during the session, all | |
under the control of the key-value pairs controlling the | |
session object. | |
</p></div><div class="section" title="Using Sessions From Your Code"><div class="titlepage"><div><div><h3 class="title"><a name="idp7678464"></a>Using Sessions From Your Code</h3></div></div></div><p style="width:90%">The main methods your code will use are:</p><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION</span> <span style="font-weight:bold ; font-family:monospace">id</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
After doing a <span style="font-family:monospace"><span class="command"><strong>SESSION activate</strong></span></span>, | |
this will return a 32-byte ASCII-encoded random | |
hexadecimal string. Every time this browser comes | |
to us with a request within the timeout period, this | |
same string will be returned (assuming they have | |
cookies enabled). | |
</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION</span> <span style="font-weight:bold ; font-family:monospace">is_new_session</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">returns 1 if it's a new session or 0 if it has | |
previously existed (i.e. it's a zero if this request | |
represents a "return" or subsequent visit to a | |
current session.)</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION new_session_reason</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
This will return why this request is the first | |
request of a new session, either "no_cookie" saying | |
the browser didn't give us a session cookie, | |
"no_session" indicating we got a cookie but couldn't | |
find it in our session table, or "timeout" where | |
they had a cookie and we found the matching session | |
but the session has timed out. | |
</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION store</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>data</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Given the name of a package, a key, and some data. | |
Stores the data in the rivet session cache table. | |
</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION fetch</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Given a package name and a key, return the data | |
stored by the store method, or an empty string if | |
none was set. (Status is set to the DIO error that | |
occurred, it can be fetched using the status | |
method.) | |
</div></div></dd></dl></div></div><div class="section" title="Session Configuration Options"><div class="titlepage"><div><div><h3 class="title"><a name="idp7702128"></a>Session Configuration Options</h3></div></div></div><p style="width:90%">The following key-value pairs can be specified when a | |
session object (like SESSION above) is created:</p><div class="variablelist"><dl><dt><span class="term">sessionLifetime</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">how many seconds the session will live for. | |
7200 == 2 hours | |
</div></div></dd><dt><span class="term">sessionRefreshInterval</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> | |
If a request is processed for a browser that | |
currently has a session and this long has elapsed | |
since the session update time was last updated, | |
update it. 900 == 15 minutes. so if at least 15 | |
minutes has elapsed and we've gotten a new request | |
for a page, update the session update time, | |
extending the session lifetime (sessions that are in | |
use keep getting extended). | |
</div></div></dd><dt><span class="term">cookieName</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"></div> | |
name of the cookie stored on the user's web browser | |
default rivetSession | |
</div></dd><dt><span class="term">dioObject</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> | |
The name of the DIO object we'll use to access the | |
database (default DIO) | |
</div></div></dd><dt><span class="term">gcProbability</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> | |
The probability that garbage collection will occur | |
in percent. (default 1%, i.e. 1)</div></div></dd><dt><span class="term">gcMaxLifetime</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">the number of seconds after which | |
data will be seen as "garbage" and cleaned up -- | |
defaults to 1 day (86400)</div></div></dd><dt><span class="term">refererCheck</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The substring you want to check each | |
HTTP referer for. If the referer was sent by the | |
browser and the substring is not found, the session | |
will be deleted. (not coded yet)</div></div></dd><dt><span class="term">entropyFile</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The | |
name of a file that random binary data can be read | |
from. (<code class="filename">/dev/urandom</code>) Data will | |
be used from this file to help generate a | |
super-hard-to-guess session ID.</div></div></dd><dt><span class="term">entropyLength</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The number of bytes which will be | |
read from the entropy file. If 0, the entropy file | |
will not be read (default 0)</div></div></dd><dt><span class="term">scrambleCode</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Set the scramble code to something unique for the | |
site or your app or whatever, to slightly increase | |
the unguessability of session ids (default "some | |
random string")</div></div></dd><dt><span class="term">cookieLifetime</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The lifetime of the cookie in | |
minutes. 0 means until the browser is closed (I | |
think). (default 0)</div></div></dd><dt><span class="term">cookiePath</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The | |
webserver subpath that the session cookie applies to | |
(defaults to | |
<code class="filename">/</code>)</div></div></dd><dt><span class="term">cookieSecure</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Specifies whether the cookie should | |
only be sent over secure connections, 0 = any, 1 = | |
secure connections only (default | |
0)</div></div></dd><dt><span class="term">sessionTable</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The name of the table that session | |
info will be stored in (default | |
<code class="varname">rivet_session</code>)</div></div></dd><dt><span class="term">sessionCacheTable</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The name of the table that contains | |
cached session data (default | |
<code class="varname">rivet_session_cache</code>)</div></div></dd><dt><span class="term">debugMode</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Set | |
debug mode to 1 to trace through and see the session | |
object do its thing (default 0)</div></div></dd><dt><span class="term">debugFile</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The | |
file handle that debugging messages will be written | |
to (default | |
<code class="varname">stdout</code>) | |
</div></div></dd></dl></div></div><div class="section" title="Session Methods"><div class="titlepage"><div><div><h3 class="title"><a name="idp7729472"></a>Session Methods</h3></div></div></div><p style="width:90%"> | |
The following methods can be invoked to find out | |
information about the current session, store and fetch | |
server data identified with this session, etc: | |
</p><div class="variablelist"><dl><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION status</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the status of the last operation | |
</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION id</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Get the session ID of the current browser. Returns | |
an empty string if there's no session (will not | |
happen is SESSION activate has been issued.) | |
</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION new_session_reason</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Returns the reason why there wasn't a previous | |
session, either "no_cookie" saying the browser | |
didn't give us a session cookie, "no_session" | |
indicating we got a cookie but couldn't find it in | |
the session table, or "timeout" when we had a cookie | |
and a session but the session had timed out. | |
</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION store</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>data</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Given a package name, a key string, and a data | |
string, store the data in the rivet session | |
cache. | |
</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION fetch</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Given a package name and a key, return the data | |
stored by the store method, or an empty string if | |
none was set. Status is set to the DIO error that | |
occurred, it can be fetched using the status | |
method. | |
</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION delete</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Given a user ID and looking at their IP address we | |
inherited from the environment (thanks, Apache), | |
remove them from the session table. (the session | |
table is how the server remembers stuff about | |
sessions). If the session ID was not specified the | |
current session is deleted. | |
</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION activate</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Find and validate the session ID if they have one. | |
If they don't have one or it isn't valid (timed out, | |
etc), create a session and drop a cookie on | |
them. | |
</div></div></dd></dl></div></div><div class="section" title="Getting Additional Randomness From The Entropy File"><div class="titlepage"><div><div><h3 class="title"><a name="idp7756576"></a>Getting Additional Randomness From The Entropy File</h3></div></div></div><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">RivetServerConf ChildInitScript "Session SESSION -entropyFile /dev/urandom \ | |
-entropyLength 10 -debugMode 1"</pre><p style="width:90%"> | |
This options say we want to get randomness from an entropy | |
file (random data pseudo-device) of /dev/urandom, to get ten | |
bytes of random data from that entropy device, and to turn | |
on debug mode, which will cause the SESSION object to output | |
all manner of debugging information as it does stuff. This | |
has been tested on FreeBSD and appears to work. | |
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="diodisplay_package.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="form.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">DIODisplay </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Form: An HTML Form Fields Generation Utility</td></tr></table></div></body></html> |