From bknr@bknr.net Wed Feb 18 22:15:00 2009
From: BKNR Commits <bknr@bknr.net>
To: bknr-cvs@common-lisp.net
Subject: [bknr-cvs] edi changed trunk/thirdparty/hunchentoot/
Date: Wed, 18 Feb 2009 23:12:41 +0100
Message-ID: <E1LZuen-000Fpl-8y@paracetamol.bknr.net>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="===============3979258967521433474=="

--===============3979258967521433474==
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable

Revision: 4283
Author: edi
URL: http://bknr.net/trac/changeset/4283

Sessions

U   trunk/thirdparty/hunchentoot/doc/index.xml
U   trunk/thirdparty/hunchentoot/session.lisp

Modified: trunk/thirdparty/hunchentoot/doc/index.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/thirdparty/hunchentoot/doc/index.xml	2009-02-18 21:25:42 UTC (rev 4=
282)
+++ trunk/thirdparty/hunchentoot/doc/index.xml	2009-02-18 22:12:41 UTC (rev 4=
283)
@@ -1136,16 +1136,6 @@
 not <a href=3D"#session-too-old-p">too old</a>.  Old sessions
 are <a href=3D"#session-gc">automatically removed</a>.
 </p>
-<p>
-For everyday session usage, you will probably just
-use <clix:ref>START-SESSION</clix:ref>,
-<clix:ref>SESSION-VALUE</clix:ref>,
-maybe <clix:ref>DELETE-SESSION-VALUE</clix:ref>
-and <clix:ref>*SESSION*</clix:ref>.  However, there are two ways to
-customize the way Hunchentoot maintains sessions:
-</p>
-<p>
-</p>
=20
   <clix:class name=3D'session'>
     <clix:description><clix:ref>SESSION</clix:ref> objects are
@@ -1218,6 +1208,29 @@
     </clix:description>
   </clix:special-variable>
=20
+  <clix:function name=3D'remove-session'>
+  <clix:lambda-list>session
+  </clix:lambda-list>
+  <clix:returns>|
+  </clix:returns>
+    <clix:description>Completely removes
+the <clix:ref>SESSION</clix:ref> object <clix:arg>session</clix:arg>
+from Hunchentoot&#039;s internal <a href=3D"#session-db">session
+database</a>.
+    </clix:description>
+  </clix:function>
+
+
+  <clix:function name=3D'reset-sessions'>
+  <clix:lambda-list>
+  </clix:lambda-list>
+  <clix:returns>|
+  </clix:returns>
+    <clix:description>Removes <em>all</em> stored sessions.
+    </clix:description>
+  </clix:function>
+
+
   <clix:special-variable name=3D'*rewrite-for-session-urls*'>
     <clix:description>Whether HTML pages should possibly be rewritten for co=
okie-less
 session-management.
@@ -1231,38 +1244,7 @@
     </clix:description>
   </clix:special-variable>
=20
-  <clix:special-variable name=3D'*session-gc-frequency*'>
-    <clix:description>A session GC (see function <clix:ref>SESSION-GC</clix:=
ref>) will happen every
-<clix:ref>*SESSION-GC-FREQUENCY*</clix:ref> requests (counting only
-requests which create a new session) if this variable is
-not <code>NIL</code>.  See <clix:ref>SESSION-CREATED</clix:ref>.
-    </clix:description>
-  </clix:special-variable>
=20
-  <clix:special-variable name=3D'*session-max-time*'>
-    <clix:description>The default time (in seconds) after which a session ti=
mes out.
-    </clix:description>
-  </clix:special-variable>
-
-  <clix:special-variable name=3D'*session-removal-hook*'>
-    <clix:description>A function of one argument
-(a <clix:ref>SESSION</clix:ref> object) which is called whenever a
-session is <a href=3D"#session-gc">garbage-collected</a>.
-    </clix:description>
-  </clix:special-variable>
-
-  <clix:special-variable name=3D'*session-secret*'>
-    <clix:description>A random ASCII string that&#039;s used to encode
-the public session data.  This variable is initially unbound and will
-be set (using <clix:ref>RESET-SESSION-SECRET</clix:ref>) the first
-time a session is created, if necessary.  You can prevent this from
-happening if you set the value yourself before
-starting <a href=3D"#acceptors">acceptors</a>.
-    </clix:description>
-  </clix:special-variable>
-
-
-
   <clix:special-variable name=3D'*use-remote-addr-for-sessions*'>
     <clix:description>Whether the client&#039;s remote IP (as returned by <c=
