homebridge-roborock-matter 3.25.0 → 3.26.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 3.26.0
+
+**The refused route answered, and what it said was that the route exists — just not for the verb we asked with. So this release asks it which verb it does take, without attempting one.**
+
+3.25.1 taught the schedule probe to keep the body of a refusal. Issue #22's reporter ran it, and the body was worth the release:
+
+```
+GET user/scene/<id> → 400
+{"code":"servlet.exception","msg":"Request method 'GET' is not supported", ...}
+```
+
+That is not "no such route". A servlet says that sentence when the path _is_ mapped and the method is not — so the singular scene resource exists, and something other than GET reaches it.
+
+Two releases have now established _what_ a HomeKit switch over these schedules would have to change: the `enabled` flag inside a scene's TIMER trigger, not the scene's own. Neither established _where_ to send it, and this thread has twice refused to guess, because a guessed write endpoint against somebody's live account does not fail politely.
+
+There is a way to ask a resource which methods it accepts without attempting any of them, and it is what OPTIONS is for. It is a safe method, it carries no body, and it cannot alter a schedule. When the probe finds a timer-driven scene, it now asks that one scene resource the question and records the `Allow` header that answers it.
+
+The probe was also dropping that header — on refusals and successes alike — which is the same defect 3.25.1 fixed one field over: a refusal saying "GET is not supported" names the verb that failed and not the ones that would work, and `Allow` is where a servlet puts those. It is now kept wherever it appears.
+
+Exactly one header is taken, deliberately. A response header block carries session material, and a diagnostic somebody pastes into a public issue must not leak their cookie to measure a verb.
+
+The constraints are otherwise unchanged and one of them is now stated more precisely: safe methods only — GET and OPTIONS — debug logging only, once per robot per session, cannot throw, credential-shaped fields redacted. Still a diagnostic, still not a feature.
+
+## 3.25.1
+
+**The schedule probe kept the status code of a refused route and threw away the server's explanation of it — so the route it was built to measure came back saying nothing.**
+
+3.25.0 shipped a read of the singular cloud scene resource, on the reasoning that a 200 makes it a candidate for a later write and a 404 rules it out for free. Issue #22's reporter ran it, and the answer was neither: `400`.
+
+That is the one outcome the probe had nothing to say about. A 404 means there is no such resource. A 400 means the server routed the request and then rejected it — which is a statement about the request, not about whether the route exists. Whether it means "unknown route", "wrong method" or "that scene is not yours" lives in the body the server sent back, and axios flattens every one of those into the same sentence: `Request failed with status code 400`.
+
+The probe recorded that sentence and dropped the body. So a measurement that took a release to ship, and somebody else's live account to run, produced a number and no reading.
+
+A refused route now keeps what the server actually said, in the log and in the diagnostics record, under the same compaction and redaction a successful answer already gets — an error envelope is no more ours to print blindly than a normal one. This holds for every route the probe reads, not just the one it was found on.
+
+No behaviour outside the diagnostic changes, and the probe is still debug-only, GET-only, once per robot per session, and unable to throw.
+
 ## 3.25.0
 
 **The schedule probe now measures whether a cloud schedule is a resource the plugin could ever write to.**

package/README.md

@@ -37,7 +37,7 @@ This is the most feature-packed, most thoroughly engineered Roborock plugin for
 - 📍 **See where it's cleaning — live.** Apple Home shows _"Cleaning — Kitchen"_ with the room the robot is actually inside, updating as it moves from room to room. Works even for cleans started from the robot's button or the Roborock app. No other Homebridge plugin does this.
 - 🧭 **One robot, one tile — and as many robots as you own.** Sign in once and your whole fleet comes along: every vacuum on your account appears as its own clean, native accessory in Apple Home. No clutter of fake fans and helper switches, and rooms appear with the names you gave them in the Roborock app.
 - ⚡ **Fast and reliable.** Commands go directly to the robot over your own network whenever possible, with the Roborock cloud as automatic backup — and built-in diagnostics in the settings if you ever want to look under the hood.
