Версия 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:
- блок
splify2манифеста:priority,hooks,tasks,events,methods,settings(и зарезервированныеluci,kinds,hide,deny); - хуки каркаса: список, порядок, протокол, политика отказа;
- периодические задачи вместо строк crontab в postinst;
- события ядра: одна подписка на роутер, раздача плагинам;
- псевдонимы и переопределения методов объекта rpcd
splify2, таблицаmethods.tsv,final; - защита: права, безопасный режим, что бывает с упавшим хуком;
- окружение программ плагина и библиотека для shell-плагинов (
SPLIFY2_LIB); - службы хоста (
SPLIFY2_HOST): скачивание, спека, настройки каркаса, применение, настройки плагина; - граница API: что плагин не трогает и как это проверяет
s2p lint; - версии, тесты совместимости и что пока не действует.
Что здесь не описано: интерфейс панели (host-api.md), ядро (steer-api.md),
методы самих плагинов (rpc в manifest.md).
Решения владельца, на которых стоит раздел: плагины splify2 могут урезать, менять и переопределять логику каркаса (хуки, замена обработчиков, скрытие и замена экранов); SDK один на steer и splify2; у каждой версии хоста с явными изменениями API — новая версия SDK и тесты совместимости.
Поле верхнего уровня рядом с steer, rpc, ui. Нужна ось compat.splify2-api; плагин с блоком без неё не
применяется (s2p lint отказывает раньше).
| Поле | Что |
|---|---|
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).
Хост собирает реестр (/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: один вызов на весь ответ |
добавить к строке каждой подписки свои поля (расписание, пометки); каркас их пересылает как есть |
Программа получает на 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) и получает ответы плагинов. Так формат архива остаётся у плагина, а каркас не знает, что
архив существует.
| Режим | Ответ ok:false |
Ответ warn |
|---|---|---|
veto |
отказ операции словами error |
предупреждение |
warn |
предупреждение словами error |
предупреждение |
transform |
предупреждение; файл, который успел переписать плагин, остаётся | предупреждение |
observe (умолчание) |
только журнал | только журнал |
Политика отказа. Хук, который упал (код не 0), не ответил за срок или ответил не объектом JSON, не
останавливает ничего: строка в журнале (logger -t splify2-ext) и предупреждение в ответе
(«плагин X: хук Y не ответил за срок»). Плагин не должен уметь «кирпичить» применение случайно. Явное
"critical": true у хука меняет это: упавший, зависший или ответивший не по форме хук такого плагина
останавливает операцию; карточка плагина показывает это как право.
Хуки до операции идут под замком state (общий с spec_set, apply, подписками, архивом), потому что трогают
спеку; хук может вызывать методы каркаса — вложенный вызов замок уже держит родитель.
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), а не задачей.
events подписывает плагин на события ядра (steer-api.md, «События»). Плагины не подписываются сами
(у каждой подписки своя очередь событий в демоне): хост держит одну службу splify2-events
(steer ctl subscribe) и раздаёт события. Служба поднимается, когда хотя бы у одного включённого плагина есть
events, и останавливается, когда последнего не осталось. Соединение оборвалось — подписка возобновляется
через несколько секунд; пропущенные события не повторяются.
subscribe — имена событий (applied, switched, failed, helper-down, …) или *. Программа prog
получает на stdin {"api": 1, "event": {<строка события ядра как есть>}}, ответа не требуется, код и срок
(timeout_s, 10 с) только в журнал. События неизвестных имён хост пропускает: список растёт в той же версии.
Все методы объекта 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 меняет первое на отказ.
- 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 не та, имя занято, программы нет или она не исполняемая.
Хост запускает программы плагина (методы 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дословно.
"$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.
Плагин пользуется платформой только через то, что описано в этом документе, 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), которые служат образцом для остальных.
- Ответ
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 против
собранной версии каркаса, и каркас не выходит, если сломал плагин из коробки.