The hunchentools Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The hunchentools Reference Manual

This is the hunchentools Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:50:56 2022 GMT+0.

Table of Contents


1 Introduction

hunchentools

Hunchentools is a utility library for the Hunchentoot web server. Hunchentools provides functions for creating dispatchers, aborting handlers, escaping strings, hardening session cookies, managing session users, and managing session CSRF tokens.

Hunchentools depends on Hunchentoot, Alexandria, CL-PPCRE, and Ironclad. Hunchentools is being developed with SBCL, CCL, and LispWorks on OS X. Hunchentools is being deployed with SBCL on Linux/AMD64.

Installation

(ql:quickload "hunchentools")

Example

(hunchentoot:define-easy-handler (handle-login :uri "/login")
    ((username :parameter-type 'parse-username :request-type :post)
     (password :parameter-type 'parse-password :request-type :post))
  (hunchentoot:start-session)
  (hunchentools:harden-session-cookie)
  (setf (hunchentoot:content-type*) "text/html; charset=utf-8")
  (case (hunchentoot:request-method*)
    (:get
     (with-output-to-string (stream)
       (render-login-page "Login" stream)))
    (:post
     (if (or (null username)
             (null password)
             (string/= username "root")
             (string/= password "foobar"))
         (with-output-to-string (stream)
           (render-login-page "Bad username and/or password." stream))
         (progn
           (setf (hunchentools:session-user) username)
           (hunchentoot:redirect "/guess"))))))

(defun render-guess-page (csrf-token message
                          &optional (stream *standard-output*))
  (with-html-page (stream)
    (:div
     (:p (cl-who:esc message))
     (:form :action "/guess" :method "post"
            (:input :type "hidden" :name "csrf-token"
                    :value (hunchentools:escape-string-custom
                            csrf-token
                            (constantly t)
                            #'write-char))
            (:input :type "text" :name "guess" :value "")
            (:input :type "submit" :value "Scan"))
     (:p (:a :href "/logout" "Logout")))))

(hunchentoot:define-easy-handler (handle-guess :uri "/guess")
    ((guess :parameter-type 'parse-guess :request-type :post))
  (hunchentoot:start-session)
  (hunchentools:harden-session-cookie)
  (setf (hunchentoot:content-type*) "text/html; charset=utf-8")
  (hunchentools:require-session-user "/logout")
  (case (hunchentoot:request-method*)
    (:get
     (with-output-to-string (stream)
       (render-guess-page (hunchentools:session-csrf-token)
                          "Guess a number."
                          stream)))
    (:post
     (hunchentools:require-session-csrf-token :post)
     (when (null guess)
       (hunchentools:abort-with-bad-request))
     (if (= guess 42)
         (hunchentoot:redirect "/guess")
         (with-output-to-string (stream)
           (render-guess-page (hunchentools:session-csrf-token)
                              "Nope. Guess again."
                              stream))))))

(defun handle-logout ()
  (hunchentoot:start-session)
  (hunchentools:harden-session-cookie)
  (hunchentools:delete-session-user)
  (hunchentoot:redirect "/login"))

(eval-when (:compile-toplevel :load-toplevel :execute)
  (push (hunchentools:create-uri-methods-dispatcher
          "/logout"
          :get
          'handle-logout)
        hunchentoot:*dispatch-table*))

License

Hunchentools is distributed under the MIT license. See LICENSE.


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 hunchentools

Hunchentoot utility library

Author

Michael J. Forster <mike@forsterfamily.ca>

License

MIT

Version

1.0.0

Dependencies
  • hunchentoot (system).
  • alexandria (system).
  • cl-ppcre (system).
  • ironclad (system).
Source

hunchentools.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 hunchentools/hunchentools.asd

Source

hunchentools.asd.

Parent Component

hunchentools (system).

ASDF Systems

hunchentools.


3.1.2 hunchentools/package.lisp

Source

hunchentools.asd.

Parent Component

hunchentools (system).

Packages

hunchentools.


3.1.3 hunchentools/abort.lisp

Dependency

package.lisp (file).

Source

hunchentools.asd.

Parent Component

hunchentools (system).

Public Interface

3.1.4 hunchentools/dispatcher.lisp

Dependency

package.lisp (file).

Source

hunchentools.asd.

Parent Component

hunchentools (system).

Public Interface

3.1.5 hunchentools/string-escaping.lisp

Dependency

package.lisp (file).

Source

hunchentools.asd.

Parent Component

hunchentools (system).

Public Interface

3.1.6 hunchentools/session-cookie.lisp

Dependency

package.lisp (file).

Source

hunchentools.asd.

Parent Component

hunchentools (system).

Public Interface

harden-session-cookie (function).


3.1.7 hunchentools/session-user.lisp

Dependency

package.lisp (file).

Source

hunchentools.asd.

Parent Component

hunchentools (system).

Public Interface

3.1.8 hunchentools/session-csrf-token.lisp

Dependency

package.lisp (file).

Source

hunchentools.asd.

Parent Component

hunchentools (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 hunchentools

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: abort-with-bad-request ()

Abort handling of the request as if the handler had returned HUNCHENTOOT:+HTTP-BAD-REQUEST+.

Package

hunchentools.

Source

abort.lisp.

Function: abort-with-forbidden ()

Abort handling of the request as if the handler had returned HUNCHENTOOT:+HTTP-FORBIDDEN+.

Package

hunchentools.

Source

abort.lisp.

Function: abort-with-internal-server-error ()

Abort handling of the request as if the handler had returned HUNCHENTOOT:+HTTP-INTERNAL-SERVER-ERROR+.

Package

hunchentools.

Source

abort.lisp.

Function: abort-with-not-found ()

Abort handling of the request as if the handler had returned HUNCHENTOOT:+HTTP-NOT-FOUND+.

Package

hunchentools.

Source

abort.lisp.

Function: abort-with-return-code (return-code)

Abort handling of the request as if the handler had returned RETURN-CODE.

Package

hunchentools.

Source

abort.lisp.

Function: create-prefix-methods-dispatcher (prefix methods handler)

Return a request dispatch function which will dispatch to the function denoted by HANDLER if the file name of the current request starts with the string PREFIX and the method of the current request is a member of the list denoted by METHODS. The dispatch function will return NIL if there is no match.

Package

hunchentools.

Source

dispatcher.lisp.

Function: create-regex-methods-dispatcher (regex methods handler)

Return a request dispatch function which will dispatch to the function denoted by HANDLER if the file name of the current request matches the CL-PPCRE regular expression REGEX and the method of the current request is a member of the list denoted by METHODS. The dispatch function will return NIL if there is no match.

Package

hunchentools.

Source

dispatcher.lisp.

Function: create-uri-methods-dispatcher (uri methods handler)

Return a request dispatch function which will dispatch to the function denoted by HANDLER if the file name of the current request matches the string URI and the method of the current request is a member of the list denoted by METHODS. The dispatch function will return NIL if there is no match.

Package

hunchentools.

Source

dispatcher.lisp.

Function: delete-session-csrf-token ()

Remove the CSRF token, if any, from the session.

Package

hunchentools.

Source

session-csrf-token.lisp.

Function: delete-session-user ()

Remove the user, if any, from the session.

Package

hunchentools.

Source

session-user.lisp.

Function: escape-string-custom (string test escape-write-function)

Given a string STRING, return a new string, encoding with the
function denoted by ESCAPE-WRITE-FUNCTION every character for which the function denoted by TEST returns true.

Use this in place of CL-WHO:ESCAPE-STRING where custom encoding is required.

Package

hunchentools.

Source

string-escaping.lisp.

Function: escape-string-js (string)

Given a string STRING, return a new string, escaping all ASCII values less than 256 with the xHH format and those greater than or equal to 256 with the uHHHH format.

Package

hunchentools.

Source

string-escaping.lisp.

Function: harden-session-cookie (&key securep name)

Set the HTTP-ONLY and secure flags of the outgoing cookie named NAME and set it to expire with the session. NAME defaults to "hunchentoot-session".

Package

hunchentools.

Source

session-cookie.lisp.

Function: require-session-csrf-token (request-type &optional name)

Abort handling the request, log a warning message, and remove any session CSRF token if the request of type denoted by REQUEST-TYPE does not provide a value for the parameter NAME, if the provided value does not match the session CSRF token, or if the session CSRF token has not been set. Othewise, do nothing. REQUEST-TYPE can be one
of :GET, :POST, :PUT, or :DELETE. NAME defaults to "csrf-token".

Package

hunchentools.

Source

session-csrf-token.lisp.

Function: require-session-user (&rest redirect-args)

Log a warning message and redirect if no user is set for the session. Otherwise, do nothing. REDIRECT-ARGS are used as keyword arguments to HUNCHENTOOT:REDIRECT.

Package

hunchentools.

Source

session-user.lisp.

Function: session-csrf-token ()

Return the current CSRF token set for the session or a new token if one has not been set. If the session does not exist, return NIL.

Package

hunchentools.

Source

session-csrf-token.lisp.

Function: session-user ()

Return the user set for the session. Return NIL if the session does not exist or if no user has been set.

SETF of SESSION-USER can be used to set a new user for the session. If the session does not exist then one is created. Signal a correctable error of type TYPE-ERROR if SETF of SESSION-USER is called with a NIL value for user.

Package

hunchentools.

Source

session-user.lisp.

Function: (setf session-user) ()
Package

hunchentools.

Source

session-user.lisp.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *csrf-secret*
Package

hunchentools.

Source

session-csrf-token.lisp.

Special Variable: *the-random-state*
Package

hunchentools.

Source

session-csrf-token.lisp.


Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary functions

Function: next-csrf-token ()
Package

hunchentools.

Source

session-csrf-token.lisp.

Function: random-string (&optional n base)

Return a random number (as a string) with base BASE and N digits.

Package

hunchentools.

Source

session-csrf-token.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   D   E   F   H   N   R   S  
Index Entry  Section

(
(setf session-user): Public ordinary functions

A
abort-with-bad-request: Public ordinary functions
abort-with-forbidden: Public ordinary functions
abort-with-internal-server-error: Public ordinary functions
abort-with-not-found: Public ordinary functions
abort-with-return-code: Public ordinary functions

C
create-prefix-methods-dispatcher: Public ordinary functions
create-regex-methods-dispatcher: Public ordinary functions
create-uri-methods-dispatcher: Public ordinary functions

D
delete-session-csrf-token: Public ordinary functions
delete-session-user: Public ordinary functions

E
escape-string-custom: Public ordinary functions
escape-string-js: Public ordinary functions

F
Function, (setf session-user): Public ordinary functions
Function, abort-with-bad-request: Public ordinary functions
Function, abort-with-forbidden: Public ordinary functions
Function, abort-with-internal-server-error: Public ordinary functions
Function, abort-with-not-found: Public ordinary functions
Function, abort-with-return-code: Public ordinary functions
Function, create-prefix-methods-dispatcher: Public ordinary functions
Function, create-regex-methods-dispatcher: Public ordinary functions
Function, create-uri-methods-dispatcher: Public ordinary functions
Function, delete-session-csrf-token: Public ordinary functions
Function, delete-session-user: Public ordinary functions
Function, escape-string-custom: Public ordinary functions
Function, escape-string-js: Public ordinary functions
Function, harden-session-cookie: Public ordinary functions
Function, next-csrf-token: Private ordinary functions
Function, random-string: Private ordinary functions
Function, require-session-csrf-token: Public ordinary functions
Function, require-session-user: Public ordinary functions
Function, session-csrf-token: Public ordinary functions
Function, session-user: Public ordinary functions

H
harden-session-cookie: Public ordinary functions

N
next-csrf-token: Private ordinary functions

R
random-string: Private ordinary functions
require-session-csrf-token: Public ordinary functions
require-session-user: Public ordinary functions

S
session-csrf-token: Public ordinary functions
session-user: Public ordinary functions

Jump to:   (  
A   C   D   E   F   H   N   R   S