This is the wookie Reference Manual, version 0.3.15, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 08:06:38 2024 GMT+0.
wookie/wookie.asdwookie/config.lispwookie/util.lispwookie/package.lispwookie/state.lispwookie/error.lispwookie/route.lispwookie/plugin.lispwookie/hook.lispwookie/request-response.lispwookie/parser.lispwookie/listener.lispwookie/listener-ssl.lispwookie/helper.lispThe main system appears first, followed by any subsystem dependency.
wookieAn evented webserver for Common Lisp.
Andrew Danger Lyon <orthecreedence@gmail.com>
MIT
0.3.15
alexandria (system).
blackbird (system).
cl-async (system).
cl-async-ssl (system).
cl-ppcre (system).
babel (system).
chunga (system).
fast-http (system).
quri (system).
do-urlencode (system).
cl-fad (system).
fast-io (system).
vom (system).
config.lisp (file).
util.lisp (file).
package.lisp (file).
state.lisp (file).
error.lisp (file).
route.lisp (file).
plugin.lisp (file).
hook.lisp (file).
request-response.lisp (file).
parser.lisp (file).
listener.lisp (file).
listener-ssl.lisp (file).
helper.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
wookie/wookie.asdwookie/config.lispwookie/util.lispwookie/package.lispwookie/state.lispwookie/error.lispwookie/route.lispwookie/plugin.lispwookie/hook.lispwookie/request-response.lispwookie/parser.lispwookie/listener.lispwookie/listener-ssl.lispwookie/helper.lispwookie/config.lispwookie (system).
*debug-on-error* (special variable).
*enabled-plugins* (special variable).
*hide-version* (special variable).
*max-body-size* (special variable).
*tmp-file-store* (special variable).
wookie/util.lispconfig.lisp (file).
wookie (system).
body-to-string (function).
camel-case (function).
get-header (macro).
getf-reverse (function).
lookup-status-text (function).
map-plist (function).
querystring-to-hash (function).
querystringp (function).
set-header (macro).
set-querystring-hash (function).
*scanner-querystring-p* (special variable).
convert-hash-vectors (function).
get-querystring-hash-r (function).
getf* (function).
print-hash (function).
wookie/package.lispwookie/state.lisppackage.lisp (file).
wookie (system).
*state* (special variable).
wookie-state (class).
wookie-state-hooks (reader method).
(setf wookie-state-hooks) (writer method).
wookie-state-plugin-config (reader method).
(setf wookie-state-plugin-config) (writer method).
wookie-state-plugins (reader method).
(setf wookie-state-plugins) (writer method).
wookie-state-routes (reader method).
(setf wookie-state-routes) (writer method).
wookie-state-ordered-routes (reader method).
(setf wookie-state-ordered-routes) (writer method).
wookie/error.lisppackage.lisp (file).
state.lisp (file).
wookie (system).
wookie-error (condition).
wookie-error-msg (reader method).
wookie-error-socket (reader method).
listener-event-handler (function).
main-event-handler (function).
wookie/route.lisperror.lisp (file).
wookie (system).
clear-route (function).
clear-routes (function).
defroute (macro).
next-route (function).
route-error (condition).
route-not-found (condition).
with-vhost (macro).
*default-vhost* (special variable).
add-route (function).
find-route (function).
make-route (function).
method-equal (function).
ordered-routes (function).
route-equal (function).
route-error-resource (reader method).
routes-modified (function).
upsert-route (function).
use-next-route (condition).
wookie/plugin.lisppackage.lisp (file).
state.lisp (file).
wookie (system).
*plugin-folders* (special variable).
defplugfun (macro).
defplugin (macro).
load-plugins (function).
plugin-config (function).
(setf plugin-config) (function).
plugin-request-data (function).
(setf plugin-request-data) (function).
register-plugin (function).
unload-plugin (function).
*available-plugins* (special variable).
*current-plugin-name* (special variable).
*scanner-plugin-name* (special variable).
match-plugin-asdf (function).
resolve-dependencies (function).
wookie/hook.lisppackage.lisp (file).
state.lisp (file).
wookie (system).
add-hook (function).
clear-hooks (function).
remove-hook (function).
do-run-hooks (macro).
run-hooks (function).
wookie/request-response.lisperror.lisp (file).
hook.lisp (file).
wookie (system).
finish-response (function).
get-socket (generic function).
request (class).
request-body (reader method).
(setf request-body) (writer method).
request-body-callback (reader method).
(setf request-body-callback) (writer method).
request-data (reader method).
(setf request-data) (writer method).
request-headers (reader method).
(setf request-headers) (writer method).
request-http (reader method).
(setf request-http) (writer method).
request-method (reader method).
(setf request-method) (writer method).
request-plugin-data (reader method).
(setf request-plugin-data) (writer method).
request-resource (reader method).
(setf request-resource) (writer method).
request-socket (reader method).
(setf request-socket) (writer method).
request-store-body (reader method).
(setf request-store-body) (writer method).
request-uri (reader method).
(setf request-uri) (writer method).
response (class).
response-already-sent (condition).
response-error (condition).
response-error-response (reader method).
response-finished-p (reader method).
(setf response-finished-p) (writer method).
response-headers (reader method).
(setf response-headers) (writer method).
response-request (reader method).
(setf response-request) (writer method).
send-100-continue (function).
send-response (function).
start-response (function).
with-chunking (macro).
*wookie-version* (special variable).
add-default-headers (function).
get-log-uri (function).
request-body-callback-setcb (reader method).
(setf request-body-callback-setcb) (writer method).
response-chunk-stream (reader method).
(setf response-chunk-stream) (writer method).
wookie/parser.lisperror.lisp (file).
request-response.lisp (file).
route.lisp (file).
hook.lisp (file).
plugin.lisp (file).
wookie (system).
get-overridden-method (function).
handle-connection (function).
read-data (function).
setup-parser (function).
wookie/listener.lisperror.lisp (file).
request-response.lisp (file).
route.lisp (file).
hook.lisp (file).
plugin.lisp (file).
parser.lisp (file).
wookie (system).
listener (class).
listener-backlog (reader method).
(setf listener-backlog) (writer method).
listener-bind (reader method).
(setf listener-bind) (writer method).
listener-port (reader method).
(setf listener-port) (writer method).
start-server (generic function).
listener-event-cb (reader method).
(setf listener-event-cb) (writer method).
wookie/listener-ssl.lisplistener.lisp (file).
wookie (system).
listener-certificate (reader method).
(setf listener-certificate) (writer method).
listener-key (reader method).
(setf listener-key) (writer method).
listener-password (reader method).
(setf listener-password) (writer method).
ssl-listener (class).
start-server (method).
wookie/helper.lisplistener.lisp (file).
plugin.lisp (file).
package.lisp (file).
wookie (system).
serve-html5-app (function).
start-static-server (function).
file-contents (function).
Packages are listed by definition order.
wookie-utilblackbird.
common-lisp.
wookie-config.
body-to-string (function).
camel-case (function).
get-header (macro).
getf-reverse (function).
lookup-status-text (function).
map-plist (function).
querystring-to-hash (function).
querystringp (function).
set-header (macro).
set-querystring-hash (function).
*scanner-querystring-p* (special variable).
convert-hash-vectors (function).
get-querystring-hash-r (function).
getf* (function).
print-hash (function).
wookie-helpercommon-lisp.
wookie.
wookie-plugin-export.
serve-html5-app (function).
start-static-server (function).
file-contents (function).
wookie-configcommon-lisp.
*debug-on-error* (special variable).
*enabled-plugins* (special variable).
*hide-version* (special variable).
*max-body-size* (special variable).
*tmp-file-store* (special variable).
wookieblackbird.
common-lisp.
wookie-config.
wookie-util.
*plugin-folders* (special variable).
*state* (special variable).
add-hook (function).
clear-hooks (function).
clear-route (function).
clear-routes (function).
defplugfun (macro).
defplugin (macro).
defroute (macro).
finish-response (function).
get-socket (generic function).
listener (class).
listener-backlog (generic reader).
(setf listener-backlog) (generic writer).
listener-bind (generic reader).
(setf listener-bind) (generic writer).
listener-certificate (generic reader).
(setf listener-certificate) (generic writer).
listener-key (generic reader).
(setf listener-key) (generic writer).
listener-password (generic reader).
(setf listener-password) (generic writer).
listener-port (generic reader).
(setf listener-port) (generic writer).
load-plugins (function).
next-route (function).
plugin-config (function).
(setf plugin-config) (function).
plugin-request-data (function).
(setf plugin-request-data) (function).
register-plugin (function).
remove-hook (function).
request (class).
request-body (generic reader).
(setf request-body) (generic writer).
request-body-callback (generic reader).
(setf request-body-callback) (generic writer).
request-data (generic reader).
(setf request-data) (generic writer).
request-headers (generic reader).
(setf request-headers) (generic writer).
request-http (generic reader).
(setf request-http) (generic writer).
request-method (generic reader).
(setf request-method) (generic writer).
request-plugin-data (generic reader).
(setf request-plugin-data) (generic writer).
request-resource (generic reader).
(setf request-resource) (generic writer).
request-socket (generic reader).
(setf request-socket) (generic writer).
request-store-body (generic reader).
(setf request-store-body) (generic writer).
request-uri (generic reader).
(setf request-uri) (generic writer).
response (class).
response-already-sent (condition).
response-error (condition).
response-error-response (generic reader).
response-finished-p (generic reader).
(setf response-finished-p) (generic writer).
response-headers (generic reader).
(setf response-headers) (generic writer).
response-request (generic reader).
(setf response-request) (generic writer).
route-error (condition).
route-not-found (condition).
send-100-continue (function).
send-response (function).
ssl-listener (class).
start-response (function).
start-server (generic function).
unload-plugin (function).
with-chunking (macro).
with-vhost (macro).
wookie-error (condition).
wookie-error-msg (generic reader).
wookie-error-socket (generic reader).
wookie-state (class).
wookie-state-hooks (generic reader).
(setf wookie-state-hooks) (generic writer).
wookie-state-plugin-config (generic reader).
(setf wookie-state-plugin-config) (generic writer).
wookie-state-plugins (generic reader).
(setf wookie-state-plugins) (generic writer).
wookie-state-routes (generic reader).
(setf wookie-state-routes) (generic writer).
*available-plugins* (special variable).
*current-plugin-name* (special variable).
*default-vhost* (special variable).
*scanner-plugin-name* (special variable).
*wookie-version* (special variable).
add-default-headers (function).
add-route (function).
do-run-hooks (macro).
find-route (function).
get-log-uri (function).
get-overridden-method (function).
handle-connection (function).
listener-event-cb (generic reader).
(setf listener-event-cb) (generic writer).
listener-event-handler (function).
main-event-handler (function).
make-route (function).
match-plugin-asdf (function).
method-equal (function).
ordered-routes (function).
read-data (function).
request-body-callback-setcb (generic reader).
(setf request-body-callback-setcb) (generic writer).
resolve-dependencies (function).
response-chunk-stream (generic reader).
(setf response-chunk-stream) (generic writer).
route-equal (function).
route-error-resource (generic reader).
routes-modified (function).
run-hooks (function).
setup-parser (function).
upsert-route (function).
use-next-route (condition).
wookie-state-ordered-routes (generic reader).
(setf wookie-state-ordered-routes) (generic writer).
Definitions are sorted by export status, category, package, and then by lexicographic order.
If T, will not catch errors but instead allow them to go to the debugger.
A list of (keyword) names of enabled plugins.
Boolean specifying whether or not to hide the Wookie version in the Server header.
The max HTTP body size in bytes that Wookie will store for each request, assuming the request is set to store the body (see request-store-body).
A list of directories where Wookie plugins can be found.
Holds all global state/context for Wookie.
Stores the path to where uploads/temporary files go.
Define a plugin function that is auto-exported to the :wookie-plugin-export package.
Simple wrapper around asdf:defsystem that maps a plugin-name (hopefully in *current-plugin-name*) to the ASDF system the plugin defines.
Defines a wookie route and pushes it into the route list.
:regex specifies whether resource is a regex or not
:chunk specifies if the route can handle chunked content
:buffer-body tells Wookie to save any body parts that come through before
with-chunking is called
:suppress-100 tells Wookie that we want to send our own ‘100 Continue‘ HTTP
response if we get an ‘Expect: 100-continue‘ header in the request
:replace tells the routing system to upsert this resource/method set
(instead of just blindly adding it to the end of the list like default)
:priority specifies a the route priority (a number, defaults to 0). Routes
with higher priority values are processed first. Both negative and
positive priorities are acceptable.
bind-request/bind-response are the variable names that the request/response values are bound to, and bind-args specifies that variable that regex group matches get sent to (a list).
Get a value from a header collection.
Set a value into a header collection.
Set up a listener for chunked data in a chunk-enabled router. This macro
takes a request object, the names of the chunk-data/finishedp arguments
for the body, and the body form.
Chunk-data is a byte-array of data received as decoded chunked data comes in from the client, and last-chunk-p is a boolean indicating whether the last chunk from the request is being sent in.
Simple wrapper that makes all defroutes in the body bind to a specific vhost:
(with-vhost "omg.com"
(defroute ...)
(defroute ...))
Add a hook into the wookie system. Hooks will be run in the order they were added.
Given a byte vector of HTTP body data and the value of a Content-Type header, convert the body to a string via the charset provided in the header. If a character encoding is not provided, go with the HTTP default, ISO-8859-1.
Camel case anything that can be converted to a string (string, keyword, symbol, etc).
Clear all hooks (default) or optionally a specific hook type.
Clear out a route in the routing table.
Clear out all routes.
Given the stream passed back from start-response, finalize the response (send empty chunk) and close the connection, if specified.
Like getf, except the VALUE comes before the KEY:
’(:value1 :key1 :value2 :key2)
Allows reverse lookups in plists without duplicating structures.
Load all plugins under the *plugin-folder* fold (set with set-plugin-folder). There is also the option to compile the plugins (default nil).
Get the HTTP standard text that goes along with a status code.
Iterate over a plist
Lets the routing system know to re-route the current request, excluding this route from the available options.
Return the configuration for a plugin. Setfable.
Allow setting of plugin configuration via setf.
Retrieve the data stored into a request object for the plugin-name (keyword) plugin. This function is setfable.
When a plugin wants to store data available to the main app, it can do so by storing the data into the request’s plugin data. This function allows this by taking the plugin-name (keyword), request object passed into the route, and the data to store.
Convert a querystring into a hash table.
Detects if the given string is an HTTP querystring.
Register a plugin in the Wookie plugin system. Generally this is called from a plugin.lisp file, but can also be called elsewhere in the plugin. The plugin-name argument must be a unique keyword, and init-fn is the initialization function called that loads the plugin (called only once, on register).
Remove a hook from a set of hooks by its function reference OR by the hook’s name given at add-hook.
Send a 100 Continue header on the given response object.
Send a response to an incoming request. Takes :status, :headers, and :body
keyword arguments, which together form an entire response.
If :close is T, close the client connection after the response has been sent fully. However, send-response does its best to read the request headers and determine whether or not the connection should be closed. Unless you have a reason to specify :close, it may be best to leave it blank.
This is a full-service convenience function for serving up an HTML5 app. This
is a lot like start-static-server, but sends all non-existent routes to the
load-index function, assuming your index.html file (or whatever you specify
in :index-file) is capable of routing on the current URL path. This lets you
run HTML apps directly from Wookie with one simple call.
Note that this must be started in the directory of the app itself.
Set the key of a querystring var into a hash, creating as many nested hashes
as needed. For instance:
(set-querystring-hash myhash "data[body][tags]" "dogs,animals,bark")
Would update ‘myhash‘ with
[body] => < hash: [tags] => "dogs,animals,bark" >
Start a response to the client, but do not specify body content (or close the connection). Return a chunked (chunga) stream that can be used to send the body content bit by bit until finished by calling finish-response.
This is a full-service convenience function that lets you quickly start up a server for serving static content (defaults to the current directory, but you can specify via ‘asset-dir‘).
Unload a plugin from the wookie system. If it’s currently registered, its
unload-function will be called.
Also unloads any current plugins that depend on this plugin. Does this recursively so all depencies are always resolved.
Grabs the current socket for the request/response given.
ssl-listener)) ¶automatically generated reader method
ssl-listener)) ¶automatically generated writer method
ssl-listener)) ¶automatically generated reader method
key.
ssl-listener)) ¶automatically generated writer method
key.
ssl-listener)) ¶automatically generated reader method
ssl-listener)) ¶automatically generated writer method
response-error)) ¶Start Wookie with the given listener.
ssl-listener)) ¶wookie-error)) ¶msg.
wookie-error)) ¶wookie-state)) ¶wookie-state)) ¶Holds the hook callbacks associated with this context.
wookie-state)) ¶wookie-state)) ¶Holds all plugin configuration.
wookie-state)) ¶wookie-state)) ¶Holds the loaded plugins and their associated data for this context
wookie-state)) ¶wookie-state)) ¶Holds the routes this context uses.
Triggered when a response is attempted more than once.
Describes a response error
(quote nil)
:response
This slot is read-only.
Describes a general routing error.
(quote nil)
:resource
This slot is read-only.
Describes a route not found error.
Describes a basic error while processing. Meant to be extended.
Describes an HTTP listener.
A class describing a request, passed to every route.
get-socket.
(setf request-body).
request-body.
(setf request-body-callback).
request-body-callback.
(setf request-body-callback-setcb).
request-body-callback-setcb.
(setf request-data).
request-data.
(setf request-headers).
request-headers.
(setf request-http).
request-http.
(setf request-method).
request-method.
(setf request-plugin-data).
request-plugin-data.
(setf request-resource).
request-resource.
(setf request-socket).
request-socket.
(setf request-store-body).
request-store-body.
(setf request-uri).
request-uri.
:socket
common-lisp.
:get
:method
"/"
:resource
:headers
:url
:data
t
:store-body
:plugin-data
:body-callback
:body-callback-setcb
:http
A class holding information about a response to the client.
Describes an HTTPS listener.
wookie-state holds all global data/state used by Wookie. It’s purpose is to make threading Wookie easier by allowing the declaration of one thread-local variable instad of many.
Holds the hook callbacks associated with this context.
(make-hash-table :size 10 :test (function eq))
:hooks
Holds the loaded plugins and their associated data for this context
(make-hash-table :test (function eq))
:plugins
Holds all plugin configuration.
:plugin-config
Holds the routes this context uses.
(make-array 0 :adjustable t :fill-pointer t)
:routes
Routes ordered according to their priority (cached value)
A plist (generated by load-plugins) that holds a mapping of plugin <–> ASDF systems for the plugins. Reset on each load-plugins run.
Used by load-plugins to tie ASDF systems to a :plugin-name
Defines the default virtualhost that routes use (unless explicitely stated otherwise). Nil means no vhost (respond to all requests).
Basically unix’s basename in a regex.
Detects a querystring.
Holds Wookie’s current version.
Run a number of hooks, catch any errors while running said hooks, and if an error occurs, clear out all traces of the current request (specified on the socket). If no errors occur, run the body normally.
Add a number of default headers to a headers plist. If one of the default headers is already present, do NOT overwrite it. This allows the app to set its own headers that can override the defaults.
Add a new route to the table.
Given a hash table, look for all hashes whos keys are a set of indexes
starting at zero and convert them to vectors. For instance:
{users: {0: ’leonard’, 1: ’freddy’, 2: ’samuel’}}
becomes:
{users: [’leonard’, ’freddy’, ’samuel’]}
This function is recursive.
Sucks up an entire file from PATH into a freshly-allocated string, returning two values: the string and the number of bytes read.
Given a method and a resource, find the best matching route.
Given a quri object, return a string of the printable version for logging.
Checks if there is a GET var called _method, and if so, uses it instead of the provided method.
Recursively build a tree of hashes based on a given set of subkeys in a query string.
Similar to GETF but compares keys with string-equal.
Handles a new connection. Creates a bunch of closures that are passed into an http-parse parser which decide amongst themselves, during different points in the parsing, when to dispatch to the found router, when to send chunked content to the route, etc.
A wrapper around main-event-handler, useful for listeners to tie into.
Handle socket events/conditions that crop up during processing.
Simple wrapper to make a route object from a set of args.
Match a plugin and an ASDF system toeach other.
Test two route methods (kewords or lists of keywords) for equality.
Return the array of routes ordered by their priority, routes with higher priority being first.
Useful for debugging hash tables.
A simple read-cb handler that passes data to the HTTP parser attached to the socket the data is coming in on. The parser runs all necessary callbacks directly, so this function just blindly feeds the data in.
Load the ASDF plugins and resolve all of their dependencies. Kind of an unfortunate name. Will probably be renamed.
Test the property values of :method and :resource-str in a route plist for equality against a supplied method and resource-str.
Reset ordered route cache after routing changes
Run all hooks of a specific type. Returns a future that is finished with no
values when all hooks have successfully run. If a hook callback returns a
future object, then run-hooks will wait for it to finish before finishing its
own future. If multiple callbacks return futures, run-hooks waits for ALL of
them to finish before finishing its future.
This setup allows an application to add extra processing to hooks that may be
asynchronous without blocking the event loop, and without the processing of
the current request stampeding full steam ahead when it may need access to
information the hook is grabbing async.
For instance, let’s say you want to check user auth on each request, you
could set up a :pre-route hook that reads the request and checks the auth
info against your database, finishing the future it returns only when the
database has responded. Once the future is finished, then Wookie will
continue processing the request.
This is the main parser function. It’s responsible for listening to a socket,
setting up an HTTP parser for it, handling the different events/callbacks the
HTTP parser throws at it, dispatching routes, handling body chunking, etc. A
lot of this is done via shared state which all lives under this function’s
top-level (let) form, and a set of local functions which read/modify this
shared state.
This function is at the core of Wookie’s being.
Note that setup-parser can be called multiple times on the same socket. The only reason to do this is if a request/response has come and gone on the socket and you wish to make the socket available for another request. Wookie handles all of this automatically.
Add a new route to the table. If a route already exists with the same method and resource string, it is replaced with the new one in the same position the old route existed in (as to preserve routing order).
route-error)) ¶wookie-state)) ¶wookie-state)) ¶Routes ordered according to their priority (cached value)
Signals to the routing system to load the next route after the one loaded. can be used to set up route load chains based on criteria not sent directly to find-route.
condition.
| Jump to: | (
A B C D F G H L M N O P Q R S U W |
|---|
| Jump to: | (
A B C D F G H L M N O P Q R S U W |
|---|
| Jump to: | *
B C D E F H K M O P R S U |
|---|
| Jump to: | *
B C D E F H K M O P R S U |
|---|
| Jump to: | C E F H L P R S U W |
|---|
| Jump to: | C E F H L P R S U W |
|---|