diff options
Diffstat (limited to 'protocol.md')
| -rw-r--r-- | protocol.md | 27 |
1 files changed, 26 insertions, 1 deletions
diff --git a/protocol.md b/protocol.md index 4094b79..2d7ec63 100644 --- a/protocol.md +++ b/protocol.md @@ -1,4 +1,4 @@ -# tomsg protocol +# tomsg protocol (version 1) 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 @@ -16,6 +16,11 @@ 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. +Note that the first message the client must send is the `version` command, with +which server and client can agree (or not) on a protocol version; if a `version` +message has not yet been replied to with an `ok` response, no other commands are +valid. See the definition of the `version` command for more information. + 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 @@ -63,6 +68,26 @@ 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> 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 + header at the top of the file. + + After the server has replied to this command with `ok`, the rest of the + protocol of (only) the specified version may be used. Before that, or if the + server replies with `error`, no commands other than `version` are valid. + + If the client sends subsequent `version` messages after the first one, the + server may choose to handle those subsequent messages and switch versions, + or always return `error`, or some arbitrary mix. However, sending multiple + `version` messages is always valid (though not recommended). + + It is probable that the server can only speak one version of the protocol, + but it may support multiple versions. Note also that the version is a + _word_, not an integer; though this document describes an integer-versioned + protocol, future versions may use other printable ASCII characters (but not + any outside that range). + - Returns `ok` or `error`. - `<tag> register <user:word> <pass:string...>` - Register a new user on the server. The password may contain spaces. - Returns `ok` or `error`. |