| Marc Slemko | 03eafbe | 2006-08-02 20:01:22 +0000 | [diff] [blame] | 1 | This is the BNF for the Thrift wire protocol. Wire-protocol encoder/decoders must provide methods to encode/decode all the terminals in this BNF. The BNF is designed to allow for both binary and ascii encodings, including XML encodings. The latter requirement necessitates breaking all logical message components into header and body as well as delimiting beginning and end of each component. In this was it is possible to represent a component as a start tag (component bebug) with attributes (component-header) some arbitray number of child elements, and end tag (component end). |
| 2 | |
| 3 | For binary formats it is typically not necessary to represent the begin and end of component on the wire. The only time the driver expects variable input is for field lists. Field lists are terminated with the special STOP field. Thus, the driver always knows what component to expect next. Thus binary formats can dispence with component start and end delimiters. |
| 4 | |
| 5 | """ General message format """ |
| 6 | |
| 7 | message-stream : message-stream message | NIL |
| 8 | message : MSG_b message-header message-body MSG_e |
| 9 | message-header : MSGH_b protocol-version sequence-number message-type MSGH_e |
| 10 | protocol-version : protocol-version-major protocol-version-minor |
| 11 | protocol-version-major : UINT08 |
| 12 | protocol-version-minor : UINT08 |
| 13 | sequence-number : UINT32 |
| 14 | message-type : INVOKE | REPLY |
| 15 | |
| 16 | message-body : invoke-body | reply-body |
| 17 | |
| 18 | """ service function invoke message body """ |
| 19 | |
| 20 | invoke-body : function-specifier arguments |
| 21 | |
| 22 | function-specifier : service-qname function-name |
| 23 | service-qname : package-name service-name |
| 24 | function-name : STRING |
| 25 | package-name : STRING |
| 26 | service-name : STRING |
| 27 | |
| 28 | arguments : ARGS_b arg-list ARGS_e |
| 29 | arg-list : arg-list arg | NIL |
| 30 | arg : ARG_b arg-identifier arg-value ARG_e |
| 31 | arg-identifier : arg-name | arg-id | arg-name arg-id |
| 32 | arg-name : STRING |
| 33 | arg-id : UINT32 |
| 34 | arg-value : datum |
| 35 | |
| 36 | """ service function reply message body """ |
| 37 | |
| 38 | reply-body : in-reply-to-id result |
| 39 | |
| 40 | result : RES_b result-header result-body RES_e |
| 41 | |
| 42 | result-header : RESH_b result-type RESH_e |
| 43 | |
| 44 | result-type : RES_NORMAL | RES_ERROR | RES_IOERROR |
| 45 | |
| 46 | result-body : normal-result-body | error-result-body |
| 47 | |
| 48 | normal-result-body : RESB_b datum RESB_e |
| 49 | |
| 50 | error-result-body : RESB_b datum RESB_e // error datum is constrained to be derived from some exception type |
| 51 | |
| 52 | """ wire representation of simple, collection and composite data """ |
| 53 | |
| 54 | datum : DATUM_b datum-header datum-body DATUM_e |
| 55 | datum-header : DATUMH_b type-specifier datum-identifier DATUMH_e |
| 56 | type-specifier : simple-type-specifier | complex-type-specifier |
| 57 | |
| 58 | datum-identifier : datum-qname | datum-id | datum-name datum-id |
| 59 | |
| 60 | datum-qname : package-name datum-name |
| 61 | datum-name : STRING |
| 62 | datum-id : UINT32 |
| 63 | datum-body : DATUMB_b simple-datum | collection-datum | struct-datum DATUMB_e |
| 64 | |
| 65 | """ simple datum """ |
| 66 | |
| 67 | simple-type-specifier : I08 | I16 | I32 | I64 | U08 | U16 | U32 | U64 | STRING | UTF8 | UTF16 | FLOAT | BOOL | STOP |
| 68 | |
| 69 | simple-data : simple-data simple-datum | NIL |
| 70 | |
| 71 | simple-datum : bool-datum | |
| 72 | i08-datum | i16-datum | i32-datum | i64-datum | |
| 73 | u08-datum | u16b-datum | u32-datum | u64-datum | |
| 74 | string-datum | utf7-datum | utf8-datum | utf16-datum // string and utf7 are equivalent |
| 75 | |
| 76 | """ Complex data """ |
| 77 | |
| 78 | complex-type-specifier collection-type-specifier | struct-type-specifier |
| 79 | |
| 80 | """ collection datum """ |
| 81 | |
| 82 | collection-type-specifier : ARRAY | MAP | SET | LIST |
| 83 | |
| 84 | collection-datum : list-datum | set-datum | map-datum |
| 85 | |
| 86 | array-datum : simple-array-datum | complex-array-datum |
| 87 | |
| 88 | simple-array-datum : ARRAY_b element-count simple-type-specifier simple-data ARRAY_e |
| 89 | |
| 90 | complex-array-datum : ARRAY_b element-count simple-type-specifier simple-data ARRAY_e |
| 91 | |
| 92 | list-datum : LIST_b element-count element-type-specifier elements LIST_e |
| 93 | |
| 94 | element-count : UINT32 |
| 95 | |
| 96 | element-type-specifier : type-specifier |
| 97 | |
| 98 | elements : elements element | NIL |
| 99 | |
| 100 | element : datum |
| 101 | |
| 102 | set-datum : SET_b element-count element-type-specifier elements SET_e |
| 103 | |
| 104 | map-datum : MAP_b element-count map-key-type-specifier map-value-type-specifier map-pairs MAP_e |
| 105 | |
| 106 | map-key-type-specifier : type-specifier |
| 107 | |
| 108 | map-value-type-specifier : type-specifier |
| 109 | |
| 110 | map-pairs : map-pairs map-pair | NIL |
| 111 | |
| 112 | map-pair : MAPP_b key-datum value-datum MAPP_e |
| 113 | |
| 114 | """ struct datum """ |
| 115 | |
| 116 | struct-type-specifier : STRUCT |
| 117 | |
| 118 | struct-datum : STRUCT_b field-list STRUCT_e |
| 119 | |
| 120 | field-list : fields terminal-field |
| 121 | |
| 122 | fields : fields field | NIL |
| 123 | |
| 124 | field : datum |
| 125 | |
| 126 | terminal-field : datum // Datum type is STOP |
| 127 | |
| 128 | |
| 129 | |