lix:ref>REAL-REMOTE-ADDR</clix:ref>)
 should be encoded into the session string.  If this value is true, a
@@ -1274,97 +1256,208 @@
     </clix:description>
   </clix:special-variable>
=20
+  <clix:function generic=3D'true' name=3D'session-remote-addr'>
+  <clix:lambda-list>session
+  </clix:lambda-list>
+  <clix:returns>remote-addr
+  </clix:returns>
+    <clix:description>
+The remote IP address of the client when this session was started as
+returned by <clix:ref>REAL-REMOTE-ADDR</clix:ref>.
+    </clix:description>
+  </clix:function>
+
+
   <clix:special-variable name=3D'*use-user-agent-for-sessions*'>
-    <clix:description>Whether the &#039;User-Agent&#039; header should be en=
coded into the session
-string.  If this value is true, a session will cease to be accessible
-if the client sends a different &#039;User-Agent&#039; header.
+    <clix:description>Whether the &#039;User-Agent&#039; header should
+be encoded into the session string.  If this value is true, a session
+will cease to be accessible if the client sends a different
+&#039;User-Agent&#039; header.
     </clix:description>
   </clix:special-variable>
=20
-
-  <clix:function generic=3D'true' name=3D'next-session-id'>
-  <clix:lambda-list>acceptor
+  <clix:function generic=3D'true' name=3D'session-user-agent'>
+  <clix:lambda-list>session
   </clix:lambda-list>
-  <clix:returns>id
+  <clix:returns>user-agent
   </clix:returns>
-    <clix:description>Returns the next sequential session ID, an
-integer, which should be unique per session.  The default method uses
-a simple global counter and isn&#039;t guarded by a lock.  For a
-high-performance production environment you might consider to use a
-more robust implementation.
+    <clix:description>
+The incoming &#039;User-Agent&#039; header that
+was sent when this session was created.
     </clix:description>
   </clix:function>
=20
=20
-  <clix:function name=3D'remove-session'>
+  <clix:accessor generic=3D'true' name=3D'session-max-time'>
   <clix:lambda-list>session
   </clix:lambda-list>
+  <clix:returns>max-time
+  </clix:returns>
+    <clix:description>
+Gets or sets the time (in seconds) after
+which <clix:arg>session</clix:arg> expires if it's not used.
+    </clix:description>
+  </clix:accessor>
+
+
+  <clix:special-variable name=3D'*session-max-time*'>
+    <clix:description>The default time (in seconds) after which a session ti=
mes out.
+    </clix:description>
+  </clix:special-variable>
+
+  <clix:special-variable name=3D'*session-gc-frequency*'>
+    <clix:description>A session GC (see function <clix:ref>SESSION-GC</clix:=
ref>) will happen every
+<clix:ref>*SESSION-GC-FREQUENCY*</clix:ref> requests (counting only
+requests which create a new session) if this variable is
+not <code>NIL</code>.  See <clix:ref>SESSION-CREATED</clix:ref>.
+    </clix:description>
+  </clix:special-variable>
+
+  <clix:function name=3D'session-gc'>
+  <clix:lambda-list>
+  </clix:lambda-list>
   <clix:returns>|
   </clix:returns>
-    <clix:description>Completely removes the SESSION object SESSION from Hun=
chentoot&#039;s
-internal session database.
+    <clix:description>Removes sessions from the current session database whi=
ch are too
+old - see <clix:ref>SESSION-TOO-OLD-P</clix:ref>.
     </clix:description>
   </clix:function>
=20
-  <clix:function name=3D'reset-session-secret'>
-  <clix:lambda-list>
+  <clix:function name=3D'session-too-old-p'>
+  <clix:lambda-list>session
   </clix:lambda-list>
-  <clix:returns>secret
+  <clix:returns>generalized-boolean
   </clix:returns>
