RedisProtocolSpecification - jasagiri @ ウィキ

ProtocolSpecification

プロトコル仕様

Redis プロトコルはコンピュータにも人間にも分析しやすいよう妥協されています。このセクションを読む前に、この README にある "REDIS TUTORIAL" セクションを読むことを強くお勧めします。TELNET でプロトコルの感覚をつかんでください。

ネットワークレイヤ

クライアントは6379ポートにTCP接続を確立しながら Redis server に接続します。すべての redis コマンドとデータは、クライアントとサーバによって終端を"\r\n" (CRLF)に変換されます。

単純な INLINE コマンド

もっとも単純なコマンドは inline コマンドです。これは server/client チャットの例です。 (サーバチャットは S: でクライアントチャットは C:で始まります。)

C: PING
S: +PONG

inline コマンドは クライアントへ送られたCRLF-終端文字です。サーバは異なった方法でコマンドを返すことが出来ます。：

エラーメッセージで (返却する最初の1バイトが "-" の時)
単一行での返信で (返却する最初の1バイトが "+" の時)
バルクデータで (返却する最初の1バイトが "$" の時)
マルチバルクデータ、値のリストで (返却する最初の1バイトが "*" の時)
整数値で (返却する最初の1バイトが ":" の時)

次に整数を返す INLINE コマンドの別の例をフォローします。：

C: EXISTS somekey
S: :0
'somekey' がサーバに存在しないなら ':0' を返す。

注意することは EXISTS コマンドは1つの引数ということです。引数は単純にスペースで区切られます。

バルクコマンド

バルクコマンドはちょうど inline コマンドに似ていますが、コマンドの最後の引数はサーバへ送ったデータのバイトオーダのストリームの必要があります。"SET" コマンドはバルクコマンドになります、次の例を見てください。：

C: SET mykey 6
C: foobar
S: +OK

コマンドの最後の引数は '6' です。DATA の指定した数のバイトをフォローします。(注意としてはこのバイトには終端の CRLF 2バイトを足されます。

すべてのバルクコマンドは、この正確なフォームで： 最後の引数の代わりに以下のバイト数が指定され CRLF。プログラマにより明確になるように、これはクライアントから送られてきたバイト列のサンプルです。：

"SET mykey 6\r\nfoobar\r\n"

バルクリプライ

サーバは1つの inline やバルクコマンドに大量に答えるかもしれない. 次の例を見てください。：

C: GET mykey
S: $6
S: foobar

バルクリプライはバルクコマンドの最後の引数ととてもよく似ています。サーバが最初の行で送った"$" バイト、実際送るデータ、最後に CRLF を続けて送ります。（？）サーバによって送られた完全なシーケンスはこうです：

"$6\r\nfoobar\r\n"

もし要求された値がバルクリプライに存在しないと、データ長として特殊な値 -1 を使用するでしょう。例：

C: GET nonexistingkey
S: $-1

クライアントライブラリの API は、要求されたオブジェクトが無い場合、空文字を返すのではなく、nil オブジェクトを返すべきです。例えば Ruby ライブラリは 'nil'、 C ライブラリは NULL、などです。

マルチバルクリプライ

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 *. Example:

C: LRANGE mylist 0 3
S: *4
S: $3
S: foo
S: $3
S: bar
S: $5
S: Hello
S: $5
S: World

The first line the server sent is "4\r\n" in order to specify that four bulk write will follow. Then every bulk write is transmitted.

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:

C: LRANGE nokey 0 1
S: *-1

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.

Nil elements in Multi-Bulk replies

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 pattern option when the specified key is missing. Example of a multi bulk reply containing an empty element:

S: *3
S: $3
S: foo
S: $-1
S: $3
S: bar

The second element is nul. The client library should return something like this:

["foo",nil,"bar"]
Single line reply

As already seen a single line reply is in the form of a single line string starting with "+" terminated by "\r\n". For example:

+OK

The client library should return everything after the "+", that is, the string "OK" in the example.

The following commands reply with a status code reply: PING, SET, SELECT, SAVE, BGSAVE, SHUTDOWN, RENAME, LPUSH, RPUSH, LSET, LTRIM

Integer reply

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.

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.

Some commands like EXISTS will return 1 for true and 0 for false.

Other commands like SADD, SREM and SETNX will return 1 if the operation was actually done, 0 otherwise.

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

Multiple commands and pipelining

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.

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.