Merge pull request #2 from sorki/srk/readme

README

Author: sorki

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Version [0.1.5.1](https://github.com/sorki/haskell-zre/compare/0.1.5.0...0.1.5.1) (2023-11-28)
 
 * Fix missing `void` import for GHC9.6.3
+* Allow `binary >= 0.8`
 
 # Version [0.1.5.0](https://github.com/sorki/haskell-zre/compare/0.1.4.0...0.1.5.0) (2022-02-28)
 

README.md

@@ -0,0 +1,119 @@
+# zre
+
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/sorki/haskell-zre/ci.yaml?branch=master)](https://github.com/sorki/haskell-zre/actions/workflows/ci.yaml)
+[![Hackage version](https://img.shields.io/hackage/v/zre.svg?color=success)](https://hackage.haskell.org/package/zre)
+[![Dependencies](https://img.shields.io/hackage-deps/v/zre?label=Dependencies)](https://packdeps.haskellers.com/feed?needle=zre)
+
+ZRE protocol implementation https://rfc.zeromq.org/spec:36/ZRE/
+
+Peer-to-peer local area networking with reliable group messaging
+and automatic peer discovery.
+
+## Usage
+
+Dependencies:
+
+```
+zeromq4
+```
+
+Clone and test
+
+```sh
+git clone https://github.com/sorki/haskell-zre/
+cd haskell-zre
+nix-build
+./result/bin/zre
+# in another terminal or networked computer
+./result/bin/zre
+```
+
+Two zre peers should find each other and be able to send message between each other.
+Firewall needs to allow traffic on UDP port 5670 and TCP port range 41000-41100.
+Application picks random port from this range and advertises it to network.
+
+## Applications
+
+Few applications are provided to get you started:
+
+ - zre - interact and dump events
+ - zrecat <group> - cat messages for group
+
+These can be installed locally using `pkgs.haskellPackage.zre`.
+
+Try running multiple copies of `zre` and `zrecat` on
+the same computer or computers on the local network
+
+```sh
+zre
+# another terminal
+zrecat test
+# now in original terminal you can join testgroup with
+> /join test
+# or send messages to it
+> /shout test msg
+```
+
+Send uptime periodically to uptime group
+
+```sh
+( while true; do uptime; sleep 1; done ) | zrecat uptime
+```
+
+Cat file to group
+
+```sh
+cat /etc/os-release | zrecat test
+```
+
+Interact manually
+
+```sh
+zre
+# in zre shell following commands are supported:
+> /join time
+> /shout time test!
+> /leave time
+> /join uptime
+> /whisper <uuid> message
+```
+
+## ZGossip
+
+Implementation of gossip protocol is included in form of key value TTL server.
+This allows connecting peers from different networks (or subnets) not reachable via multicast
+beacon. This service requires TCP port 31337 and can be started with `zgossip-server` binary.
+
+Run server
+
+```sh
+zgossip_server
+```
+
+Pass gossip endpoint to apps with
+
+```sh
+zre -g <gossip_ip>:31337
+```
+
+## Configuration
+
+ZRE applications using `runZre` will automatically try to load configuration
+file if `ZRECFG` environment variable points to it. See `zre.conf` for configuration
+example::
+
+```sh
+ZRECFG=./zre.conf zrecat test
+```
+
+To be able to use one config for multiple apps and still be able to distinguish between
+them you can also set `ZRENAME` environment variable which overrides name
+from config or default config if `ZRECFG` is not used::
+
+```sh
+ZRENAME=zrenode1 zrecat test
+```
+
+## Demos
+
+* https://asciinema.org/a/106340

README.rst

@@ -17,7 +17,7 @@ build-type:          Simple
 cabal-version:       2.0
 extra-source-files:
   CHANGELOG.md
-  README.rst
+  README.md
   zre.conf
 
 flag examples
@@ -57,7 +57,7 @@ library
                      , network-bsd ^>= 2.8
                      , network-info ^>= 0.2
                      , network-multicast ^>= 0.3
-                     , binary ^>= 0.8
+                     , binary >= 0.8
                      , bytestring
                      , containers
                      , directory