Kache Protocol Draft

kache protocol draft

just like resp version 3: https://gist.github.com/antirez/2bc68a9e9e45395e297d288453d5d54c

support type

Types equivalent to RESP version 2

• Array: an ordered collection of N other types
• Blob string: binary safe strings
• Simple string: a space efficient non binary safe string
• Simple error: a space efficient non binary safe error code and message
• Number: an integer in the signed 64 bit range Types introduced by RESP3
• Null: a single null value replacing RESP v2 *-1 and $-1 null values.
• Double: a floating point number
• Boolean: true or false
• Blob error: binary safe error code and message.
• Verbatim string: a binary safe string that should be displayed to humans without any escaping or filtering. For instance the output of LATENCY DOCTOR in Redis.
• Map: an ordered collection of key-value pairs. Keys and values can be any other RESP3 type.
• Set: an unordered collection of N other types.
• Attribute: Like the Map type, but the client should keep reading the reply ignoring the attribute type, and return it to the client as additional information.
• Push: Out of band data. The format is like the Array type, but the client should just check the first string element, stating the type of the out of band data, a call a callback if there is one registered for this specific type of push information. Push types are not related to replies, since they are information that the server may push at any time in the connection, so the client should keep reading if it is reading the reply of a command.
• Hello: Like the Map type, but is sent only when the connection between the client and the server is established, in order to welcome the client with different information like the name of the server, its version, and so forth.
• Big number: a large number non representable by the Number type use LF, not CRLF

Simple types

This section describes all the RESP3 types which are not aggregate types. They consist of just a single typed element. Blob string The general form is $<length>\n<bytes>\n

• example:
  • "$11\nhelloworld\n"
  • "$0\n\n" Simple string The general form is +<string>\n
• example: "+hello world\n"s Simple error The general form is -<string>\n
• This is exactly like a simple string, but the initial byte is - instead of +
• The first word in the error is in upper case and describes the error code
• The remaining string is the error message itself
• The ERR error code is the generic one
• example: "-ERR this is the error description\n" Number The general form is :<number>\n
• Valid numbers are in the range of the signed 64 bit integer
• example: ":1234\n" Null The null type is encoded just as _\n Double The general form is ,<floating-point-number>\n
• example:
  • ",1.23\n"
  • ",.23\n"
  • ",10\n" Boolean True and false values are just represented using #t\n and #f\n sequences Blob error The general form is !<length>\n<bytes>\n
• the first uppercase word represents the error code.
• example: "*21\nSYNTAX invalid syntax\n" Verbatim string The general form is =<length>\n<format(3 bytes)>\n<bytes>\n
• example: "=15\ntxt\nSome string\n" Big number The general form is (<big number>\n
• This type represents very large numbers that are out of the range of the signed 64 bit numbers
• Big numbers can be positive or negative
• they must not include a decimal part
• example: "(3492890328409238509324850943850943825024385\n"

Aggregate data types overview

The format for every aggregate type in RESP3 is always the same: ... numelements other types ...

Array type

The general form is *<elements number>\n... numelements other types ...

• example:
  • [1, 2, 3]: "*3\n:1\n:2\n:3\n"
  • [[1, "hello", 2], false]: "*2\n*3\n:1\n$5\nhello\n:2\n#f\n"

Map type

The general form is %<elements number>\n... numelements other types ...

• Maps are represented exactly as arrays, but instead of using the * byte, the encoded value starts with a % byte
• Note that after the % character, what follow is not, like in the array, the number of single items, but the number of field-value pairs.
• example:
  • {"first": 1, "second": 2}: "%2\n+first\n:1\n+second\n:2\n"

Set reply

The general form is ~<elements number>\n... numelements other types ...

• Sets are exactly like the Array type, but the first byte is ~ instead of *
• However they are semantically different because the represented items are unordered collections of elements
• example
  • {"orange", "apple", true, 100, 999}: "~5\n+orange\n+apple\n#t\n:100\n:999\n"

Attribute type

todo

Push type

todo

Hello replies

todo

Acknowledgements

This specification was written by Salvatore Sanfilippo, however the design was informed by multiple people that contributed worthwhile ideas and improvements. A special thank to Dvir Volk and Yao Yue for the conversation and ideas around having metadata in requests.

TODOs in this specification

• Document streaming of big strings.
• Document streaming of arrays.
• Document the optional "inline" protocol.
• Document pipelining