Онлайн-монитор: зелёная точка «онлайн» и фильтр «Онлайн сейчас»

[Postlog]

Категория: feature · Приоритет: medium · Размер: M · Ранг: 8/10

Что построить

Зелёная точка / бейдж «онлайн» рядом с активными пользователями в таблице и опциональный фильтр/панель «Онлайн сейчас». Источник — периодический опрос онлайн-набора каждого узла, кэш в сервисе флита.

Паритет с конкурентами

3x-ui (getOnlineClients / onlines), Marzneshin/Marzban (online users, scoped per-admin), Remnawave (unique online users). Индикатор онлайна — у всех.

Чего не хватает сейчас (код)

xui-клиент реализует только ListInbounds/AddClient/DelClient — нет метода онлайн-клиентов и нигде нет периодического опроса. Флит даёт состав клиентов, но не активность. В users_get нет признака онлайна, в SPA нет точки/фильтра.

Зачем

С первого взгляда видно «пользуется ли клиент аккаунтом» и «кто сейчас подключён / здоров ли узел» — самая запрашиваемая операторами read-функция и сигнал для детекта шеринга. Subgen сейчас онлайн-статус не показывает вообще.

Предлагаемая реализация

Новый метод xui-клиента OnlineClients (POST /panel/api/inbounds/onlines → список email; один файл + httptest-тест). Сервис флита (или новый presence-сервис) держит TTL-кэш онлайн-email по узлам (как уже делает TTL-кэш флита). users_get добавляет булев online по email в строку; параметр-фильтр online=true (как уже есть q и inbound). Во Vue — точка в строке и переключатель в тулбаре.

Затронутые файлы

• internal/clients/xui/online_clients.go (новый) + тест, contract.go
• internal/service/fleet/{fleet.go,contract.go} (presence-кэш)
• openapi/users_get.yaml (параметр + поле online), internal/handlers/users_get/, internal/handlers/web/static/

---

_{Продуктовый ресёрч: изучены аналоги (Marzban/Marzneshin, 3x-ui, Remnawave, Hiddify, sub-store + клиентские стандарты импорта). Паритет и subgen-gap код-обоснованы. Ранг = продуктовый приоритет.}

[Postlog]

Issue #110 — Онлайн-монитор: зелёная точка «онлайн» и фильтр «Онлайн сейчас»

🛠 План реализации

Резюме. Добавляем новый метод xui-клиента OnlineClients (POST /panel/api/inbounds/onlines → список email), отдельный presence-сервис с TTL-кэшем онлайн-email по флиту, признак online в строке users_get + параметр-фильтр online=true, и в SPA — зелёную точку у имени и переключатель «Онлайн сейчас» в тулбаре.

Важная сверка с кодом (issue местами расходится с реальностью):

• Issue утверждает, что fleet уже держит TTL-кэш и предлагает «как уже делает TTL-кэш флита». Это неверно по текущему коду: заголовок internal/service/fleet/fleet.go явно гласит «there is no cache, fresh on every call» — Fleet() дёргает все панели на каждый вызов. Поэтому кэш онлайна нельзя «подвесить к существующему», его нужно завести явно. Чтобы не ломать инвариант «fleet без кэша» (он сознательный — health/подписки всегда свежие), presence делаем отдельным сервисом internal/service/presence со своим TTL-кэшем и фоновым поллером, а не правкой fleet. См. «Открытые вопросы» — это единственная развилка.
• Ключ идентичности онлайна = email, а email клиента = ник пользователя (User.Name), т.к. провижининг кладёт email = ник (см. AGENTS.md «один клиент на панель, email = ник»). Значит online для строки юзера = «email юзера присутствует в онлайн-наборе хотя бы одной панели его флита». Сопоставляем по User.Name, не по SubID.
• del/onlines 3x-ui 3.2.x: эндпоинт POST /panel/api/inbounds/onlines (НЕ /panel/api/clients/...), ответ — конверт {"success":bool,"msg":string,"obj":[]string}, где obj — плоский список email, онлайновых на ВСЕЙ панели (по всем инбаундам), не скоупится по инбаунду. Это надо подтвердить read-only разведкой против живой панели перед реализацией (раздел «Риски»).

---

Пошаговый план (снизу вверх)

1. clients/xui — новый тонкий метод OnlineClients

