Nssession specification
In order to implement server-side session management, each and every user must be uniquely identifiable in order for session tracking to work. The two common approaches are cookie based and URL-tracking based. The first implementation will be cookie based but with URL-tracking in mind. If a browser doesn't support cookies or has them disabled, URL-tracking should be used instead.
In order to create a unique ID (UID), I propose the following method:
- Create a 64-byte string generated randomly from the set [a-zA-Z0-9].
Once the UID is generated and assigned to the client either by cookie or via URL-tracking, it should be stored in memory (using nsv) and the persistent store. In the current nssession reference implementation, the persistent store uses the filesystem.
In an environment where clustered webservers are in use, a RDBMS-backed persistent session-store is mandatory so that each machine in the cluster can refer to the same session data, and must query the RDBMS for every session variable access in order to ensure that the most recent session data is used. Also, writes must be done in a read-before-write fashion to avoid data collision. [[[ This needs some more thought. -- [Dossy]] ]]
Server-side session management allows for arbitrary key/value pairs to be maintained on the server side. One of the mandatory key/value pairs will be called "lastvisit" and it should stored in a format easily compared and manipulated (such as the number of seconds since the Epoch, such what is returned from [clock seconds]). A suggested mandatory key is "hitcount", which tracks the number of visits from the particular session.
For nsv (memory based) storage, sessions should be represented internally using the following format as the key to the nsv array:
nsv_set ns_session_data ${UID},lastvisit clock seconds
Using the comma "," as the delimiter in the array index means that a session variable name cannot have commas in them. An implementation of the nssession module should prevent this by either throwing an error. Silently removing the commas can lead to potential bugs in application code if two similarly-named session variables differ by placement of commas.
- ns_session init uid
Initializes the session identified by $uid with the mandatory defaults.
- ns_session create
Generate a new UID, then invokes ns_session init to initalize the session.
- ns_session destroy ?uid?
Completely deletes the current session both from memory and persistent store. If $uid is passed, then it will attempt to destroy that session instead.
- ns_session free ?uid?
Only removes the session from memory. [[[ Someday, a scheduled proc should probably invoke this to clean up periodically. -- [Dossy]] ]]
- ns_session save
Saves the current session to the persistent store.
- ns_session load
Loads the current session from the persistent store. If the session has been deleted from the persistent store, then create a new one (via ns_session init).
- ns_session set key value
Sets the session variable "key" with the value "value" for the current session.
- ns_session unset key
Deletes the session variable "key" from the current session. This differs from [ns_session set key {}], which simply sets variable "key" to a null string. This actually removes the variable from the session entirely.
- ns_session append key value
Appends value to key in the current session.
- ns_session lappend key value
Appends value to key in the current session in a list context.
- ns_session incr key
Increments (by one) variable key in the current session.
- ns_session exists key
Returns a boolean whether or not a particular key exists in the current session or not.
- ns_session get key
Returns the value of session variable "key" for the current session.
- ns_session keys
Returns the session variables for the current session. Includes mandatory session variables like "lastvisit". [[[ Should it really return the mandatory keys? It's probably more useful to return them and ignore them in application code than it is to not return them and have to maintain a list of mandatory session variables somewhere. -- [Dossy]] ]]
- ns_session set_uid uid
Sets the UID for the current session to $uid.
- ns_session get_uid
- ns_session uid
Returns the UID for the current session.
- ns_session valid
Returns a boolean whether or not a valid UID has been set for this session or not.
Stuff to write:
- garbage collection - a ns_schedule_proc that scans for lastvisit older than timeout period and does a [ns_session free uid] to reclaim memory
- [ns_session url] which returns the appropriate "uid=..." string for appending to URLs so that the UID will be passed via the HTTP GET method. [[[ Is this worthwhile? -- [Dossy]] ]]
Revision History:
