Skip to content

Latest commit

 

History

History
273 lines (216 loc) · 21.4 KB

guide.md

File metadata and controls

273 lines (216 loc) · 21.4 KB

Как написать плагин

Путь от пустого каталога до выпуска. Спецификации — manifest.md, s2p.md, steer-api.md, steer-abi.md, host-api.md, index.md; здесь — что делать руками и в каком порядке.

1. Что писать

Хотите Берите Шаблон Машинный код
вид выхода или протокол, службу, подкоманду steer программа-помощник — процесс под супервизором steer, говорит с ядром строками событий helper да (C) или скрипт
то, чему нужен горячий путь в процессе ядра: правила emit, health без fork, устройства через netlink .so в steerd по steer-abi so да, только C
свой экран в панели: карточка плагина во вкладке «Плагины», плитка, значок интерфейс на @splify2/plugin-api ui нет
цвета панели тема: только переменные --sp-* и --an-* theme нет
язык панели перевод: словарь строк хоста lang нет

Начинайте с программы: она не может уронить steerd, ею можно пользоваться на любом языке, и она не привязана к лицензии ядра. .so берите, когда программа не подходит. Один плагин может совмещать: у recheck есть служба, правила nft, методы rpc и интерфейс.

2. Установка SDK

sh build.sh              # bin/s2p — один файл, Go 1.21+, без зависимостей
export PATH="$PWD/bin:$PATH"   # дальше в примерах просто `s2p`
s2p version

Для C нужен zig 0.13: zig в PATH, или S2P_ZIG=<путь>, или docker с образом steer-builder:wolfssl (S2P_BUILDER_IMAGE — другой образ). С docker s2p монтирует нужные каталоги и идёт от вашего пользователя, файлов root не остаётся. Сборка для интерфейса — Node 20.19+ и npm. SDK OpenWrt не нужен нигде.

3. Заготовка, ключ, сборка

s2p new helper ./myplug --name "Мой плагин"    # id — имя каталога: [a-z0-9][a-z0-9-]*
cd myplug
s2p keygen -o dev                              # dev.sec (секрет, 0600), dev.pub
s2p lint .
s2p build . --key dev.sec                      # dist/<id>-<версия>-<арх>.s2p, по архиву на архитектуру
s2p build . --arch x86_64 --key dev.sec        # одна архитектура
s2p verify dist/myplug-0.1.0-x86_64.s2p --pub dev.pub

Что делает build: читает plugin.json, проверяет его до компиляции, запускает шаги из s2p.json (cc — компилятор, ui — сборка интерфейса), собирает дерево, проверяет его ещё раз уже вместе с машинным кодом, пишет MANIFEST с SHA-256, подписывает и пакует. Что попадает в архив: всё из каталога проекта, кроме s2p.json, package*.json, tsconfig.json, vite.config.*, README*, src/, ui-src/, build/, dist/, node_modules/ и точечных каталогов; ещё исключения — "exclude" в s2p.json. Бит x файла становится режимом 0755, остальное — 0644; владелец, группа и время — нули.

Сборка повторяема: тот же проект и тот же zig дают те же байты архива. Расхождение на другой версии zig или zlib не ошибка плагина, но индекс (s2p index) его заметит: см. раздел 10.

Без ключа: --unsigned (в MANIFEST.sig пустой файл). На роутере такой архив ставится только из файла и помечается unsigned (s2p.md, «Без подписи»).

s2p.json

Файл SDK, в архив не попадает:

{
  "cc": [
    { "kind": "helper", "out": "bin/myplug", "src": ["src/main.c"], "evline": true,
      "requires": ["net1"], "link": ["vendor/libs2p-net.so.1"],
      "defs": ["PLUGIN_ID=\"{id}\"", "PLUGIN_VERSION=\"{version}\""] }
  ],
  "ui": { "dir": ".", "cmd": ["npm", "run", "build"], "out": "ui" },
  "exclude": ["docs"]
}

