Getting started with WASP

2010-10-01

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:

8020: 14:29:53.619 -
8020: 14:29:53.619 - WASP - pluggable TCP/UDP server platform.
8020: 14:29:53.619 - Version: 6.2.103 [x64]
8020: 14:29:53.619 - (c) 2010 JetByte Limited
8020: 14:29:53.619 - Free for non-commercial use.
8020: 14:29:53.620 - See: http://www.ServerFramework.com for more details
8020: 14:29:53.620 -
8020: 14:29:53.620 - Current directory = C:\WASP
8020: 14:29:53.620 - Config File: C:\WASP\WASP.xml
8020: 14:29:53.620 - Loading configuration: "WASP" from file: C:\WASP\WASP.xml"
8020: 14:29:53.620 - CService::OnException() - Exception: LoadFileAsString() "C:\WASP\WASP.xml" - The system cannot find the file specified.
8020: 14:29:53.620 - WASP is shutting down...
8020: 14:29:53.620 - Shutting down endpoints
8020: 14:29:53.620 - Waiting 5 seconds for endpoints to shut down...
8020: 14:29:53.620 - Deleting objects...
8020: 14:29:53.620 - WASP has shut down.

The ‘8020:’ that starts each line in the log file above is simply the thread id of the thread that wrote the log message, this can be useful in some situations, it will likely change with each log produced. Next comes the timestamp of the log entry and finally the log detail itself.

WASP first logs details of the version and build that is running. Next it tells you where it’s running and where it expects to find its config file. It then attempts to load the config file and fails because it doesn’t exist. WASP then shuts down.

WASP is configured using an XML file called WASP.xml that lives in the config directory. In the example above the config directory is the current directory, but that isn’t always the case. For now we’ll assume that the config directory is the current working directory.

The simplest config file is as follows (you can download it from here):

<?xml version="1.0" encoding="Windows-1252"?>
<Configuration>
  <WASP>
    <TCP>
      <Endpoints>
        <EndPoint
          Name="Echo Server"
          Port="5050"
          HandlerDLL="[CONFIG]\EchoServer.dll">
        </EndPoint>
      </Endpoints>
    </TCP>
  </WASP>
</Configuration>

WASP works in terms of endpoints of which you can have many per instance of WASP. In the config file above we have a single endpoint which provides a server named “Echo Server” which listens on all of the machine’s TCP interfaces on port 5050. The server itself is implemented by a DLL called EchoServer.dll which lives in the config directory.

Since we don’t currently have the DLL in the config directory WASP again fails to start with the following log:

5152: 14:56:57.062 -
5152: 14:56:57.062 - WASP - pluggable TCP/UDP server platform.
5152: 14:56:57.062 - Version: 6.2.103 [x64]
5152: 14:56:57.062 - (c) 2010 JetByte Limited
5152: 14:56:57.062 - Free for non-commercial use.
5152: 14:56:57.062 - See: http://www.ServerFramework.com for more details
5152: 14:56:57.062 -
5152: 14:56:57.062 - Current directory = C:\WASP
5152: 14:56:57.062 - Config File: C:\WASP\WASP.xml
5152: 14:56:57.062 - Loading configuration: "WASP" from file: "C:\WASP\WASP.xml"
5152: 14:56:57.063 - Performance counters NOT enabled.
5152: 14:56:57.063 - IOPool - NumThreads: 2
5152: 14:56:57.063 - BufferSize: 4096
5152: 14:56:57.063 - BufferPoolSize: 10
5152: 14:56:57.063 - No Business Logic thread pool. All work will be done on the I/O threads.
5152: 14:56:57.063 - TCP SocketPoolSize: 10
5152: 14:56:57.063 - No connection limit.
5152: 14:56:57.063 - Configuring end point: "Echo Server"
5152: 14:56:57.063 - Address: 0.0.0.0
5152: 14:56:57.063 - Port: 5050
5152: 14:56:57.064 - NoDelay: false - (Nagle enabled)
5152: 14:56:57.064 - ListenBacklog: 150
5152: 14:56:57.064 - WARNING: No FramingDLL specified, data will be passed to your handler DLL as a stream of bytes as it arrives and will NOT be split into "messages".
5152: 14:56:57.064 - HandlerDLL: "C:\WASP\EchoServer.dll"
5152: 14:56:57.064 - HandlerConfig: ""
5152: 14:56:57.066 - CService::OnException() - Exception: CMemoryMappedFile::OpenFile() -"C:\WASP\EchoServer.dll" - The system cannot find the file specified.
5152: 14:56:57.066 - WASP is shutting down...
5152: 14:56:57.066 - Shutting down endpoints
5152: 14:56:57.066 - Waiting 5 seconds for endpoints to shut down...
5152: 14:56:57.066 - Shutting down I/O pool.
5152: 14:56:57.066 - Flushing buffer allocator.
5152: 14:56:57.066 - Flushing socket allocator.
5152: 14:56:57.066 - Deleting objects...
5152: 14:56:57.066 - WASP has shut down.

