Discussion on redis communication protocol

This document is translated from ：https://redis.io/topics/protocol

Redis Client use is called RESP （redis Serialization protocol ） The agreement with Redis The server communicates , Although it is designed for Redis Design , But it can also be used for other clients - Server software project .

RESP Design is a compromise between ：

• Implement a simple
• Fast parsing
• High readability

RESP Different data types can be serialized , Such as integers 、 character string 、 Array , There is also a specific type of error . The request is sent as a string array from the client to Redis The server , These strings represent the command parameters to be executed .Redis Reply with the data type of a specific command .

RESP It's binary safe , There is no need to process bulk data transferred from one process to another , Because it uses prefix length to transfer bulk data .

The protocols described here are for the client only - Server communication .Redis Cluster Use different binary protocols to exchange information between nodes .

The network layer

The client connects to Redis The server , Create to port 6379 Of TCP Connect .

although RESP Technically right and wrong TCP specific , But in Redis In the context of , The agreement is only for TCP Connect （ Or equivalent stream oriented connection , Such as Unix Socket ）.

request - Response model

Redis Accept commands with different parameters . After receiving the order , It will be processed and the reply sent back to the client .

This is the simplest model , But there are two exceptions ：

• Redis Support assembly line （ Later in this document ）. So the client can send multiple commands at once , And then wait for a reply .
• When Redis Client subscription Pub/Sub Channel time , The protocol semantics change , become push agreement , That is, the client no longer needs to send commands , Because the server will automatically send new messages to the client （ For channel clients are subscribed ）.

With the exception of the above two ,Redis The protocol is a simple request - Response protocol .

RESP Agreement that

RESP The agreement is in Redis 1.2 Introduced in , But it became Redis 2.0 China and Redis Standard way of server communication . This is where you should be Redis The protocol implemented in the client .

RESP It's actually a serialization protocol , It supports the following data types ： Simple string 、 error 、 Integers 、 Batch strings and arrays .

RESP stay Redis Used as a request in - The way to respond to the protocol is as follows ：

• The client takes the command as the RESP Array sent to Redis The server .
• The server implements one of them according to the command RESP Type to reply .

stay RESP in , The type of some data depends on the first byte ：

• about Simple string , The first byte of the reply is “+”
• about error , The first byte of the reply is “-”
• about Integers , The first byte of the reply is “：”
• about Batch string , The first byte of the reply is “$”
• about Array , The first byte of the reply is “ *”

Besides ,RESP Can be represented by a special variant of a batch string or array specified later Null value .

stay RESP in , Different parts of the agreement are always written in “\r\n”（CRLF） End .

RESP Simple string

Simple strings are encoded as follows ： The plus sign , Cannot be followed by CR or LF character （ Line breaks are not allowed ） String , With CRLF ending （ namely “\r\n”）.

Simple strings are used to transfer non binary secure strings with minimal overhead . for example , many Redis The command replies on success “OK”, As RESP Simple strings use the following 5 Bytes for encoding ：

"+OK\r\n"

To send binary security strings , Use RESP Batch string instead of .

When Redis When replying to a simple string , The client library should return a string... To the caller , The string consists of “+” The first character after that makes up , Until the end of the string , Not including the last CRLF byte .

RESP error

RESP Has a specific wrong data type . In fact, mistakes and RESP Simple strings are exactly the same , But the first character is the minus sign '-' Characters, not plus signs .RESP in Simple Strings and Errors The real difference is that the client treats errors as exceptions , The composition Error A string of type is the error message itself .

The basic format is ：

"-Error message\r\n"

Error replies are sent only when an error occurs , for example , If you try to perform an operation on the wrong data type , Or the command does not exist . When an error reply is received , The library client should throw an exception .

Here is an example of an error response ：

-ERR unknown command 'foobar'-WRONGTYPE Operation against a key holding the wrong kind of value

“-” The first word after , Until the first space or line break , Indicates the type of error returned . This is just Redis Conventions for use , No RESP Part of the wrong format .

for example ,ERR It's a general mistake , and WRONGTYPE It's a more specific mistake , Indicates that the client is trying to perform an operation on the wrong data type . This is called Wrong prefix , Is a method that allows the client to understand the error type returned by the server , Without relying on a given exact message , The message may change over time .

The client implementation may return different types of exceptions for different errors , Or you can provide a common way to catch errors by providing the error name as a string directly to the caller .

However , Such features should not be considered critical , Because it's rarely useful , And a limited client implementation may simply return a generic error condition , for example false.

RESP Integers

This type is just a CRLF Terminated string , Represents an integer , With “:” Bytes are prefixed with . for example ":0\r\n" or ":1000\r\n" It's an integer reply .

many Redis Command return RESP Integers , image INCR,LLEN and LASTSAVE.