cc[].kind — helper (статическая программа musl) или so; evline добавляет библиотеку событий SDK; requires и link — для зависимости от плагина-библиотеки (раздел 5); {id} и {version} в defs подставляются из plugin.json, чтобы версия не жила в двух местах. ui.cmd получает каталог результата в S2P_UI_OUT; всё, что он туда положит, ляжет в архив под ui.out.

Заготовки: helper, so, ui, theme, lang. Что получилось, проверяют s2p lint . и тест совместимости (раздел 11): они ловят расхождение с ядром и панелью до роутера. На роутере с ядром steer 2.1 архив без подписи ставится так: steer plugin install --file dist/myplug-0.1.0-<арх>.s2p --unsigned.

4. Минимальный манифест

{
  "schema": 1,
  "id": "myplug",
  "version": "0.1.0",
  "name": "Мой плагин",
  "license": "MIT",
  "compat": { "steer-api": "^1.0" },
  "arch": ["x86_64", "aarch64_cortex-a53"],
  "steer": { "commands": [ { "name": "myplug-hello", "prog": "bin/myplug" } ] }
}
  • compat — только оси, которые вы используете: steer-api (программы, хуки, подкоманды, nft), steer-abi (.so), host-api (интерфейс, темы, переводы). Диапазон в синтаксисе npm; minor добавляет, major ломает. Ядро или панель с меньшей версией плагин не поставит и назовёт числа.
  • arch — "all" (нет машинного кода) или список пакетных архитектур OpenWrt; s2p arches печатает десять поддерживаемых. Один .s2p — одна архитектура.
  • permissions — что плагин делает; права сверяет s2p lint: файлы nft требуют nft, pre_apply и expand — spec.transform, steer.so — so, requires.system — system-packages, каждый путь keep — fs:<путь>. У официального и стороннего репозитория права одинаковы: подпись — доверие автору, а не песочница.
  • Имена глобальны: id, виды, подкоманды и службы занимают одно пространство на роутере. Подкоманды ядра (apply, status, plugin …) заняты.
  • Версии осей. SDK 1.6.0 говорит steer-api 1.5, steer-abi 1.0, host-api 1.0, splify2-api 1.3 (s2p держит их в одном месте, строки — в tests/compat/matrix.json). Пишите самую раннюю ось, которой хватает: ^1.0, а если нужно новое — его версию (steer.links — ^1.3, splify2.luci.interface — splify2-api ^1.1).
  • Тексты для человека — состояние и действие, без технических пояснений. Переводы — i18n/<язык>.json, ключи plugin.name, plugin.description, command.<имя>.help, kind.<имя>.label.

5. Программа-помощник

Шаблон helper. Ядро запускает программу по steer.kinds[].helper на каждый выход вида (или по steer.services[] один раз на роутер), со словами из argv манифеста и подстановками {out}, {conf}, {mark}, {queue0} и другими (steer-api.md, раздел 1.3).

Правила:

  1. Первым событием — hello с api, версией плагина и id; иначе ядро погасит процесс.
  2. Дальше — up (выход готов; watch: 1 — помощник сам судит о здоровье) и down с причиной для человека. События — по одной строке JSON в дескриптор STEER_EVENT_FD (3); для этого libs2p-evline (include/s2p/evline.h, ключ evline в s2p.json).
  3. Всё, что нужно знать о выходе, лежит в файле {conf} (ключи вида, устройство, метка, таблица, метка сокетов). Спеку помощник не читает.
  4. Код 0 — удача, 2 — отказ, причина — последняя непустая строка stderr; stderr идёт в журнал ядра.
  5. На SIGTERM выйти; при гибели steerd приходит SIGTERM по PR_SET_PDEATHSIG.

Схема ключей вида (kinds/<вид>.schema.json) — подмножество JSON Schema (manifest.md, «Ключи вида»); x-secret: true прячет значение из status и журнала, x-path разворачивает путь.

