Documention for: acgiss.r
Created by: sunanda
on: 18-Dec-2006
Format: html
Downloaded on: 28-Mar-2024

1. anonymous cgi session services overview
2. installing acgiss.r
3. using acgiss.r
3.1. example
3.2. starting up
3.3. saving user data and starting a session
3.4. ending a session
3.5. extending a session
4. purging dead session records
5. configuring acgiss.r
5.1. set-parameter session-folder
5.2. set-parameter session-cookie-id
5.3. set-parameter session-duration
6. configuring and security
7. limitations
8. appendix: ways of keeping session data
     Author: Sunanda
    Version: 1.0
       Date: 18-dec-2006
 

1. anonymous cgi session services overview

acgiss.r allows you to save user-related data between invocations of a CGI script. Basically, it provides simple session support for you.

The sessions are anonymous as they do not require a visitor to identify themselves by name. acgiss.r simply feeds their user-agent (usually a web browser) with a cookie; acgiss.r then uses that cookie as an identifier to a record that holds any visitor-related data that you have saved,

2. installing acgiss.r

Copy the script to your cgi-bin folder -- or to the folder where you keep utility scripts (ie ones not directly executable by a user).

If you put it directly in your cgi-bin folder, then set the file permissions so it cannot be directly executed by a user (ie no public ability to read, write, or execute it).

You may want to change a couple of lines of code to adapt it to your own circumstamces. See Configuring acgiss.r below.

3. using acgiss.r

3.1. example

     do %acgiss.r                              ;; start the utility
     SESSION-RECORD: acgiss/get-session-record ;; retrieve session data
     either SESSION-RECORD/session-status = "new" [
        .... code for a new visitor []
        .... code for an old visitor
     ]
     append SESSION-RECORD/user-data "next=update"   ;; set some user-data
     acgiss/save-session SESSION-RECORD       ;; save the data
 

3.2. starting up

Add these two lines to your CGI scripts (or your user.r file in the CGI scripts folder):

      do %acgiss.r
      SESSION-RECORD: acgiss/get-session-record
  

(You can of course use your own word instead of SESSION-RECORD for the name).

session-record is a REBOL object, and will look something like this....

     make object! [
       scads-record-type: "acgiss"
       session-status: "new"
       session-expires: 18-Dec-2006/12:59:28
       session-id: {--some gibberish--}
       user-data: []
     ]
 

.... the session-status is new and there is nothing in user-data. This means there was no incoming cookie, so the user is not in a session with you.

If session-record looked more like this....

     make object! [
       scads-record-type: "acgiss"
       session-status: "old"
       session-expires: 18-Dec-2006/12:59:28
       session-id: {--some gibberish--}
       user-data: ["male" 29 true "both" "depends"]
     ]
 

.... then this is an existing session. There was an incoming cookie, and acgiss.r used it to retrieved the saved user-data. The user-data is something that your application has saved.

Simply calling acgiss/get-session-record does not start a session for you if one is not in progress; ie it does not send a cookie to the user-agent. To start a session, see immediately below.

3.3. saving user data and starting a session

The easiest way is:

      append SESSION-RECORD/user-data ["male" 29 true "both" "depends"]
      acgiss/save-session SESSION-RECORD
 

That will add some data to the user-data block, save SESSION-RECORD, and write a cookie, if needed.

You can make multiple calls to acgiss/save-session. It will only write a cookie on the first call.

If the user-data block is not flexible enough for your needs, you can add words to the SESSION-RECORD object, eg:

  SESSION-RECORD: make SESSION-RECORD [sex: "male" age: 29]
 

If you do that, please do not overwrite the four control fields: scads-record-type, session-status, session-expires, session-id.

3.4. ending a session

  acgiss/end-session SESSION-RECORD
 

The cookie (if any) will be deleted from memory, and the saved session-record will be deleted from your hard drive.

3.5. extending a session

By default, we create cookies with a life of 24 hours (you can change that default -- see configuring acgiss.r below). If you want to extend a cookie once a session is under way:

 acgiss/extend-session: SESSION-RECORD 72:00:00
 

Will extend the cookie's life by 72 hours from now.

4. purging dead session records

Many sessions will not formally end, so you cannot call an end-session; the visitor just drifts away and never comes back.

That may mean that, over time, 1000s of expired session records pile up in your acgiss.r working folder.

To clear those out on a regular basis, you could add a CRON (or equivalent) batch process that deletes any file in the acgiss.r working folder that is older than (say) 48 hours.

That may however remove some session records that were intended to last longer -- ie had a session-expiry of more than 48 hours.

To delete only expired session records, call acgiss.r from a CRON job like this:

     do %acgiss.r
     acgiss/set-parameters "session-folder" %.... ;; see configuring below
     acgiss/purge-expired-sessions
 

To limit the time that the purge runs, you can ask it to stop after purging some records....

     do %acgiss.r
     acgiss/purge-expired-sessions/limit 100
 

.... you may then need to run the CRON more often to prevent expired session records piling up.

5. configuring acgiss.r

There are some run-time parameters that you may want to change. You can do that in two ways:

The first method means you need to make the change only once per installation of acgiss.r. The second method gives you more flexibility at run time.

Example of set-parameter:

      do %acgiss.r
      acgiss/set-parameter "session-folder" %/c/apache/acgiss-work-folder/
      acgiss/set-parameter "session-duration" 3:15:00
 

The above example:

Either way, there are three parameters:

5.1. set-parameter session-folder

Sets the folder in which we save session records. By default, it is %../acgiss-work-folder/

5.2. set-parameter session-cookie-id

Sets the identifying name in the cookie, By default it is acgiss, so a cookie looks like:

cookie: acgiss=xxxxxxxxx 
To change the name field in cookies to sid :
acgiss/set-parameter "session-cookie-id" "sid" 

5.3. set-parameter session-duration

Sets how long a session will last. By default, it is 24 hours. To make it 168 hours (one week) instead:

acgiss/set-parameter "session-duration" 168:00:00 

If you use:

acgiss/set-parameter "session-duration" none 

Then the cookie expires as soon as the visitor closes their web browser.

6. configuring and security

I recommend that you change the default settings for all three parameters. This is so your application does not leak data to potential hackers. If a hacker sees a cookie with an acgiss= keyword in it, you have leaked potentially useful information:

I am fully aware that security by obscurity alone is not a safe approach. But keeping things secret that can be kept secret is simply prudent; no need to give the bad guys a head start.

7. limitations

acgiss.r uses the simplest possible mechanism for setting and retrieving a cookie.

We simple Version 0 HTTP cookie. Version 1 HTTP cookies (which, confusingly are known as COOKIE2) have greater flexibility.

That limits acgiss.r to a single cookie per visitor. If you need multiple cookies per visitor, you'll need to tweak the code that retrieves and sets the cookie in system/options/cgi/other-headers.

You may also want to add some extra settings to allow COOKIE-type keywords (path, domain, etc) to be set.

If you do so, please consider letting us use your changes to make an improved version of acgiss.r

8. appendix: ways of keeping session data

HTTP was originally a stateless, anonymous protocol: there was no real way to handle continuity between incoming messages from the same visitor.

There are three main ways to change it to a stateful connection. All have problems. The one acgiss.r uses is cookies.

The three ways are:

Each method has its strong points and weaknesses.

It'd be relatively easy to extend acgiss.r to support multiple mechanisms.....Feel free to do so if you'd like to.