Меню действий в строке: «Сбросить токен подписки» и копирование ссылки

[Postlog]

Категория: ux · Приоритет: low · Размер: S · Ранг: 9/10

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

Меню действий «…» в строке пользователя с пунктами «Сбросить ссылку подписки» (ротация subId → старая ссылка перестаёт работать) и «Копировать ссылку».

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

Marzban/Marzneshin (revoke/rotate subscription), 3x-ui (per-user share + reset), Remnawave (user.revoked event), Hiddify (short-link revoke). Отзыв/ротация токена — стандартное действие.

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

Токен подписки = усечённый HMAC(secret, subId) (token.Make в users_get/handler.go:77), то есть детерминирован от subId — отозвать утёкшую ссылку нельзя без смены subId, а смены subId нет. В строке только одна кнопка «Mihomo» (copy(u.sub.url), index.html:80), нет ротации и компактного меню действий.

Зачем

Оператор мгновенно гасит утёкшую ссылку, не пересоздавая пользователя, и удобно делится новой. Сегодня subgen не умеет инвалидировать подписку: HMAC от subId неизменен, subId не ротируется — утёкшая ссылка живёт вечно.

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

Сервисный метод provisioning.RotateSubID: минтит новый subId (как при создании), ре-байндит клиента на всех панелях с тем же uuid, но новым subId (AddClient уже принимает subId), обновляет users.sub_id. Ручка user_rotate_sub (openapi → ogen), тонкий хендлер. Во Vue — dropdown-меню действий в строке (Bootstrap уже вендорён), пункты дергают POST и copy().

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

• internal/service/provisioning/service.go (RotateSubID), internal/repository/users/ (UpdateSubID)
• openapi/user_rotate_sub.yaml (новый) + openapi.yaml, internal/handlers/user_rotate_sub/
• internal/handlers/web/static/{app.js,index.html}

---

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

[Postlog]

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

Issue #111 — Меню действий в строке пользователя: «Сбросить токен подписки» (ротация subId → старая ссылка мертва) и «Копировать ссылку».

Резюме

Добавляем сервисную операцию ротации subId (минт нового, ре-байнд клиента на всех панелях с тем же uuid, обновление users.sub_id), новую ogen-ручку POST /admin/api/users/rotate-sub с тонким хендлером и компактное dropdown-меню действий во Vue-строке (копирование ссылки + ротация).

---

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

1. entity — sentinel-ошибки

Файл internal/entity/errors.go. Текущий код провижининга не возвращает доменного «user not found» (в Recreate/Delete отсутствие юзера — это users.Get → sql.ErrNoRows, классифицируется как 5xx). Для паритета с user_recreate (где любая ошибка = 500) ротацию делаем так же: отдельный sentinel не обязателен. Но users.UpdateSubID теоретически может словить UNIQUE-конфликт по sub_id (см. ниже) — это инфраструктурная коллизия, не пользовательский ввод, поэтому отдельного 4xx-sentinel не заводим, отдаём как 5xx (ретраится оператором). Итог: изменений в errors.go не требуется — фиксируем это явным допущением (см. «Риски»).

2. repository/users — метод UpdateSubID

Новый файл internal/repository/users/update_sub_id.go (один метод — один файл, по образцу set_description.go):

package users

import (
	"context"

	"github.com/postlog/subgen/internal/entity"
	"github.com/postlog/subgen/internal/repository/dberr"
)

// UpdateSubID rotates a user's subscription id (invalidates the old HMAC token). A
// collision on the sub_id UNIQUE constraint surfaces as entity.ErrNameTaken's sibling
// — but sub_id is service-minted (random), so a clash is an infra retry, not user input.
func (r *Repository) UpdateSubID(ctx context.Context, userID int64, subID string) error {
	_, err := r.db.ExecContext(ctx, `UPDATE users SET sub_id=? WHERE id=?`, subID, userID)
	if err != nil {
		if dberr.IsUniqueViolation(err) {
			return entity.ErrSubIDTaken // см. примечание ниже
		}
		return err
	}
	return nil
}

Примечание по UNIQUE: users.sub_id имеет UNIQUE-констрейнт (migrations/0001-init.sql:45). Так как новый subId генерится тем же randID(16) (36^16 пространство), коллизия практически невозможна. Решение (разумный дефолт): не заводить новый sentinel — на dberr.IsUniqueViolation отдавать сырую обёрнутую ошибку (станет 5xx). Это упрощает entity и согласуется с тем, что коллизия здесь — не пользовательская ситуация. Если ревьюер захочет явный sentinel — это однострочное добавление; вынесено в открытые вопросы.

Тогда метод упрощается до:

