What we'll cover

By the end of this chapter RedisServer will speak the Redis Protocol, RESP v2. Doing this will allow any clients that was written to communicate with the real Redis to also communicate with our own server, granted that the commands it uses are within the small subset of the ones we implemented.

One such client is the redis-cli utility that ships with Redis, it'll look like this:

RESP v2 has been the protocol used by Redis since version 2.0, to quote the documentation:

1.2 already supported it, but Redis 2.0 was the first version to talk only this protocol)

As of version 6.0, RESP v2 is still the default protocol and is what we'll implement in this chapter.

RESP3

RESP v2 is the default version, but not the latest one. RESP3 has been released in 2018, it improves many different aspects of RESP v2, such as adding new types for maps — often called dictionary — and a lot more. The spec is on GitHub and explains in details the background behind it.
RESP3 is supported as of Redis 6.0, as indicated in the release notes:

Redis now supports a new protocol called RESP3, which returns more semantical replies: new clients using this protocol can understand just from the reply what type to return to the calling program.

The HELLO command can be used to switch the connection to a different protocol version. As we can see below, only two versions are currently supported, 2 & 3. We can also see the new map type in action, hello 2 returned an array with 14 items, representing 7 key/value pairs, whereas hello 3 leveraged the new map type to return a map with 7 key/value pairs.

127.0.0.1:6379> hello 2
 1) "server"
 2) "redis"
 3) "version"
 4) "6.0.6"
 5) "proto"
 6) (integer) 2
 7) "id"
 8) (integer) 6
 9) "mode"
10) "standalone"
11) "role"
12) "master"
13) "modules"
14) (empty array)

127.0.0.1:6379> hello 3
1# "server" => "redis"
2# "version" => "6.0.6"
3# "proto" => (integer) 3
4# "id" => (integer) 6
5# "mode" => "standalone"
6# "role" => "master"
7# "modules" => (empty array)

127.0.0.1:6379> hello 1
(error) NOPROTO unsupported protocol version

127.0.0.1:6379> hello 4
(error) NOPROTO unsupported protocol version

Support for the HELLO command and RESP3 might be added in a later chapter but it's not currently on the roadmap of this online book.

Back to RESP v2

The official specification goes into details about the protocol and is still reasonably short and approachable, so feel free to read it, but here are the main elements that will drive the changes to our server.

The 5 data types

RESP v2 defines five data types:

• Simple Strings
• Errors
• Integers
• Bulk Strings
• Arrays

The type of a serialized RESP data is determined by the first byte:

• Simple Strings start with +
• Errors start with -
• Integers start with :
• Bulk Strings start with $
• Arrays start with *

The data that follows the type byte depends on each type, let's look at each of them one by one.

Simple Strings

A Simple String cannot contain a new line. One of its main use cases is to return OK back to the client. The full format of a Simple String is "A + character, followed directly by the content of the string, followed by a carriage return (often written as CR or \r) and a line feed (often written as LF or \n).

This is why Simple Strings cannot contain multiples lines, a newline would create confusion given that it is also use a delimiter.

The "OK" string, here shown in its JSON form, returned by the SET command upon success is therefore serialized as +OK\r\n.

redis-cli does the work of detecting the type of the response and only shows us the actual string, OK, as we can see in the example below:

127.0.0.1:6379> SET 1 2
OK

Using nc, we can see what the full response sent back from Redis is:

> nc -v localhost 6379
SET 1 2
+OK

nc does not explicitly display invisible characters such as CR & LF, so it is hard to know for sure that they were returned, beside the newline printed after +OK. The hexdump command is useful here, it allows us to see all the bytes:

echo "SET 1 2" | nc localhost 6379 | hexdump -C
# ...
00000000  2b 4f 4b 0d 0a                                    |+OK..|
00000005

The interesting part is the middle one, 2b 4f 4b 0d 0a, these are the 5 bytes returned by Redis. The part to the right, between pipe characters (|) is their ASCII representation. We can see five characters there, + is the ASCII representation of 2b, O is for 4f, K is for 4d, and the last two bytes do not have a visual representation so they're displayed as ..

2b is the hex notation of 43 ('2b'.to_i(16) in irb), and 43 maps to + in the ASCII table. 4f is the equivalent of 79, and the capital letter O, 4b, the number 75 and the capital letter K.

0d is the equivalent of the number 13, and the carriage return character (CR), and finally, 0a is 10, the line feed character (LF).

Redis follows the Redis Protocol, that's a good start!

Errors

Errors are very similar to Simple Strings, they also cannot contain new line characters. The main difference is that clients should treat them as errors instead of successful results. In languages with exceptions, a client library might decide to throw an exception when receiving an error from Redis. This is what the official ruby library does.

Similarly to Simple Strings, errors end with a carriage return and a line feed, let's see it in action:

❯ echo "GET 1 2" | nc localhost 6379 | hexdump -C
00000000  2d 45 52 52 20 77 72 6f  6e 67 20 6e 75 6d 62 65  |-ERR wrong numbe|
00000010  72 20 6f 66 20 61 72 67  75 6d 65 6e 74 73 20 66  |r of arguments f|
00000020  6f 72 20 27 67 65 74 27  20 63 6f 6d 6d 61 6e 64  |or 'get' command|
00000030  0d 0a                                             |..|
00000032

There are more bytes here, they represent the string: "Err wrong number of arguments for 'get' command", but we can see that the response starts with the 2d byte. Looking at the ASCII table, we can see that 45, the numeric equivalent of 2d, maps to -, so far so good.

And finally, the response ends with 0d0a, respectively CR & LF.

Integers

Integers have a similar representation to Simple Strings and errors. The actual integer comes after the : character and is followed by the CR & LF characters.

An example of integer reply is with the TTL and PTTL commands

The key key-with-ttl was set with the command: SET key-with-ttl value EX 1000.

