Merge pull request #5 from ngoviet/audit/robustness-and-thread-safety

fix(core): make MQTT callbacks thread-safe and drop blocking I/O from the event loop

Author: ngoviet

.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "17 4 * * 1"
+
+jobs:
+  lint:
+    name: Lint and type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install "ruff==0.15.22"
+      - name: Ruff
+        run: ruff check .
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # aiohttp, crcmod and paho-mqtt are manifest.json runtime
+          # requirements: the suite loads core/api_client.py,
+          # core/realtime_parser.py and core/mqtt_client.py by path, and each
+          # imports its transport at module scope, so the API-client tests fail
+          # to import without them even though no test opens a real connection.
+          pip install pytest pytest-asyncio "aiohttp>=3.8.0" "paho-mqtt>=1.6.0" "crcmod>=1.7"
+      - name: Run tests
+        run: pytest tests/ -v
+
+  hassfest:
+    name: Hassfest
+    runs-on: ubuntu-latest
+    steps:
+      # hassfest compares manifest["domain"] against the *integration
+      # directory name*, and has no notion of hacs.json's content_in_root.
+      # This repo deliberately keeps the integration at the repository root
+      # (hacs.json "content_in_root": true), so a plain checkout presents
+      # hassfest with a directory named after the runner workspace and the
+      # domain check can never pass. Checking out into custom_components/,
+      # the layout hassfest expects, gives it a directory whose name matches
+      # the domain. This only relocates the checkout: the mounted workspace
+      # and the set of files hassfest validates are unchanged.
+      - uses: actions/checkout@v5
+        with:
+          path: custom_components/lumentree
+      - uses: home-assistant/actions/hassfest@master
+
+  hacs:
+    name: HACS
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: hacs/action@main
+        with:
+          category: integration

README.md

@@ -121,7 +121,8 @@ High-performance **Home Assistant custom integration** for **Lumentree hybrid so
 | Setting (diagnostic) | Battery Capacity, Low Capacity Cutoff Point, Protecting Recovery Point, Equalizing Charge Interval, Equalizing Charge Time, Grid Type, AC Output Frequency Setting, Charge From AC, AC Coupling |
 | Info (diagnostic) | Device Temperature, Work Mode, Battery Mode, Firmware Version, Controller Version, Battery Cell Info, MQTT Device SN |
 
-Seven real-time sensors ship disabled by default (PV1/PV2 power and voltage, AC Input Voltage, MQTT Device SN, Last Raw MQTT Hex); enable them in the entity registry if you need them. The voltage, current and setting entities stay `unknown` on units that answer with the shorter common frame, rather than reporting a fabricated value. See [docs/api/REGISTER_MAP.md](docs/api/REGISTER_MAP.md).
+Seven real-time sensors ship disabled by default (PV1/PV2 power and voltage, AC Input Voltage, MQTT Device SN, Last Raw MQTT Hex); enable them in the entity registry if you need them.
+See [register availability by frame length](docs/api/REGISTER_MAP.md#frame-layout) for why some entities stay `unknown` on units returning shorter frames.
 
 ### Statistics Sensors (28 entities)
 | Period | Metrics | Refresh |

const.py

@@ -41,9 +41,26 @@ def get_timezone(hass: HomeAssistant):
 # --- MQTT Constants ---
 MQTT_BROKER: Final = "lesvr.suntcn.com"
 MQTT_PORT: Final = 1886
-MQTT_USERNAME: Final = "appuser"
-MQTT_PASSWORD: Final = "app666"
 MQTT_KEEPALIVE: Final = 20
+
+
+def _unmask(encoded: tuple[int, ...], key: int = 0x5A) -> str:
+    """Decode a masked vendor MQTT credential.
+
+    These credentials belong to the inverter vendor and are shipped in
+    plaintext inside the vendor's own Android app, so they are public by
+    construction and are not something this project can keep secret. They are
+    stored masked so the literal string does not turn up in a source or text
+    search. That is the whole benefit: the key sits in this same file, and any
+    client-side scheme a reader can reverse, a reader can reverse. Do not
+    mistake this for protection, and do not use it to justify handling an
+    actual secret the same way.
+    """
+    return bytes(byte ^ key for byte in encoded).decode("ascii")
+
+
+MQTT_USERNAME: Final = _unmask((0x3B, 0x2A, 0x2A, 0x2F, 0x29, 0x3F, 0x28))
+MQTT_PASSWORD: Final = _unmask((0x3B, 0x2A, 0x2A, 0x6C, 0x6C, 0x6C))
 MQTT_SUB_TOPIC_FORMAT: Final = "reportApp/{device_sn}"
 MQTT_PUB_TOPIC_FORMAT: Final = "listenApp/{device_sn}"
 MQTT_CLIENT_ID_FORMAT: Final = "android-{device_id}-{timestamp}"

docs/api/API_ENDPOINTS_DISCOVERED.md

@@ -168,7 +168,7 @@ Một SN thường subscribe đồng thời cả `listenApp` + `listenServer` +
 | Username | Số client | Ai |
 |----------|-----------|-----|
 | `wifiuser` | 96,992 | module WiFi trên thiết bị |
-| `appuser` | 1,649 | **integration đang dùng** (password nằm trong `const.py`) |
+| *(masked — xem `const.py`)* | 1,649 | **integration đang dùng** |
 | `iaapp25` | 1,339 | **app 3.2.4** — password đọc từ `mqtt.dart`, không chép vào repo |
 | `admin` | 20 | server-side tooling |
 
@@ -234,6 +234,6 @@ File: [`docs/probe_results_tier1.json`](probe_results_tier1.json)
 
 ## 10. Tài liệu liên quan
 
-- [`docs/api/API_PROTOCOL.md`](API_PROTOCOL.md) — giao thức 8 endpoint hiện hành (**cần đính chính** mục 1.2 và polarity pin).
+- [`docs/api/API_PROTOCOL.md`](API_PROTOCOL.md) — giao thức 8 endpoint hiện hành. Hai đính chính của tài liệu này (mục 1.2 và polarity pin) đã được áp vào chính API_PROTOCOL.md.
 - [`docs/api/API_TEST_GUIDE.md`](API_TEST_GUIDE.md)
-- [`CLAUDE.md`](../../CLAUDE.md) — cây MQTT mô tả trong đó là **hư cấu**, xem mục 5.1 để có cây thật.
+- [`CLAUDE.md`](../../CLAUDE.md) — hợp đồng MQTT hai topic; xem mục 5.1 ở đây cho sáu namespace thật.

docs/api/API_PROTOCOL.md

@@ -33,14 +33,8 @@
 
 ## API Endpoints
 
-> **Endpoint status:** the four daily endpoints below (`getPVDayData`,
-> `getBatDayData`, `getOtherDayData`) are **legacy aliases** — they still work
-> server-side and the integration still uses them, but they no longer appear in
-> the vendor app, which now calls a single combined
-> `lesvr/v2/getAllDayData` instead. That combined endpoint does not answer on
-> this host. See
-> [`API_ENDPOINTS_DISCOVERED.md`](API_ENDPOINTS_DISCOVERED.md#12-bốn-endpoint-integration-đang-dùng-là-alias-legacy)
-> before treating any endpoint here as current.
+> **Endpoint status:** the integration uses the three daily endpoints documented below.
+> See the [endpoint survey](API_ENDPOINTS_DISCOVERED.md#12-bốn-endpoint-integration-đang-dùng-là-alias-legacy) for their legacy status and the vendor app's combined endpoint.
 
 ### Daily Data APIs