-- 🛡️ **Verified by Homebridge.** Reviewed and endorsed by the Homebridge team. 1838 automated tests, zero known vulnerabilities, no analytics, and a startup designed to never crash your Homebridge — even when your Wi-Fi or the Roborock cloud has a bad day.
+- 🛡️ **Verified by Homebridge.** Reviewed and endorsed by the Homebridge team. 1854 automated tests, zero known vulnerabilities, no analytics, and a startup designed to never crash your Homebridge — even when your Wi-Fi or the Roborock cloud has a bad day.
 
 ## Features
 
@@ -258,7 +258,7 @@ The complete path — robot → plugin → Homebridge → matter.js store — wa
 
 ## Contributing
 
-Model reports, diagnostics exports, and pull requests are very welcome. The codebase ships with 1838 tests (protocol fixtures verified against the [python-roborock](https://github.com/Python-roborock/python-roborock) reference), strict TypeScript checking, and CI across Node 22/24 × Homebridge 1.11/2.x — `npm test` before you push and you're set.
+Model reports, diagnostics exports, and pull requests are very welcome. The codebase ships with 1854 tests (protocol fixtures verified against the [python-roborock](https://github.com/Python-roborock/python-roborock) reference), strict TypeScript checking, and CI across Node 22/24 × Homebridge 1.11/2.x — `npm test` before you push and you're set.
 
 ## Support the project
 

package/config.schema.json

@@ -76,7 +76,7 @@
       },
       "enableLiveRoomTracking": {
         "title": "Enable Live Room Tracking",
-        "description": "While a B01/Q7-series robot is actively cleaning, periodically fetch the robot's map position (every ~20 seconds) and report the room it is physically inside as the current Matter Service Area, so controllers like Apple Home can show 'cleaning in <room>'. Requires Matter Room/Map Selection. Disable to avoid the extra map traffic.",
+        "description": "While a robot is actively cleaning, periodically fetch the robot's map position (every ~10 seconds) and report the room it is physically inside as the current Matter Service Area, so controllers like Apple Home can show 'cleaning in <room>'. Both generations are covered: B01/Q7 robots via the SCMap position, classic S/Q-series robots via the RRMap segment grid. Requires Matter Room/Map Selection. Disable to avoid the extra map traffic.",
         "type": "boolean",
         "default": true
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "3.25.0",
+  "version": "3.26.0",
   "description": "The most complete Roborock plugin for Apple Home. Supports the entire Roborock lineup — from the classic S-series to the new 2025 Q7 series that no other plugin can control. Sign in with your Roborock account and get native start/stop, room cleaning, suction levels, battery, and live 'cleaning in the kitchen' room tracking. Verified by Homebridge.",
   "license": "MIT",
   "author": {

package/roborockLib/roborockAPI.js

@@ -4560,9 +4560,11 @@ class Roborock {
    * instead of a guess. Deliberately constrained:
    *
    * - **Debug only.** Silent for every installation that has not asked for it.
-   * - **GET only.** Nothing here can change a schedule. The Hawk interceptor
-   *   signs an empty body (`roborockAPI.js` request interceptor), so a
-   *   body-bearing write would not authenticate anyway — a read does.
+   * - **Safe methods only — GET and OPTIONS.** Nothing here can change a
+   *   schedule. The Hawk interceptor signs an empty body (`roborockAPI.js`
+   *   request interceptor), so a body-bearing write would not authenticate
+   *   anyway. OPTIONS carries no body either: it asks a resource which methods
+   *   it accepts, which is how you find a write target without attempting one.
    * - **Once per robot per session,** so a poll cadence cannot turn it into
    *   traffic.
    * - **Never throws.** A probe that breaks startup would be worse than the
@@ -4592,23 +4594,78 @@ class Roborock {
   }
 
   /**
-   * GET one candidate cloud schedule route, record it, and log what came back.
+   * Pluck the one response header that says which methods a resource takes.
    *
-   * Extracted so that every route — the two candidates and the singular scene
-   * resource probed after them — shares one error path. It never throws: this
-   * rides along on a live poll, and a route that does not exist is a
-   * measurement rather than a fault, so a failure is recorded and logged at
-   * debug level instead of surfacing.
+   * The reporter's 3.25.1 reading is why this exists: `GET user/scene/{id}`
+   * came back `400` carrying `"Request method 'GET' is not supported"`. That
+   * sentence is a servlet container's way of saying the path IS mapped, just
+   * not for the verb we asked with — so the resource exists and something
+   * else reaches it. Which verb that is belongs in the `Allow` header, and a
+   * probe that keeps the body but drops the headers is the same defect as
+   * 3.25.1's, one field over.
+   *
+   * Deliberately ONE header rather than the block. Response headers carry
+   * `set-cookie` and session material; a diagnostic that printed the lot
+   * would leak more than it measures. `Allow` is the answer and the only
+   * thing taken.
+   *
+   * @param {unknown} headers axios response headers — an `AxiosHeaders`
+   *   instance in production, a plain object in tests
+   * @returns {string | undefined} the header value, or nothing when absent
+   */
+  readAllowedMethods(headers) {
+    if (!headers || typeof headers !== "object") {
+      return undefined;
+    }
+
+    /** @type {unknown} */
+    let value;
+    const accessor = /** @type {{get?: unknown}} */ (headers).get;
+    if (typeof accessor === "function") {
+      try {
+        value = accessor.call(headers, "allow");
+      } catch {
+        value = undefined;
+      }
+    }
+
+    if (value === undefined || value === null) {
+      const match = Object.entries(headers).find(
+        ([key]) => key.toLowerCase() === "allow"
+      );
+      value = match?.[1];
+    }
+
+    if (value === undefined || value === null || value === "") {
+      return undefined;
+    }
+
+    return Array.isArray(value) ? value.join(", ") : String(value);
+  }
+
+  /**
+   * Read one candidate cloud schedule route, record it, and log what came back.
+   *
+   * Extracted so that every route — the two candidates, the singular scene
+   * resource probed after them, and the OPTIONS question asked of that same
+   * resource — shares one error path. It never throws: this rides along on a
+   * live poll, and a route that does not exist is a measurement rather than a
+   * fault, so a failure is recorded and logged at debug level instead of
+   * surfacing.
    *
    * @param {string} duid robot the reading belongs to
-   * @param {{label: string, path: string}} route label to file it under, and
-   *   the path to read
+   * @param {{label: string, path: string, method?: string}} route label to
+   *   file it under, the path to read, and the safe method to read it with
+   *   (`get` unless stated)
    * @param {Record<string, unknown>} results accumulator, written in place
    * @returns {Promise<void>}
    */
   async probeOneCloudScheduleRoute(duid, route, results) {
+    const method = route.method === "options" ? "options" : "get";
+    const verb = method.toUpperCase();
+
     try {
-      const response = await this.api.get(route.path);
+      const response = await this.api[method](route.path);
       // Roborock wraps most answers in `{api,result,status,success}`. Keep
       // the envelope only when there is no `result` to unwrap, so the log
       // shows the payload rather than the wrapper.
@@ -4624,17 +4681,28 @@ class Roborock {
       // is intact.
       const decoded = this.describeCloudScheduleAnswer(payload);
 
+      // An OPTIONS answer says nothing in its body — the whole reading is the
+      // `Allow` header — so keep it on the success path too, not only on a
+      // refusal.
+      const allow = this.readAllowedMethods(response?.headers);
+
       results[route.label] = {
         path: route.path,
+        method: verb,
         ok: true,
         response: payload,
+        allow,
         schedules: decoded.length > 0 ? decoded : undefined,
       };
 
       this.log.debug(
-        `Roborock cloud schedule probe for ${this.describeDevice(duid)} — GET ${route.path} answered: ${JSON.stringify(
+        `Roborock cloud schedule probe for ${this.describeDevice(duid)} — ${verb} ${route.path} answered: ${JSON.stringify(
           this.compactDiagnosticPayload(payload)
-        )}`
+        )}${
+          allow === undefined
+            ? ""
+            : ` — the resource allows: ${this.compactDiagnosticPayload(allow)}`
+        }`
       );
 
       if (decoded.length > 0) {
@@ -4653,17 +4721,48 @@ class Roborock {
       const message =
         error instanceof Error ? error.message : String(error ?? "");
 
+      // The status alone does not measure the route, and the reporter's answer
+      // is why: `user/scene/{id}` came back `400`, not `404`. A 404 would have
+      // ruled the resource out; a 400 says the server routed the request and
+      // then rejected it, and only its own body says whether that is "no such
+      // route", "wrong method" or "that scene is not yours". Axios flattens all
+      // of it into `Request failed with status code 400`, which carries nothing.
+      //
+      // So keep the body. It goes through the same compaction and redaction as
+      // a successful answer, because an error envelope is no more ours to print
+      // blindly than a successful one.
+      const body = error?.response?.data;
+      const describedBody =
+        body === undefined ? undefined : this.compactDiagnosticPayload(body);
+
+      // And keep the headers' one useful field for the same reason. The
+      // refusal we went to this trouble for was "Request method 'GET' is not
+      // supported", which names the verb that failed and not the ones that
+      // would work; `Allow` is where a servlet puts those.
+      const allow = this.readAllowedMethods(error?.response?.headers);
+
       results[route.label] = {
         path: route.path,
+        method: verb,
         ok: false,
         status: status ?? null,
         error: message,
+        body: describedBody,
+        allow,
       };
 
       this.log.debug(
-        `Roborock cloud schedule probe for ${this.describeDevice(duid)} — GET ${route.path} failed${
+        `Roborock cloud schedule probe for ${this.describeDevice(duid)} — ${verb} ${route.path} failed${
           status ? ` with HTTP ${status}` : ""
-        }: ${message}`
+        }: ${message}${
+          describedBody === undefined
+            ? ""
+            : ` — the server said: ${JSON.stringify(describedBody)}`
+        }${
+          allow === undefined
+            ? ""
+            : ` — the resource allows: ${this.compactDiagnosticPayload(allow)}`
+        }`
       );
     }
   }
@@ -4721,9 +4820,29 @@ class Roborock {
     );
 
     if (firstSchedule) {
+      const scenePath = `user/scene/${firstSchedule.id}`;
+
+      await this.probeOneCloudScheduleRoute(
+        duid,
+        { label: "scene", path: scenePath },
+        results
+      );
+
+      // The reading that arrived is why this second question exists. That GET
+      // came back `400` saying `"Request method 'GET' is not supported"` —
+      // which is not "no such route". A servlet only says that when the path
+      // IS mapped and the verb is not, so the singular scene resource exists
+      // and some other method reaches it. Naming that method is exactly the
+      // thing still missing: we know WHAT a write would have to change (the
+      // `enabled` flag inside the TIMER trigger) and not WHERE to send it.
+      //
+      // OPTIONS is how a resource is asked that question without attempting
+      // an answer. It is defined as safe, it carries no body, and it cannot
+      // alter a schedule — so it is the one step toward a write that does not
+      // require the guess this thread has twice refused to make.
       await this.probeOneCloudScheduleRoute(
         duid,
-        { label: "scene", path: `user/scene/${firstSchedule.id}` },
+        { label: "sceneMethods", path: scenePath, method: "options" },
         results
       );
     }
@@ -5338,7 +5457,7 @@ class Roborock {
    * Fetch the current SCMap and derive which room the robot is physically
    * inside (currentPose ray-cast against the per-room boundary chains).
    * Called from the B01 status loop while the robot is actively cleaning;
-   * throttled on attempts (min 20s gap), single-flight per device, and
+   * throttled on attempts (min 10s gap), single-flight per device, and
    * disabled entirely with the enableLiveRoomTracking=false config option.
    *
    * On a room CHANGE the cached last v1 status is re-broadcast through