Add protocol description

2 files changed, 163 insertions, 0 deletions

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, `<name>` 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 `<name:type>`; 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:
+- `<tag> ok`
+  - The message from the client was successfully processed.
+- `<tag> number <num:i64>`
+  - A numeric value was returned.
+- `<tag> error <message:string...>`
+  - The client's message was successfully parsed, but handling resulted in an
+    error described in the message.
+- `<tag> list <count:i64> words...`
+  - A list of words was returned. The number of words returned is given in
+    `<count>`; the words themselves are space-separated further arguments to
+    `list`.
+- `<tag> pong`
+  - Response to the client's `ping` command.
+- `<tag> history <count:i64>`
+  - 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 reverse chronological order (newest first).
+- `<tag> history_message <index:i64> <roomname:word> <user:word> <timestamp:i64> <msgid:i64> <message:string...>`
+  - Part of the response to the client's `history` command. Index 0 is the
+    newest message; index (`<count>` - 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).
+
+- `<tag> register <user:word> <pass:string...>`
+  - Register a new user on the server. The password may contain spaces.
+  - Returns `ok` or `error`.
+- `<tag> login <user:word> <pass:string...>`
+  - Logs in as the specified user.
+  - Returns `ok` or `error`.
+- `<tag> logout`
+  - Logs out of the user the client is currently logged in as. If the client is
+    not logged in, does nothing.
+  - Returns `ok`.
+- `<tag> list_rooms`
+  - Lists all rooms the user is a member of.
+  - Returns `list` or `error`.
+- `<tag> list_members <roomname:word>`
+  - Lists all members of the given room, if the user is also a member.
+  - Returns `list` or `error`.
+- `<tag> 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`.
+- `<tag> invite <roomname:word> <user:word>`
+  - 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`.
+- `<tag> send <roomname:word> <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).
+
+    Also marks the current session as active.
+  - Returns `ok` or `error`.
+- `<tag> history <roomname:word> <number:i64>`
+  - Requests the last `<number>` messages in the given room, if the client is a
+    member of the room. In the `history` response, `<count>` will be at most
+    `<number>`, and may be less if the room does not yet have `<number>`
+    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`.
+- `<tag> history_before <roomname:word> <number:i64> <msgid:i64>`
+  - 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> ping`
+  - Asks for a `pong` response.
+  - Returns `pong`.
+- `<tag> is_online <user:word>`
+  - Returns with how many sessions the given user is currently online.
+  - Returns `number` or `error`.
+- `<tag> firebase_token <token:word>`
+  - 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`.
+- `<tag> delete_firebase_token <token:word>`
+  - Removes the given Firebase token from the account of the current user.
+  - Returns `ok` or `error`.
+- `<tag> user_active <active:i64>`
+  - 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 <numonline:i64> <user:word>`
+  - 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>` (user X) is now online with
+    `<numonline>` sessions.
+- `_push message <roomname:word> <user:word> <timestamp: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.
+- `_push invite <roomname:word>`
+  - Sent to all sessions of the invited user after an `invite` command.
+- `_push join <roomname:word> <user:word>`
+  - 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.