#559: docs: docs for protocols (#847)

Co-authored-by: Jyotinder Singh <jyotindrsingh@gmail.com>

docs/astro.config.mjs

@@ -28,6 +28,10 @@ export default defineConfig({
           label: "Commands",
           autogenerate: { directory: "commands" },
         },
+        {
+          label: "Connection Protocols",
+          autogenerate: { directory: "protocols" },
+        },
         {
           label: "Metrics",
           items: [

docs/src/content/docs/commands/QWATCH.md

@@ -7,6 +7,14 @@ The `QWATCH` command is a novel feature designed to provide real-time updates to
 
 This command is what makes DiceDB different from Redis and uniquely positions it as the easiest and most intuitive way to build real-time reactive applications like leaderboards.
 
+## Protocol Support
+
+| Protocol | Supported |
+| -------- | --------- |
+| TCP-RESP | ✅        |
+| HTTP     | ✅        |
+| WebSocket| ❌        |
+
 ## Syntax
 
 ```

docs/src/content/docs/get-started/connecting-to-dice.mdx

@@ -0,0 +1,75 @@
+--- 
+title: Connecting to DiceDB
+description: A guide on all the protocols that dice supports and all ways to connect to dice.
+sidebar:
+  order: 3
+---
+
+DiceDB supports 3 ways to connect to the database:
+1. [TCP-RESP](#tcp-resp)
+2. [HTTP](#http)
+3. [WebSockets](#websockets)
+
+## TCP-RESP
+
+RESP is a standard protocol over TCP, developed by redis. This is the default mode of communication with dicedb and allows dice to be a drop-in replacement for Redis. 
+
+
+| Name | Value | Configuration | 
+|-|-|-|
+| Default Port | 7379 | `server.port` in config file |
+
+To use Dice over TCP/RESP, you can use the official [DiceDB CLI](https://github.com/DiceDB/cli) or use any Redis CLI/SDKs for non-dice features.
+
+## HTTP
+
+Clients can also connect to DiceDB over HTTP. This allows clients to connect to dice over the web stack, enabling frontends to have direct access to dice.
+
+
+| Name | Value | Configuration | 
+|-|-|-|
+| Default Port | 8082 | `--http-port` flag |
+
+For all commands except `QWATCH`, the HTTP API is synchronous and will return the result of the command immediately. 
+
+For [`QWATCH`](/commands/qwatch), we use [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to be able to respond with changes to the result set of the queries.
+
+To understand the request and response format better, please refer to the [HTTP Protocol](/protocols/http) documentation.
+
+### When to use HTTP
+
+- To connect to dice from a web frontend.
+- When you do not have access to a raw TCP connection.
+- With small number of queries you want to `QWATCH`.
+- Integrate dice with other web services using HTTP Webhooks.
+
+
+### Limitations
+
+- `QWATCH` uses SSE or Server Sent Events, and current implementation of HTTP in DiceDB is based on HTTP 1.1. This means that there would be a limit to how many queries you can `QWATCH` at a time ([ref](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)).
+- `QWATCH` using SSE also implies that the connection is stateful and the client needs to handle reconnections in case of network failures.
+
+
+## WebSockets
+
+WebSockets protocol on DiceDB allows clients to connect to dice over a persistent websocket connection. This allows clients to connect to dice over the web while also being able to bypass the limitations of SSE. Websocket being a full-duplex protocol, allows clients to send and receive messages simultaneously.
+
+
+| Name | Value | Configuration |
+|-|-|-|
+| Default Port | 8379 | `--websocket-port` flag |
+
+To understand the request and response format better, please refer to the [WebSockets Protocol](/protocols/websockets) documentation.
+
+### When to use WebSockets
+
+- To connect to dice from a web frontend and maintain a persistent connection.
+- To `QWATCH` a large number of queries.
+- In cases wher you need large amount/high frequency of live updates being pushed from dice to the client.
+- To build real-time applications with high frequency of updates like collaborative editing, real-time gaming, etc.
+
+### Limitations
+
+- WebSockets are not supported in all browsers. Please refer to the [MDN WebSockets documentation](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for more information.
+- WebSockets are stateful connections and need to be managed by the client. This means that the client needs to handle reconnections in case of network failures.
+- In case of faster updates than the client can handle, the standard WebSocket from the browser does not implement a built-in backpressure mechanism. This means the device memory can fill up until the client handles the messages.

docs/src/content/docs/protocols/http.mdx

@@ -0,0 +1,139 @@
+--- 
+title: HTTP
+description: DiceDB supports HTTP protocol for clients to connect to the database. This document explains the request and response format.
+sidebar:
+  order: 1
+---
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [API Endpoint](#api-endpoint)
+3. [General Request Structure](#general-request-structure)
+4. [Supported Commands](#supported-commands)
+5. [Examples](#examples)
+
+## Introduction
+
+DiceDB supports HTTP protocol for clients to connect to the database. This allows clients to connect to DiceDB over the web stack, enabling frontends to have direct access to DiceDB, which is currently not possible with Redis.
+
+All commands except `QWATCH` are synchronous and will return the result of the command immediately. For `QWATCH`, we use [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to be able to respond with changes to the result set of the queries.
+
+
+## API Endpoint
+
+All requests should be sent to the base URL of your server, followed by the command name:
+
+```
+http://your-server-address:port/<command>
+```
+
+## General Request Structure
+
+- **HTTP Method**: POST for all operations
+- **Path**: The DiceDB command name (e.g., `/GET`, `/SET`, `/HGET`)
+- **Headers**: 
+  - `Content-Type: application/json`
+- **Body**: JSON object containing command arguments
+
+### Query Parameters
+
+Certain commands may require additional query parameters. For example:
+
+- `key_prefix`: Used for the `JSON.INGEST` command to specify a key prefix
+
+These will be specified in the command documentation.
+
+## Supported Commands
+
+Our HTTP API supports all DiceDB commands. Please refer to our comprehensive command reference for each command, commands which lack support will be flagged as such.
+
+## Examples
+
+### Setting a Key-Value Pair
+
+**Request:**
+```http
+POST /SET HTTP/1.1
+Host: your-server-address
+Content-Type: application/json
+
+{
+  "key": "mykey",
+  "value": "Hello, World!"
+}
+```
+
+**Response:**
+```json
+"OK"
+```
+
+### Getting a Value
+
+**Request:**
+```http
+POST /GET HTTP/1.1
+Host: your-server-address
+Content-Type: application/json
+
+{
+  "key": "mykey"
+}
+```
+
+**Response:**
+```json
+"Hello, World!"
+```
+
+### Setting a field in Hash
+
+```http
+POST http://localhost:8082/hset HTTP/1.1
+Content-Type: application/json
+
+{
+	"key": "test",
+	"field": "test",
+	"value": "test"
+}
+```
+
+**Response:**
+```json
+1
+```
+
+### Getting a field in a HashSet
+
+```http
+POST http://localhost:8082/hget HTTP/1.1
+Content-Type: application/json
+
+{
+  "key": "test",
+  "field": "test"
+}
+```
+
+**Response:**
+```json
+"test"
+```
+
+### QWATCH Example
+
+**NOTE**: The `QWATCH` command is asynchronous and requires the use of Server-Sent Events (SSE) to receive updates. The following example demonstrates how to use `QWATCH` with SSE.
+
+**Request:**
+```http
+POST /QWATCH HTTP/1.1
+Host: your-server-address
+Content-Type: application/json
+
+{
+  "query": "SELECT $key, $value WHERE $key like 'match:100:*' AND $value > 10 ORDER BY $value DESC LIMIT 3"
+}
+```
+

docs/src/content/docs/protocols/websockets.mdx

@@ -0,0 +1,75 @@
+--- 
+title: WebSockets
+description: DiceDB supports WebSocket protocol for clients to connect to the database. This document explains the request and response format.
+sidebar:
+  order: 2
+---
+
+## Introduction
+
+DiceDB supports WebSocket for connecting to the database, allowing for real-time, bidirectional communication between the client and the server. This can be particularly useful for applications that require low-latency, high-frequency updates.
+
+## Connecting to the WebSocket Server
+
+To connect to the WebSocket server, use the following URL:
+
+```
+ws://your-server-address:port/
+```
+
+Replace `your-server-address` and `port` with the appropriate values for your server.
+
+## Message Format
+
+WebSocket messages should be sent as plain text, following this format:
+
+```
+COMMAND arg1 arg2 arg3 ...
+```
+
+- The command should be in uppercase.
+- Arguments should be separated by spaces.
+- For commands that require JSON data, include it as the last argument.
+
+This is very similar to what you'd type in the DiceDB CLI.
+
+## Supported Commands
+
+All DiceDB commands are supported over the WebSocket protocol. If some commands are not supported, they will be flagged as such in the command documentation.
+
+For more information on specific commands and their usage, please refer to the command documentation, keeping in mind the WebSocket-specific formatting requirements outlined in this guide.
+
+### Special Commands
+
+- `ABORT`: This command will shut down the WebSocket server.
+
+## Responses
+
+Responses are sent back through the WebSocket connection as JSON-encoded data. The structure of the response will depend on the command executed.
+
+## Example Usage
+
+Here's a simple example of how to interact with the WebSocket server using JavaScript:
+
+```javascript
+const ws = new WebSocket('ws://your-server-address:port/ws');
+
+ws.onopen = function() {
+    console.log('Connected to WebSocket server');
+
+    // Set a key
+    ws.send('SET mykey "Hello, WebSocket!"');
+};
+
+ws.onmessage = function(event) {
+    console.log('Received:', event.data);
+};
+
+ws.onerror = function(error) {
+    console.error('WebSocket Error:', error);
+};
+
+ws.onclose = function(event) {
+    console.log('WebSocket connection closed:', event.code, event.reason);
+};
+```