`cwebs`: WebSocket wire protocol, in C

authors

André Caron

contact

andre.l.caron@gmail.com

Check out the project page for compiled HTML documentation.

Description

This library provides a parser for the WebSocket wire protocol. The parser is implemented as a finite state machine (FSM) for use in streaming applications (i.e. data arrives at an unpredictable rate and the parser must be interruptible). As such, the parser itself does not buffer any received data. It just forwards it to registered callbacks. It requires little overhead and is well suited for being used in an object-oriented wrapper.

Requirements

The core library has no dependencies. No threads, no sockets, no files, nothing. It doesn't even dynamically allocate any memory. It assumes nothing of the context in which you intend to use it. You can use it with any networking framework, any HTTP library, etc.

The test suites require some external support for implementation of HTTP request and response parsers, Base64 encoding, SHA-1, etc. Suitable libraries are referenced as Git submodules. These libraries are not required to use the core library services.

Actual dependencies are:

1. CMake. If you don't like CMake, you can whip up a build script for just about any build system. The code library consists of only 2 C source files and a few C headers.
2. A C/C++ compiler toolchain:
   • Microsoft Visual Studio (any recent version should do)
   • GCC + Make
3. Doxygen (optional). The documentation is not yet hosted online, so you will need to build a local copy.

Demonstration

There's a C++-based tunnel program with both UNIX and Windows implementations based on nothing but the native APIs. They can be used to tunnel arbitrary data exchange over port 80, all with standard HTTP semantics for virtual hosting, URL-based dispatch, encryption, etc. (caveat: very few web servers implement facilities for such a dispatch given WebSockets).

There's a full-blown WebSockets server based on Qt and the http-parser library. You can test the echo server with the echo client project which is implemented using the HTML 5 WebSocket API and jQuery.

Compiling

This library provides a CMake build script. To compile the library, download and install CMake, and then generate build scripts for your favorite build tool.

On Microsoft Windows

1. launch the visual studio command prompt

2. check out the source code (or download a source code bundle)

   git clone git@github.com:AndreLouisCaron/cwebs.git
   cd cwebs
   git submodule init
   git submodule update

3. generate NMake project files

   mkdir work
   cd work
   cmake -G "NMake Makefiles" ..

   If you intend to modify (rather than simply use) the library, generate a debug build. This will compile using debugging symbols and publish HTML documentation for internal and private symbols in addition to the public symbols. Set the build type like so:

   cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Debug ..

4. compile the libraries and tests

   nmake

5. build the HTML documentation (optional)

   nmake help

6. run the tests (optional)

   nmake /A test

You can use JOM as an alternative to NMake to accelerate builds on multi-processor machines. Use the "NMake Makefiles JOM" CMake generator and use jom instead of NMake. Beware that the test target is broken and you must still invoke nmake /A test to run the tests.

On UNIX-like systems

1. launch your favorite terminal

2. check out the source code (or download a source code bundle)

   git clone git@github.com:AndreLouisCaron/cwebs.git
   cd cwebs
   git submodule init
   git submodule update

3. generate Makefiles

   mkdir work
   cd work
   cmake ..

   If you intend to modify (rather than simply use) the library, generate a debug build. This will compile using debugging symbols and publish HTML documentation for internal and private symbols in addition to the public symbols. Set the build type like so:

   cmake -DCMAKE_BUILD_TYPE=Debug ..

4. compile the libraries and tests

   make

5. build the HTML documentation (optional)

   make help

6. run the tests (optional)

   make test

License

The code is distributed under the simplified 2-clause BSD licence. It is absolutely free to use in both open source and commercial applications, provided you don't take credit for my work.

You don't need my consent or anything to use the software, but it would be nice of you to tell me if you're using it. It would allow me to keep a list of most notable uses, giving credibility to the software and ensuring it is maintained properly. I also like to know that people are you using my software :-)

Here is a verbatim copy of the license:

Copyright (c) 2011-2012, Andre Caron (andre.l.caron@gmail.com)
All rights reserved.

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 COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS 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 COPYRIGHT
HOLDER OR CONTRIBUTORS 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.

References

• A nice resource page about WebSockets
• The WebSocket specification