Add GNOME Shell extension showing sing-box status via the Clash API

2026-07-18 15:25:26 +03:00
commit 629e031845
10 changed files with 893 additions and 0 deletions
@@ -0,0 +1,84 @@
+# sing-box Status — расширение для GNOME Shell
+
+Показывает статус прокси [sing-box](https://sing-box.sagernet.org/) в верхней панели
+GNOME, используя встроенный **Clash API**.
+
+## Что показывает
+
+**В панели (компактно):**
+
+- монохромный индикатор-кружок — залит, когда API доступен и прокси жив; полый
+  (тускнее), когда API недоступен. Цвет берётся из цвета текста панели, поэтому
+  индикатор одинаково читается на тёмной и светлой теме;
+- имя активного outbound (текущий узел Selector-группы);
+- текущую скорость, например `↓2.4M ↑120k`.
+
+**В выпадающем меню (подробности):**
+
+- `sing-box · Active / Unreachable`;
+- полная скорость (`↓ 2.4 MB/s   ↑ 120 KB/s`);
+- каждая Selector-группа отдельным подменю — выбор узла **переключает активный
+  outbound** (текущий помечен точкой, рядом — последняя измеренная задержка, если она
+  есть). Пункт **Test latency** в подменю запускает ручной замер задержки всех узлов
+  группы и обновляет значения на месте (меню при этом не закрывается);
+- число активных соединений с разбивкой по outbound;
+- **Open dashboard** (MetaCubeXD или ваш дашборд Clash) и **Settings**.
+
+## Требования
+
+- GNOME Shell 45–48.
+- sing-box с включённым `experimental_clash_api`:
+
+```jsonc
+{
+  "experimental": {
+    "clash_api": {
+      "external_controller": "127.0.0.1:9090",
+      "secret": "ваш-секрет",
+      "external_ui": "..."        // опционально, для дашборда
+    }
+  }
+}
+```
+
+## Установка (из исходников)
+
+```sh
+UUID="sing-box-status@anwinged.github.io"
+ln -s "$PWD" "$HOME/.local/share/gnome-shell/extensions/$UUID"
+glib-compile-schemas schemas/
+# На Wayland: выйдите из сессии и войдите снова, чтобы shell зарегистрировал
+# новое расширение, затем:
+gnome-extensions enable "$UUID"
+```
+
+Откройте **Settings** из меню (или `gnome-extensions prefs "$UUID"`) и задайте:
+
+- **API URL** — например `http://127.0.0.1:9090` (ваш `external_controller`);
+- **Secret** — ваш `clash_api.secret`;
+- **Dashboard URL** — например `http://127.0.0.1:9091`.
+
+## Как это работает
+
+Каждые *N* секунд (по умолчанию 2) расширение опрашивает две точки Clash API:
+
+- `GET /connections` — накопительные `downloadTotal` / `uploadTotal` (скорость — их
+  приращение за интервал) и список активных соединений с цепочками outbound;
+- `GET /proxies` — Selector-группы, их текущий узел и история задержек по узлам.
+
+Переключение outbound выполняется запросом `PUT /proxies/{group}` с телом
+`{"name": "..."}`. По умолчанию расширение не шлёт активных замеров задержки —
+показываются только те, что sing-box измерил сам. Ручной замер (пункт **Test latency**)
+выполняется через `GET /proxies/{name}/delay` только по нажатию.
+
+Сетевой слой (авторизация, разбор ответов, переключение outbound) проверен на живом
+API sing-box 1.13.13.
+
+## Файлы
+
+- `extension.js` — точка входа, добавляет кнопку в панель.
+- `lib/indicator.js` — виджет панели, меню, цикл опроса, отрисовка.
+- `lib/clashApi.js` — асинхронный клиент Clash API на libsoup 3.
+- `lib/format.js` — форматирование байтов и скорости.
+- `prefs.js` — настройки на Adwaita.
+- `schemas/` — схема GSettings.