Programmierprojekt/documents/docs/networking/commands/protocol-document.md

Protocol Document

This document describes the protocol for client-server communication in our application. It defines the structure of requests and responses, the supported commands along with their request parameters, response formats, and possible errors.

Table of Contents

• Protocol Document
• Table of Contents
• General structure of requests
• Preconditions
  • Parsing
    • Error Response
  • Command dispatching
    • Error Response
  • Command parsing
    • Error Response
• Pre-execution checks
  • UserLoggedInCheck
    • Error Response
• Commands
  • PING command
    • Required pre-execution checks
    • Request Parameters
    • Success Response
    • Example Request
    • Example Response
  • CHECK_USERNAME command
    • Required pre-execution checks
    • Request Parameters
    • Success Response
    • Example Request
    • Example Response
  • LOGIN command
    • Required pre-execution checks
    • Request Parameters
    • Success Response
    • Error Response
    • Example Request
    • Example Response
  • LOGOUT command
    • Required pre-execution checks
    • Request Parameters
    • Success Response
    • Error Response
    • Example Request
    • Example Response
  • LIST_USERS command
    • Required pre-execution checks
    • Request Parameters
    • Success Response
    • Error Response
    • Example Request
    • Example Response

General structure of requests

As mentioned before, our protocol is based on POP3. Each command is represented as a single line of text, starting with the command name followed by parameters. The server responds with a status line indicating success or failure, followed by the body.

Requests can have parameters that provide additional information for the command. Parameters are key-value pairs separated by an equal sign (=).

Responses are collections of key-value pairs, containing either a value or another collection, allowing for nested structures. Each collection is ended with the END keyword.

Preconditions

The serverside pipeline to process incoming requests consists of multiple stages. Each of these stages can yield an error response if the request does not meet the requirements of that stage.

Parsing

One of these stages is the parsing. It is responsible for parsing the raw request into a structured format that can be easily processed by the command handlers. It validates the syntax of the request as well.

Error Response

Code	Description
PARSING_ERROR	The body of the request contains syntax errors (see message field of response for more details)

Command dispatching

After the request has been successfully parsed, the next stage is to dispatch the PrimitiveRequest to the appropriate CommandParser. This is done by the CommandDispatcherDispatcher, which uses the command name to determine which parser to use.

Error Response

Code	Description
UNKNOWN_COMMAND	The command is unknown to this server. No parser has been defined

Command parsing

Once the PrimitiveRequest has been dispatched to the appropriate CommandParser, the parser is responsible for parsing the parameters of the request and creating a Request that can be executed by the responsible CommandHandler.

Error Response

Code	Description
MISSING_PARAMETER	A required parameter is missing from the request (see message field of response for more details)

Pre-execution checks

Pre-execution checks are reusable validation steps that can be registered on command handlers. They are implemented as HandlerCheck instances and are executed by the CommandHandlerExecutor before the handler's main logic is invoked.

UserLoggedInCheck

The UserLoggedInCheck is a common pre-execution check that verifies whether the user is logged in (i.e. has a user associated with his session).

Error Response

Code	Description
USER_NOT_LOGGED_IN	The user is not logged in

Commands

Commands are the core of our protocol, representing the various actions that clients can request from the server. Each command has a unique name and may require specific parameters in addition to pre-execution checks. The server processes these commands and responds accordingly.

PING command

The PING command is a simple command that can be used to check if the server is responsive.

Required pre-execution checks

None.

Request Parameters

No parameters.

Success Response

No response fields.

Example Request

PING

Example Response

+OK
END

CHECK_USERNAME command

The CHECK_USERNAME command is used to check if a username is already taken by another user. Additional users can still log in with the same username, but their name will be substituted with a suffix.

Required pre-execution checks

None.

Request Parameters

Parameter Name	Type	Optional	Description
USERNAME	String	no	The username to check for availability

Success Response

Field	Type	Description
STATUS	Enum<UsernameAvailability>	Member of enum indicating if the username is available or already taken

Members of UsernameAvailability	Description
FREE	Username is available
TAKEN	Username is already in use

Example Request

CHECK_USERNAME USERNAME='Lars'

