Skip to content

Latest commit

 

History

History
405 lines (333 loc) · 53.1 KB

splify2-api.md

File metadata and controls

405 lines (333 loc) · 53.1 KB

splify2-api v1: бэкенд splify2 для плагинов

Версия 1.3. Прибавки minor: 1.1 — splify2.luci.interface, метод paths; 1.2 — splify2.cgi; 1.3 — методы awg_list, awg_put, awg_del. Тег совместимости — compat.splify2-api (manifest.md). Хост пишет свою версию API в ответ plugins_list (поле splify2_api) и в SPLIFY2_API (major, число) каждой программе плагина. Правило версий то же, что у steer-api и host-api: minor добавляет (новый хук, поле, событие), major ломает. Плагин ^1.x исполняется хостом с API 1.y, если y ≥ x; блок splify2 плагина с другим major хост не применяет, а причину называет в ext_errors ответа plugins_list.

Что входит в splify2-api:

  1. блок splify2 манифеста: priority, hooks, tasks, events, methods, settings (и зарезервированные luci, kinds, hide, deny);
  2. хуки каркаса: список, порядок, протокол, политика отказа;
  3. периодические задачи вместо строк crontab в postinst;
  4. события ядра: одна подписка на роутер, раздача плагинам;
  5. псевдонимы и переопределения методов объекта rpcd splify2, таблица methods.tsv, final;
  6. защита: права, безопасный режим, что бывает с упавшим хуком;
  7. окружение программ плагина и библиотека для shell-плагинов (SPLIFY2_LIB);
  8. службы хоста (SPLIFY2_HOST): скачивание, спека, настройки каркаса, применение, настройки плагина;
  9. граница API: что плагин не трогает и как это проверяет s2p lint;
  10. версии, тесты совместимости и что пока не действует.

Что здесь не описано: интерфейс панели (host-api.md), ядро (steer-api.md), методы самих плагинов (rpc в manifest.md).

Решения владельца, на которых стоит раздел: плагины splify2 могут урезать, менять и переопределять логику каркаса (хуки, замена обработчиков, скрытие и замена экранов); SDK один на steer и splify2; у каждой версии хоста с явными изменениями API — новая версия SDK и тесты совместимости.

1. Блок splify2 манифеста

Поле верхнего уровня рядом с steer, rpc, ui. Нужна ось compat.splify2-api; плагин с блоком без неё не применяется (s2p lint отказывает раньше).

"compat": { "splify2-api": "^1.0" },
"permissions": ["splify2.hooks", "splify2.override"],
"splify2": {
  "priority": 100,                                   // порядок хуков и обёрток: меньше — раньше
  "hooks": {
    "pre_spec_set":    { "prog": "hooks/spec",  "mode": "transform", "timeout_s": 10 },
    "pre_apply":       { "prog": "hooks/apply", "mode": "veto" },
    "post_apply":      { "prog": "hooks/apply" },
    "heal":            { "prog": "hooks/heal",  "mode": "transform" },
    "backup_sections": { "prog": "hooks/backup" },
    "support_report":  { "prog": "hooks/support" },
    "purge":           { "prog": "hooks/purge" },
    "plugin_changed":  { "prog": "hooks/changed" },
    "sub_fields":      { "prog": "hooks/sub-fields" }
  },
  "tasks": [
    { "name": "update-subs",  "every": "10m", "prog": "bin/update-subs", "only_if": "engine-enabled" },
    { "name": "update-lists", "cron": "M 5 * * *", "jitter": "random-minute", "prog": "bin/update-lists" }
  ],
  "events": { "subscribe": ["applied", "switched", "failed"], "prog": "hooks/event" },
  "methods": {
    "alias":    { "sub_quota": "quota" },                       // splify2.sub_quota → splify2.p.<id>.quota
    "override": { "ui_get": { "prog": "rpc/ui_get", "mode": "wrap" } }
  },
  "settings": { "schema": "settings.schema.json" }
}
Поле Что
priority целое, по умолчанию 100. Хуки и обёртки идут по возрастанию priority, при равных — по id плагина
hooks хуки по именам из раздела 2; ключ с неизвестным именем — схема отвергает
tasks периодические задачи, раздел 3
events подписка на события ядра, раздел 4
methods псевдонимы и переопределения методов, раздел 5
settings.schema схема настроек плагина (JSON Schema, путь внутри плагина). Одна схема — форма в каркасе LuCI и форма в Andromeda. Значения лежат в conf/<id>/settings.json, читают и пишут их методы каркаса plugin_settings_get и plugin_settings_set; у плагина с steer.settings: "restart" (steer-api-1.5.md) хост после записи зовёт steer reload — помощники плагина поднимаются с новыми настройками сразу
luci.interface с 1.1: вид LuCI, которым плагин заменяет главный экран (splify2-api-1.1.md)
cgi с 1.2: CGI плагина в каталоге CGI веб-сервера, право splify2.cgi (splify2-api-1.2.md)
luci.views, luci.tabs, kinds, hide, deny зарезервированы под каркас LuCI (splify2-luci): схема их принимает, хост не применяет (раздел 10)

