sdsu 1.0.0

Skim milk. Gummy bears. Pure genius.

Skim milk. Gummy bears. Pure genius.

Contents

• Quick Start

• Overview

• securityRoot

• staticRoot

• wssHandlerCls

• WebSocket Client

Quick Start

> python -c "import sdsu; sdsu.main()"

Note that, for Tornado-based servers, Windows users stop the service using CRTL + PAUSE/BREAK.

Overview

The Secure, Dual-use Server Utility, or SDSU, provides:

• A preconfigured, multi-handler, Tornado-based web server

• Static file hosting from the /static subdirectory

• SSL encryption using the certificates stored in /security

• Login protection (including address whitelisting) from the credentials in /security

• Secure WebSocket exchange on the same port service as static file hosting, using the /wss path.

The sdsu.main() method takes three parameters that allow users to customize the configuration of a SDSU server before it launches: securityRoot, staticRoot, and wssHandlerCls.

securityRoot

By default, the /security subdirectory contains three files:

• certificate.pem defines the server’s SSL certificate

• credentials.csv defines the user table. Each user is defined by an email address (“email”), password (“password”), and whitelist mask (CIDR-style, IPv6 preferred but IPv4 will be translated automatically with a “2002:” prefix.) Password and whitelist mask will be used by the SplashHandler.post() method when verifying credential submissions.

• key.pem defines the server’s private SSL key.

Users can customize security configurations by creating a new copy of this directory, modifying it’s contents, and passing the new absolute path to sdsu.main() as the securityRoot parameter. For example, you are strongly encouraged to use your own certificates.

staticRoot

The /static subdirectory contains static files that will be served to satisfy HTTP requests. Except for splash.html, all static files are protected by authentication restrictions. Default contents of /static include:

• index.css, a stylesheet used by index.html and placed here to demonstrate and verify protection of static file contents.

• index.html, the default landing page for authenticated users.

• splash.html, which defines the login page for users that have not yet been authenticated. This also serves as a logout page, as upon accessing this resource any existing sessions are cleared.

Users can customize static file contents (and therefore the bulk of their web applications) by creating a new copy of this directory, modifying it’s contents, and passing the new absolute path to sdsu.main() as the staticRoot parameter.

wssHandlerCls

The class sdsu.WssHandler defines the default behavior for secure WebSocket interaction mounted by the server to the path “/wss”. Users can customize WebSocket behaviors by inheriting from this class, then pass the new child class to sdsu.main() as the wssHandlerCls parameter. Typical usage will override one or more of the following methods:

• on_open()

• on_message() (by default, simply echoes the message back to the client)

• on_close()

See class method documentation for more details, including method signatures. Keep in mind that each instance of the WebSocker handler class is unique to a specific client connection; state is not shared between clients.

WebSocket Client

Once a server is running, connection via WebSocket is trivial:

> var wss = new WebSocket("wss://" + window.location.host + "/wss");
> wss.addEventListener("message", console.log);
> wss.send("0");