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:refSTART-SESSION</clix:ref>, -clix:refSESSION-VALUE</clix:ref>, -maybe clix:refDELETE-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:descriptionclix:refSESSION</clix:ref> objects are @@ -1218,6 +1208,29 @@ </clix:description> </clix:special-variable>
+ <clix:function name='remove-session'> + clix:lambda-listsession + </clix:lambda-list> + clix:returns| + </clix:returns> + clix:descriptionCompletely removes +the clix:refSESSION</clix:ref> object clix:argsession</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:descriptionRemoves <em>all</em> stored sessions. + </clix:description> + </clix:function> + + <clix:special-variable name='*rewrite-for-session-urls*'> clix:descriptionWhether 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:descriptionA session GC (see function clix:refSESSION-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:refSESSION-CREATED</clix:ref>. - </clix:description> - </clix:special-variable>
- <clix:special-variable name='*session-max-time*'> - clix:descriptionThe default time (in seconds) after which a session times out. - </clix:description> - </clix:special-variable> - - <clix:special-variable name='*session-removal-hook*'> - clix:descriptionA function of one argument -(a clix:refSESSION</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:descriptionA random ASCII string that's used to encode -the public session data. This variable is initially unbound and will -be set (using clix:refRESET-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:descriptionWhether the client's remote IP (as returned by clix:refREAL-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-listsession + </clix:lambda-list> + clix:returnsremote-addr + </clix:returns> + clix:description +The remote IP address of the client when this session was started as +returned by clix:refREAL-REMOTE-ADDR</clix:ref>. + </clix:description> + </clix:function> + + <clix:special-variable name='*use-user-agent-for-sessions*'> - clix:descriptionWhether 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:descriptionWhether 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-listacceptor + <clix:function generic='true' name='session-user-agent'> + clix:lambda-listsession </clix:lambda-list> - clix:returnsid + clix:returnsuser-agent </clix:returns> - clix:descriptionReturns 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-listsession </clix:lambda-list> + clix:returnsmax-time + </clix:returns> + clix:description +Gets or sets the time (in seconds) after +which clix:argsession</clix:arg> expires if it's not used. + </clix:description> + </clix:accessor> + + + <clix:special-variable name='*session-max-time*'> + clix:descriptionThe default time (in seconds) after which a session times out. + </clix:description> + </clix:special-variable> + + <clix:special-variable name='*session-gc-frequency*'> + clix:descriptionA session GC (see function clix:refSESSION-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:refSESSION-CREATED</clix:ref>. + </clix:description> + </clix:special-variable> + + <clix:function name='session-gc'> + clix:lambda-list + </clix:lambda-list> clix:returns| </clix:returns> - clix:descriptionCompletely removes the SESSION object SESSION from Hunchentoot's -internal session database. + clix:descriptionRemoves sessions from the current session database which are too +old - see clix:refSESSION-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-listsession </clix:lambda-list> - clix:returnssecret + clix:returnsgeneralized-boolean </clix:returns> - clix:descriptionSets *SESSION-SECRET* to a new random value. All old sessions will -cease to be valid. + clix:descriptionReturns true if the clix:refSESSION</clix:ref> object clix:argsession</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:descriptionA function of one argument +(a clix:refSESSION</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:refSTART-SESSION</clix:ref>, +clix:refSESSION-VALUE</clix:ref>, +maybe clix:refDELETE-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:refSESSION</clix:ref>) and implement methods for +clix:refSESSION-VERIFY</clix:ref> +and clix:refSESSION-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:refSTART-SESSION</clix:ref> or +clix:refSESSION-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:descriptionA random ASCII string that's used to encode +the public session data. This variable is initially unbound and will +be set (using clix:refRESET-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:returnssecret </clix:returns> - clix:descriptionRemoves ALL stored sessions. + clix:descriptionSets 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-listacceptor </clix:lambda-list> clix:returnsname </clix:returns> - clix:descriptionReturns 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:descriptionReturns 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-listsession - </clix:lambda-list> - clix:returnsstring - </clix:returns> - clix:descriptionReturns 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-listacceptor new-session </clix:lambda-list> clix:returnsresult </clix:returns> - clix:descriptionThis 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:descriptionThis 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-listacceptor + </clix:lambda-list> + clix:returnsid + </clix:returns> + clix:descriptionReturns 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-listacceptor </clix:lambda-list> @@ -1372,8 +1465,8 @@ </clix:returns> clix:descriptionReturns 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:refSESSION</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:returnslock </clix:returns> - clix:descriptionA 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:descriptionA 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:argacceptor</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:descriptionRemoves 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-listsession - </clix:lambda-list> - clix:returnsmax-time - </clix:returns> - clix:description - </clix:description> - </clix:accessor> - - <clix:function generic='true' name='session-remote-addr'> - clix:lambda-listsession - </clix:lambda-list> - clix:returnsremote-addr - </clix:returns> - clix:description - </clix:description> - </clix:function> - - <clix:function name='session-too-old-p'> - clix:lambda-listsession - </clix:lambda-list> - clix:returnsgeneralized-boolean - </clix:returns> - clix:descriptionReturns 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-listsession - </clix:lambda-list> - clix:returnsuser-agent - </clix:returns> - clix:description - </clix:description> - </clix:function> - <clix:function generic='true' name='session-verify'> clix:lambda-listrequest </clix:lambda-list> @@ -1452,16 +1501,31 @@ </clix:returns> clix:descriptionTries 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:refREQUEST</clix:ref> object +clix:argrequest</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-listsession + </clix:lambda-list> + clix:returnsstring + </clix:returns> + clix:descriptionReturns a string which can be used to safely +restore the session clix:argsession</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.")
-
BKNR Commits