wibbly - a basic web server, receives and responds to HTTP 1.1 requests

package require wibbly

HTTP Server

::wibbly::serve ?option value ...?

Opens a server socket which listens for HTTP requests and responds to them. This command will return immediately. To actually wait for requests you need to enter the event loop, e.g. by calling vwait. Other events can then be processed in parallel, such as responding to a Tk GUI. ::wibbly::serve will process each http connection in a separate coroutine. To avoid blocking the whole server, handler code should use the coroutine-aware commands in ::coroutine::util for any operations which involve waiting. The following options can be specified:

-port port
The IP port to listen on. Defaults to 8080.

-socketcmd command
The command to use to open the server socket. The default is socket but ::tls::socket can be specified to support https.

-handler command
The command specified will be called to process each http request received. It will be called with a single argument, a web object of the class wobbly, documented below. The default handler just returns a web page describing the request received.

-accesslog filename
This specifies the name of a file where each request received will be logged. The name may contain variables and commands, which will be substituted by calling subst. The default is /tmp/wibbly.$port.[clock format now -format {%y.%m.%d}].log which will start a new log file for each day. Setting the name to an empty string will disable request logging.

-errorlog filename
This specifies the name of a file where any uncaught errors in request processing will be logged. This name will also be substituted by subst. The default is /tmp/wibbly.$port.errors.

-error2user command
This specifies a command which will be called for any uncaught errors in request processing. The command will be called with two arguments, the URI requested and the Tcl errorInfo. The command should return a list of two values, the HTTP error code to return and the html for any message to be return to the user. The default returns error code 500 (internal error) and the message Sorry, the server failed to process your request for '$uri' at $date GMT.

HTML Utilities

::wibbly::template body
Expand a template. Lines in the template body starting with % are treated as code and executed. All other lines become part of the result after variable and command substitution.

::wibbly::enhtml string
Encode string for HTML by substituting angle brackets, ampersands, space sequences, and line breaks.

::wibbly::enattr string
Encode string for HTML tag attribute by substituting angle brackets, ampersands, space sequences, and single and double quotes.

::wibbly::enpre string
Encode string for HTML <pre> by substituting angle brackets and ampersands.

::wibbly::enhex string ?pattern?
Encode string by substituting most non-alphanumerics with hexadecimal codes.

::wibbly::dehex string
Decode hexadecimal encoding of string.

Web Objects

For each request received, the user's handler is called with a web object which encapsulates the application's interface to the web server. Web Objects (wobs) belong to the class wobbly and support the following methods:

getPath
Returns the path which was requested.

getHeader name
Returns the header with the specified name from the request, or an empty string if it does not exist.

getCookie name
Returns the value of the cookie with the specified name from the request, or an empty string if it does not exist.

getFormdata
Returns a name/value dict of all the form data sent in the request, whether by GET or POST method. A file upload field will return the file content as the value here, it is left to the application code to write this out to a file if that is required.

htmlResponse html
Sets the literal html supplied as the response to be sent.

dataResponse data type
Sets the literal data supplied as the response to be sent, with the specified mime type.

fileResponse path ?type?
Sets the content of the file named by path as the response to be sent. If the mime type is not specified it will be deduced from the file extension.

cacheMaxAge seconds
Sets the cache-control header of the response to specify that the content returned may be cached for not more than the specified number of seconds.

setHeader name value
Sets the named header in the response to the given value.

errorResponse code ?detail?
Sets the response to report an error with the specified error code, and optionally adds the html in detail to give further information.

redirect newurl
Sets the response to tell the client to redirect to the specified URL.

setLogField field value
The first three fields in the access log are named remote, ident and user. The remote field will default to the IP address of the source of the request, if this is available. The ident and user fields have no default value. This method allows the application to set the specified log field to the given value.

scgi host port ?name value ...?
Forward the request to a program which provides an SCGI interface on the specified host and port. Additional argument pairs of name and value can be supplied to set or override headers in the SCGI request. The HTTP response will then be set from the SCGI response.

Example

Start a web server on port 8080 which

• dynamically generates its home page, inserting the current time;
• serves any files placed in the htdocs subdirectory;
• returns a 404 error for other cases.

package require wibbly

proc myhandler wob {
    set path [$wob getPath]
    if {$path eq "/"} {
        $wob htmlResponse "<h1>Hello World</h1>The time is [clock format now]"
    } elseif {[file isfile htdocs$path]} {
        $wob fileResponse htdocs$path
    } else {
        $wob errorResponse 404
    }
}

::wibbly::serve -handler myhandler

vwait forever