ethermess/frontend-backend-protocol.md

Frontend-Backend Protocol
=========================

This document describes how the frontend-backend protocol works. It is not
contractual, and the protocol may change in incompatible ways without prior
announcements.

Definitions
-----------

'c' refers to the ASCII value of the given character encoded as a byte.

MAC is a MAC address as a 6 byte binary value.

status is a one-byte value that can be either 0 (available), 1
(unavailable) or 2 (offline)).

msgid is an unsigned 16 bit value that is used to identify targets of ACKs.
You can treat it as more or less an opaque identifier that is valid at
least as long the backend stays running or until you get another Msgid
event with the same msgid.

nick is the nick encoded as utf-8. It is allowed to have all valid Unicode
code points other than C0 and C1 control characters and the characters
U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR. nick can be at
maximum 255 bytes long.

message is the message encoded as utf-8. It is allowed to have all the
codepoints that nick is, plus U+0A LINE FEED which is used to separate
lines in a multi-line message. message can be at maximum 1494 bytes long.

All multibyte integer values are big-endian a.k.a. network byte order.

Commands
--------

Frontend sends commands to the backend.

### Quit
Format: 'q'

Tells the backend to exit normally, doing cleanup.

### Status request
Format: 'r' + MAC

Tells the backend to send an EtherMess status request message to the given
MAC address. No caching will be used, and one status request command
corresponds to one status request message sent.

### Set status
Format: 's' + status + nick length in bytes (u8) + nick

Tells the backend to change its stored values of nick and status, and
broadcast the new values to the network. A message will be sent even if you
provide the same nick and status that are already set.

### Send message
Format: 'm' + MAC + message length in bytes (u16) + message

Tells the backend to queue this message for sending.

Note that only one message can be queued at once, so you should wait until
you receive an event either telling you of a failure to send message (Msgid
failed, ACK failed) or telling you it has been succesfully received (ACK)
before sending another message.

Events
------

Frontend receives events from the backend.

### Speak version
Format: 'v' + MAC + version (u8)

Generated when an EtherMess Speak version packet is received by the
backend.

### Status
Format: 's' + MAC + status + nick length in bytes (u8) + nick

Generated when an EtherMess status message is received by the backend.

### Msgid
Format: 'i' + msgid

Generated when backend is able to give the queued message a msgid.

### Msgid failed
Format: 'I'

Generated when backend is unable to give the queued message a msgid. You
should consider the most recently queued message to have failed to send.

### ACK
Format: 'a' + MAC + msgid

Generated when an EtherMess ACK is received by the backend.

Make sure to pay attention to the msgid, because there is no guarantees it
refers to the most recently sent message or to a message you have sent at
all.

### ACK failed
Format: 'A'

Generated when backend times out on waiting for ACK for the most recently
queued message. You should consider the message to have failed to send.

### Message received
Format: 'm' + MAC + message length in bytes (u16) + message

Generated when backend receives a valid message.