Server tools to backfill, tail, mirror, and verify PLC logs
1# Allegedly
2
3Some [public ledger](https://github.com/did-method-plc/did-method-plc) tools and services for servers
4
5Allegedly can
6
7- Tail PLC ops to stdout: `allegedly tail | jq`
8- Export PLC ops to weekly gzipped bundles: `allegdly bundle --dest ./some-folder`
9- Dump bundled ops to stdout FAST: `allegedly backfill --source-workers 6 | pv -l > /ops-unordered.jsonl`
10- Wrap the reference PLC server and run it as a mirror, copying ops from upstream:
11
12 ```bash
13 allegedly mirror \
14 --wrap "http://127.0.0.1:3000" \
15 --wrap-pg "postgresql://user:pass@pg-host:5432/plc-db"
16 ```
17
18- Wrap a plc server, maximalist edition:
19
20 ```bash
21 # put sensitive values in environment so they don't leak via process name.
22 export ALLEGEDLY_WRAP_PG="postgresql://user:pass@pg-host:5432/plc-db"
23
24 # sudo to bind :80 + :443 for acme tls, but it's better to give user net cap.
25 # will try to autoprovision cert for "plc.wtf" from letsencrypt staging.
26 sudo allegedly mirror \
27 --upstream "https://plc.directory" \
28 --wrap "http://127.0.0.1:3000" \
29 --wrap-pg-cert "/opt/allegedly/postgres-cert.pem" \
30 --acme-domain "plc.wtf" \
31 --acme-domain "alt.plc.wtf" \
32 --experimental-acme-domain "experimental.plc.wtf" \
33 --acme-cache-path ./acme-cache \
34 --acme-directory-url "https://acme-staging-v02.api.letsencrypt.org/directory" \
35 --acme-ipv6 \
36 --experimental-write-upstream
37 ```
38
39- Reverse-proxy to any PLC server, terminating TLS and forwarding writes upstream
40
41 ```bash
42 sudo allegedly wrap \
43 --wrap "http://127.0.0.1:3000" \
44 --acme-ipv6 \
45 --acme-cache-path ./acme-cache \
46 --acme-domain "plc.wtf" \
47 --experimental-acme-domain "experimental.plc.wtf" \
48 --experimental-write-upstream \
49 --upstream "https://plc.wtf" \
50 ```
51
52
53add `--help` to any command for more info about it
54
55
56## install
57
58```bash
59cargo install allegedly
60```
61
62the version on crates might be behind while new features are under development.
63to install the latest from source:
64
65- make sure you have rust/rustup set up
66- clone the repo
67- install
68
69 ```bash
70 cargo install --path . --bin allegedly
71 ```
72
73
74## future improvements
75
76### existing stuff
77
78- signals and shutdown handling
79- monitoring of the various tasks
80- health check pings
81- expose metrics/tracing
82- [x] read-only flag for mirror wrapper
83- bundle: write directly to s3-compatible object storage
84- helpers for automating periodic `bundle` runs
85
86
87### new things
88
89- [ ] experimental: websocket version of /export
90- [x] experimental: accept writes by forwarding them upstream
91- [ ] experimental: serve a tlog
92- [ ] experimental: embed a log database directly for fast and efficient mirroring
93- [ ] experimental: support multiple upstreams?
94
95- [ ] new command todo: `zip` or `check` or `diff`: compare two plc logs over some time range
96- [ ] new command to consider: `scatter` or something: broadcast plc writes to multiple upstreams
97
98
99if you have an idea for a new command, [open a request](https://tangled.org/@microcosm.blue/Allegedly/issues/new)!
100
101
102## license
103
104This work is dual-licensed under MIT and Apache 2.0. You can choose between one of them if you use this work.
105
106`SPDX-License-Identifier: MIT OR Apache-2.0`