Storing sessions in a database is a good solution. Backups are easier; persistence and pruning orphaned sessions are simpler. Security is available through the database server’s security. We will use MySQL, since it is the best supported in newLISP.

Setting up the database

First, we need a table in which to store session data. Using a MySQL TIMESTAMP column will provide us with an automatically updating time stamp on the last modification of the session, which we will use below to find old sessions to remove.

CREATE TABLE sessions (
	sid VARCHAR(255) PRIMARY KEY,
	DATA TEXT NOT NULL,
	ts TIMESTAMP
)

Designing the storage module

Several functions need to be defined to handle storing data. First, we must ensure that the MySQL module is loaded and initialized. We will do this in a separate module that we will call DBSessions.

(context 'DBSessions)
 
(unless (sym "MYSQL" 'MySQL nil) ; do not reinitialize if already loaded
  (module "mysql5.lsp") ; with newlisp 10.1, this will change to "mysql.lsp"
  (MySQL:init)
  (MySQL:connect "127.0.0.1" "user" "secret" "somedb"))
 
(context 'MAIN)

Next, we define a function to create or resume a session from the database. Sessions are stored in memory as contexts, making our job easier. Our function will query MySQL to see if the session id exists, and either create a new session and insert it or retrieve an existing session and load it. The function Web:session-id gives us the current session id from the session cookie or creates a new one and sends the client a cookie to store it. Web:session-context returns a symbol pointed to the context storing the current session.

(define (open-session)
  (when (MySQL:query (format "SELECT data FROM sessions WHERE sid = '%s'" (MySQL:escape (Web:session-id))))
    (let ((data (MySQL:fetch-row)))
      (if data
        ;; Evaluate the serialized context into the current session context
        (eval-string (first data) (Web:session-context))
        ;; Create a new session and save it
        (MySQL:query (format "INSERT INTO sessions (sid, data) VALUES ('%s', '%s')"
          (MySQL:escape (Web:session-id))
          (MySQL:escape (source (Web:session-context)))))))))

Next, we need a function to write any changes to the session to storage. Since the session is stored as a context, this is quite simple.

(define (close-session)
  (MySQL:query (format "UPDATE sessions SET data = '%s' WHERE sid = '%s'"
    (MySQL:escape (source (Web:session-context)))
    (MySQL:escape (Web:session-id)))))

We also need a function to delete entire sessions when necessary. This is also simple.

(define (delete-session)
  (MySQL:query (format "DELETE FROM sessions WHERE sid = '%s'"
    (MySQL:escape (Web:session-id)))))

Finally, a function to cull old sessions from the database. For this, we use the variable Web:SESSION_MAX_AGE to determine which sessions have expired.

(define (clean-sessions)
  (MySQL:query (format "DELETE FROM sessions WHERE NOW() >= DATE_ADD(ts, INTERVAL %d SECOND)"
    Web:SESSION_MAX_AGE)))

Registering the handler in Web

Last, the handler functions need to be registered in the Web module.

(Web:define-session-handlers
  open-session close-session delete-session clean-sessions)

Putting it all together

(unless (sym "MYSQL" 'MySQL nil) ; do not reinitialize if already loaded
  (module "mysql5.lsp") ; with newlisp 10.1, this will change to "mysql.lsp"
  (MySQL:init)
  (MySQL:connect "127.0.0.1" "user" "secret" "somedb"))
 
(context 'DBSessions)
 
(define (open-session)
  (when (MySQL:query (format "SELECT data FROM sessions WHERE sid = '%s'" (MySQL:escape (Web:session-id))))
    (let ((data (MySQL:fetch-row)))
      (if data
        ;; Evaluate the serialized context into the current session context
        (eval-string (first data) (Web:session-context))
        ;; Create a new session and save it
        (MySQL:query (format "INSERT INTO sessions (sid, data) VALUES ('%s', '%s')"
          (MySQL:escape (Web:session-id))
          (MySQL:escape (source (Web:session-context)))))))))
 
(define (close-session)
  (MySQL:query (format "UPDATE sessions SET data = '%s' WHERE sid = '%s'"
    (MySQL:escape (source (Web:session-context)))
    (MySQL:escape (Web:session-id)))))
 
(define (delete-session)
  (MySQL:query (format "DELETE FROM sessions WHERE sid = '%s'"
    (MySQL:escape (Web:session-id)))))
 
(define (clean-sessions)
  (MySQL:query (format "DELETE FROM sessions WHERE NOW() >= DATE_ADD(ts, INTERVAL %d SECOND)"
    Web:SESSION_MAX_AGE)))
 
(Web:define-session-handlers
  open-session close-session delete-session clean-sessions)
 
(context 'MAIN)

Submit article

The official CGI module has some real issues. First, it combines POST and GET variables into a single structure. This has two serious consequences: 1) the application has no way to determine the method by which a parameter is passed (that information is completely lost), and 2) name clashes between GET and POST result in the loss of one or the other parameter (in the case of the CGI module, GET information would be overwritten.)

Another issue in the CGI module is with the put-page function, which breaks if “%>” is used inside of a code island, even legitimately, such as in a string.

Web fixes both of these problems and provides a number of other features, including:

• ASP/PHP-style templates
• Getting/setting cookies, GET, and POST parameters
• Entity encoding and decoding
• HTTP header control
• Sessions
• Custom session storage
• URL building and parsing
• URL encoding and decoding
• Query string building and parsing

Additionally, Web does not suffer from the GET/POST issues that the CGI module does, nor does it mishandle tags inside of code.

HTTP Headers

Headers are set using Web:header, which accepts two parameters – the header name and the header value. By default, one header is already set: Content-type: text/html. Headers are output using Web:send-headers, which is called before any other output. The convenience function Web:redir redirects the browser to the passed URL.

GET and POST

GET and POST variables are accessed using Web:get and Web:post, which may be called in two ways. When called with a single parameter, these functions act like lookup and return the GET/POST parameter with the named key. When called with no parameters, they return an association list of the corresponding query.

Cookies

Cookies must be set before headers are sent. They are set using the Web:cookie function, which accepts up to six parameters.

;; Set a basic cookie
(cookie "foo" "bar")
;; Access a cookie value
(cookie "foo")
;; Delete a cookie by setting expires to now
(cookie "foo" nil (date-value))
;; Set a cookie that expires in an hour
(cookie "foo" "bar" (+ (date-value) (* 60 60)))

See the documentation for a full list of accepted parameters.

Sessions

By default, sessions use file-based storage (located at /tmp). They are controlled with a few simple functions. The default exit function is wrapped to ensure that Web:close-session is called at the end of a script (at least, a script that calls exit at its end.)

(Web:open-session)
(Web:session "foo" "bar") ; store "foo" as "bar"
(Web:send-headers) ; start output
(println "<p><strong>foo is:</strong> " (Web:session "foo") "</p>")
(exit 0)

It is a simple matter to design and use custom storage handlers. The function Web:define-session-handlers allows customization of which functions are called to begin/load, close/write, delete a session, and clear old sessions. See the documentation for a list of helpful functions and variables for custom storage handlers.

Templates

Templates work almost identically to the official CGI module, with a few differences. First, Web:eval-template is called with a string, rather than a file, to permit other storage methods and programmatic building of templates. Second, <%= .. %> may be substituted for the default opening tag as a shortcut for <% (print … ) %>. Last, the opening and closing tags may be customized by setting values of Web:OPEN_TAG and Web:CLOSE_TAG. The shortcut tag will always be Web:OPEN_TAG appended with and equal sign.

Encoding and decoding

There are several functions to make encoding, decoding, and escaping strings easier for dealing with URLs, javascript, and HTML entities.

Web:escape takes a string and encodes the basic HTML character entities (apostrophe, quote, ampersand, and left and right angle brackets.) Web:unescape provides the reverse. The function Web:escape-js does no encoding of entities, but instead ensures that a string may be safely output in javascript string without causing syntax errors.

Web:encode-entities encodes all HTML entities, including a number of entities that are not fully supported by all browser. The full list of entities is derived from Wikipedia. Its reverse, Web:decode-entities, translates entities back into their character equivalents.

The functions Web:url-encode and Web:url-decode deal with hex-encoding/decoding strings for use in URLs.

Query strings are easily created using Web:build-query, modeled after the PHP function http_build_query. Its counterpart, Web:parse-query, takes a query string and turns it into an association list.

For URLs, it is simpler to use Web:build-url, which takes a URL and any number of association lists which it uses to build a complete URL. Each alist may overwrite parameters from the previous, including any parameters on the passed URL.

(let ((url "http://www.artfulcode.net/?s=newlisp"))
  (println (Web:build-url url '(("s" "newlisp web module") ("foo" "bar")))))
;; => http://www.artfulcode.net/?s=newlisp+web+module&foo=bar

It also has a counterpart, Web:parse-url, which breaks a URL up into an association list of its component parts.

Download

You can find it in the repository or download it directly here.

Submit article