University-of-Basel-Studentprojects/Programmierprojekt
Archived
1
0
Fork 0
Code Issues 17 Pull Requests Actions Wiki Activity

Write protocol document outline and document existing commands #245

Merged
lars.winzer merged 6 commits from chore/61-write-protocol-document into main 2026-04-09 14:46:13 +02:00
Conversation 1 Commits 6 Files Changed 2
+21 -21
1 changed files with 21 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 5e15ad359d - Show all commits
documents/docs/networking/commands/protocol-document.md
+21 -21
View File
@@ -1,5 +1,5 @@
# Protocol Document # 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 thier request parameters, response formats and possible errors. 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 # Table of Contents
@@ -13,7 +13,7 @@ This document describes the protocol for client-server communication in our appl
- [Error Response](#error-response-1) - [Error Response](#error-response-1)
- [Command parsing](#command-parsing) - [Command parsing](#command-parsing)
- [Error Response](#error-response-2) - [Error Response](#error-response-2)
- [Pre executions checks](#pre-executions-checks) - [Pre-execution checks](#pre-execution-checks)
- [UserLoggedInCheck](#userloggedincheck) - [UserLoggedInCheck](#userloggedincheck)
- [Error Response](#error-response-3) - [Error Response](#error-response-3)
- [Commands](#commands) - [Commands](#commands)
@@ -29,7 +29,7 @@ This document describes the protocol for client-server communication in our appl
- [Success Response](#success-response-1) - [Success Response](#success-response-1)
- [Example Request](#example-request-1) - [Example Request](#example-request-1)
- [Example Response](#example-response-1) - [Example Response](#example-response-1)
- [LOGIN comamnd](#login-comamnd) - [LOGIN command](#login-command)
- [Required pre-execution checks](#required-pre-execution-checks-2) - [Required pre-execution checks](#required-pre-execution-checks-2)
- [Request Parameters](#request-parameters-2) - [Request Parameters](#request-parameters-2)
- [Success Response](#success-response-2) - [Success Response](#success-response-2)
@@ -44,13 +44,13 @@ This document describes the protocol for client-server communication in our appl
- [Example Request](#example-request-3) - [Example Request](#example-request-3)
- [Example Response](#example-response-3) - [Example Response](#example-response-3)
<!-- Plase see the comments for copy n' paste ready examples --> <!-- Please see the comments for copy ‚ n' paste ready examples -->
# General structure of requests # General structure of requests
As mentioned before, our protocol is based on POP3. 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. 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 a equal sign (`=`). 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. 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. Each collection is ended with the `END` keyword.
@@ -58,14 +58,14 @@ Each collection is ended with the `END` keyword.
# Preconditions # Preconditions
The serverside pipeline to process incomming requests consists of multiple stages. 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. Each of these stages can yield an error response if the request does not meet the requirements of that stage.
## Parsing ## 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 aswell. 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 ### Error Response
| Code | Discription | | Code | Description |
| :-------------- | :---------------------------------------------------------------------------------------------- | | :-------------- | :---------------------------------------------------------------------------------------------- |
| `PARSING_ERROR` | The body of the request contains syntax errors (see message field of response for more details) | | `PARSING_ERROR` | The body of the request contains syntax errors (see message field of response for more details) |
@@ -74,7 +74,7 @@ One of these stages is the parsing. It is responsible for parsing the raw reques
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. 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 ### Error Response
| Code | Discription | | Code | Description |
| :---------------- | :---------------------------------------------------------------- | | :---------------- | :---------------------------------------------------------------- |
| `UNKNOWN_COMMAND` | The command is unknown to this server. No parser has been defined | | `UNKNOWN_COMMAND` | The command is unknown to this server. No parser has been defined |
@@ -83,13 +83,13 @@ After the request has been successfully parsed, the next stage is to dispatch th
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`. 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 ### Error Response
| Code | Discription | | Code | Description |
| :------------------ | :------------------------------------------------------------------------------------------------ | | :------------------ | :------------------------------------------------------------------------------------------------ |
| `MISSING_PARAMETER` | A required parameter is missing from the request (see message field of response for more details) | | `MISSING_PARAMETER` | A required parameter is missing from the request (see message field of response for more details) |
# Pre executions checks # Pre-execution checks
Pre-execution checks are reusable validation steps that can be registered on command handlers. 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. They are implemented as `HandlerCheck` instances and are executed by the `CommandHandlerExecutor` before the handler's main logic is invoked.
@@ -98,7 +98,7 @@ They are implemented as `HandlerCheck` instances and are executed by the `Comman
Description of the check, what it does and when it should be used. Description of the check, what it does and when it should be used.
### Response if not met ### Response if not met
| Code | Discription | | Code | Description |
| :----------- | :----------------------- | | :----------- | :----------------------- |
| `ERROR_CODE` | Description of the error | | `ERROR_CODE` | Description of the error |
--> -->
@@ -107,7 +107,7 @@ Description of the check, what it does and when it should be used.
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). 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 ### Error Response
| Code | Discription | | Code | Description |
| :------------------- | :------------------------ | | :------------------- | :------------------------ |
| `USER_NOT_LOGGED_IN` | The user is not logged in | | `USER_NOT_LOGGED_IN` | The user is not logged in |
@@ -119,7 +119,7 @@ The server processes these commands and responds accordingly.
<!-- <!--
## Name of the command ## Name of the command
Description of the command, what it does and when it should be used. Description of the command, what it does, and when it should be used.
### Required pre-execution checks ### Required pre-execution checks
- [`Check1`](#check1) - [`Check1`](#check1)
@@ -145,7 +145,7 @@ Description of the command, what it does and when it should be used.
| `MEMBER1` | Description of member1 | | `MEMBER1` | Description of member1 |
### Error Response ### Error Response
| Code | Discription | | Code | Description |
| :----------- | :----------------------- | | :----------- | :----------------------- |
| `ERROR_CODE` | Description of the error | | `ERROR_CODE` | Description of the error |
@@ -192,7 +192,7 @@ END
## CHECK_USERNAME command ## CHECK_USERNAME command
The `CHECK_USERNAME` command is used to check if a username is already taken by another user. Additional users can still login with the same username, but thier name will be subsituted with a suffix. 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 ### Required pre-execution checks
None. None.
@@ -224,7 +224,7 @@ CHECK_USERNAME USERNAME='Lars'
END END
``` ```
## LOGIN comamnd ## 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. 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 ### Required pre-execution checks
@@ -242,7 +242,7 @@ None.
| `ID` | [`UUID`](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html) | The ID of the created user | | `ID` | [`UUID`](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html) | The ID of the created user |
### Error Response ### Error Response
| Code | Discription | | Code | Description |
| :------------------ | :----------------------------------------------------------------------------- | | :------------------ | :----------------------------------------------------------------------------- |
| `ALREADY_LOGGED_IN` | The session is already associated with a user, logging in again is prohibited. | | `ALREADY_LOGGED_IN` | The session is already associated with a user, logging in again is prohibited. |
@@ -261,7 +261,7 @@ END
## LOGOUT command ## LOGOUT command
Description of the command, what it does and when it should be used. Description of the command, what it does, and when it should be used.
### Required pre-execution checks ### Required pre-execution checks
None. None.
@@ -273,8 +273,8 @@ No parameters.
No response fields. No response fields.
### Error Response ### Error Response
| Code | Discription | | Code | Description |
| :----------------- | :--------------------------------------------------------------- | | :------------------- | :--------------------------------------------------------------- |
| `NO_USER_ASSOCIATED` | The session has no user associated, logging out is not possible. | | `NO_USER_ASSOCIATED` | The session has no user associated, logging out is not possible. |
### Example Request ### Example Request