gab2/SPECIFICATION.md

GAB - Client specification

Abstract

'gab' is a serverless chat protocol, using world-readable files, stored under recoginizable names in individual users' home directories. All files need to follow specified format to be included in the communication between server's users.

Data exchange

Entries from individual users' file are actively gathered by each client started, separately. There is no system-wide caching available, creators of new applications using the protocol might consider implementing their own, more sophisticated ways of collecting and filtering the most current entries.

File format

File sizes

The size of a single 'gab' file must be kept under 12kB each.

File names and locations

'gab' file names follow the convention: 1 Location of the file is always the respective users's home directory; 2 The name '.gab' is reserved for the main (default) channel 3 Messages sent by the user to a specific are stored in .gab-:

• a (prefix .gab, followed by a separator -, followed by the channel name
  For example: .gab-music
• file names should consist of small (Latin-1) characters and - if needed - separators ('-')
• the only exception are national characters in case of channels dedicated to communication in a language different than English. Use of such names might barr the users who are not able to type them on their keyboards. Use of such characters is left for the consideration of the channel creators.

Data format

Each 'gab' file entry consist of:

1. Timestamp

• UNIX Epoch time -> wikipedia
• Nanoseconds are optional for chat clients (if you send messages in below one second intervals you might reconsider your chatting behaviour), but recommended for applications using 'gab' protocol for automated notifications
• The reference format: date +"%s.%N"

2. Separator

• A pipe | character

3. Message itself

• Single line, preferably ASCII or UTF-8, use of ANSI sequences and/or emojis is discouraged, although not prohibited (accessible before fancy)
  Clients may filter or remove ANSI escape sequences at author/administrator's dicrection.
• No wrapping

4. New entries are to be inserted before existing ones. Appending the new messages at the end of the file causes significant cost in read speeds (we are talking reading from multiple files vs writing into one file)

Example entry

A 'raw format' entry:

1628355263.5214212|This is an example 'gab' message.

As rendered in 'gab' reference program:

 testuser  This is an example 'gab' message.

Other possible rendering:

2021-08-07 18:54:23  This is an example 'gab' message.
testuser             - - -

Notes

User names

User/author name is not a part of the specification. Client programs should, when neede, extract it from the full pathname of the currently processed 'gab' file.

/home/testuser/.gab
      ^^^^^^^^

'Private' chats/channels

'Private' channels are by convention marked by a ! attached to the 'gab' file name.

.gab-regular-chat
.gab-private-conversation!

Well-behaved programs using the 'gab' protocol should refrain from listing the private channels in their channel directiories/selection boxes.