[docs] Rewrite docs

4 files changed, 298 insertions, 88 deletions

diff --git a/PROTOCOL.md b/PROTOCOL.md
deleted file mode 100644
index b6d249e..0000000
--- a/PROTOCOL.md
+++ /dev/null
@@ -1,87 +0,0 @@
-<!--- ---------------------------------------------------------------------  -->
-
-# SOLEC protocol specification
-
-## Data format
-
-* Payload can contain multiple numeric types or binary data in a single frame
-* Numeric types are big endian
-* See [test payload](#Test) for an example of complex data structure
-
-### Frame structure
-
-| Type     | Description    |
-|----------|----------------|
-| `uint8`  | Payload type   |
-| `uint16` | Payload length |
-| `any`    | Payload        |
-
-
-### Special types
-
-#### Strings and binary
-
-Strings and binary data are prefixed wtith 2 bytes denoting their length.
-Strings are UTF-8 encoded.
-
-#### Timestamps
-
-Timestamps are stored as `uint64` in [Unix format](https://en.wikipedia.org/wiki/Unix_time).
-Timezone is always set to UTC.
-
-### Payloads
-
-All payload types are described in following files:
-
-* [Kaitai Struct](https://git.sr.ht/~rctt/solec/blob/main/solec.ksy)
-* [SVG graph](https://git.sr.ht/~rctt/solec/blob/main/solec.svg)
-
-## Client-server connection initialization
-
-1. Initialize TCP connection
-2. Receive `handshake`
-3. Send `hadnshake`
-4. Send `auth`
-5. Receive `success` or `error`
-
-## Client-server messaging
-
-After successfull auth server will listen for payloads of `message` type.
-Sending different payload will result in error and connection will be closed
-by the server.
-
-Message consist of following fields:
-* Source - address of the user sending a message
-* Target - address of channel or user receiving a message
-* Timestamp - set by user sending a message, UTC timezone
-* Content - UTF-8 string
-
-## Addresses
-
-Source and target addresses are similair to e-mail addresses. There are two
-parts separated by `@` where second part is address of the server where
-specific user or channel is registered on.
-
-Target addresses is set to user that created specific message. Messaegs can be
-relayed between servers so it's necessary to keep that info as part of the
-message.
-
-Channel addresses always starts from `#` to distinct them from user addresses.
-Because of that user address cannot start from this character.
-
-Channels can be grouped in a hierarchy. Levels of channels hierarchy are
-separated by `.`.
-
-`*` is special address reserved for broadcast messages send by the server
-administrator.
-
-| Type      | Address              |
-|-----------|----------------------|
-| user      | user@example.org     |
-| channel   | #channel@example.org |
-| broadcast | *@example.org        |
-
-## Channels hierarchy
-
-Channels can be groupped into a hierarchy. Channels hierarchy can be used to
-simplify moderation and management.
\ No newline at end of file
diff --git a/README.md b/README.md
index 58345e6..6c7bf81 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # solec
 
-* [Protocol spec](https://git.sr.ht/~rctt/solec/tree/main/item/PROTOCOL.md)
+* [Protocol spec](https://git.rctt.net/solec/plain/PROTOCOL.md?h=main)
 
 ## Running the daemon
 
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..6be417c
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,34 @@
+MMARK :=mmark
+TXT := $(patsubst %.md,%.txt,$(wildcard *.md))
+XML := $(patsubst %.md,%.xml,$(wildcard *.md))
+HTML := $(patsubst %.md,%.html,$(wildcard *.md))
+PDF := $(patsubst %.md,%.pdf,$(wildcard *.md))
+
+txt: $(TXT)
+
+%.txt: %.xml
+	xml2rfc --text --v3 -P $<
+	rm -f $(basename $<).xml
+	awk 'FNR<=4 || (FNR>=19 && FNR<=46) {next} {print}' $(basename $<).txt > tmp.txt
+	mv tmp.txt $(basename $<).txt
+
+html: $(HTML)
+
+%.html: %.xml
+	xml2rfc --html --v3 $<
+	rm -f $(basename $<).xml
+
+xml: $(XML)
+
+%.xml: %.md
+	$(MMARK) $< > $(basename $<).xml
+
+pdf: $(PDF)
+
+%.pdf: %.xml
+	xml2rfc --pdf --v3 $<
+	rm $(basename $<).xml
+
+.PHONY: clean
+clean:
+	rm -f *.txt *.xml
diff --git a/docs/rfc.md b/docs/rfc.md
new file mode 100644
index 0000000..089d93f
--- /dev/null
+++ b/docs/rfc.md
@@ -0,0 +1,263 @@
+<!--- ---------------------------------------------------------------------  -->
+
+%%%
+title = "System of Lightweight Electronic Communication"
+abbrev = "SOLEC"
+ipr= "trust200902"
+area = "Internet"
+workgroup = "SOLEC Working Group"
+submissiontype = "independent"
+keyword = ["solec-draft"]
+
+[seriesInfo]
+name = "Internet-Draft"
+value = "SOLEC"
+stream = "independent"
+status = "experimental"
+
+[[author]]
+initials = "bt"
+role = "editor"
+organization = "RCTT.net"
+  [author.address]
+  email = "bt@rctt.net"
+%%%
+
+.# Abstract
+
+This document describes working principles, features and network protocol of
+SOLEC system.
+
+{mainmatter}
+
+# Introduction
+
+SOLEC is currently under development for PWR group project and as part of my
+engineering thesis.
+
+System of Lightweight Electronic Communication or SOLEC is a system for
+decentralised communication designed for low-speed networks. It uses binary
+protocol to keep required bandwidth as low as possible.
+
+Current implementation works on top of TCP/IP stack. In future, SOLEC will be
+adapted to work over LoRa.
+
+## Decentralization
+
+Recurring problem with modern day instant messaging is its centralization.
+SOLEC solves is it in similair fashion to XMPP or SMTP. SOLEC servers exchange
+messages between each other so the users using server A can reach out users
+using server B.
+
+## User to user communication
+
+User can exchange messages with other users of the network if they are both in
+their *contacts* group. Messages from untrusted users are not forwarded by the
+server. If users are using different servers chat history is stored on both.
+
+## Channels
+
+Message can be send to a group of users called channel. Channels settings and
+history is stored on a specific server. Users can access channels from servers
+other than their own. To receive channel messages user have to join specific
+channel.
+
+# Network protocol
+
+In current version session is provided by TCP connection. Security of
+client-server connection can be achieved using TLS.
+
+## Protocol Data Unit Structure
+
+SOLEC is using Type Length Value (TLV) structure for data exchange.
+
+~~~ ascii-art
+  0                   1                   2                   3
+  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |    Type       |             Length            |   Payload   ...
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~~~
+
+Figure: SOLEC PDU Layout
+
+* Type (8):
+Payload type is indicated by 1 octed which gives 256 types that can be
+represented.
+
+* Length (16):
+Payload length is 2 octets. It indicates lenght of the payload field.
+The length does not include type and length fields.
+
+* Payload (variable):
+Payload stores set of fields determined by its type.
+
+## Payload structure
+
+Payload usually consist of one or more data fields but it is possible for
+payload to be empty. Some payload types are used only to signal some event and
+does not carry any data.
+
+## Data types
+
+Data typres are basic types that are used in construction of more comples
+payload types.
+
+### Numeric types
+
+Numeric types are Big-Endian. Numeric types names are taken from [Go language
+spec](https://go.dev/ref/spec#Numeric_types). Following types are in use:
+
+* uint8
+* uint16
+* uint32
+* uint64
+
+### Timestamp
+
+Uint64 containing Unix timestamp in UTC timezone.
+
+~~~ ascii-art
+  0                   1                   2                   3
+  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |                          Timestamp                            |
+ |                                                               |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~~~
+
+
+### String
+
+String is prefixed with two octets indicating number of bytes that it occupies.
+Text is encoded using UTF-8.
+
+~~~ ascii-art
+  0                   1                   2                   3
+  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |             Length            |         UTF-8 string        ...
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~~~
+
+Figure: String Layout
+
+## Payload types
+
+Payload type attributes describes following characteristics:
+
+* R - Reserved: implementattion should ignore payloads of this type
+* S - Server: can be send only by a server
+* C - Client: can be send only by a client
+* E - Empty: signals an event but does not carry any data
+
+| Type | Name      | Attributes |
+|------|-----------|------------|
+| 0x00 |           | R          |
+| 0x01 | Success   |  SCE       |
+| 0x02 | Error     |  S         |
+| 0x03 | Handshake |  SC        |
+| 0x04 | Auth      |   C        |
+| 0x05 | Message   |  SC        |
+| 0xFF | Test      | R          |
+
+### Success
+
+Payload is always empty for this type.
+
+### Error
+
+~~~ ascii-art
+  0
+  0 1 2 3 4 5 6 7
+ +-+-+-+-+-+-+-+-+
+ |  Error Type   |
+ +-+-+-+-+-+-+-+-+
+ ~~~
+
+#### Error types
+
+| Type | Description                                |
+|------|--------------------------------------------|
+| 0x01 | Auth failed. Invalid username or password. |
+
+### Handshake
+
+~~~ ascii-art
+  0                   1
+  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |   ver_major   |   ver_minor   |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~~~
+
+### Auth
+
+~~~ ascii-art
+  0                   1
+  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |   username (string)         ...
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |   password (string)         ...
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~~~
+
+### Message
+
+~~~ ascii-art
+  0                   1                   2                   3
+  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |                        source_address (string)              ...
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |                        target_address (string)              ...
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |                          timestamp                            |
+ |                                                               |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |                        message_content (string)             ...
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~~~
+
+
+
+### Test
+
+Test payload is used for encoder and decoders testing. Clients and servers
+should ignore this kind of payload.
+
+~~~ ascii-art
+  0                   1                   2                   3
+  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | num1 (uint8)  | time1 (timestamp)                             |
+ |               +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
+ |               | str1 (string)                               ...
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |         num2 (uint16)         | str2 (string)                 |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |                        num3 (uint32)                          |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |                        str3 (string)                          |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |                        num4 (uint64)                          |
+ |                                                               |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~~~
+
+## Sequential operations
+
+Some perations require multiple rounds of communication.
+In this case payloads are send in a sequence. Payload that is not part of this
+specific operation (for example incomming message) cannot interrupt this process.
+
+### Connection initialization
+
+- Client: Initialize TCP connection.
+- Client:  Send *handshake*.
+- Server: If *major* version of protocol differs close the connection.
+- Server: Otherwise send *handshake*.
+- Client: Send *auth*.
+- Server: If user credentials does not match send *error* with *auth_failed*.
+- Server: Otherwise send *success*.