VNOX-Server/docs/05-features/hub-server-directory.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

1.7 KiB
Raw Permalink Blame History

Hub community server directory HTTP contract

Listings are unverified user submissions, not endorsements or evidence of server ownership, reachability, protocol compatibility or safety. Hub performs no DNS resolution or network probes. This is a Hub HTTP API and does not change LNEx.

  • GET /v1/servers is public and returns { "servers": [...] }, at most 100 rows ordered by ID ascending. ?after=<UUID> continues after the final ID.
  • POST /v1/servers requires the existing session cookie, exact Origin and CSRF token. JSON fields are name (1–80 characters), address (public DNS/IP and explicit nonzero port), and description (0–500 characters). Strings are trimmed; controls and bidi formatting are rejected. DNS names become lowercase; IPs and ports are canonicalized. Success is 201 { "server": {...} }; duplicate normalized addresses return 409 address_taken. A user can hold at most 10 listings (409 listing_limit).
  • DELETE /v1/servers/{id} requires the same session, Origin and CSRF protections. Owners receive 204; missing and other users' listings receive 404 server_not_found.

Each record has id, name, address, description, owner_id, created_at (Unix seconds). Addresses are globally unique; account deletion cascades to listings. Mutation bodies are capped at 4096 bytes; JSON errors return 400 invalid_request (or 413 when oversized), invalid field values return 422 invalid_server. Mutation attempts share an independent per-account 10/hour and source 30/hour budget; public reads use an independent 20/source and 300/global minute budget. Exhaustion returns 429 try_later. Storage errors return 503 try_later. The proxy must overwrite X-Forwarded-For as required by the existing Hub authentication contract.