func (r *Repository) UpdateSubID(ctx context.Context, userID int64, subID string) error {
	_, err := r.db.ExecContext(ctx, `UPDATE users SET sub_id=? WHERE id=?`, subID, userID)
	return err
}

3. service/provisioning — метод RotateSubID

Расширяем контракт internal/service/provisioning/contract.go: в интерфейс userRepo добавить

UpdateSubID(ctx context.Context, userID int64, subID string) error

→ перегенерить мок: go generate ./internal/service/provisioning/... (обновит contract_mocks.go).

Новый метод в internal/service/provisioning/service.go (рядом с RecreateUser):

// RotateSubID mints a fresh sub_id (revoking the old HMAC subscription token), persists
// it, and re-binds the user's client on every panel with the SAME uuid but the new subId
// (AddClient carries subId). Identity (name/uuid) is preserved; only the subscription
// label rotates.
func (s *Service) RotateSubID(ctx context.Context, id int64) error {
	u, err := s.users.Get(ctx, id)
	if err != nil {
		return fmt.Errorf("users.Get: %w", err)
	}

	newSubID := s.genID(16)
	if err := s.users.UpdateSubID(ctx, u.ID, newSubID); err != nil {
		return fmt.Errorf("users.UpdateSubID: %w", err)
	}
	u.SubID = newSubID

	byID, _, err := s.nodeIndex(ctx)
	if err != nil {
		return err
	}

	var desired []connTarget
	for _, c := range u.Connections {
		desired = append(desired, connTarget{NodeID: c.NodeID, Node: c.Node, Port: c.Port, InboundID: c.InboundID})
	}

	// forceAll=true: re-bind every panel (subId changed even where the inbound set didn't);
	// syncPanels preserves the existing uuid via uuidByEmail and pushes u.SubID into AddClient.
	return s.syncPanels(ctx, byID, u, u.Connections, desired, true)
}

Почему это работает с существующим syncPanels (service.go:303): при forceAll=true для каждой панели делается delete-then-add, причём uuid сохраняется (uuidByEmail[email] → cid = existing, service.go:367), а AddClient(..., ClientSpec{ID: cid, Email: email, SubID: u.SubID}) (service.go:393) уже принимает subId. То есть ротация = тот же путь, что RecreateUser, но с предварительным минтом нового subId в стор. Дополнительный метод клиента/панели не нужен — AddClient уже всё умеет.

Порядок «БД → панели»: сначала пишем новый subId в стор (источник истины для токена), затем ре-байндим панели. Если ре-байнд частично упал — токен уже сменён (старая ссылка мертва — это и есть цель отзыва), а оператор добивает панели «Пересоздать». Это согласуется с поведением CreateUser (стор создаётся до синка панелей, service.go:189-195).

4. openapi/ogen — ручка userRotateSub

Новый файл openapi/user_rotate_sub.yaml (копия user_recreate.yaml, тело {id}):

# POST /admin/api/users/rotate-sub — rotate a user's subscription token (revoke old link).
post:
  operationId: userRotateSub
  summary: Rotate a user's subscription token
  security:
    - adminSession: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required: [id]
          properties:
            id:
              type: integer
              format: int64
  responses:
    '200': { description: rotated, content: { application/json: { schema: { $ref: './common.yaml#/components/schemas/MessageResponse' } } } }
    '400': { description: bad request, content: { application/json: { schema: { $ref: './common.yaml#/components/schemas/ErrorResponse' } } } }
    '401': { description: unauthorized, content: { application/json: { schema: { $ref: './common.yaml#/components/schemas/ErrorResponse' } } } }

В openapi/openapi.yaml добавить путь рядом с recreate (после строки 41):

  /admin/api/users/rotate-sub:
    $ref: './user_rotate_sub.yaml'

Затем go generate ./internal/oas/ — появятся oas.UserRotateSubReq/oas.UserRotateSubRes и метод UserRotateSub в интерфейсе oas.Handler (компилятор потребует реализацию и форвард).

Валидацию значений в схему не кладём (только required:[id]) — по правилу «value-constraints в сервисе». Суррогатный id не валидируем (несуществующий → not-found-подобный 5xx).

5. handler — пакет internal/handlers/user_rotate_sub

Зеркалим user_recreate (тонкий, любая ошибка = логированный 500, домен-4xx нет).

internal/handlers/user_rotate_sub/contract.go:

//go:generate go tool mockgen -source=contract.go -destination contract_mocks.go -package user_rotate_sub
package user_rotate_sub

import "context"

// rotator rotates a user's subscription token (the provisioning service satisfies it).
type rotator interface {
	RotateSubID(ctx context.Context, id int64) error
}

internal/handlers/user_rotate_sub/handler.go:

