Skip to content
This repository
Konstantin Osipov April 14, 2014
file 283 lines (240 sloc) 9.745 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282
; Tarantool IPROTO protocol.
; ======================
;
; The latest version of this document can be found in
; Tarantool source tree, doc/box-protocol.txt
;
; IPROTO is a binary request/response protocol.
; The server begins the dialogue by sending a fixed-size (128 bytes)
; text greeting to the client. The first 64 bytes of the greeting
; contain server version. The second 64 bytes contain a base64-
; encoded random string, to use in authentification packet.

; Once a greeting is read, the protocol becomes pure
; request/response and features a complete access to Tarantool
; functionality, including:
; - request multiplexing, e.g. ability to asynchronously issue
; multiple requests via the same connection
; - response format that supports zero-copy writes
;
; For data structuring and encoding, the protocol uses msgpack
; data format, see http://msgpack.org
;
; Since msgpack uses a variable representation for compound
; data structures, such as arrays and maps, the exact byte
; sequence mandated by msgpack format is omitted in this spec.
; This spec therefore only defines the expected **schema**
; of msgpack streams.
;
; To specify that a msgpack map is expected in the stream,
; the contents of the map is put into "{}" (curly braces).
;
; To specify that a msgpack array is expected in the stream,
; the contents of the array is put into "[]" (square brackets).
;
; A single key-value pair in a map is separated by a ":" (semicolon),
; values of a map or array are separated by "," (comma).
;
; Tarantool protocol mandates use of a few integer constants
; serving as keys in maps used in the protocol. These constants are
; defined in
; https://github.com/tarantool/tarantool/blob/master/src/iproto_constants.h
;
; Let's list them here too:
;

<code> ::= 0x00
<sync> ::= 0x01
<space_id> ::= 0x10
<index_id> ::= 0x11
<limit> ::= 0x12
<offset> ::= 0x13
<iterator> ::= 0x14
<key> ::= 0x20
<tuple> ::= 0x21
<function_name> ::= 0x22
<data> ::= 0x30
<error> ::= 0x31

;
; The value of the constant defines the type of value of the map.
; For example, for <error> key (0x31), the expected value is a
; msgpack string with error message.
; All requests and responses utilize the same basic structure

<packet> ::= <request> | <response>
<request> ::= <len><header><body>
<response> ::= <len><header><body>
; <len> is the length of the packet, in msgpack format.
;
; Implementor note: for simplicity of the implementation,
; the server never "compresses" the packet length, i.e.
; it is always passed as msgpack 32-bit unsigned int,
; 0xce b4 b3 b2 b1 (5 bytes)
;
<len> ::= msgpack Int (unsigned)
;
; Both <header> and <body> are msgpack maps:

<header> ::= { (<key> : <value>)+ }
<body> ::= { (<key> : <value>)+ }

; They only differ in the allowed set of keys and values,
; The key defines the type of value that follows.
; If a key is missing, and expects an integer value,
; the missing value is always assumed to be 0. If the
; missing key assumes a string value, the string is assumed
; to be empty.

<key> ::= <header_key> | <body_key>

<header_key> ::= <code> | <sync>
;
; <code> is request code or response code

;
; Request packet structure
; -----------------------------------
; Value for <code> key in request can be:
; 1 -- <select>
; 2 -- <insert>
; 3 -- <replace>
; 4 -- <update>
; 5 -- <delete>
; 6 -- <call>
; 7 -- <auth>
; 64 -- <ping>
; 66 -- <subscribe>

; <sync> is a unique request identifier, preserved in the response,
; The identifier is necessary to allow request multiplexing --
; i.e. sending multiple requests through the same connection
; before fetching a response to any of them.
; The value of the identifier currently bears no meaning to the
; server. Consequently, <sync> can be 0 or two requests
; can have an identical id.

<body_key> ::= <request_key> | <response_key>

; Different request types allow different keys in the body:

<request_key> ::= <select> | <replace> | <delete> | <update> | <call>

; Find tuples matching the search pattern
<select> ::= <space_id> | <index_id> | <iterator> | <offset> | <limit> | <key>

; Insert a tuple into the space or replace an existing one.
<replace> ::= <space_id> | <index_id> | <tuple>

; Insert is similar to replace, but will return a duplicate key
; error if such tuple already exists.
<insert> ::= <space_id> | <index_id> | <tuple>

; Delete a tuple
<delete> ::= <space_id> | <index_id> | <key>

; Update a tuple
<udpate> ::= <space_id> | <index_id> | <key> | <tuple>

; Call a stored function
<call> ::= <function_name> | <tuple>