-    <clix:description>Sets *SESSION-SECRET* to a new random value. All old s=
essions will
-cease to be valid.
+    <clix:description>Returns true if the <clix:ref>SESSION</clix:ref> objec=
t <clix:arg>session</clix:arg> has not been active in
+the last <code>(session-max-time session)</code> seconds.
     </clix:description>
   </clix:function>
=20
-  <clix:function name=3D'reset-sessions'>
+
+  <clix:special-variable name=3D'*session-removal-hook*'>
+    <clix:description>A function of one argument
+(a <clix:ref>SESSION</clix:ref> object) which is called whenever a
+session is <a href=3D"#session-gc">garbage-collected</a>.
+    </clix:description>
+  </clix:special-variable>
+
+
+    </clix:subchapter>
+
+
+    <clix:subchapter name=3D"session-behaviour" title=3D"Customizing session=
 behaviour">
+
+For everyday session usage, you will probably just
+use <clix:ref>START-SESSION</clix:ref>,
+<clix:ref>SESSION-VALUE</clix:ref>,
+maybe <clix:ref>DELETE-SESSION-VALUE</clix:ref>
+and <clix:ref>*SESSION*</clix:ref>.  However, there are two ways to
+customize the way Hunchentoot maintains sessions.
+<p>
+One way is to mostly leave the session mechanism intact but to tweak
+it a bit:
+<ul>
+<li>The publicly visible part of session is encoded using a
+<a href=3D"#*session-secret*">secret</a> which you can set yourself.</li>
+<li>And it is stored using a cookie (or GET
+parameter) <a href=3D"#session-cookie-name">name</a> that you can
+override.</li>
+<li>Each session receives a <a href=3D"#next-session-id">new ID</a> when
+it is created and you can implement a more robust way to do that.</li>
+<li>You can arrange to be called whenever a session
+is <a href=3D"#session-created">created</a> to trigger some action.  You
+might also do this to invent your own
+session <a href=3D"#session-gc">garbage collection</a>.</li>
+<li>By default, all sessions are stored in a global alist in memory.
+You can't change the alist part, but you can distribute your sessions
+amongst different <a href=3D"#session-db">"databases"</a>.</li>
+<li>By default, every operation which modifies sessions or one of the
+session databases is guarded by a global lock, but you can arrange to
+<a href=3D"#session-db-lock">provide</a> different locks for this.</li>
+</ul>
+</p>
+<p>
+The other way to customize Hunchentoot's sessions is to completely
+replace them.  This is actually pretty easy: Create your own class to
+store state (which doesn't have to and probably shouldn't inherit
+from <clix:ref>SESSION</clix:ref>) and implement methods for
+<clix:ref>SESSION-VERIFY</clix:ref>
+and <clix:ref>SESSION-COOKIE-VALUE</clix:ref> - that's it.
+Hunchentoot will continue to use cookies and/or to rewrite URLs to
+keep track of session state and it will store "the current session"
+(whatever that is in your implementation)
+in <clix:ref>*SESSION*</clix:ref>.  Everything else (like persisting
+sessions, GC, getting and setting values) you'll have to take care of
+yourself and the other session functions
+(like <clix:ref>START-SESSION</clix:ref> or
+<clix:ref>SESSION-VALUE</clix:ref>) won't work anymore.  (Almost)
+total freedom, but a lot of responsibility as well... :)
+</p>
+
+  <clix:special-variable name=3D'*session-secret*'>
+    <clix:description>A random ASCII string that&#039;s used to encode
+the public session data.  This variable is initially unbound and will
+be set (using <clix:ref>RESET-SESSION-SECRET</clix:ref>) the first
+time a session is created, if necessary.  You can prevent this from
+happening if you set the value yourself before
+starting <a href=3D"#acceptors">acceptors</a>.
+    </clix:description>
+  </clix:special-variable>
+
+  <clix:function name=3D'reset-session-secret'>
   <clix:lambda-list>
   </clix:lambda-list>
-  <clix:returns>|
+  <clix:returns>secret
   </clix:returns>
-    <clix:description>Removes ALL stored sessions.
+    <clix:description>Sets <clix:ref>*SESSION-SECRET*</clix:ref> to a
+new random value. All old sessions will cease to be valid.
     </clix:description>
   </clix:function>
