From 8abf7174e9fda296a9479f011cba7d477a357dd2 Mon Sep 17 00:00:00 2001
From: Kiow <justme@kiow.ru>
Date: Mon, 8 Jun 2026 20:12:36 +0300
Subject: [PATCH] v22

---
 core-private-routes.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/core-private-routes.md b/core-private-routes.md
index ed1b666..7456da8 100644
--- a/core-private-routes.md
+++ b/core-private-routes.md
@@ -140,9 +140,17 @@ Authentication: pass `x-node-auth-key` as gRPC metadata (or in the `authKey` fie
 | `ReportOutboundUsage` | `authKey`, `items[]` | `ok` | Equivalent to `POST /node/outbound-usage` |
 | `GetLatestConfig` | `authKey` | `revision`, `clientMapJson`, `mtprotoClientMapJson`, `servicesJson` | Config fields are JSON-encoded strings |
 | `ConfirmConfigApplied` | `authKey`, `revision` | `ok` | Equivalent to `POST /node/config/applied` |
-| `ReportNodeStats` | `authKey`, system metrics fields | `ok` | Reports CPU/RAM/disk/network/xray/mtproto snapshot; stored in Redis; drives `GET /admin/nodes/:id/runtime-status` and stats history |
+| `ReportNodeStats` | `authKey`, `system{}`, `xray{}`, `mtprotoJson` | `ok` | Reports CPU/RAM/disk/network/xray/mtproto snapshot; stored in Redis; drives `GET /admin/nodes/:id/runtime-status` and stats history |
+| `ReportOnlineUsers` | `authKey`, `users[]` | `ok` | Reports currently connected users with their IPs every 5 s; Core stores Redis TTL keys and upserts `user_ips` table |
 
-`ReportNodeStats` fields: `uptimeSeconds`, `cpuPercent`, `cpuCores`, `ramUsed`, `ramTotal`, `diskUsed`, `diskTotal`, `netRxPerSec`, `netTxPerSec`, `netRxTotal`, `netTxTotal`, `xrayRunning`, `xrayUptimeSeconds?`, `mtprotoJson`.
+`ReportNodeStats` nested fields:
+- `system`: `uptimeSeconds`, `cpuPercent`, `cpuCores`, `ramUsed`, `ramTotal`, `diskUsed`, `diskTotal`, `netRxPerSec`, `netTxPerSec`, `netRxTotal`, `netTxTotal`
+- `xray`: `running`, `uptimeSeconds?`
+- `mtprotoJson`: JSON string `Record<tag, MtProtoStatus>`
 
-The node sends `ReportNodeStats` on every heartbeat cycle. `GET /admin/nodes/:id/runtime-status` returns the latest stored snapshot without polling the node; `?fromNode=true` forces a live HTTP fetch instead.
+`ReportOnlineUsers.users[]` entry: `userId`, `nodeProtocolId`, `ips[]{ip, lastSeen}`.
+
+The node sends `ReportNodeStats` every 2 s. `GET /admin/nodes/:id/runtime-status` returns the latest stored snapshot without polling the node; `?fromNode=true` forces a live HTTP fetch instead.
+
+The node sends `ReportOnlineUsers` every 5 s. Core sets `online:user:{userId}` and `online:inbound:{nodeProtocolId}:user:{userId}` Redis keys with TTL 20 s, upserts IP history into `user_ips`, and emits `user.online` domain event when the user had a gap > 10 s.