• Новый файл internal/clients/xui/online_clients.go:

  // OnlineClients returns the set of client emails currently online on the target
  // panel (across all its inbounds). 3x-ui returns a flat []string of emails.
  func (c *Client) OnlineClients(ctx context.Context, t entity.PanelTarget) ([]string, error)

  • POST на /panel/api/inbounds/onlines с пустым телом (как DelClient зовёт postJSON(..., nil)), но нужен доступ к телу ответа — текущий postJSON тело не возвращает (только проверяет {success,msg}). Поэтому: либо завести приватный хелпер postJSONResult(ctx, t, path, body) ([]byte, error) (POST + проверка статуса + возврат сырого тела, без разбора конверта), и оба — postJSON и OnlineClients — поверх него; либо в online_clients.go распарсить конверт {success,msg,obj} локально (как делает ListInbounds для GET). Рекомендация: добавить postRaw/postJSONResult рядом в client.go и разобрать в методе конверт struct{ Success bool; Msg string; Obj []string } — симметрично ListInbounds. Метод возвращает r.Obj или ошибку fmt.Errorf("onlines: %s", msg) при !success. Без человеко-текста — технические обёртки (правило «clients без русского текста»).
  • Клиент остаётся stateless, креды — в entity.PanelTarget аргументом (правило «тонкий адаптер»).
• internal/clients/xui/online_clients_test.go — table-driven TestClient_OnlineClients (через newTestClient/httptest), кейсы: success (проверяем путь /panel/api/inbounds/onlines, метод POST, Authorization: Bearer tok, маппинг obj→[]string), empty (obj:[] → пустой слайс), error.envelope (success:false → ошибка), error.status (500 → ошибка).
• contract.go xui-клиента нет (клиент — конкретный тип, моков своего contract.go не держит) — править не нужно.

2. entity — без новых типов (по умолчанию)

• Онлайн — это []string/map[string]bool email'ов, доменного агрегата не требует. Метод-хелпер можно положить в presence-сервис, не в entity. Допущение: новых kernel-типов не заводим; если позже понадобится богаче (онлайн по узлам, last-seen) — отдельный тип. Sentinel-ошибок тоже не нужно: presence — best-effort read, ошибка панели глотается (как в fleet.fetch).

3. service/presence — новый сервис с TTL-кэшем и фоновым поллером

• Новый пакет internal/service/presence/:
  • presence.go:

    type Service struct {
        client panelClient   // OnlineClients(ctx, target) ([]string, error)
        nodes  nodeLister    // List(ctx) ([]entity.Node, error)
        ttl    time.Duration
        mu     sync.RWMutex
        online map[string]bool // email -> online (union across the fleet)
        fetchedAt time.Time
    }
    func New(client panelClient, nodes nodeLister, ttl time.Duration) *Service
    // Online reports whether an email is currently online (cached snapshot).
    func (s *Service) Online(email string) bool
    // OnlineSet returns a copy of the current online-email set (for filtering).
    func (s *Service) OnlineSet() map[string]bool
    // Refresh polls every node's onlines and replaces the snapshot. One unreachable
    // panel is tolerated (skipped); a total outage keeps the previous snapshot.
    func (s *Service) Refresh(ctx context.Context) error

  • Поведение поллера: вариант A (лениво, TTL-on-read) — Online/OnlineSet сами триггерят Refresh, если снапшот старше ttl (с single-flight, чтобы параллельные запросы не дублировали опрос). Вариант B (фоновый тикер) — go Run(ctx) в cmd/service, тикает раз в ttl, кладёт снапшот. Рекомендация: вариант B (фоновый Run(ctx) с time.Ticker), потому что онлайн-опрос всех панелей дорогой и его не надо делать в горячем пути users_get; стартовый Refresh синхронно перед Run, чтобы первая страница не была пустой. Это зеркалит уже существующий паттерн mirror.Run(ctx) (ruleset), запускаемый go mirror.Run(ctx) в main.
  • Опрос: как fleet.fetch — nodes.List → по каждому узлу client.OnlineClients(ctx, target(n)), ошибка одной панели → slog.Warn + skip; union email'ов в новый map; под mu.Lock замена online/fetchedAt. Если все панели упали — снапшот НЕ затираем (оставляем прежний, логируем), чтобы кратковременный сбой не «погасил» всех. target(n) — та же конструкция, что в fleet.go (можно продублировать локально маленькую target, не тащить из fleet, чтобы пакеты не зависели друг от друга).
