parsimony/README.md
tgiachi 2d8b0ccce6 feat(cli): command-line client for administration
- Add parsimony list, member, held, archive and queue subcommands over the REST API
- Read the token only from PARSIMONY_API_TOKEN; take the URL from --url or PARSIMONY_URL
- Print tables by default and JSON with --json
- Add member import from a file or stdin, reporting failing lines and exiting non-zero
- Require --yes for destructive commands
- Add parsimony serve; keep the old -config invocation working
- Run the CLI inside the container in the end-to-end test
- Test every command against the real API handler; mutation checks over the CLI
2026-11-09 16:57:25 +01:00

134 lines
6.2 KiB
Markdown

# parsimony
A modern, single-binary mailing list manager: an evolution of Mailman.
- Postfix delivers to parsimony over LMTP; parsimony relays through SMTP.
- Discussion lists with member-only posting, `List-*` headers, one-click unsubscribe
and DMARC-safe `From` rewriting.
- Durable outbound queue: a post is accepted once it is stored, one delivery per recipient,
and a background worker sends it with retries (1m, 5m, 15m, 1h, 3h, then every 6h, for up to
3 days). Relay outages and restarts lose nothing.
- Self-service subscribe and unsubscribe by email with double opt-in:
send to `list+join@domain` or `list+leave@domain`, then reply to the confirmation.
- Moderated lists: posts wait in a queue that the API can approve or discard.
- VERP bounces: every recipient gets a signed return address; 3 hard bounces disable a member.
- Archive with full-text search (SQLite FTS5) and threading. Each list has an
`archive_policy`: `private` (default, API only), `public` (web pages) or `off`.
Public pages hide email addresses.
- Per-recipient one-click unsubscribe links (RFC 8058) with signed tokens.
- SQLite storage, one YAML config file.
- Command-line client for administration and scripts (`parsimony list|member|held|archive|queue`).
- Admin REST API under `/api/v1` (see `docs/openapi.yaml`).
- Admin web UI (Vite, React, shadcn/ui) served by the API listener at `/`: lists, settings,
members, held queue and archive.
## Run
```
cp parsimony.example.yaml parsimony.yaml
PARSIMONY_API_TOKEN=<token> go run ./cmd/parsimony serve -config parsimony.yaml
```
The API is disabled when `PARSIMONY_API_TOKEN` is not set.
Three listeners, each configurable:
| Listener | Default | Purpose |
|----------|---------|---------|
| `lmtp` | `127.0.0.1:2424` | mail from Postfix |
| `api` | `127.0.0.1:8080` | admin REST API, bearer token |
| `web` | `127.0.0.1:8081` | public archive and unsubscribe pages (`""` disables) |
Put the `web` listener behind a reverse proxy with TLS and set `base_url` to its public URL:
the unsubscribe links in every message use it. Keep the `api` listener private.
```
curl -H "Authorization: Bearer $PARSIMONY_API_TOKEN" -d '{"name":"dev","domain":"example.org","title":"Dev"}' localhost:8080/api/v1/lists
```
## Command line
The same binary is an administration client. It talks to the REST API, so it works against a local or remote daemon.
```
export PARSIMONY_API_TOKEN=... # the token is never a flag
export PARSIMONY_URL=http://127.0.0.1:8080 # default; --url overrides
parsimony list add dev@example.org --title "Developers"
parsimony list set dev@example.org --post moderated --archive public
parsimony member add dev@example.org alice@example.com --name Alice
parsimony member import dev@example.org subscribers.txt # "email[,name]" per line, "-" reads stdin
parsimony held ls dev@example.org
parsimony held approve 12
parsimony archive ls dev@example.org --q "deploy"
parsimony queue ls
parsimony --json list ls # JSON for scripts
parsimony help
```
`<list>` is an address or a numeric id. Destructive commands (`list rm`, `archive rm`) need `--yes`.
Exit status: 0 success, 1 failure (including lines that failed in `member import`), 2 usage error.
`parsimony serve -config FILE` runs the daemon; the old `parsimony -config FILE` form still works.
In the container: `docker exec parsimony /parsimony list ls`.
## Docker
The image runs as an unprivileged user (uid 65532) and works with a read-only root filesystem.
Config is mounted read-only; the only writable path is the `/data` volume (the database).
```
docker build -t parsimony .
docker run -d --name parsimony --read-only --cap-drop ALL \
-v parsimony-data:/data \
-v $PWD/parsimony.yaml:/etc/parsimony/parsimony.yaml:ro \
-e PARSIMONY_API_TOKEN=... -p 2424:2424 -p 8080:8080 -p 8081:8081 parsimony
```
Use `db: /data/parsimony.db` in the config. A new named volume gets the right ownership by itself;
for a bind mount, make the host directory writable by uid 65532.
## Delivery and the queue
LMTP answers `250` when the post is in the queue, so a down relay never bounces mail back to Postfix.
It answers `451` only when the database itself fails.
- Temporary relay errors (4xx, timeouts, connection failures) are retried with backoff.
- A permanent rejection (5xx) drops that delivery. Only a bad-mailbox reply (`5.1.x`) counts as a hard
bounce for the member; errors such as "relay access denied" never disable members.
- Delivery is at-least-once: a crash between the relay accepting a message and the queue entry being
removed can send one message to one recipient twice.
- `GET /api/v1/queue` and the Queue page show what is pending or failing, and a stuck delivery can be discarded.
## Admin UI
The UI is a single-page app in `admin/`, built into `internal/adminui/dist` and embedded in the binary.
It is served on the API listener together with `/api`, so it needs no CORS, and only when
`PARSIMONY_API_TOKEN` is set. You sign in with that token (kept in `sessionStorage`, gone when the tab closes).
```
make admin # npm ci && npm run build
make build # go build, embeds the UI
make test # go test + vitest
make e2e # end-to-end with a real Postfix in Docker (about 2 minutes, mostly the image build)
```
Without `make admin` the binary still builds and the UI answers 503 with a hint.
For frontend work run the daemon, then `cd admin && npm run dev` (Vite proxies `/api` to `127.0.0.1:8080`).
## End-to-end test
`make e2e` starts a real Postfix and parsimony in Docker and walks the whole path: Postfix hands list mail to
parsimony over LMTP, parsimony queues it and relays the copies back through Postfix, which delivers them to
maildirs. It checks the list headers and VERP return path, a real `550 5.1.1` from Postfix disabling a member after
three hard bounces, a real LMTP `550` for a non-member, join and leave by email, moderation, the public archive
and one-click unsubscribe. The files are in `e2e/` and behind the `e2e` build tag, so `go test ./...` stays fast.
## Postfix
Deliver the list domains to parsimony over LMTP and keep the `+` extensions intact, for example:
```
transport_maps = hash:/etc/postfix/transport
# /etc/postfix/transport
lists.example.org lmtp:inet:127.0.0.1:2424
```