Adding Protocol specification to docs (WIP) #1727

Closed
g1itch wants to merge 12 commits from doc into v0.6
2 changed files with 83 additions and 0 deletions
Showing only changes of commit fe3aa76585 - Show all commits

View File

@ -0,0 +1,55 @@
Extended encoding
=================
Extended encoding is an attempt to create a standard for transmitting structured
data. The goals are flexibility, wide platform support and extensibility. It is
currently available in the v0.6 branch and can be enabled by holding "Shift"
while clicking on Send. It is planned that v5 addresses will have to support
this. It's a work in progress, the basic plain text message works but don't
expect anthing else at this time.
The data structure is in msgpack, then compressed with zlib. The top level is
a key/value store, and the "" key (empty string) contains the value of the type
of object, which can then have its individual format and standards.
Text fields are encoded using UTF-8.
Types
-----
You can find the implementations in the ``src/messagetypes`` directory of
PyBitmessage. Each type has its own file which includes one class, and they are
dynamically loaded on startup. It's planned that this will also contain
initialisation, rendering and so on, so that developers can simply add a new
object type by adding a single file in the messagetypes directory and not have
to change any other part of the code.
message
^^^^^^^
The replacement for the old messages. Mandatory keys are ``body`` and
``subject``, others are currently not implemented and not mandatory. Proposed
other keys:
``parents``:
array of msgids referring to messages that logically precede it in a
conversation. Allows to create a threaded conversation view
``files``:
array of files (which is a key/value pair):
``name``:
file name, mandatory
``data``:
the binary data of the file
``type``:
MIME content type
``disposition``:
MIME content disposition, possible values are "inline" and "attachment"
vote
^^^^
Dummy code available in the repository. Supposed to serve voting in a chan
(thumbs up/down) for decentralised moderation. Does not actually do anything at
the moment and specification can change.

View File

@ -210,6 +210,34 @@ Unencrypted Message Data
Message Encodings
"""""""""""""""""
.. list-table::
:header-rows: 1
:widths: auto
* - Value
- Name
- Description
* - 0
- IGNORE
- Any data with this number may be ignored. The sending node might simply
be sharing its public key with you.
* - 1
- TRIVIAL
- UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings
of data, like URIs or magnet links.
* - 2
- SIMPLE
- UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
::
messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message
* - 3
- EXTENDED
- See :doc:`extended_encoding`
Further values for the message encodings can be decided upon by the community.
Any MIME or MIME-like encoding format, should they be used, should make use of
Bitmessage's 8-bit bytes.
Pubkey bitfield features
""""""""""""""""""""""""