From 19a65f220bf326dd46f143c8292fa55d2b5c9bc3 Mon Sep 17 00:00:00 2001 From: bt Date: Wed, 25 Mar 2026 23:44:41 +0100 Subject: [docs] Rewrite docs --- PROTOCOL.md | 87 ------------------- README.md | 2 +- docs/Makefile | 34 ++++++++ docs/rfc.md | 263 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 298 insertions(+), 88 deletions(-) delete mode 100644 PROTOCOL.md create mode 100644 docs/Makefile create mode 100644 docs/rfc.md 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*. -- cgit v1.2.3