Readable names for unlisted values, Connected variable & rate-limit recovery (builds 25–30)

[bumaas]

This PR builds on the current master (build 24) and adds builds 25–30. It is the delta only; the tree matches our tested fork state. All 76 PHPUnit tests pass.

Motivation

Field reports showed raw API keys or "N/A" where a readable name belongs: option values and programs chosen at the appliance were missing from their profiles (the profiles hold only what the API lists as selectable), and the event profile was created once and never extended. Users also asked to tell a switched-off appliance from an offline one. A code review of the rate-limit path then found that the event stream could stay dead after a block: a restart during the block left the IO switched off for good, and the reconnect after a 401 re-sent the token the server had just rejected.

Changes

Device (Home Connect Device)

• Readable names for values missing from a profile (builds 25, 27, 28): option values, events and programs chosen at the appliance get a missing profile association added when they arrive — known keys with their translated name, unknown ones with a readable name from the key (DelicatesSilk → "Delicates Silk"). The selection still offers exactly the values of the selected program. SaltNearlyEmpty added to the dishwasher events.
• Connected variable (build 26): follows the DISCONNECTED/CONNECTED events and the /status answer the refresh requests anyway (SDK.Error.HomeAppliance.Connection.Initialization.Failed = offline). No additional request; OperationState and instance status are unchanged.
• Throttled initialization is retried (build 30): an init skipped by the 30 s refresh throttle (e.g. appliance offline at setup, online right after) arms a RetryRefresh timer for the rest of the window instead of being dropped.
• Numeric profile type (build 30): a variable follows an existing profile of the other numeric type (INTEGER vs. FLOAT) instead of being rejected.

Cloud (Home Connect Cloud)

• Recovery after a rate-limit block (builds 29, 30): the keep-alive watchdog lifts an expired block whose timer was lost to a restart and re-activates the IO; if the stream cannot be resumed (no token), the block stays pending and is retried. The instance reports IS_ACTIVE only after the IO is running again, so children no longer see an inactive IO and stay inactive.
• Single stream connect (build 30): one path fetches the token first and applies the IO once (previously twice, the first time with the old header); without a token the IO is left off, and it is no longer switched on while a block is active.
• Rejected token is dropped (build 29): after a 401 invalid_token from the stream the cached access token is cleared, so the reconnect fetches a new one.
• Quiet watchdog (build 30): no echo from the timer when the IO is switched off on purpose or no login exists — each one ended up as a log warning.

Configurator (Home Connect Configurator)

• Lists only device instances of its own cloud instance (build 30); devices of another cloud were offered as deletable rows.

Tests

PHPUnit suite extended from 52 → 76 tests, with fixtures from real captures (coffee maker, offline washer, dishwasher, washer dryer). Each fix was checked red/green: the new tests fail on the code without the fix and pass with it. The fixtures added in builds 26–28 are reformatted for json-check.php; their content is unchanged. All green.

🤖 Generated with Claude Code

[TillBrede]

Thanks for this! I went through the whole diff (builds 25–30). Overall it's in good shape: every fix comes with a test that fails without it, the commit messages explain why each change was made, and the fixtures are real captures. I found one regression worth fixing before merge and a few small points. I didn't run the suite locally; CI is green.

Worth fixing: a pending block can leave the cloud stuck at status 201

Build 30 changes ResetRateLimit() so that the block stays pending when the stream can't be resumed. That happens when no token can be fetched: login missing or revoked, or the OAuth server is down. In that case RateLimitUntil stays set and the status stays STATUS_RATE_LIMITED.

The problem is what happens next:

1. The token fetch fails because the login expired. The user sees this and re-registers.
2. ProcessOAuthData calls ForceRegisterServerEvents, which calls connectEventStream(true, true). The stream comes back up.
3. Nothing clears the block state. ForceRegisterServerEvents doesn't touch RateLimitUntil or the status.
4. The watchdog only calls ResetRateLimit() when the keep-alive is stale. Keep-alives now arrive every 55 s, so that never happens.

Result: the event stream works, but the cloud stays at 201 and the device instances stay inactive. The form keeps showing "blocked until <a time in the past>". It only recovers when some REST request happens to succeed (a user action, a SelectedProgram event, opening the configurator). Before build 30 this couldn't happen, because the block was reset unconditionally.

