v15

core-private-routes.md

@@ -2,10 +2,20 @@
 
 These routes are consumed only by the node agent and require the `x-node-auth-key` header.
 
+## Transport
+
+The node uses two transports to communicate with Core:
+
+- **HTTP** — registration only (`POST /node/register`).
+- **gRPC** — all other node-to-core calls: heartbeat, usage reporting, config sync, and stats. Core listens on `GRPC_PORT` (default `3002`). The node connects via `CORE_GRPC_URL`. Set `CORE_INSECURE=true` on the node to use plaintext instead of TLS.
+
+The HTTP routes for heartbeat, usage, config, and error remain available as a fallback but the node agent uses gRPC by default.
+
 ## Authentication
 
 - `POST /node/register` is the only public route in this group.
-- All other routes require a valid node auth key.
+- All other HTTP routes require the `x-node-auth-key` header.
+- gRPC calls pass the auth key as the `x-node-auth-key` metadata header (or in the `authKey` request field as fallback).
 - The auth key is issued by Core during registration and persisted on the node side.
 
 ## Route table
@@ -91,6 +101,7 @@ The config returned by `GET /node/config/latest` has this structure:
 {
   revision: number
   clientMap: Record<string, { userId: number; subscriptionId: number | null }>
+  mtprotoClientMap: Record<string, { userId: number; subscriptionId: number | null }>
   services: {
     xray?: XrayServiceConfig
     mtproto?: MtProtoServiceConfig
@@ -100,10 +111,11 @@ The config returned by `GET /node/config/latest` has this structure:
 
 Important notes:
 
-- `clientMap` maps subscription link UUIDs to the user and subscription used for traffic attribution.
+- `clientMap` maps subscription link UUIDs to the user and subscription — used for xray traffic attribution.
+- `mtprotoClientMap` maps MTProto link UUIDs to the user and subscription — used for telemt traffic attribution.
 - `services.xray` contains the Xray inbounds, routing, and outbounds for the node.
 - `services.mtproto` contains MTProto inbounds for `telemt`.
-- the node stores the current revision and client map locally after a successful apply
+- The node stores the current revision and client maps locally after a successful apply.
 
 ## Route semantics
 
@@ -114,3 +126,22 @@ Important notes:
 - `POST /node/config/applied` marks the node sync status as `synced`.
 - `POST /node/error` marks the node as `error` and the sync status as `failed`.
 
+## gRPC interface (`NodeService`)
+
+Core exposes a gRPC service that the node agent uses for all real-time communication. The service name is `nodeservice.NodeService` and is defined in `proto/node-service.proto`.
+
+Authentication: pass `x-node-auth-key` as gRPC metadata (or in the `authKey` field of the request as fallback).
+
+| Method | Request fields | Response fields | Notes |
+| --- | --- | --- | --- |
+| `Heartbeat` | `authKey`, `revision?`, `ip?` | `ok`, `needSync` | Equivalent to `POST /node/heartbeat` |
+| `ReportUsage` | `authKey`, `entries[]` | `ok` | Equivalent to `POST /node/usage` |
+| `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` fields: `uptimeSeconds`, `cpuPercent`, `cpuCores`, `ramUsed`, `ramTotal`, `diskUsed`, `diskTotal`, `netRxPerSec`, `netTxPerSec`, `netRxTotal`, `netTxTotal`, `xrayRunning`, `xrayUptimeSeconds?`, `mtprotoJson`.
+
+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.
+