DOne with docs for now 🎉
This commit is contained in:
parent
5d433b078c
commit
cda89e9530
|
|
@ -365,8 +365,8 @@ ideas at `contact at vaporsoft.xyz`. I will reply to all messages.
|
|||
|
||||
Check out the following links:
|
||||
|
||||
* (WIP) [Developer Docs and Specification](dev_docs.md)
|
||||
* (WIP) [Message Format Specification](message_format.md)
|
||||
* [Message Format Specification](message_format.md)
|
||||
* [Bundle Format Specification](dev_docs.md)
|
||||
* [Frequently Asked Questions](faq.md)
|
||||
* [Roadmap](roadmap.md)
|
||||
* [Ideas and Features](ideas.md)
|
||||
|
|
|
|||
87
dev_docs.md
87
dev_docs.md
|
|
@ -19,8 +19,7 @@ weather_reported_by:USER.GGP2VX0ZN41EYXMN81YB0Q4AEKRCVZ5RD1F1PHPY3748HAZSHZC4
|
|||
signature JSPJJQJRVBVGV52K2058AR2KFQCWSZ8M8W6Q6PB93R2T3SJ031AYX1X74KCW06HHVQ9Y6NDATGE6NH3W59QY35M58YDQC5WEA1ASW08
|
||||
```
|
||||
|
||||
The specifics of the message format are explained line-by-line [in the message format explanation document](message_format.md).
|
||||
Please read this document before continuing.
|
||||
The specifics of the message format are explained line-by-line [in the message format explanation document](message_format.md). **Please read the message format explanation document before continuing.**
|
||||
|
||||
# Bundles: The Transmission Medium
|
||||
|
||||
|
|
@ -29,7 +28,9 @@ A message without a receiver is not very useful. Any peer in a Pigeon cluster ha
|
|||
* 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 sends messages and files to peers through the use of "bundles". Bundles are a file directory arranged in a predictable layout that is specified by the protocol. Peers share bundles with each other through a variety of means. When a peer unpacks a bundle into their local database, the database contents are updated with new information from peers such as messages and blobs (files).
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -40,57 +41,48 @@ Pigeon follows the philosophy of "offline-first means offline-only". Bundle file
|
|||
|
||||
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
|
||||
## Where Do Messages Go in a Bundle?
|
||||
|
||||
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.
|
||||
A bundle's [message](message_format.md) payload (as opposed to its blob 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:
|
||||
|
||||
```
|
||||
author @RZW2HE8MQFRH93NP3YKWC1QGZ6VWDZW1WZPMEKQ5MP0NM6TE54W0.ed25519
|
||||
kind FILE.FV0FJ0YZADY7C5JTTFYPKDBHTZJ5JVVP5TCKP0605WWXYJG4VMRG
|
||||
author USER.R68Q26P1GEFC0SNVVQ9S29SWCVVRGCYRV7D96GAN3XVQE3F9AZJ0
|
||||
depth 0
|
||||
kind chat_message
|
||||
lipmaa NONE
|
||||
prev NONE
|
||||
depth 0
|
||||
lipmaa 0
|
||||
|
||||
a:"b"
|
||||
content:"Hello, world!"
|
||||
|
||||
signature MYTASNHSPJCV8GH59EEBX27CJHW2N6K02A3MTNFHWHSPDSQKHTMKR23WQS71MTQY0ED4CSK88XNJJ8PV5W9F1BREDR0NZ2CMMRRFT20
|
||||
signature 2VMAG4SCX5RHVBKCB1RNZCB0AJN4WN6FEMS7W9FM1CVYSZXMX7CPQFCDPYEKCTGG91Y1YSGY4G5K8XAGQ67HEPDFRMRYQHWQBATAC2R
|
||||
|
||||
author @RZW2HE8MQFRH93NP3YKWC1QGZ6VWDZW1WZPMEKQ5MP0NM6TE54W0.ed25519
|
||||
kind a
|
||||
prev %XKB8MVA3AZZAG1D29AHPG33G2T8BWAGRKJ0DJ4H01MGPM5R9Y3RG.sha256
|
||||
author USER.R68Q26P1GEFC0SNVVQ9S29SWCVVRGCYRV7D96GAN3XVQE3F9AZJ0
|
||||
depth 1
|
||||
lipmaa 0
|
||||
kind chat_message
|
||||
lipmaa NONE
|
||||
prev TEXT.6CBA4J3756A5SNM1W1GHNCTT9EG95ZP3ZMAT5Z1EJP7TXMNNVZC0
|
||||
|
||||
FILE.FV0FJ0YZADY7C5JTTFYPKDBHTZJ5JVVP5TCKP0605WWXYJG4VMRG:"b"
|
||||
content:"Good morning!"
|
||||
|
||||
signature 5Y8KQVMJ0BADEPWZEXSMYYVMVE5JYQ0069RQ4S80CT9GA64KCRVTWYSK3V728J024916P9SVZ62W9HVZ189C6PANHWD23T07C779P2R
|
||||
signature Y34Q47V0BY370RM5KWGRJRN9HFNGJN0C3DEYVB2V2476CW9RN5HD4XD7KMQ6T4T42N36R5P3XX6E3FYEWVZR25AVCF6KQPZHJP6EM10
|
||||
|
||||
author @RZW2HE8MQFRH93NP3YKWC1QGZ6VWDZW1WZPMEKQ5MP0NM6TE54W0.ed25519
|
||||
kind a
|
||||
prev %5N0KJN0TSWRVMXY3JF0FAJRXXDB1AHT9YXBTKE2V7H98GKQND4PG.sha256
|
||||
author USER.0JZA9F3EQVX3NAG69D7VRYCGRVVCWS92S9QVVNS0CFEG1P62Q86R
|
||||
depth 2
|
||||
lipmaa 1
|
||||
kind like
|
||||
lipmaa NONE
|
||||
prev TEXT.GAP6NJ21K6N75RAEJQ10C2QHFXNRHVPMC54FMGVA77CDJ8AVZQB5
|
||||
|
||||
b:FILE.FV0FJ0YZADY7C5JTTFYPKDBHTZJ5JVVP5TCKP0605WWXYJG4VMRG
|
||||
|
||||
signature 7XSFRS28B5T6GN0XEYAASFQQAJG9YTVNSXQY0JD8XHYHPQVNK2VSH081PS9CNPNKEAEJGEPXZR6GSZ21SV1HTKQ7R3SZ49P8PHRER18
|
||||
|
||||
author @ET6MN0PM5WQKEMPZ3PN39HRFQM8EH2WZRW10W45ZDWV6ZGQ1CWKY.ed25519
|
||||
kind ab606fa8-958e-45e6-9856-0103217ce0a9
|
||||
prev %HT23KER8VQJFMFDAWX7RX6CCXVVCZ2H2C9H1HEA5ZNC9A6MAFXG0.sha256
|
||||
depth 0
|
||||
lipmaa 2
|
||||
|
||||
foo:"f6a627ce-9e0d-4faa-9146-bd4e56b61811"
|
||||
|
||||
signature 3NQ3P4J3TJSWH7WTJ0T4WCTVDVX1QAVW31G0K5T59F3X1DRYE3ECD1YVFJ0PT85RTRPD2GG8H091F8TG2A7CV36J8N5Y69RYGTQJE08
|
||||
target:TEXT.5BQZVA8JDC77AVGMF45CMPVHRNXFHQ2C01QJEAR57N6K12JN6PAG
|
||||
|
||||
signature W68NWDQB2WTZ8T1RHP5BZA4N1STVKV16K0PXH10MZVR3XTF8HC7T8646X7SAKP5DFZ5K74QEKE3T2K6V0EST50YQQD7FD2PT0H8J62G
|
||||
```
|
||||
|
||||
The example above is multiple pigeon messages joined together with a carraige return ("\n").
|
||||
The file contains the messages of two authors (`@ET6MN...`, `@RZW2H...`).
|
||||
The example above is multiple pigeon messages joined together with a carriage return ("\n").
|
||||
**Notice that not all messages were created by the same author.**
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -99,36 +91,35 @@ A peer can use the file above to update their local database. It is important to
|
|||
* 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.
|
||||
* Clients always reject messages that cannot be verified. For example, if a `messages.pgn` file starts at `depth 6` for a peer `USER.ABC`, and the local client has only verified `USER.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
|
||||
* Messages may be verified using the `lipmaa` property to avoid copying an entire feed into a bundle (eg: bundling only a subset of messages).
|
||||
|
||||
Some things for Pigeon implementors to note about bundles:
|
||||
# Where Do Files Go in a Bundle?
|
||||
|
||||
* It can contain other peoples messages
|
||||
* It is advisable to only ingest blobs that are referenced
|
||||
Since Pigeon messages can contain files (blobs), we need a way to include those files with the bundle. Blobs are added to bundles using a series of nested directories, shown in the example below.
|
||||
|
||||
Example:
|
||||
|
||||
a user exports a bundle that contains a few messages and the following blobs:
|
||||
|
||||
```
|
||||
FILE.622PRNJ7C0S05XR2AHDPKWMG051B1QW5SXMN2RQHF2AND6J8VGPG
|
||||
FILE.FV0FJ0YZADY7C5JTTFYPKDBHTZJ5JVVP5TCKP0605WWXYJG4VMRG
|
||||
FILE.FV0FJ0YZADY7C5JTTFYPKDBHTZJ5JVVP5TCKP0605WWXYJG4VMRG
|
||||
FILE.FV0FJ0YZADY7C5JTTFYPKDBHTZJ5JVVP5TCKP0605WWXYJG4VMRG
|
||||
FILE.YPF11E5N9JFVB6KB1N1WDVVT9DXMCHE0XJWBZHT2CQ29S5SEPCSG
|
||||
```
|
||||
|
||||
Assuming the user's client follows this specification, the exported bundles strucutre would be laid out as follows on the local filesystem:
|
||||
If you exported a bundle that references these files, the directory structure of the bundle will look like this on the local filesystem:
|
||||
|
||||
```
|
||||
├── messages.pgn
|
||||
├── messages.pgn <= Explained in previous section.
|
||||
├── 622PRNJ
|
||||
│ └── 7C0S05X
|
||||
│ └── R2AHDPK
|
||||
│ └── WMG051B
|
||||
│ └── 1QW5SXM
|
||||
│ └── N2RQHF2
|
||||
│ └── AND6J8V.GPG
|
||||
│ └── AND6J8V.GPG <= The contents of 622...GPG are here
|
||||
├── FV0FJ0Y
|
||||
│ └── ZADY7C5
|
||||
│ └── JTTFYPK
|
||||
|
|
@ -144,7 +135,3 @@ Assuming the user's client follows this specification, the exported bundles stru
|
|||
└── BZHT2CQ
|
||||
└── 29S5SEP.CSG
|
||||
```
|
||||
|
||||
# Up Next
|
||||
|
||||
This concludes the developer documentation. Please email us with questions. To learn more, continue to the [idea bin](IDEAS.md).
|
||||
|
|
|
|||
Loading…
Reference in New Issue