The integer returned has no special meaning , It's just INCR Incremental number of ,LASTSAVE Of UNIX Time, etc. . however , The integer returned is guaranteed to be in signed 64 Bit integer range .

Integer replies are also widely used to return true or false . for example , image EXISTS or SISMEMBER Such a command will return 1 Said really ,0 Said the false .

If the operation is actually performed , Other commands such as SADD、SREM and SETNX Will return 1, Otherwise return to 0.

The following commands are integer replies ：SETNX,DEL, EXISTS,INCR,INCRBY,DECR,DECRBY,DBSIZE,LASTSAVE, RENAMENX,MOVE,LLEN,SADD,SREM,SISMEMBER,SCARD.

RESP Batch string

The batch string is used to indicate that the maximum length is 512 MB A single binary security string for .

Batch strings are encoded as follows ：

• “$” Byte followed by the number of bytes that make up the string （ Prefix length ）, With CRLF ending .
• Actual string data .
• final CRLF.

So string “foobar” The code of is as follows ：

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

When an empty string is just ：

"$0\r\n\r\n"

You can also use RESP Batch string , Used to represent Null The special format of the value to indicate that the value does not exist . In this particular format , The length is -1, And there's no data , therefore Null Expressed as ：

"$-1\r\n"

This is called Null Bulk String.

When the server uses Null Bulk String Reply time , Client library API Should not return an empty string , It's going back to nil object . for example ,Ruby The library should return “nil”, and C The library should return NULL（ Or set a special flag in the reply object ）, wait .

RESP Array

Client side usage RESP Array orientation Redis The server sends commands . Similarly , some Redis The command returns a collection of elements to the client for use RESP Array is reply type . One example is to return a list element LRANGE command .

RESP The array is sent in the following format ：

• * Character as the first byte , Then the number of elements in the array as a decimal number , And then there was CRLF.
• Every element of an array is RESP type .

So an empty array is as follows ：

"*0\r\n"

Although two RESP Batch string “foo” and “bar” The array of is encoded as ：

"*2\r\n$3\r\nfoo\r\n$3\r\nbar\r\n"

Just like you *<count>CRLF As you can see after the prefix section of the array , The other data types that make up the array are simply linked together one by one . for example , The array of three integers is encoded as follows ：

"*3\r\n:1\r\n:2\r\n:3\r\n"

Arrays can contain mixed types , Elements do not have to be of the same type . for example , A list of four integers and a batch string can be encoded as follows ：

*5\r\n:1\r\n:2\r\n:3\r\n:4\r\n$6\r\nfoobar\r\n

（ For the sake of clarity , The reply is divided into several lines ）.

The first line sent by the server is *5\r\n To specify, there will be five replies . Each reply that constitutes a multi batch reply item is then sent .

Null Array There is also the concept of , It specifies Null Another way to value （ Usually use Null Bulk String, But for historical reasons , We have two formats ）.

for example , When BLPOP Command timeout , It returns an empty array , Its count -1 As shown in the following example ：

"*-1\r\n"

When Redis use Null Array Reply time , Client library API It's time to return to one null Object instead of an empty Array. This is the distinction between empty lists and different conditions （ for example BLPOP Timeout condition for command ） Necessary .

stay RESP Arrays can be used in . for example , The array encoding of the two arrays is as follows ：

*2\r\n*3\r\n:1\r\n:2\r\n:3\r\n*2\r\n+Foo\r\n-Bar\r\n

（ For easy reading , The format is divided into multiple lines ）.

above RESP The data type encodes an array of two elements , The array consists of a string containing three integers 1、2、3 Array with a simple string and an array of errors .

Empty elements in an array

Array A single element of may be Null. This is for Redis In reply to , To indicate that these elements are missing instead of empty strings . When the specified key is missing , When and GET Pattern When used with options ,SORT This can happen with orders . contain Null Elemental Array Reply example ：

*3\r\n$3\r\nfoo\r\n$-1\r\n$3\r\nbar\r\n

The second element is Null. The client library should return the following ：

["foo",nil,"bar"]

Please note that , This is not the exception mentioned in the previous sections , It is just an example of further specifying the protocol .

Inline command

Sometimes it's just... In your hands telnet Tools , And you need to send a command to Redis The server . although Redis The protocol is easy to implement , But it's not ideal for interactive conversation , and redis-cli It may not always be available . For this reason ,Redis And take orders in a way that's specifically designed for humans , And is referred to as Inline command Format .

Here are the servers that use inline commands / Client chat example （ Server chat to S: start , Client chat to C: start ）

C: PINGS: +PONG

Here's another example of an inline command that returns an integer ：

C: EXISTS somekeyS: :0

Basically , All you need to do is telnet Write space delimited parameters in the session . because * The unified request protocol does not use a command that begins with that ,Redis Be able to detect this and parse your commands .

A complete protocol description diagram is given ：

Picture from the Internet

Reference resources ：https://redis.io/topics/protocol