- = Protocol Specification =<br/><br/>The Redis protocol is a compromise between being easy to parse by a computer
-and being easy to parse by an human. Before reading this section you are
-strongly encouraged to read the "REDIS TUTORIAL" section of this README in order
-to get a first feeling of the protocol playing with it by TELNET.<h2><a name="Networking layer">Networking layer</a></h2>A client connects to a Redis server creating a TCP connection to the port 6379.
-Every redis command or data transmitted by the client and the server is
-terminated by "\r\n" (CRLF).<h2><a name="Simple INLINE commands">Simple INLINE commands</a></h2>The simplest commands are the inline commands. This is an example of a
-server/client chat (the server chat starts with S:, the client chat with C:)<br/><br/><pre class="codeblock python" name="code">
-C: PING
-S: +PONG
-</pre>An inline command is a CRLF-terminated string sent to the client. The server can reply to commands in different ways:
-<ul><li> With an error message (the first byte of the reply will be "-")</li><li> With a single line reply (the first byte of the reply will be "+)</li><li> With bulk data (the first byte of the reply will be "$")</li><li> With multi-bulk data, a list of values (the first byte of the reply will be "<code name="code" class="python">*</code>")</li><li> With an integer number (the first byte of the reply will be ":")</li></ul>
-The following is another example of an INLINE command returning an integer:<br/><br/><pre class="codeblock python python" name="code">
-C: EXISTS somekey
-S: :0
-</pre>Since 'somekey' does not exist the server returned ':0'.<br/><br/>Note that the EXISTS command takes one argument. Arguments are separated
-simply by spaces.<h2><a name="Bulk commands">Bulk commands</a></h2>A bulk command is exactly like an inline command, but the last argument
-of the command must be a stream of bytes in order to send data to the server.
-the "SET" command is a bulk command, see the following example:<br/><br/><pre class="codeblock python python python" name="code">
-C: SET mykey 6
-C: foobar
-S: +OK
-</pre>The last argument of the commnad is '6'. This specify the number of DATA
-bytes that will follow (note that even this bytes are terminated by two
-additional bytes of CRLF).<br/><br/>All the bulk commands are in this exact form: instead of the last argument
-the number of bytes that will follow is specified, followed by the bytes,
-and CRLF. In order to be more clear for the programmer this is the string
-sent by the client in the above sample:<br/><br/><blockquote>"SET mykey 6\r\nfoobar\r\n"</blockquote>
-<h2><a name="Bulk replies">Bulk replies</a></h2>The server may reply to an inline or bulk command with a bulk reply. See
-the following example:<br/><br/><pre class="codeblock python python python python" name="code">
+ = Protocol Specification =<br/><br/>The Redis protocol is a compromise between the following things:<br/><br/><ul><li> Simple to implement.</li><li> Fast to parse by a computer.</li><li> Easy enough to parse by a human.</li></ul>
+<h2><a name="Networking layer">Networking layer</a></h2>A client connects to a Redis server creating a TCP connection to the port 6379.
+Every Redis command or data transmitted by the client and the server is
+terminated by "\r\n" (CRLF).<h1><a name="Requests">Requests</a></h1>Redis accepts commands composed of different arguments.
+Once a command is received, it is processed and a reply is sent back to the client.<h2><a name="The new unified request protocol">The new unified request protocol</a></h2>The new unified protocol was introduced in Redis 1.2, but it became the standard way for talking with the Redis server in Redis 2.0.<br/><br/>In the unified protocol all the arguments sent to the Redis server are binary safe. This is the general form:<br/><br/><pre class="codeblock python" name="code">
+*<number of arguments> CR LF
+$<number of bytes of argument 1> CR LF
+<argument data> CR LF
+...
+$<number of bytes of argument N> CR LF
+<argument data> CR LF
+</pre>See the following example:<br/><br/><pre class="codeblock python python" name="code">
+*3
+$3
+SET
+$5
+mykey
+$7
+myvalue
+</pre>This is how the above command looks as a quoted string, so that it is possible to see the exact value of every byte in the query:<br/><br/><pre class="codeblock python python python" name="code">
+"*3\r\n$3\r\nSET\r\n$5\r\nmykey\r\n$8\r\nmyvalue\r\n"
+</pre>As you will see in a moment this format is also used in Redis replies.
+The format used for every argument "$6\r\nmydata\r\n" is called a Bulk Reply.
+While the actual unified request protocol is what Redis uses to return list of items, and is called a Multi Bulk Reply. It is just the sum of N different
+Bulk Replies prefixed by a <code name="code" class="python">*<argc>\r\n</code> string where <code name="code" class="python"><argc></code> is the number of arguments (Bulk Replies) that will follow.<h1><a name="Replies">Replies</a></h1>Redis will reply to commands with different kinds of replies. It is possible to check the kind of reply from the first byte sent by the server:<br/><br/><ul><li> With a single line reply the first byte of the reply will be "+"</li><li> With an error message the first byte of the reply will be "-"</li><li> With an integer number the first byte of the reply will be ":"</li><li> With bulk reply the first byte of the reply will be "$"</li><li> With multi-bulk reply the first byte of the reply will be "<code name="code" class="python">*</code>"</li></ul>
+<h2><a name="Single line reply">Single line reply</a></h2>A single line reply is in the form of a single line string
+starting with "+" terminated by "\r\n". For example:<br/><br/><pre class="codeblock python python python python" name="code">
++OK
+</pre>The client library should return everything after the "+", that is, the string "OK" in the example.<br/><br/>The following commands reply with a single line reply:
+PING, SET, SELECT, SAVE, BGSAVE, SHUTDOWN, RENAME, LPUSH, RPUSH, LSET, LTRIM<h2><a name="Error reply">Error reply</a></h2>Errors are sent exactly like Single Line Replies. The only difference is that the first byte is "-" instead of "+".<br/><br/>Error replies are only sent when something strange happened, for instance if you try to perform an operation against the wrong data type, or if the command does not exist and so forth. So an exception should be raised by the library client when an Error Reply is received.<h2><a name="Integer reply">Integer reply</a></h2>This type of reply is just a CRLF terminated string representing an integer, prefixed by a ":" byte. For example ":0\r\n", or ":1000\r\n" are integer replies.<br/><br/>With commands like INCR or LASTSAVE using the integer reply to actually return a value there is no special meaning for the returned integer. It is just an incremental number for INCR, a UNIX time for LASTSAVE and so on.<br/><br/>Some commands like EXISTS will return 1 for true and 0 for false.<br/><br/>Other commands like SADD, SREM and SETNX will return 1 if the operation was actually done, 0 otherwise.<br/><br/>The following commands will reply with an integer reply: SETNX, DEL, EXISTS, INCR, INCRBY, DECR, DECRBY, DBSIZE, LASTSAVE, RENAMENX, MOVE, LLEN, SADD, SREM, SISMEMBER, SCARD<h2><a name="Bulk replies">Bulk replies</a></h2>Bulk replies are used by the server in order to return a single binary safe string.<br/><br/><pre class="codeblock python python python python python" name="code">
projects / redis.git / commitdiff
