From e52d3456ae08f931f33d86b6b1f1fc6c15206670 Mon Sep 17 00:00:00 2001 From: "Ian C." <108159253+ic-dev21@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:38:03 -0500 Subject: [PATCH 1/3] Add update function and tests This new function is no-op until a Hilo update. This will let us update the event details selectively. --- pyhilo/api.py | 21 ++++- pyhilo/event.py | 59 +++++++++++++- tests/test_api_auth.py | 37 ++++++++- tests/test_event.py | 179 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 291 insertions(+), 5 deletions(-) create mode 100644 tests/test_event.py diff --git a/pyhilo/api.py b/pyhilo/api.py index bb28525..9faa523 100755 --- a/pyhilo/api.py +++ b/pyhilo/api.py @@ -2,6 +2,7 @@ import asyncio import base64 +from collections.abc import Mapping from datetime import datetime, timedelta import json import random @@ -48,6 +49,20 @@ from pyhilo.signalr import SignalRHub, SignalRManager from pyhilo.util.state import AndroidDeviceDict, StateDict, get_state, set_state +_TRACE_REDACTED_KEYS = frozenset( + {"authorization", "ocp-apim-subscription-key", "accesstoken"} +) + + +def _redact_trace(values: object) -> object: + """Mask credentials so users can share trace logs when reporting issues.""" + if not isinstance(values, Mapping): + return values + return { + key: "***" if str(key).lower() in _TRACE_REDACTED_KEYS else value + for key, value in values.items() + } + class API: """An API object to interact with the Hilo cloud. @@ -288,7 +303,7 @@ async def _async_request( data: dict[str, Any] = {} url = parse.urljoin(f"https://{host}", endpoint) if self.log_traces: - LOG.debug("[TRACE] Headers: %s", kwargs["headers"]) + LOG.debug("[TRACE] Headers: %s", _redact_trace(kwargs["headers"])) LOG.debug("[TRACE] Async request: %s %s", method, url) async with self.session.request(method, url, **kwargs) as resp: @@ -302,7 +317,9 @@ async def _async_request( else: data = {"message": await resp.text()} if self.log_traces: - LOG.debug("[TRACE] Data received from /%s: %s", endpoint, data) + LOG.debug( + "[TRACE] Data received from /%s: %s", endpoint, _redact_trace(data) + ) resp.raise_for_status() return data diff --git a/pyhilo/event.py b/pyhilo/event.py index 993fef4..8516963 100755 --- a/pyhilo/event.py +++ b/pyhilo/event.py @@ -3,13 +3,22 @@ from datetime import datetime, timedelta, timezone import logging import re -from typing import Any, cast +from typing import Any, TypedDict, cast from pyhilo.util import camel_to_snake, from_utc_timestamp LOG = logging.getLogger(__package__) +class OptOutDevice(TypedDict): + """A device leaving Hilo's control, e.g. when its setpoint is changed during an event.""" + + id: int + eventDateUtc: str + triggerTypeId: int + triggerApplicationId: int | None + + class Event: """This class is used to populate the data of a Hilo Challenge Event, contains datetime info and consumption data""" @@ -38,7 +47,11 @@ def __init__(self, **event: dict[str, Any]): self.period: str = (cast(str, event.get("period", "")) or "").lower() self.event_id: int = cast(int, event["id"]) self.total_devices: int = len(devices) - self.opt_out_devices: int = len([x for x in devices if x["optOut"]]) + self._opt_out_device_ids: set[int] = {x["id"] for x in devices if x["optOut"]} + self.opt_out_devices: int = 0 + self._record_opt_outs( + cast(list[OptOutDevice], event.get("optOutDevices") or []) + ) self.pre_heat_devices: int = len([x for x in devices if x["preheat"]]) self.progress: str = cast(str, event.get("progress", "unknown")) self.mode: str = cast(str, params.get("mode", "Unknown")) @@ -68,6 +81,48 @@ def __init__(self, **event: dict[str, Any]): "reward", ] + def update(self, data: dict[str, Any]) -> None: + """Update the event in place from a partial Hilo message. + + Hilo sends partial updates: a field it isn't changing is either + missing or None (an opt-out notice carries only the opted-out + devices, with progress, parameters, etc. set to None). Only the + fields that carry a value are applied; everything else keeps its + current value. Consumption progress arrives in separate messages + handled by update_wh(). + """ + if (phases := data.get("phases")) is not None: + self._convert_phases(phases) + if (progress := data.get("progress")) is not None: + self.progress = progress + if (participating := data.get("isParticipating")) is not None: + self.participating = participating + if (configurable := data.get("isConfigurable")) is not None: + self.configurable = configurable + if (period := data.get("period")) is not None: + self.period = period.lower() + if (params := data.get("parameters")) is not None: + devices: list[dict[str, Any]] = params.get("devices", []) + self.total_devices = len(devices) + self._opt_out_device_ids.update(x["id"] for x in devices if x["optOut"]) + self.pre_heat_devices = len([x for x in devices if x["preheat"]]) + self.mode = params.get("mode", self.mode) + self._record_opt_outs(data.get("optOutDevices") or []) + if (reward := data.get("reward")) is not None: + self.reward = reward + consumption: dict[str, Any] = data.get("consumption") or {} + # Hilo reports a baseline of 0 until it has computed one; skip it so + # a known baseline is never wiped. + if allowed_wH := consumption.get("baselineWh"): + self.update_allowed_wh(allowed_wH) + self.last_update = datetime.now(timezone.utc).astimezone() + + def _record_opt_outs(self, opt_outs: list[OptOutDevice]) -> None: + # Hilo emits an entry each time a device is taken over, so the same + # device can appear many times; count each device once. + self._opt_out_device_ids.update(x["id"] for x in opt_outs) + self.opt_out_devices = len(self._opt_out_device_ids) + def update_wh(self, used_wH: float) -> None: """This function is used to update the used_kWh attribute during a Hilo Challenge Event""" LOG.debug("Updating Wh: %s", used_wH) diff --git a/tests/test_api_auth.py b/tests/test_api_auth.py index 4d0c029..b5e7b16 100644 --- a/tests/test_api_auth.py +++ b/tests/test_api_auth.py @@ -8,7 +8,7 @@ import pytest from pyhilo import API, AbstractAuth -from pyhilo.const import API_HOSTNAME +from pyhilo.const import API_HOSTNAME, SUBSCRIPTION_KEY URN = "urn:hilo:crm:abc-123" @@ -133,3 +133,38 @@ async def test_deprecated_oauth_session_still_works( assert await api.async_get_access_token() == TOKEN oauth_session.async_ensure_token_valid.assert_awaited_once() assert api.urn == URN + + +@pytest.mark.parametrize( + "secret", + [ + pytest.param(TOKEN, id="bearer_token"), + pytest.param(SUBSCRIPTION_KEY, id="subscription_key"), + ], +) +async def test_trace_logs_redact_request_credentials( + mock_session: MagicMock, caplog: pytest.LogCaptureFixture, secret: str +) -> None: + auth = AsyncMock(spec=AbstractAuth) + auth.async_get_access_token.return_value = TOKEN + api = API(session=mock_session, auth=auth, log_traces=True) + + with caplog.at_level(logging.DEBUG): + await api._async_request("get", "/endpoint") + + assert secret not in caplog.text + + +async def test_trace_logs_redact_signalr_negotiate_token( + mock_session: MagicMock, caplog: pytest.LogCaptureFixture +) -> None: + response = mock_session.request.return_value.__aenter__.return_value + response.json.return_value = {"url": "https://hub", "accessToken": "hub-token"} + auth = AsyncMock(spec=AbstractAuth) + auth.async_get_access_token.return_value = TOKEN + api = API(session=mock_session, auth=auth, log_traces=True) + + with caplog.at_level(logging.DEBUG): + await api._async_request("post", "/DeviceHub/negotiate") + + assert "hub-token" not in caplog.text diff --git a/tests/test_event.py b/tests/test_event.py new file mode 100644 index 0000000..80684b7 --- /dev/null +++ b/tests/test_event.py @@ -0,0 +1,179 @@ +"""Tests for Event updates, using message shapes captured from a real Hilo event.""" + +import pytest + +from pyhilo.event import Event, OptOutDevice + +EVENT_ID = 101 +THERMOSTAT_A = 1001 +THERMOSTAT_B = 1002 +CHARGER = 2001 + + +def _device(device_id: int, opt_out: bool = False) -> dict[str, object]: + return { + "id": device_id, + "deviceUid": f"uid-{device_id}", + "deviceType": "Thermostat", + "name": f"Device {device_id}", + "roomName": "Room", + "optOut": opt_out, + "preheat": False, + } + + +def _initial_message( + devices: list[dict[str, object]], baseline_wh: float = 0.0 +) -> dict[str, object]: + """Shape of ChallengeDetailsInitialValuesReceived.""" + return { + "id": EVENT_ID, + "progress": "scheduled", + "isParticipating": True, + "isConfigurable": False, + "period": "PM", + "phases": { + "settingsDeadlineUTC": "2026-11-17T05:00:00Z", + "preheatStartDateUTC": "2026-11-17T19:00:00Z", + "preheatEndDateUTC": "2026-11-17T21:00:00Z", + "reductionStartDateUTC": "2026-11-17T21:00:00Z", + "reductionEndDateUTC": "2026-11-18T01:00:00Z", + "recoveryStartDateUTC": "2026-11-18T01:00:00Z", + "recoveryEndDateUTC": "2026-11-18T02:00:00Z", + }, + "parameters": {"mode": "Extreme", "devices": devices}, + "consumption": {"baselineWh": baseline_wh}, + "optOutDevices": [], + } + + +def _opt_out(device_id: int, trigger_type_id: int = 3) -> OptOutDevice: + return { + "id": device_id, + "eventDateUtc": "2026-11-17T21:00:00.4189642Z", + "triggerTypeId": trigger_type_id, + "triggerApplicationId": 1 if trigger_type_id == 3 else None, + } + + +def _opt_out_notice(*opt_outs: OptOutDevice) -> dict[str, object]: + """Shape of ChallengeDetailsUpdatedValuesReceived: everything but the opt-outs is None.""" + return { + "id": EVENT_ID, + "progress": None, + "isParticipating": None, + "isConfigurable": None, + "currentPhase": None, + "parameters": None, + "report": None, + "optOutDevices": list(opt_outs), + } + + +def _event(devices: list[dict[str, object]] | None = None) -> Event: + devices = ( + devices + if devices is not None + else [_device(THERMOSTAT_A), _device(THERMOSTAT_B), _device(CHARGER)] + ) + return Event(**_initial_message(devices)) + + +@pytest.mark.parametrize( + ("devices", "expected"), + [ + pytest.param([_device(THERMOSTAT_A)], 0, id="none_opted_out"), + pytest.param( + [_device(THERMOSTAT_A, opt_out=True), _device(THERMOSTAT_B)], + 1, + id="one_flagged", + ), + ], +) +def test_initial_opt_out_count_comes_from_device_flags( + devices: list[dict[str, object]], expected: int +) -> None: + assert _event(devices).opt_out_devices == expected + + +@pytest.mark.parametrize( + ("notices", "expected"), + [ + pytest.param([[_opt_out(THERMOSTAT_A)]], 1, id="single_notice"), + pytest.param( + [[_opt_out(THERMOSTAT_A)], [_opt_out(THERMOSTAT_A, trigger_type_id=1)]], + 1, + id="same_device_repeated", + ), + pytest.param( + [[_opt_out(THERMOSTAT_A)], [_opt_out(THERMOSTAT_B)]], + 2, + id="distinct_devices", + ), + pytest.param( + [[_opt_out(THERMOSTAT_A), _opt_out(THERMOSTAT_B)]], + 2, + id="several_in_one_notice", + ), + ], +) +def test_opt_out_notices_count_each_device_once( + notices: list[list[OptOutDevice]], expected: int +) -> None: + event = _event() + + for opt_outs in notices: + event.update(_opt_out_notice(*opt_outs)) + + assert event.opt_out_devices == expected + + +def test_opt_out_notice_and_device_flag_for_same_device_count_once() -> None: + event = _event([_device(THERMOSTAT_A, opt_out=True), _device(THERMOSTAT_B)]) + + event.update(_opt_out_notice(_opt_out(THERMOSTAT_A))) + + assert event.opt_out_devices == 1 + + +@pytest.mark.parametrize( + ("attribute", "expected"), + [ + pytest.param("progress", "scheduled", id="progress"), + pytest.param("participating", True, id="participating"), + pytest.param("total_devices", 3, id="total_devices"), + pytest.param("mode", "Extreme", id="mode"), + pytest.param("period", "pm", id="period"), + ], +) +def test_opt_out_notice_keeps_other_fields(attribute: str, expected: object) -> None: + event = _event() + + event.update(_opt_out_notice(_opt_out(THERMOSTAT_A))) + + assert getattr(event, attribute) == expected + + +@pytest.mark.parametrize( + ("baseline_wh", "expected_kwh"), + [ + pytest.param(0.0, 14.76, id="zero_before_baseline_is_computed"), + pytest.param(14777.26, 14.78, id="revised_baseline"), + ], +) +def test_update_baseline(baseline_wh: float, expected_kwh: float) -> None: + event = _event() + event.update_allowed_wh(14762.21) + + event.update({"id": EVENT_ID, "consumption": {"baselineWh": baseline_wh}}) + + assert event.allowed_kWh == expected_kwh + + +def test_update_leaves_used_wh_to_consumption_messages() -> None: + event = _event() + event.update_wh(5987.98) + + event.update({"id": EVENT_ID, "consumption": {"currentWh": 0.0}}) + + assert event.used_kWh == 5.99 From 50e8ee5e91421f80585dd743da162ab6d84dcf49 Mon Sep 17 00:00:00 2001 From: "Ian C." <108159253+ic-dev21@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:30:54 +0000 Subject: [PATCH 2/3] Revert trace redaction from the update commit The credential redaction is unrelated to Event.update and was bundled into e52d345 by mistake. Pull it out so it can land as its own commit and be reviewed on its own. Co-Authored-By: Claude Opus 5.5 --- pyhilo/api.py | 21 ++------------------- tests/test_api_auth.py | 37 +------------------------------------ 2 files changed, 3 insertions(+), 55 deletions(-) diff --git a/pyhilo/api.py b/pyhilo/api.py index 9faa523..bb28525 100755 --- a/pyhilo/api.py +++ b/pyhilo/api.py @@ -2,7 +2,6 @@ import asyncio import base64 -from collections.abc import Mapping from datetime import datetime, timedelta import json import random @@ -49,20 +48,6 @@ from pyhilo.signalr import SignalRHub, SignalRManager from pyhilo.util.state import AndroidDeviceDict, StateDict, get_state, set_state -_TRACE_REDACTED_KEYS = frozenset( - {"authorization", "ocp-apim-subscription-key", "accesstoken"} -) - - -def _redact_trace(values: object) -> object: - """Mask credentials so users can share trace logs when reporting issues.""" - if not isinstance(values, Mapping): - return values - return { - key: "***" if str(key).lower() in _TRACE_REDACTED_KEYS else value - for key, value in values.items() - } - class API: """An API object to interact with the Hilo cloud. @@ -303,7 +288,7 @@ async def _async_request( data: dict[str, Any] = {} url = parse.urljoin(f"https://{host}", endpoint) if self.log_traces: - LOG.debug("[TRACE] Headers: %s", _redact_trace(kwargs["headers"])) + LOG.debug("[TRACE] Headers: %s", kwargs["headers"]) LOG.debug("[TRACE] Async request: %s %s", method, url) async with self.session.request(method, url, **kwargs) as resp: @@ -317,9 +302,7 @@ async def _async_request( else: data = {"message": await resp.text()} if self.log_traces: - LOG.debug( - "[TRACE] Data received from /%s: %s", endpoint, _redact_trace(data) - ) + LOG.debug("[TRACE] Data received from /%s: %s", endpoint, data) resp.raise_for_status() return data diff --git a/tests/test_api_auth.py b/tests/test_api_auth.py index b5e7b16..4d0c029 100644 --- a/tests/test_api_auth.py +++ b/tests/test_api_auth.py @@ -8,7 +8,7 @@ import pytest from pyhilo import API, AbstractAuth -from pyhilo.const import API_HOSTNAME, SUBSCRIPTION_KEY +from pyhilo.const import API_HOSTNAME URN = "urn:hilo:crm:abc-123" @@ -133,38 +133,3 @@ async def test_deprecated_oauth_session_still_works( assert await api.async_get_access_token() == TOKEN oauth_session.async_ensure_token_valid.assert_awaited_once() assert api.urn == URN - - -@pytest.mark.parametrize( - "secret", - [ - pytest.param(TOKEN, id="bearer_token"), - pytest.param(SUBSCRIPTION_KEY, id="subscription_key"), - ], -) -async def test_trace_logs_redact_request_credentials( - mock_session: MagicMock, caplog: pytest.LogCaptureFixture, secret: str -) -> None: - auth = AsyncMock(spec=AbstractAuth) - auth.async_get_access_token.return_value = TOKEN - api = API(session=mock_session, auth=auth, log_traces=True) - - with caplog.at_level(logging.DEBUG): - await api._async_request("get", "/endpoint") - - assert secret not in caplog.text - - -async def test_trace_logs_redact_signalr_negotiate_token( - mock_session: MagicMock, caplog: pytest.LogCaptureFixture -) -> None: - response = mock_session.request.return_value.__aenter__.return_value - response.json.return_value = {"url": "https://hub", "accessToken": "hub-token"} - auth = AsyncMock(spec=AbstractAuth) - auth.async_get_access_token.return_value = TOKEN - api = API(session=mock_session, auth=auth, log_traces=True) - - with caplog.at_level(logging.DEBUG): - await api._async_request("post", "/DeviceHub/negotiate") - - assert "hub-token" not in caplog.text From e31318c129d8c1e70ae68d0b2884957fca5a7a59 Mon Sep 17 00:00:00 2001 From: "Ian C." <108159253+ic-dev21@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:30:56 +0000 Subject: [PATCH 3/3] Redact credentials from trace logs With log_traces enabled, request headers and response bodies were logged verbatim, exposing the bearer token, the APIM subscription key and the SignalR negotiate accessToken. Users are routinely asked to share these logs when reporting issues, so they must be safe to post. Co-Authored-By: Claude Opus 5.5 --- pyhilo/api.py | 21 +++++++++++++++++++-- tests/test_api_auth.py | 37 ++++++++++++++++++++++++++++++++++++- 2 files changed, 55 insertions(+), 3 deletions(-) diff --git a/pyhilo/api.py b/pyhilo/api.py index bb28525..9faa523 100755 --- a/pyhilo/api.py +++ b/pyhilo/api.py @@ -2,6 +2,7 @@ import asyncio import base64 +from collections.abc import Mapping from datetime import datetime, timedelta import json import random @@ -48,6 +49,20 @@ from pyhilo.signalr import SignalRHub, SignalRManager from pyhilo.util.state import AndroidDeviceDict, StateDict, get_state, set_state +_TRACE_REDACTED_KEYS = frozenset( + {"authorization", "ocp-apim-subscription-key", "accesstoken"} +) + + +def _redact_trace(values: object) -> object: + """Mask credentials so users can share trace logs when reporting issues.""" + if not isinstance(values, Mapping): + return values + return { + key: "***" if str(key).lower() in _TRACE_REDACTED_KEYS else value + for key, value in values.items() + } + class API: """An API object to interact with the Hilo cloud. @@ -288,7 +303,7 @@ async def _async_request( data: dict[str, Any] = {} url = parse.urljoin(f"https://{host}", endpoint) if self.log_traces: - LOG.debug("[TRACE] Headers: %s", kwargs["headers"]) + LOG.debug("[TRACE] Headers: %s", _redact_trace(kwargs["headers"])) LOG.debug("[TRACE] Async request: %s %s", method, url) async with self.session.request(method, url, **kwargs) as resp: @@ -302,7 +317,9 @@ async def _async_request( else: data = {"message": await resp.text()} if self.log_traces: - LOG.debug("[TRACE] Data received from /%s: %s", endpoint, data) + LOG.debug( + "[TRACE] Data received from /%s: %s", endpoint, _redact_trace(data) + ) resp.raise_for_status() return data diff --git a/tests/test_api_auth.py b/tests/test_api_auth.py index 4d0c029..b5e7b16 100644 --- a/tests/test_api_auth.py +++ b/tests/test_api_auth.py @@ -8,7 +8,7 @@ import pytest from pyhilo import API, AbstractAuth -from pyhilo.const import API_HOSTNAME +from pyhilo.const import API_HOSTNAME, SUBSCRIPTION_KEY URN = "urn:hilo:crm:abc-123" @@ -133,3 +133,38 @@ async def test_deprecated_oauth_session_still_works( assert await api.async_get_access_token() == TOKEN oauth_session.async_ensure_token_valid.assert_awaited_once() assert api.urn == URN + + +@pytest.mark.parametrize( + "secret", + [ + pytest.param(TOKEN, id="bearer_token"), + pytest.param(SUBSCRIPTION_KEY, id="subscription_key"), + ], +) +async def test_trace_logs_redact_request_credentials( + mock_session: MagicMock, caplog: pytest.LogCaptureFixture, secret: str +) -> None: + auth = AsyncMock(spec=AbstractAuth) + auth.async_get_access_token.return_value = TOKEN + api = API(session=mock_session, auth=auth, log_traces=True) + + with caplog.at_level(logging.DEBUG): + await api._async_request("get", "/endpoint") + + assert secret not in caplog.text + + +async def test_trace_logs_redact_signalr_negotiate_token( + mock_session: MagicMock, caplog: pytest.LogCaptureFixture +) -> None: + response = mock_session.request.return_value.__aenter__.return_value + response.json.return_value = {"url": "https://hub", "accessToken": "hub-token"} + auth = AsyncMock(spec=AbstractAuth) + auth.async_get_access_token.return_value = TOKEN + api = API(session=mock_session, auth=auth, log_traces=True) + + with caplog.at_level(logging.DEBUG): + await api._async_request("post", "/DeviceHub/negotiate") + + assert "hub-token" not in caplog.text