=20
+
+
   <clix:function generic=3D'true' name=3D'session-cookie-name'>
   <clix:lambda-list>acceptor
   </clix:lambda-list>
   <clix:returns>name
   </clix:returns>
-    <clix:description>Returns the name (a string) of the cookie (or the
-GET parameter) which is used to store a session on the client side.
-The default is to use the string &quot;hunchentoot-session&quot;, but you can
+    <clix:description>Returns the name (a string) of the cookie (or
+the GET parameter) which is used to store a session on the client
+side.  The default is to use the
+string <code>&quot;hunchentoot-session&quot;</code>, but you can
 specialize this function if you want another name.
     </clix:description>
   </clix:function>
=20
-  <clix:function generic=3D'true' name=3D'session-cookie-value'>
-  <clix:lambda-list>session
-  </clix:lambda-list>
-  <clix:returns>string
-  </clix:returns>
-    <clix:description>Returns a string which can be used to safely
-restore the session SESSION if as session has already been
-established.  This is used as the value stored in the session cookie
-or in the corresponding GET parameter.  A default method is provided
-and there&#039;s no reason to change it unless you want to use your own
-session objects.
-    </clix:description>
-  </clix:function>
-
   <clix:function generic=3D'true' name=3D'session-created'>
   <clix:lambda-list>acceptor new-session
   </clix:lambda-list>
   <clix:returns>result
   </clix:returns>
-    <clix:description>This function is called whenever a new session has
-been created.  There&#039;s a default method which might trigger a session
-GC based on the value of *SESSION-GC-FREQUENCY*.
+    <clix:description>This function is called whenever a new session
+has been created.  There&#039;s a default method which might trigger
+a <a href=3D"#session-gc">session GC</a> based on the value of
+<clix:ref>*SESSION-GC-FREQUENCY*</clix:ref>.
 <p>
 The return value is ignored.
 </p>
     </clix:description>
   </clix:function>
=20
+
+  <clix:function generic=3D'true' name=3D'next-session-id'>
+  <clix:lambda-list>acceptor
+  </clix:lambda-list>
+  <clix:returns>id
+  </clix:returns>
+    <clix:description>Returns the next sequential session ID, an
+integer, which should be unique per session.  The default method uses
+a simple global counter and isn&#039;t guarded by a lock.  For a
+high-performance production environment you might consider to use a
+more robust implementation.
+    </clix:description>
+  </clix:function>
+
   <clix:accessor generic=3D'true' name=3D'session-db'>
   <clix:lambda-list>acceptor
   </clix:lambda-list>
@@ -1372,8 +1465,8 @@
   </clix:returns>
     <clix:description>Returns the current session database which is an
 alist where each car is a session&#039;s ID and the cdr is the
-corresponding SESSION object itself.  The default is to use a global
-list for all acceptors.
+corresponding <clix:ref>SESSION</clix:ref> object itself.  The default
+is to use a global list for all acceptors.
     </clix:description>
   </clix:accessor>
=20
@@ -1384,67 +1477,23 @@
   </clix:lambda-list>
   <clix:returns>lock
   </clix:returns>
-    <clix:description>A function which returns a lock that will be used
-to prevent concurrent access to sessions.  The first argument will be
-the acceptor that handles the current request, the second argument is
-true if the whole (current) session database is modified.  If it is
-NIL, only one existing session in the database is modified.
-
-This function can return NIL which means that sessions or session
-databases will be modified without a lock held (for example for
-single-threaded environments).  The default is to always return a
-global lock (ignoring the ACCEPTOR argument) for Lisps that support
-threads and NIL otherwise.
+    <clix:description>A function which returns a lock that will be
+used to prevent concurrent access to sessions.  The first argument
+will be the <a href=3D"#acceptors">acceptor</a> that handles the
+current <a href=3D"#requests">request</a>, the second argument is true
+if the whole (current) session database is modified.  If it
+is <code>NIL</code>, only one existing session in the database is
+modified.
+<p>
+This function can return <code>NIL</code> which means that sessions or
+session databases will be modified without a lock held (for example
+for single-threaded environments).  The default is to always return a
+global lock (ignoring the <clix:arg>acceptor</clix:arg> argument) for
+Lisps that support threads and <code>NIL</code> otherwise.
+</p>
     </clix:description>
   </clix:function>
