diff options
Diffstat (limited to 'protocol.md')
| -rw-r--r-- | protocol.md | 43 |
1 files changed, 33 insertions, 10 deletions
diff --git a/protocol.md b/protocol.md index ac8d86a..ff6651b 100644 --- a/protocol.md +++ b/protocol.md @@ -1,8 +1,12 @@ -# tomsg protocol (version 1) +# tomsg protocol (version 2) -The underlying transport of the protocol is a plain TCP socket. The individual -messages are all line-based; this means that a single message, both -client->server and server->client, always ends with a newline (ASCII 10) +The underlying transport of the protocol is a plain TCP socket. However, +because private information is communicated, the recommended transport is an +encrypted and authenticated wrapper around a TCP socket; examples are an SSH +connection, or something built on a TLS connection. + +The individual messages are all line-based; this means that a single message, +both client->server and server->client, always ends with a newline (ASCII 10) character. Preliminary definitions: @@ -56,18 +60,26 @@ A _response_ from the server will be in one of the following forms: - Response to the client's `history` command; is followed by exactly `<count>` messages of type `history_message` with the same tag. The messages are returned in chronological order (oldest first). -- `<tag> history_message <index:i64> <roomname:word> <user:word> <timestamp:i64> <msgid:i64> <message:string...>` +- `<tag> history_message <index:i64> <roomname:word> <user:word> <timestamp:i64> <msgid:i64> <replymsgid:i64> <message:string...>` - Part of the response to the client's `history` command. Index 0 is the oldest message; index (`<count>` - 1) (from the `history` response) is the newest message in the fragment requested. Timestamps are microseconds since - the UNIX epoch. The message id for each message is globally unique for the - entire server. + the UNIX epoch. The reply message id is -1 if the message is a normal + message, or nonnegative if it is a reply to the referenced message in the + same room. +- `<tag> message <roomname:word> <user:word> <timestamp:i64> <msgid:i64> <replymsgid:i64> <message:string...>` + - Response to the client's `get_message` command. This contains the + information for a single message, as in `_push message` and the + `history_message` response. A command is identified by its name, which can be found in the list below. Its arguments are zero or more words, except if for the command in question the last argument is of type `string...` (in which case it may contain spaces and ranges until the end of the line). +Note: all messages on the server have an ID that is globally unique on a single +tomsg server. + - `<tag> version <version:word>` - Indicates that the client wishes to speak the protocol with the specified version. For the version of the protocol described in this document, see the @@ -122,14 +134,20 @@ ranges until the end of the line). Also marks the current session as active. - Returns `ok` or `error`. -- `<tag> send <roomname:word> <message:string...>` +- `<tag> send <roomname:word> <replymsgid:i64> <message:string...>` - Sends a message to the given room. All room members receive a `_push message` push message on all their sessions (except the session the `send` message was sent from). + If `<replymsgid>` is -1, this sends a normal message. Otherwise, + `<replymsgid>` must be the id of a message in the given room, in which case + the sent message is a reply to the indicated earlier message. If + `<replymsgid>` is not a message in this room, `error` is returned. + Also marks the current session as active. The returned `number` response contains the message id of the message sent. + This number will be non-negative. - Returns `number` or `error`. - `<tag> history <roomname:word> <number:i64>` - Requests the last `<number>` messages in the given room, if the client is a @@ -142,6 +160,9 @@ ranges until the end of the line). - Same as `history`, except the returned messages are the last `<number>` strictly before the timestamp of the message with id `<msgid>`. - Returns `history`, followed by zero or more `history_message`. +- `<tag> get_message <msgid:i64>` + - Retrieves the message with the given id. + - Returns `message` or `error`. - `<tag> ping` - Asks for a `pong` response. - Returns `pong`. @@ -179,9 +200,11 @@ are listed below. (excluding user X) of all rooms user X is a member of receive a `_push online` push message stating that `<user>` (user X) is now online with `<numonline>` sessions. -- `_push message <roomname:word> <user:word> <timestamp:i64> <msgid:i64> <message:string...>` +- `_push message <roomname:word> <user:word> <timestamp:i64> <msgid:i64> <replymsgid:i64> <message:string...>` - Sent to all sessions of all members of a room in which a message is - posted, except the session that sent the message. + posted, except the session that sent the message. `<replymsgid>` is -1 if + the message is a normal message, and references the replied-to message + otherwise. - `_push invite <roomname:word> <user:word>` - Sent to all sessions of the invited user after an `invite` command. The `<user>` parameter indicates who invited you to the given room. |