Справочник REST API

HTTP API, который предоставляет демон Saba-chan. Схема аутентификации и каталог основных эндпоинтов.

Справочник REST API

Демон Saba-chan (saba-core) предоставляет HTTP REST API на 127.0.0.1:57474. GUI и CLI вызывают только этот API, а команды Discord, приходящие через облачный ретранслятор, обрабатываются теми же функциями внутри демона. По тому же контракту можно написать собственный клиент.

Этот справочник кратко описывает маршруты, которые, скорее всего, понадобятся пользователю или интегратору, по определениям маршрутов демона (src/ipc/). Некоторые внутренние маршруты опущены, а схемы полей могут меняться, поэтому актуальную информацию смотрите в коде.


1. Основы

  • Базовый URL: http://127.0.0.1:57474 (по умолчанию). Можно изменить переменной окружения SABA_IPC_PORT или параметром gui.ipcPort в config.json (вступает в силу после перезапуска демона).
  • Адрес привязки: жёстко задан как 127.0.0.1, поэтому снаружи недоступен. Запросы, у которых заголовок Host не является loopback-адресом (127.0.0.1, localhost, ::1), получают 403.
  • Аутентификация: каждому запросу, кроме /health, нужен заголовок X-Saba-Token. Демон создаёт новый токен при каждом запуске и записывает его в файл .ipc_token в папке данных (Windows: %APPDATA%\saba-chan\.ipc_token). При отсутствующем или неверном токене возвращается 401 без тела.
  • Content-Type: тела запросов — application/json. Большинство ответов тоже в JSON (исключения — пакеты GUI расширений, значки и т. п.).
  • Формат ошибок: зависит от маршрута. Распространённые формы — {"error": "...", "error_code": "..."}, {"success": false, "error": ..., "error_code": ...} и {"ok": false, "error": ...}. Некоторые маршруты при ошибке возвращают HTTP 200 с ok:false, поэтому проверяйте и тело.

2. Проверка работоспособности и демон