Библиотеки. Стек туннелей и TLS живут в плагине-библиотеке net1, одной на роутер. Программа, которая её использует, пишет "requires": {"plugins": {"net1": "^1.2"}} и собирается с requires: ["net1"] и link: ["…/libs2p-net.so.1"] в s2p.json: загрузчик musl и RUNPATH $ORIGIN/../../net1/lib ставит s2p cc. s2p lint проверяет связку libs2p-<имя>.so.<N> ↔ плагин <имя><N> и RUNPATH.

6. .so в steerd

Шаблон so. Подключайте steer/plugin.h (он вшит в s2p) и экспортируйте ровно один символ steer_plugin_v1_entry; всё нужное от ядра приходит таблицей steer_host_v1 в init. Следствия:

  • с libsteer* не связываться (s2p lint отвергает DT_NEEDED);
  • функции не блокируют: сеть и имена — через host->http, host->resolve, дескрипторы — через цикл демона;
  • падение .so роняет steerd: три падения за десять минут — плагин отключён;
  • обновление .so — только перезапуском службы steer (musl не выгружает библиотеки);
  • лицензия совместима с GPL-3.0 ядра; закрытому плагину — только программа;
  • манифест: steer.so.path, compat.steer-abi, право so, license.

s2p cc --kind so собирает с -fPIC -fvisibility=hidden -Wl,-z,defs, файлом версий и SONAME по имени файла. Проверка: file показывает разделяемую библиотеку нужной архитектуры, readelf --dyn-syms — один экспорт.

7. Интерфейс

Шаблон ui. Модуль ES ui/index.js панель загружает import() и зовёт activate(host); главный слот — host.slots.pluginSettings (карточка плагина во вкладке «Плагины»). Типы — @splify2/plugin-api:

npm install -D @splify2/plugin-api preact vite typescript

vite.config.ts:

import { defineConfig } from 'vite'
import { splify2Plugin } from '@splify2/plugin-api/vite'
export default defineConfig({ plugins: [splify2Plugin()] })
  • Один preact на всех: splify2Plugin() подменяет preact, preact/hooks, preact/jsx-runtime, react, react-dom прокладкой на globalThis.__splify2_host.preact. s2p lint не пропускает модуль с отдельным import из preact.
  • Манифест: ui.entry и ui.css (ui/index.js, ui/style.css), compat.host-api. Стили панели живут в shadow root: CSS плагина — только через ui.css или host.styles; цвета — переменные темы.
  • rpc: методы объявляются в rpc.methods (access: read|write), обработчик — программа или скрипт: <prog> <метод>, параметры — JSON в stdin, ответ — JSON в stdout, код 0. Вызов — host.rpc.call.
  • Строки: host.i18n.t('ключ') из i18n/<язык>.json; нет в языке человека — ru, нет и там — ключ.

s2p build запускает ui.cmd один раз и кладёт результат в каждый архив.

8. Тема и перевод

Тема (theme): type: theme, arch: all, файл themes/<имя>.json — {"name", "light", "dark"?} из переменных --sp-* и --an-*. Кода нет; --sp-bleed, --sp-inset-l, --sp-inset-r ставит панель.

Перевод (lang): type: language, id — lang-<код>, словарь панели — i18n/host/<код>.json (плоский объект «раздел.имя → строка», подстановки {0}); i18n.host.<код>.host — каким версиям словаря панели он подходит. s2p new lang ./lang-fr --name Français переименует файлы и подставит код.

9. Что проверяет s2p lint

Что Примеры отказов
схема plugin.json нет compat, неизвестное значение, .. в пути
файлы программа из манифеста не найдена или не исполняемая; пропавший словарь, тема, схема ключей
права nft, spec.transform, so, keep без нужного права
совместимость диапазон не разбирается; вид без оси steer-api; .so без steer-abi; ui без host-api
подстановки неизвестная {…}; {queue1} при resources.queues: 1
nft на верхнем уровне не set, map, chain <слот>; неизвестный слот
типы library без libs и id без major; theme с кодом; language без i18n.host
тексты предупреждение о технических словах в словарях (JSON, stderr, socket, 0x…)
машинный код ELF не той архитектуры; не тот загрузчик; машинный код при arch: all; DT_NEEDED libsteer*; libs2p-* без зависимости или RUNPATH; лишний экспорт .so; лицензия .so несовместима с GPL
интерфейс отдельный import preact; нет activate (предупреждение)
граница API в программах плагина — пути, файлы, переменные и функции каркаса вместо служб хоста (splify2-api.md, раздел 9): предупреждение, с --official — отказ

