libWebAppServer  0.1
web application messaging API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages

Overview

This is a server for handling WebSocket or FastCGI (Ajax long-polling) backend of a web application.

For a quick start, look at the Sample C++ code and Sample XHR Javascript code.

For the brave, there is also a simple WebAppClient library.

Interesting Data Structures

Here are some interesting data structures you should look at (referenced in the sample code):

Bug:
A user's WebAppConnection needs a way to deal with cookies. Some kind of method interface needs to be added whereby an application can add or delete cookies, and have cookies presented by the browser presented to the application (a virtual callback perhaps).
Bug:
The FastCGI interface needs to be able to pass more than one message thru per GET or POST request, perhaps by chaining multiple base64-encoded messages back to back with a size-delimiter between them. The reason for this is performance: any application which needs to pass a significant amount of data needs to be able to optimize its use of the link (think uploads and downloads).

How To

Everything begins with a WebAppServer. In order to use WebAppServer, it must be provided with a configuration, in the form of a WebAppServerConfig.

Note:
The WebAppServerConfig object you supply must exist at least as long as the WebAppServer exists. The WebAppServer grabs a pointer to your WebAppServerConfig object and references it while running.

The WebAppServerConfig object must be provided a set of configurations for applications to serve. This is done via the WebAppServerConfig::addWebsocket and WebAppServerConfig::addFastCGI methods.

These methods must be supplied a TCP port number. For WebSockets, it is assumed this the port number specified in either the web server config (if e.g. NGINX is using a WebSocket proxy) or provided directly in the JavaScript client in the browser. For FastCGI, it is the port number specified in the web server config. Multiple applications may be attached to the same TCP port number, however their types cannot be mixed (i.e. a TCP port must be either all FastCGI or all WebSocket).

Multiple applications on the same port must be distinguished using different routes. (A 'route' in this context is referring to the portion of the URL after the hostname, also known as the document URI.)

The user must also supply a WebAppConnectionCallback for each application to be served through the server. This object has only one responsibility: to construct a new application object (a user's object derived from the WebAppConnection base class) when a new unique visitor connects to the server.

Definition of Unique Visitor

  • WebSockets : A 'new unique visitor' for WebSockets means a 'new WebSocket' connection from a browser. The user's WebAppConnection -derived object exists as long as that JavaScript WebSocket object exists in the browser, and is deleted when that WebSocket is closed.
  • FastCGI : A 'new unique visitor' for FastCGI means the first XHR (XMLHttpRequest) (or in jQuery, "$.ajax", or in Angular, "$http") connection from a host with no "visitorId" cookie set or an unknown visitorId cookie. The user's WebAppConnection -derived continues to exist beyond the closure of that XHR connection for a period of time, to wait for the next XHR connection (since XHR connections will come and go for every message). When a new XHR connection arrives with the same visitorId cookie, it is attached to an existing WebAppConnection object if possible. The user's WebAppConnection object will be deleted if a period of time passes with no XHR connection attached to it.

XHR Usage notes

To use XHR with this library, there are a couple of rules. First, use GET methods in a long-polling technique to retrieve messages (server to browser), but do NOT use GET to send messages browser-to-server. Second, use POST to send browser-to-server, and do not expect the server to include any server-to-browser messages in the response.

Here is some Sample XHR Javascript code.

Internals

If you're interested in the internals of how this library works, read Internal Workings.