binary protocol notes from the facebook hackathon

[Marc]

Bear in mind that the magic-version byte is actually
magic-version-command/response byte.  That is, one bit there indicates
whether the message contains a command or reply.  So, we had a very uniform
message header:
 
    <mvC><cmd><keylen><res><oid><blen>
    <mvR><cmd><result><res><oid><blen>

This is nice both for line analyzers and things like mcproxy and other
bridges that need to deal with flows in both directions and for quickly
testing for normal or error processing.

Concerning changing commands -  I think we all prefer to see new commands
defined when they are needed rather than adding a lot of 'for-future-use'
gunk.  

The reserved byte in the header got stuck there because we originally
thought we might want some optional flags and since the alignment was so
serendipitous it was a no-brainer.  Putting it at the end buys nothing,
since the intention is for future-header flags and thus not very useful if
the entire message must be read to see it.

On 7/11/07 1:25 AM, "Clint Webb" <webb.clint at gmail.com> wrote:

> I agree.  Thats one thing I noticed about the protocol when I was reading my
> email on the train this morning.
> 
> Keeping the original structure would make it difficult to change the
> fixed-width parameters given to a command.
> 
> Having an offset would mean that the key can be found much easier.  However,
> care should be taken that the offset given doesnt go out of the bounds of the
> message.  I'm not in total favour of an offset either, because in this case,
> you're basically moving the calculation from the server to the client.
> 
> What I prefer is:
>  * Magic byte / version
>  * Cmd byte
>  * 4 byte opaque id.
>  * Key len byte  (if no key, 0)
>  * key, if key length above is non-zero.
>  * 4 byte body length (not including reserved byte at the end)
>  * [ cmd-specific fixed-width fields ]
>  * [ cmd-specific variable-width field ]
>  * Reserved byte (should be 0)
> 
> What I additionally prefer, is a total packet length after the magic byte, but
> that might meet substantially more debate.
> 
> Note: I'm assuming that all variable length fields will have a representative
> length byte(s) somewhere in the protocol before it.
> 
> On 7/11/07, Dustin Sallings <dustin at spy.net> wrote:
>> 
>> On Jul 10, 2007, at 9:23, Brad Fitzpatrick wrote:
>> 
>>> REQUEST STRUCTURE:
>>> 
>>>   * Magic byte / version
>>>   * Cmd byte
>>>   * Key len byte  (if no key, 0)
>>>   * Reserved byte (should be 0)
>>> 
>>>   * 4 byte opaque id.  (will be copied back in response; means
>>> nothing to server)
>>> 
>>>   * 4 byte body length (network order; not including 12 byte header)
>>> 
>>>   [ cmd-specific fixed-width fields ]
>>> 
>>>   * key, if key length above is non-zero.
>>> 
>>>   [ cmd-specific variable-width field ]
>> 
>>         I found a problem when implementing this.  Given the above
>> structure, we always know the length of a key, but we can't know the
>> location of a key unless we know how to process the given command.
>> 
>>         I don't know that this is a huge problem, but it thwarted some of my
>> generic lower-level packet handling code in my test server.
>> 
>>         Perhaps we could resurrect the reserved byte and use it as a fixed-
>> field word (or byte) count?  I remember this coming up in the
>> discussion, but I think we decided it was redundant as the command
>> should know what its headers are.
>> 
>>         Any opinions?
>> 
>> --
>> Dustin Sallings
>> 
>> 
> 
>