1<link href="http://kevinburke.bitbucket.org/markdowncss/markdown.css" rel="stylesheet"></link>
2
3Header format for the THeader.h
4===============================
5
6      0 1 2 3 4 5 6 7 8 9 a b c d e f 0 1 2 3 4 5 6 7 8 9 a b c d e f
7    +----------------------------------------------------------------+
8    | 0|                          LENGTH                             |
9    +----------------------------------------------------------------+
10    | 0|       HEADER MAGIC          |            FLAGS              |
11    +----------------------------------------------------------------+
12    |                         SEQUENCE NUMBER                        |
13    +----------------------------------------------------------------+
14    | 0|     Header Size(/32)        | ...
15    +---------------------------------
16
17                      Header is of variable size:
18                       (and starts at offset 14)
19
20    +----------------------------------------------------------------+
21    |         PROTOCOL ID  (varint)  |   NUM TRANSFORMS (varint)     |
22    +----------------------------------------------------------------+
23    |      TRANSFORM 0 ID (varint)   |        TRANSFORM 0 DATA ...
24    +----------------------------------------------------------------+
25    |         ...                              ...                   |
26    +----------------------------------------------------------------+
27    |        INFO 0 ID (varint)      |       INFO 0  DATA ...
28    +----------------------------------------------------------------+
29    |         ...                              ...                   |
30    +----------------------------------------------------------------+
31    |                                                                |
32    |                              PAYLOAD                           |
33    |                                                                |
34    +----------------------------------------------------------------+
35
36The `LENGTH` field is 32 bits, and counts the remaining bytes in the
37packet, NOT including the length field.  The header size field is 16
38bits, and defines the size of the header remaining NOT including the
39`HEADER MAGIC`, `FLAGS`, `SEQUENCE NUMBER` and header size fields.  The
40Header size field is in bytes/4.
41
42The transform ID's are varints.  The data for each transform is
43defined by the transform ID in the code - no size is given in the
44header.  If a transform ID is specified from a client and the server
45doesn't know about the transform ID, an error MUST be returned as we
46don't know how to transform the data.
47
48Conversely, data in the info headers is ignorable.  This should only
49be things like timestamps, debugging tracing, etc.  Using the header
50size you should be able to skip this data and read the payload safely
51if you don't know the info ID.
52
53Info's should be oldest supported to newest supported order, so that
54if we read an info ID we don't support, none of the remaining info
55ID's will be supported either, and we can safely skip to the payload.
56
57Info ID's and transform ID's should share the same ID space.
58
59### PADDING:
60
61Header will be padded out to next 4-byte boundary with `0x00`.
62
63Max frame size is `0x3FFFFFFF`, which is slightly less than `HTTP_MAGIC`.
64This allows us to distinguish between different (older) transports.
65
66### Transform IDs:
67
68    ZLIB_TRANSFORM 0x01 - No data for this.  Use zlib to (de)compress the
69                          data.
70
71    HMAC_TRANSFORM 0x02 - Variable amount of mac data.  One byte to specify
72                          size. Mac data is appended at the end of the packet.
73    SNAPPY_TRANSFORM  0x03  - No data for this.  Use snappy to (de)compress the
74                          data.
75
76
77### Info IDs:
78
79    INFO_KEYVALUE 0x01 - varint32 number of headers.
80                       - key/value pairs of varstrings (varint16 length plus
81                         no-trailing-null string). Implementations MUST NOT
82                         alter either key or value in any way.
83
84