lichenblankie/tinyweb-forum
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update README to match TinyWeb style

Browse source
This commit is contained in:
blankie 2026-06-16 05:13:38 +00:00
parent ea34a7f5d7
commit 94afb56bc0
2 changed files with 308 additions and 175 deletions
Download patch file Download diff file Expand all files Collapse all files

78
README.md
View file

@ -1,6 +1,17 @@
# tinyweb-forum
A decentralized link-sharing forum for [TinyWeb](https://codeberg.org/tinyweb/tinyweb). Share URLs and discuss them with other TinyWeb instances over the Reticulum mesh. No accounts, no sign-up, no central server.
A link-sharing forum plugin for [TinyWeb](https://codeberg.org/tinyweb/tinyweb). Threads and posts are stored locally and exchanged with other TinyWeb instances over the Reticulum mesh.
## Contents
- [About this project](#about-this-project)
- [Install](#install)
- [How it works](#how-it-works)
- [Moderation](#moderation)
- [Sync](#sync)
- [Storage](#storage)
- [Known rough edges](#known-rough-edges)
- [Security](#security)
## About this project
@ -12,64 +23,59 @@ Code generated by LLMs. Built by one person.
pip install tinyweb-forum
```
Enable the forum in TinyWeb's customize page (`/style`).
## Development
```bash
git clone https://codeberg.org/tinyweb/tinyweb-forum
pip install -e .
```
Enable it on TinyWeb's `/style` page under "Forum".
## How it works
- Each TinyWeb instance stores forum threads and posts in its own `forum.db`
- Instances auto-discover each other on the mesh via RNS announces — no manual setup
- You click "sync now" to exchange content; auto-sync every 5 minutes is optional (toggle on moderation page)
- At scale, sync uses epidemic gossip: each cycle picks 20 random peers instead of all peers, converging within ~O(log N) cycles
- Authors are identified by a short pseudonymous hash (no names, no accounts)
- No global server, no algorithms, no tracking
## Features
- **Threads** — share a URL or start a discussion with text
- **Replies** — reply to threads, with inline URL extraction and "+ save" links
- **Upvotes** — toggle upvote/downvote, scores propagate via sync
- **Edit** — edit your own threads (new version syncs to peers)
- **Retract** — retract your own threads and posts (retraction signal gossips to peers)
- **Peer discovery** — instances share known peers during sync, growing the network organically
- Threads and posts are stored in `~/.tinyweb/forum.db` (separate from TinyWeb's search index)
- Instances auto-discover each other via RNS announces — no manual setup
- Sync is manual by default: click "sync now" on the forum page. Auto-sync every 5 minutes is optional (toggle on moderation page)
- At scale, sync uses epidemic gossip: 20 random peers per cycle, converging within ~O(log N) cycles
- Authors are identified by a short pseudonymous identity hash (no accounts, no sign-up)
- Auto-discovery can be disabled in the moderation page
- Threads are auto-pruned after 30 days (configurable, or set to 0 to keep everything)
- Moderation is local: block authors, mute threads, keyword filters, and gossip block lists with peers (auto-block after 3 peer reports)
## Moderation
All moderation is local — you control your view:
All moderation is local — it controls what you see:
- **Block author** — `[block]` link on posts and thread meta hides all content from that identity across your instance
- **Auto-block** — when 3+ of your peers have blocked the same identity, it's auto-blocked for you too (threshold is 3)
- **Mute thread** — hide a thread from the listing
- **Keyword filters** — hide threads matching keywords
- **Block author** — hides all content from that identity
- **Auto-block** — when 3+ of your peers have blocked the same identity, it blocks for you too
- **Mute thread** — hides a thread from the listing
- **Keyword filters** — hides threads matching keywords
- **Instance sync** — choose which peers to sync with; unsync at any time
## Sync
- Instances auto-discover each other via RNS announces — just run the forum and any other forum on the mesh finds you
- Instances discover each other via RNS announces — any forum on the mesh finds you
- Content is exchanged as JSON over RNS links
- **Manual by default** — click "sync now" on the forum listing or moderation page
- Auto-sync every 5 minutes can be enabled on the moderation page
- Auto-discovery can also be disabled on the moderation page (manual instance add only)
- Peer discovery propagates through gossip — each instance shares its known peers during sync
- Auto-discovery can be disabled (manual instance add only)
- Known peers propagate through gossip — each instance shares its peers during sync
- Block lists and retractions are gossiped alongside content
- Only new/updated content is transferred (timestamp-based)
- When >20 peers, each cycle syncs with a random 20 — content converges epidemically
## Storage
- Threads older than 30 days are auto-pruned (configurable on the moderation page)
- Threads older than 30 days are auto-pruned (configurable on moderation page)
- Set retention to 0 to keep everything indefinitely
- Forum DB is stored at `~/.tinyweb/forum.db`
- Database location: `~/.tinyweb/forum.db`
## Known rough edges
- Authors are pseudonymous — no identities, no accounts
- No rate limiting on forum POST endpoints
- Retractions are voluntary — peers can ignore them
- Block gossip can be gamed (requires collusion by 3+ peers on Reticulum)
- Threads prune after 30 days by default
- Best-effort maintenance
## Security
- **No authentication** — The forum inherits TinyWeb's access model. Anyone who can reach the HTTP port (localhost by default) can post, edit, retract, block, and change moderation settings. See TinyWeb's Security section for details on `--bind 0.0.0.0`.
- **Retractions are voluntary** — Retracting a thread or post sends a signal to peers, but any peer can ignore it and keep serving the content. "Retract" is a polite request, not a guaranteed delete.
- **No authentication** — The forum inherits TinyWeb's access model. Anyone who can reach the HTTP port (localhost by default) can post, edit, retract, block, and change moderation settings. See TinyWeb's Security section for `--bind 0.0.0.0`.
- **Retractions are voluntary** — Retracting a thread or post sends a signal to peers, but any peer can ignore it. "Retract" is a polite request, not a guaranteed delete.
- **Block gossip can be gamed** — Auto-block triggers after 3 peer reports. On Reticulum this requires 3+ real instances to collude, which is impractical at mesh scale, but is not cryptographically enforced.
- **No rate limiting** — Forum POST endpoints have no throttling. Low risk since the HTTP port is localhost-only by default.