Possible fix: split ResetRateLimit() into two steps, "connect" and "clear block + SetStatus(IS_ACTIVE)". Then run the second step after every successful connectEventStream() while RateLimitUntil !== 0 && !isRateLimitActive(). That covers ForceRegisterServerEvents, RegisterServerEvents and the 401 path. A test would be: block pending, then ForceRegisterServerEvents() with a valid token, then assert the status is IS_ACTIVE and RateLimitUntil is 0.

Minor points

• Numeric profile type (createVariableFromConstraints): the variable now takes the type of an existing profile. When the existing profile is INTEGER and the API reports FLOAT, values like 4.5 °C get cut to 4. That's still better than the variable not being created at all, which is what happened before. createStates already avoids the clash by giving float profiles a .f suffix, and options/settings could do the same.
• RetryRefresh can be lost: refreshDeviceState() clears the timer on every call. A throttled value refresh ($initializeDevice = false) in the same window clears it and doesn't re-arm it. In practice the next IS_ACTIVE status change triggers the init again, so the fix is just for robustness: only clear the timer when a refresh actually runs, or re-arm it when needsInitialization() is true.
• Misleading debug label: the RetryRefresh timer goes through the RefreshDeviceState action, so a retry shows up in the debug log as Event:CONNECTED (deferred).
• Stale comment in handleExpiredTokenFromStream: it still says "FetchAccessToken() in RegisterServerEvents"; that call is now in connectEventStream.
• getReadableName() and digits: keys with digits followed by capitals split oddly, e.g. HotAir3D becomes "Hot Air3 D". Cosmetic.

Looks good

• connectEventStream(): one code path, the token is fetched before anything is applied, the IO is applied once, and timer calls produce no echo.
• ForceRegisterServerEvents no longer switches the IO on during a block. Before, that cost a GET /events that came back as 429.
• After a 401, the rejected token is dropped, and IS_ACTIVE is only set once the IO is running again.
• The watchdog clears a block that expired across a restart, and it leaves an IO alone when the user switched it off.
• The Connected variable makes no extra requests and ignores 429 and other unrelated errors.
• The event, option and program associations are added only when needed, so existing installations get them too, and rebuilding the profiles still removes extra values from the selection.
• The configurator now filters devices by their own cloud. Devices with no cloud are still listed.

[TillBrede]

Thanks for the quick follow-up. Build 31 addresses all points, approving.

One small thing for a follow-up: RetryRefresh is a repeating timer, and since build 31 it is only cleared inside the active-parent branch of refreshDeviceState(). If the cloud goes inactive while a retry is pending (e.g. a rate-limit block), the timer keeps firing every 1–30 s until the cloud is active again. That costs no API requests, but a script run and a debug line each time. Adding $this->SetTimerInterval('RetryRefresh', 0); before setInstanceStatus(IS_INACTIVE) would stop it; the status change back to IS_ACTIVE starts the initialization again anyway.

[bumaas]

Thanks for the thorough review. Builds 31 and 32 (ee6ca57) are on the branch:

• Pending block: connectEventStream() now lifts an expired block as soon as the stream runs again (liftRateLimit()), whichever path registered it: reset timer, watchdog, new login or 401 recovery. A block that is still running is lifted by ResetRateLimit() after a successful request, as before. Test as you suggested (testReRegistrationLiftsPendingBlock), plus the counterpart that a running block is kept.
• Numeric profile type: the lossy direction only (existing INTEGER profile, API reports a Double) gets a float profile of its own with the .f suffix and a float variable; the existing profile is left alone. A FLOAT profile with an Int setting stays as it is. Fixture is a real capture of my oven, Cooking.Oven.Option.SetpointTemperature is a Double there.
• RetryRefresh: the timer is only cleared by a refresh that actually runs and does not leave the initialization due. A throttled value refresh leaves it alone (testThrottledValueRefreshKeepsPendingRetry).
• The retry has its own action RetryRefreshDeviceState and shows up as trigger: RetryRefresh in the debug log.
• getReadableName(): IDos1BaseLevel gives "IDos 1 Base Level", HotAir3D gives "Hot Air 3D", Eco50 gives "Eco 50".
• Comment in handleExpiredTokenFromStream fixed.

82 tests / 663 assertions green.