WebSocket Server

Overview

This tutorial demonstrates how Mongoose Library can be used to implement a WebSocket server that does the following:

Starts a listening HTTP server on port 8000
The /websocket URL serves a WebSocket echo server
The /rest URL serves a RESTful server by responding with JSON string {"result": 123}
Any other URI serves static files from the current directory

Full source code for this tutorial is at https://github.com/cesanta/mongoose/tree/master/tutorials/websocket/websocket-server

Build and test

Follow the Build Tools to setup your development environment. Then start command prompt / terminal, clone Mongoose repository and build the example:

git clone https://github.com/cesanta/mongoose
cd mongoose/tutorials/websocket/websocket-server
make
...
Starting WS listener on ws://localhost:8000/websocket

Start your browser on URL http://localhost:8000 - and you should see a directory listing. That's the static web server working:

Now change the URL to http://localhost:8000/rest - and you should see an output from the RESTful handler:

Now it's time to test a websocket server. In your browser, enter the URL http://localhost:8000/test.html:

Click on "Connect" button. In the textarea input field, type "hello" and click on "Send". You should see that message echoed back:

How it works

A WebSocket server is basically a regular HTTP server which at some point switches protocol from HTTP to WebSocket. In main() we set up a regular HTTP server:

And the secret sauce of turning HTTP server into a websocket server is in the event handler function:

There, we check the requested URI. If it is equal to /websocket, then we call an API function mg_ws_upgrade(). It turns HTTP connection to a WebSocket connection. WebSocket connection is full duplex, i.e. messages can be sent at any point by any side of the connection. Mongoose fires MG_EV_WS_MSG event when a message is received.

In this example, we catch incoming messages and echo them back:

Mongoose handles receiving fragmented WebSocket messages for you, there is no need to check the F flag.

TLS support (WSS)

A Secure WebSocket server is an upgraded HTTPS server, a TLS connection is first established, then the HTTPS connection is upgraded to a WSS connection. For more information on developing TLS servers, check the TLS tutorial You can follow the HTTP Server tutorial for guidance

WebSocket broadcast

In some timed applications or one-to-many scenarios, it is common to need to send notifications or messages that have to be broadcast to all connected clients. You can find examples on how to do this in the timers tutorial and the multithreading one-to-many tutorial. The procedure is as follows:

For each incoming request, we upgrade the connection and 'mark' it to identify it as a listener to whom we'll send data in due time.

When we need to send data, we scan all connections searching for our 'mark' and replicate the data to them