Skip to content

What it is

kbve.com’s forum: the feed, space, tag, thread and compose pages under /forum, and the /api/v1/forum routes that post threads and comments, let an author edit their own, and let staff remove or moderate. Threads, comments, spaces and tags live in Supabase’s forum schema; the spaces and tags lists are read through a Valkey cache. Writes verify the session against Supabase Auth through jedi::jwt_cache. The staff routes ask forum.is_staff first, and the RPCs then ask forum.has_staff_permission for the staff bits the act needs: MODERATOR or CONTENT_MODERATE to moderate, STAFF or ADMIN to post in a staff-only space, with superadmin passing both. A thread’s page is /forum/t/{id}/{slug}: the id finds it and the slug is only for the reader, so an old /forum/t/{slug} link, a bare id or a slug from before a rename redirects there.

A thread has one home space, which its URL and breadcrumb follow, and can be listed in others: it then shows in their feeds too, with one set of comments. How many is forum.settings.max_thread_listings, a row an UPDATE moves. The author sets them when posting (also_in) or later with PUT /api/v1/forum/t/{id}/listings; staff or a space’s moderators take one out, or put it back, with POST …/listings/{space}/unlist and /relist. A space whose post_policy is staff (Announcements) takes threads and listings from staff only.

It is also the only forum client in the tree. Other backends — the BBS, and rareicon’s in-game news — read and post over HTTP rather than carry their own. GET /api/v1/forum/feed is the /forum/ feed as JSON (filtered by space, space_id, tag or thread type, sorted and paged as the page is, with a next cursor; ?space=news&type=announcement is a game’s news), and GET /api/v1/forum/t/{slug_or_id} is one thread with its rendered body and the same comments its page shows. Both are anonymous and cached for thirty seconds. GET /api/v1/forum/spaces lists the open spaces with the thread types each takes, and a signed-in author’s POST /api/v1/forum/preview renders a draft as its thread page will, with the tags it will get. A backend that has already authenticated a member some other way posts for them through /api/v1/forum/service/threads and /api/v1/forum/service/t/{slug_or_id}/comments, with a service_role bearer as the wallet’s service routes take; those run the web paths’ own hashtag tagging and RPCs. A refused write answers {"error", "refused": true} with only the reason the RPC raised for the author; constraint names, hints and transport errors stay in the log.

The forum does not take Postgres’s word for what is public. The RPCs and policies already filter, and src/visibility.rs filters again: a feed lists only active, non-NSFW threads in open spaces; a thread page or its JSON is 404 for a draft, scheduled, pending or removed thread, or one whose space has closed; and a space, tag, thread or cursor that could not exist is refused before PostgREST is asked.

Every thread, from any of those paths, is built as one NewThread (src/compose.rs) and checked there before an RPC is called, so a rule added once holds for the web, the BBS and a game alike. The service route takes the space as space_id or space (its slug) and, beyond the title and body, a thread_type, structured type_data (an object, at most 8 KiB), explicit tags (merged ahead of the body’s hashtags, twenty in all), a slug, a locale and nsfw. A caller that retries sends an idempotency_key: the first request claims it in Valkey for a day, a repeat gets the same thread back with a 200, and one sent while the first is still writing gets a 409. A created thread answers {thread_id, url}. Scheduled posting is not offered: the schema has the column, but nothing yet publishes a scheduled thread.

The page’s markup

The site owns it, as with KBVE Profile: kbve-web’s build renders docs/askama/forum/ into askama templates on the site’s bundles, and the Dockerfile compiles them in from the kbve-web image KBVE_WEB pins. The site’s 404.html comes along for the thread pages’ error responses.

Where it came from

Moved out of axum-kbve with the same paths, status codes and JSON, error strings included, since clients read them. axum-kbve still holds a copy of the forum client, because its store and Minecraft lots ask it who is staff.

Releasing

Bump version: above. The kbve-forum job publishes the image and kbve-forum-deploy opens the merge request that repoints kbve-forum-deployment.yaml.

Discuss on the forum

Questions, fixes and notes on this page live in the KBVE forum.