From 8e028e1171f7106ef7e291674190184d3a29bc54 Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Sat, 5 Sep 2020 23:00:22 +0400 Subject: [PATCH] Describe private chats system --- protocol-spec/private-chats.md | 373 +++++++++++++++++++++++++++++++++ 1 file changed, 373 insertions(+) create mode 100644 protocol-spec/private-chats.md diff --git a/protocol-spec/private-chats.md b/protocol-spec/private-chats.md new file mode 100644 index 0000000..0462943 --- /dev/null +++ b/protocol-spec/private-chats.md @@ -0,0 +1,373 @@ +# Private chats + +## 1. Introduction + +This extension is intended for organizing private chat between two users. + +## 2. Message type identifiers + +- `urn:cadmium:chats:private:message` - regular message +- `urn:cadmium:chats:private:read` - read message system +- `urn:cadmium:chats:private:typing` - typing message system + +## 3. Errors + +- Ratelimit system: disabled +- Authorization: enabled + +## 4. Chat message types + +- `urn:cadmium:chats:message-types:general` - message with text and optional media +- `urn:cadmium:chats:message-types:audio` - audio message +- `urn:cadmium:chats:message-types:geolocation` - message with geolocation (coordinates) + +## 5. Use cases + +### 5.1. Exchanging messages + +1. Sending message: + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:message", + "to": ["@user2@cadmium.org"], + "payload": { + "type": "urn:cadmium:chats:message-types:general", + "content": { + "text": "hello world", + } + } + } + ``` + + **Successful response**: + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:message", + "from": "cadmium.org", + "ok": true, + "payload": { + "messageID": "3b5135a5-aff5-4396-a629-a254f383e82f", + "originServerTimestamp": 1599327584 + } + } + ``` + + **Error response**: + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:message", + "from": "cadmium.org", + "ok": false, + "payload": { + "errID": "banned", + "errText": "The user banned you" + } + } + ``` + +2. Receiving message on other side: + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:message", + "from": "@user1@cadmium.im", + "ok": true, + "payload": { + "messageID": "3b5135a5-aff5-4396-a629-a254f383e82f", + "originServerTimestamp": 1599327584, + "type": "urn:cadmium:chats:message-types:general", + "content": { + "text": "hello world", + } + } + } + ``` + +### 5.2. Exchanging media + +1. Upload the media to HTTP Upload service (explanation out of scope of this document) +2. Send message containing the URL of uploaded media: + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:message", + "to": ["@user2@cadmium.org"], + "payload": { + "type": "urn:cadmium:chats:message-types:general", + "content": { + "text": "", + "media": [ + { + "url": "https://upload.cadmium.im/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67", + "mimeType": "image/jpeg" + } + ] + } + + } + } + ``` + + **Response**: + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:message", + "from": "cadmium.org", + "ok": true, + "payload": { + "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e", + "originServerTimestamp": 1599329232 + } + } + ``` + +3. Receive message with media on other side: + + ```json + { + "id": "defg", + "type": "urn:cadmium:chats:private:message", + "from": "@user1@cadmium.im", + "ok": true, + "payload": { + "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e", + "originServerTimestamp": 1599329232, + "type": "urn:cadmium:chats:message-types:general", + "content": { + "text": "", + "media": [ + { + "url": "https://upload.cadmium.im/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67", + "mimeType": "image/jpeg" + } + ] + } + } + } + ``` + +### 5.3. Read messages + +1. Read message + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:read", + "to": ["@user1@cadmium.org"], + "payload": { + "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e", + } + } + ``` + + Response: + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:read", + "from": "cadmium.im", + "ok": true, + "payload": {} + } + ``` + +2. Receive notification about message reading on other side: + + ```json + { + "id": "defg", + "type": "urn:cadmium:chats:private:read", + "from": "@user2@cadmium.im", + "ok": true, + "payload": { + "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e" + } + } + ``` + +### 5.3. Typing messages + +1. Typing message + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:typing", + "to": ["@user1@cadmium.org"], + "payload": { + "status": "typing", + } + } + ``` + +2. Receive notification about typing message on other side: + + ```json + { + "id": "defg", + "type": "urn:cadmium:chats:private:read", + "from": "@user2@cadmium.im", + "ok": true, + "payload": { + "status": "typing" + } + } + ``` + +3. Pause typing message (e.g. when user stops abruptly typing message or just sent the message) + + ```json + { + "id": "abcd", + "type": "urn:cadmium:chats:private:typing", + "to": ["@user1@cadmium.org"], + "payload": { + "status": "paused", + } + } + ``` + +4. Receive notification pausing typing message on other side: + + ```json + { + "id": "defg", + "type": "urn:cadmium:chats:private:read", + "from": "@user2@cadmium.im", + "ok": true, + "payload": { + "status": "paused" + } + } + ``` + +## 6. Business Rules + +None. + +## 7. JSON Schema + +### Send message (`urn:cadmium:chats:private:message`) + +**Request**: + +```typescript +interface SendMessagePayload { + type: string; // the type of message + content: Content // the payload of message (depends on type) +} +``` + +**Response**: + +```typescript +interface SendMessageResponsePayload { + messageID: string; // the message id (stored in chat timeline) + originServerTimestamp: number // unix timestamp of sent message on the origin server +} +``` + +#### Content sections + +- `urn:cadmium:chats:message-types:general`: + + ```typescript + interface GeneralMessageContent { + text: string; // the text (body) of message + media?: Media[]; // media content + } + + interface Media { + url: string; // url of media (where it stores) + mimeType: string; // mime type of media + } + ``` + +- `urn:cadmium:chats:message-types:audio`: + + ```typescript + interface AudioMessageContent { + url: string; // the url of audio message + } + ``` + +- `urn:cadmium:chats:message-types:geolocation`: + + ```typescript + interface GeolocationMessageContent { + lat: number; // the GPS latitude + lon: number; // the GPS longitude + } + ``` + +### Receive message (`urn:cadmium:chats:private:message`) + +```typescript +interface ReceiveMessagePayload { + messageID: string; // the id of received message + originServerTimestamp: number; // unix timestamp of received message on the origin server + type: string; // the type of message + content: Content // the payload of message (depends on type) +} +``` + +### Read message (`urn:cadmium:chats:private:read`) + +**Request**: + +```typescript +interface ReadMessagePayload { + messageID: string; // the message id of read message +} +``` + +**Response**: + +None. + +### Receive read message notification (`urn:cadmium:chats:private:read`) + +```typescript +interface ReceiveReadMessageNotifPayload { + messageID: string; // the message id of read message +} +``` + +### Typing message (`urn:cadmium:chats:private:typing`) + +**Request**: + +```typescript +interface TypingMessagePayload { + status: TypingStatus; // the status of the typing +} + +enum TypingStatus { + typing, + paused +} +``` + +**Response**: + +None. + +### Receive read message notification (`urn:cadmium:chats:private:typing`) + +```typescript +interface TypingMessageNotifPayload { + status: TypingStatus; // the status of the typing +} +```