WASP Tutorial Archives

A new release of WASP, now with SSL/TLS support

| 0 Comments
We've just released a new version of WASP, our pluggable application server platform. This release is built with release 6.5.2 of The Server Framework and includes support for secure TCP connections using SSL/TLS via our SChannel Option pack.

Setting up a secure TCP endpoint with WASP is easy, simply add the Secure configuration option to the <EndPoint> node like this:
<?xml version="1.0" encoding="Windows-1252"?>
<Configuration>
  <WASP>
    <TCP>
      <Endpoints>
        <EndPoint
          Name="Echo Server"
          Port="5050"
          HandlerDLL="[CONFIG]\EchoServer.dll"
          Secure="true">
        </EndPoint>
      </Endpoints>
    </TCP>
  </WASP>
</Configuration>
This tells WASP to secure the endpoint using a default certificate called "Wasp" that is located in the "MY" certificate store. You can add a self signed test certificate using the standard Microsoft "make cert" utility, makecert.exe and a simple script which creates and installs the correct type of certificate can be downloaded from here.

if you do not want to use a certificate called "Wasp" in the "MY" certificate store then you can configure the certificate used by adding the StoreName, CertificateName and UseMachineStore config values.
<?xml version="1.0" encoding="Windows-1252"?>
<Configuration>
  <WASP>
    <TCP>
      <Endpoints>
        <EndPoint
          Name="Echo Server"
          Port="5050"
          HandlerDLL="[CONFIG]\EchoServer.dll"
          Secure="true"
          StoreName="OurSpecialStore"
          CertificateName="OurCertificate"
          UseMachineStore="true">
        </EndPoint>
      </Endpoints>
    </TCP>
  </WASP>
</Configuration>
Testing your new secure endpoint can be done using either our OpenSSL server test or our SChannel server test. These are example clients that ship with The Server Framework and that allow you to create thousands of concurrent connections and control how they send data to a server. This is an easy way to build a test system for your server as all of the complexity of managing and controlling the connections is done for you and you simply have to adjust the messages that are generated and how the response validation is done. The default message that is built is an network byte order integer length prefixed message and so this program can be used to stress test WASP with either of the first two example plugins that were discussed in the tutorial.

You can download the SChannelEchoServerTest program from here. See our for details of how to run this tool.

WASP command line options

| 0 Comments
As you've seen from some of the earlier tutorials, WASP has quite a few command line parameters that can change how it runs. You can run WASP as a normal executable or install it as a Windows Service. The complete set of command line options are displayed if you run WASP with /help or with an option that it doesn't understand but I thought I'd list them all here for completeness and so that I can explain in a little more detail what each one does. 

More complex message framing

| 0 Comments
So far the tutorials have focused on a simple length prefixed message type. This is probably the easiest message in the world to process, the message framing is very simple and there's hardly anything to do in your message framing DLL. Unfortunately not all protocols are this simple to parse. Another common real-world protocol is a line based protocol that is delimited by a terminating character, or characters. One such protocol is the POP3 protocol which works in terms of commands which are delimited by the CR LF sequence.

In this tutorial we'll explore how we can write a message framing plugin for CR LF terminated messages and use per connection user data to track our parsing state.

WASP's config file

| 0 Comments
As you have discovered if you've been following the tutorials, WASP is configured using an XML file.

This file can either live in the same directory as the WASP executable or, for when you're running WASP as a Windows Service, it can live in a place that is configured in the registry.

The file is pretty simple and we've covered most of the options in the various tutorials but there are some configuration options that we haven't touched on yet and it seems sensible to have one place to look for details of all of the options that you can configure in the config file. This blog post is the place!

WASP plugin entry points

| 0 Comments
By now you've probably taken a look inside of the WASP SDK header, WASPDLLEntryPoints.h and seen all of the various plugin entry points that you can export from your plugin. This tutorial will explain what each of them is for and how you use them and will present a simple plugin which uses all of the entry points and logs its actions to WASP's debug log.

WASP Server instances

| 0 Comments
A single WASP plugin can be loaded by multiple end points to provide the same server on multiple ports. A plugin could, for example, be configured on one end point to provide services to the internal network and on another end point to provide services to the internet. Alternatively, in later WASP releases, a single plugin may be used to provide services over an insecure link on one end point and via an SSL protected link on another.

To enable the plugin to distinguish between connections from a specific end point WASP supports the concept of server instances.

Calling WASP functions from your plugin DLL.

| 0 Comments
So far our simple example WASP plugins have all used OnReadCompletedEx() which gives you both an input and an output buffer and assumes that you generate a single response to each inbound message. It also assumes that you wont write more data than will fit in a single I/O buffer. Whilst this is suitable for some server designs it's quite restrictive. Most plugins will probably use a combination of OnReadCompleted() and the WASP callback function writeToConnection(). OnReadCompleted() only provides inbound data and writeToConnection() can be called to send any amount of data to any active connection and can be called by your plugin at any time.

WASP's thread pools

| 0 Comments
Way back in 2002 when I was developing ISO8583 servers for PayPoint I put together a two thread pool server design that has worked so well that many of the servers that I develop today still use variations on the original design. The main idea behind the design was that the threads that do the network I/O should never block and the threads that do the user work can block if they like. Since this work was being done before Windows Vista came along with it's changes to how overlapped I/O that was still pending when the thread that issued it exited, see here. The I/O threads were not allowed to exit. However, to handle peaks and troughs in demand and operations that could block for various lengths of time (due to database access) it was useful to be able to expand and contract the thread pool that did the actual work. This led to a design where we had a fixed sized pool of I/O threads and a variable sized pool of "business logic" threads. Dispatch to the business logic pool was via a thread safe queue (built using and I/O completion port) and the dispatch was two stage so that the dispatcher could determine when it needed to expand the pool to deal with more work. Due to way the intra-pool dispatch worked it was easy to instrument the server using performance counters so that support staff could easily visualise how heavily loaded the server was. 

