Session

What is a Session?

The main purpose of sessions is to workaround the stateless aspect of HTTP protocol. This means that by default, no state information is saved between two requests from the same client. So, in order to make an application, you need to save some data somewhere and keep it associated with a given client. This is exactly what the Session object does.

To be able to track a given client, Cheyenne uses a session cookie. You can also insert the session ID manually in URL or HTML forms if the client doesn't support cookies (very unlikely nowadays). The session ID cookie name is RSPSID and its type is HTTPOnly (a secured way to store session cookies in client browser memory).

Cheyenne will associate this session ID and the client IP address with a REBOL object stored in memory and shared by worker processes. The main purpose is to allow storing persistent data in the session across requests and across workers.

A session has a limited lifetime, it will expire by default, after 20 minutes of idle time (timeout). This delay can be changed easily using the timeout? configuration keyword, or using session/timeout call from an RSP script.

Session data

To be able to share data using sessions, you first need to add some variables to the session context. This is achieved using the session/add function. Here's an example:

 session/add 'username "John"
 session/add 'age 25

To read back these values, use the session/content block! series direct access:

 print session/content/username
 print session/content/age

The session data is the fastest and safest way to share data between several RSP scripts.

Note: Watch out for session shared value memory usage. As sessions values are transmitted between processes, adding big block! or string! series will have a significant impact on RSP scripts performances and Cheyenne memory usage. Try to keep the session data as small as possible.

Manual mode

By default, your RSP scripts live without any session. You need to explicitly start a session first before any other session operation, using session/start, then you can start adding data in it. You need to start it just once, the session will be then available in all other RSP scripts in the same folder or sub-folders.

In order to write safe code when accessing session data (from a script that hasn't started the session), you need to test if the session is active or not (and activate it in the later case):

 <%
     unless session/active? [
         session/start
         session/add 'username none
     ]
     name: session/content/username
     ...
 %>

This can be done in an even shorter form combining session testing & starting:

 <%
     unless session/start [
         session/add 'username none
     ]
     name: session/content/username
     ...
 %>

Of course, it is also possible to close the session using session/end function. All session data is then lost. It is possible to open a new session for the same client by calling session/start again.

Keep in mind that sessions have a cost in Cheyenne resources and performances, try to start them only then it is really needed and close them as soon as you don't need them anymore.

Note: This manual session handling mode should be familiar to PHP coders, but the automatic mode is the best way to manage sessions in Cheyenne.

Automatic mode

This is the best way to use sessions as you don't have to mess around with starting/testing/ending sessions manually, you just need to declare a webapp container in the configuration file, and Cheyenne will do the rest for you!

In this mode, the session applies automatically to all RSP scripts inside the webapp folder. So you don't need to use session/start and session/end in this case. Session objects will be automatically garbage-collected after the session's expiration delay.

A special login word is added to session/content, with a value of false. If the auth? configuration directive is present in the webapp definition, this value indicates the state of the user authentication. It is used internally by the webapp to secure access to all its files, until the user logs in and an RSP script sets the login value to true, giving access to all the files.

More information about automatic session mode on the webapp page.

Session events

In addition to other benefits from using a webapp, you also get two session-related events:

• on-session-start: called when a new session starts.
• on-session-end: called when a session is destroyed.

You can implement these events as functions in the webapp's %app-init.r definition file to add, e.g., all the required session variables in the start event.

More information about webapp's events on the webapp page.