Merge pull request #331 from codecrafters-io/extract-stage-descriptions

Extract stage descriptions to markdown files

Author: Arpan-206

course-definition.yml

@@ -0,0 +1,26 @@
+In this stage, you'll implement a TCP server that listens on port 6379.
+
+[TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) is the underlying protocol used by protocols like HTTP, SSH and others
+you're probably familiar with. Redis clients & servers use TCP to communicate with each other.
+
+Don't worry if you're unfamiliar with the TCP protocol, or what Redis clients & servers are. You'll learn more about this in the
+next stages.
+
+### Tests
+
+The tester will execute your program like this:
+
+```bash
+$ ./your_program.sh
+```
+
+It'll then try to connect to your TCP server on port 6379. If the connection succeeds, you'll pass this stage.
+
+### Notes
+
+- 6379 is the default port that Redis uses.
+- If you already have a Redis server running on your machine and listening on port 6379, you'll see a "port already in use" error when running your code. Try stopping the existing Redis server and running your code again.
+
+{{#reader_is_bot}}
+- In this stage, you can assume that you only need to handle a single client. We'll get to handling multiple clients & multiple requests per client in later stages.
+{{/reader_is_bot}}

stage_descriptions/base-01-jm1.md

@@ -0,0 +1,34 @@
+In this stage, you'll implement support for the [PING](https://redis.io/commands/ping) command.
+
+Redis clients communicate with Redis servers by sending "[commands](https://redis.io/commands/)". For each command, a Redis server sends a response back to the client.
+Commands and responses are both encoded using the [Redis protocol](https://redis.io/topics/protocol) (we'll learn more about this in later stages).
+
+[PING](https://redis.io/commands/ping/) is one of the simplest Redis commands. It's used to check whether a Redis server is healthy.
+
+The response for the `PING` command is `+PONG\r\n`. This is the string "PONG" encoded using the [Redis protocol](https://redis.io/docs/reference/protocol-spec/).
+
+In this stage, we'll cut corners by ignoring client input and hardcoding `+PONG\r\n` as a response. We'll learn to parse client input in later stages.
+
+### Tests
+
+The tester will execute your program like this:
+
+```bash
+$ ./your_program.sh
+```
+
+It'll then send a `PING` command to your server and expect a `+PONG\r\n` response.
+
+```bash
+$ redis-cli PING
+```
+
+Your server should respond with `+PONG\r\n`, which is "PONG" encoded as a [RESP simple string](https://redis.io/docs/reference/protocol-spec/#resp-simple-strings).
+
+### Notes
+
+- You can ignore the data that the tester sends you for this stage. We'll get to parsing
+client input in later stages. For now, you can just hardcode `+PONG\r\n` as the response.
+- You can also ignore handling multiple clients and handling multiple PING commands in the stage, we'll get to that in later stages.
+- The exact bytes your program will receive won't be just `PING`, you'll receive something like this: `*1\r\n$4\r\nPING\r\n`,
+which is the Redis protocol encoding of the `PING` command. We'll learn more about this in later stages.

stage_descriptions/base-02-rg2.md

@@ -0,0 +1,39 @@
+In this stage, you'll respond to multiple
+[PING](https://redis.io/commands/ping) commands sent by the same connection.
+
+A Redis server starts to listen for the next command as soon as it's done responding to the previous one. This allows
+Redis clients to send multiple commands using the same connection.
+
+### Tests
+
+The tester will execute your program like this:
+
+```bash
+$ ./your_program.sh
+```
+
+It'll then send multiple PING commands using the same connection. For example, it might send:
+
+```bash
+$ echo -e "PING\nPING" | redis-cli
+```
+
+The tester will expect to receive multiple `+PONG\r\n` responses (one for each command sent).
+
+{{#lang_is_javascript}}
+In most languages, you'd need to run a loop that reads input from a connection and sends a
+response back. In JavaScript however, if you're listening to the
+[`data`](https://nodejs.org/api/net.html#net_event_data) event, this should be automatically handled for you. **It
+is very likely that the code you had for the previous stage will pass this stage without any changes!**
+{{/lang_is_javascript}}
+
+{{^lang_is_javascript}}
+You'll need to run a loop that reads input from a connection and sends a
+response back.
+{{/lang_is_javascript}}
+
+### Notes
+
+- Just like the previous stage, you can hardcode `+PONG\r\n` as the response for this stage. We'll get to parsing
+ client input in later stages.
+- The PING commands will be sent using the same connection. We'll get to handling multiple connections in later stages.

stage_descriptions/base-03-wy1.md

@@ -0,0 +1,41 @@
+In this stage, you'll add support for multiple concurrent clients.
+
+In addition to handling multiple commands from the same client, Redis servers are also designed to handle multiple clients at once.
+
+{{#lang_is_javascript}}
+In most languages, you'd need to either use threads or implement an
+[Event Loop](https://en.wikipedia.org/wiki/Event_loop) to do this. In JavaScript however, since [the concurrency
+model itself is based on an event loop](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop), most
+standard library functions are designed to support this kind of concurrent behaviour out of the box. **It is very
+likely that the code you had for the previous stage will pass this stage without any changes!**
+{{/lang_is_javascript}}
+
+{{^lang_is_javascript}}
+To implement this, you'll need to either use threads, or, if you're feeling
+adventurous, an [Event Loop](https://en.wikipedia.org/wiki/Event_loop) (like
+the official Redis implementation does).
+{{/lang_is_javascript}}
+
+### Tests
+
+The tester will execute your program like this:
+
+```bash
+$ ./your_program.sh
+```
+
+It'll then send two PING commands concurrently using two different connections:
+
+```bash
+# These two will be sent concurrently so that we test your server's ability to handle concurrent clients.
+$ redis-cli PING
+$ redis-cli PING
+```
+
+The tester will expect to receive two `+PONG\r\n` responses.
+
+### Notes
+
+- Since the tester client _only_ sends the PING command at the moment, it's okay to
+  ignore what the client sends and hardcode a response. We'll get to parsing
+  client input in later stages.

stage_descriptions/base-04-zu2.md

@@ -0,0 +1,36 @@
+In this stage, you'll add support for the [ECHO](https://redis.io/commands/echo) command.
+
+`ECHO` is a command like `PING` that's used for testing and debugging. It accepts a single argument and returns it back as a
+RESP bulk string.
+
+```bash
+$ redis-cli PING # The command you implemented in previous stages
+PONG
+$ redis-cli ECHO hey # The command you'll implement in this stage
+hey
+```
+
+### Tests
+
+The tester will execute your program like this:
+
+```bash
+$ ./your_program.sh
+```
+
+It'll then send an `ECHO` command with an argument to your server:
+
+```bash
+$ redis-cli ECHO hey
+```
+
+The tester will expect to receive `$3\r\nhey\r\n` as a response (that's the string `hey` encoded as a [RESP bulk string](https://redis.io/docs/reference/protocol-spec/#bulk-strings).
+
+### Notes
+
+- We suggest that you implement a proper Redis protocol parser in this stage. It'll come in handy in later stages.
+- Redis command names are case-insensitive, so `ECHO`, `echo` and `EcHo` are all valid commands.
+- The tester will send a random string as an argument to the `ECHO` command, so you won't be able to hardcode the response to pass this stage.
+- The exact bytes your program will receive won't be just `ECHO hey`, you'll receive something like this: `*2\r\n$4\r\nECHO\r\n$3\r\nhey\r\n`. That's
+  `["ECHO", "hey"]` encoded using the [Redis protocol](https://redis.io/docs/reference/protocol-spec/).
+- You can read more about how "commands" are handled in the Redis protocol [here](https://redis.io/docs/reference/protocol-spec/#sending-commands-to-a-redis-server).

stage_descriptions/base-05-qq0.md

@@ -0,0 +1,44 @@
+In this stage, you'll add support for the [SET](https://redis.io/commands/set) &
+[GET](https://redis.io/commands/get) commands.
+
+The `SET` command is used to set a key to a value. The `GET` command is used to retrieve the value of a key.
+
+```bash
+$ redis-cli SET foo bar
+OK
+$ redis-cli GET foo
+bar
+```
+
+The `SET` command supports a number of extra options like `EX` (expiry time in seconds), `PX` (expiry time in milliseconds) and more. We
+won't cover these extra options in this stage. We'll get to them in later stages.
+
+### Tests
+
+The tester will execute your program like this:
+
+```bash
+./your_program.sh
+```
+
+It'll then send a `SET` command to your server:
+
+```bash
+$ redis-cli SET foo bar
+```
+
+The tester will expect to receive `+OK\r\n` as a response (that's the string `OK` encoded as a [RESP simple string](https://redis.io/docs/reference/protocol-spec/#resp-simple-strings)).
+
+This command will be followed by a `GET` command:
+
+```bash
+$ redis-cli GET foo
+```
+
+The tester will expect to receive `$3\r\nbar\r\n` as a response (that's the string `bar` encoded as a [RESP bulk string](https://redis.io/docs/reference/protocol-spec/#bulk-strings).
+
+### Notes
+
+- If you implemented a proper Redis protocol parser in the previous stage, you should be able to reuse it in this stage.
+- Just like the previous stage, the values used for keys and values will be random, so you won't be able to hardcode the response to pass this stage.
+- If a key doesn't exist, the `GET` command should return a "null bulk string" (`$-1\r\n`). We won't explicitly test this in this stage, but you'll need it for the next stage (expiry).

stage_descriptions/base-06-la7.md

@@ -0,0 +1,50 @@
+In this stage, you'll add support for setting a key with an expiry.
+
+The expiry for a key can be provided using the "PX" argument to the [SET](https://redis.io/commands/set) command. The expiry is provided in milliseconds.
+
+```bash
+$ redis-cli SET foo bar px 100 # Sets the key "foo" to "bar" with an expiry of 100 milliseconds
+OK
+```
+
+After the key has expired, a `GET` command for that key should return a "null bulk string" (`$-1\r\n`).
+
+{{#lang_is_haskell}}
+The [time](https://hackage.haskell.org/package/time) package is available
+to use as a dependency.
+{{/lang_is_haskell}}
+
+### Tests
+
+The tester will execute your program like this:
+
+```bash
+$ ./your_program.sh
+```
+
+It'll then send a `SET` command to your server to set a key with an expiry:
+
+```bash
+$ redis-cli SET foo bar px 100
+```
+
+It'll then immediately send a `GET` command to retrieve the value:
+
+```bash
+$ redis-cli GET foo
+```
+
+It'll expect the response to be `bar` (encoded as a RESP bulk string).
+
+It'll then wait for the key to expire and send another `GET` command:
+
+```bash
+$ sleep 0.2 && redis-cli GET foo
+```
+
+It'll expect the response to be `$-1\r\n` (a "null bulk string").
+
+### Notes
+
+- Just like command names, command arguments are also case-insensitive. So `PX`, `px` and `pX` are all valid.
+- The keys, values and expiry times used in the tests will be random, so you won't be able to hardcode a response to pass this stage.