[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/
BKNR Commits
bknr at bknr.net
Wed Feb 18 22:12:41 UTC 2009
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
===================================================================
--- trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-18 21:25:42 UTC (rev 4282)
+++ trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-18 22:12:41 UTC (rev 4283)
@@ -1136,16 +1136,6 @@
not <a href="#session-too-old-p">too old</a>. Old sessions
are <a href="#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>
<clix:class name='session'>
<clix:description><clix:ref>SESSION</clix:ref> objects are
@@ -1218,6 +1208,29 @@
</clix:description>
</clix:special-variable>
+ <clix:function name='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's internal <a href="#session-db">session
+database</a>.
+ </clix:description>
+ </clix:function>
+
+
+ <clix:function name='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='*rewrite-for-session-urls*'>
<clix:description>Whether HTML pages should possibly be rewritten for cookie-less
session-management.
@@ -1231,38 +1244,7 @@
</clix:description>
</clix:special-variable>
- <clix:special-variable name='*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:special-variable name='*session-max-time*'>
- <clix:description>The default time (in seconds) after which a session times out.
- </clix:description>
- </clix:special-variable>
-
- <clix:special-variable name='*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="#session-gc">garbage-collected</a>.
- </clix:description>
- </clix:special-variable>
-
- <clix:special-variable name='*session-secret*'>
- <clix:description>A random ASCII string that'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="#acceptors">acceptors</a>.
- </clix:description>
- </clix:special-variable>
-
-
-
<clix:special-variable name='*use-remote-addr-for-sessions*'>
<clix:description>Whether the client's remote IP (as returned by <clix: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>
+ <clix:function generic='true' name='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='*use-user-agent-for-sessions*'>
- <clix:description>Whether the 'User-Agent' 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 'User-Agent' header.
+ <clix:description>Whether the 'User-Agent' 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
+'User-Agent' header.
</clix:description>
</clix:special-variable>
-
- <clix:function generic='true' name='next-session-id'>
- <clix:lambda-list>acceptor
+ <clix:function generic='true' name='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't guarded by a lock. For a
-high-performance production environment you might consider to use a
-more robust implementation.
+ <clix:description>
+The incoming 'User-Agent' header that
+was sent when this session was created.
</clix:description>
</clix:function>
- <clix:function name='remove-session'>
+ <clix:accessor generic='true' name='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='*session-max-time*'>
+ <clix:description>The default time (in seconds) after which a session times out.
+ </clix:description>
+ </clix:special-variable>
+
+ <clix:special-variable name='*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='session-gc'>
+ <clix:lambda-list>
+ </clix:lambda-list>
<clix:returns>|
</clix:returns>
- <clix:description>Completely removes the SESSION object SESSION from Hunchentoot's
-internal session database.
+ <clix:description>Removes sessions from the current session database which are too
+old - see <clix:ref>SESSION-TOO-OLD-P</clix:ref>.
</clix:description>
</clix:function>
- <clix:function name='reset-session-secret'>
- <clix:lambda-list>
+ <clix:function name='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 sessions will
-cease to be valid.
+ <clix:description>Returns true if the <clix:ref>SESSION</clix:ref> object <clix:arg>session</clix:arg> has not been active in
+the last <code>(session-max-time session)</code> seconds.
</clix:description>
</clix:function>
- <clix:function name='reset-sessions'>
+
+ <clix:special-variable name='*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="#session-gc">garbage-collected</a>.
+ </clix:description>
+ </clix:special-variable>
+
+
+ </clix:subchapter>
+
+
+ <clix:subchapter name="session-behaviour" title="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="#*session-secret*">secret</a> which you can set yourself.</li>
+<li>And it is stored using a cookie (or GET
+parameter) <a href="#session-cookie-name">name</a> that you can
+override.</li>
+<li>Each session receives a <a href="#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="#session-created">created</a> to trigger some action. You
+might also do this to invent your own
+session <a href="#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="#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="#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='*session-secret*'>
+ <clix:description>A random ASCII string that'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="#acceptors">acceptors</a>.
+ </clix:description>
+ </clix:special-variable>
+
+ <clix:function name='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>
+
+
<clix:function generic='true' name='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 "hunchentoot-session", 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>"hunchentoot-session"</code>, but you can
specialize this function if you want another name.
</clix:description>
</clix:function>
- <clix:function generic='true' name='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's no reason to change it unless you want to use your own
-session objects.
- </clix:description>
- </clix:function>
-
<clix:function generic='true' name='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'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's a default method which might trigger
+a <a href="#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>
+
+ <clix:function generic='true' name='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'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='true' name='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'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>
@@ -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="#acceptors">acceptor</a> that handles the
+current <a href="#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>
- <clix:function name='session-gc'>
- <clix:lambda-list>
- </clix:lambda-list>
- <clix:returns>|
- </clix:returns>
- <clix:description>Removes sessions from the current session database which are too
-old - see SESSION-TOO-OLD-P.
- </clix:description>
- </clix:function>
-
- <clix:accessor generic='true' name='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='true' name='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='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 been active in
-the last (SESSION-MAX-TIME SESSION) seconds.
- </clix:description>
- </clix:function>
-
- <clix:function generic='true' name='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='true' name='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>
+ <clix:function generic='true' name='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's no reason to change it unless you
+want to use your own session objects.
+ </clix:description>
+ </clix:function>
+
</clix:subchapter>
<clix:subchapter name="handlers" title="Handlers">
Modified: trunk/thirdparty/hunchentoot/session.lisp
===================================================================
--- trunk/thirdparty/hunchentoot/session.lisp 2009-02-18 21:25:42 UTC (rev 4282)
+++ trunk/thirdparty/hunchentoot/session.lisp 2009-02-18 22:12:41 UTC (rev 4283)
@@ -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.")
More information about the Bknr-cvs
mailing list