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.