Права (permissions, manifest.md): splify2.hooks — любой хук; splify2.override — methods.override; splify2.hide, splify2.deny — зарезервированные поля. Карточка плагина показывает их человеку при установке. Хук или переопределение без права в реестр не попадают.

Словари языка каркаса — отдельно: i18n/core/<язык>.json включённых плагинов (формат — s2p.md).

2. Хуки

Хост собирает реестр (/var/run/splify2/ext.reg) из манифестов включённых плагинов при любой перемене их состава и, если файла нет или state.json менеджера новее, при ближайшем вызове. Хуки идут из реестра, а не из манифестов на каждый вызов.

Хук Где в каркасе Что может плагин
pre_spec_set spec_set: после разбора присланной спеки во временный файл, до проверки ядром transform — переписать файл (SPLIFY2_SPEC_TMP), результат всё равно проверит ядро; veto — отказать; warn — довезти файлы, на которые ссылается спека (так каталог списков скачивает недостающие), и предупредить о том, что не вышло; observe
post_spec_set spec_set: после записи спеки наблюдать (так плагин ставит отложенное применение)
pre_apply apply: после зон фаервола, до steer apply veto — остановить применение; warn — довезти файлы спеки и предупредить, строка в ответе
post_apply apply при коде ядра 0 наблюдать
post_apply_fail apply при коде ядра не 0 наблюдать
heal apply и spec_heal: после зашитого лечения transform — поправить рабочую копию спеки; принятую ядром копию хост кладёт на место
backup_sections архив настроек (плагин backup) отдавать, проверять и принимать свои разделы архива
support_report support_report добавить раздел отчёта (без секретов)
purge splify2-purge назвать свои следы (показ) или убрать их (--yes)
plugin_changed после установки, снятия, включения, выключения, обновления плагина пересчитать своё
sub_fields sub_list и sub_info: один вызов на весь ответ добавить к строке каждой подписки свои поля (расписание, пометки); каркас их пересылает как есть

2.1 Протокол

Программа получает на stdin объект {"api": 1, "hook": "<имя>", "plugin": "<id>", "ctx": {…}}, отвечает в stdout объектом JSON с кодом 0 за срок timeout_s (по умолчанию 10 с). Программа запускается от root в каталоге плагина, с окружением раздела 7 плюс SPLIFY2_HOOK (имя хука). Ответ:

{ "ok": true, "warn": ["строка для человека"], "error": "причина отказа" }

ok — истина, если плагин не возражает. warn — предупреждения, хост добавляет их в ответ метода. error — причина, если ok ложно. Остальные поля хук называет сам по таблице ниже; неизвестные хост пропускает.