; Authenticate a session
; <key> holds the user name. <tuple> must be an array of 2 fields:
; authentication mechanism ("chap-sha1" is the only supported
; mechanism right now) and password, encrypted according to the
; specified mechanism
; https://github.com/tarantool/tarantool/blob/master/src/scramble.h
; for instructions how to prepare a hashed password for "chap-sha1"
; authentication mechanism.
; Authentication in Tarantool is optional, if no
; authentication is performed, session user is 'guest'.
; The server responds to authentication packet with a standard
; response with 0 tuples.

<auth> ::= <key> | <tuple>

; As can be seen from the grammar some requests have common keys,
; whereas other keys can be present only in a body of a single
; request type.

; <space_id> space to use in the request
; To find the numeric space id by space name, one
; must first query "_space" system space.
; Id of _space system space is defined in box.schema.SPACE_ID
; (global Lua variable set in package "box")

; <index_id> index id of the index to use in the request
; Similarly to space, to find the numeric index id
; by index name, one must query the "_index" system space.
; Id of _index system space is defined in box.schema.INDEX_ID
; (global Lua variable set in package "box").
; <tuple> defines the actual argument of the operation
; in <replace> it defines the tuple which will be inserted
; into the database.
; In <call> it defines call arguments.
; When request body allows <tuple> as a key, it must always
; be present, since otherwise the request is meaningless.

; <offset> specifies offset in the result set, expects <uint32> value
; <limit> specifies limit in the result set, expects a <uint32> value
; <iterator> specifies the iterator type to use in search
; <function_name> is used to give call path for a Lua function

; <tuple> in <update> must carry a list of update operations:

<op_list> ::= [ (<operation>)+ ]

<operation> ::= [ <op>, <field_no>, (<argument>)+ ]

<field_no> ::= <int32>

;
; <op> is a 1-byte ASCII string carrying operation code:

; "=" - assign operation argument to field <field_no>;
; will extend the tuple if <field_no> == <max_field_no> + 1
; "#" - delete <argument> fields starting from <field_no>
; "!" - insert <argument> before <field_no>

; The following operation(s) are only defined for integer
; types (32 and 64 bit):

; "+" - add argument to field <field_no>, both arguments
; are treated as signed 32 or 64 -bit ints
; "-" - subtract argument from the field <field_no>
; "&" - bitwise AND of argument and field <field_no>
; "^" - bitwise XOR of argument and field <field_no>
; "|" - bitwise OR of argument and field <field_no>

; Finally there is an operation that expects offset, cut length and
; string paste arguments
; ":" - implementation of Perl 'splice' command

;
; It's an error to specify an argument of a type that
; differs from expected type.
;
; Response packet structure
; ----------------------------------------

; Value of <code> key in response is:
; 0 -- SUCCESS
; !0 -- Tarantool error code
; If response <code> is 0 (success), response body contains zero or
; more tuples, otherwise it carries an error message that corresponds
; to the return code.

; On success, the server always returns a tuple or tuples,
; when found.
; I.e. on success, response <body> contains <set> key.
; For select/update/delete, it's the tuple that matched
; the search criterion. For <replace>, it's the inserted tuple.
; For <call>, it's whatever the called function returns.

<response_key> = <data> | <error>

; Set of tuples in the response
<data> expects a msgpack array of tuples as value

; Error message is present in the response only if there is an error
; <error> expects as value a msgpack string

; The error <code> consists of the actual error code
; and request completion status (completion status is
; complementary since it can be deduced from the error code)
; There are only 3 completion status codes in use:
; 0 - success; The only possible error code with this status is
       0, ER_OK
; 1 - try again; An indicator of an intermittent error.
; Usually is returned when two clients attempt to change
; the same tuple simultaneously.
; (<update> is not always done atomically)
; 2 - error
;
; The error code holds the actual error. Existing error codes include:
;
; Completion status 0 (success)
; -----------------------------
; 0x00000000 -- ER_OK
;
; Completion status 1 (try again)
; -------------------------------
; 0x00000201 -- ER_MEMORY_ISSUE
; An error occurred when allocating memory
;
; Completion status 2 (error)
; ---------------------------
; 0x00000102 -- ER_ILLEGAL_PARAMS
; Malformed query
;
; 0x00000302 -- ER_TUPLE_FOUND
; Duplicate key exists in a unique index
;
; Convenience macros which define hexadecimal constants for
; <int32> return codes (completion status + code) can be found here:
; https://github.com/tarantool/tarantool/blob/master/src/errcode.h
;
;
; Additional packets
; ------------------

; vim: syntax=bnf
Something went wrong with that request. Please try again.