WASP uses a variation on this design.
The simple echo server plugin that we developed in the earlier tutorial was easy to test using telnet as it simply echoed all data back to the client. The plugin which used simple message framing was less easy to test using telnet as you first needed to enter the correct bytes to specify a message length as an int in network byte order. 

Neither plugin was easy to stress test using telnet as you'd need lots of monkeys and lots of machines to simulate lots of users.

The Server Framework ships with an example client that allows you to create thousands of concurrent connections and control how they send data to a server. This is an easy way to build a test system for your server as all of the complexity of managing and controlling the connections is done for you and you simply have to adjust the messages that are generated and how the response validation is done. The default message that is built is an network byte order integer length prefixed message and so this program can be used to stress test WASP with either of the two example plugins that we've developed so far.

You can download the EchoServerTest program from here.
Most TCP servers deal with distinct messages whereas TCP itself deals in terms of a stream bytes. By default a single read from a TCP stream can return any number of bytes from 1 to the size of the buffer that you supplied. TCP knows nothing about your message structure. This is where message framing comes in. If the protocol that you are supporting has a concept of what constitutes a "message" then your protocol requires message framing. The simplest message framing is a length prefixed message where all messages start with a series of one, or more, bytes that convey the length of the message to the receiver. Another common message framing style is to have a terminating character, or characters, perhaps each message is terminated with a CR LF combination. Whatever your framing requirements WASP's message framing handlers can help.

The simplest plugin, examining EchoServer.dll

| 0 Comments
WASP plugins are, at present, native DLLs that expose a set of known entry points. The minimal plugin exposes a single entry point, either OnReadCompleted() or OnReadCompletedEx(). The entry points and other details that you need to build a plugin for WASP are detailed in the WASPDLLEntryPoint.h header file that ships in the SDK directory with WASP.

Automating WASP installation

| 0 Comments
As you will have noticed if you've been following along with the tutorials, WASP displays a message box when you successfully install an instance of the service or install the performance counters. This is less than ideal for automated installations and so you can add the /noMessages command line argument to these operations to give you an installation which does not require a user to acknowledge the message box. 

If you need to automate the installation of one or more instances of WASP and/or the performance counters you can using /noMessages.

Enabling and viewing WASP's performance counters

| 0 Comments
WASP can expose internal metrics using performance counters. These can then be viewed using the standard Windows performance monitoring tool, perfmon. WASP's performance counters allow you to see how your server is performing and the counters can be automatically monitored and integrated with the counters from other Windows services, such as SQL server, the base operating system or the CLR, to provide a fully integrated production monitoring system. 

Installation of performance counters is done once per machine rather than once per WASP instance and performance counters can be used and viewed both when WASP is running as a Windows Service and from the command line. You install the counters by running WASP from the command line with the /installCounters command line argument. As with installing WASP as a Windows Service, you will be prompted to elevate your credentials if you do not have the appropriate access rights on your account.

Running WASP as a Windows Service

| 0 Comments
In the last tutorial I showed you how to run WASP as a normal command line executable. This can be useful for testing and development and also for debugging but when you want to run WASP on a production machine you probably want to run it as a Windows Service.

Running as a Windows Service has the advantage that you don't need a user logged in to the machine to run WASP, you can also control it remotely using the Windows Service Control Manager application. 

To run WASP as a service you first need to install it as a service.

Checking for new versions of WASP

| 0 Comments
I've got quite a few plans for expanding the functionality that WASP provides. Ideally it should showcase all of the major options available with The Server Framework; so pretty soon I'll be adding UDP support, hosting plugins written in managed code, providing secure TCP connections using SSL, etc. Plus I'm sure that some bugs will be shaken out as users push the system in ways that I haven't anticipated and so haven't tested. So, expect there to be updates coming along.

WASP can automatically check for updates by reading a web page at www.ServerFramework.com. By default it does this once a week. You can disable this by adding a DisableUpdateCheck value to the instance node of your config file and setting it to "true". This will prevent WASP from automatically checking for updates. Alternatively you can change how often WASP checks by adding a CheckForUpdatesEvery value; valid values for this are "Day", "Week" and "Month".

WASP will remember if it's not up to date and remind you each time it starts, you can stop it doing this by adding a RemindOnStartIfNotUpToDate value to the instance node and setting it to "false".

All of the details of what the update check is doing and the results of the check are logged to the log file.

If you disable automatic update checks then you can check for updates manually by running WASP with the /checkForUpdates command line parameter. This will log the results to the log and display a message box telling you how things went. If you want to automate this process and run the test from a script then you can run WASP with /noMessages /checkForUpdates which will not display the message box and will return an exit code of 1 if an update is available and 0 if WASP is up to date.

During the update check WASP requests a web page, http://wasp.ServerFramework.com/WASP-LatestVersion.html with a user agent string that identifies the version of WASP that is making the call and the version of the operating system that it is running on.

Getting started with WASP

| 0 Comments
The easiest way to get started with WASP is to download the latest version from the download page, here, unzip the contents somewhere and then run the WASP executable, simply double click the executable in Explorer or navigate to the directory that you have installed WASP into and type "wasp". The result should be that a log file is created in a subdirectory of the directory where the exe is located called log. The contents of the log file will look something like this:

Follow us on Twitter: @ServerFramework

About this Archive

This page is an archive of recent entries in the WASP Tutorial category.

WASP is the previous category.

I usually write about the development of The Server Framework, a super scalable, high performance, C++, I/O Completion Port based framework for writing servers and clients on Windows platforms.

Find recent content on the main index or look in the archives to find all content.