=20
-  <clix:function name=3D'session-gc'>
-  <clix:lambda-list>
-  </clix:lambda-list>
-  <clix:returns>|
-  </clix:returns>
-    <clix:description>Removes sessions from the current session database whi=
ch are too
-old - see SESSION-TOO-OLD-P.
-    </clix:description>
-  </clix:function>
-
-  <clix:accessor generic=3D'true' name=3D'session-max-time'>
-  <clix:lambda-list>session
-  </clix:lambda-list>
-  <clix:returns>max-time
-  </clix:returns>
-    <clix:description>
-    </clix:description>
-  </clix:accessor>
-
-  <clix:function generic=3D'true' name=3D'session-remote-addr'>
-  <clix:lambda-list>session
-  </clix:lambda-list>
-  <clix:returns>remote-addr
-  </clix:returns>
-    <clix:description>
-    </clix:description>
-  </clix:function>
-
-  <clix:function name=3D'session-too-old-p'>
-  <clix:lambda-list>session
-  </clix:lambda-list>
-  <clix:returns>generalized-boolean
-  </clix:returns>
-    <clix:description>Returns true if the SESSION object SESSION has not bee=
n active in
-the last (SESSION-MAX-TIME SESSION) seconds.
-    </clix:description>
-  </clix:function>
-
-  <clix:function generic=3D'true' name=3D'session-user-agent'>
-  <clix:lambda-list>session
-  </clix:lambda-list>
-  <clix:returns>user-agent
-  </clix:returns>
-    <clix:description>
-    </clix:description>
-  </clix:function>
-
   <clix:function generic=3D'true' name=3D'session-verify'>
   <clix:lambda-list>request
   </clix:lambda-list>
@@ -1452,16 +1501,31 @@
   </clix:returns>
     <clix:description>Tries to get a session identifier from the cookies
 (or alternatively from the GET parameters) sent by the client.  This
-identifier is then checked for validity against the REQUEST object
-REQUEST.  On success the corresponding session object (if not too
-old) is returned (and updated).  Otherwise NIL is returned.
-
+identifier is then checked for validity against the <clix:ref>REQUEST</clix:=
ref> object
+<clix:arg>request</clix:arg>.  On success the corresponding session object (=
if not too
+old) is returned (and updated).  Otherwise <code>NIL</code> is returned.
+<p>
 A default method is provided and you only need to write your own one
 if you want to maintain your own sessions.
+</p>
     </clix:description>
   </clix:function>
=20
+  <clix:function generic=3D'true' name=3D'session-cookie-value'>
+  <clix:lambda-list>session
+  </clix:lambda-list>
+  <clix:returns>string
+  </clix:returns>
+    <clix:description>Returns a string which can be used to safely
+restore the session <clix:arg>session</clix:arg> if as session has
+already been established.  This is used as the value stored in the
+session cookie or in the corresponding GET parameter.  A default
+method is provided and there&#039;s no reason to change it unless you
+want to use your own session objects.
+    </clix:description>
+  </clix:function>
=20
+
     </clix:subchapter>
=20
     <clix:subchapter name=3D"handlers" title=3D"Handlers">

Modified: trunk/thirdparty/hunchentoot/session.lisp
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/thirdparty/hunchentoot/session.lisp	2009-02-18 21:25:42 UTC (rev 42=
82)
+++ trunk/thirdparty/hunchentoot/session.lisp	2009-02-18 22:12:41 UTC (rev 42=
83)
@@ -96,8 +96,8 @@
 was sent when this session was created.")
    (remote-addr :initform (real-remote-addr *request*)
                 :reader session-remote-addr
-                :documentation "The remote IP address of the client when
-this sessions was started as returned by REAL-REMOTE-ADDR.")
+                :documentation "The remote IP address of the client
+when this session was started as returned by REAL-REMOTE-ADDR.")
    (session-start :initform (get-universal-time)
                   :reader session-start
                   :documentation "The time this session was started.")



--===============3979258967521433474==--