feat(message-bus): add ping/keepalive on WS + root declaraiton on AsyncAPI

- plan also eviction in case of permison revoked

example.env

@@ -1093,6 +1093,27 @@ OXICLOUD_WOPI_ENABLED=false
 # DEPRECATED — use OXICLOUD_TRUST_PROXY_CIDR instead
 #OXICLOUD_TRUST_PROXY_HEADERS=
 
+# -----------------------------------------------------------------------------
+# REALTIME MESSAGE BUS (/api/rt/ws)
+# -----------------------------------------------------------------------------
+# WebSocket endpoint for folder-live updates, notifications, and the
+# collaborative editor. See docs/plan/message-bus.md for the JSON-RPC 2.0
+# wire protocol.
+
+# Server-initiated protocol Ping interval (seconds). Prevents intermediate
+# proxies (Traefik, nginx, Cloudflare) and NAT boxes from reaping the TCP
+# session as idle. Read at each WS connect — a change takes effect on new
+# connections without restart. Set 0 (or any non-positive value) to fall
+# back to the default.
+#
+# Tuning: the interval should sit at most half the smallest hop's idle
+# timeout, so a single missed Ping doesn't kill the connection. Common
+# floors:
+#   * nginx `proxy_read_timeout` default 60s  → ping ≤ 30s
+#   * Cloudflare hard limit 100s              → ping ≤ 45s
+#   * Traefik with idleTimeout bumped to 3600s → 30s is safely under
+#OXICLOUD_RT_WS_KEEPALIVE_SECONDS=30
+
 # -----------------------------------------------------------------------------
 # MEMORY ALLOCATOR TUNING (IMPORTANT FOR RAM USAGE)
 # -----------------------------------------------------------------------------