> echo "TTL key-with-ttl" | nc localhost 6379 | hexdump -C
# ...
00000000  3a 39 38 38 0d 0a                                 |:988..|
00000006

The key not-a-key does not exist.

> echo "TTL not-a-key" | nc localhost 6379 | hexdump -C
# ...
00000000  3a 2d 32 0d 0a                                    |:-2..|
00000005

The key key-without-ttl was set with the command: SET key-without-ttl value.

> echo "TTL key-without-ttl" | nc localhost 6379 | hexdump -C
# ...
00000000  3a 2d 31 0d 0a                                    |:-1..|
00000005

All of these responses start with the 3a byte, which is equivalent to 58, aka :. In the two cases where the response is a negative value, -2 for a non existent key and -1 for an existing key without a ttl, the next byte is 2d, equivalent to 45, aka -.

The rest of the data, before the 0d & 0a bytes, is the actual integer data, in ASCII format, 31 is the hex equivalent to 49, which is the character 1, 32 is the hex equivalent to 50, which is the character 2. 39 & 38 are respectively the hex equivalent to 57 & 56, the characters 9 & 8.

A ruby client parsing this data would extract the string between : and \r\n and call to_i on it: '988'.to_i == 988.

Bulk Strings

In order to work for any strings, Bulk Strings need to first declare their length, and only then the actual data. This lets the receiver know how many bytes to expect, instead of reading anything until it finds CRLF, the way it does for a Simple String.

The length of the string is sent directly after the dollar sign, and is delimited by CRLF, the following is the actual string data, and another CRLF to end the string.

The RESP Bulk String representation of the JSON string "GET" is: $3\r\nGET\r\n.

Interestingly, it seems like Redis does not care that much about the final CRLF, as long as it finds two characters there, it assumes it's the end of the Bulk String and tries to process what comes after.

In the following example, we first send the command GET a to Redis over port 6379, as a an array of Bulk Strings, followed by the non existent command NOT A COMMAND. The response first contains the -1 integer, followed by the error.

irb(main):001:0> require 'socket'
=> true
irb(main):002:0> socket = TCPSocket.new 'localhost', 6379
irb(main):004:0> socket.write("*2\r\n$3\r\nGET\r\n$1\r\na\r\n*1\r\n$13\r\nNOT A COMMAND\r\n")
=> 35
irb(main):005:0> socket.read_nonblock(1024, exception: false)
=> "$-1\r\n-ERR unknown command `NOT`, with args beginning with: `A`, `COMMAND`, \r\n"

The following is handled identically by Redis, despite the fact the a Bulk String is not terminated by CRLF. We can see that Redis ignored the b and c characters and proceeded with the following command, the non existent NOT A COMMAND. I am assuming that the code in charge of reading client input first reads the length, then grabs that many bytes and jumps by two characters, regardless of what these characters are.

irb(main):027:0> socket.write("*2\r\n$3\r\nGET\r\n$1\r\nabc*1\r\n$13\r\nNOT A COMMAND\r\n")
=> 35
irb(main):030:0> socket.read_nonblock(1024, exception: false)
=> "$-1\r\n-ERR unknown command `NOT`, with args beginning with: `A`, `COMMAND`, \r\n"

There's a special value for Bulk Strings, the null Bulk String. It is commonly returned when a Bulk String would otherwise be expected, but there was no value to return. This happens in many cases, such as when there are no values for the key passed to the GET command. RESP represents it as a string with a length of -1: $-1\r\n.

Arrays

Arrays can contain values of any types, including other nested arrays. Similarly to Bulk Strings, arrays must first declare their lengths, followed by CRLF, and all items come afterwards, in their regular serialized form. The following is a JSON representation of an arbitrary array:

[ 1, "a-string", [ "another-string-in-a-nested-array" ], "a-string-with\r\n-newlines" ]

The following is the RESP representation of the same array:

*4\r\n:1\r\n$8\r\na-string\r\n*1\r\n$32\r\nanother-string-in-a-nested-array\r\n$24\r\na-string-with\r\n-newlines\r\n

We can include newlines and indentation for the sake of readability

*4\r\n
  :1\r\n
  $8\r\na-string\r\n
  *1\r\n
    $32\r\nanother-string-in-a-nested-array\r\n
  $24\r\na-string-with\r\n-newlines\r\n

RESP has a special notation for the NULL array: *-1\r\n. The existence of two different NULL values, one for Bulk Strings and one for Bulk Arrays is confusing and is one of the many changes in RESP3. RESP3 has a single null value.

Requests & Responses

As we saw in a previous example, requests are sent as arrays of Bulk Strings. The command GET a-key should be sent as *2\r\n$3\r\nGET\r\n$5\r\na-key\r\n, or in plain English: "An array of length 2, where the first string is of length 3 and is GET and the second string is of length 5 and is a-key".

We can illustrate this by sending this string with the TCPSocket class in ruby:

irb(main):001:0> require 'socket'
=> true
irb(main):002:0> socket = TCPSocket.new 'localhost', 6379
irb(main):003:0> socket.write "*2\r\n$3\r\nGET\r\n$5\r\na-key\r\n"
=> 24
irb(main):004:0> socket.read_nonblock 1024
=> "$-1\r\n"

Inline Protocol

RESP's main mode of operation is following a request/response model described above. It also supports a simpler alternative, called "Inline Commands", which is useful for manual tests or interactions with a server. This is similar to how we've used nc in this book so far.

Anything that does not start with a * character — which is the first character of an array, the format Redis expects for a command — is treated as an inline command. Redis will read everything until a newline is detected and attempts to parse that as a command. This is essentially what we've been doing so far when implementing the RedisServer class.

Let's try this quickly with nc:

> nc localhost 6379
# ...
SET 1 2
+OK
GET 1
$1
2

