diff --git a/docs/protocol/daemon-api.md b/docs/protocol/daemon-api.md new file mode 100644 index 0000000..06417f3 --- /dev/null +++ b/docs/protocol/daemon-api.md @@ -0,0 +1,99 @@ +# Daemon Api + +The Daemon Api is the api that provides the communication between the Server and a Daemon. +All interactions are instantiated from the Server. +
+This api is used to provide the frontend capability to instantiate game processes. + +## Structure + +The Daemon Api is something like a Rest Api on the Daemon witch is accessed from the Server. +
+Every enpoint follows the following schema: `/` + +| Name | Description | +|------|-------------| +| Endpoint Collection | As the name says, a endpoint collection is a collection of endpoints. All endpoints from a collection are from the same daemon. The purpose of a endpoint collection is to group certain endpoints. (e.g. `network` contains all endpoints related to networks) | +| Endpoint | A endpoint is like a function on a daemon witch can be executed by the frontend. Mostly it changes database stated or sends notifications to other users. | + +## Security + +In normal cases all daemons are not public accessible. (e.g. secured by a firewall or Docker Networks) +
+Although all request must contain an api token. The api token can be configured with an environment variable on the server and Dameon side. +It is recommended to change the api token is regular time spans. + +## Request + +### Header + +The server sends the following headers: + +```http +Content-Type: application/json; charset=utf-8 +Accept: application/json +Accept-Charset: utf-8 +Authorization: +``` + +### Body + +The server sends the following parameters: + +```json +{ + "user_id": "" // the id of the user who executed the endpoint + // ... - endpoint specific parameters +} +``` + +## Response + +### Header + +The daemon must respond with the following headers: + +```http +Content-Type: application/json; charset=utf-8 +``` + +The status code is also passed to the frontend. + +### Body + + +The daemon must respond with the following body: + +```json +{ + "error": "message" // optional error message + // ... - endpoint specific data +} +``` + +## Endpoint Discovery + +When a server boots, it discovers all existing endpoints. Therefore, it executes the discovery endpoint for every Dameon type. +This is needed to filter out request for non-existing endpoints and to route requests to the daemon according to the endpoint. +
+
+The response looks like this: + +```json +[ + { + "id": "", + "description": "", + "disabled": false, + "endpoints": [ + { + "id": "", + "description": "", + "disabled": false + } + ] + } +] +``` + +_The description is currently not used._ diff --git a/docs/protocol/notification.md b/docs/protocol/notification.md new file mode 100644 index 0000000..5bca3b4 --- /dev/null +++ b/docs/protocol/notification.md @@ -0,0 +1,13 @@ +Create redis hash: +``` +$ hset notification: data id topic +``` + +Notify server of new notification: +``` +$ subscribe notifications +1) "message" +2) "notifications" +3) ":" + +``` diff --git a/docs/protocol/websocket.md b/docs/protocol/websocket.md new file mode 100644 index 0000000..11d6644 --- /dev/null +++ b/docs/protocol/websocket.md @@ -0,0 +1,71 @@ +# Websocket Api + +The websocket api is the interface for any frontend to communicate with the backend. +
+By default the websocket is available at `/ws`. (e.g. `wss://server.cryptic-game.net/ws`) + +## Request + +```json +{ + "tag": "random string", + "endpoint": "user/register", + "data": { + "username": "TestUser", + "password": "#Test123" + } +} +``` + +| Name | Description | +|------------|----------------------------------------------------------------------------------------------------------------| +| `tag` | The tag is a random string witch is copied to the response of this request to identify the according response. | +| `endpoint` | The endpoint witch should be executed. | +| `data` | The data witch should be passed to the endpoint. | + +## Response + +```json +{ + "status": { + "code": 200, + "name": "OK" + }, + "error": "", // optional + "tag": "random string", + "data": { + "id": "fd973bf5-3801-402f-8c85-d5313aa02baa", + "user_id": "2cea82a0-3425-4d0e-8e1b-4823ad744162" + } +} +``` + +| Name | Description | +|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------| +| `status` | The status code and name of the response. The codes are similar to the [Http Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status). | +| `error` | A optional error message. | +| `tag` | The same value as in the request. | +| `data` | A optional data witch the endpoint produced. | + +## Notification + +```json +{ + "status": { + "code": 900, + "name": "Notification" + }, + "topic": "MESSAGE_SEND", + "data": { + "user_id": "fd973bf5-3801-402f-8c85-d5313aa02baa", + "whisper": false, + "content": "Hello" + } +} +``` + +| Name | Description | +|----------|--------------------------------------------------------------------| +| `status` | The status is in every Notification the same. | +| `topic` | The topic of the notification. It can be interpreted as a channel. | +| `data` | A optional data of the notification. | diff --git a/mkdocs.yml b/mkdocs.yml index e9a0b90..e7206a9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,3 +44,8 @@ extra: link: https://github.com/cryptic-game - icon: fontawesome/brands/twitter link: https://twitter.com/Cryptic_Game + +markdown_extensions: + - pymdownx.highlight: + linenums: true + - pymdownx.superfences