Server tools to backfill, tail, mirror, and verify PLC logs
microcosm.blue
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 --acme-domain "plc.wtf" \
30 --acme-cache-path ./acme-cache \
31 --acme-directory-url "https://acme-staging-v02.api.letsencrypt.org/directory"
32 ```
33
34
35add `--help` to any command for more info about it
36
37
38## install
39
40```bash
41cargo install allegedly
42```
43
44the version on crates might be behind while new features are under development.
45to install the latest from source:
46
47- make sure you have rust/rustup set up
48- clone the repo
49- install
50
51 ```bash
52 cargo install --path . --bin allegedly
53 ```
54
55
56## future improvements
57
58### existing stuff
59
60- signals and shutdown handling
61- monitoring of the various tasks
62- health check pings
63- expose metrics/tracing
64- read-only flag for mirror wrapper
65- bundle: write directly to s3-compatible object storage
66- helpers for automating periodic `bundle` runs
67
68
69### new things
70
71- experimental: websocket version of /export
72- experimental: accept writes by forwarding them upstream
73- experimental: serve a tlog
74- experimental: embed a log database directly for fast and efficient mirroring
75- experimental: support multiple upstreams?
76
77- [ ] new command todo: `zip` or `check` or `diff`: compare two plc logs over some time range
78- [ ] new command to consider: `scatter` or something: broadcast plc writes to multiple upstreams
79
80
81if you have an idea for a new command, [open a request](https://tangled.org/@microcosm.blue/Allegedly/issues/new)!
82
83
84## license
85
86This work is dual-licensed under MIT and Apache 2.0. You can choose between one of them if you use this work.
87
88`SPDX-License-Identifier: MIT OR Apache-2.0`