diff options
Diffstat (limited to 'doc/ProtocolSpecification.html')
| -rw-r--r-- | doc/ProtocolSpecification.html | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/doc/ProtocolSpecification.html b/doc/ProtocolSpecification.html new file mode 100644 index 000000000..686c574e8 --- /dev/null +++ b/doc/ProtocolSpecification.html @@ -0,0 +1,142 @@ + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> + <head> + <link type="text/css" rel="stylesheet" href="style.css" /> + </head> + <body> + <div id="page"> + + <div id='header'> + <a href="index.html"> + <img style="border:none" alt="Redis Documentation" src="redis.png"> + </a> + </div> + + <div id="pagecontent"> + <div class="index"> +<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. --> +<b>ProtocolSpecification: Contents</b><br> <a href="#Networking layer">Networking layer</a><br> <a href="#Simple INLINE commands">Simple INLINE commands</a><br> <a href="#Bulk commands">Bulk commands</a><br> <a href="#Bulk replies">Bulk replies</a><br> <a href="#Multi-Bulk replies">Multi-Bulk replies</a><br> <a href="#Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a><br> <a href="#Single line reply">Single line reply</a><br> <a href="#Integer reply">Integer reply</a><br> <a href="#Multi bulk commands">Multi bulk commands</a><br> <a href="#Multiple commands and pipelining">Multiple commands and pipelining</a> + </div> + + <h1 class="wikiname">ProtocolSpecification</h1> + + <div class="summary"> + + </div> + + <div class="narrow"> + = 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"> +C: GET mykey +S: $6 +S: foobar +</pre>A bulk reply is very similar to the last argument of a bulk command. The +server sends as the first line a "$" byte followed by the number of bytes +of the actual reply followed by CRLF, then the bytes are sent followed by +additional two bytes for the final CRLF. The exact sequence sent by the +server is:<br/><br/><blockquote>"$6\r\nfoobar\r\n"</blockquote> +If the requested value does not exist the bulk reply will use the special +value -1 as data length, example:<br/><br/><pre class="codeblock python python python python python" name="code"> +C: GET nonexistingkey +S: $-1 +</pre>The client library API should not return an empty string, but a nil object, when the requested object does not exist. +For example a Ruby library should return 'nil' while a C library should return +NULL, and so forth.<h2><a name="Multi-Bulk replies">Multi-Bulk replies</a></h2>Commands similar to LRANGE needs to return multiple values (every element +of the list is a value, and LRANGE needs to return more than a single element). This is accomplished using multiple bulk writes, +prefixed by an initial line indicating how many bulk writes will follow. +The first byte of a multi bulk reply is always <code name="code" class="python">*</code>. Example:<br/><br/><pre class="codeblock python python python python python python" name="code"> +C: LRANGE mylist 0 3 +S: *4 +S: $3 +S: foo +S: $3 +S: bar +S: $5 +S: Hello +S: $5 +S: World +</pre>The first line the server sent is "<b>4\r\n" in order to specify that four bulk +write will follow. Then every bulk write is transmitted.<br/><br/>If the specified key does not exist instead of the number of elements in the +list, the special value -1 is sent as count. Example:<br/><br/><pre class="codeblock python python python python python python python" name="code"> +C: LRANGE nokey 0 1 +S: *-1 +</pre>A client library API SHOULD return a nil object and not an empty list when this +happens. This makes possible to distinguish between empty list and non existing ones.<h2><a name="Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a></h2>Single elements of a multi bulk reply may have -1 length, in order to signal that this elements are missing and not empty strings. This can happen with the SORT command when used with the GET <i>pattern</i> option when the specified key is missing. Example of a multi bulk reply containing an empty element:<br/><br/><pre class="codeblock python python python python python python python python" name="code"> +S: *3 +S: $3 +S: foo +S: $-1 +S: $3 +S: bar +</pre>The second element is nul. The client library should return something like this:<br/><br/><pre class="codeblock python python python python python python python python python" name="code"> +["foo",nil,"bar"] +</pre><h2><a name="Single line reply">Single line reply</a></h2>As already seen 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 python python 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 status code reply: +PING, SET, SELECT, SAVE, BGSAVE, SHUTDOWN, RENAME, LPUSH, RPUSH, LSET, LTRIM<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="Multi bulk commands">Multi bulk commands</a></h2>As you can see with the protocol described so far there is no way to +send multiple binary-safe arguments to a command. With bulk commands the +last argument is binary safe, but there are commands where multiple binary-safe +commands are needed, like the MSET command that is able to SET multiple keys +in a single operation.<br/><br/>In order to address this problem Redis 1.1 introduced a new way of seding +commands to a Redis server, that uses exactly the same protocol of the +multi bulk replies. For instance the following is a SET command using the +normal bulk protocol:<br/><br/><pre class="codeblock python python python python python python python python python python python" name="code"> +SET mykey 8 +myvalue +</pre>While the following uses the multi bulk command protocol:<br/><br/><pre class="codeblock python python python python python python python python python python python python" name="code"> +*3 +$3 +SET +$5 +mykey +$8 +myvalue +</pre>Commands sent in this format are longer, so currently they are used only in +order to transmit commands containing multiple binary-safe arguments, but +actually this protocol can be used to send every kind of command, without to +know if it's an inline, bulk or multi-bulk command.<br/><br/>It is possible that in the future Redis will support only this format.<br/><br/>A good client library may implement unknown commands using this +command format in order to support new commands out of the box without +modifications.<h2><a name="Multiple commands and pipelining">Multiple commands and pipelining</a></h2>A client can use the same connection in order to issue multiple commands. +Pipelining is supported so multiple commands can be sent with a single +write operation by the client, it is not needed to read the server reply +in order to issue the next command. All the replies can be read at the end.<br/><br/>Usually Redis server and client will have a very fast link so this is not +very important to support this feature in a client implementation, still +if an application needs to issue a very large number of commands in short +time to use pipelining can be much faster. +</b> + </div> + + </div> + </div> + </body> +</html> + |