s2p lint понимает каталог проекта, готовый .s2p и одиночный plugin.json (только схема). --strict — предупреждения тоже отказ; --official — плагин официального репозитория: обращение к внутренностям каркаса (граница API) тоже отказ.

10. Подпись, ключи, выпуск

Подпись — Ed25519 в формате usign: s2p keygen пишет пару без пароля (как usign -G -N); ключи с паролем s2p не читает. Номер ключа — 16 знаков hex. Закрытые ключи в деревьях не хранятся: в CI это секреты.

  • Ротация: на время перехода архив подписывают двумя ключами — s2p sign x.s2p --key новый.sec --add (или --key старый.sec --key новый.sec в build). Верна любая подпись доверенного неотозванного ключа.

  • Репозиторий: подписанные архивы одной папкой, затем

    s2p index dist -o repo --repo mine --name "Мои плагины" --mirror https://example.org/plugins/ \
        --pub dev.pub --key index.sec --expires 30d [--meta meta.json]

    Индекс сливается с прежним (repo/index.json): версии остаются, пока их не убрали (--drop id@версия); отзыв — --yank id@версия --why "…" [--security]. --meta — default, key_role, tags, changelog. Разложить repo/ на хостинг; срок индекса — --expires, переподписывать нужно раньше его конца (официальный репозиторий — раз в неделю).

  • Проверка: s2p verify repo/index.json --pub index.pub --base repo — подпись, схема, срок, sha256 и размер каждого архива.

  • Человек подключает репозиторий адресом и ключом (steer plugin repo add), интерфейс говорит, что он не официальный.

11. Тест совместимости

Заглушки хостов повторяют проверки ядра и splify2 и запускаются на каталоге плагина (у плагина с машинным кодом — после s2p build, на собранном дереве). Код возврата 0 — плагин подключится; иначе строки FAIL с причиной.

sh tests/compat/run.sh --steer ./myplug          # ядро steer 2.1: ось steer-api, хуки видов, помощник, службы, steer.links
sh tests/compat/run.sh ./myplug 1.3              # splify2 с splify2-api 1.3: хуки, задачи, события, методы
sh tests/compat/run.sh ./myplug 1.1              # он же на хосте 1.1: хуки, задачи, события, методы, host-api
sh tests/compat/run.sh ./myplug 1.0              # он же на хосте 1.0 (плагину ^1.0 нужно, чтобы работал и там)
s2p lint --official ./myplug                     # граница API: плагин не лезет в внутренности каркаса

Ось, которой нет у плагина, не проверяется; ось не из диапазона — FAIL compat.<ось>. Образцы — examples/: splify2-hooks (хуки, задача, события, метод), splify2-interface (замена главного экрана) проходят всё выше; остальные образцы — только манифест (по схеме: s2p lint examples/vless/plugin.json).

12. Стенд

sh tests/run.sh          # lint, build, sign, verify, index на шаблонах; C под 4 архитектуры
FULL=1 sh tests/run.sh   # C под все 10

Он же — образец: как собрать враждебный архив (tests/craft.py), как проверить .so (file, readelf), как исполнить помощника под qemu-aarch64.

Частые отказы

Сообщение Причина
нужен --key … (или --unsigned) build без ключа
такого ключа среди доверенных нет verify без --pub ключа, которым подписан архив
…не сходится — файл изменён или подпись испорчена MANIFEST.sig не от этого MANIFEST
zig не найден, а образа … нет нет компилятора для C: поставьте zig 0.13 или соберите образ steer-builder
DT_NEEDED libsteer… .so связан с библиотекой ядра: берите всё из таблицы host_v1
путь …: содержит .. в архиве путь выводит из каталога плагина
файла … нет в плагине путь в манифесте не существует (и s2p.json его не создаёт)