Maintaining backward-forward compatibility of your own Client-Server protocol

When you are integrating your client with well-known interfaces, protocols are quite clear (well, at least they should be). Whether your server is an HTTP server, COM interface or even just a Windows DLL with exported functions, you know how to communicate with the server just by looking at the documentation (e.g. HTTP protocol, MSDN). We know that if documentation declares a specific interface/protocol, it must stand behind it. Although it sounds obvious, when we develop our own custom Client-Server protocol, we sometimes miss this point. HTTP client-server is something too obvious. But there are many more we are creating. Let’s not think about them as client-server, but more as consumer-producer components. Take these examples –

  • Dll_A (client) calls exported functions in Dll_B (server)
  • Process_A (client) collects information from Process_B (server) over IPC
  • A user-space module (client) sends information to a kernel module (server)
  • Client sends a packet to server

–          All must work with a predefined interface. In order to make your client to work with the server properly, you must define a protocol that is known to both of them. The simple and best way to do it in order to minimize the chances of bugs is that both will use the exact same protocol definition files. Whether this is a header (.h) file, an xml file, an ini file – you name it, having both the client and server (or consumer and producer) use the same file means they both “speak” the same language. Consider the following protocol definition –

enum {

struct {
    EConfigParams eConfigParam,
    void* pData

The EConfigParams enum declares an interface between two components and SConfigMessage will be a generic message structure sent from client to server which can be one of two declared messages. Since SConfigMessage contains the EConfigParams enum and a void pointer it is very generic and can be expanded for many other usages (new protocol messages). Client code will look like this:

//Send enable message
SPConfigMessage configMessage = {eConfigEnable, NULL};
//Send name message
SPConfigMessage configMessage = {eConfigName, “MyName”};

Server code will look like this:

void receive(SConfigMessage* configMessage)
    if (configMessage == NULL)

    switch (configMessage->eConfigParam)
        case eConfigEnable: enable(); break;
        case eConfigName:   setName((char*)configMessage->pData)); break;

This is pretty straight forward. Client sends a message, and as a result server calls enable() or setName() according to the enum value declared in the protocol. Now we need to add a new feature that should make the server to call disable() function. Usually we add an enum value as the last value (good practice) but sometimes we add it in the place where it is more in context. In our example, having an enum value of eConfigDisable makes sense to be next to (before/after) eConfigEnable (this is risky!). Consider we are taking this approach, the enum will look like this:

enum {
    eConfigDisable, //This is new!

//Send disable message
SPConfigMessage configMessage = {eConfigDisable, NULL};

The server will have a new case for eConfigDisable

case eConfigDisable: disable(); break;

In order to test your code you rebuild both your client and your server and perform a test. You reproduce eConfigDisable message scenario and noticed that client sends the right message and server calls the disable() function as expected. You even make sure no degradation exists after these changes by checking all other possible messages in the protocol – enable() and setName(). Both work as expected. Well, it seems like everything is working just fine but it may not. If there is even the slightest chance that your client code can be released to your customers without releasing the server as well, you are in a high risk of unexpected behavior at server side. If your client and your server are always being released together, not separated, not patched – there is no risk. So, where is the risk? After changing the enum to include eConfigDisable, the enum values after this value have changed. So eConfigName value was changed from 1 to 2. When you rebuild both your server and client you’re all good, but what happens when you update just your client? Or just your server? Backward-forward compatibility here will be harmed. Let’s take a look:


enum values

When client sends a message




Old client + New server Client – 0 = eConfigEnable 1 = eConfigName Server – 0 = eConfigEnable 1 = eConfigDisable 2 = eConfigName No impact (value remains 0) No impact (client does not support eConfigDisable) Client will send ‘1’ Server will treat it as eConfigDisable
New client + Old server Client – 0 = eConfigEnable 1 = eConfigDisable 2 = eConfigName Server – 0 = eConfigEnable 1 = eConfigName No impact (value remains 0) Client will send ‘1’ Server was supposed to ignore unknown values (eConfigDisable) but will treat it as eConfigName POTENTIAL CRASH!! Client will send ‘2’ Server will ignore it (while it actually supports eConfigName)

The above table shows states where your client and server ‘speak’ different languages, different protocols. Client sends A but server treats it as B. The good case is that an operation will be ignored. The worst case (which is very likely to happen) is an unexpected behavior at server side which can easily lead to a crash. Just think of the simple situation where you are using a new client, an old server and client sends eConfigDisable. Server treats it as eConfigName (since both values are 1) and server access the pData pointer while actually the pointer’s value is NULL. In this simple example it may not be a big deal, but in cases where pData points to structure A in client and server will treat it as structure B, crashes are very likely to happen. Once again, just to clarify the most important point here – This invalid state of Client-Server protocol mismatch can happen only when they are not released to your customer together in 100% of the times. Different installers, patches or components updates can lead to this invalid state quite easily. Solution: How can we deal with such cases? How to avoid getting into this invalid state in products that are not tight together into one installer or are sometimes being patched/updated? Solutions that may help but won’t solve the issue:

  • Adding the last value of an enum “NUMBER_OF_WHATEVER”. This is just bad practice.
  • Hardcoding enum values.
  • Manual code reviews each time the protocol changes
  • Documentation of the enum/structure that must remain consistent. For example: like: “Don’t change values” / “Don’t touch here” / “Contact me for any change” / lots of exclamation marks / etc.

All of the solutions above may help a bit but still will not keep you safe of errors. The ideal solution will keep your code repository server free of such issues the whole time. In order to achieve this we need:

  • To be able to run a ‘diff’ between two protocol definition files and catch risky changes.
  • Automatic execution of this diff between code that is committed to your repository server and the existing code.
  • To block the commit upon error resulting from the ‘diff’.

The repository server I usually work with is TortoiseSVN, so I’ve created scripts in order to deal with such tricky cases. The idea is to deploy a pre-commit hook to SVN, so whenever a developer commits code to your SVN repository server, all protocol definition files will be checked for risky changes and if a risk was found, commit will fail. This way you keep your repository server safe in an automated procedure. Stay tuned for the scripts! Whether you are using this script or not, here are my guidelines for how to keep your client-server protocol consistent:

  • Protocol declarations (defined values, enums, structs) documentation should be very clear and with well-known high risk. Values, order and structure can be very risky
  • Use code analysis to ensure you keep your backward-forward compatibility
  • Take manual code reviews on high-risk definition files
  • Use automation

Leave a Reply

Your email address will not be published.