Хук ctx Дополнительно в ответе
pre_spec_set {"spec_tmp": "<путь>"}; путь же в SPLIFY2_SPEC_TMP —
post_spec_set {"rev": "<ревизия>"} —
pre_apply {"spec": "<путь JSON-вида спеки>"} —
post_apply, post_apply_fail {"rc": <код ядра>, "output": "<вывод>"} —
heal {"spec_tmp": "<путь рабочей копии>"}; путь же в SPLIFY2_SPEC_TMP message — что поправлено (в ответе apply)
backup_sections {"op": "export"}, {"op": "check", "sections": {"имя": "текст"}} или {"op": "restore", "sections": {…}} export: sections — объект «имя → текст», warn — что не попало в архив; check: ok:false с error отменяет восстановление целиком до первой записи; restore: restored — массив {name, kind, count, dropped} (что записано, показывается человеку числами), warn
support_report {} section: {"title": "…", "text": "…"}
purge `{"dry_run": true false, "keep_config": true
plugin_changed `{"id": "<плагин>", "action": "install remove
sub_fields {"subs": [{"name", "kind": "url|links|none", "present": bool, "mtime": <unix-время файла узлов>}]} fields: объект «имя подписки → {поле: значение}», значение — строка, число или флаг. Поля, которые каркас отдаёт сам (name, title, link, url, kind, path, present, bytes, mtime, used, used_nodes, quota, hwid), не принимаются; имя поля — [a-z_][a-z0-9_]*

Имена разделов backup_sections — [A-Za-z0-9_]+, текст — обычный текст без управляющих знаков (кроме перевода строки и табуляции). В архив раздел ложится как [plugin <id> <имя>], строки текста — с отступом в один пробел; архив с такими разделами — формат 4 (без них остаётся формат 3 и читается прежними версиями). Плагину, которого нет на роутере, раздел не передаётся: восстановление идёт дальше, в ответе — предупреждение.

Порядок восстановления. Плагин backup проверяет присланный файл целиком до первой записи: настройки каркаса — службой хоста state check, данные плагинов — операцией check хука. Записывает он в таком порядке: сначала разделы плагинов (restore), потом настройки каркаса (state import). Порядок не случаен: спека из архива ссылается на файлы, которые кладут плагины (свои списки), а ядро при проверке спеки читает их с диска. Поэтому при restore плагин ещё не видит восстановленную спеку; операция check не меняет ничего ни у кого.

Хук backup_sections вызывает не каркас, а плагин-владелец (backup): он просит хост раздать хук (hook) и получает ответы плагинов. Так формат архива остаётся у плагина, а каркас не знает, что архив существует.

2.2 Режимы и исход

Режим Ответ ok:false Ответ warn
veto отказ операции словами error предупреждение
warn предупреждение словами error предупреждение
transform предупреждение; файл, который успел переписать плагин, остаётся предупреждение
observe (умолчание) только журнал только журнал

Политика отказа. Хук, который упал (код не 0), не ответил за срок или ответил не объектом JSON, не останавливает ничего: строка в журнале (logger -t splify2-ext) и предупреждение в ответе («плагин X: хук Y не ответил за срок»). Плагин не должен уметь «кирпичить» применение случайно. Явное "critical": true у хука меняет это: упавший, зависший или ответивший не по форме хук такого плагина останавливает операцию; карточка плагина показывает это как право.

Хуки до операции идут под замком state (общий с spec_set, apply, подписками, архивом), потому что трогают спеку; хук может вызывать методы каркаса — вложенный вызов замок уже держит родитель.

3. Периодические задачи

tasks[] заменяет строки crontab из postinst пакета. Менеджер состава плагинов (plugin_sync) пишет один размеченный блок в /etc/crontabs/root:

# splify2-plugins begin
*/10 * * * * /usr/sbin/splify2-task <плагин> <задача>
17 5 * * * /usr/sbin/splify2-task lists-catalog update-lists
# splify2-plugins end

Чужие строки crontab не трогаются; плагин выключен или снят — его строк в блоке нет; последний — нет и блока.

Поле Что
name [a-z0-9][a-z0-9-]*, уникально внутри плагина
every Nm, Nh, Nd: 10m → */10 * * * *; 6h → <минута> */6 * * *; 1d → <минута> 4 * * *
cron пять полей crontab; M в поле минут — минута, выбранная один раз
jitter random-minute — минута выбирается случайно один раз и хранится в /etc/splify2/tasks.json (ключ "<плагин>:<задача>"); none — минута 0. Роутеры не стучатся в источник в одну секунду
prog программа в каталоге плагина; получает окружение раздела 7, SPLIFY2_TASK и первым аргументом имя задачи
only_if engine-enabled — автозапуск ядра включён (есть S??steer в /etc/rc.d); spec-present — есть спека
timeout_s срок, по умолчанию 600 с

Одно из every и cron обязательно. splify2-task берёт замок на задачу (прошлый запуск ещё идёт — второй не стартует; брошенный замок с мёртвым процессом снимается), проверяет only_if и срок. В безопасном режиме задачи не записываются и не запускаются. Постоянную службу плагин объявляет в steer.services[] (manifest.md), а не задачей.

4. События ядра

events подписывает плагин на события ядра (steer-api.md, «События»). Плагины не подписываются сами (у каждой подписки своя очередь событий в демоне): хост держит одну службу splify2-events (steer ctl subscribe) и раздаёт события. Служба поднимается, когда хотя бы у одного включённого плагина есть events, и останавливается, когда последнего не осталось. Соединение оборвалось — подписка возобновляется через несколько секунд; пропущенные события не повторяются.

subscribe — имена событий (applied, switched, failed, helper-down, …) или *. Программа prog получает на stdin {"api": 1, "event": {<строка события ядра как есть>}}, ответа не требуется, код и срок (timeout_s, 10 с) только в журнал. События неизвестных имён хост пропускает: список растёт в той же версии.

5. Методы: псевдонимы и переопределения

Все методы объекта splify2 перечислены в methods.tsv (по строке «имя, вид[, плагин]»), и этот файл — часть API:

Вид Что значит
frame метод каркаса: обработчик можно обернуть или заменить (methods.override); имя занять нельзя
final plugin_*, plugins_*, repo_*, repos_*, prefs_*: ни заменить, ни обернуть, ни взять имя
fast быстрый путь опроса (live, spec_get, applied_get): диспетчер отвечает на них до чтения реестра, поэтому заменить их нельзя
moved метод вынесен из каркаса в плагин (третья колонка): без плагина отвечает отказом not_installed («Нужен плагин X»), с плагином его имя берёт methods.alias этого плагина

Псевдонимы (methods.alias: «имя на объекте splify2 → метод rpc.methods плагина»):

  • вынесенный из каркаса метод — только плагин, названный в methods.tsv, и только из официального репозитория (splify2, splify2-core-plugins); иначе имя занято и блок отвергается строкой в ext_errors;
  • новое имя, которого у каркаса нет, — любой плагин; имя появляется в list объекта (после перечитки rpcd), а права на него (access метода плагина) хост записывает в ACL группы плагина splify2-p-<id>;
  • занятое имя (каркасом, final, быстрым путём, другим плагином) — отказ с названием занявшего;
  • ответ псевдонима — ответ метода плагина дословно, вход — запрос дословно (в том числе большой: через файл).

Переопределения (methods.override, право splify2.override; только методы вида frame):

Режим Что делает хост
replace вызывает программу плагина вместо обработчика каркаса; не более одного replace на метод — второй отвергается с названием занявшего
wrap вызывает обработчик каркаса и передаёт его ответ программе плагина в SPLIFY2_NEXT (и в файле SPLIFY2_NEXT_FILE); ответ программы — новый ответ. Обёрток может быть несколько: по priority, затем по id

Программа получает метод первым аргументом, запрос — на stdin. Упавшая или ответившая не по форме замена даёт ответ каркаса; упавшая обёртка — ответ без неё; "critical": true меняет первое на отказ.

6. Защита

  • final. Методы plugin_*, plugins_*, repo_*, repos_*, prefs_* не переопределяются, не оборачиваются и не берутся псевдонимом: ни при каком праве. Через них человек всегда может снять плагин.
  • Права. Хук без splify2.hooks, переопределение без splify2.override в реестр не попадают.
  • Безопасный режим — файл /etc/splify2/safe или SPLIFY2_SAFE=1 в окружении вызова. Хуки, задачи, события и переопределения выключены; остаются каркас, менеджер плагинов и псевдонимы вынесенных из каркаса методов (архив настроек и каталог списков продолжают работать). Реестр пересобирается сам при появлении и снятии файла.
  • Упавший хук ничего не останавливает (раздел 2.2); исключение — явный critical.
  • Причины. Всё, что хост не принял из блока splify2, записано строкой err реестра и приходит в plugins_list.ext_errors: нет права, версия API не та, имя занято, программы нет или она не исполняемая.

7. Окружение программы и библиотека для shell-плагинов

Хост запускает программы плагина (методы rpc, хуки, задачи, события, замены) с окружением:

Переменная Значение
STEER_PLUGIN_ID, STEER_PLUGIN_DIR, STEER_PLUGIN_CONF как у методов rpc (manifest.md): каталог плагина (только чтение) и каталог настроек (пишется, сохраняется всегда; в нём settings.json)
STEER_PLUGIN_STATE рабочий каталог плагина в памяти (<state>/plugin/<id>, steer-api.md): создан закрытым (0700), не переживает перезагрузку. Сюда плагин кладёт временные файлы, замки, накопители кусков — не в /tmp
SPLIFY2_API major splify2-api (1)
SPLIFY2_LIB путь к lib.sh
SPLIFY2_HOST путь к службам хоста (раздел 8)
SPLIFY2_HOOK, SPLIFY2_TASK, SPLIFY2_EVENT имя хука, задачи или события
SPLIFY2_SPEC_TMP у pre_spec_set и heal: файл спеки, который можно переписать
SPLIFY2_NEXT, SPLIFY2_NEXT_FILE у wrap: ответ каркаса

Больше ничего плагину не обещано: ни путей каркаса, ни его переменных-швов, ни его функций (раздел 9).

. "$SPLIFY2_LIB" подключает пять вещей, и их состав — публичная часть splify2-api (удаление или смена смысла — major):

Что Назначение
jshn (libubox) json_init, json_add_*, json_load, json_get_var, json_select, json_dump — разбор запроса и сборка ответа
s2_fail "текст" отказ метода rpc: {"ok":false,"error":"текст"} в stdout и выход с кодом 0 (код не 0 хост считает падением программы)
s2_fail_code КОД "английский текст {имя}" [ИМЯ ЗНАЧЕНИЕ]… отказ метода rpc с кодом: текст error на языке каркаса, code и args — «Тексты для человека». Так отказывают все официальные плагины
s2_t КОД "английский текст {имя}" [ИМЯ ЗНАЧЕНИЕ]… текст для человека (предупреждение, причина, строка отчёта) на языке каркаса: печатает его, не отказывая
s2_setting КЛЮЧ значение настройки плагина (служба settings get, раздел 8): что задал человек, иначе умолчание схемы

s2_fail "текст" остаётся для текста, который уже готов и переводу не подлежит (слова пакетного менеджера, ответ ядра steer дословно). Своя фраза плагина — всегда s2_fail_code.

Файл не печатает и не завершает процесс при подключении.

Тексты для человека

Каркас английский; русский и другие языки — языковые плагины (type: language). Тексты бэкенда (отказы, предупреждения, причины в ответах rpc) переводит хост перед ответом, поэтому панель Andromeda, LuCI-каркас и десктоп видят одно и то же.

  • Вызов. s2_fail_code КОД "Текст по умолчанию {имя}" имя "$значение". Текст по умолчанию — английский, подстановки {имя} — по именам, значения парами «имя значение». Код — область.смысл из латиницы, цифр, точки, дефиса и подчёркивания (lists.too_big), он же ключ словаря.
  • Язык — язык каркаса из настроек (luci.main.lang; S2_LANG в окружении его переопределяет). auto («как в браузере») бэкенд определить не может — тогда английский, а клиент при желании переводит сам по code и args.
  • Словарь — i18n/backend/<язык>.json в каталоге плагина: плоский объект «код → текст» с теми же {имя}. Хост читает словари включённых плагинов (в порядке каталогов; первое найденное слово побеждает); язык pt-br без своего словаря берёт pt. Нет словаря, кода в нём или плагин выключен — английский текст из вызова. Словари каркаса и официальных плагинов несут языковые плагины (lang-ru, lang-en); сторонний плагин кладёт словарь со своими кодами рядом с собой (i18n/backend/ru.json внутри него самого) — отдельный языковой плагин для этого не нужен. Манифест словарь не объявляет: его находят по каталогу, как i18n/core/<язык>.json.
  • Ответ отказа: {"ok":false,"error":"<текст>","code":"<код>","args":{"имя":"значение"}} — args есть всегда (может быть пустым), значения — строки. Клиенту, у которого свой перевод, достаточно code и args.
  • Правила текстов — те же, что у интерфейса: состояние и действие, без технических пояснений. Сообщения журнала (logger, stderr) переводу не подлежат: они для разработчика.
  • Отказы, пришедшие из ядра steer, хост переводит по коду ядра: ключ словаря — steer.<код ядра> (steer.spec.unknown_kind), подстановки берутся из args ядра, в ответе code — тот же ключ (у ответов плагинной части msg), args — как у ядра. Перечень кодов — steer-errors.md. Нет кода у отказа или перевода в словаре — текст ядра идёт в error дословно.

8. Службы хоста

"$SPLIFY2_HOST" <служба> … — единственный путь плагина к тому, что принадлежит каркасу: скачиванию, спеке, настройкам каркаса, применению. Это обычная команда, а не библиотека: плагин на любом языке зовёт её одинаково, а каркас вправе менять всё, что за ней. Ответ — один объект JSON в stdout; код возврата 0 при успехе и 1 при отказе ({"ok":false,"error":"…"}), если ниже не сказано иное. Служба, которой нужны настройки плагина (settings), берёт плагин из STEER_PLUGIN_ID, STEER_PLUGIN_DIR и STEER_PLUGIN_CONF.

Служба Что делает Ответ
fetch URL ФАЙЛ [--timeout СЕК] скачать http(s) в файл: сначала во временный, потом переименование (оборванная загрузка не оставляет обрубок); обход закрытого издателя (зеркала, обходные адреса, туннель по режиму хоста). Срок по умолчанию — 60 с {"ok":true,"note":"…"}; note — каким путём приехало, если не напрямую. Отказ: {"ok":false,"error":"не скачалось","note":"почему по каждому пути"}
fetch-mode [get] режим «качать через туннель» — общий для всего, что скачивает каркас (списки, пакеты ядра, подписки); им владеет хост {"mode":"always|off","out":"имя выхода"}; out пусто, если нет поднятого выхода
fetch-mode set always|off записать режим {"ok":true,"mode":"…"}
paths ресурсы ядра, которые плагин получает по имени, а не зашивает: каталог списков (спека называет списки путями под ним) и программа ядра (srs-read, fit, … — steer-api.md) {"ok":true,"lists":"…","spec_dir":"…","subs_dir":"…","steer":"…"} (spec_dir, subs_dir — с 1.1; тот же ответ у метода paths объекта splify2)
spec get [--applied] [ФАЙЛ] JSON-вид спеки ядра (spec-fields.md): в stdout или копией в файл. --applied — снимок спеки в момент последнего применения (снимка нет — сама спека: «не применено» без снимка не бывает); сравнение двух видов говорит, есть ли неприменённое. Формат файла спеки на диске плагину знать не нужно спека (без ФАЙЛА) или {"ok":true}; кода 1 нет спеки
spec uses ПУТЬ спека ссылается на этот путь (подстрока) только код: 0 — да, 1 — нет или спеки нет
spec check ФАЙЛ проверить спеку ядром, ничего не меняя {"ok":true} или {"ok":false,"error":"слова ядра"}
apply применить сохранённую спеку тем же методом, что кнопка «Применить» (зоны фаервола, хуки pre_apply и post_apply, снимок применённого) ответ метода apply дословно; код 0 — ядро применило, 1 — ядро отвергло (в ответе output его словами: то, что плагин положил на диск перед применением, пора откатить), 3 — применение не состоялось, ядро ничего не видело (оно занято коннектором, хук плагина остановил): откатывать нечего
engine включено ли ядро и работает ли {"ok":true,"known":bool,"enabled":bool,"running":bool}; enabled — стоит автозапуск, running — процесс. При known:false (хост не может ответить) считайте ядро включённым
settings get КЛЮЧ значение настройки плагина по схеме (splify2.settings.schema): записанное человеком, иначе default схемы значение в stdout; код 1 и пусто — нет ни того, ни другого. Ключа нет в схеме — {"ok":false,…}
settings set КЛЮЧ ЗНАЧЕНИЕ записать одну скалярную настройку (строка, число, флаг) в settings.json атомарно, сохранив остальные значения; проверка по схеме: тип, enum, minimum/maximum, pattern. Пустое значение убирает ключ (возвращает умолчание). Объекты и массивы целиком пишет форма каркаса {"ok":true} или {"ok":false,"error":"…"}
state check|export|import КАТАЛОГ настройки каркаса как каталог файлов: spec, sub, sub.<имя>, select, xsteer.<имя>, options (текст дословный). check проверяет присланное (размеры, имена, пути за пределы каталогов настроек, ссылки, спека — ядром) и ничего не пишет; export выгружает; import проверяет, пишет в нужном порядке (подписки и ключи раньше спеки), гоняет хук pre_spec_set на спеке и ничего не применяет. Каталог выгрузки закрыт (umask 077): внутри ссылки узлов и приватные ключи туннелей. Свои списки и данные плагинов сюда не входят export, check: {"ok":true}; import: {"ok":true,"spec":bool,"sub":bool,"subs":N,"xsteer":N,"select":bool,"warn":"…"}
sub list · sub info ИМЯ · sub refresh ИМЯ ответы методов каркаса sub_list, sub_info, sub_refresh дословно: подписки (name, title, kind, present, mtime — время файла узлов, used, остаток в quota, поля плагинов из хука sub_fields), одна подписка, обновление по сохранённой ссылке (туннель перечитывается только при изменившихся узлах). Код 0, если метод ответил объектом; отказ метода — в ответе (ok:false). Имя — латиница, цифры, подчёркивание ответ метода (sub refresh: {"ok":true,"name","changed":bool,"usable":N})
call МЕТОД (запрос — стандартный ввод) вызвать метод каркаса, не заходя в rpcd (у rpcd свой срок вызова, а перебор узлов идёт долго). Разрешены методы узлов и проверок: vless_nodes, hysteria2_nodes, proxy_nodes, vless_probe, hysteria2_probe, proxy_probe, outbound_probe; остальные — отказ (чего нет в списке, добавляют сюда, а не обходят). Ответ метода дословно; код 0, если метод ответил объектом ответ метода; outbound_probe: {"output","code":"ok|no_answer|no_device","state":"слова для человека","ms"} — ветвиться по code
probe ident ВЫХОД · probe geo ВЫХОД признак устройства выхода (номер устройства в системе: при смене узла движок пересоздаёт TUN, и признак меняется — прежний замер уже не о нём) и страна, замеренная через сам выход (curl --interface, адрес проверки — geo_url каркаса). Кэш и сроки — у плагина ident: {"ok":true,"ident":"tun0:12"|"none","curl":false?}; geo: {"ok":true,"output","ip","cc"?,"ms","ident"} или {"ok":false,"error","why":"no_device|no_curl|no_answer"}, код 1
release versions steer|splify2 перечень выпусков продукта с запасными источниками (version.json с трёх адресов, api.github.com, VERSION ветки dist) {"ok":true,"arch"?:"…","current"?:"…","versions":["новые…"],"names":{"версия":"название"},"prerelease"?:"версия","note"?:"…"}; arch — у ядра, current — у splify2
release fetch ПРОДУКТ ВЕРСИЯ ИМЯ ФАЙЛ скачать файл выпуска (steer, splify2): адреса и sha256 из перечня выпусков, затем лестница обхода закрытого издателя (зеркала, туннель по режиму хоста). Версия — цифры и точки, имя — [A-Za-z0-9._+-] {"ok":true,"via"?:"каким путём"} или {"ok":false,"error":"не скачалось","note":"почему по каждому пути"}, код 1
pkg info менеджер пакетов и установленное {"ok":true,"manager":"apk|opkg","ext":"apk|ipk","noarch":"noarch.apk|all.ipk","arch":"архитектура пакетов OpenWrt, пусто — не определилась","steer_min":"наименьшая версия ядра, с которой работает интерфейс","versions":{"steer-core","splify2","luci-app-splify2"}}
pkg install ФАЙЛ… [--replace ИМЯ…] [--restart-rpcd] поставить пакеты одной транзакцией менеджера. Файлы — только в /tmp или в STEER_PLUGIN_STATE плагина; место на флеше проверяется до менеджера; конфликт, где менеджер называет мешающим пакет из --replace, разрешается его снятием; --restart-rpcd — перезапуск rpcd отложенно, после ответа {"ok":true,"output":"вывод менеджера","removed":bool} или {"ok":false,"error":"…","output":"…","removed":bool}, код 1; «мало места» — {"ok":false,"error":"…"}
engine дополнено: busy — ядро ведёт коннектор (podkop, forkop), пакеты ядра ставить нельзя к полям выше добавляется "busy":"кто"
engine modules [--want a,b] · engine settle [модуль…] протоколы ядра, которые нужны спеке (плюс просимые): имена и порядок как у карточки модулей, неизвестное имя — отказ; и довод после установки ядра: протоколы-плагины, автозапуск, спека в spec.yaml, перезапуск службы при спеке modules: {"ok":true,"modules":[…]} или {"ok":false,"error":"неизвестный модуль: …"}, код 1; settle: {"ok":true,"restarted":bool,"ensure_error"?:"…"}
sub quota ИМЯ спросить у панели подписки остаток трафика, ничего не подменяя (ни файл узлов, ни выбор); запомненное читает sub_info {"ok":true,"kind":"url|links|none","name":"…","asked":bool,"why":"…","quota":{"up","down","total","expire","at","since","since_used"}}; why — почему остатка нет, это не отказ. Подписки нет — {"ok":false,…}, код 1
sub title ИМЯ [НАЗВАНИЕ] своё название подписки; пустое снимает своё и возвращает названное панелью или продавцом. До 200 байт, без управляющих знаков {"ok":true,"name":"…","title":"название, которое увидит человек"}
hook backup_sections --ctx ФАЙЛ [--plugin ID] вызвать хук плагина-владельца у плагинов (только backup_sections; контекст — файл: он бывает в мегабайты) {"ok":true,"results":[{"plugin":"id","status":"ok|failed|timeout|bad_answer","response":{…}}]}; response — объект плагина как есть; плагина без хука в списке нет; в безопасном режиме список пуст

Правила служб:

  • Хост не пускает плагин мимо себя, а плагин не должен хотеть. Чего нет в таблице — недостающая часть API: её добавляют сюда, в хост и в заглушку хоста (тесты совместимости), а не обходят.
  • Состояние каркаса записывает только хост, под замком state (общий с spec_set, apply, подписками). Службы state export и state import берут замок сами; программа плагина его не берёт.
  • Служба отвечает быстро или честно. Срок вызова — срок программы плагина (хука, задачи, метода rpc); fetch сам ограничен --timeout.
  • Стабильность. Имя службы, её аргументы, поля ответа и коды возврата — часть API: удаление или смена смысла — major; новая служба, новое поле ответа, новый необязательный аргумент — minor.

9. Граница API

Плагин пользуется платформой только через то, что описано в этом документе, manifest.md и steer-api.md: манифест, хуки, задачи, события, схему настроек и службы хоста. Он не читает и не пишет:

  • файлы каркаса и ядра: /usr/lib/splify2/, /usr/share/splify2/, /usr/libexec/rpcd/splify2, /etc/splify2/, /var/run/splify2/, /var/lib/splify2/, /var/lock/splify2*, /etc/steer/ (спека, подписки, списки, выбор, ключи туннелей), /etc/config/splify2, /etc/init.d/steer, /etc/rc.d/;
  • файлы, которые каркас объявляет своими: common.sh, env.sh, fetch.sh, spec.sh, ext.sh, plugin.sh, fast.sh;
  • переменные-швы каркаса, которыми стенды уводят его пути: SPEC, SUB, SUBS_DIR, LISTS, APPLIED, MANIFEST, UCI_SPLIFY2, XSTEER_DIR, STEER (как переменная каркаса), RPCD_LIB, JSHN_SH, FETCH_SH, SPEC_SH, ENV_SH, EXT_*, PLUGIN_ROOT, PLUGIN_STATE, PLUGIN_CONF_DIR, SPLIFY2_LIBDIR, SPLIFY2_LOCK_*;
  • функции каркаса: call_lock, need_fetch, need_ext, spec_json, spec_put, spec_have, spec_rev, uci_file, uci_commit, private_file, own_file, engine_check, fetch_*, sub_*, plugin_*;
  • uci каркаса (splify2.*).

Свои данные плагин держит в STEER_PLUGIN_CONF (сохраняются) и STEER_PLUGIN_STATE (память), настройки — в схеме, а то, что ему нужно от каркаса, берёт службой хоста. Публичные методы объекта splify2 (ubus call splify2 …, methods.tsv) — тоже API; плагин вправе их звать.

s2p lint ищет обращения к запретному в программах плагина (shell-файлы, файлы с #! и всё в bin/, hooks/, rpc/, lib/): пути, имена файлов, переменные и вызовы функций из списка выше. Имя, которое плагин определяет сам (функция sanitize_list в его lib/), обращением не считается. Находка — предупреждение; s2p lint --official делает её ошибкой — так проверяются официальные плагины (splify2-core-plugins), которые служат образцом для остальных.

10. Версии, совместимость и что пока не действует

  • Ответ plugins_list: host_api (панель, host-api.md), splify2_api (этот раздел), ext_errors.
  • Каждая версия splify2 с явным изменением API (строка в methods.tsv, поле манифеста, хук, протокол, переменная окружения) — новая версия splify2-api и новая версия SDK: строка в tests/compat/matrix.json и каталог заглушки tests/compat/splify2-<версия>/. Старые заглушки остаются: плагин проверяется против всех версий из диапазона своего compat.
  • Принимаются, но не применяются: splify2.luci.views, splify2.luci.tabs, splify2.kinds, splify2.hide, splify2.deny (splify2.luci.interface действует с 1.1). Это точки каркаса LuCI (splify2-luci); их действие появится позже, с осью compat.splify2-luci. Принимать их уже сейчас — чтобы плагин не менял манифест вместе с каркасом.

Тесты совместимости

tests/compat/splify2-<версия>/ — заглушка хоста заданной версии: не копия каркаса, а стенд, который ведёт себя как он по этому документу — таблица methods.tsv версии, права, разбор блока, запуск хуков по фикстурам контекста и службы хоста (host, lib.sh, jshn.sh, tools/: те же команды, ответы и коды возврата, что у настоящего хоста, поверх каталога-песочницы с фикстурами спеки, списков и настроек). Плагин в заглушке видит только то, что видит на роутере: SPLIFY2_HOST, SPLIFY2_LIB, STEER_PLUGIN_* — ни путей, ни швов каркаса. sh tests/compat/run.sh <каталог плагина> [версия] проверяет, что плагин подключится:

  • блок splify2 по схеме, ось compat.splify2-api включает версию, права соответствуют использованию;
  • хуки: каждая программа исполняема, получает фикстуру своего контекста и обязана ответить объектом JSON с булевым ok за срок; transform оставляет после себя годный JSON; хук backup_sections на export отдаёт допустимые имена разделов, на check и restore — объект с булевым ok; support_report — раздел с text; purge — plan массивом строк;
  • методы: у каждого псевдонима и переопределения есть метод rpc или программа; псевдоним не занимает final, fast, frame и чужой moved; переопределение — только frame; не более одного replace на метод внутри плагина;
  • задачи: every и cron разбираются, программа исполняема, имя уникально;
  • события: subscribe и программа;
  • граница API: тот же поиск запретного, что у s2p lint (раздел 9), — плагин, который обходит платформу, в заглушке не заработает, потому что того, в обход чего он ходит, в песочнице нет.

Хост проверяет себя в обратную сторону: CI splify2 прогоняет эти тесты на плагинах splify2-core-plugins против собранной версии каркаса, и каркас не выходит, если сломал плагин из коробки.