diff options
| -rw-r--r-- | doc/overview.org | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/doc/overview.org b/doc/overview.org new file mode 100644 index 0000000..d399a16 --- /dev/null +++ b/doc/overview.org @@ -0,0 +1,51 @@ +* Components +** HBBP + - UDP `broadcast` and `listener` + - transmit a zero-terminated key and an optional arbitrary-binary + payload: key is comparable to an HTTP URI, the payload to HTTP + POST data + - IPv6-only + - restricted to a single network using link-local broadcast and + listening on only interface +*** Usage +*** Wire format + One of: + - <key> + - <key> \0 <payload> + + encapsulated in IPv6 UDP. <key> must not contain \0. +** P2P tables + P2P tables are a lightweight distributed key-value store with + built-in collision arbitration. Eventual consistency is maintained + using a HBBP-based gossip protocol. +*** Usage + - p2ptbl init <table> :: create a new table named <table> + - p2ptbl update <table> <key> <value> [iface] :: set the value of + <key> to <value> in <table> no matter if <key> existed before + or not; If given, broadcast the update over [iface] + - p2ptbl get <table> <key> :: get the value of <key> in <table> or + zero output if <key> does not exist in <table> + - p2ptbl gossip <table> <size> <iface> :: broadcast <table> over + <iface>; Send at most <size> bytes compressed table data: if + the table is larger, a random subset is sent + + All tables are stored in /tmp/p2ptbl/table. The above tools + require the full path to the table. + + To be synchronized via gossip protocol, a table must be enabled + for receiving updates by symlinking /hbbp/p2ptbl/<table> to + /sbin/p2ptbl-recv. +*** P2P table format + - tab separated + - fields + - key :: per-table unique token + - version :: integer + - value(s) :: anything, tab-separated + - on merge of two tables, for each key the variant with the + largest version number wins + - on update, the version number is incremented by some + sufficiently large random amount (to avoid collisions) + ... e.g. 2^32 +*** Gossip protocol + HBBP with key "p2ptbl/<table-name>" and gzip-compressed shuffled + random subsets of a table as payload. |