// Package user_rotate_sub implements the userRotateSub operation
// (POST /admin/api/users/rotate-sub).
package user_rotate_sub

import (
	"context"
	"log/slog"

	"github.com/postlog/subgen/internal/oas"
)

// MsgRotated is the success message (exported so apitest can assert it).
const MsgRotated = "Токен подписки сброшен"

type Handler struct{ svc rotator }

func New(svc rotator) *Handler { return &Handler{svc: svc} }

func (h *Handler) UserRotateSub(ctx context.Context, req *oas.UserRotateSubReq) (oas.UserRotateSubRes, error) {
	if err := h.svc.RotateSubID(ctx, req.ID); err != nil {
		slog.Error("handler user_rotate_sub: rotate failed", "id", req.ID, "err", err)
		return nil, err
	}
	return &oas.MessageResponse{Message: MsgRotated}, nil
}

go generate ./internal/handlers/user_rotate_sub/... сгенерит contract_mocks.go.

6. composite + wiring

• internal/handlers/api/server.go: добавить поле UserRotateSub *userRotateSubHandler.Handler в Handlers (рядом с UserRecreate, ~строка 67), импорт, и форвард-метод:

  func (s *Server) UserRotateSub(ctx context.Context, req *oas.UserRotateSubReq) (oas.UserRotateSubRes, error) {
      return s.h.UserRotateSub.UserRotateSub(ctx, req)
  }

• cmd/service/main.go: импорт userRotateSubHandler и строка в api.Handlers{...}: UserRotateSub: userRotateSubHandler.New(prov), (рядом с UserRecreate, ~строка 213).

7. фронт — меню действий в строке

Файлы internal/handlers/web/static/index.html + app.js.

В index.html сейчас две ячейки: <td> с кнопкой «Mihomo» (строка 80, copy(u.sub.url)) и <td class="actions"> с группой кнопок (строки 81-88). По issue нужно компактное dropdown-меню «…». Минимальный разумный вариант (Bootstrap уже вендорён, но JS-бандл Bootstrap не подключён — проверить; если нет, делаем dropdown на чистом Vue-состоянии, как другие тоглы в SPA): добавить в act-group пункты «Копировать ссылку» (вызывает copy(u.sub.url)) и «Сбросить ссылку» (вызывает новый rotateSub(u)). Дропдаун — через локальный флаг открытия на строке (openMenuId === u.id), чтобы не тянуть Bootstrap JS. Кнопку «Mihomo» можно оставить или свернуть в пункт меню «Копировать ссылку» (issue просит копирование — оставляем явный пункт).

В app.js рядом с recreateUser (строки 419-423) добавить:

async rotateSub(u) {
  if (!confirm("Сбросить ссылку подписки для " + u.name + "? Старая ссылка перестанет работать.")) return;
  this.actingId = u.id;
  try { const d = await this.post("/admin/api/users/rotate-sub", { id: u.id }); if (d.ok) await this.loadUsers(); }
  finally { this.actingId = 0; }
},

loadUsers() перечитает строку — u.sub.url обновится новым токеном (бэк считает его как token.Make(secret, новый subId) в users_get). «Копировать ссылку» переиспользует существующий copy() (app.js:385).

Дизайн-токены — как в AGENTS.md (3x-ui dark скин); используем существующие классы кнопок (btn-sm btn-outline-secondary), новых стилей минимум (опц. .dropdown-menu в app.css под палитру).

---

Миграции БД

Не требуются. users.sub_id уже существует с UNIQUE-констрейнтом (migrations/0001-init.sql:45); ротация — это UPDATE, схема не меняется.

---

OpenAPI / ogen

• Новый openapi/user_rotate_sub.yaml + $ref в openapi/openapi.yaml (см. шаг 4).
• go generate ./internal/oas/ — генерит UserRotateSubReq/Res + метод интерфейса.
• Value-валидация в схему не выносится; только required:[id].

---

Тесты

Unit (table-driven, один Test{Type}_{Method} на метод)

1. internal/repository/users/update_sub_id_test.go — TestRepository_UpdateSubID. Образец — set_description_test.go/delete_test.go (репо-тесты идут против реальной SQLite, см. соседние *_test.go). Кейсы: success (subId сменился, читается через Get/IDBySubID), error.not_found (несуществующий id → UPDATE 0 строк, без ошибки — фиксируем как no-op; если нужен not-found — обсудить).

