The most important protocol concept is that of the "message".
In their most simple form, Pigeon protocol messages are just ASCII text documents. They are human readable and can even be created by hand in a text editor, though most clients will provide better means of authoring messages.
A message without a receiver is not very useful. Any peer in a Pigeon cluster has two things it needs to share with its peers:
* Messages, created by the peer or forwarded on behalf of a "peer of a peer"
* Files, in the form of blobs
Pigeon sends messages and files to peers through the use of "bundles", which are simply a filesystem directories that is arranged in a predictable layout. The directories are transmitted over any medium that supports file transfer (the protocol does not involve itself with such concerns).
Pigeon follows the philosophy of "offline-first means offline-only". Bundle files could theoretically be:
* Transmitted over removable media such as USB drives or optical media (CD).
* Compressed using zip compression to increase storage capacity.
* Encrypted using tools like PGP
* Hosted and dynamically updated on a web server for network retrieval.
The protocol does not place any restrictions on how bundles are handled, transported, compressed or encrypted. It does, however, dictate the internal layout of the bundle. Authors of protocol clients must pay special attention to how bundles are created to ensure security and interoperability between client implementations.
## The Structure of a Bundle: Messages
A bundle's message payload is contained in a plaintext file at the root bundle directory. The file is named `messages.pgn`. Messages are joined together via carriage return (`\n`). Typically, `messages.pgn` will contain messages created by the bundle's author, plus messages created by the author's peers.
Here is an example of the contents of a `messages.pgn` file:
The example above is multiple pigeon messages joined together with a carraige return ("\n").
The file contains the messages of two authors (`@ET6MN...`, `@RZW2H...`).
A peer can use the file above to update their local database. It is important to note that **a client will always reject a message that it cannot verify**. Below is an example of a refused update:
* Peer A has verified peer B's messages up to `depth 5`.
* Peer C sends Peer A a new bundle.
* The bundle contains messages authored by peer B, starting at `depth 8`.
* Since Peer A cannot verify message at `depth 8` until it receives `depth 7` and `depth 6`, the messages are rejected by peer A.
* Clients always reject message that cannot be verified. For example, if a `messages.pgn` file starts at `depth 6` for a peer `@ABC`, and the local client has only verified `@ABC`s feed up to `depth 3`, the messages in the bundle will be rejected by the local client because it does not have enough information available to verify the authenticity of the message.
* Messages must be ordered `depth` for a particular author.
* Messages
Some things for Pigeon implementors to note about bundles:
* It can contain other peoples messages
* It is advisable to only ingest blobs that are referenced