Write protocol document outline and document existing commands #245
@@ -1,5 +1,5 @@
|
||||
# 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
|
||||
@@ -13,7 +13,7 @@ This document describes the protocol for client-server communication in our appl
|
||||
- [Error Response](#error-response-1)
|
||||
- [Command parsing](#command-parsing)
|
||||
- [Error Response](#error-response-2)
|
||||
- [Pre executions checks](#pre-executions-checks)
|
||||
- [Pre-execution checks](#pre-execution-checks)
|
||||
- [UserLoggedInCheck](#userloggedincheck)
|
||||
- [Error Response](#error-response-3)
|
||||
- [Commands](#commands)
|
||||
@@ -29,7 +29,7 @@ This document describes the protocol for client-server communication in our appl
|
||||
- [Success Response](#success-response-1)
|
||||
- [Example Request](#example-request-1)
|
||||
- [Example Response](#example-response-1)
|
||||
- [LOGIN comamnd](#login-comamnd)
|
||||
- [LOGIN command](#login-command)
|
||||
- [Required pre-execution checks](#required-pre-execution-checks-2)
|
||||
- [Request Parameters](#request-parameters-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 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
|
||||
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 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.
|
||||
Each collection is ended with the `END` keyword.
|
||||
@@ -58,14 +58,14 @@ Each collection is ended with the `END` keyword.
|
||||
|
||||
|
||||
# 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.
|
||||
|
||||
## 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
|
||||
| Code | Discription |
|
||||
| Code | Description |
|
||||
| :-------------- | :---------------------------------------------------------------------------------------------- |
|
||||
| `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.
|
||||
|
||||
### Error Response
|
||||
| Code | Discription |
|
||||
| Code | Description |
|
||||
| :---------------- | :---------------------------------------------------------------- |
|
||||
| `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`.
|
||||
|
||||
### Error Response
|
||||
| Code | Discription |
|
||||
| Code | Description |
|
||||
| :------------------ | :------------------------------------------------------------------------------------------------ |
|
||||
| `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.
|
||||
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.
|
||||
|
||||
### Response if not met
|
||||
| Code | Discription |
|
||||
| Code | Description |
|
||||
| :----------- | :----------------------- |
|
||||
| `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).
|
||||
|
||||
### Error Response
|
||||
| Code | Discription |
|
||||
| Code | Description |
|
||||
| :------------------- | :------------------------ |
|
||||
| `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
|
||||
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
|
||||
- [`Check1`](#check1)
|
||||
@@ -145,7 +145,7 @@ Description of the command, what it does and when it should be used.
|
||||
| `MEMBER1` | Description of member1 |
|
||||
|
||||
### Error Response
|
||||
| Code | Discription |
|
||||
| Code | Description |
|
||||
| :----------- | :----------------------- |
|
||||
| `ERROR_CODE` | Description of the error |
|
||||
|
||||
@@ -192,7 +192,7 @@ 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 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
|
||||
None.
|
||||
@@ -224,7 +224,7 @@ CHECK_USERNAME USERNAME='Lars'
|
||||
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.
|
||||
|
||||
### 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 |
|
||||
|
||||
### Error Response
|
||||
| Code | Discription |
|
||||
| Code | Description |
|
||||
| :------------------ | :----------------------------------------------------------------------------- |
|
||||
| `ALREADY_LOGGED_IN` | The session is already associated with a user, logging in again is prohibited. |
|
||||
|
||||
@@ -261,7 +261,7 @@ END
|
||||
|
||||
|
||||
## 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
|
||||
None.
|
||||
@@ -273,8 +273,8 @@ No parameters.
|
||||
No response fields.
|
||||
|
||||
### Error Response
|
||||
| Code | Discription |
|
||||
| :----------------- | :--------------------------------------------------------------- |
|
||||
| Code | Description |
|
||||
| :------------------- | :--------------------------------------------------------------- |
|
||||
| `NO_USER_ASSOCIATED` | The session has no user associated, logging out is not possible. |
|
||||
|
||||
### Example Request
|
||||
|
||||
Reference in New Issue
Block a user