The reason RESP's main mode of operations is more complicated is because inline commands are severely limited. It is impossible to store a key or a value that contains the carriage return and line feed characters since they're use as delimiters even though Redis does support any strings as keys and values as seen in the following example:

> redis-cli
127.0.0.1:6379> SET a-key "foo\nbar"
OK
127.0.0.1:6379> GET a-key
"foo\nbar"

Let's double check with nc to see what Redis stored:

> nc localhost 6379
# ...
GET a-key
$7
foo
bar

We could also use hexdump to triple check:

> echo "GET a-key" | nc localhost 6379 | hexdump -C
# ...
00000000  24 37 0d 0a 66 6f 6f 0a  62 61 72 0d 0a           |$7..foo.bar..|
0000000d

We can see the 0a byte between o/6f & b/62.

Without inline commands sending test commands would be excruciating:

> nc -c localhost 6379
*2
$3
GET
$1
a
$1
1

Note that we're using the -c flags, which tells nc to send CRLF characters when we type the return key, instead of the default of LF. As we've seen above, for RESP arrays, RESP expects CRLF delimiters.

Pub/Sub

Redis supports a Publish/Subscribe messaging paradigm, with the SUBSCRIBE, UNSUBSCRIBE & PUBLISH commands, documented on Pub/Sub page of the official documentation.

These commands have a significant impact of how data flows between clients and servers, and given that we have not yet added support for pub/sub, we will ignore its impact on our implementation of the Redis Protocol for now. Future chapters will add support for pub/sub and will follow the RESP specification.

Pipelining

RESP clients can send multiple requests at once and the RESP server will write multiple responses back, this is called pipelining. The only constraint is that commands must be processed in the same ordered they were received, so that clients can associate the responses back to each request.

The following is an example of sending two commands at once and then reading the two responses, in Ruby:

irb(main):001:0> require 'socket'
=> true
irb(main):002:0> socket = TCPSocket.new 'localhost', 6379
irb(main):003:0> socket.write "SET 1 2\r\nGET 1\r\n"
=> 16
irb(main):004:0> socket.read_nonblock 1024
=> "+OK\r\n$1\r\n2\r\n"

We first wrote the string "SET 1 2\r\nGET 1\r\n", which represents the command SET 1 2 and the command GET in the inline format.

The response we get from the server is a string containing the two responses, fist the Simple String +OK\r\n, followed by the Bulk String $1\r\n2\r\n.

Making our Server speak RESP

As far as I know there is no official test suite that we could run our server against to validate that it correctly follows RESP. What we can do instead is rely on redis-cli as a way to test the RESP implementation of our server. Let's see what happens when we try it with the current server. First let's start the server from Chapter 4:

DEBUG=t ruby -r"./server" -e "RedisServer.new"

and in another shell, let's open redis-cli on port 2000:

> redis-cli -p 2000

You should see the following the server logs:

