Programmierprojekt/documents/docs/our-protocol.md

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