Skip to content

Latest commit

 

History

History
68 lines (54 loc) · 6.42 KB

steer-api-1.1.md

File metadata and controls

68 lines (54 loc) · 6.42 KB

steer-api 1.1 — что добавлено к 1.0

Ядро steer 2.1 говорит steer-api 1.1. Это прибавка к steer-api.md (1.0), а не новый договор: программа, написанная по 1.0, работает, если не опиралась на снятое (раздел «Снято»). Плагин, которому нужно новое, пишет compat.steer-api: "^1.1"; ядро 2.1 отвечает steer version --json с "api":"1.1". Тест совместимости программы с ядром 2.1 — sh tests/compat/run.sh --steer <каталог плагина> (заглушка ядра tests/compat/steer-2.1/host.py).

Официальные плагины протоколов (vless, hysteria2, proxy, xsteer, warpbox, obfs) написаны только на этом API: в ядре 2.1 нет ни их видов, ни их команд. Сторона плагина в исходниках ядра — steer/src/plugkit (pk_conf_load, pk_main, PK_PROGRAM) — образец разбора {conf} и точки входа.

Ядро без своих протоколов

  • Виды tunnel:<протокол> и xsteer, подкоманды и команды сокета протоколов — только из манифестов. Без плагина выход такого вида — unavail с причиной «нужен плагин — поставить», а apply — отказ с той же причиной; кто даёт вид, ядро узнаёт из provides.kinds индекса семени (/usr/share/steer/seed/index.json, index.md). Вида нет ни у кого — «протокол не знаю» / «неизвестный kind».
  • kinds[].description — строка для человека: её берёт steer spec-schema в описание варианта вида.

{conf} и команды (разделы 1.4 и 4.3)

  • commands[].conf: true — первое слово подкоманды — имя выхода: ядро находит его в спеке и передаёт программе --conf <файл> с {conf} этого выхода (memfd /proc/self/fd/N, иначе файл помощника). Слово с / — путь, передаётся как есть. --spec программам протоколов больше не передаётся (снято).
  • {conf} выхода, развёрнутого хуком expand с помощником (группа kind: warp), несёт вид и ключи, с которыми выход записал человек (output.kind: "warp", output.keys), а не группу, которой он стал, и output.members[] — выходы, заведённые разворотом: name, kind, device, mark, table, ipv6, over, sock_mark, sock_mark_required.
  • У выхода вида ядра с помощником от плагина (impl: core, helper.when) output.keys — ключи, которые печатает вид ядра (у interface с obfs — obfs).
  • ctl.args — объект {"kind": "int", "flag": "--node", "min": -1, "max": 9999}: число в пределах, которое ядро передаёт флагом; ctl.body: "file" и ctl.body_max — тело запроса временным файлом, путь — последним словом; ctl.lock. ctl.spec снято (manifest.md, steer.commands[]).

Хуки (раздел 3)

  • Вход check и expand несёт output.common — общие ключи выхода (on_fail, over, ipv6, device…), кроме kind, protocol и owner.
  • expand вида с помощником: развёрнутая группа получает owner на себя, и её помощник — помощник вида.

Помощник и события (раздел 2)

  • hello обязателен первым и несёт api (steer-api программы: major как у ядра, minor не новее) и mod — id плагина. Иначе процесс гасится, причина — в last_down и rejected (steer ctl helper). Версию плагина (ver) с версией ядра ядро не сверяет.
  • state — файл состояния <state>/plugin/<id>/<выход>.status.json переписан: ядро шлёт подписчикам сокета событие plugin-state ({"id","out"}); status печатает файл полем plugin.state выхода, у вида tunnel:<протокол> — ещё прежним полем "<протокол>". Файл мёртвого процесса (pid) не печатается.
  • В файле состояния diag — строки {"id","verdict","what","why"} для steer diag; probe — ход проверки узла {"state","node","total"}.
  • revive (прежнее имя awg) — файл члена развёрнутой группы переписан, перенастроить устройство.
  • kinds[].health: "events" — здоровье выхода по up/down (и node/nonode) помощника, без пробы ядра.
  • helper.when: "<ключ>" у вида impl: core — помощник выходу вида ядра, у которого есть этот ключ (плагин obfs: вид interface, ключ obfs).
  • x-watch: true у ключа-пути в схеме — содержимое файла входит в подпись перезапуска помощника.

Снято

  • ctl.spec и --spec/--state-dir у подкоманд протоколов: выход — только {conf}.
  • Встроенные виды vless, hysteria2, протоколы прокси и xsteer в ядре и шов steer-<id> рядом со steerd.

Телефон

В статической сборке телефона плагинов на диске нет (open.md, О-13): программы vless, xsteer и obfs слинкованы в бинарник (PK_PROGRAM), их манифесты — строками в нём; ядро запускает тот же бинарник с STEER_PK_BUILTIN=<id>. Договор с программой тот же.