dujiangyan/packages/zhongli
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Agent Pi e3be58ba97
All checks were successful
/ publish (pull_request) Has been skipped
/ publish-container (pull_request) Has been skipped
/ deploy-docs (pull_request) Has been skipped
/ checks (pull_request) Successful in 6m59s
/ pr-review (pull_request) Successful in 1m1s
/ gitleaks (pull_request) Successful in 45s
🐛 fix: adapt ty ignore comments to ty 0.0.104 rule renames
2026-11-14 11:36:12 +10:00
..
logo Feat: Rename fedibooster to Zhongli 2026-03-02 14:34:36 +10:00
src/zhongli 🐛 align fenliu and zhongli typing with bumped dependencies 2026-10-16 12:19:11 +10:00
tests 🐛 fix: adapt ty ignore comments to ty 0.0.104 rule renames 2026-11-14 11:36:12 +10:00
.editorconfig Move from defunct repo with objectformat=sha256 2024-11-18 13:01:56 +10:00
.gitignore Refactor configuration to load block lists from external sources using 2026-01-22 18:06:29 +10:00
.pre-commit-config.yaml 🐛 fix: adapt ty ignore comments to ty 0.0.104 rule renames 2026-11-14 11:36:12 +10:00
.pysentry.toml Update dependencies and add security ignore files 2026-02-15 07:26:09 +10:00
.python-version feat(zhongli): replace minimal-activitypub with longwei 2026-04-03 20:06:24 +10:00
.uv-secure.toml Feat: Remove legacy code. Zhongli now only works with Fenliu. 2026-03-04 11:09:10 +10:00
AGENTS.md 🎉 add AGENTS.md at all levels, LICENSE.md, .editorconfig; symlink CLAUDE.md 2026-07-20 12:06:39 +10:00
CHANGELOG.md docs(zhongli): update changelog for 2026.8.30 2026-08-30 08:56:31 +10:00
CLAUDE.md 🎉 add AGENTS.md at all levels, LICENSE.md, .editorconfig; symlink CLAUDE.md 2026-07-20 12:06:39 +10:00
Containerfile 🚚 Update Codeberg references to forge.marvin8.zone 2026-08-03 18:41:46 +10:00
entrypoint.py 🐛 zhongli: remove privilege drop that fails in rootless podman 2026-06-23 12:55:17 +10:00
justfile 🚚 Update Codeberg references to forge.marvin8.zone 2026-08-03 18:41:46 +10:00
LICENSE.md Move from defunct repo with objectformat=sha256 2024-11-18 13:01:56 +10:00
logging-config.toml 🔧 zhongli: add timestamp to stdout log format 2026-06-23 12:55:29 +10:00
pyproject.toml 🔧 bump: workspace and package dependency floors, pre-commit hook revs 2026-11-14 11:10:00 +10:00
README.md 🐛 Fix docs links per review feedback 2026-08-04 06:26:16 +10:00
Release-Notes.md 🔧 bump: version 2026.8.15 → 2026.8.30 2026-08-30 08:56:36 +10:00
Release-Notes.md.template 📝 remove spurious trailing em dash from Release-Notes version line 2026-07-12 18:06:06 +10:00
ruff.toml 🔧 align ruff.toml: TID252, py312 target, consistent ignores; enable zhongli format check 2026-07-20 12:07:06 +10:00
Security-Audit.md ⬆️ bump deps and auto reformat by ruff 2026-08-30 08:55:45 +10:00

Zhongli

Automatically boost/reblog Fediverse posts. Formerly Fedibooster.

Repo CI Downloads AGPL

Overview

Zhongli consumes pre-filtered posts from FenLiu's queue and automatically reblogs them to your Fediverse account. FenLiu handles the heavy lifting (filtering, spam detection, curation); Zhongli handles the reblogging and duplicate prevention.

FenLiu configuration is required. There is no legacy mode.

Status

Phase Status Notes
1: Infrastructure ✅ Complete FenLiu client, models, tests
2: FenLiu-Only Mode ✅ Complete ReblogService, queue polling, attachments
3: Validation Optimization ✅ Complete MinimalValidator, pre-filtered posts
4: Documentation ✅ Complete FenLiu-only, updated config
5: UX Polish ⏳ Optional Metrics, dry-run, progress indicators