GET  /health                     # токен не нужен
GET  /api/version
GET  /api/diagnostics
GET  /api/events                 # поток событий (SSE)
POST /api/daemon/shutdown
  • /health: {"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}. token лишь сообщает, верен ли отправленный X-Saba-Token; само значение никогда не раскрывается.
  • /api/version: {version, components: {...}} (версии ядра, модулей и расширений).
  • /api/events: Server-Sent Events. Основные типы — instance.exit (завершение сервера / вердикт о сбое), backup.done, update.available, schedule.warn, provision.progress и action.run. При переподключении пропущенные события можно догнать с помощью заголовка Last-Event-ID или ?since=<n>.
  • /api/daemon/shutdown: завершает работу демона.

3. Серверы (экземпляры)

Saba-chan управляет каждым сервером как экземпляром, который идентифицируется UUID (id).

3.1 Список, создание, изменение, удаление

GET    /api/servers                        # список серверов + состояние работы
GET    /api/instances                      # список экземпляров
POST   /api/instances                      # создать
PUT    /api/instances/reorder              # тело: { "order": [id, ...] }
GET    /api/instance/:id                   # подробности (+ состояние согласия с условиями в agreements)
PATCH  /api/instance/:id                   # изменить настройки (объект ключ-значение)
DELETE /api/instance/:id                   # удалить
POST   /api/instance/:id/rename            # тело: { "name": "..." }
  • Основные поля POST /api/instances: { "name", "module_name", "port"?, "preset"?, "module_settings"?, "accept_agreements"?: [id] }. При успехе возвращается 201 {success, id, ...}, а если в модуле определён этап установки, в фоне начинается установка файлов сервера (§3.5).
  • Помимо порта и настроек модуля, PATCH /api/instance/:id принимает и настройки демона, например:
    • auto_restart, restart_on_unknown_exit: перезапускать ли автоматически после сбоя / завершения по неизвестной причине
    • extra_args: дополнительные аргументы запуска (строка или массив строк; null очищает их)
    • memory_limit_mb: лимит памяти (МиБ, не менее 256; принимаются формы "4G"/"4096M"; null/0 — без ограничения). Действует только в Windows.
  • Для переименования сервер должен быть остановлен; если имя уже занято, возвращается 409 name_taken.

3.2 Запуск / остановка / перезапуск

POST /api/instance/:id/start
POST /api/instance/:id/stop                # необязательное тело: { "force": true }
POST /api/instance/:id/restart             # необязательное тело: { "force": true }
GET  /api/instance/:id/events              # история последних завершений
GET  /api/server/:name/status              # состояние по имени
  • Перед запуском демон проверяет согласие с условиями и выполняет проверки модуля. Непринятые условия возвращают 409 agreement_required (с agreements); критический провал проверки — 409 preflight_failed.
  • Остановка отправляет игре команду корректной остановки, ждёт тайм-аут модуля (по умолчанию 30 секунд) и принудительно завершает процесс, если он ещё жив. С force: true процесс завершается немедленно.
  • events возвращает {events: [...]} с вердиктом о завершении (user_stop, in_game_stop, crash, unknown_exit), доказательствами, запланированным автоперезапуском и т. д.

3.3 Консоль и команды

GET  /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin               # тело: { "command": "say hello" }
POST /api/instance/:id/command             # тело: { "command": "<name>", "args"?: {...} }
GET  /api/instance/:id/commands            # команды, доступные для этого сервера
POST /api/instance/:id/rest                # игры только с REST (например, Palworld)
POST /api/instance/:id/rcon                # имя для совместимости; использует путь команд ниже (stdin → REST → RCON)
  • Опрос консоли: ответ — {success, lines: [{id, timestamp, source, content, level}], running, ...}. С since возвращаются строки, у которых id больше или равен ему, поэтому в следующий раз отправляйте последний полученный id + 1. Без since вы получите последние count строк (по умолчанию 100). Демон хранит в памяти последние 10 000 строк каждого сервера.
  • Порядок путей команд: stdin → REST → RCON. Команды сначала идут в консоль сервера (stdin), а для игр, поддерживающих только REST, например Palworld, — через REST. RCON используется только для игры, модуль которой объявляет supported = ["rcon"] (нет ни консоли, ни REST API); тогда демон назначает каждому экземпляру свой порт и случайный пароль и подключается только через loopback (127.0.0.1). В остальных случаях /rcon — путь, сохранённый только по имени для старых клиентов; он отправляет в stdin. Серверы без пути команд возвращают 409 no_command_path.
  • /stdin возвращает 409 stdin_not_supported, если модуль не поддерживает stdin.
  • /command выполняет команду, определённую модулем; если сервер остановлен, возвращается 409 server_not_running.

3.4 Настройки, условия, проверки

POST /api/instance/:id/launch-preview      # тело: { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements          # тело: { "accept": ["eula"] }
GET  /api/instance/:id/properties          # прочитать конфигурационный файл игры
PUT  /api/instance/:id/properties          # тело: { "settings": {...} }
POST /api/instance/:id/validate            # проверка сервера
POST /api/instance/:id/diagnose            # диагностика журнала
  • launch-preview вычисляет командную строку запуска, не запуская сервер. Пример ответа: {success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}. Значения паролей маскируются как ***. Если модуль не объявляет аргументов запуска, возвращается has_launch_args: false.
  • agreements записывает согласие с условиями, которые объявляет модуль (например, eula в Minecraft). Работает только локально; запросы из удалённых источников (Discord и т. п.) получают 403 agreement_local_only. Для необъявленных id возвращается 400 invalid_format.

3.5 Ход установки и обновления игрового сервера

GET    /api/provision-progress/:name       # :name = имя экземпляра
DELETE /api/provision-progress/:name       # закрыть состояние неудачного прогресса
GET    /api/instance/:id/check-update
POST   /api/instance/:id/apply-update

Пример ответа provision-progress:

{
  "active": true,
  "step": 2,
  "total": 5,
  "label": "...",
  "message": "...",
  "percent": 40,
  "done": false,
  "error": null
}

Когда ничего не выполняется, возвращается {"active": false}. Успешное состояние прогресса автоматически очищается через 5 секунд; неудачное остаётся, пока вы не закроете его через DELETE (если сервер только создавался, в этот момент создание откатывается). Прогресс доступен и как provision.progress в /api/events.

apply-update возвращает 409 server_running, если сервер работает. Перед обновлением делается бэкап (для модулей с поддержкой бэкапов).

3.6 Бэкапы и задачи по расписанию

GET    /api/instance/:id/backups                     # { success, backups: [{ name, kind, created, size }] }
POST   /api/instance/:id/backups                     # сделать бэкап сейчас
DELETE /api/instance/:id/backups/:name
POST   /api/instance/:id/backups/:name/restore       # сервер должен быть остановлен
GET    /api/instance/:id/schedule
PUT    /api/instance/:id/schedule                    # тело: { "schedule": [...], "backup_keep"?: 10 }
  • kind бэкапа: manual, scheduled, pre-update, pre-restore. Если модуль не поддерживает бэкапы, возвращается 400 backup_unsupported; если сохранять пока нечего — 400 nothing_to_back_up.
  • Восстановление возвращает 409 server_running, если сервер работает, а перед восстановлением текущее состояние сохраняется как pre-restore.
  • Вид одной задачи по расписанию:
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }

