# Our Network Protocol Documentation

## Overview
Our protocol is inspired by *POP3*, but has been highly customized to fit our specific needs.
It is a text-based protocol operating over raw TCP sockets, designed for human readability and strict structure.

## Packet Structure
Each network packet consists of:
- **4-byte header**: Specifies the size of the payload (big-endian integer).
- **4-byte request ID**: Generated by the client, used to match requests and responses.
- **Payload**: The actual data, its size as specified by the header.

This structure is used for both requests and responses.

## Conventions
- All keys (in both requests and responses) use UPPER_SNAKE_CASE.
- Only a-z, A-Z, 0-9 are allowed in keys.
- Only human-readable strings are transmitted.
- Binary data is not allowed.

## Request Format
A request consists of a single line:

```
COMMAND KEY1=ARG1 KEY2=ARG2
```

- **COMMAND**: The action to perform.
- **KEY=VALUE pairs**: Optional parameters. There may be zero or more.
- **Whitespace**: Extra spaces between key, separator, and value are ignored. Any other characters between them are an error.
- **Standalone values**: Not allowed. Every value must have a key.

### String Values
- Strings with spaces must be enclosed in single quotes: `'example string'`.
- Inside quoted strings, line breaks are allowed.
- To include a single quote inside a string, escape it (e.g., `'It\'s fine'`).

If these rules are violated, the request is considered invalid and will be rejected.

## Response Format
Responses are more complex and can represent nested collections.

- **Success**: Starts with `+OK`
- **Error**: Starts with `-ERR`
- After the status, a newline follows, then fields in the format `KEY=VALUE`.
- Collections and elements are ended with the `END` keyword.
- A collection starts with a key, and its elements are indented.
- A element starts with a key, and its fields are indented.

### Example: Nested Collection
```
+OK
    KEY1=VALUE1
    FIELDS
        FIELD
            NESTED_KEY=NESTED_VALUE
        END
    END
    KEY2=VALUE2
END
```

## Error Handling
Any violation of the format (invalid characters, unescaped quotes, binary data, etc.) results in the request being rejected with an error response.

### Example Error Response When Violating Syntax Rules:
```
-ERR
    CODE=PARSING_ERROR
    MSG='Error occured during parsing. Likely due to malformed payload.'
END
```