| <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.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="up" href="index.html" title="Apache Rivet 3.0"><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"><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"><div class="titlepage"><div><div><h3 class="title"><a name="idm45384557756848"></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"><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"><div class="titlepage"><div><div><h3 class="title"><a name="idm45384557708512"></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 class="programlisting">RivetServerConf ChildInitScript "package require DIO" |
| RivetServerConf ChildInitScript "::DIO::handle Postgresql DIO -user www"</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm45384557703120"></a>Example Usage</h3></div></div></div><p style="width:90%">In your httpd.conf, add:</p><pre 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 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 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"><div class="titlepage"><div><div><h3 class="title"><a name="idm45384557696368"></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 class="variablelist"><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; 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="border: 1px solid #282; 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="border: 1px solid #282; 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="border: 1px solid #282; 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="border: 1px solid #282; 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"><div class="titlepage"><div><div><h3 class="title"><a name="idm45384557672704"></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 class="variablelist"><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"><div class="titlepage"><div><div><h3 class="title"><a name="idm45384557645360"></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 class="variablelist"><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="border: 1px solid #282; 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="border: 1px solid #282; 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="border: 1px solid #282; 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="border: 1px solid #282; 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="border: 1px solid #282; 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="border: 1px solid #282; 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="border: 1px solid #282; 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"><div class="titlepage"><div><div><h3 class="title"><a name="idm45384557618256"></a>Getting Additional Randomness From The Entropy File</h3></div></div></div><pre 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> |