• internal/service/presence/contract.go (+ //go:generate go tool mockgen):

  type panelClient interface { OnlineClients(ctx context.Context, t entity.PanelTarget) ([]string, error) }
  type nodeLister interface { List(ctx context.Context) ([]entity.Node, error) }

  nodeLister сегментно совпадает с тем, что в fleet/contract.go, но по interface-segregation объявляется локально (правило «свой приватный контракт в своём пакете»).
• presence_test.go — TestService_Refresh (table-driven, моки MockpanelClient/MocknodeLister): empty (нет узлов), success.union (два узла, email'ы объединяются), success.partial_outage (один узел падает — берём онлайн второго, не ошибка), error.total_outage (все панели падают — прежний снапшот сохраняется/ошибка по контракту). Online/OnlineSet проверяются через публичный Refresh+ассерт снапшота.

4. handlers/users_get — поле online в строке + фильтр online=true

• internal/handlers/users_get/contract.go — добавить зависимость:

  type presenceReader interface {
      Online(email string) bool
      OnlineSet() map[string]bool
  }

  Регенерить мок: go generate ./internal/handlers/users_get/.
• handler.go:
  • В Handler/New добавить поле presence presenceReader (передаётся из main). Порядок аргументов New расширяется — обновить вызов в cmd/service/main.go.
  • В каждую row добавить row.Online = h.presence.Online(u.Name) (email = ник).
  • Фильтр online=true: ogen сгенерит params.Online oas.OptBool. Решение, где фильтровать:
    • Проблема: список юзеров серверно-пейджится в БД (users.ListPage с LIMIT/OFFSET), а онлайн — рантайм-факт из памяти presence, в БД его нет. Фильтровать online ПОСЛЕ пейджинга нельзя (страница «сожмётся»), а до пейджинга — БД про онлайн не знает.
    • Рекомендуемое решение: когда online=true, не пушить фильтр в SQL, а в хендлере (a) получить OnlineSet(), (b) запросить страницу с увеличенным/полным охватом или отфильтровать на стороне сервиса. Чистый вариант без переписывания пейджинга: добавить в entity.UserListParams опциональное поле Names []string (whitelist ников) и в users репозиторий — фильтр name IN (...). Хендлер при online=true берёт OnlineSet() → список ников → кладёт в Names; пустой набор → отдать пустую страницу без запроса. Тогда пейджинг/total остаются корректными (БД считает total по тому же фильтру).
    • Это требует правок internal/repository/users/list_page.go (+ count query) и entity.UserListParams. Объём растёт, но это единственный способ сохранить корректный серверный пейджинг+total с эфемерным фильтром. Если владелец согласен на упрощение (онлайн-фильтр без пейджинга, т.к. онлайн-юзеров обычно мало) — можно фильтровать клиентом. См. «Открытые вопросы».
  • Лог: presence-промахов не логируем (best-effort), как h.fleet.Fleet(ctx) уже игнорит ошибку (fl, _ := ...).
• handler_test.go — расширить TestHandler_UsersGet: добавить мок MockpresenceReader, кейсы — success.online (email в наборе → Online:true), success.offline, и (если делаем серверный фильтр) success.filter_online (передан Names, проверяем вызов ListPage с whitelist). Конструктор New(...) в тесте обновить под новую сигнатуру.

5. openapi/ogen — параметр + поле ответа

• openapi/users_get.yaml:
  • В parameters добавить:

    - name: online
      in: query
      description: When true, return only users currently online (cached panel snapshot).
      schema:
        type: boolean

  • В схему users[].items добавить в required online и в properties:

    online:
      type: boolean
      description: Whether the user's client is currently online on any panel (cached).

  • Только форма контракта (type/required) — value-констрейнтов нет (правило ADR-0003). online — bool без ограничений.
• Затем go generate ./internal/oas/ (директива в internal/oas/, спека openapi/ogen.yml). Сгенерится oas.UsersGetParams.Online OptBool и поле oas.UsersGetOKUsersItem.Online bool.

6. cmd/service/main.go — композиция

• Сконструировать presence-сервис рядом с fleetSvc:

  presenceSvc := presence.New(xc, nodesRepo, <ttl>)
  if err := presenceSvc.Refresh(ctx); err != nil { slog.Warn("presence: initial refresh failed", "err", err) }
  go presenceSvc.Run(ctx) // фоновый тикер (вариант B)

  TTL по умолчанию — захардкоженная константа в пакете presence (напр. 10 * time.Second), не через config (config — только статика; новый env заводим только если владелец захочет тюнить). Допущение: TTL = 10s (3x-ui-панель сама обновляет онлайн ~каждые 10s; см. «Открытые вопросы», если нужен env-тюнинг).
• Прокинуть presenceSvc в buildRouter (добавить параметр) и в usersGetHandler.New(usersRepo, fleetSvc, presenceSvc, cfg.Secret, cfg.PublicBase).

7. Фронт — зелёная точка + переключатель «Онлайн сейчас»

• internal/handlers/web/static/index.html:
  • Точка у имени в ячейке td.uname (строка ~63): перед {{ u.name }} вставить
    <span class="online-dot" :class="{on: u.online}" :title="u.online ? 'онлайн' : 'офлайн'"></span>.
  • В users-toolbar (после tb-filter, ~строка 53) — переключатель:

    <label class="tb-online">
      <input type="checkbox" v-model="onlineOnly" @change="onOnlineFilter">
      <span class="online-dot on"></span> Онлайн сейчас
    </label>

• internal/handlers/web/static/app.js:
  • data: onlineOnly: false.
  • onOnlineFilter() → this.userPage = 1; this.loadUsers(); (как toggleInboundFilter).
  • В loadUsers() (build params, ~строка 124): if (this.onlineOnly) p.set("online", "true");.
  • В пустом-состоянии строки 90 учесть onlineOnly в тексте «Ничего не найдено».
• internal/handlers/web/static/app.css: токены 3x-ui-dark (см. AGENTS.md). Добавить:

  .online-dot{display:inline-block;width:8px;height:8px;border-radius:50%;background:rgba(255,255,255,.18);margin-right:7px;vertical-align:middle}
  .online-dot.on{background:#3fb950;box-shadow:0 0 0 2px rgba(63,185,80,.18)} /* зелёный, как 3x-ui online */
  .tb-online{display:inline-flex;align-items:center;gap:6px;cursor:pointer;font-size:13px;color:var(--text-dim)}

  Цвет зелёный из палитры (без webfont, в духе Ant-dark). Правка видна без пересборки Go при SUBGEN_STATIC_DIR (embed/диск — render.go).

---

Миграции БД

Не требуются. Онлайн-статус — эфемерные данные, опрашиваются с панелей и держатся в памяти presence-сервиса; в SQLite ничего не пишем. Следующий свободный номер (если бы понадобился) — migrations/0004-*.sql, но в этом issue он не нужен.

OpenAPI/ogen

• Править только openapi/users_get.yaml (параметр online + поле online в item, оба — только форма: type/required).
• $ref в openapi/openapi.yaml уже есть (ручка существует) — не трогаем.
• go generate ./internal/oas/ после правки спеки. Value-валидации в схеме нет (булев флаг без констрейнтов) — правило ADR-0003 соблюдено.

Тесты

• TestClient_OnlineClients (xui, httptest) — путь/метод/заголовок/маппинг конверта, кейсы success/empty/error.envelope/error.status.
• TestService_Refresh (presence, mockgen по своему contract.go) — empty/success.union/success.partial_outage/error.total_outage.
• TestHandler_UsersGet (расширить) — добавить MockpresenceReader, кейсы success.online/success.offline и (если серверный фильтр) success.filter_online.
• apitest: опционально. Чёрный ящик против живой 3x-ui мог бы проверить wire-контракт /panel/api/inbounds/onlines, но это вызов ВНЕШНЕЙ панели, а не subgen-ручки; apitest суиты бьют по subgen API. Достаточно добавить проверку поля online в существующий UserSuite (GET /admin/api/users возвращает online в строке) — без живого онлайна оно будет false, проверяем лишь присутствие поля и тип. Полноценный online-апитест требует поднять клиента и реально подключиться — за рамками M-размера, не делаем.

Документация

• CHANGELOG.md — одна строка: ## YYYY-MM-DD — Онлайн-монитор: точка «онлайн» и фильтр (#<PR>) + 1–2 строки сути (новый presence-сервис с TTL-поллером, метод OnlineClients, поле/фильтр online в users_get, точка/тумблер в SPA).
• ADR — нужен (docs/decisions/0004-<slug>.md, напр. 0004-online-presence-poller.md), потому что есть нетривиальные развилки с реальным trade-off:
  • presence как отдельный сервис vs. встраивание в fleet (и почему НЕ ломаем инвариант «fleet без кэша»);
  • фоновый тикер vs. ленивый TTL-on-read;
  • как онлайн-фильтр уживается с серверным пейджингом/total (whitelist Names vs. клиентский фильтр).
    Секции Context / Considered Options / Decision / Consequences. Ссылку на ADR положить в CHANGELOG.

Риски и edge-cases

• Контракт /panel/api/inbounds/onlines не подтверждён в репо — нигде не используется. Перед реализацией: read-only разведка против живой панели (3.2.6) под env -u HTTPS_PROXY ... curl'ом, чтобы зафиксировать точный путь, метод (POST), тело (пустое?) и форму ответа (obj:[]string?). Если форма иная (объект, скоуп по инбаунду) — подправить DTO/маппинг в online_clients.go (anti-corruption boundary).
• Email≠ник в краевых случаях: провижининг гарантирует email=ник, но если в панели остались «ручные» клиенты с другим email — они не сматчатся на юзера. Это ок: онлайн-точка — про subgen-юзеров, матч по User.Name.
• Стейл-снапшот: при TTL точка может на ≤TTL отставать от реальности — приемлемо для индикатора. Total-outage не гасит всех (оставляем прежний снапшот).
• Пейджинг+онлайн-фильтр: если выбрать клиентский фильтр (упрощение), total/номера страниц станут неверны для онлайн-режима. Рекомендуемый whitelist-вариант это решает ценой правок репозитория. Развилка — в «Открытых вопросах».
• Гонки: presence-снапшот читается из users_get конкуррентно с поллером — защитить sync.RWMutex, OnlineSet() отдаёт копию.
• Холодный старт: первый Refresh синхронно перед стартом сервера/тикера, иначе первая страница покажет всех офлайн.

Зависимости/порядок

• Самостоятельный issue, хардовых зависимостей от других Партиальный провижининг: типизированный исход вместо «непрозрачного 500» поверх уже созданного юзера #83–Маршрутные правила: логические операторы (AND/OR/NOT) с рекурсивным tree-UI, SUB-RULE и полный паритет матчеров с mihomo #113 нет. Тонкая связь: если параллельно идёт рефактор fleet/presence в смежном issue — синхронизировать target(n)/nodeLister. По умолчанию реализуем автономно.

❓ Открытые вопросы (@Postlog)

1. Онлайн-фильтр и серверный пейджинг. Сделать «правильно» — добавить whitelist Names []string в entity.UserListParams + фильтр name IN (...) в repository/users (корректный total/пейджинг, но +правки репозитория и его тестов), или упростить — клиентский фильтр онлайна поверх обычной страницы (меньше кода, но total/номера страниц в онлайн-режиме станут неточными)? По умолчанию возьму whitelist-вариант (корректный пейджинг).
2. TTL и env-тюнинг. Зашить TTL поллера константой (~10s) или вынести в config новым env (SUBGEN_PRESENCE_TTL)? По умолчанию — константа 10s (config = только статика, лишний env без явной нужды не ввожу).
3. presence vs fleet (подтверждение). Issue предполагал расширение fleet его «TTL-кэшем», но fleet сейчас без кэша by design (всегда свежий для health/подписок). По умолчанию завожу отдельный internal/service/presence и не трогаю инвариант fleet — подтвердите, что это ок.

[Postlog]

✅ Решения зафиксированы (по итогам обсуждения с владельцем)

• Серверная сортировка/выдача — только по БД-полям; онлайн-набор приходит из поллера, не из SQL, поэтому серверной сортировки по «онлайн» нет.
• Presence — отдельный internal/service/presence (TTL-кэш онлайн-email), инвариант fleet (всегда свежий) не трогаем. Остальные дефолты плана (TTL ~10s константой, фильтр через whitelist в repository) — в силе, если не уточнишь.