From a6ded4443bfcd5841cf35390a13cc9c2a82bc553 Mon Sep 17 00:00:00 2001 From: Tom Smeding Date: Mon, 27 Jul 2020 19:35:00 +0200 Subject: protocol: Protocol version 2: message replies --- protocol.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) (limited to 'protocol.md') diff --git a/protocol.md b/protocol.md index ac8d86a..8c02017 100644 --- a/protocol.md +++ b/protocol.md @@ -1,4 +1,4 @@ -# 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 @@ -56,18 +56,22 @@ A _response_ from the server will be in one of the following forms: - Response to the client's `history` command; is followed by exactly `` messages of type `history_message` with the same tag. The messages are returned in chronological order (oldest first). -- ` history_message ` +- ` history_message ` - Part of the response to the client's `history` command. Index 0 is the oldest message; index (`` - 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. 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. + - ` version ` - 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 +126,20 @@ ranges until the end of the line). Also marks the current session as active. - Returns `ok` or `error`. -- ` send ` +- ` send ` - 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 `` is -1, this sends a normal message. Otherwise, + `` 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 + `` 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`. - ` history ` - Requests the last `` messages in the given room, if the client is a @@ -179,9 +189,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 X) is now online with `` sessions. -- `_push message ` +- `_push message ` - 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. `` is -1 if + the message is a normal message, and references the replied-to message + otherwise. - `_push invite ` - Sent to all sessions of the invited user after an `invite` command. The `` parameter indicates who invited you to the given room. -- cgit v1.2.3-70-g09d2 From a9413077b5839b98fc791fcadbae4f8fa1c3743f Mon Sep 17 00:00:00 2001 From: Tom Smeding Date: Tue, 28 Jul 2020 16:05:57 +0200 Subject: protocol: Add get_message command for use with replies --- protocol.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'protocol.md') diff --git a/protocol.md b/protocol.md index 8c02017..8bbba49 100644 --- a/protocol.md +++ b/protocol.md @@ -63,6 +63,10 @@ A _response_ from the server will be in one of the following forms: 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. +- ` message ` + - 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 @@ -152,6 +156,9 @@ tomsg server. - Same as `history`, except the returned messages are the last `` strictly before the timestamp of the message with id ``. - Returns `history`, followed by zero or more `history_message`. +- ` get_message ` + - Retrieves the message with the given id. + - Returns `message` or `error`. - ` ping` - Asks for a `pong` response. - Returns `pong`. -- cgit v1.2.3-70-g09d2 From bd8546c49594fddb4a41b5eb5bd82719c3c5e4f1 Mon Sep 17 00:00:00 2001 From: Tom Smeding Date: Wed, 29 Jul 2020 10:40:24 +0200 Subject: protocol: Clarify necessity of a secure transport --- protocol.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'protocol.md') diff --git a/protocol.md b/protocol.md index 8bbba49..ff6651b 100644 --- a/protocol.md +++ b/protocol.md @@ -1,8 +1,12 @@ # 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: -- cgit v1.2.3-70-g09d2