This log contains quite a lot more information, much of it we’ll explain in later tutorials. Right now the important part of the log for us is the following section:

5152: 14:56:57.063 - Configuring end point: "Echo Server"
5152: 14:56:57.063 - Address: 0.0.0.0
5152: 14:56:57.063 - Port: 5050
5152: 14:56:57.064 - NoDelay: false - (Nagle enabled)
5152: 14:56:57.064 - ListenBacklog: 150
5152: 14:56:57.064 - WARNING: No FramingDLL specified, data will be passed to your handler DLL as a stream of bytes as it arrives and will NOT be split into "messages".
5152: 14:56:57.064 - HandlerDLL: "C:\WASP\EchoServer.dll"
5152: 14:56:57.064 - HandlerConfig: ""
5152: 14:56:57.066 - CService::OnException() - Exception: CMemoryMappedFile::OpenFile() -"C:\WASP\EchoServer.dll" - The system cannot find the file specified.

This shows that we’re configuring an endpoint called “Echo Server” which listens on port 5050. Since we didn’t specify any other configuration options in the file we default some values, so we’re listening on the IPV4 ‘any’ address, Nagle is enabled and we have a listen backlog queue of 150 connections.

The warning tells us that we have not provided details of a DLL that will perform message framing and so every byte that arrives on the connection will be passed through to our handler DLL as it arrives and we’ll need to deal with breaking the byte stream into messages ourselves. The handler DLL is EchoServer.dll which is located in our config directory which is the same as where the executable lives, C:\WASP.

Finally we get an error because the DLL cannot be found. WASP then shuts down.

You can download a prebuild EchoServer.dll from here, be sure to use the same build as your build of WASP, either x86 or x64, don’t worry, you’ll get a helpful log message if you use the wrong type of DLL. Once the handler DLL is in the correct place you can start WASP and it will actually complete its start up sequence and run; well, you will if nothing else is already listening on the same port, if you get errors in the log about not being able to bind then change the value of Port in your config file to something that isn’t in use, use netstat -a to tell you the ports that are currently in use on your machine…

So, hopefully, you now have a WASP powered echo server running and the log file looks something like this:

