From bc3ce98673a961bf6886efe1f63345a80d8a9f3b Mon Sep 17 00:00:00 2001 From: Tom Smeding Date: Sat, 20 Jun 2020 23:50:46 +0200 Subject: Add protocol description --- TODO.txt | 2 + protocol.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+) create mode 100644 TODO.txt create mode 100644 protocol.md diff --git a/TODO.txt b/TODO.txt new file mode 100644 index 0000000..554ee05 --- /dev/null +++ b/TODO.txt @@ -0,0 +1,2 @@ +- Somehow communicate (push? poll?) to room members whether a particular user is currently _active_, not just online. +- A session is marked inactive 2 minutes after the latest activity on that session. Make the number "2" configurable and not a hard-coded constant. diff --git a/protocol.md b/protocol.md new file mode 100644 index 0000000..aa6de82 --- /dev/null +++ b/protocol.md @@ -0,0 +1,161 @@ +# tomsg protocol + +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) +character. + +Preliminary definitions: +- A _string_ is a series of non-zero bytes. To allow for clients written in + languages that automatically parse strings as UTF-8, argument strings should + always be valid UTF-8. However, the server currently does not care. +- A _word_ is a string without spaces (ASCII 32) or newlines. Note that the + empty string is also a valid word. + +There are three kinds of messages: commands from the client, command responses +from the server, and push messages from the server (not to be confused with push +_notifications_). These three kinds are described below. + +In the syntax descriptions below, `` indicates an argument called "name"; +the angle brackets are not part of the syntax. The type of the argument may be +indicated with the notation ``; possible types are `i64` (a 64-bit +signed integer in decimal notation), `word` (a word), and `string...` (a string +stretching until the end of the line). + +A message from client to server consists of a _tag_, a space, the command name, +a space, and finally the arguments to the command. The tag is a word, and may be +arbitrarily chosen by the client; it will be returned by the server in its +response to the client's message, so that the client can easily link requests +and responses. + +All client commands, if not syntactically invalid, will be replied to with a +server response. + +A _response_ from the server will be in one of the following forms: +- ` ok` + - The message from the client was successfully processed. +- ` number ` + - A numeric value was returned. +- ` error ` + - The client's message was successfully parsed, but handling resulted in an + error described in the message. +- ` list words...` + - A list of words was returned. The number of words returned is given in + ``; the words themselves are space-separated further arguments to + `list`. +- ` pong` + - Response to the client's `ping` command. +- ` history ` + - 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 reverse chronological order (newest first). +- ` history_message ` + - Part of the response to the client's `history` command. Index 0 is the + newest message; index (`` - 1) (from the `history` response) is the + oldest 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. + +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). + +- ` register ` + - Register a new user on the server. The password may contain spaces. + - Returns `ok` or `error`. +- ` login ` + - Logs in as the specified user. + - Returns `ok` or `error`. +- ` logout` + - Logs out of the user the client is currently logged in as. If the client is + not logged in, does nothing. + - Returns `ok`. +- ` list_rooms` + - Lists all rooms the user is a member of. + - Returns `list` or `error`. +- ` list_members ` + - Lists all members of the given room, if the user is also a member. + - Returns `list` or `error`. +- ` create_room` + - Creates a new room, and enters the room. The id of the room is returned to + the client. Returns an error if the client is not logged in. + + Also marks the current session as active. + - Returns `name` or `error`. +- ` invite ` + - Invites the given user to the given room, if the client is currently a + member of that room. The invited user is immediately added to the room. + + If the invite succeeds, the invited user receives a `_push invite` push + message on all its sessions, and all current room members receive a + `_push join` push message on all their sessions (except the session the + `invite` message was sent from). + + Also marks the current session as active. + - Returns `ok` or `error`. +- ` 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). + + Also marks the current session as active. + - Returns `ok` or `error`. +- ` history ` + - Requests the last `` messages in the given room, if the client is a + member of the room. In the `history` response, `` will be at most + ``, and may be less if the room does not yet have `` + messages. Each message will be returned in a `history_message` response + after the `history` response, in reverse chronological order. + - Returns `history`, followed by zero or more `history_message`. +- ` history_before ` + - 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`. +- ` ping` + - Asks for a `pong` response. + - Returns `pong`. +- ` is_online ` + - Returns with how many sessions the given user is currently online. + - Returns `number` or `error`. +- ` firebase_token ` + - Adds the given Firebase token to the account of the current user. This is + used for new-message push notifications for Android-based clients. + - Returns `ok` or `error`. +- ` delete_firebase_token ` + - Removes the given Firebase token from the account of the current user. + - Returns `ok` or `error`. +- ` user_active ` + - Marks the user as active (if `active` > 0) or inactive (if `active` + <= 0) on the current session. This does not influence whether the user is + marked active on any of the other sessions on which they are currently + logged in. + + A session is automatically marked inactive 2 minutes after the latest + activity on that session. + + This is used for Firebase notifications: a user will only receive Firebase + notifications if they are marked inactive on all their sessions, or if they + have no active sessions. + - Returns `ok` or `error`. + +Push messages from the server are formatted like responses with tag `_push`. +These are not sent in response to a particular client message, but are sent by +the server due to other events. Some have already been mentioned above, but all +are listed below. + +- `_push online ` + - When user X logs in or logs out in a session, all sessions of all members + (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 ` + - Sent to all sessions of all members of a room in which a message is + posted, except the session that sent the message. +- `_push invite ` + - Sent to all sessions of the invited user after an `invite` command. +- `_push join ` + - Sent to all sessions of all members of a room (except the session sending + the `invite` command) in which a new user entered. +- `_push ping` + - Sent by the server once in a while. Please ignore. -- cgit v1.2.3-54-g00ecf