diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d8d7a3..133e142 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,20 @@ All notable changes to this project are documented here. This project adheres to [Semantic Versioning](https://semver.org/). +## [Unreleased] + +### Added +- **`livetennisapi.reconcile`**, for anyone reading the live feed on their own + socket or through webhooks. No I/O and no new dependency. + `parse_frame()` turns a message into a typed frame (`score`, `point`, + `point_update`, `score_withdrawn`, the break-point pair, everything else as + `ControlFrame`) and raises `FrameError` on bad JSON. `PointSequencer` drops + repeated point frames and holds the ones that arrive after a missing point. + It reports the `after_seq` to fetch from `get_match_points()` and releases + points in `seq` order once a page fills the gap. `ScoreBook` keeps the + newest score per match and applies `score_withdrawn`: `withdrawn` and + `withheld` drop the state, `deferred` keeps it and flags it. + ## [1.8.0] — 2026-09-02 ### Added diff --git a/README.md b/README.md index a733677..e39defe 100644 --- a/README.md +++ b/README.md @@ -237,6 +237,90 @@ Check `frame.pbp_coverage` (`point` | `game`) and `frame.quality` (`clean` | `PushStream` the same frames arrive with `points=True` — see above, including the resume machinery the push side adds. +### Your own socket: order points, fill gaps, apply withdrawals + +`LiveScoreStream` is synchronous and yields scores, signals and points. If you +run your own socket (asyncio, say) or take the same frames as webhooks, +`livetennisapi.reconcile` does the bookkeeping without any I/O: + +- `parse_frame(message)` turns text, bytes or a dict into a typed frame, and + raises `FrameError` on bad JSON or a message with no `type`. +- `PointSequencer` drops repeated `point` frames, holds frames that arrive + after a missing one, and gives you the range to fetch: `gap.after_seq` goes + straight into `get_match_points(match_id, after_seq=...)`, which reads + `GET /matches/{matchId}/points`. Pass the page + to `fill()` and the held points come out in `seq` order, each one once. +- `ScoreBook` keeps the newest score per match by its `sequence`. On a + `score_withdrawn` frame it drops a `withdrawn` or `withheld` state, and + flags a `deferred` one through `verdict()`. + +Point frames are sent once and never replayed, so a dropped frame stays lost +until you fetch it. Each match's `seq` starts at 1 and never skips, so a jump +means points are missing. A runnable example (ULTRA key in +`LIVETENNISAPI_KEY`, `pip install "livetennisapi[ws]"`): + +```python +import asyncio + +import websockets + +from livetennisapi import AsyncLiveTennisAPI, LiveScoreStream, PointUpdate +from livetennisapi.reconcile import ControlFrame, FrameError, PointSequencer, ScoreBook, parse_frame + + +async def main() -> None: + points, scores = PointSequencer(), ScoreBook() + url = LiveScoreStream().url # the /ws address with your key; nothing connects yet + async with AsyncLiveTennisAPI() as client, websockets.connect(url) as ws: + await ws.send('{"topics": ["live-scores"], "signals": ["points"]}') + async for message in ws: + try: + frame = parse_frame(message) + except FrameError as exc: + print("skipped a bad frame:", exc) + continue + + if isinstance(frame, PointUpdate): + ready = points.add(frame) + gap = points.gap(frame.match_id) + while gap is not None: + print(f"match {gap.match_id}: fetching points {gap.after_seq + 1}-{gap.before_seq - 1}") + page = await client.get_match_points(gap.match_id, after_seq=gap.after_seq) + if page is None: + break + try: + ready += points.fill(gap.match_id, page) + except ValueError: # the match finished and is served on another basis + points.forget(gap.match_id) + break + if not page.has_more: + break + gap = points.gap(gap.match_id) + for p in ready: + print(f"match {p.match_id} point {p.point.seq}: won by p{p.point.winner}") + + elif scores.apply(frame): + current = scores.get(frame.match_id) + if current is None: + print(f"match {frame.match_id}: score taken back, waiting for the next one") + else: + print(f"match {frame.match_id}: sets {current.score.sets}") + + elif isinstance(frame, ControlFrame) and frame.type == "error": + print("the feed refused us:", frame.raw) + break + + +asyncio.run(main()) +``` + +After a reconnect, catch up each match you were following before reading +live frames again: `for match_id, last in points.cursors.items()`, fetch +`after_seq=last` and pass each page to `fill()`. A page with `has_more` +true means there is more to fetch. `seq` is the order points were stored, +which is not always the order they were played. Sort by +`(set, game, number)` to replay a match. + ### Model fields ride the WebSocket too Score frames carry the same ULTRA model fields as REST — `update.score.win_probability_p1` diff --git a/src/livetennisapi/reconcile.py b/src/livetennisapi/reconcile.py new file mode 100644 index 0000000..fa1c252 --- /dev/null +++ b/src/livetennisapi/reconcile.py @@ -0,0 +1,464 @@ +"""Parse live-feed frames and keep the per-match ``seq`` order yourself. + + from livetennisapi.reconcile import PointSequencer, ScoreBook, parse_frame + +No socket and no HTTP in here. You call these with frames you already have: +from the native ``/ws`` feed on any WebSocket library (asyncio included), +from a webhook body, or from a ``PushStream`` frame's ``.raw``. Nothing here +needs ``websockets``. + +:func:`parse_frame` turns one message into a typed frame object, or raises +:class:`FrameError` when the message is not a JSON object with a ``type``. + +:class:`PointSequencer` handles ``point`` frames. They are events that the +server sends once, with no replay, so a dropped frame is a lost point until +you fetch it. Each match's ``seq`` starts at 1 and never skips a value, so the +sequencer can tell exactly what is missing. It drops repeats and holds frames +that arrive ahead of a gap. It tells you which range to fetch from +``GET /matches/{matchId}/points?after_seq=``, then releases the held frames +in ``seq`` order once the gap is filled. + +:class:`ScoreBook` keeps the newest score per match and applies +``score_withdrawn`` frames: a withdrawn or withheld state is dropped, a +deferred one is kept and flagged. + +Live Tennis API: https://livetennisapi.com +""" + +from __future__ import annotations + +import json +from collections.abc import Iterable, Mapping +from dataclasses import dataclass +from datetime import datetime +from typing import Any, ClassVar, Union, cast + +from .models import LivePoint, Model, PointsPage +from .ws import BreakPoint, BreakPointResult, PointUpdate, ScoreUpdate + +__all__ = [ + "ControlFrame", + "FeedFrame", + "FrameError", + "Gap", + "PointSequencer", + "PointTagUpdate", + "ScoreBook", + "ScoreWithdrawn", + "parse_frame", +] + + +class FrameError(ValueError): + """The message is not a frame: bad JSON, not an object, or no ``type``. + + ``message`` holds what was received, so you can log it or count it. + """ + + def __init__(self, reason: str, message: Any) -> None: + super().__init__(reason) + self.message = message + + +@dataclass +class ScoreWithdrawn(Model): + """One ``score_withdrawn`` frame: a score state already sent is taken back. + + ``superseded_sequence`` is the score ``sequence`` to act on. ``kind`` is + ``withdrawn`` (discard it), ``deferred`` (it may be early, so keep it + until the next accepted state) or ``withheld`` (nothing can be published + for the match right now). The frame carries no replacement score: the + next ``score`` frame, or ``GET /matches/{matchId}/score``, is where to + resume. + """ + + _datetime_fields: ClassVar[tuple[str, ...]] = ("ts", "published_at") + + type: str | None = None + match_id: int | None = None + kind: str | None = None + superseded_sequence: int | None = None + reason: str | None = None + safe_to_resume: bool | None = None + ts: datetime | None = None + published_at: datetime | None = None + + +@dataclass +class PointTagUpdate(Model): + """One ``point_update`` frame: ``serve`` and ``outcome`` for a point already sent. + + Apply it to the point you hold with the same ``seq``. Nothing else about + that point changes. + """ + + _datetime_fields: ClassVar[tuple[str, ...]] = ("published_at",) + + type: str | None = None + match_id: int | None = None + seq: int | None = None + serve: int | None = None + outcome: str | None = None + published_at: datetime | None = None + + +@dataclass +class ControlFrame(Model): + """Any other frame: ``subscribed``, ``ping``, ``error``, or a type this version does not know. + + Read ``type`` to tell them apart. Every field the server sent is on + ``raw`` and readable as an attribute, for example ``frame.error``. + """ + + type: str | None = None + + +#: What :func:`parse_frame` returns. +FeedFrame = Union[ + ScoreUpdate, + PointUpdate, + PointTagUpdate, + ScoreWithdrawn, + BreakPoint, + BreakPointResult, + ControlFrame, +] + +_PARSERS: dict[str, type[Model]] = { + "score": ScoreUpdate, + "point": PointUpdate, + "point_update": PointTagUpdate, + "score_withdrawn": ScoreWithdrawn, + "break_point": BreakPoint, + "break_point_result": BreakPointResult, +} + + +def parse_frame(message: str | bytes | bytearray | Mapping[str, Any]) -> FeedFrame: + """Turn one feed message into a typed frame. + + Accepts the text or bytes of a WebSocket message, a webhook body, or a + dict you already decoded. Raises :class:`FrameError` when the message is + bad JSON, is not a JSON object, or has no ``type`` string. + + An unknown type comes back as :class:`ControlFrame`, because the feed + adds frame types without a new API version. + """ + data: Any = message + if isinstance(message, (bytes, bytearray)): + try: + data = bytes(message).decode("utf-8") + except UnicodeDecodeError as exc: + raise FrameError("frame is not valid UTF-8", message) from exc + if isinstance(data, str): + try: + data = json.loads(data) + except (ValueError, RecursionError) as exc: + raise FrameError(f"frame is not valid JSON: {exc}", message) from exc + if not isinstance(data, Mapping): + raise FrameError("frame is not a JSON object", message) + kind = data.get("type") + if not isinstance(kind, str) or not kind: + raise FrameError("frame has no type", message) + parser = _PARSERS.get(kind, ControlFrame) + frame = parser.from_dict(data) + if frame is None: # from_dict returns None only for None input + raise FrameError("frame could not be parsed", message) + return cast(FeedFrame, frame) + + +def _as_seq(value: Any) -> int | None: + """A usable ``seq``: an int of at least 1. ``True`` is not a seq.""" + if isinstance(value, bool) or not isinstance(value, int) or value < 1: + return None + return value + + +def _as_match_id(value: Any) -> int | None: + if isinstance(value, bool) or not isinstance(value, int): + return None + return value + + +@dataclass(frozen=True) +class Gap: + """Points missing from one match: everything after ``after_seq`` and before ``before_seq``. + + Fetch them with ``client.get_match_points(match_id, after_seq=gap.after_seq)`` + and hand each page to :meth:`PointSequencer.fill`. ``before_seq`` is the + first point already held past the gap. The fetch can stop there. Reading + on does no harm, because repeats are dropped. + """ + + match_id: int + after_seq: int + before_seq: int + + @property + def missing(self) -> range: + """The ``seq`` values not yet received.""" + return range(self.after_seq + 1, self.before_seq) + + +class PointSequencer: + """Put ``point`` frames in ``seq`` order per match, drop repeats, report gaps. + + Feed it every point frame with :meth:`add` and every REST catch-up page + with :meth:`fill`. Both return the points that are now ready, in ``seq`` + order, each exactly once. + + ``from_start`` decides what happens the first time a match shows up. + False (the default) starts that match at the first point you see. That + suits a live view on the native feed. A lower ``seq`` that turns up later + is dropped as handled. True treats ``seq`` 1 as expected, so joining a + match in the middle reports everything before as a gap to fetch. Use + True, or :meth:`resume`, when frames can arrive out of order from the + start, as webhooks can. + + ``seq`` is the order points were stored, not always the order they were + played. To replay a match in playing order, sort by ``(set, game, number)``. + """ + + def __init__(self, *, from_start: bool = False) -> None: + self.from_start = bool(from_start) + self._cursors: dict[int, int] = {} + self._held: dict[int, dict[int, PointUpdate]] = {} + + # -- state ---------------------------------------------------------------- + + def cursor(self, match_id: int) -> int | None: + """The highest ``seq`` released for a match, or None if it was never seen.""" + return self._cursors.get(match_id) + + @property + def cursors(self) -> dict[int, int]: + """A copy of every match's cursor. On reconnect, fetch ``after_seq=cursor`` for each.""" + return dict(self._cursors) + + def resume(self, match_id: int, last_seq: int) -> list[PointUpdate]: + """Set a match's cursor, for example from a ``seq`` you stored before a restart. + + ``last_seq`` 0 means nothing is held yet, so ``seq`` 1 is the next one + expected. Held points at or below the new cursor are dropped, and any + held points that now follow on from it are returned, in ``seq`` order. + The cursor never moves back, because points already returned would + come out a second time. Call :meth:`forget` first to start over. + """ + if isinstance(last_seq, bool) or not isinstance(last_seq, int) or last_seq < 0: + raise ValueError(f"last_seq must be an int >= 0, got {last_seq!r}") + current = self._cursors.get(match_id) + if current is not None and last_seq < current: + raise ValueError(f"match {match_id}: last_seq {last_seq} is behind the cursor {current}") + self._cursors[match_id] = last_seq + held = self._held.get(match_id) + if held: + for seq in [s for s in held if s <= last_seq]: + del held[seq] + return self._drain(match_id) + + def forget(self, match_id: int) -> None: + """Drop all state for a match, for example once it has finished.""" + self._cursors.pop(match_id, None) + self._held.pop(match_id, None) + + def held(self, match_id: int) -> int: + """How many points of a match are waiting for a gap to be filled.""" + return len(self._held.get(match_id, ())) + + def gap(self, match_id: int) -> Gap | None: + """The match's open gap, or None when nothing is missing.""" + held = self._held.get(match_id) + cursor = self._cursors.get(match_id) + if not held or cursor is None: + return None + return Gap(match_id=match_id, after_seq=cursor, before_seq=min(held)) + + def gaps(self) -> list[Gap]: + """Every open gap, one per match.""" + out = [self.gap(m) for m in self._held] + return [g for g in out if g is not None] + + # -- input ---------------------------------------------------------------- + + def add(self, frame: PointUpdate | Mapping[str, Any]) -> list[PointUpdate]: + """Take one live ``point`` frame. Returns the points now ready, in ``seq`` order. + + An empty list means the frame was a repeat, or it is held behind a gap + (check :meth:`gap`). A frame with no usable ``match_id`` or ``seq`` is + returned as it is, because it cannot be ordered and dropping it would + lose data. + """ + update = frame if isinstance(frame, PointUpdate) else PointUpdate.from_dict(frame) + if update is None: + return [] + match_id = _as_match_id(update.match_id) + seq = _as_seq(update.point.seq if isinstance(update.point, LivePoint) else None) + if match_id is None or seq is None: + return [update] + return self._offer(match_id, seq, update) + + def fill(self, match_id: int, page: PointsPage | Mapping[str, Any] | Iterable[LivePoint]) -> list[PointUpdate]: + """Take one REST page from ``get_match_points``. Returns the points now ready. + + Pass a :class:`~livetennisapi.PointsPage`, the decoded JSON of + ``GET /matches/{matchId}/points``, or a list of + :class:`~livetennisapi.LivePoint` (or point dicts). Points you + already have are dropped. A page for another match raises + ``ValueError``. Raises ``ValueError`` for a page on the ``reconstruction`` + basis: that is a different ``seq`` numbering for a finished match, so + it cannot be merged with live frames. Read it from ``after_seq=0`` + with a fresh sequencer instead. + """ + coverage: str | None = None + quality: str | None = None + if isinstance(page, Mapping): + page = PointsPage.from_dict(page) or PointsPage() + if isinstance(page, PointsPage): + if page.raw.get("basis") == "reconstruction": + raise ValueError( + f"match {match_id}: this page is on the reconstruction basis, whose seq numbering " + "differs from the live stream. Read it from after_seq=0 with a fresh PointSequencer" + ) + page_match = _as_match_id(page.match_id) + if page_match is not None and page_match != match_id: + raise ValueError(f"this page is for match {page_match}, not match {match_id}") + coverage, quality = page.pbp_coverage, page.quality + points: Iterable[LivePoint] = page.points + else: + points = page + + parsed = [LivePoint.from_dict(p) if isinstance(p, Mapping) else p for p in points] + usable = [(seq, p) for p in parsed if isinstance(p, LivePoint) and (seq := _as_seq(p.seq)) is not None] + ready: list[PointUpdate] = [] + for seq, point in sorted(usable, key=lambda pair: pair[0]): + update = PointUpdate(match_id=match_id, point=point, pbp_coverage=coverage, quality=quality) + update.raw = { + "type": "point", + "match_id": match_id, + "point": point.raw, + "pbp_coverage": coverage, + "quality": quality, + } + ready.extend(self._offer(match_id, seq, update)) + return ready + + # -- internals ------------------------------------------------------------ + + def _offer(self, match_id: int, seq: int, update: PointUpdate) -> list[PointUpdate]: + cursor = self._cursors.get(match_id) + if cursor is None: + cursor = 0 if self.from_start else seq - 1 + self._cursors[match_id] = cursor + if seq <= cursor: + return [] # already released + held = self._held.setdefault(match_id, {}) + if seq in held: + return [] # already waiting + held[seq] = update + return self._drain(match_id) + + def _drain(self, match_id: int) -> list[PointUpdate]: + """Release held points that follow on from the cursor.""" + held = self._held.get(match_id) + if held is None: + return [] + cursor = self._cursors[match_id] + ready: list[PointUpdate] = [] + while cursor + 1 in held: + cursor += 1 + ready.append(held.pop(cursor)) + self._cursors[match_id] = cursor + if not held: + del self._held[match_id] + return ready + + +class ScoreBook: + """The newest score per match, with ``score_withdrawn`` applied. + + Pass every ``score`` and ``score_withdrawn`` frame to :meth:`apply`. Other + frames are ignored. Scores are ordered by the score's ``sequence``, so an + older state arriving late never replaces a newer one. + + On ``withdrawn`` or ``withheld`` the matching state is removed, and + :meth:`get` returns None until another score arrives. That can be an + older state re-served by ``GET /matches/{matchId}/score``. Only the + sequence taken back is refused. + + On ``deferred``, or a kind this version does not know, the state stays. + :meth:`verdict` returns the frame so you can show the score as + provisional. A newer score clears the verdict. + """ + + def __init__(self) -> None: + self._scores: dict[int, ScoreUpdate] = {} + self._verdicts: dict[int, ScoreWithdrawn] = {} + #: Per match, the sequences taken back. A score with one of them is never shown again. + self._taken_back: dict[int, set[int]] = {} + + @staticmethod + def sequence(update: ScoreUpdate) -> int | None: + """The score's ``sequence``, read from the nested score object.""" + score = update.score + value = score.raw.get("sequence") if isinstance(score, Model) else None + if isinstance(value, bool) or not isinstance(value, int): + return None + return value + + def get(self, match_id: int) -> ScoreUpdate | None: + """The score to show for a match, or None if there is none you can rely on.""" + return self._scores.get(match_id) + + def verdict(self, match_id: int) -> ScoreWithdrawn | None: + """The last ``score_withdrawn`` that applied to this match's current state.""" + return self._verdicts.get(match_id) + + def forget(self, match_id: int) -> None: + """Drop all state for a match, for example once it has finished.""" + self._scores.pop(match_id, None) + self._verdicts.pop(match_id, None) + self._taken_back.pop(match_id, None) + + def apply(self, frame: FeedFrame) -> bool: + """Apply one frame. Returns True when the score for that match changed.""" + if isinstance(frame, ScoreUpdate): + return self._apply_score(frame) + if isinstance(frame, ScoreWithdrawn): + return self._apply_withdrawal(frame) + return False + + def _apply_score(self, update: ScoreUpdate) -> bool: + match_id = _as_match_id(update.match_id) + if match_id is None: + return False + held = self._scores.get(match_id) + new_seq = self.sequence(update) + old_seq = self.sequence(held) if held is not None else None + if new_seq is not None and old_seq is not None and new_seq <= old_seq: + return False # stale or repeated + if new_seq is not None and new_seq in self._taken_back.get(match_id, ()): + return False # the state that was taken back + self._scores[match_id] = update + self._verdicts.pop(match_id, None) + return True + + def _apply_withdrawal(self, frame: ScoreWithdrawn) -> bool: + match_id = _as_match_id(frame.match_id) + if match_id is None: + return False + superseded = frame.superseded_sequence + if isinstance(superseded, bool) or not isinstance(superseded, int): + return False # names no state, so it cannot apply to one + discard = frame.kind in ("withdrawn", "withheld") + if discard: + # Remember it even when it is not the state we hold, so the + # score frame cannot slip in later if the two arrive swapped. + self._taken_back.setdefault(match_id, set()).add(superseded) + held = self._scores.get(match_id) + if held is None or self.sequence(held) != superseded: + return False # not the state we hold + self._verdicts[match_id] = frame + if not discard: + return False # deferred, or a kind this version does not know: keep it, flagged + del self._scores[match_id] + return True diff --git a/tests/test_reconcile.py b/tests/test_reconcile.py new file mode 100644 index 0000000..9578952 --- /dev/null +++ b/tests/test_reconcile.py @@ -0,0 +1,385 @@ +"""Frame parsing, point ordering and gap repair, and score withdrawals. + +Everything here is pure: no socket, no HTTP. REST catch-up pages are plain +dicts shaped like ``GET /matches/{matchId}/points``. +""" + +from __future__ import annotations + +import json +from datetime import datetime + +import pytest + +from livetennisapi import LivePoint, PointsPage, PointUpdate, ScoreUpdate +from livetennisapi.reconcile import ( + ControlFrame, + FrameError, + Gap, + PointSequencer, + PointTagUpdate, + ScoreBook, + ScoreWithdrawn, + parse_frame, +) + +MATCH = 4711 + + +def point_frame(seq: int, match_id: int = MATCH) -> dict: + return { + "type": "point", + "match_id": match_id, + "point": {"seq": seq, "set": 1, "game": 1, "number": seq, "winner": 1}, + "pbp_coverage": "point", + "quality": "clean", + "published_at": "2026-09-25T10:00:00.000Z", + } + + +def page(*seqs: int, has_more: bool = False, basis: str = "live") -> dict: + return { + "match_id": MATCH, + "pbp_coverage": "point", + "quality": "clean", + "basis": basis, + "points": [{"seq": s, "set": 1, "game": 1, "number": s} for s in seqs], + "last_seq": max(seqs) if seqs else 0, + "has_more": has_more, + } + + +def seqs(updates: list[PointUpdate]) -> list[int]: + return [u.point.seq for u in updates] + + +def score_frame(sequence: int | None, match_id: int = MATCH, sets=(0, 0)) -> dict: + return {"type": "score", "match_id": match_id, "score": {"sets": list(sets), "sequence": sequence}} + + +def withdrawn_frame(sequence: int, kind: str = "withdrawn", match_id: int = MATCH) -> dict: + return { + "type": "score_withdrawn", + "match_id": match_id, + "kind": kind, + "superseded_sequence": sequence, + "reason": "illegal_completed_set", + "safe_to_resume": kind == "withdrawn", + "ts": "2026-09-25T10:00:03.108Z", + "published_at": "2026-09-25T10:00:03.115Z", + } + + +# -- parse_frame --------------------------------------------------------------- + + +class TestParseFrame: + def test_point_frame_from_text(self): + frame = parse_frame(json.dumps(point_frame(7))) + assert isinstance(frame, PointUpdate) + assert isinstance(frame.point, LivePoint) + assert frame.point.seq == 7 + assert frame.match_id == MATCH + + def test_score_frame_from_bytes_keeps_sequence(self): + frame = parse_frame(json.dumps(score_frame(118, sets=(1, 0))).encode()) + assert isinstance(frame, ScoreUpdate) + assert frame.score.sets == [1, 0] + assert ScoreBook.sequence(frame) == 118 + + def test_score_withdrawn_frame(self): + frame = parse_frame(withdrawn_frame(118)) + assert isinstance(frame, ScoreWithdrawn) + assert frame.superseded_sequence == 118 + assert frame.kind == "withdrawn" + assert frame.safe_to_resume is True + assert isinstance(frame.ts, datetime) + assert isinstance(frame.published_at, datetime) + + def test_point_update_frame(self): + frame = parse_frame({"type": "point_update", "match_id": MATCH, "seq": 9, "serve": 2, "outcome": "ace"}) + assert isinstance(frame, PointTagUpdate) + assert (frame.seq, frame.serve, frame.outcome) == (9, 2, "ace") + + def test_control_and_unknown_frames(self): + ack = parse_frame('{"type": "subscribed", "topics": ["live-scores"], "signals": ["points"]}') + assert isinstance(ack, ControlFrame) + assert ack.type == "subscribed" + assert ack.signals == ["points"] + future = parse_frame('{"type": "something_new", "x": 1}') + assert isinstance(future, ControlFrame) + assert future.type == "something_new" + + def test_deeply_nested_input_is_a_frame_error(self): + with pytest.raises(FrameError): + parse_frame("[" * 100_000) + + @pytest.mark.parametrize( + "message", + ["{not json", "", b"\xff\xfe", "[1, 2]", "42", '"score"', "{}", '{"type": 5}', '{"type": ""}', "null"], + ) + def test_malformed_raises_frame_error(self, message): + with pytest.raises(FrameError) as info: + parse_frame(message) + assert info.value.message == message + assert isinstance(info.value, ValueError) + + +# -- PointSequencer ------------------------------------------------------------ + + +class TestPointSequencer: + def test_in_order_frames_pass_straight_through(self): + sq = PointSequencer() + out = [] + for s in (1, 2, 3, 4): + out += sq.add(point_frame(s)) + assert seqs(out) == [1, 2, 3, 4] + assert sq.cursor(MATCH) == 4 + assert sq.gap(MATCH) is None + assert sq.gaps() == [] + + def test_first_frame_mid_match_starts_the_cursor_there(self): + sq = PointSequencer() + assert seqs(sq.add(point_frame(40))) == [40] + assert seqs(sq.add(point_frame(41))) == [41] + + def test_from_start_reports_the_points_before_the_first_frame(self): + sq = PointSequencer(from_start=True) + assert sq.add(point_frame(4)) == [] + assert sq.gap(MATCH) == Gap(match_id=MATCH, after_seq=0, before_seq=4) + assert seqs(sq.fill(MATCH, page(1, 2, 3, 4))) == [1, 2, 3, 4] + + def test_out_of_order_frames_are_released_in_seq_order(self): + sq = PointSequencer() + assert seqs(sq.add(point_frame(1))) == [1] + assert sq.add(point_frame(3)) == [] + assert sq.add(point_frame(4)) == [] + assert sq.held(MATCH) == 2 + assert seqs(sq.add(point_frame(2))) == [2, 3, 4] + assert sq.held(MATCH) == 0 + assert sq.gap(MATCH) is None + + def test_duplicates_are_dropped(self): + sq = PointSequencer() + assert seqs(sq.add(point_frame(1))) == [1] + assert sq.add(point_frame(1)) == [] + assert sq.add(point_frame(3)) == [] + assert sq.add(point_frame(3)) == [] # a repeat of a held frame + assert seqs(sq.add(point_frame(2))) == [2, 3] + assert sq.add(point_frame(2)) == [] + + def test_gap_reports_the_range_and_rest_page_fills_it(self): + sq = PointSequencer() + for s in (1, 2, 3): + sq.add(point_frame(s)) + assert sq.add(point_frame(7)) == [] + assert sq.add(point_frame(8)) == [] + + gap = sq.gap(MATCH) + assert gap == Gap(match_id=MATCH, after_seq=3, before_seq=7) + assert list(gap.missing) == [4, 5, 6] + assert sq.gaps() == [gap] + + # The catch-up read overlaps what we hold on both ends: 3 is already + # released and 7, 8 are held. Each point still comes out exactly once. + released = sq.fill(MATCH, page(3, 4, 5, 6, 7, 8)) + assert seqs(released) == [4, 5, 6, 7, 8] + assert sq.gap(MATCH) is None + assert sq.cursor(MATCH) == 8 + # A filled point carries the page's coverage, like a live frame. + assert released[0].pbp_coverage == "point" + assert released[0].raw["point"]["seq"] == 4 + + # The live frames for the filled points turn up late: all repeats. + for s in (4, 5, 6, 7, 8): + assert sq.add(point_frame(s)) == [] + assert seqs(sq.add(point_frame(9))) == [9] + + def test_partial_fill_narrows_the_gap(self): + sq = PointSequencer() + sq.add(point_frame(1)) + sq.add(point_frame(6)) + assert seqs(sq.fill(MATCH, page(2, 3, has_more=True))) == [2, 3] + assert sq.gap(MATCH) == Gap(match_id=MATCH, after_seq=3, before_seq=6) + assert seqs(sq.fill(MATCH, page(4, 5))) == [4, 5, 6] + + def test_fill_accepts_a_points_page_or_a_list(self): + sq = PointSequencer() + sq.add(point_frame(1)) + sq.add(point_frame(4)) + parsed = PointsPage.from_dict(page(2)) + assert seqs(sq.fill(MATCH, parsed)) == [2] + assert seqs(sq.fill(MATCH, [LivePoint.from_dict({"seq": 3})])) == [3, 4] + + def test_fill_sorts_an_unsorted_page(self): + sq = PointSequencer() + sq.add(point_frame(1)) + assert seqs(sq.fill(MATCH, page(4, 2, 3))) == [2, 3, 4] + + def test_fill_accepts_point_dicts(self): + sq = PointSequencer() + sq.add(point_frame(1)) + assert seqs(sq.fill(MATCH, [{"seq": 2}, {"seq": 3}])) == [2, 3] + + def test_fill_refuses_a_page_for_another_match(self): + sq = PointSequencer() + sq.add(point_frame(1)) + other = page(2) + other["match_id"] = MATCH + 1 + with pytest.raises(ValueError, match="not match"): + sq.fill(MATCH, other) + assert sq.cursor(MATCH) == 1 + + def test_from_start_keeps_out_of_order_first_frames(self): + sq = PointSequencer(from_start=True) + sq.resume(MATCH, 4) + assert sq.add(point_frame(6)) == [] + assert seqs(sq.add(point_frame(5))) == [5, 6] + + def test_fill_refuses_the_reconstruction_basis(self): + sq = PointSequencer() + sq.add(point_frame(1)) + with pytest.raises(ValueError, match="reconstruction"): + sq.fill(MATCH, page(1, 2, basis="reconstruction")) + + def test_matches_are_tracked_separately(self): + sq = PointSequencer() + sq.add(point_frame(1, match_id=1)) + sq.add(point_frame(10, match_id=2)) + assert sq.add(point_frame(3, match_id=1)) == [] + assert seqs(sq.add(point_frame(11, match_id=2))) == [11] + assert sq.gaps() == [Gap(match_id=1, after_seq=1, before_seq=3)] + assert sq.cursors == {1: 1, 2: 11} + + def test_resume_sets_the_cursor_and_releases_what_follows(self): + sq = PointSequencer() + sq.resume(MATCH, 10) + assert sq.add(point_frame(9)) == [] + assert sq.add(point_frame(12)) == [] + assert sq.gap(MATCH) == Gap(match_id=MATCH, after_seq=10, before_seq=12) + # Learning elsewhere that 11 was already handled closes the gap. + assert seqs(sq.resume(MATCH, 11)) == [12] + with pytest.raises(ValueError): + sq.resume(MATCH, -1) + + def test_resume_never_moves_the_cursor_back(self): + sq = PointSequencer() + for s in (1, 2, 3): + sq.add(point_frame(s)) + with pytest.raises(ValueError, match="behind"): + sq.resume(MATCH, 1) + assert sq.fill(MATCH, page(2, 3)) == [] + sq.forget(MATCH) + assert sq.resume(MATCH, 1) == [] + + def test_forget_clears_a_match(self): + sq = PointSequencer() + sq.add(point_frame(1)) + sq.add(point_frame(5)) + sq.forget(MATCH) + assert sq.cursor(MATCH) is None + assert sq.gaps() == [] + + def test_unorderable_frames_are_returned_not_dropped(self): + sq = PointSequencer() + no_seq = {"type": "point", "match_id": MATCH, "point": {"set": 1}} + bool_seq = {"type": "point", "match_id": MATCH, "point": {"seq": True}} + no_match = {"type": "point", "point": {"seq": 3}} + for frame in (no_seq, bool_seq, no_match): + out = sq.add(frame) + assert len(out) == 1 + assert sq.cursors == {} + + +# -- ScoreBook ----------------------------------------------------------------- + + +class TestScoreBook: + def test_newer_scores_replace_older_and_stale_ones_are_ignored(self): + book = ScoreBook() + assert book.apply(parse_frame(score_frame(5))) is True + assert book.apply(parse_frame(score_frame(7, sets=(1, 0)))) is True + assert book.apply(parse_frame(score_frame(6))) is False + assert book.apply(parse_frame(score_frame(7, sets=(1, 0)))) is False + assert ScoreBook.sequence(book.get(MATCH)) == 7 + + def test_withdrawn_discards_the_held_state(self): + book = ScoreBook() + book.apply(parse_frame(score_frame(118))) + assert book.apply(parse_frame(withdrawn_frame(118))) is True + assert book.get(MATCH) is None + assert book.verdict(MATCH).superseded_sequence == 118 + # The taken-back state is never shown again, even if re-sent. + assert book.apply(parse_frame(score_frame(118))) is False + # The next accepted state is the one to resume from, and clears the verdict. + assert book.apply(parse_frame(score_frame(119))) is True + assert book.verdict(MATCH) is None + + def test_an_older_state_reserved_after_a_withdrawal_is_shown(self): + # GET /matches/{id}/score re-serves the last good state, whose sequence is lower. + book = ScoreBook() + book.apply(parse_frame(score_frame(4))) + book.apply(parse_frame(score_frame(5))) + book.apply(parse_frame(withdrawn_frame(5))) + assert book.apply(parse_frame(score_frame(4))) is True + assert ScoreBook.sequence(book.get(MATCH)) == 4 + + def test_withdrawal_that_arrives_before_its_score_still_refuses_it(self): + book = ScoreBook() + book.apply(parse_frame(score_frame(5))) + assert book.apply(parse_frame(withdrawn_frame(6))) is False + assert book.apply(parse_frame(score_frame(6))) is False + assert ScoreBook.sequence(book.get(MATCH)) == 5 + assert book.apply(parse_frame(score_frame(7))) is True + + def test_withheld_discards_the_held_state(self): + book = ScoreBook() + book.apply(parse_frame(score_frame(40))) + assert book.apply(parse_frame(withdrawn_frame(40, kind="withheld"))) is True + assert book.get(MATCH) is None + + def test_deferred_keeps_the_state_and_flags_it(self): + book = ScoreBook() + book.apply(parse_frame(score_frame(40))) + assert book.apply(parse_frame(withdrawn_frame(40, kind="deferred"))) is False + assert ScoreBook.sequence(book.get(MATCH)) == 40 + assert book.verdict(MATCH).kind == "deferred" + book.apply(parse_frame(score_frame(41))) + assert book.verdict(MATCH) is None + + def test_withdrawal_of_a_state_not_held_changes_nothing(self): + book = ScoreBook() + book.apply(parse_frame(score_frame(50))) + assert book.apply(parse_frame(withdrawn_frame(49))) is False + assert book.apply(parse_frame(withdrawn_frame(50, match_id=999))) is False + assert ScoreBook.sequence(book.get(MATCH)) == 50 + assert book.verdict(MATCH) is None + + def test_withdrawal_without_a_sequence_changes_nothing(self): + book = ScoreBook() + book.apply(parse_frame(score_frame(None))) + frame = withdrawn_frame(1) + del frame["superseded_sequence"] + assert book.apply(parse_frame(frame)) is False + assert book.get(MATCH) is not None + + def test_unknown_kind_keeps_the_state_and_flags_it(self): + book = ScoreBook() + book.apply(parse_frame(score_frame(8))) + assert book.apply(parse_frame(withdrawn_frame(8, kind="something_new"))) is False + assert ScoreBook.sequence(book.get(MATCH)) == 8 + assert book.verdict(MATCH).kind == "something_new" + + def test_other_frames_are_ignored(self): + book = ScoreBook() + assert book.apply(parse_frame(point_frame(1))) is False + assert book.apply(parse_frame('{"type": "ping"}')) is False + + def test_forget_clears_a_match(self): + book = ScoreBook() + book.apply(parse_frame(score_frame(3))) + book.apply(parse_frame(withdrawn_frame(3))) + book.forget(MATCH) + assert book.verdict(MATCH) is None + assert book.apply(parse_frame(score_frame(1))) is True