Skip to content

Commit bbbceb7

Browse files
authored
feat: resume the SSE cache snapshot from the last cursor on reconnect (#71)
* feat: resume the SSE cache snapshot from the last cursor on reconnect * fix: tie the cursor scope to the response that supplied it
1 parent 249b336 commit bbbceb7

3 files changed

Lines changed: 214 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -343,7 +343,7 @@ Listen for vehicle error events. The callback receives a list of dictionaries co
343343
The alerts in the vehicle's latest alerts batch, newest first. An alert without `endedAt` is active. The vehicle sends its window of recent alerts (up to 100, reaching back days) and drops old ones off it, active ones included, so this is what the vehicle currently reports, not a lifetime history.
344344

345345
### `listen_AlertChanges(callback: Callable[[str, dict], None]) -> Callable[[],None]`
346-
Listen for alerts starting and ending. The callback receives `"started"` or `"ended"` and the alert. Each alerts event carries the vehicle's recent alerts, ended ones included, and is resent unchanged, including as the snapshot on every reconnect, so only an alert not seen before that comes ahead of every alert already seen (batches are newest first; position is used rather than `startedAt`, which the vehicle's clock can skew) is a start, and only a known active alert that now has `endedAt` is an end. The first batch only seeds `alerts`. An alert that started and ended between two batches calls back with both. The lifecycle rules are based on [purcell-lab/teslemetry-alerts](https://github.com/purcell-lab/teslemetry-alerts).
346+
Listen for alerts starting and ending. The callback receives `"started"` or `"ended"` and the alert. Each alerts event carries the vehicle's recent alerts, ended ones included, and is resent unchanged, including as the connect snapshot, so only an alert not seen before that comes ahead of every alert already seen (batches are newest first; position is used rather than `startedAt`, which the vehicle's clock can skew) is a start, and only a known active alert that now has `endedAt` is an end. The first batch only seeds `alerts`. An alert that started and ended between two batches calls back with both. The lifecycle rules are based on [purcell-lab/teslemetry-alerts](https://github.com/purcell-lab/teslemetry-alerts).
347347

348348
### `listen_ChargerPower(callback: Callable[[float | None], None]) -> Callable[[],None]`
349349
Listen for charger power whether the vehicle is AC or DC charging. Combines `ACChargingPower` and `DCChargingPower` (DC preferred), gated by `DetailedChargeState`: the value drops to `0` when charging ends, since neither source is reliably reset then, and a lone zero while charging is held until both sources have reported. Enables all three fields; the returned function removes all three listeners.

‎teslemetry_stream/stream.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,10 @@ def __init__(
8787
self.parse_timestamp = parse_timestamp
8888
self.manual = manual
8989
self.retries: int = 0
90+
# Last cache position received, and the (url, topics) it belongs to -
91+
# only a reconnect asking for the same vehicles and topics may resume from it.
92+
self._cursor: Any = None
93+
self._cursor_scope: tuple[str, str | None] | None = None
9094
self.vehicles: dict[str, TeslemetryStreamVehicle] = {}
9195
self.energysites: dict[int, TeslemetryStreamEnergySite] = {}
9296
self.fields: dict[str, Any] = {}
@@ -267,6 +271,9 @@ async def connect(self) -> None:
267271
params = {"cache": "true"}
268272
if self.topics:
269273
params["topics"] = ",".join(self.topics)
274+
scope = (url, params.get("topics"))
275+
if scope == self._cursor_scope and self._cursor is not None:
276+
params["cursor"] = str(self._cursor)
270277
response = await self._session.get(
271278
url,
272279
headers=headers,
@@ -285,6 +292,10 @@ async def connect(self) -> None:
285292
if self._response is not None:
286293
self._response.close()
287294
self._response = response
295+
# Only now, so a failed GET leaves the cursor tied to the response still supplying it.
296+
if scope != self._cursor_scope:
297+
self._cursor = None
298+
self._cursor_scope = scope
288299
LOGGER.debug(
289300
"Connected to %s with status %s", self._response.url, self._response.status
290301
)
@@ -362,6 +373,9 @@ async def __anext__(self) -> dict[str, Any]:
362373
field, _, value = line_in_bytes.decode("utf8").partition(": ")
363374
if field == "data":
364375
data = json.loads(value)
376+
# An event without a cursor keeps the last one received.
377+
if data.get("cursor") is not None:
378+
self._cursor = data["cursor"]
365379
if self.parse_timestamp:
366380
data["timestamp"] = _parse_created_at(data["createdAt"])
367381
return cast(dict[str, Any], data)

‎tests/test_sse_cursor.py‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
"""Checks the SSE `cursor` resume: the stream keeps the last `cursor` an event
2+
carried and sends it back on a reconnect asking for the same vehicles and
3+
topics, so the connect snapshot starts after it. A first connect, or one
4+
whose vehicles or topics changed, omits it and takes a full snapshot.
5+
"""
6+
from __future__ import annotations
7+
8+
import asyncio
9+
import contextlib
10+
import json
11+
from typing import Any
12+
13+
import aiohttp
14+
15+
from teslemetry_stream.stream import TeslemetryStream
16+
17+
VIN = "LRW3F7EK4NC000001"
18+
19+
20+
def line(event: dict[str, Any]) -> bytes:
21+
return f"data: {json.dumps(event)}\n".encode()
22+
23+
24+
def event(cursor: int | None = None) -> dict[str, Any]:
25+
ev: dict[str, Any] = {
26+
"vin": VIN,
27+
"createdAt": "2026-11-07T10:00:00.000Z",
28+
"data": {"Odometer": 1},
29+
}
30+
if cursor is not None:
31+
ev["cursor"] = cursor
32+
return ev
33+
34+
35+
class FakeContent:
36+
"""Response body that yields its lines once, then ends cleanly."""
37+
38+
def __init__(self, lines: list[bytes]) -> None:
39+
self._lines = list(lines)
40+
41+
def __aiter__(self) -> FakeContent:
42+
return self
43+
44+
async def __anext__(self) -> bytes:
45+
if not self._lines:
46+
raise StopAsyncIteration
47+
return self._lines.pop(0)
48+
49+
50+
class FakeResponse:
51+
def __init__(self, events: list[dict[str, Any]]) -> None:
52+
self.url = "https://fake.teslemetry.com/sse"
53+
self.status = 200
54+
self.content = FakeContent([line(e) for e in events])
55+
56+
def close(self) -> None:
57+
pass
58+
59+
60+
class FakeSession:
61+
def __init__(self, responses: list[FakeResponse | Exception]) -> None:
62+
self._responses = list(responses)
63+
self.calls: list[dict[str, Any]] = []
64+
65+
async def get(self, url: str, **kwargs: Any) -> FakeResponse:
66+
self.calls.append({"url": url, **kwargs})
67+
response = self._responses.pop(0)
68+
if isinstance(response, Exception):
69+
raise response
70+
return response
71+
72+
73+
def make_stream(session: FakeSession, **kwargs: Any) -> TeslemetryStream:
74+
return TeslemetryStream(
75+
session=session, # type: ignore[arg-type]
76+
access_token="test-token",
77+
server="api.teslemetry.com",
78+
manual=True,
79+
**kwargs,
80+
)
81+
82+
83+
def sent_cursor(session: FakeSession, index: int) -> str | None:
84+
return session.calls[index]["params"].get("cursor")
85+
86+
87+
def check(label: str, ok: bool, detail: str = "") -> bool:
88+
print(f"{label:<72} {'PASS' if ok else 'FAIL'}{' ' + detail if detail else ''}")
89+
return ok
90+
91+
92+
async def test_resume(results: list[bool]) -> None:
93+
session = FakeSession(
94+
[
95+
FakeResponse([event(5), event()]),
96+
FakeResponse([event(9)]),
97+
FakeResponse([event()]),
98+
]
99+
)
100+
stream = make_stream(session, topics=["data"])
101+
stream.active = True
102+
103+
await stream.__anext__()
104+
results.append(
105+
check("first connect omits cursor", sent_cursor(session, 0) is None)
106+
)
107+
results.append(check("cursor tracked from an event", stream._cursor == 5))
108+
109+
await stream.__anext__()
110+
results.append(
111+
check("an event without cursor keeps the last value", stream._cursor == 5)
112+
)
113+
114+
await stream.__anext__() # body ends, reconnects
115+
results.append(
116+
check(
117+
"reconnect sends the last cursor",
118+
sent_cursor(session, 1) == "5",
119+
f"got {sent_cursor(session, 1)!r}",
120+
)
121+
)
122+
results.append(
123+
check(
124+
"cursor sent next to cache=true",
125+
session.calls[1]["params"].get("cache") == "true",
126+
)
127+
)
128+
129+
stream.topics = ["data", "alerts"]
130+
await stream.__anext__() # body ends, reconnects with new topics
131+
results.append(
132+
check(
133+
"reconnect after a topic change omits cursor",
134+
sent_cursor(session, 2) is None,
135+
f"got {sent_cursor(session, 2)!r}",
136+
)
137+
)
138+
results.append(
139+
check("topic change discards the old cursor", stream._cursor is None)
140+
)
141+
142+
143+
async def test_vehicle_change(results: list[bool]) -> None:
144+
session = FakeSession(
145+
[FakeResponse([event(5)]), FakeResponse([event()])]
146+
)
147+
stream = make_stream(session, vin=VIN)
148+
stream.active = True
149+
150+
await stream.__anext__()
151+
stream.vin = "LRW3F7EK4NC000002"
152+
await stream.__anext__() # body ends, reconnects for another vehicle
153+
results.append(
154+
check(
155+
"reconnect after a vehicle change omits cursor",
156+
sent_cursor(session, 1) is None,
157+
f"got {sent_cursor(session, 1)!r}",
158+
)
159+
)
160+
161+
162+
async def test_failed_connect_after_topic_change(results: list[bool]) -> None:
163+
session = FakeSession(
164+
[
165+
FakeResponse([event(5), event(7)]),
166+
aiohttp.ClientError("refused"),
167+
FakeResponse([event()]),
168+
]
169+
)
170+
stream = make_stream(session, topics=["data"])
171+
stream.active = True
172+
173+
await stream.__anext__()
174+
stream.topics = ["data", "alerts"]
175+
with contextlib.suppress(aiohttp.ClientError):
176+
await stream.connect() # GET with the new topics fails
177+
await stream.__anext__() # the old response is still supplying cursors
178+
await stream.__anext__() # old body ends, reconnects with the new topics
179+
results.append(
180+
check(
181+
"old response's cursor is not sent for the new topics",
182+
sent_cursor(session, 2) is None,
183+
f"got {sent_cursor(session, 2)!r}",
184+
)
185+
)
186+
187+
188+
async def main() -> int:
189+
results: list[bool] = []
190+
await test_resume(results)
191+
await test_vehicle_change(results)
192+
await test_failed_connect_after_topic_change(results)
193+
passed = sum(results)
194+
print(f"\n{passed}/{len(results)} checks passed")
195+
return 0 if passed == len(results) else 1
196+
197+
198+
if __name__ == "__main__":
199+
raise SystemExit(asyncio.run(main()))

0 commit comments

Comments
 (0)