Example Response

+OK 
  STATUS=FREE
END

LOGIN command

The LOGIN command is used to log in a user with a specified username. If the username is already taken by another user, the server will append a suffix to the username to make it unique.

Required pre-execution checks

None.

Request Parameters

Parameter Name	Type	Optional	Description
USERNAME	String	no	The username to create the user with

Success Response

Field	Type	Description
USERNAME	String	Username of the newly created user, can differ from the requested one
ID	UUID	The ID of the created user

Error Response

Code	Description
ALREADY_LOGGED_IN	The session is already associated with a user, logging in again is prohibited.

Example Request

LOGIN USERNAME='Lars'

Example Response

+OK
  USERNAME='Lars_1234'
  ID=e47a671e-2b2a-42df-bb82-953fe2ebd307
END

LOGOUT command

Description of the command, what it does, and when it should be used.

Required pre-execution checks

None.

Request Parameters

No parameters.

Success Response

No response fields.

Error Response

Code	Description
NO_USER_ASSOCIATED	The session has no user associated, logging out is not possible.

Example Request

LOGOUT

Example Response

+OK
END

LIST_USERS command

The LIST_USERS command is used to retrieve a list of all currently logged-in users.

Required pre-execution checks

None.

Request Parameters

No parameters.

Success Response

Field	Type	Description
USERS	Collection<User>	Collection of all users currently online

Fields of User	Type	Description
USERNAME	String	Username of the newly created user, can differ from the requested one
ID	UUID	The ID of the created user

Error Response

None.

Example Request

LIST_USERS

Example Response

+OK
  USERS
    USER
      USERNAME=Lars_001
      ID=56765d0f-8cd3-4eec-91b2-7e36265c1a5d
    END
    USER
      USERNAME=Lars_002
      ID=b7bbd9b3-0d49-4c92-8306-b1c8506d2ff0
    END
    USER
      USERNAME=Lars
      ID=982bc78e-547f-495a-a821-433a3603f92c
    END
  END
END

SEND_MESSAGE command

The SEND_MESSAGE command is used to transfer the chat message sent by a user to the server.

Required pre-execution checks

None.

Request Parameters

Field	Type	Description
TYPE	Enum<ChatType	GLOBAL, LOBBY or WHISPER, specifying the Chat
GAME	int	ID for identifying the Lobby Chat
USER	String	Username of the player that sent the message
TARGET	String	Username of to which the message is sent to (only in Whisper Chat)
TIME	String	Timestamp, when the message was sent
TEXT	String	Content of the message

Success Response

No response fields.

Error Response

None.

Example Request

SEND_MESSAGE TYPE=GLOBAL GAME=1 USER=player1 TARGET=null TIME='10:30' TEXT='Hello World'

Example Response

+OK
END

GET_MESSAGE_COUNT command

The GET_MESSAGE_COUNT is used to get the current number of messages that are stored in the queue for a client.

Required pre-execution checks

None.

Request Parameters

No parameters.

Success Response

Field	Type	Description
COUNT	int	The current number of messages

Error Response

Code	Description
NO_USER_ASSOCIATED	The session has no user associated, there is no queue of messages for the client

Example Request

GET_MESSAGE_COUNT

Example Response

+OK
COUNT=10
END

GET_NEXT_MESSAGE command

The GET_NEXT_MESSAGE command is used to get the next message stored in a queue for the client.

Required pre-execution checks

None.

Request Parameters

No parameters.

Success Response

Field	Type	Description
TYPE	Enum<ChatType	GLOBAL, LOBBY or WHISPER, specifying the Chat
GAME	int	ID for identifying the Lobby Chat
USER	String	Username of the player that sent the message
TARGET	String	Username of to which the message is sent to (only in Whisper Chat)
TIME	String	Timestamp, when the message was sent
TEXT	String	Content of the message

Error Response

Code	Description
NO_USER_ASSOCIATED	The session has no user associated, there is no queue of messages for the client

Example Request

GET_NEXT_MESSAGE

Example Response

+OK
TYPE=GLOBAL GAME=-1 USER=player1 TARGET=null TIME=9:30 TEXT="Guten Tag"
END