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

25 lines
1.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.