Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
102 lines (83 sloc) 4.48 KB
Hunchensocket - WebSockets for Hunchentoot
==========================================
Hunchensocket is a Common Lisp implementation of [WebSocket]s realized
as an extension to [Edi Weitz'] [edi] excellent [Hunchentoot] web server.
As [WebSocket]s are still in draft state and security concerns have been
[raised](http://www.ietf.org/mail-archive/web/hybi/current/msg04744.html) against older
(but supported) draft versions of the protocol implemented in a number of
browsers, it should not be used productively (yet), unless of course you know
what you're doing.
Installation
------------
Hunchensocket is supported by and available through [asdf-install] and
(soon) [Quicklisp].
Support
-------
Currently, only [draft-ietf-hybi-thewebsocketprotocol-00] [draft-hybi-00] aka
draft-hixie-thewebsocketprotocol-76 as implemented in [Chromium] versions 6 to
13 and [Firefox] 4.0 to 5.0 (disabled, must be enabled explicitly) are available
but newer drafts and the future standard are to come as new web browser versions
supporting them emerge. For a more complete matrix including proprietary
browsers, please consider the WebSocket
[Wikipedia article](http://en.wikipedia.org/wiki/WebSocket#Browser_support).
Usage
-----
Hunchensocket is meant to be used as a Hunchentoot extension. In order to be
able to establish and send and receive on WebSockets, Follow the regular
Hunchentoot [documentation](http://www.weitz.de/hunchentoot/#start) but exchange
the regular `HUNCHENTOOT:ACCEPTOR` and `HUNCHENTOOT:SSL-ACCEPTOR` with
`HUNCHENSOCKET:WEBSOCKET-ACCEPTOR` and `HUNCHENSOCKET:WEBSOCKET-SSL-ACCEPTOR`,
respectively.
In order to make use of WebSocket connections, one must define WebSocket
handlers that decide whether to accept a WebSocket request and, if they do,
return a cascading closure of function as follows:
```λ request -> λ stream mutex -> λ message```
Or, in other words, a (dispatcher) function that takes a Hunchentoot request
object and, if it accepts the request, returns a (handshake handler) function
which can (optionally) be used to perform initial set-up stuff and finally has
to evaluate to a final (message handler) function that will be called upon
socket input and has access to the both lexically enclosed and dynamically
available websocket stream and mutex objects in order to send data through the
socket.
Unless you have very special plans for using WebSockets, esp. in case all you
want is to exploit their possibilities for your web project, you are adviced to
use [hunchen.io] which handles the tedious parts for you and can be used
together with the [socket.io] client-side JavaScript libraries.
Links and References
--------------------
Homepage: <http://www.cliki.net/hunchensocket>
Hacking: <http://github.com/e-user/hunchensocket>
[WebSocket]: http://en.wikipedia.org/wiki/WebSocket
[edi]: http://weitz.de/
[Hunchentoot]: http://weitz.de/hunchentoot/
[asdf-install]: http://www.cliki.net/ASDF-Install
[Quicklisp]: http://www.quicklisp.org/
[draft-hybi-00]: http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-00
[Chromium]: http://www.chromium.org/Home
[Firefox]: http://www.mozilla.com/en-US/firefox/new/
[hunchen.io]: http://cliki.net/hunchen.io
[socket.io]: http://socket.io/
Copyright
---------
Copyright (C) 2011 Alexander Kahl <e-user@fsfe.org>
This file is part of Hunchensocket.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* 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.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR 'AS IS' AND ANY EXPRESSED
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 AUTHOR 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.
Jump to Line
Something went wrong with that request. Please try again.