Install

pip install zhongli

Or from source:

git clone https://forge.marvin8.zone/marvin8/dujiangyan.git
cd zhongli
uv sync
uv run zhongli

Container

Images are published to registry.marvin8.zone/marvin8/zhongli on every release.

Volumes

Path Purpose
/app/config/config.toml Configuration file (required, bind-mount)
/app/data/ SQLite cache database (persist across runs)

Config for container use

Add cache_db_path so the database lands on the persistent volume:

run_continuously = true
delay_between_posts = 300
cache_db_path = "/app/data/cache.db"

[fediverse]
domain_name = "mastodon.social"
api_token = "your-token"

[fenliu]
base_url = "https://fenliu.example.com"
api_key = "your-api-key"

Run as a daemon

podman run -d \
  -v ./config.toml:/app/config/config.toml:ro \
  -v zhongli-data:/app/data \
  registry.marvin8.zone/marvin8/zhongli

Run as a one-shot / cron job

podman run --rm \
  -v ./config.toml:/app/config/config.toml:ro \
  -v zhongli-data:/app/data \
  registry.marvin8.zone/marvin8/zhongli \
  /app/config/config.toml --max-posts 10

The container starts as root, fixes config permissions to 0600, then drops to an unprivileged zhongli user (UID 1000) before running.

Health check

The image includes a HEALTHCHECK that passes as long as /app/data/zhongli.log was written within the last 15 minutes. To activate it, mount a logging config that writes to that path:

logging-config.toml:

[[handlers]]
sink = "sys.stdout"
format = "{message}"
level = "INFO"

[[handlers]]
sink = "/app/data/zhongli.log"
rotation = "1 day"
retention = 3
level = "DEBUG"
serialize = true

Then pass it to zhongli:

podman run -d \
  -v ./config.toml:/app/config/config.toml:ro \
  -v ./logging-config.toml:/app/config/logging-config.toml:ro \
  -v zhongli-data:/app/data \
  registry.marvin8.zone/marvin8/zhongli \
  /app/config/config.toml --logging-config /app/config/logging-config.toml

If your delay_between_posts exceeds 10 minutes, override the healthcheck interval to avoid false negatives: add --health-interval=<2× delay> to your podman run invocation, or set HealthInterval in your Quadlet unit.

Quadlet (systemd)

Quadlet is the recommended way to run zhongli as a persistent rootless systemd service (requires Podman ≥ 4.4).

Create ~/.config/containers/systemd/zhongli.container:

[Unit]
Description=Zhongli Fediverse reblog bot

[Container]
Image=registry.marvin8.zone/marvin8/zhongli:latest
AutoUpdate=registry
Volume=%h/.config/zhongli/config.toml:/app/config/config.toml:ro
Volume=%h/.config/zhongli/logging-config.toml:/app/config/logging-config.toml:ro
Volume=zhongli-data.volume:/app/data
Exec=/app/config/config.toml --logging-config /app/config/logging-config.toml
HealthOnFailure=restart

[Service]
Restart=on-failure
RestartSec=30s

[Install]
WantedBy=default.target

Create ~/.config/containers/systemd/zhongli-data.volume:

[Volume]

Then enable and start:

systemctl --user daemon-reload
systemctl --user start zhongli
systemctl --user status zhongli

Logs via: journalctl --user -u zhongli -f

Author Opt-Out Signals

Zhongli respects the following Fediverse opt-out conventions. When detected, the post is permanently rejected (not retried):

Signal Where checked Returned error type
#noBot in author bio account.note (HTML-stripped) nobot
#noIndex in author bio account.note (HTML-stripped) noindex
#noBot as a post tag status.tags nobot

These checks run on every post before the duplicate-attachment scan.

Configuration

Zhongli requires FenLiu and a Fediverse account:

[fediverse]
domain_name = "mastodon.social"
api_token = "your-token"

[fenliu]
base_url = "https://fenliu.example.com"
api_key = "your-api-key"

# Optional
run_continuously = false
delay_between_posts = 300
reblog_sensitive = false
max_reblog = 5
# allow_insecure_http = false  # set true only if FenLiu is on a local network without HTTPS

