VNOX-Server/docs/02-protocol/node-features.md
loki5512344 c18ccadf99
chore(server): checkpoint deployed services and unfinished forums
User requested a checkpoint and stopped all agents. Deployed artifacts remain the last verified releases; unfinished settings/categories/forums are preserved as WIP. See TODO/roadmap for verification and remaining release/updater work.
2026-11-01 15:31:20 +01:00

5.4 KiB
Raw Permalink Blame History

Node settings, structured channels and forums (LNEx v4 additive)

Plan and compatibility

Implement persisted public node name/description, one-level channel categories and actual forum topics/replies. Authorization uses the verified Central account/session and existing guild permissions. Existing channels/messages/ownership/voice keys remain intact. Storage extends gateway SQLite/PostgreSQL idempotently, independently of Hub migrations.

Session advertises node_settings (6), channel_structure (7), forums (8). A capable desktop sends 0x0232 ClientFeatures {node_settings=1,channel_structure=2,forums=3} after Session, before channel listing/actions, only when the corresponding server flag is true. No AUTH fields are added: older v4 signature verification re-encodes AUTH and would drop unknown fields. Older clients never report features: new category/forum kinds are hidden from their channel lists and metadata delivery; existing text/voice remain usable. New clients talking to old gateways disable unsupported controls/packets.

Settings

0x0230 NodeSettingsRequest {request_id=1,update=2,display_name=3,description=4}. 0x0231 NodeSettingsResult {request_id=1,display_name=2,description=3,error_code=4,error=5}. Reads return public data to authenticated clients; updates require the exact session's configured node-admin Central UUID. Name is trimmed, 1–100 characters, no control/bidi override characters. Description is trimmed, at most 2000 characters, permits newline/tab but no other controls/bidi overrides. Success persists before ACK and updates HELLO's node name; future restarts use the stored name/description, config name is only an initial fallback. Changes broadcast Result with empty request_id to feature-capable authenticated clients. Errors are correlated Results, never unrelated join errors.

Categories and layout

Channel kinds are text, voice, category, forum. Add parent_id/position to ChannelCreate (5/6), ChannelState (7/8), ChannelListItem (5/6); ChannelEdit optionally changes parent_id (3) and position (4), absent means unchanged, present empty parent means detach to root. Position is 0–1000000, stable ties use channel ID. Categories always live at root; a child's parent must be an existing category in the exact same global/guild scope. No nested categories, cycles, cross-guild parents or implicit channel replacement.

Node administrators manage global structure; guild management still requires the existing owner/MANAGE_CHANNELS policy. Category JoinChannel is rejected before changing current text/voice subscriptions. Forum JoinChannel is view-only (no generic chat history, audio or UDP credentials). Deleting a category atomically reparents children to root and deletes only the grouping metadata. Bootstrap general/voice IDs remain undeletable. A forum containing any topic cannot be deleted; guild deletion containing forum topics is also refused, preserving discoverability and all replies.

Forums

0x0240 ForumRequest: request_id (1), ForumOperation operation (2), channel_id (3), topic_id (4), title (5), content (6), offset (7), limit (8), message_id (9). Enum UNSPECIFIED=0, LIST=1, CREATE=2, OPEN=3, REPLY=4.

0x0241 ForumResult: request_id (1), operation (2), channel_id (3), topic_id (4), topics (5), posts (6), has_more (7), error_code (8), error (9). Every response/error is correlated. 0x0242 ForumChanged: channel_id (1), topic (2), post (3), broadcast only to current authorized forum subscribers and rechecked at delivery.

ForumTopic: topic_id (1), channel_id (2), title (3), MemberInfo author (4), created_at (5), updated_at (6), reply_count (7). ForumPost: ChatMessage message (1), MemberInfo author (2), topic_id (3), uint64 ordinal (4). Author IDs/account/name/avatar originate solely from the authenticated verified session. Snapshot names/avatar allow offline authors; clients retain newer live profile cache entries when displaying snapshots.

LIST defaults to 20, maximum 50 topics; OPEN defaults to 50, maximum 100 posts; offsets at most 100000. Handler fetches limit+1 to determine has_more. Titles are trimmed, 1–160 characters, without control/bidi overrides. Bodies are trimmed, 1–16000 characters and at most 64 KiB, newline/tab permitted. CREATE requires stable client UUID topic_id and message_id; REPLY requires stable message_id. Retries reuse IDs and must match channel/topic/author device+account/title/body to be idempotent; conflicts fail without linking unrelated/private messages. Topic and first message commit atomically. Per-topic ordinal guarantees deterministic reply order even within one millisecond.

Posts reuse existing messages under the forum channel ID plus an explicit topic mapping. Reads always constrain both channel and topic. Generic chat sends/history, message edits/deletes/reactions and attachment uploads do not mutate forum posts; dedicated ForumRequest is the only posting API in this scope. No topic/post deletion is exposed. Forum access requires node-global visibility or guild membership; guild posting additionally requires owner/MESSAGE_SEND, node administration does not bypass guild policy. Rate limits and shared-access guards protect posting versus concurrent channel/access changes. CREATE/REPLY clients refresh signed profile through the existing bounded activity queue, without interrupting voice.

All deferred administrative or forum actions are fenced to the authenticated client session so queued operations cannot execute on a different node after switching.