| 4 | | <title>Session Management</title> |
|---|
| 5 | | <abstract> |
|---|
| 6 | | <para> CherryPy 2.1 includes a powerful sessions system provided via a new "sessionFilter". The |
|---|
| 7 | | old sessions system was difficult to extend and was not thread safe. |
|---|
| 8 | | </para> |
|---|
| 9 | | </abstract> |
|---|
| 10 | | <itemizedlist> |
|---|
| 11 | | <listitem> |
|---|
| 12 | | <section> |
|---|
| 13 | | <title>sessionFilter.on</title> |
|---|
| 14 | | <para> Can be True or False. Will toggle on/off a specific named session. The setting |
|---|
| 15 | | only affects individual sessions, the sessionfilter must still be turned on using |
|---|
| 16 | | sessionFilter.on. </para> |
|---|
| 17 | | </section> |
|---|
| 18 | | </listitem> |
|---|
| 19 | | <listitem> |
|---|
| 20 | | <section> |
|---|
| 21 | | <title>sessionFilter.storageType</title> |
|---|
| 22 | | <para> The storagType is the string name of the storage type for sessionName. The built |
|---|
| 23 | | in storageType are: 'ram', 'file',</para> |
|---|
| 24 | | </section> |
|---|
| 25 | | </listitem> |
|---|
| 26 | | <listitem> |
|---|
| 27 | | <section> |
|---|
| 28 | | <title>sessionFilter.timeout</title> |
|---|
| 29 | | <para> The number of minutes of inactivity before an individual session can be removed. |
|---|
| 30 | | </para> |
|---|
| 31 | | </section> |
|---|
| 32 | | </listitem> |
|---|
| 33 | | <listitem> |
|---|
| 34 | | <section> |
|---|
| 35 | | <title>sessionFilter.cleanUpDelay</title> |
|---|
| 36 | | <para> The number of minutes to wait before cleaning up old sessions. </para> |
|---|
| 37 | | </section> |
|---|
| 38 | | </listitem> |
|---|
| 39 | | </itemizedlist> |
|---|
| | 4 | <title>Session Management</title> |
|---|
| | 5 | <abstract> |
|---|
| | 6 | <para>CherryPy 2.1 includes a powerful sessions system provided via a new <literal>sessionFilter</literal>. </para> |
|---|
| | 7 | </abstract> |
|---|
| | 8 | <section id="usingsessions"> |
|---|
| | 9 | <title>Using Sessions</title> |
|---|
| | 10 | <para>First you need to enable the session filter through the configuration system, by setting <option>sessionFilter.on</option> to <literal>True</literal>. This gives you a variable called <literal>cherrypy.session</literal>, which is a dictionary-like object where you can read/store your session data. This dictionnary always has a special key called <literal>_id</literal> which contains the session id.</para> |
|---|
| | 11 | <para>Here is a sample code showing how to implement a simple counter using sessions:</para> |
|---|
| | 12 | <example> |
|---|
| | 13 | <programlisting> |
|---|
| | 14 | import cherrypy |
|---|
| | 15 | class Root: |
|---|
| | 16 | def index(self): |
|---|
| | 17 | count = cherrypy.session.get('count', 0) + 1 |
|---|
| | 18 | cherrypy.session['count'] = count |
|---|
| | 19 | return 'Counter: %s' % count |
|---|
| | 20 | index.exposed = True |
|---|
| | 21 | |
|---|
| | 22 | cherrypy.config.update({'sessionFilter.on': True}) |
|---|
| | 23 | cherrypy.server.start() |
|---|
| | 24 | </programlisting> |
|---|
| | 25 | </example> |
|---|
| | 26 | </section> |
|---|
| | 27 | <section> |
|---|
| | 28 | <title>Configuring sessions</title> |
|---|
| | 29 | <para> The following configuration options are available for "sessionFilter": </para> |
|---|
| | 30 | <itemizedlist> |
|---|
| | 31 | <listitem> |
|---|
| | 32 | <para><option>sessionFilter.on</option>: |
|---|
| | 33 | <literal>True</literal> or <literal>False</literal> (default): enable/disable sessions</para> |
|---|
| | 34 | </listitem> |
|---|
| | 35 | <listitem> |
|---|
| | 36 | <para><option>sessionFilter.storageType</option>: |
|---|
| | 37 | Specify which storage type should be used for storing session data on the server. Built-in types are <literal>Ram</literal> (default), <literal>File</literal> and <literal>PostgreSQL</literal> (see <xref linkend="backends"/> for more info)</para> |
|---|
| | 38 | </listitem> |
|---|
| | 39 | <listitem> |
|---|
| | 40 | <para><option>sessionFilter.timeout</option>: |
|---|
| | 41 | The number of minutes of inactivity before an individual session can be removed. It can be a float (ex: 0.5 for 30 seconds). Defaults to 60.</para> |
|---|
| | 42 | </listitem> |
|---|
| | 43 | <listitem> |
|---|
| | 44 | <para><option>sessionFilter.cleanUpDelay</option>: |
|---|
| | 45 | Once in a while the server cleans up old/expired sessions. This config option specifies how often this clean up process should happe. The delay is in minutes. Defaults to 5.</para> |
|---|
| | 46 | </listitem> |
|---|
| | 47 | <listitem> |
|---|
| | 48 | <para><option>sessionFilter.cookieName</option>: |
|---|
| | 49 | The name of the cookie that CherryPy will use to store the session ID. Defaults to <literal>sessionID</literal>.</para> |
|---|
| | 50 | </listitem> |
|---|
| | 51 | <listitem> |
|---|
| | 52 | <para><option>sessionFilter.getDB</option>: |
|---|
| | 53 | See the <option>PostgreSQL</option> backend from <xref linkend="backends"/>.</para> |
|---|
| | 54 | </listitem> |
|---|
| | 55 | <listitem> |
|---|
| | 56 | <para><option>sessionFilter.deadlockTimeout</option>: |
|---|
| | 57 | See <xref linkend="concurrent"/>.</para> |
|---|
| | 58 | </listitem> |
|---|
| | 59 | <listitem> |
|---|
| | 60 | <para><option>sessionFilter.onCreateSession</option>: |
|---|
| | 61 | See <xref linkend="callbacks"/>.</para> |
|---|
| | 62 | </listitem> |
|---|
| | 63 | <listitem> |
|---|
| | 64 | <para><option>sessionFilter.onDeleteSession</option>: |
|---|
| | 65 | See <xref linkend="callbacks"/>.</para> |
|---|
| | 66 | </listitem> |
|---|
| | 67 | <listitem> |
|---|
| | 68 | <para><option>sessionFilter.storageClass</option>: |
|---|
| | 69 | See <xref linkend="custombackend"/>.</para> |
|---|
| | 70 | </listitem> |
|---|
| | 71 | </itemizedlist> |
|---|
| | 72 | </section> |
|---|
| | 73 | |
|---|
| | 74 | <section id="backends"> |
|---|
| | 75 | <title>Choosing the backend</title> |
|---|
| | 76 | <para>CherryPy comes with multiple build-in backends for storing session data on the server side. They are:</para> |
|---|
| | 77 | |
|---|
| | 78 | <itemizedlist> |
|---|
| | 79 | <listitem> |
|---|
| | 80 | <para><option>Ram</option>: |
|---|
| | 81 | All data is stored in RAM; this is the fastest storage, but it means that the data will be lost if you restart the server; and it also means that it won't scale to multiple processes/machines</para> |
|---|
| | 82 | </listitem> |
|---|
| | 83 | <listitem> |
|---|
| | 84 | <para><option>File</option>: |
|---|
| | 85 | All data is stored on disk; this is a bit slower than Ram storage, but the data will persist if you restart the server server; it also means that data can also be shared amongst multiple CherryPy processes (either on the same machine, or on multiple machines if all machines have access to the same disk ... through something like NFS for instance)</para> |
|---|
| | 86 | </listitem> |
|---|
| | 87 | <listitem> |
|---|
| | 88 | <para><option>PostgreSQL</option>: |
|---|
| | 89 | This backend is included with CherryPy to show how easy it is to implement your own custom backend for the session system. All data is stored in a PostgreSQL database; storing your data in a database is the recommend setup for production if you have a very high traffic website and you need to scale your site accross multiple machines. To use this backend you'll need to create the following table in your PostgreSQL database: |
|---|
| | 90 | <screen> |
|---|
| | 91 | create table session ( |
|---|
| | 92 | id varchar(40), |
|---|
| | 93 | data text, |
|---|
| | 94 | expiration_time timestamp |
|---|
| | 95 | ) |
|---|
| | 96 | </screen> |
|---|
| | 97 | </para> |
|---|
| | 98 | You also need to programmatically set the <literal>sessionFilter.getDB</literal> config option to a function that returns a DB connection. |
|---|
| | 99 | </listitem> |
|---|
| | 100 | </itemizedlist> |
|---|
| | 101 | </section> |
|---|
| | 102 | |
|---|
| | 103 | <section id="custombackend"> |
|---|
| | 104 | <title>Writing your own custom backend</title> |
|---|
| | 105 | <para>By default, CherryPy comes with 3 built-in backends, but if you have specific needs, it is very easy to implement your own custom backend (for instance, another database, or an XML-RPC server, ...). To do so, all you have to do is write a class that implements the following methods: |
|---|
| | 106 | <screen> |
|---|
| | 107 | class MyCustomBackend: |
|---|
| | 108 | def save(self, id, data, expirationTime): |
|---|
| | 109 | """ Save the session data and expirationTime for that session id """ |
|---|
| | 110 | def load(self, id): |
|---|
| | 111 | """ Load the session data and expirationTime for 'id' and return |
|---|
| | 112 | a tuple (data, expirationTime) (even if the session is |
|---|
| | 113 | expired). Return None if id doesn't exist. """ |
|---|
| | 114 | def cleanUp(self): |
|---|
| | 115 | """ Delete expired session data from storage and call |
|---|
| | 116 | 'onDeleteSession' for each deleted session id """ |
|---|
| | 117 | </screen> |
|---|
| | 118 | Note that if you want to use <option>explicit</option> locking (see <xref linkend="concurrent"/>), you also have to implement two extra methods: <literal>acquireLock</literal> and <literal>releaseLock</literal>. |
|---|
| | 119 | </para> |
|---|
| | 120 | |
|---|
| | 121 | <para>Once you have written this class, you have to programmatically set the <literal>sessionFilter.storageClass</literal> config option to this class.</para> |
|---|
| | 122 | |
|---|
| | 123 | <para>If you need help in writing your own custom backend it is a good idea to look at how the current ones (ram, file and postgresql) are implemented. They are implemented in the file <filename>cherrypy/lib/filter/sessionfilter.py</filename></para> |
|---|
| | 124 | </section> |
|---|
| | 125 | |
|---|
| | 126 | <section id="concurrent"> |
|---|
| | 127 | <title>Handling concurrent requests for the same session data</title> |
|---|
| | 128 | <para>It is normally quite rare to have to simultaneous requests with the same session ID. It means that a same browser is making 2 requests to your server at the same time (to dynamic pages ... static pages don't have sessions). However, this case can happen (if you're using frames for instance), and it will happen more and more often as more and more people start using Ajax.</para> |
|---|
| | 129 | <para>In that case, we need to make sure that access to the session data is serialized. This way threads can't both modify the data at the same time and leave it in an inconsistent state.</para> |
|---|
| | 130 | <para>By default, CherryPy will serialize access to the session data, so if a browser makes a second request while a first request is still being handled by the server, the second request will block while the first request is accessing the data. As soon as the first request is finished then the second request will be able to access it.</para> |
|---|
| | 131 | <para>This means that the second request will block until the first request is finished. If you're using the <option>ram</option> backend, you can manually shorten the window where the second request will block. This is achieved by having the first request explicitely tell CherryPy when it starts using the session data and when it is finished with it. In order to do so, you have to call <literal>cherrypy.session.acquireLock</literal> and <literal>cherrypy.session.releaseLock</literal>. You also have to set the <literal>sessionFilter.locking</literal> config option to <option>explicit</option>.</para> |
|---|
| | 132 | <para>Note that this technique only works with the <option>ram</option> backend. For other backends like <option>file</option> or <option>postgresql</option>, it is not safe to release the session before the request is finished, because the session data will only be saved at the end of the request anyway. So it would be bad if some other thread started accessing the data between the time when it is released and the time when it is saved. |
|---|
| | 133 | </para> |
|---|
| | 134 | </section> |
|---|
| | 135 | |
|---|
| | 136 | <section id="callbacks"> |
|---|
| | 137 | <title>Being notified when sessions are created/deleted</title> |
|---|
| | 138 | <para>It is possible to configure the <literal>sessionFilter</literal> so that it calls some special callback functions from your code when sessions are being created/deleted. To do so you have to set the <literal>sessionFilter.onCreateSession</literal> and <literal>sessionFilter.onDeleteSession</literal> config options. When a session is created/deleted, CherryPy will call these functions and pass them the session data.</para> |
|---|
| | 139 | </section> |
|---|
