cadmium-docs-legacy/protocol-spec/core.md

73 lines
2.0 KiB
Markdown
Raw Normal View History

2019-11-12 17:39:52 +00:00
# Protocol Core
2019-11-12 16:39:24 +00:00
2019-11-16 12:14:55 +00:00
- [Protocol Core](#protocol-core)
- [Transport](#transport)
- [Entity ID](#entity-id)
- [BaseMessage](#basemessage)
## Transport
2019-12-22 14:39:30 +00:00
2019-11-16 12:14:55 +00:00
For starting we simply use JSON + Websockets.
2019-11-12 16:39:24 +00:00
## Entity ID
2019-12-22 14:39:30 +00:00
- Room alias: `#<roomAlias>@<serverpart>`
- Username: `@<username>@<serverpart>`
- User ID with any 3PID: `%<type>:<data>@<serverpart>`
- Currently supported only following types: `email` and `msisdn`.
- Raw User ID: `@<UUID>@<serverpart>`
- Message ID: `&<uuid>@<serverpart (from which server the message was sent)>`
- Room ID: `!<roomID>@<serverpart>`
- Single server-part: `<serverpart>`
2019-11-12 16:39:24 +00:00
**Server-part**:
2019-12-22 14:39:30 +00:00
- hostname: `IPv4 / [IPv6] / dns-domain:<port (1-65535)>` (for end-users use)
- server ID: static SHA256 hash string from 4096 characters (for internal protocol use)
2019-11-12 16:39:24 +00:00
**Username/Room alias/RoomID** - MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`, `.`, `_`, `=`, `-`, and `/`.
**Special business rules**:
2019-12-22 14:39:30 +00:00
- RoomID SHOULD be UUID identifier.
- Servers MUST use server ID in internal purposes instead of normal server-part with hostname. Only end-users MUST use normal server-part with hostname. This is done for easy multi-domain serving.
2019-11-12 17:51:29 +00:00
## BaseMessage
2019-12-22 14:39:30 +00:00
2019-11-12 17:51:29 +00:00
BaseMessage is a basic message model, basis of the whole protocol. It is used for a very easy protocol extension process.
BaseMessage scheme:
2019-12-22 14:39:30 +00:00
```typescript
interface BaseMessage {
/**
* Message identifier (used to track the request-response chain)
*/
2019-12-15 15:08:48 +00:00
id: string,
/**
* Type of message (used to determine which extension this message belongs to)
*/
2019-12-15 15:08:48 +00:00
type: string,
/**
* From which entity this message is send
*/
2019-12-15 15:08:48 +00:00
from: EntityID,
/**
* Message recipient
*/
2019-12-15 15:08:48 +00:00
to: EntityID,
/**
* Operation success indicator (used to determine if the error happened while processing request)
*/
2019-12-15 15:08:48 +00:00
ok: boolean,
/**
* Message payload (used to store extra information in message, list of permissible fields in the payload depends on "type" field)
*/
2019-12-15 15:08:48 +00:00
payload: Map<K,V>
}
2019-12-22 14:39:30 +00:00
```