7.6 KiB

Raw Blame History

HTTP API сервера

Служебный HTTP-слой матчевого блока: очередь, тикеты на подключение и /health. После подключения клиент переходит на WebSocket и работает по docs/protocol.md.

Базовая часть стека: ASP.NET Core 10, один процесс, состояние в памяти.

1. Запуск

$env:PATH = "$env:LOCALAPPDATA\dotnet;$env:PATH"

dotnet run --project server\src\Vanguard.Server --urls http://localhost:5080

Проверка:

Invoke-RestMethod http://localhost:5080/health

Контейнер:

docker compose up --build
# http://localhost:8080/health

Каталог карт ищется в content/sets вверх от каталога сборки. Если контент лежит в другом месте, задайте Content:Path (или Content__Path в окружении).

2. Авторизация

Пока это dev-заглушка: игрок представляется строкой playerId. Никаких токенов и паролей нет, поэтому сервер нельзя выставлять в интернет как есть.

Когда появится мета-API, playerId будет браться из JWT, а контракты очереди и тикетов не изменятся. Ограничения на формат: 1–64 символа, буквы, цифры, _, ., -.

3. Очередь

`POST /api/game/queue`

Поставить игрока в очередь.

{
  "playerId": "p1",
  "mode": "classic-ranked",
  "deck": ["BT01/001EN", "BT01/002EN", "..."]
}

mode: classic-ranked или classic-casual.
deck: ровно 50 printingId. Проверяются те же правила, что и в декбилдере: 50 карт, ≤4 по nameId, ≤4 Sentinel, ≤4 Heal, известные принты и хотя бы одна карта grade 0 без триггера для стартового Авангарда.

Ответ 200:

{
  "queueId": "5b5c7a4e-9d5a-4f7b-a0d8-6f1b2c3d4e5f",
  "status": "queued",
  "mode": "classic-ranked"
}

Ответ 400 при плохой колоде:

{
  "error": "deck.invalid",
  "message": "Колода не проходит проверку.",
  "violations": [
    { "code": "deck.size", "message": "В колоде 49 карт, требуется 50." }
  ]
}

Повторный запрос от того же playerId отменяет его предыдущую очередь в любом режиме: один игрок — одна активная очередь.

`GET /api/game/queue/{queueId}?playerId=p1`

Статус очереди. Клиент опрашивает, пока не получит matched.

{
  "queueId": "5b5c7a4e-9d5a-4f7b-a0d8-6f1b2c3d4e5f",
  "status": "matched",
  "mode": "classic-ranked",
  "waitedSeconds": 7,
  "window": 100,
  "matchId": "9f2c...",
  "seat": 0,
  "ticket": "c2VjcmV0...",
  "opponent": "p2",
  "reason": null,
  "wsUrl": "ws://localhost:5080/game"
}

status:

Значение	Смысл
`queued`	ждёт противника, `window` — текущее окно MMR
`matched`	матч найден, `ticket` — одноразовый тикет
`cancelled`	игрок отменил очередь или встал в новую
`expired`	очередь истекла (10 минут)
`failed`	не удалось создать матч

wsUrl заполняется только для matched. Он строится из Game:PublicWsUrl или из текущего запроса. Тикет живёт 60 секунд: если клиент не успел подключиться, он запрашивает новый через POST /api/game/tickets с matchId.

Подбор:

две независимые очереди — ranked и casual;
скрытый MMR, стартовое окно ±100;
окно расширяется на 50 каждые 5 секунд, максимум 2000;
пара выбирается по ближайшему MMR в пределах взаимных окон;
кто встал раньше — садится за место 0.

MMR наружу не отдаётся. В ранкеде после матча он меняется по Эло (K = 32), в casual — нет.

`DELETE /api/game/queue/{queueId}?playerId=p1`

Отменить очередь. 204 — отменена, 409 — уже не активна.

4. Тикеты

`POST /api/game/tickets`

Выдать новый одноразовый тикет на подключение. Нужен для переподключения после обрыва: старый тикет уже израсходован.

{ "playerId": "p1", "matchId": "9f2c..." }

Ответ 200:

{
  "ticket": "c2VjcmV0...",
  "matchId": "9f2c...",
  "seat": 0,
  "wsUrl": "ws://localhost:5080/game",
  "expiresAt": "2026-10-21T12:01:00+00:00"
}

TTL — 60 секунд, тикет одноразовый.
Тикет привязан к (playerId, matchId, seat).
Если матч уже завершён, тикет всё равно выдаётся: клиент может подключиться и посмотреть итоговое состояние.
404 — матч не найден, 403 — игрок не сидит в этом матче.

5. Health

`GET /health`

{
  "status": "ok",
  "matches": 3,
  "activeMatches": 2,
  "queued": 4,
  "serverTimeMs": 1760000000000
}

matches включает завершённые матчи, которые ещё живут в памяти (10 минут после финала — для реконнекта и просмотра результата).

6. Полный сценарий

POST /api/game/queue        → queueId
GET  /api/game/queue/{id}   → matched + ticket + wsUrl
WS   /game                  → ClientHello(ticket)
                            ← ServerHello + ServerSnapshot
                            → ClientIntent(...)
                            ← ServerIntentResult + ServerEvents
...
обрыв
POST /api/game/tickets      → новый ticket
WS   /game                  → ClientHello(ticket, resumeFromSeq)
                            ← ServerHello + ServerEvents (догон)

Формат WebSocket-кадров, интентов, событий, таймеров и кодов ошибок — docs/protocol.md.

7. Ограничения текущего этапа

Всё состояние (очереди, тикеты, матчи, профили) — в памяти процесса. Рестарт сервера теряет матчи; клиентский kill и реконнект переживаются.
Один процесс: горизонтальное масштабирование и Orleans-хостинг ещё впереди.
IMatchGrain уже отделён от ASP.NET Core и WebSocket: замена на Orleans grain не затронет транспорт и правила.
Нет PostgreSQL/Redis, JWT, коллекций и наград — это следующие блоки.
Rate limit: 16 интентов в секунду с одного соединения. Живой UI в него не упирается; тестовый бот специально притормаживается.

7.6 KiB Raw Blame History Unescape Escape