Quassel IRC

h1. Protocol Buffers

"Google Protocol Buffers":http://code.google.com/apis/protocolbuffers/ is an open binary serialization format created by Google.

This page describes an attempt to create an alternate language and platform neutral protocol for Quassel using the Protocol Buffers format.

The initial plan was to use JSON for an alternate protocol, but using Protocol Buffers has some distinct advantages, so this is the successor of that idea.

h2. Why Protocol Buffers?

??

Protocol buffers are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data – *think XML, but smaller, faster, and simpler*

??

Protocol buffers are not just a format definition, but also include code generation for many different languages.

This offers several advantages, one being a absolutely clear defined, self-describing protocol, instead of protocol based on conventions and possibly outdated documentation.

Additionally, protocol buffers are a binary protocol, with highly optimized implementations in several languages. Official support by Google for C++, Java and Python, as well as third party extension for many other popular languages, including PHP, Obj-C, Perl, JS, and many more.

h2. Current State

Work is currently in progress for supporting alternative protocols, i.e. something else besides QDataStream serialization. This requires lots of refactoring first in order to abstract everything away properly.

Once this work is done, we'll look into offering something based on Protocol Buffers.

**Note that the information in the following sections is completely outdated and not in any way resembling the future implementation!**

Well just keep it here for now for reference.

h2. Protocol Definition

Note: The protocol is still being actively worked on.

The outlined protocol definitions are not final, and just listed here for documentation.

h3. Message Container

Every Message has to be wrapped in a container, since we otherwise can't determine the message type. This is done by the "QuasselServerMessage" and "QuasselClientMessage" message types. This design is modeled around the Protocol Buffers "Union Types":http://code.google.com/apis/protocolbuffers/docs/techniques.html#union example.

QuasselServerMessage are messages the server sends, while QuasselClientMessage are messages the client sends.

<pre>

message QuasselServerMessage {

  enum MessageType {

    ERROR = 0,         // Generic message for errors

    SUCCESS = 1,       // Generic message for success

    SESSION_STATE = 2, // State of current session, sent after init

    ...

  }

  required MessageType type = 1;

  optional ErrorMessage errorMessage = 100;

  optional SuccessMessage successMessage = 101;

  optional SessionState sessionState = 102;

  ...

}

</pre>

<pre>

message QuasselClientMessage {

  enum MessageType {

    REQUEST = 0,       // Generic Request message (request init, request login, request backlog, etc..)

    ...

  }

  required MessageType type = 1;

  optional RequestMessage request = 2;

  ...

}

</pre>

Once the protocol is better defined, the full protocol files will be available here.