Configuration explained:

  • [fediverse] - Your Mastodon/Pixelfed/Misskey account
  • [fenliu] - Connection to FenLiu queue service
  • run_continuously - Keep polling or exit after max_reblog posts
  • delay_between_posts - Seconds between reblogs (0 for no delay)
  • reblog_sensitive - Whether to boost sensitive/NSFW posts
  • max_reblog - Stop after boosting N posts (0 for unlimited)
  • fenliu.skip_missing_alt_text - Skip posts where any attachment lacks alt text (default: false)
  • fenliu.allow_insecure_http - Allow an HTTP base_url for private local-network deployments where HTTPS is not feasible. Never enable this in production. http://localhost and http://127.0.0.1 are always exempt and do not require this flag (default: false)

Security: config.toml is created with 0600 permissions (owner read/write only). If you copy or restore the file from another location, re-apply: chmod 600 config.toml. Zhongli will refuse to start if it detects the file is readable by group or world.

cache.db (attachment deduplication database) is also created with 0600 permissions. If the file already exists with looser permissions, zhongli logs a warning with a chmod 600 hint.

fenliu.base_url must use https:// to protect the API key in transit. The only exceptions are http://localhost and http://127.0.0.1 (always permitted for local development), and any URL when allow_insecure_http = true is set explicitly for private-network deployments.

Debug log: When using --logging-config logging-config.toml, debug output is written to ~/.cache/zhongli/zhongli.log. This directory is created automatically and is accessible only by the owner. Never configure /tmp/ as a log destination — it is world-readable.

Usage

zhongli config.toml                 # Run with config file
zhongli config.toml --max-posts 10  # Override max posts
zhongli --help                      # Show all options

How It Works

  1. Poll FenLiu Queue - Get next curated post
  2. Validate - Quick checks (has content, not a reply, respects sensitive setting)
  3. Find on Fediverse - Search for post by URL
  4. Check for Duplicates - Compare attachments (URL, hash, perceptual)
  5. Reblog - Boost to your account with circuit breaker protection
  6. Report Feedback - ACK (success), NACK (transient error), ERROR (permanent)
  7. Repeat - Until configured limit or continuous mode ends

Features

  • FenLiu Integration - Consume pre-curated, pre-filtered posts
  • Duplicate Prevention - Three-layer attachment detection (URL, SHA-256, dHash)
  • Reliable Reblogging - Circuit breaker pattern, retry logic, error classification
  • Smart Feedback - ACK/NACK/ERROR reporting to FenLiu
  • Production Ready - 132 tests, full type checking, comprehensive error handling

Development

uv sync              # Install deps
prek run --all-files # Pre-commit checks
uv run tryke test    # Run tests (132 tests; from repo root: uv run tryke test --root packages/zhongli)
nox                  # Full CI simulation

Recent Work

  • ✅ Phase 3: Validation optimized for FenLiu pre-filtered posts
  • ✅ Phase 2: Full FenLiu-only mode operational
  • ✅ Phase 1: FenLiu infrastructure complete with 132 tests
  • ✅ Attachment deduplication system (URL, content hash, perceptual hash)
  • ✅ Circuit breaker pattern integrated
  • ✅ Complete feedback mechanism (ACK/NACK/ERROR)

Next Steps

Phase 5 - UX polish and observability (metrics, dry-run mode, progress indicators)

Privacy / Federation behaviour

When Zhongli looks up a post by URL, it first queries its home instance's local index without triggering any outbound federation. If the post is already known (e.g. it appeared in a followed account's timeline), no federation request is made.

If the post is not in the local index, Zhongli falls back to a federated lookup (resolve=True). This causes the home instance to fetch the post directly from the remote instance. Remote instance administrators can observe this request, which reveals that your instance is interested in that post. This is an inherent consequence of ActivityPub federation and cannot be avoided when a post is not yet locally cached.

Operator note: If you are operating Zhongli on a small or single-user instance, remote administrators may be able to infer your curation patterns from federation traffic.

License

GNU AGPL v3.0

Support

  • Buy me coffee
  • Monero: 88xtj3hqQEpXrb5KLCigRF1azxDh8r9XvYZPuXwaGaX5fWtgub1gQsn8sZCmEGhReZMww6RRaq5HZ48HjrNqmeccUHcwABg