7460: 15:58:45.372 -
7460: 15:58:45.372 - WASP - pluggable TCP/UDP server platform.
7460: 15:58:45.372 - Version: 6.2.103 [x64]
7460: 15:58:45.372 - (c) 2010 JetByte Limited
7460: 15:58:45.372 - Free for non-commercial use.
7460: 15:58:45.372 - See: http://www.ServerFramework.com for more details
7460: 15:58:45.372 -
7460: 15:58:45.372 - Current directory = C:\WASP
7460: 15:58:45.372 - Config File: C:\WASP\WASP.xml
7460: 15:58:45.372 - Loading configuration: "WASP" from file: "C:\WASP.xml"
7460: 15:58:45.372 - Performance counters NOT enabled.
7460: 15:58:45.373 - IOPool - NumThreads: 2
7460: 15:58:45.373 - BufferSize: 4096
7460: 15:58:45.373 - BufferPoolSize: 10
7460: 15:58:45.373 - No Business Logic thread pool. All work will be done on the I/O threads.
7460: 15:58:45.373 - TCP SocketPoolSize: 10
7460: 15:58:45.373 - No connection limit.
7460: 15:58:45.373 - Configuring end point: "Echo Server"
7460: 15:58:45.373 - Address: 0.0.0.0
7460: 15:58:45.373 - Port: 5050
7460: 15:58:45.374 - NoDelay: false - (Nagle enabled)
7460: 15:58:45.374 - ListenBacklog: 150
7460: 15:58:45.374 - WARNING: No FramingDLL specified, data will be passed to your handler DLL as a stream of bytes as it arrives and will NOT be split into "messages".
7460: 15:58:45.374 - HandlerDLL: "C:\WASP\EchoServer.dll"
7460: 15:58:45.374 - HandlerConfig: ""
7460: 15:58:45.378 - Connection handling dll Loaded: "C:\WASP\EchoServer.dll"
7460: 15:58:45.378 - Optional entry points:
7460: 15:58:45.378 -               Initialise: No
7460: 15:58:45.378 -  OnConnectionEstablished: No
7460: 15:58:45.378 -          OnReadCompleted: No
7460: 15:58:45.378 -        OnReadCompletedEx: Yes
7460: 15:58:45.378 - OnConnectionClientClosed: No
7460: 15:58:45.378 -        OnConnectionReset: No
7460: 15:58:45.378 -       OnConnectionClosed: No
7460: 15:58:45.378 -     OnConnectionComplete: No
7460: 15:58:45.378 -      OnShutdownInitiated: No
7460: 15:58:45.378 -                 Shutdown: No
7460: 15:58:45.378 - Starting Endpoints
7460: 15:58:45.378 - WASP is running...
7460: 15:58:45.387 - WASP is accepting connections

Once again, the important section of this log is this bit:

7460: 15:58:45.378 - Optional entry points:
7460: 15:58:45.378 -               Initialise: No
7460: 15:58:45.378 -  OnConnectionEstablished: No
7460: 15:58:45.378 -          OnReadCompleted: No
7460: 15:58:45.378 -        OnReadCompletedEx: Yes
7460: 15:58:45.378 - OnConnectionClientClosed: No
7460: 15:58:45.378 -        OnConnectionReset: No
7460: 15:58:45.378 -       OnConnectionClosed: No
7460: 15:58:45.378 -     OnConnectionComplete: No
7460: 15:58:45.378 -      OnShutdownInitiated: No
7460: 15:58:45.378 -                 Shutdown: No

This shows us which DLL entry points the handler DLL exports. This simple handler exports only one function, OnReadCompletedEx(). Either this or OnReadCompleted() MUST be exported for a DLL to be usable as a handler DLL, all of the other entrypoints are optional.

You can test your WASP using telnet, simply open a command prompt and run up telnet to connect to localhost on port 5050 and type stuff. The stuff that you type will be echoed back to you. Note that since telnet might also echo the data you send you’ll likely see two copies of each character that you type.

You can ask WASP to stop accepting new connections, but to continue to process the existing ones by running WASP again from the command line and passing the /pause command line switch to it. The log will show that WASP is no longer accepting connections and a new telnet connection will fail. You can ask WASP to begin accepting connections again by calling it with /pause for a second time, again the log will show what’s going on.

When you want WASP to shut down you can request a clean shutdown from the command line by running WASP with the /stop command line argument. All existing connections will be terminated and WASP will shut down.

WASP can also run as a Windows Service but we’ll deal with that in the next tutorial. When running as a Windows Service the command line controls cannot be used. Instead you can control the service using the Service Control Manager in the usual way.