| Dave Watson | 792db4e | 2015-01-16 11:22:01 -0800 | [diff] [blame] | 1 | <link href="http://kevinburke.bitbucket.org/markdowncss/markdown.css" rel="stylesheet"></link> |
| 2 | |
| 3 | Header 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 | |
| 36 | The `LENGTH` field is 32 bits, and counts the remaining bytes in the |
| 37 | packet, NOT including the length field. The header size field is 16 |
| 38 | bits, and defines the size of the header remaining NOT including the |
| 39 | `HEADER MAGIC`, `FLAGS`, `SEQUENCE NUMBER` and header size fields. The |
| 40 | Header size field is in bytes/4. |
| 41 | |
| 42 | The transform ID's are varints. The data for each transform is |
| 43 | defined by the transform ID in the code - no size is given in the |
| 44 | header. If a transform ID is specified from a client and the server |
| 45 | doesn't know about the transform ID, an error MUST be returned as we |
| 46 | don't know how to transform the data. |
| 47 | |
| 48 | Conversely, data in the info headers is ignorable. This should only |
| 49 | be things like timestamps, debuging tracing, etc. Using the header |
| 50 | size you should be able to skip this data and read the payload safely |
| 51 | if you don't know the info ID. |
| 52 | |
| 53 | Info's should be oldest supported to newest supported order, so that |
| 54 | if we read an info ID we don't support, none of the remaining info |
| 55 | ID's will be supported either, and we can safely skip to the payload. |
| 56 | |
| 57 | Info ID's and transform ID's should share the same ID space. |
| 58 | |
| 59 | ### PADDING: |
| 60 | |
| 61 | Header will be padded out to next 4-byte boundary with `0x00`. |
| 62 | |
| 63 | Max frame size is `0x3FFFFFFF`, which is slightly less than `HTTP_MAGIC`. |
| 64 | This allows us to distingush 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). |
| 82 | |