D, [2020-08-12T16:11:42.461645 #91271] DEBUG -- : Received command: *1
D, [2020-08-12T16:11:42.461688 #91271] DEBUG -- : Response: (error) ERR unknown command `*1`, with args beginning with:
D, [2020-08-12T16:11:42.461925 #91271] DEBUG -- : Received command: $7
D, [2020-08-12T16:11:42.461960 #91271] DEBUG -- : Response: (error) ERR unknown command `$7`, with args beginning with:
D, [2020-08-12T16:11:42.462005 #91271] DEBUG -- : Received command: COMMAND
D, [2020-08-12T16:11:42.462036 #91271] DEBUG -- : Response: (error) ERR unknown command `COMMAND`, with args beginning with:

The server received the string "*1\r\n$7\r\nCOMMAND\r\n", which is the RESP representation of the string "COMMAND" in a single item array, [ "COMMAND" ] in JSON.

The COMMAND command is useful when running Redis in a cluster. Given that we have not yet implementer cluster capabilities, going into details about the COMMAND command is a little bit out of scope. In short the COMMAND command is useful to provide meta information about each command, such as information about the positions of the keys. This is useful because in cluster mode, clients have to route requests to the different nodes in the cluster. It is common for a command to have the key as the second element, the one coming directly after the command itself. This happens to be the case for all the commands we've implemented so far. But some commands have different semantics. For instance MSET can contain multiple keys, so clients need to know where the keys are in the command. While rare, some commands have the first key at a different index, this is the case for the OBJECT command.

Back to redis-cli running against our Redis server, if you then try to send a command, GET 1 for instance, redis-cli will crash after printing the following error:

Error: Protocol error, got "(" as reply type byte

This is because our server writes the string (nil) when it does find an try for the given key. (nil) is what redis-cli displays when it receives a null Bulk String, as we can see with the following example, we first send the GET 1 command with redis-cli and then with nc and observe the response in each case:

❯ nc -c localhost 6379
GET 1
$-1
# ...
> redis-cli
127.0.0.1:6379> GET 1
(nil)

Our server must send the null Bulk String, $-1\r\n, to follow RESP. This is what redis-cli tells us before stopping, it expected a "type byte", one of +, -, :, $ or *, but instead got (.

In order to use redis-cli against our own server, we should implement the COMMAND command, since it sends it directly after starting. We also need to change how we process client input, to parse RESP arrays of Bulk Strings. We also need to support inline commands. Finally, we also need to update the responses we write back, and serialize responses following RESP.

Let's get to it!

Parsing Client Input

Modules & Namespaces

Most of the changes will take place in server.rb. As the codebase started to grow, I thought it would be easier to start using ruby modules, so I nested the Server class under the Redis namespace. This will allow us to create other classes & modules under the Redis namespace as well. All the other classes have been updated to be under the Redis namespace as well, e.g. ExpireHelper is now BYORedis::ExpireHelper. BYO stands for Build Your Own. I'm purposefully not using Redis as it is already used by the popular redis gem. We're not using both at the same time in the same project for now, so it wouldn't really have been a problem. But say that you would like to use the redis gem to communicate with the server we're building, we will prevent any kind of unexpected errors by using different names.

# expire_helper.rb
module BYORedis
  module ExpireHelper

    def self.check_if_expired(data_store, expires, key)
      # ...
    end
  end
end

listing 5.1: Nesting ExpireHelper under the Redis module

Storing partial client buffer

As of the previous chapter we never stored the client input. We would read from the socket when IO.select would tell us there is something to read, read until the end of the line, and process the result as a command.

It turns out that this approach is a bit too aggressive. Clients should be able to send a single command in two parts, there's no reason to treat that as an error.

In order to do this, we are going to create a Client struct to hold the client socket as well a string containing all the pending input we have not process yet:

# server.rb
Client = Struct.new(:socket, :buffer) do
  def initialize(socket)
    self.socket = socket
    self.buffer = ''
  end
end

listing 5.2: The new Client class

We need to adapt process_poll_events to use this new class instead of the raw socket coming as a result of TCPServer#accept:

# server.rb
def process_poll_events(sockets)
  sockets.each do |socket|
    begin
      if socket.is_a?(TCPServer)
        @clients << Client.new(@server.accept)
      elsif socket.is_a?(TCPSocket)
        client = @clients.find { |client| client.socket == socket }
        client_command_with_args = socket.read_nonblock(1024, exception: false)
        if client_command_with_args.nil?
          @clients.delete(client)
          socket.close
        elsif client_command_with_args == :wait_readable
          # ...
        else
          # We now need to parse the input as a RESP array
          # ...
        end
      else
        # ...
      end
    rescue Errno::ECONNRESET
      @clients.delete_if { |client| client.socket == socket }
    end
  end
end

listing 5.3: Updated handling of socket in server.rb

Parsing commands as RESP Arrays

More things need to change in process_poll_events. We first append the result from read_nonblock to client.buffer, which will allow us to continue appending until we accumulate enough to read a whole command. We then delegate the processing of client.buffer to a different method, split_commands:

# server.rb
def process_poll_events(sockets)
  sockets.each do |socket|
    begin
      # ...
      elsif socket.is_a?(TCPSocket)
        # ...
        else
          client.buffer += client_command_with_args
          split_commands(client.buffer) do |command_parts|
            response = handle_client_command(command_parts)
            @logger.debug "Response: #{ response.class } / #{ response.inspect }"
            @logger.debug "Writing: '#{ response.serialize.inspect }'"
            socket.write response.serialize
          end
        end
      else
        # ...
      end
      # ...
    end
  end
end

def split_commands(client_buffer)
  @logger.debug "Full result from read: '#{ client_buffer.inspect }'"

  scanner = StringScanner.new(client_buffer.dup)
  until scanner.eos?
    if scanner.peek(1) == '*'
      yield parse_as_resp_array(scanner)
    else
      yield parse_as_inline_command(scanner)
    end
    client_buffer.slice!(0, scanner.charpos)
  end
end
#...

listing 5.4 Updated handling of client input in server.rb

split_commands is in charge of splitting the client input into multiple commands, which is necessary to support pipelining. As a reminder, since we're adding support pipelining, we have to assume that the content of client.buffer might contain more than one command, and if so, we want to process them all in the order we received them, and write the responses back, in the same order.

It also handles the two different versions of commands, inline, or "regular", as RESP Arrays. We use the StringScanner class, which is really convenient to process data from a string, from left to right. We call String#dup on the argument to StringScanner to make sure that the StringScanner gets its own instance. As we iterate through client.buffer, every time we find a whole command, we want to remove it from the client input. We do this with client_buffer.slice!(0, scanner.charpos). If client_buffer contains two commands, i.e. GET a\r\nGET b\r\n, once we processed GET a, we want to remove the first 7 characters from the string: GET a\r\n, so that we never attempt to process them again. Note that we only do this after yielding, meaning that we only ever treat a command as done after we successfully wrote to the socket.

We first peek at the first character, if it is *, the following should be a RESP array, and we process it as such. Otherwise, we assume that we're dealing with an inline command. Each branch delegates to a method handling the parsing of the string.

The yield approach allows us to process each parsed command one by one, once parsed, we yield it, and it is handled by the handle_client_command method, which has barely changed from the previous chapter.

Let's look at the parse_as_resp_array & parse_as_inline_command methods:

def parse_as_inline_command(client_buffer, scanner)
  command = scanner.scan_until(/(\r\n|\r|\n)+/)
  raise IncompleteCommand if command.nil?

  command.split.map(&:strip)
end

def parse_as_resp_array(scanner)
  unless scanner.getch == '*'
    raise 'Unexpectedly attempted to parse a non array as an array'
  end

  expected_length = scanner.scan_until(/\r\n/)
  raise IncompleteCommand if expected_length.nil?

  expected_length = parse_integer(expected_length, 'invalid multibulk length')
  command_parts = []

  expected_length.times do
    raise IncompleteCommand if scanner.eos?

    parsed_value = parse_as_resp_bulk_string(scanner)
    raise IncompleteCommand if parsed_value.nil?

    command_parts << parsed_value
  end

  command_parts
end

def parse_integer(integer_str, error_message)
  begin
    value = Integer(integer_str)
    if value < 0
      raise ProtocolError, "ERR Protocol error: #{ error_message }"
    else
      value
    end
  rescue ArgumentError
    raise ProtocolError, "ERR Protocol error: #{ error_message }"
  end
end

listing 5.5 Parsing RESP Arrays in server.rb

parse_as_inline_command starts by calling StringScanner#scan_until, with /\r\n/. scan_until keeps iterating through the string, until it encounters something that matches its argument. In our case it will keep going through client_buffer until it finds CRLF, if it doesn't find a match, it returns nil. We're not even trying to process the string in this case, it is incomplete, so we'll leave it in there and eventually reattempt later on, the next time we read from this client.

If the string returned is not nil, it contains the string, and in this case, we do what we used to, we split it on spaces, and return it as an array of string parts, e.g. GET 1\r\n would be returned as [ 'GET', '1' ]

parse_as_resp_array is more complicated. As a sanity check, we test again that the first character is indeed *, getch also moves the internal cursor of StringScanner, moving it to the first character of the expected length. Using scan_until we extract all the characters until the first CRLF characters in the client input.

If nil is returned, this means that we reached the end of the string without encountering CR & LF, and instead of treating this as a client error, we raise an IncompleteCommand error, to give the client a change to write the missing parts of the command later on.

expected_length will contain a string composed of the characters before CRLF & the CRLF characters. For instance, if the scanner was created with the string $3\r\nabc\r\n — The Bulk String representation of the string "3" — expected_length would be equal to "3\r\n". The Ruby String#to_i is not strict enough here. It returns 0 in a lot of cases where we'd want an error instead, such as "abc".to_i == 0. We instead use the Kernel.Integer method, which raises an ArgumentError exception with invalid strings. We catch ArgumentError and raise a ProtocolError instead.

In the next step we iterate as many times as the value of expected_length with expected_length.times. We start each iteration by checking if we reached the end of the string with eos?. If we did, then instead of returning a protocol error, we raise an IncompleteCommand exception. This gives a chance to the client to send the remaining elements of the array later on.

As mentioned above, a request to Redis is always an array of Bulk Strings, so we attempt to parse all the elements as strings, by calling parse_as_bulk_string with the same scanner instance. Before looking at the method, let's see how the two new exceptions IncompleteCommand & ProtocolError are defined and handled:

IncompleteCommand & ProtocolError are custom exceptions defined at the top of the file:

# server.rb
IncompleteCommand = Class.new(StandardError)
ProtocolError = Class.new(StandardError) do
  def serialize
    RESPError.new(message).serialize
  end
end

listing 5.6 The new exceptions in server.rb

RESPError is defined in resp_types.rb:

# resp_types.rb
module BYORedis
  RESPError = Struct.new(:message) do
    def serialize
      "-#{ message }\r\n"
    end
  end
  # ...
end

listing 5.7 The new RESPError class

They are handled in the begin/rescue block in process_poll_events:

# server.rb
begin
  # ...
rescue Errno::ECONNRESET
  @clients.delete_if { |client| client.socket == socket }
rescue IncompleteCommand
  # Not clearing the buffer or anything
  next
rescue ProtocolError => e
  socket.write e.serialize
  socket.close
  @clients.delete(client)
end

listing 5.8 Handling the new exceptions in server.rb

We don't write anything back when encountering an IncompleteCommand exception, we assume that the client has not finished sending the command. On the other hand, for ProtocolError, we write an error back to the client, following the format of a RESP error and we disconnect the client. This is what Redis does too.

Back to parse_as_resp_bulk_string:

# server.rb
def parse_as_resp_bulk_string(scanner)
  type_char = scanner.getch
  unless type_char == '$'
    raise ProtocolError, "ERR Protocol error: expected '$', got '#{ type_char }'"
  end

  expected_length = scanner.scan_until(/\r\n/)
  raise IncompleteCommand if expected_length.nil?

  expected_length = parse_integer(expected_length, 'invalid bulk length')
  bulk_string = scanner.rest.slice(0, expected_length)

  raise IncompleteCommand if bulk_string.nil? || bulk_string.length != expected_length

  scanner.pos += bulk_string.bytesize + 2
  bulk_string
end

listing 5.9 Parsing Bulk Strings

The first step is calling StringScanner#getch, it moves the internal cursor of the scanner by one character and returns it. If the first character is $, we received a Bulk String as expected. Anything else is an error.

Redis accepts empty strings, and while it may be unusual, it is possible for a Redis key to be an empty string, and a value can also be an empty string. If the expected length is negative, then we stop and return a ProtocolError

The next step is extracting the actual string. StringScanner maintains an internal cursor of the progress through the string. At this point this cursor is right after CRLF, where the string content starts. StringScanner#rest returns the string from this cursor until the end, and using slice, we extract only the number of characters indicated by expected_length.

If the result of this operation is nil or shorter than the expected length, we don't want to treat it as an error yet, since it is possible for the clients to write the missing elements of the command, so we raise an IncompleteCommand, in the hope that the client will send the missing parts later on.

The final step is to advance the cursor position in the StringScanner instance. We do this with the StringScanner#pos= method. Notice how we use the bytesize methods and two to it. We use bytesize instead of length to handle characters that span over multiple bytes, such as CJK characters, accentuated characters, emojis and many others. Let's look at the difference in irb:

irb(main):045:1* def print_length_and_bytesize(str)
irb(main):046:1*   puts str.length
irb(main):047:1*   puts str.bytesize
irb(main):048:0> end
=> :print_length_and_bytesize
irb(main):049:0> print_length_and_bytesize('a')
1
1
=> nil
irb(main):050:0> print_length_and_bytesize('é')
1
2
=> nil
irb(main):051:0> print_length_and_bytesize('你')
1
3
=> nil
irb(main):058:0> print_length_and_bytesize('😬')
1
4
=> nil

As we can see, all of these strings return 1 for length, but different values, respectively 2, 3 & 4 for bytesize. Going into details about UTF-8 encoding is out of scope, but the main takeaway from this is that what we consider to be a single character, might span over multiple bytes.

If a client had sent 你 has a Bulk String, we'd expect it to pass the length as 3, and therefore we need to advance the cursor by 3 in the StringScanner instance. We also add two to account for the trailing CRLF characters. Note that, like Redis, we do not actually check that these two characters are indeed CR & LF, we just skip over them.

Updating the command responses

The commands we've implemented so far, GET, SET, TTL & PTTL do not return data that follows the format defined in RESP. GET needs to return Bulk Strings, SET returns the Simple String OK or the null Bulk String if it didn't set the value and the last two, TTL & PTTL, return integers. We will first create new classes to wrap the process of serializing strings and integers to their matching RESP format:

# resp_types.rb
module BYORedis
  # ...
  RESPInteger = Struct.new(:underlying_integer) do
    def serialize
      ":#{ underlying_integer }\r\n"
    end

    def to_i
      underlying_integer.to_i
    end
  end

  RESPSimpleString = Struct.new(:underlying_string) do
    def serialize
      "+#{ underlying_string }\r\n"
    end
  end

  OKSimpleStringInstance = Object.new.tap do |obj|
    OK_SIMPLE_STRING = "+OK\r\n".freeze
    def obj.serialize
      OK_SIMPLE_STRING
    end
  end

  RESPBulkString = Struct.new(:underlying_string) do
    def serialize
      "$#{ underlying_string.bytesize }\r\n#{ underlying_string }\r\n"
    end
  end

  NullBulkStringInstance = Object.new.tap do |obj|
    NULL_BULK_STRING = "$-1\r\n".freeze
    def obj.serialize
      NULL_BULK_STRING
    end
  end

  RESPArray = Struct.new(:underlying_array) do
    def serialize
      serialized_items = underlying_array.map do |item|
        case item
        when RESPSimpleString, RESPBulkString
          item.serialize
        when String
          RESPBulkString.new(item).serialize
        when Integer
          RESPInteger.new(item).serialize
        when Array
          RESPArray.new(item).serialize
        end
      end
      "*#{ underlying_array.length }\r\n#{ serialized_items.join }"
    end
  end
  NullArrayInstance = Object.new.tap do |obj|
    NULL_ARRAY = "*-1\r\n".freeze
    def obj.serialize
      NULL_ARRAY
    end
  end
end

listing 5.10 The new RESP types

RESPArray is not strictly required at the moment since none of the commands we've implemented so far return array responses, but the COMMAND command, which we'll implement below returns an array, so it'll be useful there.

We could have chosen a few different options to represent the null array and the null list, such as adding the logic in serialize methods of RESPArray & RESPBulkString. I instead decided to create two globally available instances that implement the same interface, the serialize method. This allows the code in server.rb to always call serialize on the result it gets from calling the call method. On the other hand, in the *Command classes, it forces us to explicitly handle these null cases, which I find preferable to passing nil values around.

We use the String#freeze method to prevent accidental modifications of the values at runtime. Ruby will throw an exception if you attempt to do so:

irb(main):001:0> require_relative './server'
=> true
irb(main):002:0> BYORedis::NULL_BULK_STRING
=> "$-1\r\n"
irb(main):003:0> BYORedis::NULL_BULK_STRING << "a"
Traceback (most recent call last):
        4: from /Users/pierre/.rbenv/versions/2.7.1/bin/irb:23:in `<main>'
        3: from /Users/pierre/.rbenv/versions/2.7.1/bin/irb:23:in `load'
        2: from /Users/pierre/.rbenv/versions/2.7.1/lib/ruby/gems/2.7.0/gems/irb-1.2.3/exe/irb:11:in `<top (required)>'
        1: from (irb):3
FrozenError (can't modify frozen String: "$-1\r\n")

That said, do note that "constants" in Ruby aren't really "constants", it is possible to reassign the value at runtime:

irb(main):004:0> BYORedis::NULL_BULK_STRING = "something else"
(irb):4: warning: already initialized constant BYORedis::NULL_BULK_STRING
/Users/pierre/dev/redis-in-ruby/code/chapter-5/resp_types.rb:32: warning: previous definition of NULL_BULK_STRING was here
irb(main):005:0> BYORedis::NULL_BULK_STRING
=> "something else"

While it doesn't prevent all kinds of weird runtime issues, I do like the use of String#freeze to at least be explicit about the nature of the value, signifying that it is not supposed to be modified.

The OK Simple String is so common that I created a constant for it, OKSimpleStringInstance, so that it can be reused instead of having to allocate a new instance every time we need it. Only the SetCommand class uses it for now, but more commands use it, such as LSET, MSET and many others.

Let's start with GET:

# get_command.rb
module BYORedis
  class GetCommand

    # ...

    def call
      if @args.length != 1
        RESPError.new("ERR wrong number of arguments for 'GET' command")
      else
        key = @args[0]
        ExpireHelper.check_if_expired(@data_store, @expires, key)
        value = @data_store[key]
        if value.nil?
          NullBulkStringInstance
        else
          RESPBulkString.new(value)
        end
      end
    end
  end
end

listing 5.11 Updated response in GetCommand

Now that BYORedis::GetCommand has been updated, let's tackle SetCommand:

# set_command.rb
def call
  key, value = @args.shift(2)
  if key.nil? || value.nil?
    return RESPError.new("ERR wrong number of arguments for 'SET' command")
  end

  parse_result = parse_options

  existing_key = @data_store[key]

  if @options['presence'] # ...
    NullBulkStringInstance
  elsif @options['presence'] # ...
    NullBulkStringInstance
  else

    # ...

    OKSimpleStringInstance
  end

rescue ValidationError => e
  RESPError.new(e.message)
rescue SyntaxError => e
  RESPError.new(e.message)
end

listing 5.12 Updated response in SetCommand

The SET command has two possible outputs, either the nil string if the outcome was that nothing was set, as a result of the NX or XX options, or the Simple String OK if the outcome was a successful set. This is where the special case instances NullBulkStringInstance & OKSimpleStringInstance come in handy. By returning them here, the code in server.rb can leverage duck typing and call the serialize method, but under the hood, the same strings will be used, BYORedis::OK_SIMPLE_STRING & BYORedis::NULL_BULK_STRING. This is a very small optimization, but given how common it is to call the SET command, it is interesting to think about things like that to prevent unnecessary work on the server.

And finally we need to update TtlCommand and PttlCommand

# pttl_command.rb
def call
  if @args.length != 1
    RESPError.new("ERR wrong number of arguments for 'PTTL' command")
  else
    key = @args[0]
    ExpireHelper.check_if_expired(@data_store, @expires, key)
    key_exists = @data_store.include? key
    value = if key_exists
              ttl = @expires[key]
              if ttl
                (ttl - (Time.now.to_f * 1000)).round
              else
                -1
              end
            else
              -2
            end
    RESPInteger.new(value)
  end
end

# ttl_command.rb
def call
  if @args.length != 1
    RESPError.new("ERR wrong number of arguments for 'TTL' command")
  else
    pttl_command = PttlCommand.new(@data_store, @expires, @args)
    result = pttl_command.call.to_i
    if result > 0
      RESPInteger.new((result / 1000.0).round)
    else
      RESPInteger.new(result)
    end
  end
end

listing 5.13 Updated response in PttlCommand & TtlCommand

Case insensitivity

It is not explicitly mentioned in the RESP v2 documentation, but Redis treats commands and options as case insensitive. The following examples are all valid: get 1, GeT 1, set key value EX 1 nx.

In order to apply the same handling logic, we changed the keys in the COMMANDS constant to be lower case, and we always lower case the client input when attempting to find a handler for the command:

# server.rb
COMMANDS = {
  'command' => CommandCommand,
  'get' => GetCommand,
  'set' => SetCommand,
  'ttl' => TtlCommand,
  'pttl' => PttlCommand,
}
# ...

def handle_client_command(command_parts)
  @logger.debug "Received command: #{ command_parts }"
  command_str = command_parts[0]
  args = command_parts[1..-1]

  command_class = COMMANDS[command_str.downcase]

  # ...
end

listing 5.14 Updates for case insensitivity in BYORedis::Server

We also need to update the BYORedis::SetCommand class to handle options regardless of the case chosen by clients:

# set_command.rb
# ...
OPTIONS = {
  'ex' => CommandOptionWithValue.new(
    'expire',
    ->(value) { validate_integer(value) * 1000 },
  ),
  'px' => CommandOptionWithValue.new(
    'expire',
    ->(value) { validate_integer(value) },
  ),
  'keepttl' => CommandOption.new('expire'),
  'nx' => CommandOption.new('presence'),
  'xx' => CommandOption.new('presence'),
}
#...
def parse_options
  while @args.any?
    option = @args.shift
    option_detail = OPTIONS[option.downcase]
    # ...
  end
end
#...

listing 5.15 Updates for case insensitivity in SetCommand

The COMMAND command

In order to implement COMMAND, we added a describe method to each of the *Command classes, so that the CommandCommand class can iterate over all these classes and call .describe on them, and then serialize the result to a RESP array:

# command_command.rb
module BYORedis
  class CommandCommand

    def initialize(_data_store, _expires, _args)
    end

    def call
      RESPArray.new(Server::COMMANDS.map { |_, command_class| command_class.describe } )
    end

    def self.describe
      [
        'command',
        -1, # arity
        # command flags
        [ 'random', 'loading', 'stale' ].map { |s| RESPSimpleString.new(s) },
        0, # position of first key in argument list
        0, # position of last key in argument list
        0, # step count for locating repeating keys
        # acl categories: https://github.com/antirez/redis/blob/6.0/src/server.c#L161-L166
        [ '@slow', '@connection' ].map { |s| RESPSimpleString.new(s) },
      ]
    end
  end
end

listing 5.16 The new CommandCommand class

# get_command.rb

def self.describe
  [
    'get',
    2, # arity
    # command flags
    [ 'readonly', 'fast' ].map { |s| RESPSimpleString.new(s) },
    1, # position of first key in argument list
    1, # position of last key in argument list
    1, # step count for locating repeating keys
    # acl categories: https://github.com/antirez/redis/blob/6.0/src/server.c#L161-L166
    [ '@read', '@string', '@fast' ].map { |s| RESPSimpleString.new(s) },
  ]
end

# pttl_command.rb

def self.describe
  [
    'pttl',
    2, # arity
    # command flags
    [ 'readonly', 'random', 'fast' ].map { |s| RESPSimpleString.new(s) },
    1, # position of first key in argument list
    1, # position of last key in argument list
    1, # step count for locating repeating keys
    # acl categories: https://github.com/antirez/redis/blob/6.0/src/server.c#L161-L166
    [ '@keyspace', '@read', '@fast' ].map { |s| RESPSimpleString.new(s) },
  ]
end

# set_command.rb

def self.describe
  [
    'set',
    -3, # arity
    # command flags
    [ 'write', 'denyoom' ].map { |s| RESPSimpleString.new(s) },
    1, # position of first key in argument list
    1, # position of last key in argument list
    1, # step count for locating repeating keys
    # acl categories: https://github.com/antirez/redis/blob/6.0/src/server.c#L161-L166
    [ '@write', '@string', '@slow' ].map { |s| RESPSimpleString.new(s) },
  ]
end

# ttl_command.rb

def self.describe
  [
    'ttl',
    2, # arity
    # command flags
    [ 'readonly', 'random', 'fast' ].map { |s| RESPSimpleString.new(s) },
    1, # position of first key in argument list
    1, # position of last key in argument list
    1, # step count for locating repeating keys
    # acl categories: https://github.com/antirez/redis/blob/6.0/src/server.c#L161-L166
    [ '@keyspace', '@read', '@fast' ].map { |s| RESPSimpleString.new(s) },
  ]
end

listing 5.17 Updates for the COMMAND command in SetCommand, GetCommand, TtlCommand & PttlCommand

test.rb & test_helper.rb

Testing the BYORedis::Server class is becoming more and more complicated, in order to keep things clean, I moved a lot of the helper method to the test_helper.rb file, so that test.rb only contains the actual tests.

The assert_command_results helper has been updated to handle the RESP format. For the sake of simplicity, it assumes that the data is not serialized and does that for you. This allows us to write simpler assertions such as:

assert_command_results [
  [ 'SET 1 3 NX EX 1', '+OK' ],
  [ 'GET 1', '3' ],
  [ 'SET 1 3 XX keepttl', '+OK' ],
]

and the assert_command_results will serialize the commands as RESP Arrays for us.

I also added a new assertion helper, assert_multipart_command_results. It allows a little bit more flexibility around expectations for commands sent through multiple write calls. Instead of being a single command like in assert_command_results, the first element of the pair is itself an array of strings, each of them representing a sequence of characters that will be sent to the server. This is handy to test pipelining as well as edge cases with regard to RESP.

# test_helper.rb
# The arguments in an array of array of the form
# [
#   [ [ "COMMAND-PART-I", "COMMAND-PART-II", ... ], "EXPECTED_RESULT" ],
#   ...
# ]
def assert_multipart_command_results(multipart_command_result_pairs)
  with_server do |server_socket|
    multipart_command_result_pairs.each do |command, expected_result|
      command.each do |command_part|
        server_socket.write command_part
        # Sleep for one milliseconds to give a chance to the server to read
        # the first partial command
        sleep 0.001
      end

      response = read_response(server_socket)

      if response.length < expected_result.length
        # If the response we got is shorter, maybe we need to give the server a bit more time
        # to finish processing everything we wrote, so give it another shot
        sleep 0.1
        response += read_response(server_socket)
      end

      assert_response(expected_result, response)
    end
  end
end

def assert_command_results(command_result_pairs)
  with_server do |server_socket|
    command_result_pairs.each do |command, expected_result|
      if command.is_a?(String) && command.start_with?('sleep')
        sleep command.split[1].to_f
        next
      end
      command_string = if command.start_with?('*')
                         command
                       else
                         BYORedis::RESPArray.new(command.split).serialize
                       end
      server_socket.write command_string

      response = read_response(server_socket)

      assert_response(expected_result, response)
    end
  end
end

def assert_response(expected_result, response)
  assertion_match = expected_result&.match(/(\d+)\+\/-(\d+)/)
  if assertion_match
    response_match = response.match(/\A:(\d+)\r\n\z/)
    assert response_match[0]
    assert_in_delta assertion_match[1].to_i, response_match[1].to_i, assertion_match[2].to_i
  else
    if expected_result && !%w(+ - : $ *).include?(expected_result[0])
      # Convert to a Bulk String unless it is a Simple String (starts with a +)
      # or an error (starts with -)
      expected_result = BYORedis::RESPBulkString.new(expected_result).serialize
    end

    if expected_result && !expected_result.end_with?("\r\n")
      expected_result += "\r\n"
    end

    if expected_result.nil?
      assert_nil response
    else
      assert_equal expected_result, response
    end
  end
end

def read_response(server_socket)
  response = ''
  loop do
    select_res = IO.select([ server_socket ], [], [], 0.1)
    last_response = server_socket.read_nonblock(1024, exception: false)
    if last_response == :wait_readable || last_response.nil? || select_res.nil?
      response = nil
      break
    else
      response += last_response
      break if response.length < 1024
    end
  end
  response&.force_encoding('utf-8')
rescue Errno::ECONNRESET
  response&.force_encoding('utf-8')
end

def to_query(*command_parts)
  [ BYORedis::RESPArray.new(command_parts).serialize ]
end

listing 5.18 The new test helpers in test_helper.rb

Conclusion

We can now use redis-cli, with redis-cli -p 2000 to interact with our redis server:

> redis-cli -p 2000
127.0.0.1:2000> COMMAND
1) 1) "command"
   2) (integer) -1
   3) 1) random
      2) loading
      3) stale
   4) (integer) 0
   5) (integer) 0
   6) (integer) 0
   7) 1) @slow
      2) @connection
2) 1) "get"
   2) (integer) 2
   3) 1) readonly
      2) fast
   4) (integer) 1
   5) (integer) 1
   6) (integer) 1
   7) 1) @read
      2) @string
      3) @fast
3) 1) "set"
   2) (integer) -3
   3) 1) write
      2) denyoom
   4) (integer) 1
   5) (integer) 1
   6) (integer) 1
   7) 1) @write
      2) @string
      3) @slow
4) 1) "ttl"
   2) (integer) 2
   3) 1) readonly
      2) random
      3) fast
   4) (integer) 1
   5) (integer) 1
   6) (integer) 1
   7) 1) @keyspace
      2) @read
      3) @fast
5) 1) "pttl"
   2) (integer) 2
   3) 1) readonly
      2) random
      3) fast
   4) (integer) 1
   5) (integer) 1
   6) (integer) 1
   7) 1) @keyspace
      2) @read
      3) @fast
127.0.0.1:2000> GET a-key
(nil)
127.0.0.1:2000> SET name pierre
OK
127.0.0.1:2000> GET name
"pierre"
127.0.0.1:2000> SET last-name J EX 10
OK
127.0.0.1:2000> TTL last-name
(integer) 6
127.0.0.1:2000> PTTL last-name
(integer) 5016
127.0.0.1:2000> PTTL last-name
(integer) 2432
127.0.0.1:2000> DEL name
(error) ERR unknown command `DEL`, with args beginning with: `name`,

All the commands we already implemented work as expected and non implemented commands such as DEL return an unknown command error. So far so good!

In the next chapter we'll write our own Hashing algorithm and ban the use of the Hash class in our code.

Code

As usual, the code is available on GitHub.