action — backup | restart | announce | update; используется ровно одно из every_minutes (каждые N минут) и at (ежедневно в HH:MM). Для announce нужен message, а warn_minutes применяется только к restart и update. Неверные задачи возвращают 400 validation_failed (с details).


4. Модули

GET    /api/modules                        # установленные модули
POST   /api/modules/refresh                # перечитать папку модулей
GET    /api/module/:name                   # метаданные модуля
GET    /api/module/:name/versions          # версии игрового сервера, доступные для установки
GET    /api/module/:name/locales
GET    /api/modules/manifest               # каталог модулей, доступных для установки
POST   /api/modules/manifest/:id/install   # установить модуль из каталога
DELETE /api/modules/:id                    # удалить модуль

Каталог модулей берётся из подписанного списка релизов, а загруженные файлы устанавливаются только после сверки их хеша.


5. Расширения

GET    /api/extensions                     # список с состоянием установки/включения
POST   /api/extensions/rescan
GET    /api/extensions/manifest            # каталог расширений, доступных для установки
GET    /api/extensions/updates
POST   /api/extensions/:id/install
DELETE /api/extensions/:id
POST   /api/extensions/:id/enable          # асинхронно выполняет хук daemon.startup
POST   /api/extensions/:id/disable

GET    /api/extensions/:id/config
PUT    /api/extensions/:id/config

GET    /api/extensions/:id/gui             # пакет GUI (UMD JavaScript)
GET    /api/extensions/:id/gui/styles      # CSS
GET    /api/extensions/:id/i18n/:locale    # ko / en / ja / ...

Ошибки маршрутов расширений имеют вид {success: false, error, error_code, ...}.


6. Настройки

GET  /api/config/gui
PUT  /api/config/gui                       # частичный JSON (поверхностное слияние)
GET  /api/config/bot
PUT  /api/config/bot                       # настройки бота, например префикс и псевдонимы (частичный JSON)
GET  /api/system/metrics                   # CPU, память, диск, потребление по серверам

Все пользовательские настройки хранятся по пространствам имён в одном файле config.json в папке данных. Демон синхронизирует настройки бота с ретранслятором. Сам Discord-бот работает на облачном ретрансляторе, поэтому у демона нет API для запуска или остановки процесса бота.


7. Обновления

GET  /api/updates/status                   # текущее состояние и версии по компонентам
POST /api/updates/check                    # проверить обновления сейчас
POST /api/updates/download                 # необязательное тело: { "components": [...] }
GET  /api/updates/download/progress
POST /api/updates/apply                    # необязательное тело: { "components": [...] }
POST /api/updates/launch-updater           # применить через установщик (демон останавливается)
GET  /api/updates/config
PUT  /api/updates/config

Сведения об обновлениях берутся из подписанного списка релизов. Компоненты, чьи работающие файлы нужно заменить, помечаются в ответе apply как требующие отдельного применения; вызов launch-updater запускает установщик (saba-chan-installer --apply), который останавливает демон, заменяет файлы и снова запускает только то, что изменилось. Эти маршруты отвечают в виде {ok: ...}.


8. Сопряжение с облачным ретранслятором

Для процесса сопряжения GUI ↔ сервер-ретранслятор. Подробный порядок действий — на странице Discord-бот.

POST   /api/relay/pair/initiate            # выдать код сопряжения (передаётся ретранслятору)
GET    /api/relay/pair/:code/status        # опросить, завершено ли сопряжение
GET    /api/relay/agent                    # состояние агента ретранслятора
POST   /api/relay/agent/start
POST   /api/relay/agent/stop
DELETE /api/config/node-token              # удалить токен узла этого ПК (останавливает агента)

Когда сопряжение завершено (status: "claimed"), демон автоматически сохраняет токен узла и переподключает агента ретранслятора с новым токеном. Аутентификацией перед ретранслятором занимается демон, так что клиентам об этом заботиться не нужно.


9. Пример аутентификации (curl)

TOKEN=$(cat "$APPDATA/saba-chan/.ipc_token")

curl -H "X-Saba-Token: $TOKEN" \
     http://127.0.0.1:57474/api/servers

curl -X POST \
     -H "X-Saba-Token: $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"command":"list"}' \
     http://127.0.0.1:57474/api/instance/<instance-id>/stdin

<instance-id> — это id из ответа GET /api/servers или GET /api/instances.


10. Совместимость версий

  • Этот API относится к приватному IPC. Это не публичный контракт, поэтому пути и схемы могут меняться даже в минорных версиях.
  • Если вы распространяете собственный клиент, проверяйте версию демона (version из GET /health) и обрабатывайте её консервативно.

Если возникли проблемы, переходите в раздел Устранение неполадок.