Add readme.

broker/readme.md

@@ -1,4 +0,0 @@
-```
-cargo build -r -p neon_broker --features bench && target/release/neon_broker
-target/release/neon_broker_bench -s 1 -p 1
-```

broker/src/bin/bench.rs

@@ -18,6 +18,10 @@ timeline publishers and subscribers; each publisher continiously sends
 messages, subscribers read them. Each second the tool outputs number of
 messages summed across all subscribers and min number of messages
 recevied by single subscriber.
+
+For example,
+cargo build -r -p neon_broker --features bench && target/release/neon_broker
+target/release/neon_broker_bench -s 1 -p 1
 "#;
 
 #[derive(Parser, Debug)]

broker/src/bin/neon_broker.rs

@@ -13,7 +13,7 @@
 //! subscribers.
 //!
 //! Only safekeeper message is supported, but it is not hard to add something
-//! else with templating.
+//! else with generics.
 use clap::{command, Parser};
 use futures_core::Stream;
 use futures_util::StreamExt;

docs/broker.md

@@ -0,0 +1,25 @@
+# Neon broker
+
+Neon storage broker targets two issues:
+- Allowing safekeepers and pageservers learn which nodes also hold their
+  timelines, and timeline statuses there.
+- Avoiding O(n^2) connections between storage nodes while doing so.
+
+This is used
+- By pageservers to determine the most advanced and alive safekeeper to pull WAL from.
+- By safekeepers to synchronize on the timeline: advance
+  `remote_consistent_lsn`, `backup_lsn`, choose who offloads WAL to s3.
+
+Technically, it is a simple stateless pub-sub message broker based on tonic
+(grpc) making multiplexing easy. Since it is stateless, fault tolerance can be
+provided by k8s; there is no built in replication support, though it is not hard
+to add.
+
+Currently, the only message is `SafekeeperTimelineInfo`. Each safekeeper, for
+each active timeline, once in a while pushes timeline status to the broker.
+Other nodes subscribe and receive this info, using it per above.
+
+grpcurl can be used to check which values are currently being pushed:
+```
+grpcurl -proto broker/proto/broker.proto -d '{"all":{}}' -plaintext localhost:50051 neon_broker.NeonBroker/SubscribeSafekeeperInfo
+```

docs/sourcetree.md

@@ -2,6 +2,11 @@
 
 Below you will find a brief overview of each subdir in the source tree in alphabetical order.
 
+`broker`:
+
+Neon storage broker, providing messaging between safekeepers and pageservers.
+[broker.md](./broker.md)
+
 `/control_plane`:
 
 Local control plane.