http-session

Introduction

http-session is an implementation of facilities for managing HTTP sessions of web applications.

Repository

https://github.com/mario-goulart/http-session/

API

Parameters

session-lifetime

[parameter] (session-lifetime [number])

The lifetime of sessions in seconds. Default is 3600s (1h).

session-id-generator

[parameter] (session-id-generator [procedure])

A zero argument procedure which generates a random unique identifier for sessions. Defaults to a procedure which concatenates current-milliseconds with the process ID and a random number between 0 and 1000 plus the current-process-id and returns its SHA-1 digest.

match-ip-address?

[parameter] (match-ip-address? [boolean])

Indicates whether http-session should match IP addresses to check if sessions are valid.

Procedures

session-create

[procedure] (session-create #!optional (bindings '()))

Creates a session and returns the session identifier.

The optional bindings argument is an alist '((symbol . value)...) of variable bindings valid for the generated session.

session-refresh!

[procedure] (session-refresh! sid)

Refreshes the session identified by sid, that is, sets the lifetime of the session identified by sid to (session-lifetime).

session-valid?

[procedure] (session-valid? sid)

Returns #t if the session identified by sid is valid. Returns #f otherwise.

A session is valid if (all items should be satisfied):

There is a session identifier equal to sid in the session table
The session lifetime corresponding to the session identified by sid is greater than zero
When match-ip-address? is not #f, the IP number corresponding to the session identified by sid matches the IP number of the client

 (use awful http-session)
 
 (define (session-item->list session-item)
   (list (session-item-expiration session-item)
         (session-item-ip session-item)
         (session-item-bindings session-item)
         (session-item-finalizer session-item)))
 
 (define (list->session-item l)
   (apply make-session-item l))
 
 (session-storage-initialize
  (lambda ()
    (let ((dir (create-temporary-directory)))
      (print "Using " dir " as sessions-dir.")
      dir)))
 
 (session-storage-set!
  (lambda (sid session-item)
    (with-output-to-file (make-pathname (session-storage) sid)
      (lambda ()
        (pp (session-item->list session-item))))))
 
 (session-storage-ref
  (lambda (sid)
    (let ((data (with-input-from-file
                    (make-pathname (session-storage) sid)
                  read)))
      (list->session-item data))))
 
 (session-storage-delete!
  (lambda (sid)
    (delete-file* (make-pathname (session-storage) sid))))
 
 
 ;; awful pages
 (define-session-page (main-page-path)
   (lambda ()
     (with-request-variables (foo)
       ($session-set! 'foo foo)
       (string-append "foo set to " (->string foo)))))
 
 (define-session-page "/foo"
   (lambda ()
     (->string ($session 'foo))))

Usage example

Web server

(use spiffy web-scheme-handler http-session html-tags html-utils spiffy-request-vars)
(file-extension-handlers `(("ws" . ,web-scheme-handler)))
(start-server)

index.ws

(define (page:next sid)
  (html-page
   (string-append
    (<h1> (let ((n (add1 (session-ref sid 'n 0))))
            (session-set! sid 'n n)
            (number->string n)))
    (<a> href: (string-append "?sid=" sid) "Next"))))

(let ((sid ((request-vars) 'sid)))
  (if sid
      (if (session-valid? sid)
          (begin (session-refresh! sid)
                 (page:next sid))
          (html-page "Invalid session."))
      (let ((sid (session-create)))
        (page:next sid))))

License

 Copyright (c) 2010-2018, Mario Domenech Goulart
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
 3. The name of the authors may not be used to endorse or promote products
    derived from this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Version History

Version 2.10

CHICKEN 5 support

Version 2.9

Trigger the backend's session-storage-set! when a session item binding is deleted with session-del!, to match the behaviour of session-set! (by Evan Hanson)

Version 2.8

Bug fix for session-del! (by Evan Hanson)

Version 2.7

Backend storage API
Removed session-table, make-session-table, session-delete-binding! and session-delete! (deprecated a long time ago)

Version 2.6

Raise specific invalid-session error instead of a general error when attempting to access sessions using invalid sid (as suggested by Moritz Heidkamp)
Compile with -O3 instead of -O2

Version 2.5

Replaced sha1 by simple-sha1 as dependency.

Version 2.4

Bug fix for session-id-generator for long duration processes. The current-milliseconds value overflows the exact numbers limit for long lived process, so inexact->exact failed. Updating to this version is highly recommended.

Version 2.3

Dropped requirement for regex

Version 2.2

Handle the inexactness of current-milliseconds on chickens >= 4.6.0

Version 2.1

Added the session-set-finalizer! procedure (by Moritz Heidkamp)

Version 2.0

Some major changes
make-session-table is now exported (it was make-table internally).
current-url and current-ip are gone
session-create doesn't use the url-pattern argument anymore (the session-table can be parameterized for separating web applications)
added match-ip-address? parameter. By default, http-session ignores the IP address of the client when checking whether the session is valid. If match-ip-address? is #t, it will take the IP address into account.
Deprecated procedures: session-delete-binding! and session-delete!
New procedures: session-del! (to substitute session-delete-binding!) and session-destroy! (to substitute session-delete!)

Version 1.2.3

Added parameters to export list again

Version 1.2.2

Ported to Chicken 4

Version 1.2

Added http-session:bindings, bug fix for http-session:set!.

Version 1.1

Bug fix

Version 1.0

Initial release

http-session

Introduction

Author

Repository

Requirements

API