2. internal/service/provisioning/service_test.go — добавить TestService_RotateSubID (мокаются userRepo/nodeRepo/panelClient через локальный contract_mocks.go; genID подменяется детерминированным, как уже инжектится в New). Кейсы:

   • success.rebinds_all_panels — Get отдаёт юзера с N коннектами на 1-2 узлах; ожидаем UpdateSubID(новый subId), затем на каждой панели ListInbounds → DelClient → AddClient с SubID=новый и сохранённым uuid (через uuidByEmail). Проверить, что в AddClient уходит именно новый subId.
   • error.user_get — users.Get → downstream err (проброс).
   • error.update_sub_id — UpdateSubID → downstream err (проброс, панели не трогаются — ListInbounds не ожидается).
   • error.panel_failure — один AddClient падает → агрегированная ошибка (syncPanels собирает failures в строку; здесь require.Error + ErrorContains, т.к. это не sentinel).
   • empty.no_connections — юзер без коннектов: только UpdateSubID, панели не трогаются.

   Примечание: genID в тесте надо зафиксировать — конструктор New ставит randID; в тесте после New(...) присвоить svc.genID = func(int) string { return "newsubid" } (поле приватное, но тест в том же пакете provisioning).

3. internal/handlers/user_rotate_sub/handler_test.go — TestHandler_UserRotateSub (мок rotator из локального contract.go). Кейсы: success (→ MsgRotated), error.downstream (→ проброс, nil, err). Зеркало user_recreate/handler_test.go.

apitest

Добавить сценарий в apitest/users/ (по образцу существующих user-сценариев против реального 3x-ui в docker): создать юзера, прочитать его sub.url/токен, дёрнуть POST /admin/api/users/rotate-sub сырым map[string]any{"id":...}, убедиться что (а) ответ 200+MsgRotated, (б) новый sub.url отличается, (в) старый токен на /sub/mihomo/<old> больше не резолвится (404/иное), (г) клиент на панели по-прежнему существует с тем же email и новым subId. Тела — чёрный ящик (map[string]any, не oas.*), id как число. Запуск: make -C apitest test под DOCKER_CONTEXT=desktop-linux (см. memory).

---

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

• CHANGELOG.md — новая запись сверху:
  ## 2026-06-12 — Ротация токена подписки: revoke/rotate subId (#111) + 1-2 строки сути (новая ручка POST /admin/api/users/rotate-sub, сервисный RotateSubID минтит новый subId и ре-байндит клиента с тем же uuid; меню действий в строке + копирование ссылки).
• ADR — не требуется. Изменение прямолинейное: переиспользует существующий путь syncPanels/AddClient, новых архитектурных развилок нет. Достаточно строки в CHANGELOG.

---

Риски и edge-cases

• Частичный отказ панелей при ротации: subId уже сменён в сторе (цель — отзыв старой ссылки — достигнута), но ре-байнд на части панелей мог упасть → новая ссылка на этих узлах временно не работает. Поведение идентично RecreateUser; оператор добивает «Пересоздать». Хендлер вернёт 5xx с агрегированной ошибкой — оператор увидит.
• Сохранение uuid: ключевой инвариант — uuid VLESS-credential НЕ меняется при ротации (меняется только метка subId). Это обеспечивается веткой uuidByEmail[email] в syncPanels (service.go:366-369) при forceAll=true. Тест должен это явно проверять, иначе ротация молча пересоздаст credential.
• UNIQUE-коллизия sub_id: практически невозможна (рандом 36^16); отдаём как 5xx без отдельного sentinel (допущение).
• Параллельные действия по одному юзеру: actingId/busy на фронте уже сериализуют кнопки в строке; гонок на бэке нет сверх существующих.
• Bootstrap dropdown JS: в SPA, возможно, не подключён JS-бандл Bootstrap — dropdown реализуем на Vue-состоянии (флаг открытия), не на data-bs-toggle. Проверить при реализации; на план не влияет.

---

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

Самодостаточно — внешних зависимостей от других issue (#83–#113) нет. Порядок внутри: entity (no-op) → users.UpdateSubID → provisioning.RotateSubID (+ контракт/мок) → openapi+go generate → хендлер → composite/wiring → фронт → тесты → CHANGELOG.

---

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

1. UNIQUE-коллизия sub_id в UpdateSubID — оставляем как 5xx (без нового sentinel, как предложено в дефолте выше), или завести entity.ErrSubIDTaken + типизированный 4xx? (Рекомендую дефолт: коллизия рандома 36^16 нереалистична, отдельный sentinel — лишний код.)
2. Кнопка «Mihomo» в строке (copy(u.sub.url), index.html:80) — свернуть её в пункт меню «Копировать ссылку», или оставить отдельную кнопку + добавить меню «…»? (Дефолт: заменяю кнопку «Mihomo» на компактное меню «…» с пунктами «Копировать ссылку» / «Сбросить ссылку», а «Изменить/Пересоздать/Удалить» оставляю как есть либо тоже сворачиваю в меню — по вкусу владельца.)