Dev/mihomo control

mihomo-control/README.md

@@ -0,0 +1,95 @@
+# Mihomo Control
+
+Monitor and control a Mihomo (Clash Meta) instance right from the Noctalia
+bar: live traffic, proxy mode, proxy-group selection, latency tests and active
+connections. It talks to the Mihomo external controller, which can run on this
+machine (`127.0.0.1`) or on a remote host — just configure the IP, port and
+secret.
+
+## Plugin
+
+| Field   | Value                       |
+| ------- | --------------------------- |
+| ID      | `mdj2812/mihomo-control`    |
+| Entries | Bar widget: `widget`; panel: `panel`; service: `service`; shortcut: `mode` |
+
+## Usage
+
+Add the **Mihomo Control** widget from the Add-widget picker. It shows the
+current proxy mode (rule / global / direct); hover it for the connection
+status, live download and upload rates, connection count and each proxy
+group's current selection. Left-click the widget to toggle the control panel,
+or open it with:
+
+```sh
+noctalia msg panel-toggle mdj2812/mihomo-control:panel
+```
+
+The panel lets you switch the proxy mode (rule / global / direct), restart the
+server, refresh the status, and manage every proxy group. Each group card
+lists all of its members with their latency — sourced from mihomo's health
+checks and refreshed by the group's **Test latency** button. Each card also
+shows an overall latency (the selected member's, or the best tested one) right
+in its subtitle, visible without expanding. Member lists are collapsed by
+default; click a group header to expand it. Click a member to select it; the
+current selection is marked with a dot. Use **Test all** next to the Proxy
+groups heading to run a latency test on every group at once.
+
+Add the **Mihomo: Rule** shortcut from Settings → Control Center shortcuts to
+quickly toggle between rule and global mode.
+
+Before the widget shows anything, enable the plugin's `service` entry — it owns
+all communication with the external controller and streams the traffic data.
+
+## Settings
+
+| Setting             | Type    | Default      | Description                                                                 |
+| ------------------- | ------- | ------------ | --------------------------------------------------------------------------- |
+| Host                | string  | `127.0.0.1`  | Hostname or IP of the Mihomo external controller.                           |
+| Port                | string  | `9090`       | Port of the Mihomo external controller.                                     |
+| Secret              | string  | *(empty)*    | `secret` from your Mihomo config; empty when authentication is disabled.    |
+| HTTPS               | bool    | off          | Use `https://` (external-controller-tls or a TLS reverse proxy).            |
+| Allow insecure TLS  | bool    | off          | Skip certificate verification for self-signed TLS controllers.              |
+| Test URL            | string  | `https://www.gstatic.com/generate_204` | URL used for latency tests; empty uses each group's configured test URL. |
+| Refresh interval    | int     | `2`          | Seconds between status polls (1–60); traffic rates stream in real time.     |
+
+## IPC
+
+The service exposes two IPC events for scripting and debugging:
+
+```sh
+noctalia msg plugin mdj2812/mihomo-control:service all refresh
+noctalia msg plugin mdj2812/mihomo-control:service all cmd '{"op":"mode","mode":"global"}'
+```
+
+`refresh` re-polls version, config, connections and proxy groups. `cmd` accepts
+the same command tables the panel sends (`mode`, `select`, `delay_test`,
+`delay_test_all`, `restart`, `close_connections`, `refresh`).
+
+## Notes
+
+- The plugin only talks HTTP to the configured external controller. It spawns
+  no processes, runs no external commands, and writes no files.
+- The bar widget and card use the Clash cat logo (`icon.png`), the official
+  mascot of the Clash / mihomo project. In the bar widget the cat is tinted by
+  connection status: green online, amber while connecting, red offline; the
+  panel uses the neutral logo next to its own status indicator.
+- The traffic rate uses mihomo's streaming `GET /traffic` endpoint; status,
+  connections and proxy groups are polled every refresh interval.
+- The secret is stored in your Noctalia config and sent as the standard
+  `Authorization: Bearer <secret>` header. It is sent in plain text unless
+  HTTPS is enabled — use HTTPS for remote controllers.
+- **Restart** posts to `/restart`, which re-executes the core; the plugin
+  reconnects automatically once it is back. There is no API endpoint that
+  stops the core — switching the mode to `direct` is the closest equivalent.
+- A latency test where every node fails is reported as *all nodes timed out*:
+  mihomo answers the delay endpoint with HTTP 504 in that case. If that keeps
+  happening, set **Test URL** to an endpoint your network can reach.
+
+## Development
+
+- `service.luau` — headless API backend, publishes `mihomo.*` state.
+- `widget.luau` — bar widget (rates + tooltip).
+- `panel.luau` — control panel.
+- `shortcut.luau` — rule/global mode toggle.
+- `translations/` — user-facing strings.