A library for quickly building smtp/memcache protocol style RPC servers and clients
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


MindTouch.Clacks 0.3

A library for quickly building smtp/memcache protocol style clients and servers

Build status


Apache 2.0

What's this for?

If you want to build a fast RPC server that uses a simple ASCII/Binary protocol with persistent connections like those used by memcache, smtp, beanstalkd, this is your toolkit. It handles all the network issues and lets you just define commands and responses you support and expose them in a client that supports connection pooling.

There is nothing tying the client and server libraries together, so if you wanted to write a client for some other server using this style of protocol, the client portion will make your life that much easier.

And if you want to implement the server and let other create clients in other languages, the protocol is just ASCII and bytes over TCP, so your .NET based server is easily accessed by any other language

So what's this ASCII/Binary protocol?

The protcol style, pioneered by SMTP and used by such lightweight RPC servers as memcached and beanstalkd, runs over TCP using ASCII encoding. Clients connect, send commands and data, wait for responses, and close the connection. Commands are processed serially per connection, allowing a single connection to send/receive many commands.

The protocol contains two kinds of data: Text lines and byte blobs. Text lines are white-space separated ASCII encoded commands of the format:


Where CMD is the command name, followed by 0 or more ARGs and optinionally followed by the number of bytes to expect in a following byte blob. If the command specifies a trailing BYTECOUNT argument, the server expects the following line to be of the format:


Where BYTES is BYTECOUNT bytes followed by a line terminator.

Responses use the identical format, except that the first element of the Text line is considered a status code.


MindTouch.Clacks is fully functional providing both a synchronous and asynchronous server. It's currently undergoing real world testing before we lock down the API and write documentation.


  • Need timeouts and error propagation in async handlers (consider Task dependency?)
  • Need way to register other than last argument as bytecount
  • Would be nice to add an Async Client (again, Task dependency?)


Both client and server libraries are meant for containment, i.e. the plumbing for your own abstraction of the protocol rather than raw usage, although there is nothing about the code that enforces such a design decision

Creating a server that can echo arguments :: // build server var server = ServerBuilder .CreateAsync(new IPEndPoint("", 12345)) .WithCommand("ECHO") .HandledBy((request, response) => response(Response.Create("ECHO").WithArguments(request.Arguments)) ) .Register(); .Build();

// Run the server until you press enter
using(server) {

Calling the server to echo some arguments :: // create a client (uses default connection pool using(var client = new ClacksClient(", 12345)) { var response = client.Exec( Request.Create("ECHO") .WithArgument("hi") .WithArgument("there") ); Console.Writeline("Server echoed: {0}", string.join(" ", response.Arguments); }


  • Arne F. Claassen (sdether)
  • Corey Coto (coreycoto)