clack

API Reference

clack

Web application environment for Common Lisp

CLACK

# 
Clack main package just for convenience.


## SYNOPSIS

    (clackup (lambda (env)
               (declare (ignore env))
               '(200 nil ("Hello, Clack!")))
             :port 5000
             :debug t)

    (clackup #p"app.lisp"
             :server :fcgi
             :port 8080
             :debug nil)

## DESCRIPTION

Contrary to your expectations, this package is not so significant. Just exporting symbols imported from Clack.Component and Clack.Middleware.

This package is mostly just here to avoid confusion, especially for beginners. Most peaple expect there to be a package that has the same as asdf:system.

Worthy of special mention is `clackup'. It provides an easy way to run Clack Applications.

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Component
* Clack.Middleware

  • Variable *CLACK-OUTPUT* '*STANDARD-OUTPUT*
    Standard output for a Clack running process.
  • Variable *CLACK-ERROR-OUTPUT* '*ERROR-OUTPUT*
    Standard error output for a Clack running process.
  • Function CLACKUP app &rest args &key (server hunchentoot) (port 5000) (debug t) watch (use-thread t) (use-cl-debugger t) (use-default-middlewares t) &allow-other-keys
    Easy way to run Clack Application.
    You can specify backend server with passing `:server'. The default is `:hunchentoot'.
    
    Example:
      (clackup (lambda (env)
                 (declare (ignore env))
                 '(200 nil ("ok")))
               :port 5000
               :debug t)
    
      (clackup #p"app.lisp"
               :server :fcgi
               :port 8080
               :debug nil)
    

CLACK.BUILDER

# 
Clack.Builder - Clack utility to build up from some Middleware and Application into one function.


## SYNOPSIS

    (builder
     <clack-middleware-accesslog>
     (<clack-middleware-static>
      :path "/public/"
      :root #p"/static-files/")
     app)

## DESCRIPTION

Clack.Builder allows you to write middlewares inline. It builds up with calling `wrap' of middlewares sequencially and returns a function also as an Application.

The following example is:

    (builder
     <clack-middleware-accesslog>
     (<clack-middleware-static>
      :path "/public/"
      :root #p"/static-files/")
     app)

same as below one.

    (wrap (make-instance '<clack-middleware-accesslog>)
          (wrap (make-instance '<clack-middleware-static>
                   :path "/public/"
                   :root #p"/static-files/")
                app))

`builder-lazy' is almost same as `builder', but it builds up every time when the Application calls.

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Middleware

  • Variable *BUILDER-LAZY-P* NIL
    Flag whether using lazy building.
    If t, build up for each HTTP request.
    This is useful in development phase.
  • Macro BUILDER &rest app-or-middleware
    Some Middleware and Applications reduce into one function.
  • Macro BUILDER-LAZY &rest app-or-middleware
    Some Middleware and Applications reduce into one function. This evals given Components in each HTTP request time.

CLACK.REQUEST-RESPONSE

CLACK.REQUEST

# 
Clack.Request - Portable HTTP Request object for Clack Request.


## SYNOPSIS

    (defun app (env)
      (let ((req (make-request env)))
      `(200
        (:content-type "text/plain")
        ("Hello, " (query-parameter req "name")))))

## DESCRIPTION

Clack.Request provides a consistent API for request objects.

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

  • Class <REQUEST>
    Portable HTTP Request object for Clack Request.
    ENV Reader: ENV
    Raw env
    REQUEST-METHOD Reader: REQUEST-METHOD
    The HTTP request method.
    This must be one of :GET, :HEAD, :OPTIONS, :PUT, :POST, or :DELETE.
    SCRIPT-NAME Reader: SCRIPT-NAME
    The initial portion of the request URL's path, corresponding to the application.
    This may be an empty string if the application corresponds to the server's root URI. If this key is not empty, it must start with a forward slash (/).
    PATH-INFO Reader: PATH-INFO
    The remainder of the request URL's path.
    This may be an empty string if the request URL targets the application root and does not have a trailing slash.
    SERVER-NAME Reader: SERVER-NAME
    The resolved server name, or the server IP address.
    SERVER-PORT Reader: SERVER-PORT
    The port on which the request is being handled.
    SERVER-PROTOCOL Reader: SERVER-PROTOCOL
    The version of the protocol the client used to send the request.
    Typically this will be something like :HTTP/1.0 or :HTTP/1.1.
    REQUEST-URI Reader: REQUEST-URI
    The request URI. Must start with '/'.
    URI-SCHEME Reader: URI-SCHEME
    REMOTE-ADDR Reader: REMOTE-ADDR
    REMOTE-PORT Reader: REMOTE-PORT
    QUERY-STRING Reader: QUERY-STRING
    The portion of the request URL that follows the '?', if any.
    RAW-BODY Reader: RAW-BODY
    CONTENT-LENGTH Reader: CONTENT-LENGTH
    CONTENT-TYPE Reader: CONTENT-TYPE
    CLACK-HANDLER Reader: CLACK-HANDLER
    HEADERS
    HTTP-COOKIE
    BODY-PARAMETERS
    QUERY-PARAMETERS
  • Method REFERER (request <request>)
  • Method REFERER (request <request>)
  • Method USER-AGENT (request <request>)
  • Method USER-AGENT (request <request>)
  • Method HEADERS (request <request>) &optional name
  • Method INITIALIZE-INSTANCE (this <request>) &rest env
  • Function SHARED-RAW-BODY env
    Returns a shared raw-body, or returns nil if raw-body is
    empty. This function modifies REQ to share raw-body among the
    instances of <request>.
  • Function MAKE-REQUEST env
    A synonym for (make-instance '<request> ...).
    Make a <request> instance from environment plist. Raw-body of the instance
    will be shared, meaning making an instance of <request> doesn't effect
    on an original raw-body.
  • Method SECUREP (req <request>)
  • Method SECUREP (req <request>)
  • Method COOKIES (req <request>) &optional name
  • Method COOKIES (req <request>) &optional name
  • Method BODY-PARAMETER (req <request>) &optional name
  • Method BODY-PARAMETER (req <request>) &optional name
  • Method QUERY-PARAMETER (req <request>) &optional name
  • Method QUERY-PARAMETER (req <request>) &optional name
  • Method PARAMETER (req <request>) &optional name
  • Method PARAMETER (req <request>) &optional name

CLACK.RESPONSE

# 
Clack.Response - Portable HTTP Response object for Clack response.


## SYNOPSIS

    (defvar res nil)
    
    (setf res (make-response 200))
    (setf res (make-response 200 '(:content-type "text/html")))
    (setf res (make-response 200 '(:content-type "text/html") '("aiueo")))
    
    ;; Access each fields
    (status res)
    ;;=> 200
    (headers res)
    ;;=> (:content-type "text/html")
    (headers res :content-type)
    ;;=> "text/html"
    (body res)
    ;;=> ("aiueo")
    
    ;; Set to each fields
    (setf (status res) 304)
    (setf (headers res :content-type) "text/plain")
    (setf (body res) '("moved"))
    (setf (body res) "moved") ;; string also allowed

## DESCRIPTION

Clack.Response allows you a way to create Clack response.

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

  • Class <RESPONSE>
    Portable HTTP Response object for Clack response.
    STATUS Accessor: STATUS
    HEADERS
    BODY Reader: BODY
    SET-COOKIES
  • Method INITIALIZE-INSTANCE (res <response>) &key
  • Function MAKE-RESPONSE &optional status headers body
    A synonym for (make-instance '<response> ...).
    Create a <response> instance.
  • Method HEADERS (res <response>) &optional name
  • Method HEADERS (res <response>) &optional name
  • Method PUSH-HEADER (res <response>) name value
  • Method PUSH-HEADER (res <response>) name value
  • Method SET-COOKIES (res <response>) &optional name
  • Method SET-COOKIES (res <response>) &optional name
  • Method REDIRECT (res <response>) url &optional (status 302)
  • Method REDIRECT (res <response>) url &optional (status 302)
  • Method FINALIZE (res <response>)
  • Method FINALIZE (res <response>)

CLACK.COMPONENT

# 
Clack.Component - Base Class for Clack Component.


## SYNOPSIS

    (in-package :cl-user)
    (defpackage clack.app.example
      (:use :cl :clack)
      (:export :<clack-app-example>))
    (in-package :clack.app.example)
    
    (defclass <clack-app-example> (<component>) ())
    (defmethod call ((this <clack-app-example>) env)
      (declare (ignore this env))
      `(200 (:content-type "text/plain") ("Hello, World!")))

## DESCRIPTION

Clack.Component is the base class shared between Clack.Middleware and Clack Application.

You must implement `clack.component:call' as a method which is called when an HTTP request comes in and returns a response.

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Middleware

  • Type COMPONENT-DESIGNATOR NAME NIL PACKAGE-NAME COMMON-LISP EXTERNALP T
  • Class <COMPONENT>
    Base Class for Clack Component shared between <middleware> and Clack Application.
  • Method CALL (app function) env
    Functions should be called like Component.
  • Method MAKE-APP (comp <component>)
  • Method MAKE-APP (comp <component>)

CLACK.MIDDLEWARE

# 
Clack.Middleware - Base Class for Clack Middleware.


## SYNOPSIS

    (in-package :cl-user)
    (defpackage clack.middleware.example
      (:use :cl :clack)
      (:export :<clack-middleware-example>))
    (in-package :clack.middleware.example)
    
    (defclass <clack-middleware-example> (<middleware>) ())
    (defmethod call ((this <clack-middleware-example>) env)
      ;; pre-processing `env'
      (let ((res (call-next this env)))
        ;; post-processing `res'
        res))

## DESCRIPTION

Clack.Middleware is the base class to write Clack Middleware.

All you have to do is to inherit from `<middleware>' and then implement the callback `call' method to do the actual work.

Middleware is similar to ':around' method of CLOS. You can delegate some processes to Application (or next Middleware) to call `call-next'.

## AUTHOR

  Author: Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Component

  • Class <MIDDLEWARE> inherits (<COMPONENT> )
    Class for Clack Middleware.
    APP Reader: APP
  • Method CALL-NEXT (this <middleware>) env
  • Method CALL-NEXT (this <middleware>) env
  • Method WRAP (this function) app-or-middleware
  • Method WRAP (this function) app-or-middleware
  • Method WRAP (this <middleware>) app-or-middleware
  • Method WRAP (this <middleware>) app-or-middleware

CLACK.HANDLER

# 
Clack.Handler - Class for Handler


## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

  • Class <HANDLER>
    SERVER-NAME Accessor: SERVER-NAME
    ACCEPTOR Accessor: ACCEPTOR
  • Method STOP (this <handler>)
  • Method STOP (this <handler>)

CLACK.HTTP-STATUS

  • Variable *HTTP-STATUS* (MAKE-HASH-TABLE :TEST #'EQL)
  • Function HTTP-STATUS-REASON code

CLACK.APP.FILE

# 
Clack.App.File - Serve static files.


## SYNOPSIS

    ;; THIS IS JUST FOR EXAMPLE
    (clackup (<clack-app-file>
              :root #p"./static-files/"))
    
    ;; Then access 'http://localhost/jellyfish.jpg' through into local './static-files/jellyfish.jpg'.
    ;; If the file isn't found, 404 will be returned.

## DESCRIPTION

Clack.App.File serves static files in local directory. This Application should be used in other Middleware or Application (ex. Clack.Middleware.Static).

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Middleware.Static

  • Class <CLACK-APP-FILE> inherits (<COMPONENT> )
    Clack Application to serve static files.
    FILE Accessor: FILE
    ROOT Accessor: ROOT
    ENCODING Accessor: ENCODING
  • Method CALL (this <clack-app-file>) env
  • Method SHOULD-HANDLE (this <clack-app-file>) file
  • Method SHOULD-HANDLE (this <clack-app-file>) file
  • Method LOCATE-FILE (this <clack-app-file>) path root
  • Method LOCATE-FILE (this <clack-app-file>) path root
  • Method SERVE-PATH (this <clack-app-file>) env file encoding
  • Method SERVE-PATH (this <clack-app-file>) env file encoding

CLACK.APP.DIRECTORY

# 
Clack.App.Directory - Server static files from document root with directory index.


## SYNOPSIS

    ;; mount /var/www/ to http://localhost:5000/
    (clackup
     (make-instance '<clack-app-directory>
        :root #p"/var/www/")
     :port 5000)
    
    ;; same as above
    (clack.app.directory:start-server
       :root #p"/var/www/"
       :port 5000)

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.App.File

  • Class <CLACK-APP-DIRECTORY> inherits (<CLACK-APP-FILE> )
  • Function START-SERVER &key (root (truename ".")) (port 5000)
  • Method SHOULD-HANDLE (this <clack-app-directory>) file
  • Method SERVE-PATH (this <clack-app-directory>) env file encoding

CLACK.APP.URLMAP

# 
Clack.App.URLMap - Map multiple apps in different paths.


## SYNOPSIS

    (defparameter *urlmap* (make-instance '<clack-app-urlmap>))
    (mount *urlmap* "/pc/" #'app-for-pc)
    (mount *urlmap* "/api/" #'app-for-api)
    (call *urlmap* env)
    
    ;; Useful synonym.
    (builder-urlmap
      ("/pc/" #'app-for-pc)
      ("/api/" #'app-for-api))

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Builder

  • Class <CLACK-APP-URLMAP> inherits (<COMPONENT> )
    Class to map multiple apps in different paths.
    %MAPPING
  • Method MOUNT (this <clack-app-urlmap>) location app
  • Method MOUNT (this <clack-app-urlmap>) location app
  • Method CALL (this <clack-app-urlmap>) env
  • Macro BUILDER-URLMAP &rest apps
    Useful syntax sugar for building applications.

CLACK.FILE-WATCHER

  • Function WATCH-SYSTEMS identifier systems &key (use-thread *supports-threads-p*)
  • Function STOP-WATCHING identifier

CLACK.MIDDLEWARE.STATIC

# 
Clack.Middleware.Static - Middleware to serve static files.


## SYNOPSIS

    (run
      (builder
       (<clack-middleware-static>
        :path "/public/"
        :root #p"/static-files/")
       app))

## DESCRIPTION

This is a Clack Middleware component for serving static files.

## Slots

* path (Required, String or Function)

<code>path</code> specifies the prefix of URL or a callback to match with requests to serve static files for.

Notice. Don't forget to add slush "/" to the end.

* root (Optional, Pathname)

<code>root</code> specifies the root directory to serve static files from.

## EXAMPLE

The following example code would serve */public/foo.jpg* from */static-files/foo.jpg*.

    (run
      (builder
       (<clack-middleware-static>
        :path "/public/"
        :root #p"/static-files/")
       app))

You can set any function that returns a mapped filename as <code>:path</code>. The above example can be rewritten as following code.

    (run
      (builder
       (<clack-middleware-static>
        :path (lambda (path)
                (when (ppcre:scan "^/public/" path)
                  (subseq path 7)))
        :root #p"/static-files/")
       app))

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.App.File

  • Class <CLACK-MIDDLEWARE-STATIC> inherits (<MIDDLEWARE> )
    Clack Middleware to intercept requests for static files.
    PATH Accessor: STATIC-PATH
    ROOT Accessor: STATIC-ROOT
  • Method CALL (this <clack-middleware-static>) env

CLACK.MIDDLEWARE.CONDITIONAL

# 
Clack.Middleware.Conditional - Conditional wrapper for Clack middleware.


## SYNOPSIS

    (builder
     (:condition (lambda (env)
                   (scan "WebKit" (getf env :http-user-agent)))
      :builder '<clack-middleware-something>)
     app)

    (builder
      (<clack-middleware-conditional>
       :condition (lambda (env)
                    (scan "WebKit" (getf env :http-user-agent)))
       :builder '(<clack-middleware-static>
                  :path "/public/"
                  :root #p"/static-files/"))
      app)

    (wrap
     (make-instance '<clack-middleware-conditional>
        :condition (lambda (env)
                     (scan "WebKit" (getf env :http-user-agent)))
        :builder '(<clack-middleware-something>
                   :path "/public/"
                   :root #p"/static-files/"))
     app)

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

  • Class <CLACK-MIDDLEWARE-CONDITIONAL> inherits (<MIDDLEWARE> )
    CONDITION
    BUILDER
    MIDDLEWARE
  • Method INITIALIZE-INSTANCE (this <clack-middleware-conditional>) &key
  • Method WRAP (this <clack-middleware-conditional>) app
  • Method CALL (this <clack-middleware-conditional>) env

CLACK.SESSION.STATE

# 
Clack.Session.State - Basic parameter-based session state.


## DESCRIPTION

Clack.Session.State maintains session state by passing the session through the request params. Usually you wouldn't use this because this cannot keep session through each HTTP request. This is just for creating new session state manager.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Middleware.Session

  • Class <CLACK-SESSION-STATE>
    SESSION-KEY Accessor: SESSION-KEY
    SID-GENERATOR Accessor: SID-GENERATOR
    SID-VALIDATOR Accessor: SID-VALIDATOR
  • Method EXPIRE (this <clack-session-state>) id res &optional options
  • Method EXPIRE (this <clack-session-state>) id res &optional options
  • Method SESSION-ID (this <clack-session-state>) env
  • Method SESSION-ID (this <clack-session-state>) env
  • Method VALID-SID-P (this <clack-session-state>) id
  • Method VALID-SID-P (this <clack-session-state>) id
  • Method EXTRACT-ID (this <clack-session-state>) env
  • Method EXTRACT-ID (this <clack-session-state>) env
  • Method GENERATE-ID (this <clack-session-state>) &rest args
  • Method GENERATE-ID (this <clack-session-state>) &rest args
  • Method FINALIZE (this <clack-session-state>) id res options
  • Method FINALIZE (this <clack-session-state>) id res options

CLACK.SESSION.STATE.COOKIE

# 
Clack.Session.State.Cookie - Basic cookie-based session state.


## DESCRIPTION

Clack.Session.State.Cookie will maintain session state using browser cookies.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Session.State
* Clack.Middleware.Session

  • Class <CLACK-SESSION-STATE-COOKIE> inherits (<CLACK-SESSION-STATE> )
    PATH Accessor: PATH
    DOMAIN Accessor: DOMAIN
    EXPIRES Accessor: EXPIRES
    SECURE Accessor: SECURE
    HTTPONLY Accessor: HTTPONLY
  • Method EXPIRE (this <clack-session-state-cookie>) id res &optional options
  • Method SESSION-ID (this <clack-session-state-cookie>) env
  • Method FINALIZE (this <clack-session-state-cookie>) id res options

CLACK.SESSION.STORE

# 
Clack.Session.Store - Basic in-memory session store.


## DESCRIPTION

Clack.Session.Store is a basic in-memory session data store. This is volatile storage and not recommended for multiprocessing environments. However, this is very useful for development and testing.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Middleware.Session

  • Class <CLACK-SESSION-STORE>
    STASH Accessor: STASH
  • Method FETCH (this <clack-session-store>) sid
  • Method FETCH (this <clack-session-store>) sid
  • Method STORE-SESSION (this <clack-session-store>) sid session
  • Method STORE-SESSION (this <clack-session-store>) sid session
  • Method REMOVE-SESSION (this <clack-session-store>) sid
  • Method REMOVE-SESSION (this <clack-session-store>) sid

CLACK.MIDDLEWARE.SESSION

# 
Clack.Middleware.Session - Middleware for session management.


## SYNOPSIS

    (clackup (builder
              (<clack-middleware-session>
               :state (make-instance '<clack-session-state-cookie>))
              (lambda (env)
                (sunless (gethash :counter (getf env :clack.session))
                  (setf it 0))
                `(200
                  (:content-type "text/plain")
                  (,(format nil "Hello, you've been here for ~Ath times!"
                            (incf (gethash :counter (getf env :clack.session)))))))))

## DESCRIPTION

Clack.Middleware.Session provides a session interface. By default this will use cookies to keep session state and store data in memory.

You can change this behavior by inheriting `<clack-session-state>' and `<clack-session-store>'.

Note the `:clack.session' is a hash table, not a plist, because plists cannot keep state between functions.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Session.State
* Clack.Session.Store

  • Class <CLACK-MIDDLEWARE-SESSION> inherits (<MIDDLEWARE> )
    Clack Middleware for session management.
    STATE Accessor: STATE
    STORE Accessor: STORE
  • Method CALL (this <clack-middleware-session>) env

CLACK.MIDDLEWARE.SESSION.COOKIE

# 
Clack.Middleware.Session.Cookie - Session middleware that saves session data in the cookie.


## SYNOPSIS

    (clackup (builder
              (<clack-middleware-session-cookie>
               :secret "secret key here")
              app)

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Middleware.Session
* Clack.Session.State

  • Class <CLACK-MIDDLEWARE-SESSION-COOKIE> inherits (<CLACK-MIDDLEWARE-SESSION> )
    SECRET Accessor: SECRET
    Server side secret to sign the session data using HMAC SHA1.

CLACK.MIDDLEWARE.ACCESSLOG

# 
Clack.Middleware.Accesslog


## SYNOPSIS

    (clackup (builder
              <clack-middleware-accesslog>
              (lambda (env)
                '(200 () ("Hi.")))))

## DESCRIPTION

Clack.Middleware.Accesslog provides access logging facility.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

  • Variable *TIME-FORMAT* '((:DAY 2) #\/ :SHORT-MONTH #\/ (:YEAR 4) #\: (:HOUR 2) #\: (:MIN 2) #\: (:SEC 2) #\ :GMT-OFFSET)
  • Class <CLACK-MIDDLEWARE-ACCESSLOG> inherits (<MIDDLEWARE> )
    LOGGER
    FORMATTER
  • Method CALL (mw <clack-middleware-accesslog>) env

CLACK.MIDDLEWARE.LET

# 
Clack.Middleware.Let


## SYNOPSIS

    (clackup (builder
              (<clack-middleware-let> :bindings `((*standard-output* ,*clack-output*)))
              (lambda (env)
                (format t "You've got an access!~%")
                '(200 nil ("Hi!")))))

## DESCRIPTION

Clack.Middleware.Let allows you to bind variables within each requests like `cl:let'.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

  • Class <CLACK-MIDDLEWARE-LET> inherits (<MIDDLEWARE> )
    BINDINGS
  • Method CALL (this <clack-middleware-let>) env

CLACK.MIDDLEWARE.BACKTRACE

# 
Clack.Middleware.Backtrace


## SYNOPSIS

    (clackup (builder
              (<clack-middleware-backtrace>
               :output #P"/var/log/app/myapp_error.log"
               :result-on-error '(500 () ("Internal Server Error")))
              (lambda (env)
                (error "Fatal error! Help!!")
                '(200 () ("ok? (probably not)")))))

## DESCRIPTION

Clack.Middleware.Backtrace catches all errors and outputs their backtraces to `*error-output*`. You can specify what to return in `:result-on-error` slot. The default behaviour is rethrowing the signal.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

  • Class <CLACK-MIDDLEWARE-BACKTRACE> inherits (<MIDDLEWARE> )
    OUTPUT Accessor: OUTPUT
    RESULT-ON-ERROR Accessor: RESULT-ON-ERROR
  • Method CALL (this <clack-middleware-backtrace>) env

CLACK.UTIL.DOC

# 
Clack.Util.Doc - For writing Clack documentations.


## SYNOPSIS

    ;; Clear documentation of `*package*'.
    (doc:start)
    
    (doc:NAME "
    Clack - Web Application Environment for Common Lisp
    ")
    
    (doc:DESCRIPTION "
    Clack is a Web Application Environment for Common Lisp inspired by Python's WSGI and Ruby's Rack. Your awesome framework should base on this.
    ")

    ;; I recommend to use with cl-annot (https://github.com/arielnetworks/cl-annot).
    ;; It allows you to write docs by annotation-style.
    (cl-annot:enable-annot-syntax)
    
    (doc:start)
    
    @doc:NAME "
    Clack - Web Application Environment for Common Lisp
    "

## DESCRIPTION

Clack.Util.Doc enables easy writing package documentations with Markdown.

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* [cl-annot](https://github.com/arielnetworks/cl-annot)

  • Variable *SECTION-PLIST* '(:SYNOPSIS "SYNOPSIS" :EXPLANATION "EXPLANATION" :DEPENDENCIES "DEPENDENCIES" :DESCRIPTION "DESCRIPTION" :EXAMPLE "EXAMPLE" :SEE "SEE ALSO" :AUTHOR "AUTHOR" :CONTRIBUTORS "CONTRIBUTORS" :COPYRIGHT "COPYRIGHT" :LICENSE "LICENSE")
  • Function START NAME NIL PACKAGE-NAME COMMON-LISP EXTERNALP T
    Clear the docstring of `*package*'.
    I recommend you to put `(doc:start)' before calling doc functions,
    because they append sections duplicately when the packaged is reloaded.
  • Function DOC header &optional (string "") (level 1)
    Set documentation to current package
  • Function SECTION header &optional (string "") (level 1)
  • Function NAME string
  • Function SYNOPSIS string
  • Function EXPLANATION string
  • Function DEPENDENCIES string
  • Function DESCRIPTION string
  • Function EXAMPLE string
  • Function SEE string
  • Function AUTHOR string
  • Function CONTRIBUTORS string
  • Function COPYRIGHT string
  • Function LICENSE string

CLACK.UTIL

# 
Clack.Util - Utilities for Clack core and middleware development.


## DESCRIPTION

Most of the time, Clack uses other utility libraries such as Alexandria, but I realized they were not sufficient for Clack.

See each description of these functions for the details.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

  • Macro GETF* place key
    Similar to `getf', but accepts a string, a keyword, or a symbol as KEY.
  • Macro REMF* place key
    Similar to `remf', but accepts a string, a keyword, or a symbol as KEY.
  • Function NAPPEND &rest list-of-list
    Similar to `nconc', but assures LIST-OF-LIST to be overwritten with the result.
  • Function MERGE-PLIST p1 p2
    Merges two plists into one plist.
    If there are same keys in the two plists, the one in P2 is adopted.
    
    Example:
      (merge-plist '(:apple 1 :grape 2) '(:banana 3 :apple 4))
      ;;=> (:GRAPE 2 :BANANA 3 :APPLE 4)
    
  • Function FIND-HANDLER server &key (force t)
    Returns a handler package. SERVER must be a symbol or a keyword without "Clack.Handler." prefix.
    
    Example:
      (find-handler :hunchentoot)
  • Function LOAD-HANDLER server
    Loads a handler system in run-time. SERVER must be a symbol or a keyword.
    
    Example:
      (load-handler :hunchentoot)
  • Function HMAC-SHA1-HEX-STRING string secret
  • Function GENERATE-RANDOM-ID NAME NIL PACKAGE-NAME COMMON-LISP EXTERNALP T
    Generates a random token.
  • Function HTML-ENCODE str
  • Function APPLY-MIDDLEWARE app mw-class-name mw-package &rest args
    Applys a middleware to the `app'. This function is for resolving symbol packages in run-time.

clack-handler-fcgi

Clack handler for FastCGI.

CLACK.HANDLER.FCGI

# 
Clack.Handler.Fcgi - Clack handler for FastCGI.


## SYNOPSIS

    ;; Start server
    (run (lambda (env)
           '(200 nil ("ok")))
         :port 9000)
    
    ;; Using clackup
    (clackup (lambda (env)
               '(200 nil ("ok")))
             :server :fcgi
             :port 9000)

## DESCRIPTION

Clack.Handler.Fcgi is a Clack handler to run any Clack application as a FastCGI application. This handler depends on the library "cl-fastcgi", so it only works on SBCL, CMUCL, GNU CLISP, Clozure CL, LispWorks and ECL.

Here's an example using Nginx.

    # nginx.conf
    worker_processes  1;
    
    events {
        worker_connections  1024;
    }
    
    http {
        server {
            listen       8080;
            server_name  localhost;
            location / {
                   include_fastcgi_params;
                   fastcgi_pass   127.0.0.1:9000;
            }
        }
    }

This configuration to opens port 8080 to web browsers, and listens for the Lisp process on port 9000.

Run Clack application by `clackup`.

    (clack:clackup (lambda (env) '(200 nil ("Hello, FastCGI!")))
      :server :fcgi
      :port 9000)

Now, you can access [http://localhost:8080/](http://localhost:8080/) and Clack should show you "Hello, FastCGI!".

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

  • Method INITIALIZE-INSTANCE (acceptor <fcgi-acceptor>) &rest args
  • Function RUN app &key (debug t) (port 9000) fd
    Start FastCGI server.
  • Function STOP acceptor

clack-handler-hunchentoot

Clack handler for Hunchentoot.

CLACK.HANDLER.HUNCHENTOOT

# 
Clack.Handler.Hunchentoot - Clack handler for Hunchentoot.


## SYNOPSIS

    (defpackage clack-sample
      (:use :cl
            :clack.handler.hunchentoot))
    (in-package :clack-sample)

    ;; Start Server
    (run (lambda (env)
           '(200 nil ("ok")))
         :port 5000)

## DESCRIPTION

Clack.Handler.Hunchentoot is a Clack handler for the Lisp web server Hunchentoot. This package exports `run' and `stop'.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

  • Function RUN app &key debug (port 5000) ssl ssl-key-file ssl-cert-file ssl-key-password max-thread-count max-accept-count (persistent-connections-p t)
    Start Hunchentoot server.
  • Function STOP acceptor
    Stop Hunchentoot server.
    If no acceptor is given, try to stop `*acceptor*' by default.

clack-handler-toot

Clack handler for Toot.

CLACK.HANDLER.TOOT

  • Function RUN app &key debug (port 5000) ssl ssl-key-file ssl-cert-file ssl-key-password
    Start Toot server.
  • Function STOP acceptor
    Stop Toot server.

clack-handler-wookie

Clack handler for Wookie.

CLACK.HANDLER.WOOKIE

  • Function RUN app &key debug (port 5000) ssl ssl-key-file ssl-cert-file ssl-key-password
  • Function STOP server

clack-middleware-auth-basic

Basic Authentication Middleware.

CLACK.MIDDLEWARE.AUTH.BASIC

# 
Clack.Middleware.Auth.Basic - Basic Authentication Middleware.


## SYNOPSIS

    (clackup
     (builder
      (<clack-middleware-auth-basic>
       :authenticator #'(lambda (user pass)
                          (and (string= user "hoge")
                               (string= pass "fuga"))))
      app))

## DESCRIPTION

Clack.Middleware.Auth.Basic allows to basic authenticate simply. All you have to do is pass a function to authenticate to `<clack-middleware-auth-basic>`, `:authenticator`.

    (make-instance '<clack-middleware-auth-basic>
       :authenticator
       #'(lambda (user pass)
           ;; Authenticate here and return t or nil.
           ))

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

  • Class <CLACK-MIDDLEWARE-AUTH-BASIC> inherits (<MIDDLEWARE> )
    Clack Middleware to authenticate.
    AUTHENTICATOR Accessor: AUTHENTICATOR
    REALM Accessor: REALM
  • Method CALL (this <clack-middleware-auth-basic>) env

clack-middleware-clsql

Middleware for CLSQL connection management

CLACK.MIDDLEWARE.CLSQL

# 
Clack.Middleware.Clsql - Middleware for CLSQL connection management.


## SYNOPSIS

    (builder
     (<clack-middleware-clsql>
      :database-type :mysql
      :connection-spec '("localhost" "db" "fukamachi" "password"))
     app)

## DESCRIPTION

This is a Clack Middleware component for managing CLSQL's connection.

## Slots

* database-type (Optional, Keyword)

The default is `:sqlite3`.

* connection-spec (Optional, List)

The default is `("memory")`.

* connect-args (Optional, List)

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* [CLSQL](http://clsql.b9.com/)

  • Class <CLACK-MIDDLEWARE-CLSQL> inherits (<MIDDLEWARE> )
    DATABASE-TYPE Accessor: DATABASE-TYPE
    CONNECTION-SPEC Accessor: CONNECTION-SPEC
    CONNECT-ARGS Accessor: CONNECT-ARGS
  • Method CALL (this <clack-middleware-clsql>) env

clack-middleware-csrf

Middleware for easy CSRF protection

CLACK.MIDDLEWARE.CSRF

# 
Clack.Middleware.Csrf - Middleware for easy CSRF protection.


## SYNOPSIS

    ;; building application.
    (builder <clack-middleware-csrf> app)
    
    ;; in CL-EMB template.
    <form name="test-form" method="post" action="/">
    <input type="text" name="name" />
    <%= (csrf-html-tag session) %>
    <input type="submit" value="Send" />
    </form>

## DESCRIPTION

## Block behavior

    (builder
     <clack-middleware-session>
     (<clack-middleware-csrf>
      :block-app #'(lambda (env)
                     @ignore env
                     '(302
                       (:location "http://en.wikipedia.org/wiki/CSRF")
                       nil)))
     app)

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Middleware.Session

  • Class <CLACK-MIDDLEWARE-CSRF> inherits (<MIDDLEWARE> )
    Clack Middleware for easy CSRF protection.
    BLOCK-APP Accessor: BLOCK-APP
    ONE-TIME-P Accessor: ONE-TIME-P
  • Method CALL (this <clack-middleware-csrf>) env
  • Function CSRF-TOKEN session
    Return a random CSRF token.
  • Function CSRF-HTML-TAG session
    Return an 'input' tag containing random CSRF token.
    Note this has a side-effect, natually. This function stores the generated id into the current session when called.

clack-middleware-dbi

Middleware for CL-DBI connection management.

CLACK.MIDDLEWARE.DBI

# 
Clack.Middleware.Dbi - Middleware for CL-DBI connection management.


## SYNOPSIS

    (builder
     (<clack-middleware-dbi>
      :driver-name :mysql
      :connect-args '(:database-name "dbname"
                      :username "fukamachi"
                      :password "password"))
     app)

## DESCRIPTION

This is a Clack Middleware component for managing CL-DBI's connections.

## Slots

* driver-name (Required, Keyword)
* connect-args (Required, List)

`connect-args` parameters (`:username`, `:password` and so on) will be passed to `dbi:connect` as keyword parameters.

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* [CL-DBI](https://github.com/fukamachi/cl-dbi)

  • Variable *DB* NIL
  • Class <CLACK-MIDDLEWARE-DBI> inherits (<MIDDLEWARE> )
    DRIVER-NAME Accessor: DRIVER-NAME
    CONNECT-ARGS Accessor: CONNECT-ARGS
  • Method CALL (this <clack-middleware-dbi>) env

clack-middleware-oauth

Supports authorization mechanism by OAuth

CLACK.MIDDLEWARE.OAUTH

# 
Clack.Middleware.OAuth - Supports authorization mechanism by OAuth.


## SYNOPSIS

    (run
      (builder
       (<clack-middleware-oauth>
         :consumer-key "XXXXXXXXXXXXXXXXXXXXX"
         :consumer-secret "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
         :authorize-uri "http://localhost/authorize"
         :request-token-uri "http://localhost/request"
         :access-token-uri "http://localhost/access"
         :path "/auth"
         :callback-base "http://localhost/"
         :authorized #'callback)
       app))

## DESCRIPTION

This is a Clack Middleware for OAuth.
Please read rfc5849 for more information.

## Slots

* consumer-key, consumer-secret (Required, String)

OAuth parameter.

* authorize-uri, request-token-uri, access-token-uri (Required, String)

URIs to process OAuth.

* path

A path to be handled by <clack.middleware.oauth>.

* callback-base

A host address will be passed to OAuth Provider.
(format nil "~a~a" `callback-base' `path') should be valid URI.

* authorized (Required, function)

A callback function when authorization is suceeded.
It will be called with two parameters: clack request and cl-oauth:access-token.


## AUTHOR

* Norihisa Fujita (n.fujita@ariel-networks.com)

  • Class <CLACK-MIDDLEWARE-OAUTH> inherits (<MIDDLEWARE> )
    PATH Accessor: OAUTH-PATH
    CALLBACK-BASE Accessor: OAUTH-CALLBACK-BASE
    CALLBACK-URI Accessor: OAUTH-CALLBACK-URI
    CONSUMER-KEY Accessor: OAUTH-CONSUMER-KEY
    CONSUMER-SECRET Accessor: OAUTH-CONSUMER-SECRET
    AUTHORIZE-URI Accessor: OAUTH-AUTHORIZE-URI
    REQUEST-TOKEN-URI Accessor: OAUTH-REQUEST-TOKEN-URI
    ACCESS-TOKEN-URI Accessor: OAUTH-ACCESS-TOKEN-URI
    AUTHORIZED Accessor: OAUTH-AUTHORIZED
    STATE Accessor: OAUTH-STATE
    STATE-EXPIRE Accessor: OAUTH-STATE-EXPIRE
  • Method CALL (this <clack-middleware-oauth>) env

clack-middleware-postmodern

Middleware for POSTMODERN connection management

CLACK.MIDDLEWARE.POSTMODERN

# 
Clack.Middleware.Postmodern - Middleware for Postmodern connection management


## SYNOPSIS

 (builder
  (<clack-middleware-postmodern>
   :database "database-name"
   :user "database-user"
   :password "database-password"
   :host "remote-address")
  app)

## DESCRIPTION

This is a Clack Middleware component for managing Postmodern connections.

The database connection will be bound to postmodern:*database* as expected
by most of the postmodern functionality. Additionally it can be found
in the environment under the key :clack.postmodern.databases in form of
an list that maps the database names to the connections. This allows
the connection to multiple databases. The connections can be retrieved
by calling (get-connection db-name env).

## Slots

* database (String)

The name of the database.

* user (String)

The database user name.

* password (String)

The password to the database.

* host (Optional, String)

The address of the database server. The default is "localhost"

* port (Optional, Integer)

The port on which the database server is listening.

* pooled-p (Optional, Boolean)

If true, then the connection pool is used. The default is true.

* use-ssl (Optional, Keyword)

Same meaning as in the connection spec to a postmodern database. 

## AUTHOR

* Karl Heinrichmeyer (karl.heinrichmeyer@gmail.com)

## SEE ALSO

* [Postmodern](http://marijnhaverbeke.nl/postmodern/)

  • Class <CLACK-MIDDLEWARE-POSTMODERN> inherits (<MIDDLEWARE> )
    This middleware opens a connection to the specified database
    and stores it in *database* as expected by postmodern. It also
    stores the connection(s) in an alist (database name as key) in
    the environment with the key :clack.postmodern.databases.
    DATABASE Accessor: DATABASE
    The name of the database to connect to.
    USER Accessor: USER
    The name of the database user.
    PASSWORD Accessor: PASSWORD
    The password for the database.
    HOST Accessor: HOST
    The host the database server is on.
    PORT Accessor: PORT
    The port the database server is listening on.
    POOLED-P Accessor: POOLED-P
    Shall the connections be pooled?
    USE-SSL Accessor: USE-SSL
    Keyword for the use-ssl configuration.
  • Method CALL (this <clack-middleware-postmodern>) env
  • Function GET-CONNECTION db-name env

clack-middleware-rucksack

Middleware for Rucksack connection management

CLACK.MIDDLEWARE.RUCKSACK

# 
Clack.Middleware.Rucksack - Middleware for Rucksack connection management.


## SYNOPSIS

    (defvar *rs* (rs:open-rucksack "db/"))
    
    (builder
     (<clack-middleware-rucksack>
      :rucksack *rs*)
     app)

    ;; also same
    (builder
     <clack-middleware-rucksack>
     app)

## AUTHOR

* Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* [Rucksack](https://github.com/arielnetworks/rucksack)

  • Class <CLACK-MIDDLEWARE-RUCKSACK> inherits (<MIDDLEWARE> )
    RUCKSACK Accessor: RUCKSACK
  • Method CALL (this <clack-middleware-rucksack>) env

clack-session-store-dbi

CL-DBI-based session store for Clack.Middleware.Session

CLACK.SESSION.STORE.DBI

# 
Clack.Session.Store.Dbi - CL-DBI-based session store for Clack.Middleware.Session.


## SYNOPSIS

    (clackup (builder
              (<clack-middleware-session>
               :store (make-instance '<clack-session-store-dbi>
                                     :connect-args '(:mysql
                                                     :database-name "myapp"
                                                     :username "nobody"
                                                     :password "1234")))
              app))

    ;; Using custom connector.
    (clackup (builder
              (<clack-middleware-session>
               :store (make-instance '<clack-session-store-dbi>
                                     ;; connector function must return a DBI connection.
                                     :connector (lambda () (myapp.db:db))))
              app))

## DESCRIPTION

Clack.Session.Store.Dbi is a CL-DBI based storage for session data. This will use Marshal and CL-Base64 to serialize/deserialize data.

Your session table must have at least the following schema structure:

    CREATE TABLE sessions (
        id           CHAR(72) PRIMARY KEY,
        session_data TEXT
    );

## SEE ALSO

* CL-DBI
* Clack.Middleware.Session
* Clack.Session.Store

  • Class <CLACK-SESSION-STORE-DBI> inherits (<CLACK-SESSION-STORE> )
    CONNECT-ARGS Reader: STORE-CONNECT-ARGS
    CONNECTOR Reader: STORE-CONNECTOR
    TABLE-NAME Reader: STORE-TABLE-NAME
    %CONNECTION
  • Method INITIALIZE-INSTANCE (store <clack-session-store-dbi>) &key
  • Method FETCH (store <clack-session-store-dbi>) sid
  • Method STORE-SESSION (store <clack-session-store-dbi>) sid session
  • Method REMOVE-SESSION (store <clack-session-store-dbi>) sid

clack-test

Testing Clack Applications.

CLACK.TEST

# 
Clack.Test - Testing Clack Applications.


## SYNOPSIS

    (defpackage clack-test.sample
      (:use :cl
            :clack.test
            :prove
            :drakma))
    (in-package :clack-test.sample)
    
    (test-app
     (lambda (env)
       (declare (ignore env))
       `(200 (:content-type "text/plain") ("Hello, Clack!")))
     (lambda ()
       (multiple-value-bind (body status headers)
           (http-request "http://localhost:4242")
         (is status 200)
         (is body "Hello, Clack!")
         (is (assoc :content-type headers) "text/plain")))
     "Testing simple application")

## DESCRIPTION

Clack.Test provides simple interface to test Clack Application or Middleware.

Your Lisp have to support multi-thread to run this.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* [prove](https://github.com/fukamachi/prove)
* Drakma

  • Variable *CLACK-TEST-HANDLER* :HUNCHENTOOT
    Backend Handler to run tests on. String or Symbol are allowed.
  • Variable *CLACK-TEST-PORT* 4242
    HTTP port number of Handler.
  • Variable *ENABLE-DEBUG-P* T
  • Function TEST-APP app client &optional desc
    Test Clack Application.
  • Macro DEFINE-APP-TEST desc app client &optional (enable-debug-p *enable-debug-p*)
    Define tests for Clack Application. This just wrap `prove:deftest', so you can run this test by calling `(prove:run-test :foo)'.

CLACK.TEST.SUITE

# 
Clack.Test.Suite - Test suite for Clack handlers.


## SYNOPSIS

    ;; Tests Clack.Handler.Hunchentoot.
    (clack.test.suite:run-server-tests :hunchentoot)
    
    ;; Tests one test.
    (clack.test.suite:run-server-tests :hunchentoot '|% double encoding in PATH-INFO|)

## DESCRIPTION

Clack.Test.Suite is a test suite to test a new Clack server implementation. It automatically loads a new handler environment and uses Drakma to send HTTP requests to the local server to make sure your handler implements the Clack specification correctly.

Your Lisp have to support multi-thread to run these tests.

## AUTHOR

Eitaro Fukamachi (e.arrows@gmail.com)

## SEE ALSO

* Clack.Test

  • Variable *CLACK-TEST-ACCESS-PORT* CLACK.TEST:*CLACK-TEST-PORT*
    Port of localhost to request.
    Use if you want to set another port. The default is `*clack-test-port*`.
  • Function RUN-SERVER-TESTS handler-name &optional name
    Run tests for clack.handler.
    Handler name is a keyword and doesn't include the clack.handler prefix.
    For example, if you have a handler `clack.handler.foo',
    you would call like this: `(run-server-tests :foo)'.

t-clack-handler-fcgi

t-clack-handler-hunchentoot

t-clack-handler-toot

t-clack-handler-wookie

t-clack-middleware-auth-basic

t-clack-middleware-csrf